Backend Python & API Rules cho CuCu Note
========================================

Mục tiêu: dạy Agent cách làm việc với backend Python/FastAPI của CuCu theo **một chuẩn cố định**, tránh bày thêm cấu trúc lạ.

## 1. Luôn dùng ruff + black cho backend Python

- Khi cần format / lint backend, **chỉ đề xuất** (hoặc chạy nếu có shell/MCP):
  - `cd backend && ruff check . --fix`
  - `cd backend && black .`
- Không tự nghĩ thêm formatter khác cho backend (flake8, yapf, v.v.) trừ khi user yêu cầu rõ.
- Khi sửa nhiều file backend, trước khi kết thúc work, hãy nhắc user chạy (hoặc tự chạy) combo `ruff + black`.

## 2. Cấu trúc API – mỗi domain một folder

- Mặc định, backend FastAPI của CuCu tuân thủ:
  - `backend/api/memos/` – toàn bộ API liên quan đến memos, comments, shortcuts, attachments, v.v.
  - `backend/api/chatbot/` – toàn bộ API liên quan đến chatbot & history (`/api/agent/chat`, `/api/history/...`).
- Khi cần thêm API mới:
  - Nếu là **note/memo** → thêm vào module con trong `backend/api/memos/`.
  - Nếu là **chatbot/history** → thêm vào module con trong `backend/api/chatbot/`.
  - Không tạo file route rời ngoài hai folder này, trừ khi user nói rõ tạo domain mới.

## 3. Backend agents/service dùng pattern singleton

- Với các class “agent” hoặc service dài hạn (giữ state, cache, graph…) trong backend, **ưu tiên pattern singleton** giống `CANIFAGraph`:

  - Cấu trúc chuẩn trong một file:
    - Khai báo class chính, ví dụ: `FormatterAgent`, `CANIFAGraph`, hoặc service tương tự.
    - Ở cuối file, khai báo biến module-level:
      ```python
      _instance: list[MyClass | None] = [None]
      ```
    - Hàm getter:
      ```python
      def get_my_class(...) -> MyClass:
          if _instance[0] is None:
              _instance[0] = MyClass(...)
          return _instance[0]
      ```
    - Hàm reset (chủ yếu cho test):
      ```python
      def reset_my_class() -> None:
          _instance[0] = None
      ```
- Khi cần tạo một “agent mới” (ví dụ formatter, conversation manager, graph mới), Agent nên:
  - Đặt class + singleton helper trong **cùng một file**.
  - Tránh tạo nhiều instance rời rạc ở nhiều chỗ.

## 4. Khi refactor backend

- Luôn giữ:
  - File API route trong `backend/api/...` chỉ làm việc với FastAPI (request/response, status code).
  - Logic domain (memos, chatbot, format, history…) nằm trong `backend/common` hoặc `backend/agent` dưới dạng class/service, có thể là singleton nếu hợp lý.
- Khi Agent đề xuất thay đổi cấu trúc:
  - Trước tiên kiểm tra rule này.
  - Nếu thay đổi **phá vỡ** pattern trên, cần hỏi lại user hoặc giải thích lý do rõ ràng.


