Giao diện
Triển khai chính tài liệu này
Tài liệu này là một app trong repo (code/apps/web-document), build ra web tĩnh và deploy như các app web khác.
Nội dung được sinh ra lúc nào
Hai thứ tách rời, và tách rời có lý do:
Vì sao commit nội dung sinh ra thay vì sinh lúc build:
- Pull request nào đổi API, quyền hay schema thì diff tài liệu hiện ra ngay trong review — người review thấy được tài liệu thay đổi thế nào.
- Bước đọc database cần PostgreSQL 17 chạy toàn bộ migration. Amplify không có DB, và không nên có.
- Build site không phụ thuộc DB nên deploy không bao giờ fail vì DB.
Đây đúng là quy ước repo đã dùng cho schema.graphql và generated.ts: file sinh ra được commit, và có gate chặn khi nó lệch source.
Gate chống lệch
bash
pnpm exec nx run web-document:docgen-checkLệnh này chạy lại mọi bộ sinh và fail nếu kết quả khác những gì đã commit. Thêm --skip-db để bỏ bước cần PostgreSQL — phần còn lại (API, quyền, module, số liệu, sidebar) vẫn kiểm được ở nơi không có DB.
Chạy tại máy
bash
# từ code/
pnpm exec nx run web-document:docgen # sinh lại nội dung từ source
pnpm exec nx serve web-document # http://localhost:5173
pnpm exec nx build web-document # -> .vitepress/distBước docgen phần database cần PostgreSQL 17 native ở 127.0.0.1:5433 và psql 17 trong PATH. Nó tạo một scratch DB riêng, chạy migration lên đó, đọc catalog rồi tự xoá scratch DB; nó không bao giờ chạm pideal_dev.
Nếu máy đang dùng chung với checkout khác, bước này đặt PI_SCRATCH_TEMPLATE=0 để không xoá template DB mà checkout khác đang dùng.
Deploy
Khai trong amplify.yml ở gốc repo, cùng mẫu với web-storybook và web-gitflow:
| appRoot | code/apps/web-document |
| build | pnpm -C ../.. --filter web-document build |
| artifacts | .vitepress/dist |
| Node | 20, pnpm 9.15.4 |
Bắt buộc bật Basic auth cho branch này trong Amplify console (Access control). Nội dung tài liệu mô tả toàn bộ cấu trúc hệ thống: tên bảng, tên cột, ma trận quyền, mã lỗi, đường dẫn. Không có giá trị secret nào trong đây — chỉ có tên biến môi trường — nhưng đây vẫn là tài liệu nội bộ.
Cấu trúc thư mục
| Đường dẫn | Nội dung | Commit? |
|---|---|---|
generated/ | Markdown do bộ sinh viết. Không sửa tay — lần docgen sau ghi đè | có |
public/db-graph.json | Dữ liệu sơ đồ, trang tương tác nạp lúc chạy | có |
data/db-introspect.json | Ảnh chụp schema thô, chỉ bộ sinh đọc | có |
.vitepress/sidebar.json | Mục lục sinh từ các trang có thật trên đĩa | có |
.vitepress/dist/ | Kết quả build | không |
| các thư mục khác | Trang viết tay | có |
Sidebar sinh ra chứ không viết tay, nên nó không bao giờ trỏ tới trang chưa tồn tại — và vì build bật ignoreDeadLinks: false, một link chết là build fail.
Bộ sinh
Nằm ở code/scripts/docgen/, chạy theo thứ tự phụ thuộc:
| Bước | Sinh ra gì |
|---|---|
db-introspect | Ảnh chụp schema cuối từ PostgreSQL (bước duy nhất cần DB) |
db-graph | Domain, nhóm con, cạnh khoá ngoại |
db-pages | Trang bảng, hàm SQL, kiểu dữ liệu |
api-pages | Tham chiếu API GraphQL theo domain |
module-pages | Trang module, kiểm đủ theo từng bảng |
ref-pages | Quyền, mã lỗi, route auth, đường dẫn client |
security-pages | Danh mục kiểm soát, RLS |
decision-pages | Sổ quyết định, nhật ký kiến trúc |
metrics | Số liệu hệ thống |
scope-pages | Phạm vi & độ tin cậy |
nav | Sidebar |
Chạy một bước: node scripts/docgen/index.mjs --only api-pages.