Affiliate - Technical Map

Auto-generated bởi codebase-doc-generator ngày 2026-03-23 (verified từ code thực). Không chỉnh sửa thủ công.

Routes

Route	Path	Mục đích
`ROUTE_AFFILIATE`	`/affiliate`	Root shell
`ROUTE_AFFILIATE_APPROVAL`	`/affiliate/approval`	Danh sách CTV chờ duyệt
`ROUTE_AFFILIATE_APPROVAL_EDIT`	`/affiliate/approval/:id/edit`	Chỉnh sửa hồ sơ duyệt
`ROUTE_AFFILIATE_LIST`	`/affiliate/list`	Danh sách CTV active
`ROUTE_AFFILIATE_LIST_CREATE`	`/affiliate/list/create`	Tạo mới CTV
`ROUTE_AFFILIATE_LIST_EDIT`	`/affiliate/list/:id/edit`	Sửa CTV
`ROUTE_AFFILIATE_LIST_REFERRAL`	`/affiliate/list/:id/referral`	Referral summary theo CTV
`ROUTE_AFFILIATE_ORDER`	`/affiliate/order`	Danh sách order affiliate
`ROUTE_AFFILIATE_ORDER_DETAIL`	`/affiliate/order/:id/detail`	Chi tiết order affiliate
`ROUTE_AFFILIATE_PAYMENT`	`/affiliate/payment`	Danh sách payment/invoice affiliate
`ROUTE_AFFILIATE_PAYMENT_DETAIL`	`/affiliate/payment/:id/detail`	Chi tiết payment
`ROUTE_AFFILIATE_PAYMENT_ORDER`	`/affiliate/payment/order/:id/detail`	Mở order detail từ payment

Item	Giá trị
Sidebar title	`route./affiliate-left-menu`
`moduleId`	`affiliate_management`
Permissions chính	`ITLeader`, `ITStaff`
Platforms	Admin, CRM, POS

Special routing

Root route redirect theo runtime:
- POS + có module permission + BranchPOS -> vào ROUTE_AFFILIATE_LIST
- ngược lại -> vào ROUTE_AFFILIATE_APPROVAL

FE Pages (10)

Nhóm	Files
Approval	`pages/approval/ApprovalList.tsx`
List	`pages/list/List.tsx`, `ListCreate.tsx`, `ListReferral.tsx`
Order	`pages/order/OrderList.tsx`, `OrderDetail.tsx`, `OrderCustomerList.tsx`
Payment	`pages/payment/PaymentList.tsx`, `PaymentDetail.tsx`, `PaymentCustomerList.tsx`

FE Components (31)

Core

Component	Vai trò
`WithdrawAffiliateForm`	Form rút tiền / withdraw
`ActionBar`	Thanh action chuẩn
`AffiliateByInfo`	Thông tin CTV

List

Component	Vai trò
`ListTable`	Bảng danh sách CTV
`ListToolbar`	Search, membership, tag, date range, export
`ListForm`	Form tạo/sửa CTV
`ListReferralTable`	Referral summary
`ListActivePopup`	Popup kích hoạt/thao tác

Order

Component	Vai trò
`OrderTable`	Bảng order affiliate
`OrderCards`	Pending/approved cards
`OrderToolbar`	Filter order/payment
`OrderApproveBar`	Action approve/reject/cancel
`OrderCommissionField`, `OrderItemCommissionField`	Hiển thị commission
`OrderLeftDetail`, `OrderRightDetail`	Layout chi tiết

Payment

Component	Vai trò
`PaymentTable`	Bảng invoice affiliate
`PaymentActivePopup`	Popup action payment
`PaymentCommissionField`, `PaymentItemCommissionField`	Field commission
`PaymentLeftDetail`, `PaymentRightDetail`	Detail layout

GraphQL Operations

File: diva-admin/src/modules/affiliate/graphql/affiliate.graphql

Queries chính

Query	Mục đích
`GetAffiliateUsers`, `GetAffiliateUsersAggregate`, `GetAffiliateUsersFile`	Danh sách CTV active/pending + export
`GetAffiliateUserByPk`, `GetAffiliateUserIdByAccountId`, `GetAffiliateUserIdByPhoneNumber`	Lookup CTV
`SearchAffiliateUser`	Search nhanh
`GetAffiliateReferralListByUserId`	Referral summary
`GetAffiliateOrders`, `GetAffiliateOrderCards`, `GetAffiliateOrdersFile`, `GetAffiliateOrderByPk`	Order affiliate
`GetAffiliateInvoices`, `GetAffiliateInvoiceCards`, `GetAffiliateInvoicesFile`, `GetAffiliateInvoiceByPk`	Invoice/payment affiliate
`GetAffiliateConfig`	Config CTV
`GetWithdrawHistory`, `GetWithdrawHistoryCards`	Withdraw history
`GetCustomerAffiliateReport`, `GetCustomerAffiliateReportCards`, `GetCustomerAffiliateReportFile`	Report drill-down dùng lại ở module report
`GetCustomerNameAndEmailByPhoneNumber`	Hỗ trợ đăng ký

