FE: module refund — hoàn tiền đơn hàng #
Phần chung (khởi tạo client, lỗi, danh sách, ngôn ngữ) ở tài liệu FE của Core:
docs/fe/common.md (bản đọc: xforge-documentation, ADR-0102 của xforge-core).
Sửa file này CÙNG PR khi đổi hành vi FE thấy được của module.
Phiếu hoàn ghi tiền trả lại khách cho một đơn đã trả. Chỉ hoàn phần tiền mặt /
chuyển khoản, trần theo grandTotal của đơn. Phần đơn trả bằng thẻ quà hoàn
riêng: refundOrderToGiftCard (module gift_card); hệ thống không tự chia một
lần hoàn giữa tiền và thẻ, nhân viên quyết từng bên.
Vòng đời #
pending → completed | failed. Riêng cách momo: pending → processing
(đã gửi cổng) → completed | failed.
Mỗi phiếu có actions: thao tác người gọi làm được lúc này. Bật / tắt nút theo
đó, đừng tự suy từ status. Giá trị lạ thì bỏ qua.
actions | Khi nào | Quyền | Method |
|---|---|---|---|
send | method là momo và phiếu pending | refund.send | sendRefund |
complete | pending / processing | refund.complete | completeRefund |
fail | pending / processing, trừ khi MoMo đã xác nhận | refund.complete | failRefund |
CMS / admin (XforgeClient) #
Menu: key refund.refunds (quyền refund.read).
| Việc | Method | Quyền |
|---|---|---|
| Danh sách | listRefunds({ query }) (lọc status, order_id; q theo số phiếu) | refund.read |
| Chi tiết | getRefund({ params: { id } }) | refund.read |
| Tạo | createRefund({ body: { orderId, amount, shippingAmount?, method, reason? } }) | refund.create |
| Hoàn tất | completeRefund({ params: { id }, body: { reference? } }) | refund.complete |
| Thất bại | failRefund({ params: { id }, body: { reason, gatewayChecked? } }) | refund.complete |
| Gửi MoMo | sendRefund({ params: { id } }) | refund.send |
method:bank_transfer,cash,manual,momo. Ba cách đầu hệ thống không chuyển tiền: nhân viên trả khách rồicompleteRefundkèm mã giao dịch.- Đơn phải
paid/partially_refunded. Phiếupending/processing/completedcùng giữ suất: tổng không vượtgrandTotal, phầnshippingAmountkhông vượt phí giao.failednhả suất. - Hoàn tất: đơn thành
partially_refunded, hoặcrefundedkhi đã hoàn đủ. Đơnrefundedchưa giao thì huỷ được. - MoMo:
sendRefundtrả về phiếu đãcompleted(reference= mã MoMo),failed(failReason), hoặc vẫnprocessingkhi chưa rõ kết quả. Lúc đó kiểm trên trang MoMo rồicompleteRefund, hoặcfailRefundvớigatewayChecked: true(đã kiểm: chưa hoàn).
Webhook gửi đi #
Sự kiện refund.completed, đăng ký ở màn "Tích hợp" (docs/fe/cms.md §8),
người đăng ký cần refund.read. Phát khi phiếu hoàn tất, cả hoàn tay lẫn qua
MoMo. data là hợp đồng (thêm field được):
{ refundId, number, orderId, orderNumber, status, method, currency, amount, shippingAmount, refundedTotal, paymentStatus }
Không có lý do, mã giao dịch hay dữ liệu cá nhân; bên nhận đọc chi tiết qua API.
Lỗi cần xử lý #
code | Status | FE nên |
|---|---|---|
refund_order_not_found | 404 | đơn không thuộc store |
refund_order_not_paid | 409 | đơn chưa trả (details.paymentStatus) |
refund_amount_exceeds | 409 | hiện details.available; phần đã trả bằng thẻ hoàn ở gift_card |
refund_shipping_exceeds | 409 | hiện details.available |
refund_shipping_over_amount | 400 | phần phí giao lớn hơn số tiền hoàn |
refund_momo_unavailable | 409 | đơn không trả qua MoMo / store chưa cấu hình: chọn cách khác |
refund_not_gateway | 409 | phiếu không phải momo: tải lại |
refund_not_pending | 409 | phiếu đã đổi trạng thái: tải lại |
refund_gateway_check_required | 409 | hỏi người đối soát đã kiểm MoMo chưa, gửi lại với gatewayChecked |
refund_gateway_paid | 409 | MoMo đã hoàn: chỉ còn completeRefund |