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.
Ánh xạ thực thi (Plane)
Cùng một trục này điều phối việc thực thi. Ba tầng của Plane ánh xạ vào nó, và Feature là điểm neo bắt buộc cho công việc hằng ngày:
| Tầng Plane | Đơn vị trục | Tiêu đề | Parent | Bắt buộc |
|---|---|---|---|---|
| Epic | Epic (E1-E12) | [EPIC/<MODULE>] outcome | - | tùy chọn - việc cắt ngang (Platform, Reports đa module) không nhất thiết thuộc epic |
| Work Item | Feature | [FEAT/<MODULE>] tên feature | Epic của nó, nếu có | mỗi Feature một work item |
| Sub-issue | Task (việc hằng ngày của team) | [<area>/target] … | một Feature trong Phase hiện tại | bắt buộc - mọi task chọn một Feature |
Cả Epic lẫn Feature đều lấy prefix là tên capability module (vocabulary cố định), không phải AREA code tự do. ID chính tắc của feature trong spine <module>/<AREA> nằm ở link URD trong work item - AREA định danh yêu cầu và test (URD-PCK-001), còn tiêu đề giữ dạng dễ đọc ([FEAT/Sale] Product Picker). Feature work item gắn đầy đủ label (Type Feature · Phase · Module) và không có cycle - nó là một container. Task không bao giờ gắn thẳng vào Epic và không bao giờ trôi nổi: nó luôn đặt parent = [FEAT/<MODULE>] mà nó đẩy tiến độ, để tiến độ cộng dồn theo từng feature. Tư cách thuộc Epic được kế thừa qua parent của Feature đó.
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>/
├── urd.md # ⓜ Trang mặt tiền của module - 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
Không còn trang hub
index.mdcho từng module.urd.mdlà trang mặt tiền: nhãn module trong sidebar trỏ thẳng tới URD. Trang tổng quan chung của mọi module nằm tại Tổng quan Modules (bảng module + Bản đồ Module). Không giữ một file<module>.mdngang hàng.
4. Vai trò tài liệu
| Trang | Vai trò | Trả lời |
|---|---|---|
urd.md | Trang mặt tiền + Tài liệu Yêu cầu Người dùng | "Module này 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.
5.1 Ánh xạ kỹ thuật (Module ⇄ Package) - trục ngang
Trục ngang nằm ngay trong URD: dòng header của mỗi tính năng khai báo Dev package (**Dev:** [@nx/inventory](...)), và ADR được liên kết từ PRD/tài liệu package. Tương hỗ: mỗi index củ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 Chuỗi truy vết - 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. Chuỗi này sống ở hai chỗ:
- Dòng header của mỗi tính năng trong
urd.md-**Mã tính năng** · **Phase** · **PRDs** · **Dev**(xem mẫu §5). Liên kết thiếu được ghi-(không bao giờ bỏ trống) để các khoảng trống hiện rõ. - Ma trận truy vết - góc nhìn độ phủ liên dự án theo module.
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 |
Dòng **Dev:** của tính năng URD → developer package | index package → module (URD) |
| URD module → phase lộ trình | dòng phase lộ trình → module (URD) |
| 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 urd.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 |
Định nghĩa Hoàn thành - ba cổng
Trạng thái không phải cảm tính, cũng không phải một ticket đã đóng. Một feature đi qua ba cổng rõ ràng:
| Cổng | Hoàn thành khi | Người chốt | Tín hiệu |
|---|---|---|---|
| Hoàn tất kỹ thuật | code merge + review | Lập trình viên | Sub-issue Plane = Done |
| Hoàn thiện | các yêu cầu Must đạt Acceptance Criteria (URD) | PO / QE | Feature work item = Done · badge wiki → Built |
| Nghiệm thu phát hành | Done signal end-to-end của epic chạy thật trên merchant | PM | Epic đạt 100% + đã kiểm chứng |
Phần trăm trên Plane chỉ là chỉ báo tiến độ. Một feature chỉ Built khi đạt Acceptance Criteria - không phải khi các task đóng hết.
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
Feature Catalogcủaurd.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 → urd.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 thẳng tới
urd.md(trang mặt tiền); 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ó URD 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 (urd.md + prds/)
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 chuỗi truy vết §6.1 trong header từng tính năng (dùng - cho liên kết chưa tồn tại)
# 3. Đăng ký trong sidebar (nhãn module trỏ …/<module>/urd): .vitepress/locales/en.ts và vi.ts| Bước | Người phụ trách |
|---|---|
Sao chép bộ khung + điền urd.md (gồm chuỗi truy vết theo tính năng) | 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 thư mục <module>/ với urd.md làm trang mặt tiền |
Thêm lại trang hub index.md cho một module | Quy ước đã bỏ hub; URD là trang mặt tiền, tổng quan chung nằm ở Tổng quan Modules |
| 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 chuỗi truy vết trong header tính năng URD | 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