feat(api): add customer accounts with live summary and append-only ledger

One balance row per (user, kind, currency): available and frozen carry the
platform base currency, points carries none. Monetary and points rows use
separate partial unique indexes because a plain UNIQUE lets NULL repeat.

Balance changes go through transactional primitives that debits guard with a
conditional update, credits add atomically, and freeze/release move both sides
in one transaction after locking rows by primary key. Every change appends an
immutable entry holding its resulting balance. Registration and a migration
backfill create the zero rows; GET /api/me/stats is the only public surface and
no endpoint mutates a balance.

The mall buyer center and points page drop the USER_STATS fixture for the
shared contract; the fixture stays exported so the fixed-data adapter can still
serve the account domain as a rollback path.

Implements openspec change add-customer-accounts.
This commit is contained in:
2026-09-18 11:54:53 +00:00
parent bcd97ab48f
commit 7a2745fb16
19 changed files with 818 additions and 21 deletions
+10 -10
View File
@@ -1,18 +1,18 @@
## 1. Account persistence and mutation boundary
- [ ] 1.1 Add additive migrations for customer accounts, account kinds/currencies, append-only entries, and required indexes/checks.
- [ ] 1.2 Initialize zero account rows for existing seeded users and every newly registered customer. Do not credit demo points here.
- [ ] 1.3 Implement the Rust account module with stable-order account locking, conditional non-negative debits/freezes, atomic credits/releases, and entry insertion.
- [x] 1.1 Add additive migrations for customer accounts, account kinds/currencies, append-only entries, and required indexes/checks.
- [x] 1.2 Initialize zero account rows for existing seeded users and every newly registered customer. Do not credit demo points here.
- [x] 1.3 Implement the Rust account module with stable-order account locking, conditional non-negative debits/freezes, atomic credits/releases, and entry insertion.
## 2. Summary contract and proof
- [ ] 2.1 Add shared account-summary types, client method, localized UI strings, and fixed-data adapter compatibility.
- [ ] 2.2 Expose authenticated `GET /api/me/stats` through the account service without public balance mutation endpoints.
- [ ] 2.3 Add API integration tests for zero initialization, summary ownership, immutable entries, available-to-frozen transfer, and competing insufficient debits.
- [x] 2.1 Add shared account-summary types, client method, localized UI strings, and fixed-data adapter compatibility.
- [x] 2.2 Expose authenticated `GET /api/me/stats` through the account service without public balance mutation endpoints.
- [x] 2.3 Add API integration tests for zero initialization, summary ownership, immutable entries, available-to-frozen transfer, and competing insufficient debits.
## 3. Mall migration and verification
- [ ] 3.1 Replace buyer-center and points-page `USER_STATS` reads with the shared account summary API.
- [ ] 3.2 Remove affected stats fixture imports while keeping the fixed-data adapter rollback path intact.
- [ ] 3.3 Seed and browser-smoke the live buyer account summary.
- [ ] 3.4 Run cargo test for vmall-api, the mall build, and strict validation for this OpenSpec change.
- [x] 3.1 Replace buyer-center and points-page `USER_STATS` reads with the shared account summary API.
- [x] 3.2 Remove affected stats fixture imports while keeping the fixed-data adapter rollback path intact.
- [x] 3.3 Seed and browser-smoke the live buyer account summary.
- [x] 3.4 Run cargo test for vmall-api, the mall build, and strict validation for this OpenSpec change.