# FamilyDashboard Admin coin management regression workflow

Use this when touching Admin → Aufgaben & Coins, manual coin bookings, coin ledger corrections, bulk void/delete/reset, or tests around `CoinTransaction`.

## Durable lessons

- The primary user-facing regression for manual bookings is: booking `+10` coins through `POST /api/admin/coins/manual` must increase both `summary.posted` and `summary.available` by exactly `10`, with `reserved` unchanged.
- Keep coin balances ledger-derived. Manual fixes, single voids, and bulk voids should create append-only `CoinTransactionType.manual` counter-bookings unless the user explicitly asks for destructive history maintenance.
- Destructive Admin paths may exist for maintenance, but require exact confirmation strings:
  - bulk hard-delete: `DELETE_COIN_BUCHUNGEN`
  - reset child history to zero: `COINS_AUF_NULL`
- If hard-deleting selected transactions, include dependent counter-bookings via `reference_transaction_id` so the remaining ledger is not left with orphaned offsets.
- When testing coin deltas, capture the ledger baseline before the action. Seed/test setup can legitimately contain existing transactions from other tests or seeded behaviours; assertions should prove deltas unless the test explicitly resets history.

## Minimal backend tests to add/keep

- `+10` manual booking:
  - get admin ledger summary baseline
  - `POST /api/admin/coins/manual` with `{ child_id, amount: 10, comment, idempotency_key }`
  - assert `posted == baseline.posted + 10`, `available == baseline.available + 10`, `reserved` unchanged
  - assert a returned/manual transaction exists in ledger
- single void:
  - create manual source transaction
  - void twice with same idempotency key
  - assert final summary returns to the captured baseline and only one counter-booking references the source
- bulk void/delete:
  - create selected source transactions
  - bulk-void should return to baseline
  - bulk-delete of originals should remove originals and dependent counter-bookings, leaving baseline unchanged
- reset:
  - capture baseline, create a manual source, then reset with `COINS_AUF_NULL`
  - assert the child ledger becomes zero and transactions list is empty

## Verification sequence

1. Back up production DB before deploy/test work: `scripts/backup-db.sh`.
2. Run targeted local backend tests for admin coin management plus existing admin CRUD void/manual tests.
3. Run frontend build when Admin UI changed.
4. Rebuild with `docker compose up -d --build` (never `down -v`).
5. Run targeted tests inside the backend container and compare production DB row counts before/after to prove the bind-mounted DB was untouched.
6. Commit, push, and verify the exact remote branch ref with a token-backed credential helper when `origin` is HTTPS.