Shared Rules — Affiliate Approval And Payout

1. Thuật ngữ chuẩn

Thuật ngữ	Nghĩa trong hệ thống
Affiliate user	Hồ sơ CTV ở bảng affiliate_user; có thể pending hoặc active
Approval queue	Các affiliate_user có is_active = false đang chờ duyệt hoặc đang bị revoke
Order affiliate	Commission record gắn với order; chưa phải payout cuối
Invoice affiliate	Commission record gắn với invoice/payment; là bước ngay trước materialization vào wallet
Withdraw request	Yêu cầu rút commission từ ví, lưu ở transaction_request với behavior_id = refund_collaborator

2. State Matrix

2.1 affiliate_user

State	Dấu hiệu DB	Ý nghĩa
Pending / inactive	is_active = false, approved_at = null	Chưa có quyền CTV hoặc đã bị thu hồi
Active	is_active = true, approved_at != null	Đã được duyệt và có thể tích lũy commission

2.2 order_affiliate

State	Dấu hiệu DB	Ý nghĩa
Pending	is_approved = false, rejected = false	Chờ duyệt hoa hồng cấp order
Approved	is_approved = true, rejected = false	Đã duyệt order commission
Rejected	rejected = true	Bị từ chối ở cấp order
Cancelled approval	is_approved = false, approved_at = null	Hoàn tác duyệt order, chỉ hợp lệ khi chưa có invoice approved

2.3 invoice_affiliate

State	Dấu hiệu DB	Ý nghĩa
Pending	is_approved = false, rejected = false	Chờ duyệt payout cấp invoice
Approved	is_approved = true, approved_at != null	Commission đã được materialize sang wallet
Rejected	rejected = true	Bị từ chối ở cấp invoice

3. Action Matrix

Reference type	Action	Kết quả chính
user	approve	Active affiliate, bind/create account, set tag, ghi log
user	revoke	Deactivate affiliate, clear approved_at, ghi log
order	approve	Set is_approved = true, approved_at = now
order	cancel	Hoàn tác approve order nếu chưa có invoice approved
order	reject / unreject	Toggle rejected
invoice	approve	Set approved fields, update transaction request sang success, add commission
invoice	reject / unreject	Toggle rejected

4. Invariants

1. Không thể approve user nếu thiếu tag_id.
2. Không thể cancel order_affiliate nếu có bất kỳ invoice_affiliate nào đã approved.
3. Không có nhánh cancel approved invoice trong action engine; invoice chỉ approve/reject/unreject.
4. Không thể đổi wallet type nhận commission nếu đã có invoice approved trong order đó.
5. Không thể sửa commission percent của invoice/order nếu invoice target đã approved; action chỉ update pending path.

5. Cross-Module Boundary Rules

Boundary	Rule
affiliate -> user	Approve CTV có thể create customer account mới và cập nhật account tag
affiliate -> wallet	Invoice approval credit commission; withdraw tạo transaction_request riêng
affiliate -> report	Report đọc aggregate/view/function từ cùng family data nhưng không phải source-of-truth để mutate
affiliate -> settings	useRefreshSettings được gọi ở order pages để lấy config commission/wallet validity mới nhất

6. Những điều dễ hiểu nhầm

6.1 "Payment" trong affiliate không phải luôn là tiền đã rút

PaymentList trong affiliate đang hiển thị invoice_affiliate. Đây là trạng thái commission cấp invoice, không phải lịch sử tiền đã rút khỏi ví.

6.2 Approve affiliate không luôn đi qua approval queue

Staff có thể tạo CTV mới bằng ListCreate và path đó gọi affiliateUserRegistration theo role user, dẫn tới record active ngay sau create nếu tag hợp lệ.

6.3 Wallet balance không suy ra trực tiếp từ invoice_affiliate

Balance đang đọc wallet_balance / wallet_stats; invoice_affiliate chỉ là upstream business record. Nguồn số dư thật nằm ở wallet layer sau khi transaction request thành công.

7. Checklist QA ngắn

1. Tách test affiliate payment approval khỏi test withdraw request.
2. Test cả 2 nhánh registration: customer self-register và staff create affiliate.
3. Test historical visibility cho affiliate inactive nhưng đã có order/payment approved.
4. Test fail path khi invoice approve gặp thiếu transaction_id.
5. Test action logs cho approve/revoke/reject/update percent ở cả order và invoice.