Tài liệu cho người dựng FE #
Cho team CMS, team storefront và đội dev của khách. Bản đọc được gom ở repo
xforge-documentation (ADR-0102); NGUỒN là các file ở đây, sửa cùng PR với code
Core.
| Bạn dựng | Đọc |
|---|---|
CMS / admin của khách (nhân viên, /api/v1/*) | common.md → cms.md |
Storefront (người mua, /api/v1/storefront/*) | common.md → storefront.md |
| Màn hình của một module (thu tiền, giỏ, kho…) | FE.md của module đó (repo module, vd modules/foundation/payments/FE.md) |
Hợp đồng chi tiết từng endpoint (field, kiểu, quyền) nằm trong spec / SDK — tài liệu này nói thứ tự gọi và những chỗ dễ sai.
| Cần gì | Ở đâu |
|---|---|
| Tra endpoint | GET /docs (Swagger UI), GET /openapi.json; storefront: GET /storefront/openapi.json |
| Client có kiểu | sdk/api.ts (XforgeClient), sdk/storefront.ts (StorefrontClient), sdk/runtime.ts |
| Mã lỗi | ERROR_CODES, ErrorParams trong sdk/api.ts |
| Quyền | PERMISSIONS, OPERATION_PERMISSIONS (cùng file) |
| Menu | GET /api/v1/menu (listMenu) + sự kiện core.menu_changed (cms §3, §6); mọi key: sdk/menu.json / sdk/menu.md |
SDK sinh từ chính route của server (deno task sdk:gen) — lấy bản sdk/ cùng
phiên bản với server đang chạy, đừng sửa tay.
Viết tài liệu ở đây #
- Đổi hành vi FE thấy được (route, luồng phiên, sự kiện realtime, mã lỗi cần xử
lý, menu) → sửa file tương ứng CÙNG PR, kèm
CHANGELOG.md. - Người đọc ở NGOÀI repo (đội dev của khách): không nhắc app / API quản trị nền tảng (tài liệu của nó ở xforge-platform; bản dựng của xforge-documentation đỏ khi gặp), không bắt đọc ADR / file nội bộ mới hiểu được (ghi mã ADR để tra thì được).
- Luồng riêng của một module →
FE.mdcủa module, không thêm vào đây.