Tasks — Admin → Super Agent
Spec: admin-to-superagent · Mockup: sell-credit (modal), list, detail
Hiện trạng: Đã có applyAdminCashFunding (credits + note), modal trên SuperAgentDetailPage (amount + note). Chưa có bảng cash transaction riêng, chưa đủ field form, chưa có list/detail.
Phạm vi V1: Submit chỉ trạng thái Paid in full — credits issued. Detail view-only. Không upload bằng chứng.
UI dùng chung: @kioskgaming/ui / portal-cash-settlement — Admin chỉ wire API + route.
Phase 1 — Backend & data model
| # | Task | Ghi chú |
|---|---|---|
| 1.1 | Thiết kế bảng cash_transactions | ✅ Schema |
| 1.2 | Migration + Sequelize model + indexes | Index: buyer_id, flow, status, received_at, created_at |
| 1.3 | Enum / constants: flow, status, payment_method | V1 status: paid_full only on create |
| 1.4 | Refactor superAgentCreditPurchaseBizService.applyAdminCashFunding | Nhận payload mới; tạo cash_transaction + giữ payment_transaction / credit wallet transfer |
| 1.5 | Snapshot costRate buyer tại thời điểm bán | Lưu vào cash_transaction, không đọc lại rate sau này |
| 1.6 | Ghi performed_by (admin id) + audit log tạo giao dịch | Tối thiểu: created_at, admin id trong metadata |
| 1.7 | API POST /api/admin/super-agents/:id/cash-credits (hoặc mở rộng endpoint cash funding hiện tại) | Body: credits, cash_received, payment_method, received_at, external_ref?, note? |
| 1.8 | Validation | SA active; credits > 0; cost rate > 0; cash_received > 0; payment_method enum; received_at hợp lệ |
| 1.9 | API GET /api/admin/cash-transactions | List + filter flow/status/payment_method/date/search; pagination |
| 1.10 | API GET /api/admin/cash-transactions/:id | Detail view-only; include linked credit transaction summary |
| 1.11 | (Optional V1) Export CSV từ list API | Khớp filter hiện tại |
| 1.12 | Unit tests biz service + controller | Happy path, invalid SA, zero credits, snapshot cost rate |
Phase 2 — UI package (packages/ui)
Chi tiết: ui-package-cash-settlement. Làm trước hoặc song song Phase 2 Admin wire.
| # | Task | Ghi chú |
|---|---|---|
| UI.1–UI.7 | Module portal-cash-settlement | Modal, list ledger, detail view-only |
| UI.8 | Export từ @kioskgaming/ui | SellCreditsCashModal, PortalCashTransactionsLedger, PortalCashTransactionDetail |
Phase 3 — Admin wire (integration)
| # | Task | Ghi chú |
|---|---|---|
| 3.1 | Super Agent detail: mở SellCreditsCashModal | flow=admin_super_agent, buyer = SA đang xem |
| 3.2 | Hook useAdminSuperAgentCashCredits + API client | Map form → POST cash-credits |
| 3.3 | Route /cash-transactions + sidebar menu | Render PortalCashTransactionsLedger |
| 3.4 | Hook useAdminCashTransactions (list) + export CSV | Inject onFetch / onExport |
| 3.5 | Route /cash-transactions/:id | Render PortalCashTransactionDetail |
| 3.6 | Submit success → refresh SA balance; optional navigate detail |
Không implement lại form/table/detail trong kioskgaming_admin — chỉ compose từ package.
Tham chiếu: SuperAgentDetailPage.tsx (thay modal cũ amount+note)
Phase 4 — QA & docs
| # | Task | Ghi chú |
|---|---|---|
| 4.1 | Manual test checklist Admin → SA | Modal, wallet +credit, list, detail |
| 4.2 | Xác nhận không đổi USD wallet online | Regression payment tx audit |
| 4.3 | Cập nhật spec nếu lệch implementation | File admin-to-superagent.md |
Phụ thuộc cho luồng khác
Phase 1 (bảng + list/detail API) dùng chung cho Super Agent → Agent và Agent → Shop — mở rộng flow enum khi làm các luồng đó.