Quy ước cấu trúc tài liệu Module
Nguồn chân lý duy nhất cho cách cấu trúc tài liệu của mọi module sản phẩm. Bộ khung mirror nằm tại
content/{en,vi}/modules/_template/(không xuất bản lên site — sao chép từ source). Mọi module — core, extended hay industry — đều theo đúng hình dạng này.Đây là phần đối ứng sản phẩm/nghiệp vụ của Cấu trúc tài liệu cho lập trình viên hướng tới kỹ sư. Tài liệu module mô tả sản phẩm làm gì cho người dùng; tài liệu package cho lập trình viên mô tả nó được xây dựng như thế nào.
1. Mục tiêu
| Mục tiêu | Vì sao quan trọng |
|---|---|
| Tính đồng nhất | Người đọc đã nắm tài liệu của một module thì nắm được tất cả. Không tốn chi phí khám phá. |
| Phù hợp đối tượng | Viết cho PM / PO / BA / QE / sales — ngôn ngữ nghiệp vụ, không phải chi tiết triển khai. |
| Truy vết Spec ↔ test | Mọi yêu cầu (URD) ánh xạ tới một test case (TC) theo ID. Không gì không được kiểm thử, không gì không được truy vết. |
| Ưu tiên trực quan | Bảng + mermaid (graph, stateDiagram-v2, sequenceDiagram, erDiagram) thay vì văn xuôi. |
| Trung thực về trạng thái | Mỗi module/tính năng khai báo Built / In-progress / Planned để người đọc không nhầm một mục lộ trình với tính năng đã ship. |
| Code là chân lý | Tính năng Built mô tả hành vi thực tế đã đối chiếu với codebase, không phải kỳ vọng. |
2. Phân hạng Module
| Hạng | Thư mục | Ý nghĩa | Giai đoạn |
|---|---|---|---|
| Core | modules/core/ | Thiết yếu, mọi merchant đều cần | A |
| Extended | modules/extended/ | Tiện ích bổ sung tăng trưởng/gắn kết | B |
| Industry | modules/industry/ | Bộ giải pháp chuyên biệt theo ngành dọc | C |
| Use Cases | modules/use-cases/ | Kịch bản đầu-cuối kết hợp nhiều module | — |
Giải pháp ngành là sự kết hợp của các module core/extended, không phải module mới. Trang của chúng tham chiếu tới các module mà chúng đóng gói thay vì đặc tả lại.
3. Bố cục thư mục
content/{en,vi}/modules/<tier>/<module>/
├── index.md # ⓜ Thẻ định danh: mục đích, phạm vi, năng lực, phụ thuộc, luồng chính
├── urd.md # ⓜ Tài liệu Yêu cầu Người dùng: personas, phạm vi, yêu cầu chức năng, nghiệm thu
├── test-cases.md # ⓜ (Built/In-progress) Test case truy vết tới ID của URD
├── prds/
│ ├── index.md # ⓜ Danh mục PRD
│ └── YYYY-MM-DD-<slug>.md # ⊕ một PRD cho mỗi đợt tính năng
└── <feature>.md ... # ⊕ Tài liệu chuyên sâu theo tính năng (tùy chọn, hiếm khi cần ở cấp module)ⓜ bắt buộc · ⊕ tùy chọn
Theo thư mục, giống package cho lập trình viên. Trang tổng quan nằm tại
<module>/index.mdđể URL giữ nguyên/modules/<tier>/<module>. Không giữ một file<module>.mdngang hàng.
Bộ bắt buộc theo trạng thái
| Trạng thái module | File bắt buộc |
|---|---|
| Built / In-progress | index.md + urd.md + test-cases.md + prds/index.md |
| Planned (chưa xây) | index.md + urd.md (stub OK) + prds/index.md — test-cases.md tùy chọn cho đến khi bắt đầu xây |
4. Vai trò tài liệu
| Trang | Vai trò | Trả lời |
|---|---|---|
index.md | Thẻ định danh / tổng quan | "Module này là gì, làm được gì, phụ thuộc vào gì?" |
urd.md | Tài liệu Yêu cầu Người dùng | "Nó phải làm gì cho người dùng, và làm sao biết nó đúng?" |
prds/*.md | Tài liệu Yêu cầu Sản phẩm | "Đợt này chúng ta xây gì, và vì sao?" |
test-cases.md | Kiểm chứng | "Mỗi yêu cầu được chứng minh ra sao?" |
<feature>.md | Chuyên sâu tính năng | "Một tiểu vùng phức tạp này hoạt động đầu-cuối ra sao?" |
Quy tắc: giữ các vai trò tách biệt. Yêu cầu nằm trong URD; lý do/phạm vi đợt nằm trong PRD; bằng chứng nằm trong test-cases. Trang tổng quan liên kết tới cả ba và không lặp lại nội dung nào.
5. Mẫu cho từng trang
File khung nằm tại
content/{en,vi}/modules/_template/(chỉ source). Thứ tự các mục là cố định.
index.md — 9 mục
Identity (bảng) · Purpose & Scope (trong/ngoài) · Capabilities · Module Dependencies · Backend Packages (liên kết tới tài liệu lập trình viên) · Key User Flows (mermaid) · Roles & Permissions · Status & Roadmap · Related Pages
urd.md — 8 mục
Header (module id · phiên bản · ngày) · Purpose · Scope (trong/ngoài) · Definitions · Conceptual Model (mermaid) · Functional Requirements (bảng ID + ưu tiên MoSCoW) · Acceptance Criteria (Given/When/Then) · Constraints & Non-Goals · Version History
test-cases.md — 3 mục
Coverage Summary (số lượng theo nhóm yêu cầu) · Test Cases (một bảng: TC ID · URD ref · Scenario · Steps · Expected · Priority) · Traceability (ma trận URD → TC; gắn cờ mọi yêu cầu chưa được phủ)
prds/index.md
Một bảng duy nhất: PRD · Date · Status · Title · Modules touched.
prds/YYYY-MM-DD-<slug>.md — PRD
Context (vấn đề/cơ hội) · Goals & Non-Goals · Requirements (liên kết ID của URD) · UX / Flows · Rollout & Metrics · Open Questions.
6. Quy ước ID & truy vết
| Hiện vật | Định dạng ID | Ví dụ |
|---|---|---|
| Module | <TIER>-NN | CORE-06, EXT-02, IND-03 |
| Yêu cầu URD | URD-<AREA>-NNN | URD-STK-001 |
| Test case | TC-<AREA>-NNN | TC-STK-001 |
| Ưu tiên (yêu cầu) | MoSCoW: Must · Should · Could · Won't | — |
<AREA>là mã ngắn 2–4 chữ cái cho mỗi vùng chức năng, nhất quán giữa URD và TC để chúng khớp nhau (URD-STK-001↔TC-STK-001).- Mọi yêu cầu Must có ít nhất một test case. Mục Traceability của
test-cases.mdphải gắn cờ mọi khoảng trống.
7. Quy tắc văn phong biên soạn
| Quy tắc | Thực thi |
|---|---|
| Đối tượng | PM/PO/BA/QE/sales. Giải thích tính năng theo góc nhìn người dùng; liên kết tới tài liệu lập trình viên cho nội bộ — không bao giờ chèn inline schema/SQL/code. |
| Ưu tiên trực quan | Bảng/mermaid cho mọi danh sách ≥3 mục. Chỉ dùng văn xuôi khi không cái nào phù hợp. |
| Văn xuôi súc tích | Tối đa 4 dòng mỗi đoạn. Gạch đầu dòng > đoạn văn. |
| Frontmatter | Luôn có title, description, outline: deep. |
| Nhãn trạng thái | Dùng <Badge> của VitePress cho giai đoạn/trạng thái (Built, In-progress, Planned, Phase A/B/C). |
| Liên kết chéo | Liên kết nội bộ dùng đường dẫn tuyệt đối /vi/.... Liên kết module → tài liệu backend package, và module → use-cases dùng nó. |
| Chỉ tiếng Anh trong định danh | Tiếng Việt chỉ trong chuỗi bản địa hóa hướng tới người dùng. |
| Không emoji | Trừ khi là một phần của UI đang được tài liệu hóa. |
8. Chính sách Trạng thái & Lộ trình
| Trạng thái | Ý nghĩa | Trong index.md |
|---|---|---|
Built | Đã ship và kiểm chứng được trong code hôm nay | Mô tả hành vi thực tế |
In-progress | Ship một phần | Đánh dấu năng lực nào đã chạy so với chờ |
Planned | Chỉ là lộ trình | Gắn nhãn rõ ràng; không tuyên bố hành vi đang chạy |
Các giai đoạn lộ trình (P1/P2/P3 trong một module, và Phase A/B/C theo hạng) nằm trong mục
Status & Roadmapcủaindex.md. Không rải ghi chú giai đoạn khắp các bảng yêu cầu — giữ chúng ở một nơi.
9. Song song EN ↔ VI
| Quy tắc | Chi tiết |
|---|---|
| Mirror | Mỗi file EN có một bản đối ứng VI tại cùng đường dẫn tương đối |
| Đồng đều số dòng | Số dòng EN/VI chênh lệch trong ±5% |
| Thứ tự dịch | EN ship trước → VI theo sau theo lô |
| Nhãn mermaid | Dịch nhãn node; giữ định danh state/event và ID bằng tiếng Anh |
title & description của frontmatter | Được dịch |
| ID / code / tên định danh | Không bao giờ dịch (URD-STK-001, CORE-06, tên entity) |
10. Quy ước thanh bên (sidebar)
Mỗi module lồng dưới hạng của nó. Một module có trang con hiển thị chúng theo thứ tự cố định:
<Module Name> (liên kết → index.md)
├─ URD
├─ Test Cases
├─ PRDs (liên kết → prds/index.md)
└─ <feature pages…> (chỉ khi có)Quy tắc:
- Nhãn module liên kết tới
index.md; các mục con theo thứ tự URD → Test Cases → PRDs → Features. - Một module
Plannedchỉ có trang tổng quan hiển thị dưới dạng liên kết phẳng (không có mục lồng). - Giải pháp ngành là liên kết phẳng (chúng kết hợp, không đặc tả).
11. Khởi tạo một Module mới
# 1. Sao chép bộ khung
cp -r content/en/modules/_template content/en/modules/<tier>/<module>
cp -r content/vi/modules/_template content/vi/modules/<tier>/<module>
# 2. Thay placeholder: <Module Name>, <TIER>-NN, <AREA>, TODO:, dates
# 3. Đăng ký trong sidebar: .vitepress/locales/en.ts và vi.ts| Bước | Người phụ trách |
|---|---|
Sao chép bộ khung + điền index.md + urd.md | PM/PO/BA |
Thêm test-cases.md khi bắt đầu xây | QE |
| Thêm một PRD cho mỗi đợt | PM/PO |
| Đăng ký sidebar | Tác giả |
12. Mẫu phản (không được làm)
| Mẫu phản | Vì sao tệ |
|---|---|
<module>.md ngang hàng + thư mục <module>/ | Hai chỗ cho một module; dùng <module>/index.md |
Tên dài module-<x>-urd.md / module-<x>-tc.md | Tiền tố thừa; dùng urd.md / test-cases.md |
| Chèn inline schema DB, SQL, hoặc code vào tài liệu module | Sai đối tượng; liên kết tới tài liệu package cho lập trình viên |
| Yêu cầu không có test case | Phá vỡ truy vết; mọi Must cần một TC |
| Trộn yêu cầu, lý do và bằng chứng trên một trang | Dùng URD / PRD / test-cases tương ứng |
| Mô tả tính năng Planned như thể đã Built | Gây hiểu nhầm cho người đọc; luôn gắn nhãn trạng thái |
| Cấu trúc tự do theo từng module | Chính là lý do quy ước này tồn tại |
13. Liên quan
- Cấu trúc tài liệu cho lập trình viên — phần đối ứng hướng tới kỹ sư
- bộ khung
_template/—content/{en,vi}/modules/_template/ - Tổng quan Modules — danh mục module
- Phân loại ưu tiên MoSCoW — https://en.wikipedia.org/wiki/MoSCoW_method