Quy ước Cấu trúc Tài liệu

Nguồn chân lý duy nhất về cách cấu trúc tài liệu nhà phát triển cho mọi package backend. Bộ khung mẫu nằm tại content/{en,vi}/developer/packages/_template/ (chỉ có trong source - đã loại khỏi trang đã xuất bản, hãy sao chép từ source). Mọi package - hiện tại hay tương lai - đều tuân theo đúng hình dạng này.

1. Mục tiêu

Mục tiêu	Vì sao quan trọng
Đồng nhất	Người đọc đã biết tài liệu của một package thì biết tất cả. Không tốn chi phí tìm hiểu.
Súc tích	Bảng/biểu đồ thay cho văn xuôi. Một dev kỳ cựu phải định hướng được trong <2 phút.
Trực quan trước	Mermaid (erDiagram, stateDiagram-v2, flowchart, sequenceDiagram, C4Container) + bảng. Văn xuôi chỉ khi không có biểu đồ nào phù hợp.
Diátaxis sạch	Một góc phần tư trên một trang (reference / explanation / how-to / tutorial). Không trộn lẫn.
Spec là nguồn	API reference được kết xuất từ /doc/openapi.json, không viết tay.
Vận hành cùng chỗ	Tài liệu vận hành + runbook theo từng package (you-build-it-you-run-it).

2. Cấu trúc Thư mục

content/{en,vi}/developer/packages/<service-name>/
├── index.md              # ⓜ Identity card + service catalog
├── architecture.md       # ⓜ C4 + state machines + runtime scenarios
├── domain-model.md       # ⓜ ERD + entity tables
├── api-events.md         # ⓜ Kafka + WS topics in/out + payloads
├── integration.md        # ⓜ Sister-service + external-system contracts
├── configuration.md      # ⓜ Env vars + flags + seeded data
├── operations.md         # ⓜ Deploy + observability + security + runbook
├── <feature>.md ...      # ⊕ Optional per-feature deep dive
├── decisions/
│   ├── index.md          # ⓜ ADR catalogue
│   └── NNNN-<slug>.md    # ⓜ MADR - one per decision
└── changelog.md          # ⊕ Optional, only if stable contract

ⓜ bắt buộc · ⊕ tùy chọn

Không có api-rest.md - REST reference được kết xuất trực tiếp từ /doc/openapi.json của mỗi service (Scalar viewer tại /doc, gateway portal explorer). Bảng REST viết tay nhanh chóng lệch khỏi mã nguồn. Thay vào đó hãy liên kết tới spec trực tiếp từ index.md.

3. Bản đồ Góc phần tư Diátaxis

Trang	Góc phần tư	Đối tượng
index.md	Reference (identity card)	Dev mới onboarding, integrator
architecture.md	Explanation	Dev kỳ cựu, SRE, kiến trúc sư
domain-model.md	Reference	Người triển khai
/doc/openapi.json trực tiếp	Reference	API consumer
api-events.md	Reference	Bên đăng ký/phát sự kiện
integration.md	Explanation + reference	Dev nhóm liên quan
<feature>.md	Reference + chút explanation	Feature owner
configuration.md	Reference	Operator, deployer
operations.md	How-to + reference	SRE, on-call
decisions/NNNN.md	Explanation	Bất kỳ ai hỏi "tại sao?"
changelog.md	Reference	API consumer, integrator

Quy tắc: không bao giờ pha trộn các góc phần tư. Nếu một trang reference phát sinh phần "Vì sao chúng ta làm vậy" dài hơn 2 đoạn, hãy chuyển nó vào ADR và liên kết.

4. Quy tắc Tách File

Quy tắc	Ngưỡng
Tách chủ đề thành file riêng	≥150 dòng HOẶC ≥10 endpoint/sự kiện/bảng HOẶC ≥1 biểu đồ mermaid HOẶC được tham chiếu từ ≥1 trang khác
Nâng thư mục thành cây con	≥3 trang anh em cùng chủ đề
Đặt trực tiếp trong index.md	<40 dòng VÀ <5 mục
Một ADR mỗi file	Luôn - không gộp các quyết định
REST + Async luôn tách	Đối tượng khác nhau, cách kết xuất khác nhau

5. Mẫu Cho Từng Trang

Các file bộ khung nằm tại content/{en,vi}/developer/packages/_template/ (chỉ có trong source). Số lượng và thứ tự các phần là cố định.

