🔨 Update mdc cursor rules and claude.md for backend

Author: Phinease

.cursor/rules/backend/app_layer_rules.mdc

@@ -0,0 +1,114 @@
+---
+globs: backend/apps/**/*.py
+description: App layer (API) contract for FastAPI endpoints in backend/apps. Parse/validate input, call services, map domain errors to HTTP, return JSONResponse on success.
+---
+
+### Purpose and Scope
+
+- The App layer is the HTTP boundary for the backend. It applies to files under `backend/apps/*.py`.
+- Responsibilities:
+  - Parse and validate HTTP inputs.
+  - Call underlying services; do not implement core business logic here.
+  - Translate domain/service exceptions into `HTTPException` with proper status codes.
+  - Return `JSONResponse(status_code=HTTPStatus.OK, content=payload)` on success.
+- Configuration: Do not access environment variables directly. Read configuration via `consts.const` or pass values through from the request to services.
+
+References: [backend/consts/exceptions.py](mdc:backend/consts/exceptions.py)
+
+### Routing and URL Design
+
+- Keep existing top-level prefixes for compatibility (e.g., `"/agent"`, `"/memory"`). When adding new modules or endpoints, follow these rules:
+  - Use plural nouns for collection-style resources (e.g., `"/agents"`, `"/memories"`).
+  - Use snake_case for all path segments. Avoid hyphens and camelCase.
+  - Prefer resource-oriented paths for CRUD-style operations. Example: `"/agents"` (collection), `"/agents/{agent_id}"` (single resource).
+  - Use action-style paths only when necessary to match current patterns or when the operation is not naturally CRUD (e.g., `"/agent/run"`, `"/agent/stop/{conversation_id}"`).
+  - Path parameters must be singular, semantic nouns: `"/agents/{agent_id}"`, `"/memories/{memory_id}"`.
+  - Keep backwards compatibility: do not rename existing routes; new routes should follow these conventions.
+
+### HTTP Methods
+
+- GET: Read and list operations only. Maintain existing special cases where GET performs safe actions (e.g., `GET /agent/stop/{conversation_id}`), but do not introduce new side-effecting GETs.
+- POST: Create resources, perform searches, or trigger actions with side effects (e.g., `POST /memory/add`, `POST /memory/search`, `POST /agent/run`).
+- DELETE: Delete resources or clear collections (e.g., `DELETE /memory/clear`). Ensure idempotency.
+- PUT/PATCH: Update resources. Prefer `PUT` for full updates and `PATCH` for partial updates. Preserve legacy `POST /update` endpoints for compatibility but favor PUT/PATCH for new code.
+
+### Authorization and Identity
+
+- Retrieve the bearer token via header injection: `authorization: Optional[str] = Header(None)`.
+- Use utility helpers to parse identity (prefer functions in `utils.auth_utils`, such as `get_current_user_id` or `get_current_user_info`) and pass `user_id` and/or `tenant_id` down to services. The App layer should not implement token parsing logic itself.
+
+### Request Validation
+
+- Prefer Pydantic models in `consts.model` as request bodies for complex payloads (e.g., `AgentRequest`).
+- For simple atomic fields, use `Body(..., embed=True)` to pin the JSON key name.
+- Use `Query(...)` for filters and pagination, `Path(...)` for path parameters, and `Header(...)` for headers.
+- Pagination recommendations for listing endpoints: `page: int = Query(1, ge=1)`, `page_size: int = Query(20, ge=1, le=100)`, plus optional `order_by`, `filters` as appropriate. Return pagination metadata (`items`, `total`) or match existing return shapes in the codebase.
+
+### Responses
+
+- On success, return `JSONResponse(status_code=HTTPStatus.OK, content=payload)`.
+- If a standard response model exists in the project (e.g., conversation responses), continue to use it for consistency.
+- For new endpoints, return a structured content dictionary with necessary fields (e.g., `{"data": ..., "message": "OK"}`) while staying consistent with existing patterns.
+
+### Exception Mapping
+
+- Catch domain/service exceptions from `backend/consts/exceptions.py` and map to `HTTPException` with appropriate status codes. Examples:
+  - `UnauthorizedError` → 401 UNAUTHORIZED
+  - `LimitExceededError` → 429 TOO_MANY_REQUESTS
+  - Parameter/validation errors (e.g., invalid enum, unknown config key) → 400 BAD_REQUEST or 406 NOT_ACCEPTABLE (follow existing precedent such as `set_single_config` using 406)
+  - Unexpected errors → 500 INTERNAL_SERVER_ERROR (log the error; do not leak internal details)
+
+### Logging and Observability
+
+- Use a module-level logger: `logger = logging.getLogger("<module_name>")`.
+- Log key events and errors. For listing/search endpoints, optionally log query scope and timing while avoiding sensitive data.
+
+### Async/Sync Conventions
+
+- Match the existing style in each module. Keep `async def` where already used.
+- When calling async services, prefer direct `await`. When calling sync services, invoke them directly without creating new event loops.
+
+### Backward Compatibility
+
+- Do not break existing routes, payload shapes, or response structures.
+- New endpoints should follow these conventions strictly to converge the API style across modules.
+
+### Correct Example (parse input, call service, map exceptions, return JSONResponse)
+```python
+from http import HTTPStatus
+import logging
+from fastapi import APIRouter, HTTPException
+from starlette.responses import JSONResponse
+
+from consts.exceptions import LimitExceededError, AgentRunException, MemoryPreparationException
+from services.agent_service import run_agent
+
+logger = logging.getLogger(__name__)
+router = APIRouter()
+
+@router.post("/agent/run")
+def run_agent_endpoint(payload: dict):
+    try:
+        result = run_agent(payload)
+        return JSONResponse(status_code=HTTPStatus.OK, content=result)
+    except LimitExceededError as exc:
+        raise HTTPException(status_code=HTTPStatus.TOO_MANY_REQUESTS, detail=str(exc))
+    except MemoryPreparationException as exc:
+        raise HTTPException(status_code=HTTPStatus.BAD_REQUEST, detail=str(exc))
+    except AgentRunException as exc:
+        raise HTTPException(status_code=HTTPStatus.INTERNAL_SERVER_ERROR, detail=str(exc))
+```
+
+### Incorrect Example (business logic in App layer or non-HTTP error handling)
+```python
+from starlette.responses import JSONResponse
+
+def run_agent_endpoint(payload: dict):
+    # WRONG: performing core business logic inside the app layer
+    if payload.get("force"):
+        return {"status": "forced"}  # WRONG: returns plain dict without HTTP status context
+
+    # WRONG: not translating domain errors to HTTP
+    result = risky_logic(payload)
+    return JSONResponse(result)
+```

