api-designer

api-designer — Thiết kế API từ spec + DB

Sinh & quản lý tài liệu Thiết kế API 2 tầng từ spec (spec-writer) và thiết kế DB (db-designer). Mục tiêu: tài liệu API đủ căn cứ để sinh test spec và code — endpoint có request/response JSON, validation khớp ràng buộc DB, error code, route mapping — đồng thời giữ truy vết API-ID ↔ F-NNN ↔ màn (F-NNN) ↔ bảng DB.

Ngôn ngữ: tiếng Việt là chính; method/URL/JSON key/tên kiểu để tiếng Anh (theo mẫu).

---

Kỷ luật xuất (BẮT BUỘC — tránh dump dài, lag)

• Ghi file trực tiếp bằng Write/Edit. KHÔNG in/dán toàn bộ nội dung tài liệu (endpoint, JSON) ra chat.
• Tạo xong báo ngắn: đường dẫn + tóm tắt (số endpoint, nhóm resource). Người dùng muốn xem thì mở file.
• Không hỏi "có tạo file không" kèm preview toàn bộ nội dung.

---

Vị trí trong pipeline

api-designer là Stage 4 (API) — chạy SAU DB (db-designer), TRƯỚC plan/code.

Stage	Việc	Skill
2. Spec	Spec tổng + spec con màn hình	spec-writer
3. DB	Thiết kế CSDL	db-designer
4. API	Thiết kế API từ spec + DB	api-designer ← đang ở đây
5. Plan / 6. Code	Lập kế hoạch & code	superpowers:writing-plans / executing-plans

Hết Stage 4 LUÔN hỏi người dùng: "Dừng ở API, hay tiếp tục sang plan (Stage 5)?"

---

Điều kiện tiên quyết (đọc TRƯỚC khi làm)

1. Phải có docs/spec/00_index.md + 01_requirements.md + screens/. Thiếu → đề nghị chạy spec-writer.
2. Nên có docs/spec/database/03_database-design.md. Thiếu → cảnh báo người dùng: API thiết kế khi chưa có DB sẽ phải đoán cột → đề nghị chạy db-designer trước, hoặc chấp nhận đánh dấu Cần xác nhận cho phần dữ liệu.
3. Đọc 02_tech_context.md (backend framework, auth, base URL, JSON key style). Thiếu → bổ sung theo db-designer/references/tech-context-template.md.
4. Đọc 00_index.md (F-NNN, màn, bảng DB), các screens/F-NNN_*.md (yêu cầu dữ liệu của màn) để rút ra endpoint cần có.

---

Cấu trúc 2 tầng (BẮT BUỘC)

API design gồm tài liệu chung (1 file, toàn dự án) + tài liệu riêng (1 file/nhóm resource).

• Tài liệu chung sở hữu: nguyên tắc RESTful, base URL/versioning, xác thực/phân quyền, header chung, định dạng response chung, error code & HTTP status, pagination, sort/filter, kiểu dữ liệu chung, danh sách toàn bộ endpoint.
• Tài liệu riêng sở hữu: chi tiết từng endpoint (request/response JSON, validation, error theo endpoint, thao tác DB, route mapping).
• CẤM định nghĩa lại ở tài liệu riêng những gì đã có ở tài liệu chung (response format, error code, auth) — chỉ tham chiếu.
• Phải tạo tài liệu chung TRƯỚC tài liệu riêng.

---

Bốn nhánh — tự nhận diện ý định

Nhánh 1 — Tạo tài liệu API mới (lần đầu)

1. Đảm bảo tech context + đã đọc DB design.
2. Rút endpoint từ spec: mỗi hành động màn hình (xem danh sách, tạo, sửa, xóa, đổi trạng thái, đăng nhập...) → 1 endpoint. Nhóm theo resource (auth, tasks, users...).
3. Sinh tài liệu chung docs/spec/api/05_00_common-api.md theo references/api-common-template.md — gồm danh sách toàn bộ endpoint (gán API-NNN).
4. Với mỗi nhóm resource: sinh docs/spec/api/05_NN_<resource>-api.md theo references/api-resource-template.md — mỗi endpoint có request/response JSON + validation + error + thao tác DB (bảng/cột).
5. Validation phải khớp ràng buộc DB (độ dài, NOT NULL, CHECK, UNIQUE) — xem references/api-rules.md.
6. Cập nhật 00_index.md: thêm bảng truy vết API (xem references/api-rules.md §truy vết).
7. Self-review theo checklist cuối + phase-gate. Báo người dùng. Hỏi có sang Stage 5 (plan) không.

