Ecommerce Refund / Withdraw Deep Dive

Bộ tài liệu này đào sâu flow ecommerce-refund-withdraw 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 không phải viết lại PRD cũ, mà là chốt một bản đồ rõ ràng cho các flow:

refund order dịch vụ,
refund order mỹ phẩm,
refund topup / collaborator,
commission refund như child request,
boundary với negative payment.

Đọ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ữ, boundary, state machine, approval model
FE Dev	type-refund-request.md	Hiểu route, page, GraphQL, permission, runtime drift
BE Dev	module-overview.md	Hiểu action path, event path, side effects chính
QA	type-refund-request.md, type-negative-payment-boundary.md	Viết test cases theo từng nhánh
Người mới vào hệ thống	module-overview.md	Có mental model tổng trước khi đi sâu

Files

File	Vai trò
module-overview.md	Bản đồ tổng: route, data flow, action/event, tables, risks
shared-rules.md	Thuật ngữ, trạng thái, behavior matrix, approval và semantic rules
type-refund-request.md	Deep dive cho family `transaction_request`: refund/withdraw/commission refund
type-negative-payment-boundary.md	Deep dive cho `negative payment` và lý do không được gộp vào refund

Kết luận ngắn

Refund / withdraw thật sự là flow wallet.transaction_request-centric.
Side effects quan trọng không nằm hết ở action approve, mà nằm mạnh ở event transaction_request_update.
negative payment là một state machine riêng qua hrm.request_working_schedule; chỉ có coupling dữ liệu với wallet, không cùng workflow với refund.
transaction_request.reference_id đang bị overload nên không thể coi là khóa canonical duy nhất.

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

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.
Ưu tiên mô tả “hệ thống đang chạy như thế nào”.
Chủ động ghi ra các drift hoặc dấu hiệu bug thay vì làm phẳng thành một flow lý tưởng.