.cursor/rules/backend/database_layer_rules.mdc

@@ -0,0 +1,83 @@
+---
+globs: backend/database/**/*.py
+description: Database layer standards for models, CRUD, transactions, and exceptions
+---
+
+# Database Layer Standards
+
+Scope: all Python under `backend/database/**/*.py`. Concise standards for models, CRUD, transactions, and exceptions.
+
+- Models: define in [backend/database/db_models.py](mdc:backend/database/db_models.py).
+- Sessions: use `get_db_session()` from [backend/database/client.py](mdc:backend/database/client.py).
+- Exceptions: share a DB exception type in [backend/consts/exceptions.py](mdc:backend/consts/exceptions.py).
+- SQLAlchemy Core: prefer `insert`/`update`/`select` with `session.execute()`/`session.scalars()`; ORM `session.add()` is allowed but not default.
+
+## 1) Models and audit fields
+- Inherit all models from `TableBase`.
+- Shared fields: `create_time`, `update_time`, `created_by`, `updated_by`, `delete_flag` (`Y`/`N`).
+- Never re-declare shared fields; add only table-specific columns.
+
+## 2) CRUD and audit
+- Create: set `created_by`, `updated_by`, default `delete_flag='N'`; timestamps are server-managed.
+- Update: set `updated_by`; do not change `create_time`/`created_by`.
+- Delete: soft-delete only (`delete_flag='Y'`, set `updated_by`). Cascade by soft-deleting children in same transaction when needed.
+- Read: exclude soft-deleted rows by default (`delete_flag='N'`).
+
+## 3) Transactions and sessions
+- Always use `with get_db_session() as session:`.
+- Never call `commit()`, `rollback()`, or `close()` in DB-layer code.
+- The context manager centrally handles commit/rollback/close.
+
+## 4) Exceptions
+- Do not catch DB exceptions in `backend/database/**`; let them propagate.
+- Central handling occurs in `get_db_session()`.
+- Services that must proceed non-blockingly may catch a shared type (e.g., `DatabaseOperationError`).
+
+## 5) Exception flow (inside get_db_session)
+- On exception: `rollback` → re-raise → `close` → propagate to callers.
+
+## 6) Reference patterns (Core; no explicit commit/rollback)
+```python
+from sqlalchemy import insert, update, select
+from database.client import get_db_session, as_dict
+
+def create_entity(data: dict):
+    with get_db_session() as session:
+        return session.execute(
+            insert(SomeModel).values(**data).returning(SomeModel.id)
+        ).scalar_one()
+
+def update_entity(entity_id: int, updates: dict, actor: str):
+    with get_db_session() as session:
+        session.execute(
+            update(SomeModel)
+            .where(SomeModel.id == entity_id, SomeModel.delete_flag == 'N')
+            .values(**updates, updated_by=actor)
+        )
+
+def soft_delete_entity(entity_id: int, actor: str):
+    with get_db_session() as session:
+        session.execute(
+            update(SomeModel)
+            .where(SomeModel.id == entity_id, SomeModel.delete_flag == 'N')
+            .values(delete_flag='Y', updated_by=actor)
+        )
+
+def read_active_entity(entity_id: int):
+    with get_db_session() as session:
+        record = session.scalars(
+            select(SomeModel).where(
+                SomeModel.id == entity_id,
+                SomeModel.delete_flag == 'N',
+            )
+        ).first()
+        return None if record is None else as_dict(record)
+```
+
+## 7) Validation checklist
+- All models inherit `TableBase`; no duplicated audit fields.
+- Deletes are soft deletes (`delete_flag='Y'`) and set `updated_by`.
+- No direct `commit`/`rollback`/`close` outside `get_db_session()`.
+- No DB exception catching in `backend/database/` modules.
+- Reads default to `delete_flag='N'`.
+- Services that must proceed on failure catch a shared DB exception type in `consts.exceptions`.