Nhánh 2 — Thêm/sửa một endpoint hoặc nhóm resource

1. Đọc 00_index.md + tài liệu chung để lấy API-NNN kế tiếp, error code, format.
2. Thêm/sửa endpoint trong tài liệu riêng; cập nhật danh sách endpoint tổng ở tài liệu chung.
3. Tăng version + Lịch sử thay đổi. Cập nhật bảng truy vết API ở 00_index.md.

Nhánh 3 — Đồng bộ khi spec/DB thay đổi — QUAN TRỌNG

1. Đọc 00_index.md: xác định F-NNN/bảng nào đổi → endpoint nào bị ảnh hưởng.
2. Liệt kê danh sách endpoint/tài liệu tác động cho người dùng xác nhận TRƯỚC KHI sửa.
3. Sửa đồng bộ request/response/validation + danh sách endpoint chung. Tăng version + changelog.
4. Cập nhật 00_index.md.
5. Kiểm tra chéo theo ../spec-writer/references/cross-doc-checks.md (mục C: API ↔ màn & DB); báo CRITICAL/WARNING.

Nhánh 4 — Review / gap analysis

1. Chạy checklist + phase-gate (cuối file) + đối chiếu chéo: mọi yêu cầu dữ liệu của màn có endpoint phục vụ? mọi endpoint chỉ tham chiếu bảng/cột có thật trong DB design?
2. Báo cáo thiếu sót (endpoint thiếu JSON, validation lệch DB, error chưa định nghĩa, API thừa không gắn F-NNN).

---

Cấu trúc tài liệu sinh ra

docs/spec/
├── 00_index.md            # bổ sung bảng truy vết API ở đây
└── api/
    ├── 05_00_common-api.md          # tài liệu chung (BẮT BUỘC, tạo trước)
    ├── 05_01_<resource>-api.md      # tài liệu riêng theo nhóm resource
    └── 05_02_<resource>-api.md

Số file riêng: 05_01..99; 05_00 luôn là tài liệu chung.

---

Quy tắc tầng nào sở hữu gì

• Tài liệu chung: format/error/auth/pagination dùng chung — định nghĩa MỘT lần.
• Tài liệu riêng: chi tiết endpoint — tham chiếu tài liệu chung, không lặp.
• Validation ở API là hợp đồng I/O; phải nhất quán (không mâu thuẫn) với CHECK/độ dài/NOT NULL của DB design và với validation UI ở spec con.
• KHÔNG viết code handler trong tài liệu — chỉ bảng route mapping (endpoint → handler name).

---

Template & quy tắc — đọc khi cần

• references/api-common-template.md — khuôn tài liệu chung (10 section).
• references/api-resource-template.md — khuôn tài liệu riêng (6 section + per-endpoint).
• references/api-rules.md — quy tắc REST/đặt tên, API-ID, error code chuẩn, validation↔DB, cập nhật truy vết 00_index.md, phase-gate.

---

Checklist self-review (trước khi báo người dùng)

1. 2 tầng: có tài liệu chung; tài liệu riêng không lặp format/error/auth, có link tham chiếu chung.
2. API-ID: mọi endpoint có API-NNN; danh sách tổng ở tài liệu chung khớp các tài liệu riêng.
3. JSON: mọi endpoint có ví dụ request (nếu có body) + response thành công + bảng error.
4. Validation ↔ DB: ràng buộc validate khớp định nghĩa cột DB (độ dài, NOT NULL, CHECK, UNIQUE).
5. Phủ màn hình: mọi yêu cầu dữ liệu của screens/F-NNN_*.md có endpoint phục vụ.
6. Truy vết: mọi endpoint map F-NNN + màn + bảng DB trong 00_index.md; không tham chiếu bảng/cột không tồn tại.
7. Placeholder & version: không còn Cần xác nhận chưa xử lý; có version + Lịch sử thay đổi.