feat(admin): per-user finance panel — balances, benefits, risk, ledger
CI / changes (pull_request) Successful in 4s
CI / unit (pull_request) Successful in 11s
CI / integration (pull_request) Successful in 28s
CI / ui (pull_request) Has been skipped
CI / conformance (pull_request) Successful in 10s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m46s
CI / changes (pull_request) Successful in 4s
CI / unit (pull_request) Successful in 11s
CI / integration (pull_request) Successful in 28s
CI / ui (pull_request) Has been skipped
CI / conformance (pull_request) Successful in 10s
CI / gate (pull_request) Successful in 0s
CI / deploy (pull_request) Successful in 1m46s
The /_gm user card gains a Finance panel: an account's chip balances per funding segment, benefits per origin (hints, no-ads until/forever), the recorded refund risk (abuse flag + floor-0 loss), and the append-only ledger history newest-first. Backed by a new payments.AccountStatement read straight from the materialized tables + the ledger (uncached — an admin, rare view). Folds the agreed admin / reports / catalog plan into PLAN.md (the PR stack: this panel, then the catalog editor, admin grant, refund + ledger export) and moves the tournament-entry storage design to the tournament stage.
This commit is contained in:
@@ -36,7 +36,7 @@ status — without re-deriving decisions.
|
||||
| E4 | Durability (PITR) | 2 | DONE |
|
||||
| E5 | Payment intake | 2 | DONE |
|
||||
| E6 | Ads | 2 | DONE |
|
||||
| E7 | Admin & reports | 2 | TODO |
|
||||
| E7 | Admin, reports & catalog | 2 | TODO |
|
||||
| E8 | Guest limits | — | TODO |
|
||||
| E9 | Tournament fee | future | TODO |
|
||||
|
||||
@@ -693,38 +693,89 @@ it tunes without a store release.
|
||||
|
||||
---
|
||||
|
||||
## E7 — Admin & reports
|
||||
## E7 — Admin, reports & catalog
|
||||
|
||||
**Status:** TODO · **Release 2** · depends on: E2 (ledger/grant), E5 (payments/refunds) ·
|
||||
mechanics: PAYMENTS §11.
|
||||
**Status:** TODO · **Release 2** · depends on: E2 (ledger/grant/spend), E5 (payments/refunds),
|
||||
E6 (D31 retired the legacy `hint_balance`/`paid_account`) · mechanics: PAYMENTS §11, §12, D32.
|
||||
|
||||
**Goal.** The admin console financial surface: per-user report, admin grant UI, manual
|
||||
refund UI, ledger export.
|
||||
**Delivery & baked decisions (this planning round).** A linear PR stack into `development`.
|
||||
|
||||
**Work (`/_gm`, `backend/internal/server/handlers_admin_console.go` + `adminconsole/`).**
|
||||
- **Archived product = the existing `product.active` flag** (no new column, no migration):
|
||||
`active=false` **is** "archived". Its three behaviours already hold — hidden from the user
|
||||
storefront (`store_catalog.go` filters `active`), an **in-flight external payment still
|
||||
credits** (the `fund` credit path resolves the order and never re-checks `active`; only order
|
||||
*creation* / chip *spend* require `active`), and a product with any order/ledger row **cannot
|
||||
be hard-deleted** (FK `orders→product` / `ledger→product` are RESTRICT). The admin toggle is
|
||||
labelled **Archive / Unarchive**.
|
||||
- **Delete vs archive:** the editor offers a hard **Delete** only for a product with **no
|
||||
orders and no ledger rows** (never transacted — the FK is the DB backstop); a transacted
|
||||
product is **archive-only**.
|
||||
- **Admin grant = raw atoms + by-product.** Keep the quick raw-atom grant (N hints / no-ads
|
||||
days / forever) AND add grant-by-product: pick a defined product (including archived "reward"
|
||||
bundles) and grant its atoms. Both write an `admin_grant` ledger row; by-product records
|
||||
`product_id` + the snapshot. **Both refuse any set containing `chips`** (admin never grants
|
||||
currency) **or `tournament`** (no credit target until E9) — an explicit refusal, never a
|
||||
silent no-op.
|
||||
- **Manual refund = full order only** for now (the E5 `Refund` engine takes an amount; partial
|
||||
is a later add if needed).
|
||||
- **Tournament stays atom-only (E0); its entry economy is E9.** The catalog editor can compose
|
||||
products carrying the `tournament` atom (archived templates for E9), but granting/spending a
|
||||
`tournament` atom is refused until E9 designs the storage (recurring types, each its own
|
||||
benefit + price) — see E9. Adding a `benefits.tournament` counter now was rejected: the model
|
||||
is multi-type, so a single column would be wrong and force a second DB break.
|
||||
- The admin grant **no longer mirrors `grant-hints`** (E6/D31 removed that action); it is a
|
||||
fresh action on `payments.Grant`.
|
||||
|
||||
- **Per-user financial panel** on the existing user card (`consoleUserDetail` :343,
|
||||
`UserDetailView`): segment balances, payments, spends, grants, refunds, full history —
|
||||
read from the append-only ledger + materialized cache.
|
||||
- **Admin grant** action (mirror the existing `POST /_gm/users/:id/grant-hints`): grant
|
||||
concrete values (no-ads days / hints), **origin picker**, **never chips**; writes an
|
||||
`admin_grant` ledger row (E2 `Grant`).
|
||||
- **Manual refund** action: admin-initiated refund of a specific order (ties to the refund
|
||||
path); records a `refund` ledger row; best-effort benefit revoke.
|
||||
- **Ledger export**: CSV/JSON export of the ledger for tax reporting + future Robokassa
|
||||
reconciliation (export-ready schema; reconciliation itself not built).
|
||||
**Goal.** The admin console financial surface — per-user report, admin grant, manual refund,
|
||||
ledger export — plus the **configurable product catalog editor** (D32).
|
||||
|
||||
**Work (`/_gm`, `handlers_admin_console.go` + `adminconsole/`, `internal/payments/`).**
|
||||
|
||||
- **Per-user financial panel** on the user card (`consoleUserDetail`, `UserDetailView`): segment
|
||||
chip balances `(account, source)`, benefits `(account, origin)` (hints, no-ads until/forever),
|
||||
and the full append-only ledger (fund/spend/admin_grant/refund — amount, origin, product,
|
||||
provider, snapshot) from the ledger + materialized cache. Replaces the retired
|
||||
`PaidAccount`/`HintBalance` fields with the segmented view.
|
||||
- **Catalog editor** (`/_gm/catalog`): list every product (active + archived) with its atoms and
|
||||
per-method/currency prices; create/edit (title, atom items `atom_type→quantity`, price rows
|
||||
`method+currency→amount`); **Archive/Unarchive** (`active`); **Delete** (never-transacted
|
||||
only). Enforce the projection's shape: a **pack** (carries `chips`) needs a money price per
|
||||
method; a **value** (no `chips`) needs a single `CHIP` price. A `tournament`-bearing product is
|
||||
allowed in composition but cannot be activated for sale until E9.
|
||||
- **Admin grant** action: raw atoms (hints / no-ads days / forever) and by-product (a value
|
||||
product, incl. archived); **origin picker**; refuses `chips`/`tournament`; `admin_grant` ledger
|
||||
row (+ `product_id`/snapshot for by-product) via `payments.Grant`.
|
||||
- **Manual refund** action: refund a specific paid order **in full** — a `refund` ledger row +
|
||||
best-effort floor-0 benefit revoke (E5 `Refund`).
|
||||
- **Ledger export**: CSV/JSON for tax + future Robokassa reconciliation (export-ready;
|
||||
reconciliation itself not built).
|
||||
- Auth unchanged: gateway Basic-Auth in front of `/_gm` + backend same-origin CSRF on POSTs.
|
||||
|
||||
**Tests.**
|
||||
|
||||
- unit: report view assembly; grant refuses chips; export shape.
|
||||
- integration: grant/refund write correct ledger rows; report reflects balances+history.
|
||||
- unit: panel view assembly; catalog pack/value shape projection; grant refuses chips + tournament;
|
||||
editor validation (pack⇒money price, value⇒CHIP price); export shape.
|
||||
- integration: grant (raw + by-product) writes the right `admin_grant` row + benefit; refund writes
|
||||
a `refund` row + floor-0 revoke; catalog CRUD round-trips (create→edit→archive→delete-if-clean);
|
||||
delete refused on a transacted product; panel reflects balances + benefits + history.
|
||||
|
||||
**Done-criteria.** An operator can see a user's full financial picture, grant concrete
|
||||
values (origin-picked, never chips), issue a manual refund, and export the ledger.
|
||||
**Done-criteria.** An operator can: see a user's full financial picture; create/edit/archive
|
||||
products + prices and delete only never-transacted ones; grant concrete values raw or by-product
|
||||
(origin-picked, never chips/tournament); refund an order in full; export the ledger.
|
||||
|
||||
**Notes/risks.** `/_gm` per-user detail already surfaces `PaidAccount`/`HintBalance` — replace
|
||||
those with the segmented view as the legacy columns retire.
|
||||
**PR stack (linear into `development`).**
|
||||
|
||||
1. **Per-user financial panel** (read-only ledger/segments/benefits on the user card; retires the
|
||||
`PaidAccount`/`HintBalance` display).
|
||||
2. **Catalog editor** (product/atom/price CRUD + archive/unarchive + delete-if-clean + shape
|
||||
validation).
|
||||
3. **Admin grant** (raw + by-product, refuse chips/tournament, origin-picked, `admin_grant` +
|
||||
snapshot).
|
||||
4. **Manual refund** (full order via E5 `Refund`) + **ledger export** (CSV/JSON).
|
||||
|
||||
**Notes/risks.** High-blast-radius (money, ledger — append-only, trigger-enforced). No mixed-in
|
||||
refactors. The catalog editor becomes the source of truth for products; the contour SQL seeds
|
||||
become bootstrap-only.
|
||||
|
||||
---
|
||||
|
||||
@@ -770,11 +821,23 @@ on creation, not mid-game) at implementation and record it here.
|
||||
**Status:** TODO · **future** · depends on: E0 (atom provisioned), tournament feature ·
|
||||
mechanics: PAYMENTS §5, §7.
|
||||
|
||||
**Goal.** Charge a chip entry fee for tournaments. The `tournament` atom + a catalog product
|
||||
are provisioned in E0/E7; the spend mechanic reuses E2 (`Spend`). The actual tournament
|
||||
feature and its coupling to entry are out of scope until the tournament feature exists.
|
||||
**Goal.** A chip entry economy for tournaments. The `tournament` atom is provisioned (E0) and
|
||||
E7's catalog editor can compose tournament products; E7 deliberately **defers the entry storage
|
||||
+ credit/spend** here, to avoid guessing the schema.
|
||||
|
||||
**Done-criteria.** Deferred — revisit when tournaments are built.
|
||||
**Design to settle here (not before — avoid a double DB break).** Tournaments are expected in
|
||||
**several recurring types** (daily / weekly / monthly …), each its **own benefit with its own
|
||||
price** — so a single `benefits.tournament` counter is wrong. Model the entry store as
|
||||
**per-tournament-type** (e.g. a `tournament_type` catalog + a per-`(account, type)` entry
|
||||
balance), design the pricing, then:
|
||||
|
||||
- lift E7's **refusal** of granting/spending the `tournament` atom (admin grant by-product +
|
||||
chip spend);
|
||||
- add the **spend** (charge an entry) reusing E2 `Spend`;
|
||||
- wire the coupling to the actual tournament feature (out of scope until it exists).
|
||||
|
||||
**Done-criteria.** Deferred — revisit when tournaments are built; this stage owns the
|
||||
tournament-entry storage + pricing design.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user