.cursor/rules/backend/service_layer_rules.mdc

@@ -0,0 +1,113 @@
+---
+globs: backend/services/**/*.py
+description: Service layer implements core business logic orchestration; raise custom exceptions; no HTTP handling
+---
+
+### Service Layer Rules
+
+- **Scope**: Applies to `backend/services/*.py`.
+- **Goal**: Implement core business logic and orchestrate complex workflows. Coordinate repositories/SDKs. Keep HTTP concerns out of this layer.
+- **Exceptions**: Raise domain/service exceptions declared in `backend/consts/exceptions.py`. If a new case is needed, add a new class there, then raise it here. Do not translate to HTTP here.
+- **Environment variables**: Do not access `os.getenv()` directly. Read configuration from `consts.const` (see `environment_variable` rule) or accept parameters.
+
+Reference: [backend/consts/exceptions.py](mdc:backend/consts/exceptions.py)
+
+### Correct example (service orchestrates business logic and raises domain exceptions)
+```python
+# backend/services/agent_service.py
+from typing import Any, Dict
+
+from consts.exceptions import LimitExceededError, AgentRunException, MemoryPreparationException
+# from consts.const import APPID, TOKEN  # Example: read config via consts, not os.getenv
+
+
+def run_agent(task_payload: Dict[str, Any]) -> Dict[str, Any]:
+    """Run agent core workflow and return domain result dict.
+    Raises domain exceptions on failure; no HTTP concerns here.
+    """
+    if _is_rate_limited(task_payload):
+        raise LimitExceededError("Too many requests for this tenant.")
+
+    try:
+        memory = _prepare_memory(task_payload)
+    except Exception as exc:
+        # Wrap low-level error in a domain exception for the app layer to translate
+        raise MemoryPreparationException("Failed to prepare memory.") from exc
+
+    try:
+        result = _execute_core_logic(task_payload, memory)
+    except Exception as exc:
+        raise AgentRunException("Agent execution failed.") from exc
+
+    # Return a plain Python object, not a Response
+    return {"status": "ok", "data": result}
+
+
+def _is_rate_limited(_: Dict[str, Any]) -> bool:
+    return False
+
+
+def _prepare_memory(_: Dict[str, Any]) -> Dict[str, Any]:
+    return {"memo": "prepared"}
+
+
+def _execute_core_logic(_: Dict[str, Any], __: Dict[str, Any]) -> Dict[str, Any]:
+    return {"answer": "42"}
+```
+
+### Incorrect example (service leaks HTTP/web concerns or reads env directly)
+```python
+# backend/services/agent_service.py
+from fastapi import HTTPException  # WRONG: HTTP in service
+from starlette.responses import JSONResponse  # WRONG: Response in service
+import os  # WRONG: direct env access in service
+
+
+def run_agent(_: dict):
+    # WRONG: translating to HTTP inside service
+    if os.getenv("RATE_LIMIT", "0") == "1":  # WRONG: direct getenv here
+        raise HTTPException(status_code=429, detail="Too many requests")
+
+    # WRONG: returning framework response from service
+    return JSONResponse({"status": "ok"})
+```
+
+### Declaring a new custom exception (do this in exceptions module)
+```python
+# backend/consts/exceptions.py
+class OrderProcessingError(Exception):
+    """Raised when order processing fails in service layer."""
+    pass
+```
+
+### Existing exceptions (excerpt from current code)
+```python
+"""
+Custom exception classes for the application.
+"""
+
+
+class AgentRunException(Exception):
+    """Exception raised when agent run fails."""
+    pass
+
+
+class LimitExceededError(Exception):
+    """Raised when an outer platform calling too frequently"""
+    pass
+
+
+class UnauthorizedError(Exception):
+    """Raised when a user from outer platform is unauthorized."""
+    pass
+
+
+class SignatureValidationError(Exception):
+    """Raised when X-Signature header is missing or does not match the expected HMAC value."""
+    pass
+
+
+class MemoryPreparationException(Exception):
+    """Raised when memory preprocessing or retrieval fails prior to agent run."""
+    pass
+```