---
name: cucu-api-design
description: Chuẩn thiết kế & review API cho CuCu Note (REST/FastAPI/Mongo), dựa trên cursor-skills/api + python.
---

# CuCu API Design Skill

Skill này định nghĩa **cách thiết kế và review API** cho CuCu Note.
Agent dùng skill này khi:

## When to Use

- Người dùng:
  - muốn thêm/sửa route trong `backend/api/memos` hoặc `backend/api/chatbot`,
  - hỏi về status code, error shape, input validation,
  - nghi ngờ performance hoặc security của API.

## Nguyên tắc chung (REST/FastAPI)

1. **REST chuẩn & status code**
   - Dùng HTTP methods đúng:
     - GET: đọc memos, history.
     - POST: tạo memos, comments, chat request.
     - PATCH: update memo.
     - DELETE: xoá memo/comment (nếu có).
   - Status code:
     - 200/201 cho success,
     - 400 cho bad request (input sai),
     - 401/403 cho auth/permission (sau này nếu bật),
     - 404 khi resource không tồn tại,
     - 500 khi lỗi server bất ngờ.

2. **Shape của response**
   - Với list:
     - Trả dạng `{ "memos": [...], "nextPageToken": "...", "totalSize": N }`  
       (như các route memos hiện tại).
   - Với item:
     - Trả object schema tương ứng (`MemoResponse`, v.v.).
   - Với error:
     - Trả `{ "detail": "<message>" }` hoặc format thống nhất.

3. **Input validation & security**
   - Validate:
     - ID (ObjectId/uid) → nếu không valid, trả 400.
     - filter string (date/tag) → parse cẩn thận, không bùng.
   - Không tin vào client:
     - Kiểm tra `visibility`, `creator_id` trước khi trả memo/private content.
   - Ghi log lỗi nhưng **không log secret** (token, mật khẩu, v.v.).

4. **Performance**
   - Mọi query Mongo nên:
     - Có filter rõ ràng (`creator_id`, `visibility`, `created_at`, v.v.).
     - Có `limit` & `sort`, tránh scan toàn bộ collection.
   - Đối với chatbot:
     - `memo_retrieval_tool` chỉ gọi khi cần, không lạm dụng cho lời chào.

## Instructions (Agent phải làm gì)

1. **Khi thiết kế route mới:**
   - Xác định:
     - Nó thuộc `memos` (ghi chú, comment, shortcut) hay `chatbot` (chat/history).
   - Đề xuất:
     - Tên path: ví dụ `/memos/{memo_id}/comments`, `/api/history/{identity_key}`.
     - Method phù hợp.
     - Request body & response schema (dựa vào `common/memos_core/schemas.py`).
   - Kiểm tra:
     - Access control (creator vs guest).
     - Error case (memo không tồn tại, input xấu).

2. **Khi review API hiện có:**
   - So code thật với checklist trên:
     - Status code có hợp lý không?
     - Có chỗ nào dùng `Exception` chung chung -> 500 mà đáng ra phải 400/404?
     - Query Mongo có filter + limit/sort chưa?
   - Đề xuất cải thiện cụ thể, chỉ ra từng function/route.

3. **Khi người dùng hỏi “có bug API không?”:**
   - Dùng skill này để:
     - Đọc nhanh logic route.
     - So với chuẩn REST + security.
     - Nêu rõ:
       - Đây là bug thật, hay chỉ là chỗ chưa chuẩn (ví dụ message error chưa rõ).