index.md - 14 sections

Quick Reference · Purpose & Scope · Tech Stack · Project Structure · Architecture · Domain Snapshot · Surface Summary · Components · Services · Repositories · Entry Points · Configuration · Operations · Related Pages

architecture.md - 7 sections

System Context (C4 L1) · Container View (C4 L2) · Component View (C4 L3) · State Machines Index · Runtime Scenarios · Crosscutting Concerns · Related Pages

domain-model.md - 5 sections

Full ERD · Entities (mỗi bảng một block) · Cross-entity Invariants · Soft-delete Behavior · Related Pages

api-events.md - 8 sections

Inbound Kafka · Outbound Kafka · Inbound BullMQ · Outbound BullMQ · WebSocket Emissions · Payload Schemas · Idempotency & Ordering · Related Pages

integration.md - 5 sections

Sister Services · External Systems · Critical Cross-Service Flows · Contract Stability · Related Pages

configuration.md - 5 sections

Environment Variables · Feature Flags · Seeded Data · Configuration Storage · Related Pages

operations.md - 5 sections

Deployment · Observability · Security · Runbook · Related Pages

<feature>.md - 7 sections

Overview · Entity Model · Lifecycle · Operations · REST Endpoints · Events · Related Pages

decisions/index.md

Một bảng duy nhất: ID · Status · Date · Title · Supersedes.

decisions/NNNN-<slug>.md - MADR

Context · Decision · Consequences · Alternatives Considered · References.

6. Quy tắc Phong cách Viết

Quy tắc	Cách áp dụng
Trực quan trước	Bảng/mermaid cho mọi danh sách ≥3 mục. Văn xuôi chỉ khi không cái nào phù hợp.
Văn xuôi gọn	Tối đa 4 dòng mỗi đoạn. Ưu tiên gạch đầu dòng hơn đoạn văn khi có thể.
Frontmatter	Luôn có title, description, outline: deep.
Code block	Chỉ dùng cho: cây thư mục · ví dụ env · JSON payload · TS interface.
Liên kết chéo	Liên kết nội bộ dùng đường dẫn tuyệt đối /vi/developer/....
Chỉ tiếng Anh trong identifier	Tiếng Việt chỉ chấp nhận trong chuỗi i18n hướng người dùng.
Không emoji	Trừ khi nó là một phần của UI đang được mô tả.

7. Quy tắc ADR (MADR)

Quy tắc	Chi tiết
Đánh số	4 chữ số đệm 0, tuần tự, không bao giờ tái sử dụng
Giá trị status	Proposed · Accepted · Deprecated · Superseded by NNNN
Date	Ngày ra quyết định (không phải ngày tạo file)
Cập nhật	Chỉ thêm mới - thay thế bằng ADR mới; lật status của ADR cũ
ADR liên service	Nằm trong developer/decisions/, không đặt theo từng package
ADR riêng service	developer/packages/<svc>/decisions/

8. API Reference - Tích hợp OpenAPI

Khía cạnh	Quy ước
Nguồn chân lý	Mỗi service cung cấp /doc/openapi.json lúc runtime
Kết xuất trên wiki	Không có trang api-rest.md - bảng Surface Summary trong index.md liên kết thẳng tới spec trực tiếp
Khám phá trực tiếp	Gateway portal tại packages/gateway/portal đọc /doc/openapi.json và kết xuất UI tương tác
Reference viết tay	Cấm - không bao giờ trùng lặp schema cấp trường trong markdown

9. Tách Operations và Runbook

Phạm vi	Nằm ở
Triển khai, observability, bảo mật, các lớp cảnh báo riêng từng service	<svc>/operations.md
Sự cố liên service, quy trình toàn hệ thống, war-room playbook	Cây trung tâm runbook/
<svc>/operations.md liên kết sang runbook/ cho công việc liên service	Luôn

10. Song song EN ↔ VI

Quy tắc	Chi tiết
Mirror	Mỗi file EN có file VI tương ứng tại cùng đường dẫn
Số dòng tương đương	EN/VI chênh lệch trong ±5%
Thứ tự dịch	EN ra trước → VI theo sau theo lô
Nhãn mermaid	Dịch nhãn node; giữ tên state/event bằng tiếng Anh
Frontmatter title & description	Dịch
Tên code/identifier	Không bao giờ dịch

