TODO (client input): các mục dưới đây là khung gợi ý sẵn có — điền nội dung thật từ SOURCE-REQUIREMENTS.md rồi xóa các blockquote TODO này.

1. Định vị

TODO: định vị dự án — BAGA là gì, phục vụ ai, mô hình vận hành.

2. Kênh và phạm vi

TODO: bảng kênh/nền tảng trong phạm vi hiện hành (storefront web, CMS, BI platform…) và phần ngoài phạm vi.

3. Luồng khách cốt lõi

TODO: tóm tắt end-to-end flow chính (browse → cart → checkout → …) ở mức tổng quan; chi tiết từng bước nằm ở Hành trình nghiệp vụ.

4. Quy tắc vận hành quan trọng

TODO: 4–8 điểm behavior quan trọng nhất mà mọi người phải nhớ (mỗi điểm 1–2 câu, chi tiết trỏ về FR/BR tương ứng).

5. Thuật ngữ chung

Trang này là bảng điều hành dự án. Requirement nằm ở FR/NFR/BR/AC; trang này chuyển requirement đã freeze thành kế hoạch thực thi, hạn chót, người phụ trách, release, tiến độ và báo cáo.

TODO (client input): điền data/project.yaml (releases, reporting, workstreams, tasks, risks) và cập nhật trạng thái thực tế ở data/project-progress.yaml. Hai file này tách biệt để không mất lịch sử kế hoạch.

Xem nhanh: Dự án trên 1 trang — bản cô đọng để theo dõi hằng ngày, họp nhanh hoặc in A4 ngang.

Planning baseline: Điền planning note khi roadmap được chốt với client.

Live progress · 26/09/2026: Overlay tiến độ thực tế sẽ được điền sau khi project.yaml có task thật. Trước đó không ghi trạng thái giả.

1. Release roadmap

2. Work plan

Mỗi task có một owner chính, deadline, status, progress, dependency, requirement reference và note. Baseline nằm ở project.yaml; live execution update nằm ở project-progress.yaml để giữ lịch sử kế hoạch ban đầu. Khi đổi deadline, giữ deadline cũ trong note để lịch sử báo cáo khách hàng không bị mất.

3. Nhịp báo cáo

4. Risk register

5. Mẫu báo cáo khách hàng

1. 1. Trạng thái tổng thể: Xanh / Vàng / Đỏ và lý do
2. 2. Tiến độ: Hoàn tất / Tổng số, theo release
3. 3. Đã hoàn tất từ báo cáo trước
4. 4. Đang thực hiện
5. 5. Kế hoạch kỳ tiếp theo
6. 6. Điểm chặn / quá hạn / rủi ro và người phụ trách
7. 7. Thay đổi phạm vi/change request mới
8. 8. Mục tiêu phát hành và độ tin cậy
9. 9. Link demo/bằng chứng

6. Quy ước status

Cách cập nhật hằng ngày

Project management tách baseline và live execution để không làm mất lịch sử kế hoạch:

• packages/biz-docs/data/project.yaml: kế hoạch baseline, người phụ trách theo role, start/hạn chót, dependency và note gốc;
• packages/biz-docs/data/project-progress.yaml: trạng thái thực tế, % tiến độ, ngày bắt đầu/cập nhật thực tế, ghi chú trực tiếp và bằng chứng.

Khi task bắt đầu hoặc có thay đổi thực tế, ưu tiên cập nhật project-progress.yaml. Nếu đổi hạn chót/baseline chính thức, cập nhật project.yaml đồng thời ghi hạn chót cũ + lý do trong note để báo cáo có lịch sử rõ ràng.

Trạng thái mỗi công việc đi theo một luồng duy nhất: To do → Doing → Ready for test → Done. Nếu QA/PM kiểm tra chưa đạt, công việc chuyển sang Bug/Rework, sửa xong phải quay lại Ready for test để kiểm tra lại. Done chỉ được dùng khi đã đạt tiêu chí chấp nhận, có bằng chứng và được người có thẩm quyền phê duyệt. Điểm chặn được ghi riêng trong note/risk, không dùng để bỏ qua bước kiểm tra.

Blocker quá một ngày làm việc phải được báo chặn ngay, không chờ báo cáo tuần.

Định nghĩa hoàn tất (Definition of Done) chung

