Affiliate Approval And Payout Deep Dive

Bộ tài liệu này đào sâu flow affiliate-approval-and-payout theo code thực tế hiện tại. Đây là package reverse-engineer trong docs/modules, không phải PRD/spec delivery. Mục tiêu là chốt mental model rõ cho 4 lớp dễ bị gộp sai trong module affiliate:

• đăng ký CTV và duyệt CTV là hai nhánh khác nhau, không phải cùng một create flow,
• affiliate_user, order_affiliate, invoice_affiliate là ba lớp state khác nhau nhưng đều đi qua cùng action affiliateUserChangeStatus,
• affiliate payment trong UI không đồng nghĩa payout thật; payout/withdraw thực tế chạy qua wallet.transaction_request,
• commission được materialize sang wallet chỉ khi approve invoice thành công.

Đọc file nào?

Bạn là ai?	Nên đọc trước	Mục tiêu
PO / BA	shared-rules.md	Chốt thuật ngữ, state model, approval boundary, payout semantics
FE Dev	type-affiliate-approval-and-status.md	Hiểu route redirect, create/edit, approve/revoke, popup actions
BE Dev	type-order-commission-and-invoice.md	Hiểu order/invoice approval, commission materialization, mutation side effects
QA	type-payment-withdraw-and-wallet-boundary.md, shared-rules.md	Tách test affiliate invoice approval khỏi wallet withdraw history
Người mới vào hệ thống	module-overview.md	Có bản đồ tổng trước khi đi sâu

Files

File	Vai trò
module-overview.md	Bản đồ tổng: route families, lifecycle, backend boundaries, data layers
shared-rules.md	Thuật ngữ chuẩn, state matrix, invariants, cross-module boundaries
type-affiliate-approval-and-status.md	Deep dive cho registration, approval queue, activate/revoke, referral shell
type-order-commission-and-invoice.md	Deep dive cho order affiliate, invoice affiliate, commission percent, wallet type
type-payment-withdraw-and-wallet-boundary.md	Deep dive cho withdraw request, wallet balance, transaction_request boundary, history cards

Kết luận ngắn

1. affiliate là một lifecycle chain từ user approval sang order commission, rồi mới sang invoice approval và wallet payout.
2. Action affiliateUserChangeStatus là engine trạng thái trung tâm cho cả 3 reference types: user, order, invoice.
3. Approve invoice mới là điểm commission được materialize thật qua transaction_request sang wallet.
4. Withdraw/payout không nằm trong invoice_affiliate; nó là flow riêng ở wallet với behavior_id = refund_collaborator.

Liên kết tài liệu liên quan

• docs/modules/affiliate/overview.md
• docs/modules/wallet/overview.md
• docs/modules/ecommerce/overview.md
• docs/modules/report/overview.md
• docs/modules/user/overview.md
• docs/modules/phase-2-backlog.md

Phạm vi của bộ docs này

• Bám theo code hiện tại của diva-admin, ecommerce-api, Hasura metadata và DB ecommerce + wallet.
• Ưu tiên mô tả hệ thống đang chạy như thế nào thay vì policy affiliate lý tưởng.
• Chủ động ghi ra các drift hoặc dấu hiệu bug/risk ở route guard, approval semantics, wallet boundary và mutation side effects.