Khuyến mãi, Trả trước & Request Flows — Business Rules

Tổng quan

Nhóm này gom nhiều subdomain dễ bị viết lẫn vào nhau:

• prepaid order,
• refund / withdraw request,
• fund management,
• voucher campaign / activation / restore,
• negative payment request.

Chúng cùng nằm trong ecommerce nhưng không cùng data model.

Mounted vs Dormant

Subdomain	Trạng thái
prepaid-order	Mounted, dùng thật
withdraw/refund request	Mounted, có 2 cây route song song
fund-management	Mounted, dùng thật
negative-payment-requests	Mounted, approval flow riêng
promotion	Code + GraphQL + permission còn, nhưng route mount đang comment

Prepaid order

Vai trò

Prepaid order là luồng bán thẻ/gói trả trước, có commission, payment và logic nạp ví riêng.

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PR-001	Tạo prepaid order bắt buộc phải chọn prepaid card/gói hợp lệ.
BR-PR-002	Mỗi card phải có ít nhất 1 người nhận hoa hồng.
BR-PR-003	Tổng commission không được vượt giá trị card hoặc số thực nạp.
BR-PR-004	prepaid_value_into_wallet tính khác nhau giữa prepaid_type_card và prepaid_type_flexible.
BR-PR-005	Payment method wallet / wallet_promotion không sinh fund như các payment method khác.

Refund / Withdraw

Refund và withdraw chạy qua wallet.transaction_request, không phải bản chất là một cột trạng thái của order.

Behaviors chính

Behavior	Ý nghĩa
refund_order	Hoàn order dịch vụ
refund_order_cosmetic	Hoàn order mỹ phẩm
refund_topup	Hoàn topup ví
refund_collaborator	Chi / hoàn liên quan collaborator hoặc commission payout

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PR-006	Approve refund của order/cosmetic sẽ hủy các request refund khác cùng reference_id + branch_id.
BR-PR-007	refund_topup có thể split số tiền giữa VND và VND_PROMOTION.
BR-PR-008	Refund cash yêu cầu upload chứng từ.
BR-PR-009	Approve refund có thể kéo theo refund commission, rollback point và revenue qua event wallet.

Fund management

Fund management là màn hình tổng hợp và thao tác quỹ, đọc từ cả fund và invoice theo nhiều loại nguồn.

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PR-010	Fund filter riêng cho service, cosmetic, prepaid, wallet, wallet promotion, installment.
BR-PR-011	Fund không đại diện toàn bộ wallet flow; một phần logic hoàn/chi vẫn nằm ở transaction_request.

Voucher campaign / activation / restore

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PR-012	Approve voucher campaign chỉ cho trạng thái draft và campaign chưa hết hạn.
BR-PR-013	Khi approve, hệ thống generate trước voucher issued theo quota online/offline rồi mới publish.
BR-PR-014	Offline voucher activation kiểm tra published status, remaining quota, per-customer limit và race-check quota.
BR-PR-015	Cancel order có thể restore voucher về trạng thái dùng lại được, nhưng implementation hiện có dấu hiệu bất thường ở usage_count.

Negative payment

Đây là subdomain riêng, không nên gộp với refund.

Tạo negative payment
  -> tạo invoice âm (`negative=true`)
  -> tạo request approval trong `request_working_schedule`
  -> approval flow riêng
  -> side effects commission / invoice link / request link

Quy tắc nghiệp vụ

Mã	Quy tắc
BR-PR-016	Chỉ tạo negative payment khi order chưa paid_at và chưa có request pending.
BR-PR-017	Negative payment bám request_working_schedule, không bám transaction_request.
BR-PR-018	Với service/cosmetic, negative payment còn tính commission âm để trình duyệt.

Rủi ro / Findings

Mức	Mô tả
P1	Promotion đang ở trạng thái “nửa sống nửa chết”: code còn nhưng route bị comment.
P1	Refund/withdraw có 2 cây route song song cho cùng page set.
P1	canApproved ở refund/negative detail có dấu hiệu check approver sai theo created_by thay vì current user.
P1	RestoreVouchersOnOrderCancel tăng usage_count khi restore voucher, có mùi bug nghiệp vụ.
P2	WithdrawRequestCreate có fallback amount 40000000 nếu không đọc được balance.
P2	Nếu gộp negative payment vào refund docs sẽ sai boundary hệ thống.