Một task chỉ được coi là Done khi output đã merge/available ở môi trường phù hợp, acceptance/negative path cần thiết đã test, không làm yếu gate bảo mật/data-integrity, có bằng chứng đủ để người khác kiểm tra lại và QA/PM hoặc người duyệt được chỉ định đã phê duyệt. Với release, cần thêm bản ghi phát hành, lỗi đã biết, demo/UAT bằng chứng và trạng thái báo cáo khách hàng.

TODO (client input): điền data/journey.yaml (các bước luồng chính) và data/exceptions.yaml (negative paths). Khung hiển thị bên dưới tự sinh từ register.

1. Luồng chính

Ghi chú: các bước bị defer hoặc ngoại lệ (không bắt buộc).

2. Các tình huống ngoại lệ

Negative/error paths là phần của spec, không phải việc xử lý sau. Các tình huống dưới đây phải chứng minh hệ thống dừng/route đúng chỗ thay vì bypass identity, payment, approval hoặc audit gates:

3. Nguyên tắc khi gặp case chưa có dữ liệu thật

Nếu thiếu dữ liệu/config thật (deployment input), dùng fixture/mock để build/test nhưng không thay behavior đã freeze. Nếu case mới làm thay đổi business rule hoặc thuộc non-goals, tạo change request/version mới.

TODO (client input): điền 3 danh sách dưới đây và register data/features.yaml. Feature nằm ngoài cột P0 chỉ quay lại bằng change request/version mới.

Ranh giới P0

Trong P0:

• TODO: capability 1
• TODO: capability 2

Ngoài P0 / chỉ quay lại bằng change request:

• TODO: non-goal 1
• TODO: non-goal 2

Kiến trúc phải giữ đường mở:

• TODO: extension point bắt buộc (đọc thêm infra/docs/ARCHITECTURE.md của repo để khớp topology hiện hành).

Ghi chú chung về nguyên tắc scope (ví dụ: feature ngoài cột P0 không tự quay lại).

Không còn câu hỏi business chặn development

data/decisions.yaml là baseline hiện hành. Giá trị thật cần nhập trước pilot/release (catalog, giá, VAT, credentials…) là deployment data/config, không phải câu hỏi thiết kế phải quay lại hỏi client.

Nếu phát sinh yêu cầu khác behavior đã freeze, tạo change request/version mới thay vì tự mở rộng phạm vi.

FR là functional baseline của dự án. dec trỏ tới decision register để truy vết rationale/policy; status Cần chốt nghĩa là yêu cầu chưa đủ rõ để code — phải chốt decision trước khi đưa vào sprint.

Trạng thái thường gặp (đặt tên thống nhất khi nhập liệu):

• Cần chốt: chưa đủ chi tiết để code/nghiệm thu — đang chờ decision.
• Baseline: đã khóa, có đủ truy vết (AC + decision).
• Deferred: ngoài phạm vi hiện hành, chỉ quay lại qua change request/version mới.

Nhóm FR được khai trong data/fr.yaml (groups[]); mỗi FR nên có ít nhất một AC phủ và các decision liên quan.

Bảng mã

Danh sách yêu cầu

1. Các trục trạng thái

Mỗi thực thể có vòng đời riêng nên tách state machine theo trục (account, cart, order, payment, shipment, content, …) thay vì một cột status cố gánh mọi sự kiện. Register: data/states.yaml.

Ghi chú chung về state machine (ví dụ: chuyển state bằng API/server rule và audit ở action nhạy cảm).

Các transition nhạy cảm phải fail-closed:

• chuyển state bằng API/server rule, không dựa vào ẩn nút UI;
• action nhạy cảm phải audit actor/time/action/target/reason;
• state không được tự sinh từ hệ thống ngoài khi chưa có integration được chốt.

2. Business rules (BR)

Các rule dưới đây là invariant triển khai, không phải gợi ý UI. Register: data/br.yaml.

3. Negative-path bắt buộc

• TODO: negative path 1
• TODO: negative path 2

NFR chia làm hai loại khi nhập liệu (data/nfr.yaml):

• NFR nghiệp vụ đã chốt: product/runtime boundaries, security baseline, data/reliability baseline — status “Baseline” sau khi decision liên quan đã chốt.
• Technical baseline: performance/monitoring/backup thresholds do team đặt/test theo dataset thực tế và lưu runbook/bằng chứng; không cần client chốt formal SLA/RPO/RTO để bắt đầu build.

Ranh giới phải giữ khi implementation và security review:

