BAGA — Tài liệu yêu cầu & nghiệm thu
Control plane nghiệp vụ cho bagaofficial.com: yêu cầu, quy tắc, nghiệm thu, quyết định và kế hoạch triển khai — một cổng nhập liệu duy nhất trước khi code.
Site này là control plane nghiệp vụ của bagaofficial.com, dựng theo mẫu biz-docs đã kiểm chứng trong nội bộ RunLumi. Baseline nghiệp vụ hợp nhất nằm tại SOURCE-REQUIREMENTS.md (cùng thư mục); clarification/decision mới hơn luôn ưu tiên wording cũ khi có xung đột.
Trạng thái hiện tại: khung sườn đang chờ nhập liệu. Các register trong
data/mới chỉ có mục ví dụ đánh dấu[VÍ DỤ]— thay bằng input thật theo hướng dẫn trongpackages/biz-docs/README.md.
Cách dùng
| Vai trò | Bắt đầu từ | Dùng để |
|---|---|---|
| Chủ thương hiệu / Product | Quản lý dự án → Phạm vi → Quyết định | Chốt phạm vi, duyệt change request, theo dõi plan/trạng thái/rủi ro |
| Tech lead / Developer | FR → Trạng thái & quy tắc → NFR → Quyền | Nhận yêu cầu đã khóa và implement theo rule đã chốt |
| QA | Nghiệm thu → Hành trình → Truy vết | Chạy AC + negative paths theo release plan và lưu bằng chứng |
| Vận hành / CSKH | Hành trình → Quyền → Phụ thuộc | Xác nhận workflow vận hành và dependency deployment |
Quy ước
- Baseline: requirement nằm trong
SOURCE-REQUIREMENTS.md+ các registerdata/*.yamlở trạng thái đã chốt. - Decision mới hơn thắng: khi wording cũ mâu thuẫn decision mới, decision mới ưu tiên.
- Deferred / non-goal: không tự quay lại scope nếu chưa có change request/version mới.
- Deployment input: dữ liệu/config/credential thật cần seed trước pilot/release; khi chưa có, dev dùng fixture/mock/config placeholder an toàn — không giả lập thành công.
- Task trạng thái: cập nhật tại
data/project-progress.yaml; đổi deadline phải giữ deadline cũ + lý do trong note. - Sửa một register phải đồng bộ truy vết liên quan (FR ↔ AC ↔ D-xx) — xem Truy vết; không sửa bảng generated bằng tay.
Bản đồ tài liệu
| Trang | Nội dung |
|---|---|
| Tổng quan | Định vị, kênh, luồng nghiệp vụ cốt lõi |
| Quản lý dự án | Release roadmap, task owner/hạn chót/trạng thái, rủi ro, nhịp báo cáo |
| Hành trình nghiệp vụ | Luồng chính từng bước + negative paths bắt buộc |
| Phạm vi | Trong P0, non-goals, extension points |
| Yêu cầu chức năng | FR implementation-ready |
| Trạng thái & quy tắc | State machines + business rules (BR) |
| Yêu cầu phi chức năng | NFR: kiến trúc, bảo mật, độ tin cậy |
| Nghiệm thu | AC scenarios + readiness checklist |
| Quyền & phân quyền | Permission matrix |
| Đo lường | Operating metrics + golden datasets |
| Quyết định | Decision register |
| Truy vết | AC ↔ FR/NFR ↔ decision traceability |
| Phụ thuộc | Deployment inputs và fallback |
| Thư viện màn hình | Visual reference mobile/desktop per screen |
| Tài liệu nguồn | Tài liệu tham chiếu dùng trong dự án |
| Xuất PDF | Gộp toàn bộ site để in/lưu PDF |
Invariants bắt buộc của repo (trích AGENTS.md)
Các ranh giới dưới đây là điều kiện ràng buộc sẵn có của repo bagaofficial.com — trích nguyên văn mục Non-negotiable architecture trong AGENTS.md (toàn bộ danh sách nằm ở đó). Mọi requirement nhập vào control plane phải tương thích với chúng:
- “Browser code must never call Nhanh, and this repo holds no Nhanh client at all: commerce reads go through the BI storefront API via
packages/bi-client/(read-only — Nhanh writes happen only inside the BI platform).” - “Storefront reads come from the BI’s catalog projection via the storefront API — never per-page Nhanh calls.”
- “Secrets never enter git, HTML, client bundles, logs or analytics.”
- “Checkout totals, prices, inventory and eligibility are recalculated server-side.”
- “Demo checkout must never create a real order.”
- “Legacy URL redirects are part of migration correctness.”
- “Astro owns routing, SEO, content and server rendering. React is allowed only for interactive islands with meaningful client state.”
Khi thay behavior đã freeze: cập nhật đồng thời SOURCE-REQUIREMENTS.md, decision register, FR/NFR/BR/AC/state/exception và truy vết. Khi chỉ thay plan/deadline: cập nhật data/project.yaml + data/project-progress.yaml, không sửa requirement.