Skip to content

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:

commitPRdeploymáy devcó PostgreSQL 17docgen11 bộ sinhGitnội dung sinh ra được commitgenerated/*.mdpublic/*.jsonquality gatedocgen --check · buildAmplifychỉ build, không docgenweb tĩnh+ Basic authBước đọc database cần PostgreSQL — chỉ chạy ở máy dev.Amplify không có DB và không cần: nội dung đã commit.PR nào đổi API/quyền/schema thì diff tài liệu hiện ra trong review.

Vì sao commit nội dung sinh ra thay vì sinh lúc build:

  1. 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.
  2. 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ó.
  3. 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-check

Lệ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/dist

Bướ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:

appRootcode/apps/web-document
buildpnpm -C ../.. --filter web-document build
artifacts.vitepress/dist
Node20, 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ẫnNội dungCommit?
generated/Markdown do bộ sinh viết. Không sửa tay — lần docgen sau ghi đècó
public/db-graph.jsonDữ liệu sơ đồ, trang tương tác nạp lúc chạycó
data/db-introspect.jsonẢnh chụp schema thô, chỉ bộ sinh đọccó
.vitepress/sidebar.jsonMục lục sinh từ các trang có thật trên đĩacó
.vitepress/dist/Kết quả buildkhông
các thư mục khácTrang viết taycó

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ướcSinh ra gì
db-introspectẢnh chụp schema cuối từ PostgreSQL (bước duy nhất cần DB)
db-graphDomain, nhóm con, cạnh khoá ngoại
db-pagesTrang bảng, hàm SQL, kiểu dữ liệu
api-pagesTham chiếu API GraphQL theo domain
module-pagesTrang module, kiểm đủ theo từng bảng
ref-pagesQuyền, mã lỗi, route auth, đường dẫn client
security-pagesDanh mục kiểm soát, RLS
decision-pagesSổ quyết định, nhật ký kiến trúc
metricsSố liệu hệ thống
scope-pagesPhạm vi & độ tin cậy
navSidebar

Chạy một bước: node scripts/docgen/index.mjs --only api-pages.

Sinh từ ad83b0aea · 820 migration · PostgreSQL 17