v1.6 — 15/05/2026 (đồng bộ với PRD v1.8)

Thay đổi	Section	Ảnh hưởng
Update status badge sau khi chốt DEC-027/028/029 + 4 lint clean (vietnamese / interaction / matrix / glossary đều PASS); 94 ca kiểm thử	Header	All
Lint vietnamese clean: chuẩn hoá calque headings sang "Quy ước ..."	Đầu vào chuẩn	None

Tóm tắt quyết định (Decision Brief) - Ví KM 2 (Promotion Wallet 2)

Phiên bản: 1.6 Ngày: 15/05/2026 Độ phức tạp: L Module: wallet, ecommerce, settings, user, report Trạng thái package: Sẵn sàng bàn giao — đã chốt DEC-027 (lot lifecycle không có pending), DEC-028 (schema wallet_km2_payment_attempt merge), DEC-029 (balance realtime qua action get_customer_km2_balance) ngày 15/05/2026 sau review đa góc nhìn Phase 5; 4 lint clean (vietnamese / interaction / matrix / glossary đều PASS); 94 ca kiểm thử trong qa-test-plan, có TG-001..TG-007 evidence checklist; G3.7 cổng kiểm tra độ đầy đủ UI pass

---

File này dùng để làm gì: đây là cửa vào của package Ví KM 2. PO, Sếp, Tech Lead và nhóm delivery đọc file này trước để nắm phạm vi, quyết định, ảnh hưởng, rủi ro và nên đọc file nào tiếp theo.

Quy tắc ưu tiên: nếu brief này xung đột với SOURCE_OF_TRUTH.md, ưu tiên SOURCE_OF_TRUTH.md. Brief chỉ tóm tắt và trỏ sang file chịu trách nhiệm, không trùng API, SQL, ca kiểm thử hoặc toàn bộ Nhật ký quyết định.

Đầu vào chuẩn (Canonical Inputs)

File	Vai trò
SOURCE_OF_TRUTH.md	Nguồn sự thật chuẩn và khóa giải pháp
EVIDENCE_PACK.md	Bằng chứng code/screen/db/config thật
prd.md	Quy ước nghiệp vụ, DEC, FR/AC, công thức
ui-spec.md	Quy ước màn hình, delta UI, state và copy
dev-spec.md	Quy ước data/API/migration/security/tasks
qa-test-plan.md	Oracle kiểm thử và traceability
go-live-checklist.md	Readiness, deploy order, rollback và monitoring
handoff.md	RACI, timeline, điểm còn mở và thứ tự giao việc

1) Tóm tắt 5 phút

• Ví KM 2 là ví khuyến mãi theo cơ chế gói nạp ưu đãi (Gói Ví KM2): khách mua gói giá nhỏ, nhận giá trị ví lớn hơn, và mỗi đơn chỉ được dùng tối đa theo % cấu hình trên phần sản phẩm/dịch vụ đủ điều kiện.
• Package khóa phương án tách wallet type riêng VND_PROMOTION_2, không overload VND_PROMOTION của KM1, để tránh sai nghĩa báo cáo, fund, print và customer revenue.
• Day-1 reuse shell đang có: Settings PromotionWallet, master data prepaid_card, flow bán thẻ trả trước, payment order, customer detail và prepaid report shell.
• Phần build mới nằm ở engine bản ghi theo từng lần mua: wallet_km2_lot, wallet_km2_lot_deduction, FIFO deduction bằng Go action có transaction lock và expiry scheduler; riêng Hoàn ví KM2 reuse luồng Yêu cầu hoàn tiền hiện có với behavior refund_km2_wallet.
• Biên ảnh hưởng đã được khóa: các flow thanh toán, hoàn tiền, hoá đơn, quỹ, report, notification và permission phải tách KM1/KM2; rank, appointment, kho, CRM assignment, affiliate/referral, CMS gift/event và HR cơ bản không mở scope nghiệp vụ mới.
• Do liên quan tiền/ví/report/fund, package được nâng lên profile L để có go-live-checklist.md, rollback và monitoring trước khi bàn giao dev.
• Migration seed KM2 ở trạng thái tắt (disabled=true); PO/Admin chỉ bật trong go-live sau khi readiness pass. Quyền dùng Dynamic Permission v2 (role_module.actions + portal + branch_mode + backend enforcement); bản ghi lần mua (lot) luôn đọc qua action có kiểm tra quyền khách/branch, không đọc trực tiếp toàn bộ lot qua GraphQL.