11. Quy ước Sidebar

Mục sidebar của mỗi package PHẢI lồng các trang con vào 3 nhóm Diátaxis + một liên kết Decisions, theo thứ tự sau:

Package Name
├─ Concepts          (collapsed by default)
│  ├─ Architecture
│  ├─ Domain Model
│  └─ Integration
├─ Reference         (collapsed)
│  ├─ API Events
│  ├─ Configuration
│  └─ Operations
├─ Features          (collapsed)
│  ├─ <feature-1>
│  ├─ <feature-2>
│  └─ ...
└─ Decisions

Quy tắc:

• Thứ tự nhóm: Concepts → Reference → Features → Decisions (luôn luôn).
• Mặc định gập lại - giữ sidebar ban đầu gọn (3 mục hiện + Decisions).
• Concepts gồm các trang giải thích vì sao/hệ thống được định hình như thế nào (architecture, domain, tích hợp liên service).
• Reference gồm các trang chỉ để tra cứu (REST endpoint, sự kiện, env var, ops/runbook).
• Features gồm các trang đi sâu theo từng feature (mỗi feature nghiệp vụ không tầm thường một trang).
• Decisions là một liên kết phẳng tới decisions/index.md; danh sách ADR được kết xuất bên trong trang đó.
• Nếu một nhóm không có trang nào (ví dụ service nhỏ không có trang feature), bỏ luôn nhóm đó thay vì hiển thị một phần rỗng.

Hình thức trong VitePress (.vitepress/locales/{en,vi}.ts):

{
  text: '<Service Name>',
  link: '/en/developer/packages/<svc>/',
  collapsed: true,
  items: [
    { text: 'Concepts', collapsed: true, items: [/* ... */] },
    { text: 'Reference', collapsed: true, items: [/* ... */] },
    { text: 'Features', collapsed: true, items: [/* ... */] },
    { text: 'Decisions', link: '/en/developer/packages/<svc>/decisions/' },
  ],
}

12. Khởi tạo một Package mới

# 1. Copy skeleton
cp -r content/en/developer/packages/_template \
      content/en/developer/packages/<svc>
cp -r content/vi/developer/packages/_template \
      content/vi/developer/packages/<svc>

# 2. Replace placeholders
#    <service-name>, <Service Name>, TODO:, <n>, <NNNNN>

# 3. Register in sidebar
#    .vitepress/locales/en.ts and vi.ts

Bước	Người chịu trách nhiệm
Sao chép bộ khung	Tác giả của package mới
Điền 8 file bắt buộc + decisions/index.md + ít nhất 1 ADR	Cùng người
Thêm trang theo từng feature khi feature được thêm	Feature owner
PR đăng ký sidebar	Tác giả
Duyệt code review	Người kiểm tra quy ước tài liệu (CI lint tùy chọn)

13. Anti-pattern (không được làm)

Anti-pattern	Vì sao không nên
Viết tay toàn bộ OpenAPI reference trong markdown	Lệch khỏi code mỗi PR - hãy liên kết tới /doc/openapi.json trực tiếp
Thêm api-rest.md vào package	Cấm - bề mặt REST chỉ nằm trong OpenAPI spec
Trộn reference + explanation trong cùng trang	Vi phạm Diátaxis; không quét được
File ADR gộp nhiều quyết định	Phá vỡ URL ổn định và việc thay thế
Tài liệu vận hành để trong wiki SRE riêng	Tách quyền sở hữu, phân rã nhanh
Sơ đồ C4 cấp Code	Mã nguồn là nguồn - sơ đồ sẽ mục nát
Đoạn văn dài (>4 dòng)	Vi phạm nguyên tắc trực quan trước
Identifier tiếng Việt trong code mẫu	Phá quy tắc chỉ-tiếng-Anh
Bỏ qua bộ khung _template/	Gây trôi cấu trúc

| Sidebar phẳng với 10+ mục cùng cấp | Khó quét; nhóm vào Concepts/Reference/Features theo §11 |

14. Liên quan

• Bộ khung _template/ - content/{en,vi}/developer/packages/_template/
• Diátaxis framework - https://diataxis.fr/
• arc42 template - https://arc42.org/overview
• C4 model - https://c4model.com/
• MADR (Markdown ADR) - https://adr.github.io/madr/