Tasks — Admin → Super Agent
Spec: admin-to-superagent · Mockup: sell-credit (modal), list, detail
Current status: applyAdminCashFunding exists (credits + note), modal on SuperAgentDetailPage (amount + note). No separate cash transaction table, form fields incomplete, no list/detail.
V1 scope: Submit only Paid in full — credits issued status. Detail view-only. No proof upload.
Shared UI: @kioskgaming/ui / portal-cash-settlement — Admin only wires API + route.
Phase 1 — Backend & data model
| # | Task | Notes |
|---|---|---|
| 1.1 | Design cash_transactions table | ✅ 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 | Accept new payload; create cash_transaction + keep payment_transaction / credit wallet transfer |
| 1.5 | Snapshot buyer costRate at time of sale | Store in cash_transaction, do not re-read rate later |
| 1.6 | Record performed_by (admin id) + create audit log | Minimum: created_at, admin id in metadata |
| 1.7 | API POST /api/admin/super-agents/:id/cash-credits (or extend existing cash funding endpoint) | 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; valid received_at |
| 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 | View-only detail; include linked credit transaction summary |
| 1.11 | (Optional V1) Export CSV from list API | Match current filters |
| 1.12 | Unit tests biz service + controller | Happy path, invalid SA, zero credits, snapshot cost rate |
Phase 2 — UI package (packages/ui)
Details: ui-package-cash-settlement. Do before or parallel with Admin wire Phase 2.
| # | Task | Notes |
|---|---|---|
| UI.1–UI.7 | Module portal-cash-settlement | Modal, list ledger, detail view-only |
| UI.8 | Export from @kioskgaming/ui | SellCreditsCashModal, PortalCashTransactionsLedger, PortalCashTransactionDetail |
Phase 3 — Admin wire (integration)
| # | Task | Notes |
|---|---|---|
| 3.1 | Super Agent detail: open SellCreditsCashModal | flow=admin_super_agent, buyer = SA being viewed |
| 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 to detail |
Do not reimplement form/table/detail in kioskgaming_admin — only compose from package.
Reference: SuperAgentDetailPage.tsx (replace old amount+note modal)
Phase 4 — QA & docs
| # | Task | Notes |
|---|---|---|
| 4.1 | Manual test checklist Admin → SA | Modal, wallet +credit, list, detail |
| 4.2 | Confirm online USD wallet unchanged | Regression payment tx audit |
| 4.3 | Update spec if implementation diverges | File admin-to-superagent.md |
Dependency for other flows
Phase 1 (table + list/detail API) shared by Super Agent → Agent and Agent → Shop — extend flow enum when implementing those flows.