2) Bản đồ package

File	Đọc khi cần	Phụ trách nội dung
SOURCE_OF_TRUTH.md	Đối chiếu nguồn sự thật chuẩn / conflict	PO/BA + TL
EVIDENCE_PACK.md	Xem bằng chứng code/screen/db/config	PO/BA + TL
prd.md	Duyệt phạm vi nghiệp vụ, DEC, FR/AC, công thức	PO/BA
ui-spec.md	Thiết kế/triển khai màn hình, thay đổi, tương tác	UI/UX + FE
dev-spec.md	Triển khai data/API/migration/security/tasks	TL + FE/BE
qa-test-plan.md	Viết/rà test oracle và regression	QA
go-live-checklist.md	Release gates, rollback, monitoring	Ops + TL
handoff.md	RACI, timeline, blocker, thứ tự việc	Delivery + TL

3) Khóa phạm vi

Trong phạm vi

#	Nội dung	Tham chiếu
1	Cấu hình KM2 global-first: bật/tắt, max%, cho phép KM1+KM2, chính sách Hoàn ví KM2	prd.md FR-001
2	Mở rộng prepaid_card thành loại Gói Ví KM2 bằng wallet_target và expiry_months	prd.md FR-002
3	Bán Gói Ví KM2 qua flow thẻ trả trước, tạo bản ghi wallet_km2_lot theo số lượng và snapshot giá mua gói	prd.md FR-003
4	Thanh toán bằng KM2 theo max%, FIFO và audit deduction	prd.md FR-004
5	Flag eligible riêng allow_promo_wallet_2 cho product/service	prd.md FR-005
6	Customer profile hiện tổng số dư, danh sách Gói Ví KM2 đã mua, cảnh báo hết hạn và Hoàn ví KM2	prd.md FR-006, FR-009
7	Expiry scheduler, report/fund/print impact và QA regression cho các flow đang chạy	dev-spec.md, qa-test-plan.md

Ngoài phạm vi

#	Không làm trong phase này	Lý do	Ref
1	Branch-specific config UI hoàn chỉnh	Day-1 dùng global-first để bám pattern settings hiện tại	SOURCE_OF_TRUTH.md
2	Bulk enable KM2 hàng loạt product/service	Chưa có evidence về bulk UI/pipeline phù hợp	SOURCE_OF_TRUTH.md
3	Customer app tự mua Gói Ví KM2	Không thuộc rollout POS/Admin	SOURCE_OF_TRUTH.md
4	Hợp nhất KM1/KM2 thành một lớp analytics mới	Rủi ro phá semantics báo cáo hiện tại	SOURCE_OF_TRUTH.md

4) Quyết định đã khóa

Quyết định	Ý nghĩa bàn giao	Tham chiếu
Tách wallet type VND_PROMOTION_2	Giảm regression KM1 và giữ báo cáo/fund/print rõ nghĩa	prd.md DEC-001
Reuse shell hiện có, không tạo module lạ	FE/UX phải extend màn hình đang chạy thay vì vẽ flow rời	SOURCE_OF_TRUTH.md DEC-002
Config v1 global-first	Migration seed config tắt; sau go-live chỉ có đúng một config global active; branch override để phase sau	SOURCE_OF_TRUTH.md DEC-005, DEC-023
FIFO deduction dùng Go transaction + idempotency	Bảo vệ tiền ví khi double submit, race condition, retry lỗi	dev-spec.md C3/C5
Expired lot không được deduct dù scheduler miss	Payment action phải check expired_at khi trừ tiền	dev-spec.md C3
Cross-branch usage không mở rộng visibility	Khách có thể dùng Gói Ví KM2 khác chi nhánh qua Go action, nhưng UI/API chỉ trả dữ liệu theo Dynamic Permission v2 và phạm vi khách/branch	SOURCE_OF_TRUTH.md DEC-014, DEC-024, DEC-025; dev-spec.md C8
Hoàn ví KM2 reuse Yêu cầu hoàn tiền	Không tạo approval module riêng; thêm behavior refund_km2_wallet, label "Hoàn ví KM2" vào request engine hiện có	SOURCE_OF_TRUTH.md DEC-026; prd.md FR-009
Impact boundary là contract bàn giao	Team phải list rõ feature nào ảnh hưởng, thêm gì, và feature nào không mở scope; QA có TC-IMPACT-* để chặn gộp nhầm KM1/KM2	SOURCE_OF_TRUTH.md mục 5.2-5.3; qa-test-plan.md
ZNS là optional Phase 2+ trừ khi PO chốt bắt buộc	Go-live Phase 1 không bị block bởi template ZNS nếu FR-011 chưa enable	SOURCE_OF_TRUTH.md