• Không auto purge dữ liệu business — soft-delete mặc định, hard purge là action riêng có confirmation/audit (nếu client chốt policy như vậy).
• Secrets never enter git, HTML, client bundles, logs or analytics (invariant AGENTS.md).
• Deployment inputs (credentials thật) phải seed trước pilot/release, nhưng không thay behavior nghiệp vụ.

NFR baseline của dự án. Ngưỡng thuần kỹ thuật (performance, monitoring, backup) do team đặt/test và lưu runbook; behavior nghiệp vụ thì phải qua decision.

1. Nguyên tắc nghiệm thu

Mỗi mốc pass bằng bằng chứng bám FR/NFR/AC hiện hành. Không dùng wording cũ đã defer hoặc non-goal làm điểm chặn. Decision còn status “Mở” là điểm chặn nghiệm thu của AC liên quan.

2. Kịch bản nghiệm thu (AC)

Register: data/ac.yaml. Mỗi AC gồm scenario, expected behavior đầy đủ (gồm negative paths) và các bước kiểm thử có thể lặp lại.

AC là acceptance baseline của dự án. Chưa AC nào được coi là đã chốt khi còn phụ thuộc decision D-xx đang Mở.

3. Readiness checklist trước release

• TODO: mọi AC đã pass có bằng chứng.
• TODO: permission matrix + audit test pass.
• TODO: backup/restore drill có bằng chứng.
• TODO: deployment inputs (config/credentials) đã seed cho môi trường release.

4. Deployment inputs không phải điểm chặn code

Thiếu giá trị thật (config/credentials/dữ liệu seed) có thể chặn release tương ứng, nhưng không phải lý do thay đổi domain behavior hay quay lại hỏi lại spec.

1. Chỉ số baseline

Register: data/metrics.yaml. Mỗi metric phải có nguồn dữ liệu, window/timezone và cách xử lý retry/refund/adjustment — không biến thiếu dữ liệu manual thành dữ liệu tự động giả.

2. Golden datasets cần chuẩn bị

• TODO: dataset 1 (phủ case gì, bao nhiêu case, ai duyệt).
• TODO: dataset 2.

3. Không dùng deferred/non-goal metric làm điểm chặn

Không yêu cầu metric cho integration/phạm vi đã defer làm điều kiện nghiệm thu của release hiện hành.

1. Nguyên tắc

Matrix này là implementation baseline. Các invariant mặc định (điều chỉnh theo client input):

1. Authorization kiểm tại API/server, không dựa vào việc ẩn nút UI.
2. Vai trò gate (duyệt/phê duyệt) chỉ do role được gán thực hiện; admin quản lý assignment nhưng không tự có quyền gate nếu chưa được gán.
3. Action nhạy cảm phải audit actor/time/action/mục tiêu/reason và before-after khi phù hợp.
4. Guest (chưa xác thực) là trạng thái, không phải role.
5. Thay đổi matrix sau khi freeze phải version và regression-test RBAC.

2. Ký hiệu

• Own: chỉ dữ liệu của account.
• R: read.
• RW: read/write theo state rule.
• A: approval/gate action.
• Admin: quản trị cấu hình/quyền.
• Request: gửi yêu cầu, không tự thực thi.
• —: không có quyền mặc định.

3. Permission matrix

Decision register này là source of truth cho behavior đã khóa (data/decisions.yaml). Sau khi chốt, team implement mà không quay lại hỏi; thay đổi behavior đã khóa phải qua change request/version mới.

Quy ước ID

• Mỗi decision một mã D-xx duy nhất; không tái sử dụng mã đã bỏ — giữ ID lịch sử để bảo toàn truy vết.
• Status: Mở (đang chờ — điểm chặn nghiệm thu của yêu cầu liên quan), Đã chốt (baseline hiện hành), Deferred (cố ý hoãn).
• Giá trị cấu hình thật (dữ liệu, giá, VAT, credentials…) là deployment data, không phải decision — không tạo decision card cho chúng.

Nguyên tắc khi code

1. Không hỏi lại client về behavior đã có trong decision register (status Đã chốt).
2. Nếu thiếu deployment value, dùng fixture/config default để build và để client nhập dữ liệu thật trước release.
3. Nếu chi tiết thuần kỹ thuật không đổi behavior nghiệp vụ, tech lead được chọn phương án an toàn, đơn giản, testable và ghi trong ADR/runbook khi cần.
4. Nếu yêu cầu mới mâu thuẫn freeze hoặc thuộc non-goals, tạo change request/version mới.

