Quy ước cấu trúc tài liệu Module
Nguồn sự thật 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.
Trục tính năng (Feature Spine)
Toàn bộ wiki có một trục duy nhất, và đơn vị nối kết nó lại là Tính năng (Feature).
Một Tính năng là một Vùng chức năng - chính mã
<AREA>sẵn có (STK,PO,BOM…). Ta không phát minh hệ ID mới: yêu cầu (URD-<AREA>-NNN), đợt build (PRD-<AREA>-NNN), và test (TC-<AREA>-NNN) của một tính năng đã được gắn theo mã đó. Ta chỉ đặt tên cho cái mà những mã này trỏ tới và nâng nó thành đối tượng hạng nhất.
Một tính năng sống ở hai nhà với hai vai trò, nối bằng một Mã tính năng (<module>/<AREA>):
| Nhà | Vai trò | Đối tượng |
|---|---|---|
| Delivery (danh mục tính năng) | Danh sách - tên · trạng thái, nhóm theo Phase → Epic. Không chi tiết nghiệp vụ. | PM / quản lý |
URD (urd.md) | Mô tả - mỗi tính năng làm gì cho người dùng, yêu cầu và nghiệm thu. Đây là tài liệu nghiệp vụ. | PM / PO / BA / QE |
Delivery Phase → Epic → Feature (danh sách + trạng thái, link → URD) [góc nhìn PM - đơn giản]
URD Feature = một mục: mô tả nghiệp vụ + yêu cầu + nghiệm thu
PRD một đợt build của Feature (1 Feature → nhiều PRD theo thời gian)
Test Case viết TỪ một PRD (lúc này TC mới có ý nghĩa)
─────────────────────────────────────────────────────────────────────────────────
Module ⇄ Package (ánh xạ ngang: nghiệp vụ ⇄ kỹ thuật)Trục một chiều: Phase → Epic → Feature (URD) → PRD → Test Case. Một trục ngang: Module ⇄ Package (xem bảng ánh xạ ở §5). Mọi quy tắc bên dưới đều phục vụ trục này.
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. |
| Liên kết đầu-cuối | Người đọc có thể theo một tính năng từ lộ trình → module → PRD → ADR → dev → test → runbook chỉ trong vài cú nhấp. |
| Ư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à sự thật | 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
├── 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 |
|---|
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?" |
<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?" |
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 - 11 mục
Traceability block (xem §6.1) · Identity (bảng) · Purpose & Scope (trong/ngoài) · Capabilities · Module Dependencies · Engineering Mapping (§5.1, Module ⇄ Package) · 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
5.1 Ánh xạ kỹ thuật (Module ⇄ Package) - trục ngang
Trang index của module mang một bảng đóng khoảng cách giữa tài liệu nghiệp vụ và kỹ thuật. Mỗi tính năng một dòng:
## Engineering Mapping
| Tính năng | Dev package | ADRs | Trạng thái |
|---|---|---|---|
| `STK` Stock Tracking | [@nx/inventory](/vi/developer/packages/inventory/) | [ADR-0001](/vi/developer/packages/inventory/decisions/0001-...) | Built |Tương hỗ: mỗi
indexcủa package được liên kết bổ sung một dòng trỏ ngược lại module (xem §6.2).
urd.md - tổ chức theo tính năng
URD chính là danh sách tính năng của module. Thứ tự cố định:
Header (module id · phiên bản · ngày) · Purpose · Scope (trong/ngoài) · Definitions (tùy chọn) · Conceptual Model (mermaid, tùy chọn) · Feature Catalog (bảng tính năng tổng quan) · Features (một mục con cho mỗi tính năng) · Constraints & Non-Goals · Version History
- Feature Catalog - bảng tóm tắt:
Mã tính năng · Tính năng · Phase · Trạng thái · Ưu tiên. Đây là danh sách tính năng dễ quét; trạng thái theo từng tính năng. - Features - phần thân. Mỗi tính năng một mục con, theo thứ tự catalog. Mỗi tính năng giữ mô tả + yêu cầu + nghiệm thu cùng nhau để người đọc nhảy tới một tính năng là thấy hết:
### `STK` - Stock Tracking <Badge text="Built" />
**Mã tính năng:** `inventory/STK` · **Phase:** P1 · **PRDs:** [PRD-STK-001](./prds/...) · **Dev:** [@nx/inventory](...)
Làm gì cho người dùng: <1-3 dòng, ngôn ngữ nghiệp vụ>
**Yêu cầu**
| ID | P | Yêu cầu |
|---|:-:|---|
| URD-STK-001 | **M** | ... |
**Nghiệm thu**
::: details AC-STK-01: ...
| Given | When | Then |
:::Kiểu tách cũ - một bảng Functional-Requirements toàn cục cộng một mục Acceptance-Criteria toàn cục riêng - đã bị bỏ. Yêu cầu và nghiệm thu giờ nằm trong tính năng của chúng.
prds/index.md
Một bảng duy nhất: PRD · Date · Status · Title · Modules touched.
prds/YYYY-MM-DD-<slug>.md - PRD
Header khai báo Mã tính năng (<module>/<AREA>) để thấy rõ 1 Feature → nhiều PRD. Thân: 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 |
| Tính năng (= Vùng chức năng) | <module>/<AREA> | inventory/STK, inventory/PO |
| Yêu cầu URD | URD-<AREA>-NNN | URD-STK-001 |
| PRD | PRD-<AREA>-NNN | PRD-STK-001 |
| ADR (dev) | ADR-NNNN | ADR-0005 |
| Ư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 = một tính năng, nhất quán giữa URD, TC và PRD để chúng khớp nhau (URD-STK-001↔TC-STK-001) và cùng quy về Mã tính năng<module>/<AREA>.- ID là được đệm số 0, tuần tự, và không bao giờ tái sử dụng - kể cả sau khi một yêu cầu bị bỏ, số của nó được loại bỏ vĩnh viễn, không dùng lại.
6.1 Khối truy vết (đầu mọi index.md của module) - BẮT BUỘC
Wiki có MỘT trục: người đọc phải theo được một tính năng đơn từ lộ trình → module → PRD → ADR → dev → test → runbook. Mọi index.md của module mở đầu bằng khối cố định này. Liên kết thiếu được ghi - (không bao giờ bỏ trống) để các khoảng trống hiện rõ:
> **Status:** In-progress · **Owner:** <name> · **Phase:** 1 · **Last reviewed:** YYYY-MM-DD
>
> | Chain | Link |
> |-------|------|
> | Roadmap | [Phase 1](/en/delivery/roadmap#phase-1) |
> | URD | [URD](./urd) |
> | PRD | [PRD-STK-001](./prds/2026-05-10-opening-balance) |
> | Decisions (ADR) | [ADR-0001](/en/developer/packages/inventory/decisions/0001-polymorphic-inventory-item) |
> | Plan | [.agents/plans/2026-05-10-inventory-opening-balance](#) |
> | Dev docs | [@nx/inventory](/en/developer/packages/inventory/) |
> | Runbook | [Inventory ops](/en/runbook/operations/) |
> | Delivery log | [Traceability matrix](/en/delivery/traceability-matrix) |6.2 Footer "Related Pages" tương hỗ - BẮT BUỘC
Liên kết Markdown là một chiều, nên một liên kết PHẢI được thêm theo CẢ HAI chiều. Khi bạn thêm module → ADR, hãy thêm cả ADR → module. Mọi trang kết thúc bằng ## Related Pages. Các cặp tương hỗ bắt buộc:
| Nếu trang A liên kết tới B | B phải liên kết ngược lại A |
|---|---|
| Dòng tính năng Delivery → anchor tính năng URD | Tính năng URD → danh mục tính năng Delivery |
index module Engineering Mapping → developer package | index package → module |
index module → phase lộ trình | dòng phase lộ trình → module |
| PRD → ID yêu cầu URD | URD → các PRD của nó |
| module / PRD → ADR | ADR "Related" → module / PRD |
| tính năng → runbook | runbook → tính năng / package |
Một CI lint nhẹ về sau có thể kiểm tra mọi tham chiếu
related:đều giải được và được tương hỗ - phương án thay thế rẻ tiền cho việc kiểm tra liên kết lúc build.
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.mdvà liên kết tới lộ trình delivery. 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) |
| Link graph | Liên kết trong khối truy vết và footer Related là giống hệt giữa EN/VI - dịch văn xuôi, không bao giờ làm lệch link graph. EN là chuẩn cho ID. |
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 (danh sách tính năng)
├─ PRDs (liên kết → prds/index.md)
├─ Test Cases
└─ <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ự spine URD → PRDs → Test Cases → Features (test case viết từ PRD, nên PRDs đứng trước Test Cases). - 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
# Điền khối truy vết §6.1 (dùng - cho các liên kết chưa tồn tại)
# 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 (gồm khối truy vết) + urd.md | PM/PO/BA |
| Thêm một PRD cho mỗi đợt | PM/PO |
| Đăng ký sidebar | Tác giả |
12. Phản mẫu (không được làm)
| Phản mẫu | Vì sao tệ |
|---|---|
<module>.md ngang hàng + thư mục <module>/ | Hai chỗ cho một module; dùng <module>/index.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 |
| Một bảng Functional-Requirements toàn cục + mục Acceptance toàn cục riêng | Đã bỏ; tổ chức URD theo tính năng (§5) để mỗi tính năng tự chứa |
| Một tính năng có trong URD nhưng không có trong danh mục Delivery (hoặc ngược lại) | Phá vỡ trục; hai nhà phải khớp nhau |
| 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 |
| Liên kết một chiều | Phá vỡ trục; thêm liên kết Related tương hỗ (§6.2) |
| Bỏ sót khối truy vết | Người đọc không thể theo tính năng đầu-cuố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
- Quy trình phát triển - thứ tự tạo các tài liệu (URD → PRD → ADR → Plan → code → test) và vị trí duy nhất cho từng loại
- 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ư
- Delivery - Lộ trình - kế hoạch giai đoạn hướng tới tương lai
- Delivery - Danh mục tính năng - danh sách tính năng theo từng phase (một nhà của Feature Spine)
- Delivery - Ma trận truy vết - góc nhìn độ phủ liên dự án
- 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