5) Bản đồ ảnh hưởng

Khu vực	Reuse / Extend / Build mới	Điều team cần chú ý	Tham chiếu
UI	Reuse + Extend	Settings, PrepaidCard, PrepaidOrder, CustomerDetail, Report shell	ui-spec.md
Backend / API	Extend + Build mới	payment_order, transaction_insert, deduct_km2_payment, refund_km2_wallet, scheduler	dev-spec.md
Database / Hasura	Extend + Build mới	3 table wallet mới, 3 alter ecommerce, permissions, cron/action metadata	dev-spec.md
Notification / Export	Extend	ZNS optional; export/report/fund phải tách KM2 semantics	ui-spec.md, dev-spec.md
QA / Regression	Full regression	Payment, fund, print, report, customer revenue, race condition	qa-test-plan.md

6) Rủi ro và blocker

Mức	Rủi ro / blocker	Phụ trách	Cách xử lý	Tham chiếu
Cao	Sai tiền ví khi retry/double submit payment	TL + BE	Idempotency key + transaction lock + post-deploy monitoring	dev-spec.md, go-live-checklist.md
Cao	Báo cáo/fund/print nhập nhằng KM1/KM2	TL + BE + QA	Tách field/semantics, grep hardcode, QA regression FR-012	dev-spec.md, qa-test-plan.md
Cao	Lộ dữ liệu lot/deduction nếu role user được direct select toàn bảng	TL + BE + QA	Không cấp RLS direct select cho user; dùng get_customer_km2_lots có access check	dev-spec.md, qa-test-plan.md
Cao	Quyền KM2 bị hard-code theo role, không theo Dynamic Permission v2	TL + FE + BE + QA	Seed/mapping module_permission_action + role_module.actions, test grant/revoke/portal split/API no-leak	SOURCE_OF_TRUTH.md, dev-spec.md, qa-test-plan.md
Trung bình	Lot quá hạn vẫn bị trừ nếu scheduler miss	BE	Payment action guard expired_at > NOW() + scheduler alert	dev-spec.md
Trung bình	Vị trí report dashboard chưa chốt	PO	Chốt trước Phase 3; không block Phase 1/2	handoff.md
Thấp	ZNS template chưa đăng ký	Ops	Chỉ block nếu PO bật FR-011 trong rollout	go-live-checklist.md

Cập nhật sau review kỹ thuật 28/04/2026: package đủ để kickoff Phase 1/2, nhưng team phải dùng bộ TG-001..TG-007 trong handoff.md làm gate trước merge/UAT. Các gate này khóa 7 điểm rủi ro còn lại: Hoàn ví KM2 trong Yêu cầu hoàn tiền, hard-code KM1/KM2, FIFO/idempotency/expiry, DB/Hasura/codegen, Dynamic Permission v2, scheduler/rollback/monitoring và impact boundary regression.

7) Tóm tắt bàn giao

Nhóm	Việc chính	File cần đọc
PO/BA	Chốt phạm vi, DEC, công thức, PD-001	decision-brief.md, prd.md
UI/UX	Chốt delta UI trên màn hình hiện có và copy/state	ui-spec.md
FE	Triển khai settings, prepaid, payment, customer, report UI	ui-spec.md, dev-spec.md
BE	Triển khai migrations, action, scheduler, report/fund contracts	dev-spec.md
QA	Test FR/AC và regression tiền/ví/report	qa-test-plan.md
TL/Ops	Chốt deploy order, rollback, monitoring, sign-off	go-live-checklist.md, handoff.md

8) Điểm còn mở

ID	Câu hỏi còn mở	Phụ trách	Hạn chót	Nếu chưa chốt thì ảnh hưởng
PD-001	Report KM2 đặt trong group/menu nào	PO	Trước Phase 3	Không block Phase 1/2, chỉ block report dashboard