Bản đồ cấu trúc wiki
Trang này giải thích wiki được tổ chức ra sao, mỗi loại trang chịu trách nhiệm cho phần nào, và vì sao một số domain có ít trang hơn domain khác.
Quy tắc một domain kể chuyện
Các domain đi theo hướng từ ngoài vào trong. Mỗi trang trả lời một nhóm câu hỏi riêng; không lặp lại toàn bộ nội dung của trang khác.
| Tầng | Câu hỏi chính | Nội dung nên có | Trang chuẩn |
|---|---|---|---|
| 1. Tổng quan | Domain này là gì, nằm ở đâu trong hệ thống? | Phạm vi, đối tượng, quick flow, link đọc tiếp | index.md |
| 2. End-user | Người dùng thao tác và nhìn thấy gì? | Actor, điều kiện trước, happy path, trạng thái UI | end-user-view.md |
| 3. Khái niệm | Những object, trạng thái và invariant nào cần hiểu? | Thuật ngữ, lifecycle, rule, boundary | concepts.md |
| 4. Kiến trúc | Thành phần và dữ liệu phối hợp thế nào? | UI/API/service, database, queue, external system | architecture.md |
| 5. Codebase | Luồng thực thi nằm ở đâu trong code? | Route, controller, service, worker, sequence | codebase-flow.md |
| 6. Data links | Dữ liệu được đọc, ghi và đồng bộ ở đâu? | Table, projection, event, queue, blob, provider | data-links.md |
| 7. Case thường gặp | Khi có triệu chứng cụ thể thì kiểm tra gì? | Behavior, cách verify, source anchor, ví dụ thực tế | common-cases.md |
| 8. Tham chiếu | Có thể truy ngược về source nào? | Spec, class, route, test, anchor | references.md nếu domain có |
Đọc theo vai trò
| Vai trò | Luồng đọc đề xuất |
|---|---|
| Người mới / Product | Bản đồ hệ thống → Tổng quan → End-user → Khái niệm |
| Support / Operations | Tổng quan → End-user → Case thường gặp → Khái niệm |
| Engineer | Tổng quan → Khái niệm → Kiến trúc → Data links → Codebase → Tham chiếu |
| Architect / PM | Bản đồ hệ thống → Tổng quan → Kiến trúc → Tham chiếu |
Nếu chỉ cần câu trả lời cho một tình huống cụ thể, bắt đầu từ common-cases.md, sau đó đi ngược về Concepts hoặc Architecture khi cần hiểu nguyên nhân.
Ma trận domain và ngoại lệ có chủ đích
Các ngoại lệ dưới đây là quyết định tổ chức nội dung, không phải thiếu sót ngẫu nhiên. Khi một domain chưa có một loại trang riêng, thông tin đó được đặt ở trang gần nhất và liên kết từ Overview.
| Domain | Cấu trúc chính | Ngoại lệ / cách hiểu |
|---|---|---|
| Subscription | Luồng chuẩn đầy đủ | Có thêm codebase flow cho lifecycle và billing schedule. |
| Booking | Luồng chuẩn đầy đủ | Có các phần mở rộng cho discount, combine booking và reconciliation. |
| Communication | Luồng chuẩn đầy đủ | Tập trung vào render, delivery, reminder và campaign. |
| Incident Management | Luồng chuẩn đầy đủ | Workflow, permission, acknowledgement và signature được trình bày theo case. |
| Platform | Luồng kỹ thuật đầy đủ | Là domain cross-cutting; End-user mô tả bề mặt quan sát được, còn trọng tâm là event/notification/history. |
| Finance | Overview → Concepts → Architecture → Data links → Common cases | Chủ yếu là domain nội bộ/admin nên không có End-user view riêng. |
| Payment | Overview → Concepts → Architecture → Data links → Common cases | Tập trung vào configuration, checkout, provider và reconciliation; không có End-user hoặc Codebase page riêng. |
| Master Data | Overview → Concepts → Architecture → Data links → Common cases | Là domain setup/source data; không có End-user hoặc Codebase page riêng. |
| Customer Portal | Overview → End-user → Concepts → Architecture → Data links → Common cases | Customer-facing nhưng phần code được gắn vào Architecture và Data links; không có Codebase page riêng. |
| Dashboard | Overview → End-user → Concepts → Architecture → Data links → Common cases | Read-only query/aggregate; không có Codebase page riêng. |
| Payroll | Overview → End-user → Concepts → Architecture → Data links → Common cases | Workflow được mô tả ở Architecture và Data links; không có Codebase page riêng. |
| Staff | Overview → End-user → concepts-architecture.md → Data links → Common cases | Concepts và Architecture được gộp vì cùng một boundary nghiệp vụ. |
| Foundation | Nhóm tài liệu nền tảng | Không phải business domain độc lập; bao gồm app, storage, timezone, database và conventions dùng chung. |
Chuẩn nội dung của từng trang
- Mỗi trang có đúng một tiêu đề H1 và một đoạn mở đầu trả lời nhanh đây là gì, dành cho ai, đọc để làm gì.
- H2 dùng cho các chủ đề chính; H3 chỉ dùng cho nhánh nhỏ hoặc từng case. Không tạo heading chỉ để trang trí.
- Tên class, route, enum, table và anchor giữ nguyên dạng code để có thể tìm ngược về repository.
- Mỗi business rule quan trọng nên có một Ví dụ thực tế ngay sau rule, nêu rõ bối cảnh → mục đích → kết quả mong đợi.
- Ghi rõ nội dung đang mô tả implementation hiện tại, contract trong OpenSpec, hay quyết định tổ chức tài liệu.
- Khi một nội dung đã có trang sở hữu, trang khác chỉ tóm tắt và link về trang đó; không tạo hai bản giải thích dễ lệch nhau.
- Các danh mục page/link để tra cứu (
Đọc theo thứ tự,Liên quan,Các trang trong phần này) dùng ordered list hoặc table; bullet list dành cho facts, notes và checklist không có thứ tự.
Chuẩn trang “Case thường gặp”
Mỗi case nên đi theo đúng thứ tự sau để người đọc có thể chẩn đoán nhanh:
- Triệu chứng / câu hỏi — người dùng hoặc support đang thấy gì?
- Behavior đúng / rule — hệ thống phải làm gì, và điều gì không được làm?
- Cách kiểm tra — kiểm tra ở UI, API, dữ liệu, queue hoặc code nào?
- Source anchor — spec, class, route, test hoặc trang liên quan nào làm căn cứ?
- Ví dụ thực tế — bối cảnh → mục đích → kết quả mong đợi.
Các case ưu tiên behavior đang chạy. Khi cần contract gốc hoặc chi tiết triển khai, mở source anchor được dẫn trong case thay vì suy ra từ ví dụ.