Decision register của dự án. Mục status 'Mở' là điểm chặn nghiệm thu; 'Đã chốt' là baseline hiện hành. Giá trị cấu hình thật (catalog, giá, VAT…) là deployment data, không phải decision.

Mỗi quyết định được chốt cần ghi ngày, người quyết định, nội dung, lý do, yêu cầu bị ảnh hưởng và phiên bản chính sách. Thay đổi sau đó cần đánh giá ảnh hưởng đến đơn đang xử lý trước khi áp dụng.

Dùng trang này để kiểm tra độ phủ: không có kịch bản nghiệm thu nào thiếu yêu cầu bảo trợ, và mỗi quyết định chốt phải được đánh giá tác động tới đúng tập yêu cầu liệt kê.

Ma trận sinh tự động từ register data/ (trường ac/dec/impacts) — không sửa bảng generated bằng tay; sửa register gốc.

Kịch bản nghiệm thu → Yêu cầu chức năng

Quyết định → Yêu cầu bị ảnh hưởng

Phủ nghiệm thu: 1/1 FR được gắn với ít nhất một kịch bản AC. Các FR còn lại (nếu có) được kiểm qua kịch bản tổng hợp AC-01 hoặc kiểm thử riêng theo gợi ý ở từng thẻ FR.

Ghi chú chung về phân loại dependency (runtime integration / manual tool / deployment config / technical baseline).

Phân loại dependency

1. Runtime integrations: dịch vụ ngoài đang được chốt (ví dụ email delivery, thanh toán nếu có). Provider cụ thể là technical/deployment choice; failure behavior phải được chốt trong decision.
2. External tool dùng thủ công: tool chạy ngoài hệ thống; hệ thống chỉ lưu dữ liệu nhập tay, không gọi API ngầm.
3. Deployment configuration: dữ liệu/config/credentials thật cần seed trước release (catalog, giá, VAT, domain, DNS…).
4. Technical baseline: monitoring, backup/restore, performance — tech team tự đặt threshold thực dụng và lưu runbook/bằng chứng.

Khi thiếu deployment input thật, team dùng fixture/mock/config placeholder an toàn và giữ publish/release gate phù hợp — không giả lập thành công trong môi trường thật.

Ranh giới kiến trúc hiện hành của repo

Topology, rendering tiers, cache và data flow hiện hành là authority của infra/docs/ARCHITECTURE.md (prod) và infra/docs/ARCHITECTURE_LOCAL.md (local); dependency thay đổi topology phải cập nhật hai tài liệu đó theo quy tắc docs-mandatory trong AGENTS.md — trang này chỉ liệt kê dependency nghiệp vụ.

Thư viện này dùng để trao đổi nhanh giữa product, design và engineering. Mỗi trang hiển thị hai phiên bản của cùng một screen; prompt gốc trong screens/<folder>/ vẫn là nguồn tham chiếu để triển khai và kiểm tra lại.

• Mobile: tham chiếu web responsive dưới 768px (breakpoint đầu tiên của storefront), vùng chạm và hành trình một tay.
• Desktop: tham chiếu web responsive, shell, density và hierarchy (breakpoint 1068px).
• Behavior: không suy diễn từ hình ảnh; frozen requirements, server state và acceptance criteria vẫn là nguồn quyết định.

TODO (client input / capture): tạo thư mục screens/<tên-screen>/ với desktop.png, mobile.png, desktop-visual-prompt.md, mobile-visual-prompt.md — xem screens/README.md để biết contract đầy đủ. Trang screen tự xuất hiện trong thư viện khi thư mục có content front matter folder.

Trang này tập hợp các tài liệu nguồn dùng để tham chiếu trong quá trình triển khai. Chúng bổ sung ngữ cảnh cho team và không thay thế source of truth về requirement, decision và acceptance trong các trang còn lại.

TODO (client input): đặt tài liệu thật vào packages/biz-docs/static/reference/ rồi thêm mục dưới đây với link tương đối ../reference/<file>. Link tương đối để file được serve kèm site..

TODO: Tên tài liệu 1

Mở hoặc tải tài liệu — mô tả ngắn: tài liệu gồm gì, dùng khi nào, phiên bản/ngày.

TODO: Tên tài liệu 2

Mở hoặc tải tài liệu — mô tả ngắn.