Mutations chính

Mutation	Backend/action
`RegisterAffiliateUser`	`affiliateUserRegistration`
`UpdateAffiliateUser`	Hasura update
`ChangeAffiliateUserStatus`	`affiliateUserChangeStatus`
`UpsertAffiliateConfig`	Hasura insert/update
`ChangeCustomerCommission`	Cập nhật commission cấu hình khách hàng/CTV

FE Filtering logic

Page	Logic đáng chú ý
`ApprovalList.tsx`	`is_active = false`, filter keyword/tag/membership/date
`List.tsx`	`is_active = true`, chung toolbar với approval
`OrderList.tsx`	Map UI status `confirmed/wait_confirmed/canceled` sang `_statuses = {approved,pending,rejected}` dùng function args
`PaymentList.tsx`	Map status sang điều kiện `is_approved` + `rejected`, đồng thời chỉ lấy payment của order đã approved

Backend Actions

`affiliate_user_registration.go`

Hành vi	Ghi chú
Kiểm tra trùng phone trong `affiliate_user`	Trả `REG_EXISTED` hoặc `REG_PENDING`
Kiểm tra account customer theo phone	Reuse account nếu có
`handleRegisterAffiliateByUser`	Tạo/duyệt ngay, yêu cầu tag hợp lệ
`handleRegisterAffiliateByCustomer`	Tạo bản ghi pending

`affiliate_user_change_status.go`

Reference type	Actions
`affiliate_user_type`	`approve`, `revoke`
`affiliate_order_type`	`approve`, `cancel`, `reject`, `unreject`
`affiliate_invoice_type`	`approve`, `reject`, `unreject`

Side effects chính:

Ghi affiliate_action_log
Tạo customer account nếu duyệt user mà chưa có account
Approve invoice sẽ gọi AddAffiliateCommission()
Ghi commission_revoke_log
Gửi notification / ZNS / SMS sau khi commission thành công

`change_affiliate_wallet_type.go`

Hành vi	Ghi chú
Đổi `wallet_receive_commission` của order	Chặn nếu có invoice approved
Tính lại `temp_commission_amount`	Theo customer current level
Cập nhật `invoice_affiliate.commission_amount`	Cho các invoice liên quan chưa duyệt

`get_report_affiliate.go`

Hành vi	Ghi chú
Đọc `aggregate_affiliate_report` theo chunks	Hỗ trợ limit/offset lớn
Query thêm wallet transactions	Tính `withdrawn_amount`

Store/Data model

`affiliate_user`

Field	Ý nghĩa
`account_id`	Account customer gắn với CTV
`affiliate_code`	Mã CTV, hiện thường lấy theo phone
`customer_name`, `phone_number`	Thông tin chính
`citizen_id`, `bank_*`, `tax_number`	Hồ sơ thanh toán/KYC
`is_active`	Đã duyệt hay chưa
`approved_at`	Thời điểm duyệt
`tag_id`	Nhãn CTV
`kyc_files`	Tài liệu KYC

`order_affiliate`

Field	Ý nghĩa
`order_id`	Order gốc
`affiliate_user_id`	CTV
`type_id`	`Direct` / `Referral`
`is_approved`, `rejected`	Trạng thái duyệt
`wallet_type`	Loại ví nhận commission
`order_total`	Giá trị order
`temp_commission_amount`	Hoa hồng tạm tính

`invoice_affiliate`

Field	Ý nghĩa
`invoice_id`	Invoice nguồn
`paid_amount`	Tiền thanh toán
`commission_amount`	Hoa hồng
`current_customer_level`, `current_sale_percent`	Snapshot membership/percent
`is_approved`, `rejected`, `approved_at`	Trạng thái
`transaction_id`	Link sang wallet transaction request

Các bảng/view liên quan

Object	Vai trò
`affiliate_action_log`	Audit trail
`affiliate_user_log`	Lịch sử người dùng CTV
`affiliate_summary_view`	Referral summary theo customer
`affiliate_report` / `aggregate_affiliate_report`	Report tổng hợp
`summary_order_affiliate_result` / function `summary_order_affiliate`	Cards cho order affiliate
`invoice_affiliate`	Payment detail
`affiliate_config`, `affiliate_user_tag`	Config và phân loại

Backend services

Service	Vai trò
ecommerce-api	Đăng ký, đổi trạng thái, đổi ví, aggregate report
wallet-api	Commission/wallet transaction side
controller (Hasura)	CRUD và functions trên ecommerce DB

Rủi ro / Findings kỹ thuật

#	Note
1	`affiliate_user_registration` dùng logic khác nhau theo role truy cập (`user/admin` so với `customer/anonymous`).
2	`PaymentList` chỉ lấy payment của order đã approved và affiliate user active hoặc trường hợp approved lịch sử được giữ lại.
3	Report customer affiliate trong module report dùng lại components từ affiliate, nên affiliate là source of truth cho drill-down.
4	Dữ liệu withdraw không nằm hoàn toàn trong ecommerce; phải nối thêm wallet transactions theo behavior `refund_collaborator`.