Wallet Transaction Request / Commission Deep Dive

Bộ tài liệu này đào sâu flow wallet-transaction-request-and-commission 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 một mental model rõ ràng cho 4 lớp dễ bị lẫn:

• transaction_request là request engine,
• transaction là ledger đã materialize,
• commission là một family request riêng nhưng dùng cùng engine,
• balance khả dụng phụ thuộc hold_amount, min_balance_capacity và wallet type.

Đọ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ữ, status, boundary, invariants
FE Dev	type-transaction-request-engine.md	Hiểu write surface, GraphQL, permission, UI drift
BE Dev	module-overview.md	Hiểu action/event/trigger/materialization path
QA	type-transaction-request-engine.md, type-wallet-balance-and-hold.md	Thiết kế test matrix theo request type, status và balance semantics
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: FE surfaces, action/event engine, tables, coupling, risks
shared-rules.md	Thuật ngữ, status matrix, behavior matrix, invariants, boundary rules
type-transaction-request-engine.md	Deep dive cho request engine: create, approve/reject, ledger materialization
type-commission-lifecycle.md	Deep dive cho commission create, temp commission, refund/clawback
type-wallet-balance-and-hold.md	Deep dive cho wallet_balance, wallet_stats, hold amount, wallet auto-create

Kết luận ngắn

1. Wallet không có FE module riêng; UI chỉ là nhiều write/read surface cho cùng một request engine.
2. transaction_request mới là source-of-truth của workflow, còn transaction là ledger được materialize khi request sang S.
3. Commission không phải subsystem tách rời; nó là một family behavior_id chạy trên cùng request engine.
4. available balance hiện có drift giữa business rule, DB trigger và một số check/runtime path trong code.

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

• docs/modules/wallet/overview.md
• docs/modules/wallet/wallet.md
• docs/modules/wallet/wallet.technical.md
• docs/modules/ecommerce/requests.md
• docs/modules/ecommerce/deep-dives/refund-withdraw/README.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, wallet-api, ecommerce-api, Hasura metadata và migrations của DB wallet.
• Ưu tiên mô tả hệ thống đang chạy như thế nào thay vì mô hình lý tưởng.
• Chủ động ghi ra các drift hoặc dấu hiệu bug ở FE, backend và DB.