db-designer

db-designer — Thiết kế Cơ sở dữ liệu từ spec

Sinh & quản lý tài liệu Thiết kế Cơ sở dữ liệu từ bộ spec do spec-writer tạo ra (docs/spec/). Mục tiêu: tài liệu DB đủ căn cứ để sinh test spec và code — định nghĩa bảng/cột/kiểu, constraint, index, relation, ER diagram, phân loại dữ liệu — đồng thời giữ truy vết F-NNN ↔ bảng ↔ NFR trong 00_index.md.

Ngôn ngữ: tiếng Việt là chính; tên bảng/cột/kiểu dữ liệu/constraint để 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 (định nghĩa bảng, ER) ra chat.
• Tạo xong báo ngắn: đường dẫn + tóm tắt (số bảng, danh mục). 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

db-designer là Stage 3 (DB) — chạy SAU spec (spec-writer), TRƯỚC API (api-designer).

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

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

---

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

1. Phải có docs/spec/00_index.md + docs/spec/01_requirements.md. Nếu chưa có → dừng, đề nghị chạy spec-writer trước.
2. Đọc 00_index.md để lấy danh sách F-NNN, NFR-X-NNN, các màn hình.
3. Đọc 01_requirements.md (Glossary, scope, NFR) và các screens/F-NNN_*.md liên quan để biết dữ liệu nào màn hình cần.

---

Tech context (bước mở đầu — bắt buộc)

DB design cần biết DBMS. Trước khi thiết kế bảng:

1. Kiểm tra docs/spec/02_tech_context.md. Nếu chưa có → sinh nó theo references/tech-context-template.md, hỏi người dùng (1 câu/lần) các mục còn thiếu: DBMS + phiên bản, backend framework, phương thức xác thực (session/JWT/OAuth2), ngôn ngữ lập trình.
2. Thông tin nào người dùng chưa chốt → ghi giá trị đề xuất + đánh dấu Cần xác nhận, KHÔNG bịa.
3. 02_tech_context.md dùng chung cho cả db-designer và api-designer.

---

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

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

1. Đảm bảo tech context (mục trên).
2. Đọc spec để rút ra thực thể: mỗi danh từ nghiệp vụ lặp lại / mỗi đối tượng màn hình thao tác → ứng viên bảng. Đối chiếu Glossary + catalog entity ở conventions.md nếu có.
3. Phân loại bảng: Master / Transaction / Log / Trung gian (M:N).
4. Sinh docs/spec/database/03_database-design.md theo references/db-design-template.md (≤15 bảng: 1 file; >15 bảng: tách Master/Transaction/ER theo references/db-rules.md § file).
5. Với mỗi bảng: viết đủ 9 mục theo references/db-rules.md (định nghĩa, constraint, index, relation, quy tắc nghiệp vụ, hiệu năng, bảo mật, thời hạn lưu trữ).
6. Vẽ ER diagram Mermaid Crow's Foot (xem references/db-rules.md §ER).
7. Điền Phân loại dữ liệu (PII / Mật / Nội bộ / Công khai) cho mọi cột nhạy cảm.
8. Liên kết index ↔ NFR-P (yêu cầu hiệu năng) khi có.
9. Cập nhật 00_index.md: thêm bảng truy vết DB (xem references/db-rules.md §truy vết).
10. Self-review theo checklist cuối + phase-gate. Báo người dùng. Hỏi có sang Stage 4 (API) không.

Nhánh 2 — Thêm/sửa một bảng

1. Đọc 00_index.md + tài liệu DB hiện có để biết quan hệ.
2. Thêm/sửa định nghĩa bảng (đủ 9 mục), cập nhật ER diagram cho khớp.
3. Tăng version tài liệu + ghi Lịch sử thay đổi.
4. Cập nhật bảng truy vết DB trong 00_index.md.

Nhánh 3 — Đồng bộ khi yêu cầu (spec) thay đổi — QUAN TRỌNG

1. Đọc 00_index.md xác định F-NNN nào đổi → bảng nào bị ảnh hưởng.
2. Liệt kê danh sách bảng/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ộ: định nghĩa bảng + ER + phân loại dữ liệu. 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 B: màn ↔ DB); báo CRITICAL/WARNING.

Nhánh 4 — Review / gap analysis tài liệu DB hiện có

1. Chạy checklist chất lượng + phase-gate (cuối file).
2. Báo cáo các thiếu sót (bảng thiếu PK/FK, cột thiếu NULL constraint, ER lệch định nghĩa, thiếu phân loại dữ liệu, Cần xác nhận chưa giải quyết).

---

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

docs/spec/
├── 00_index.md            # (spec-writer) — bổ sung bảng truy vết DB ở đây
├── 02_tech_context.md     # DBMS / framework / auth (dùng chung db + api)
└── database/
    ├── 03_database-design.md        # ≤15 bảng: 1 file
    │                                 # >15 bảng: tách ↓
    ├── 03_1_master-tables.md
    ├── 03_2_transaction-tables.md
    └── 03_3_er-diagram.md

(ADR tùy chọn: docs/spec/database/adr/ADR-NNN_*.md cho quyết định lớn — xem references/db-rules.md §ADR.)

---

Quy tắc tầng nào sở hữu gì (tránh trùng/mâu thuẫn)

• Spec con (spec-writer) sở hữu: field UI, validation phía người dùng, message, flow màn hình.
• Tài liệu DB sở hữu: cột vật lý, kiểu dữ liệu, constraint DB, index, relation, phân loại dữ liệu.
• Quy tắc nghiệp vụ ở DB chỉ ghi phần thực thi ở tầng dữ liệu (CHECK constraint, FK behavior, soft delete); KHÔNG lặp lại nguyên văn rule UI.
• KHÔNG bịa thực thể/cột không có căn cứ ở spec; cần thêm → đánh dấu Cần xác nhận.

---

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

• references/db-design-template.md — khuôn tài liệu DB (9 section + per-table).
• references/tech-context-template.md — khuôn 02_tech_context.md.
• references/db-rules.md — quy tắc đặt tên, kiểu dữ liệu, ER Mermaid, phân loại dữ liệu, cập nhật truy vết 00_index.md, phase-gate, ADR.

---

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

1. PK/FK: mọi bảng có primary key; mọi FK có index tương ứng.
2. NULL: mọi cột ghi rõ NULL/NOT NULL.
3. ER khớp: ER diagram khớp 100% định nghĩa bảng mới nhất.
4. Phân loại dữ liệu: mọi cột PII/nhạy cảm có phân loại + yêu cầu bảo vệ.
5. Truy vết: mọi bảng map tới ≥1 F-NNN trong 00_index.md; index hiệu năng gắn NFR-P nếu có.
6. Placeholder: không còn Cần xác nhận chưa xử lý (trừ phần cố ý chờ người dùng) + có version & Lịch sử thay đổi.
7. Không lệ thuộc ORM: định nghĩa ở mức logic (SQL/kiểu dữ liệu), KHÔNG viết schema Prisma/TypeORM trong tài liệu thiết kế.