Phase 7.6 — Wallet
| Field |
Value |
| Identifier |
loyalty-7.6 |
| Status |
Complete |
| Module |
loyalty |
| Service |
loyalty-service |
| Version |
0.7.6.0 |
| Database |
loyalty_db |
| Depends On |
Phase 7.5 |
| ADR(s) |
ADR-001, ADR-003, ADR-006, ADR-011 |
| Manifest |
phase-manifest.yaml |
Objective
Deliver the Wallet Engine: wallet accounts with an append-only immutable ledger as the sole balance source (credit / debit / adjust / transfer) — without gift cards, analytics, or partner APIs.
Scope
In Scope
WalletAccount shell — no mutable balance columnWalletLedgerEntry append-only ledger; balance = SUM(signed amounts)- Credit, debit, adjust, transfer (atomic two-leg)
- Idempotency, insufficient-funds rejection, open-account-only mutations
- Permissions, events, validators, migration
0007_phase_76_wallet
- Tests + documentation + handover + service snapshot
Out of Scope
- Gift Card Platform (7.7)
- Analytics (7.8)
- Public / Partner / Webhook APIs (7.9)
- Final Review (7.10)
Ledger Rules
| Rule |
Detail |
| Append-only |
No UPDATE/DELETE of ledger rows |
| Signed amounts |
credit/transfer_in positive; debit/transfer_out negative; adjust signed |
| Open accounts only |
Frozen/closed reject mutations |
| Transfer |
Same currency; not same account; single commit |
| Balance |
Computed from ledger only |
APIs
| Method |
Path |
Permission |
| POST |
/api/v1/wallets |
loyalty.wallets.create |
| GET |
/api/v1/wallets |
loyalty.wallets.view |
| GET |
/api/v1/wallets/{id} |
loyalty.wallets.view |
| GET |
/api/v1/wallets/{id}/balance |
loyalty.wallets.view |
| GET |
/api/v1/wallets/{id}/ledger |
loyalty.wallets.view |
| PATCH |
/api/v1/wallets/{id} |
loyalty.wallets.manage |
| POST |
/api/v1/wallets/{id}/credit |
loyalty.wallets.credit |
| POST |
/api/v1/wallets/{id}/debit |
loyalty.wallets.debit |
| POST |
/api/v1/wallets/{id}/adjust |
loyalty.wallets.adjust |
| POST |
/api/v1/wallets/{id}/transfer |
loyalty.wallets.transfer |
| POST |
/api/v1/wallets/{id}/delete |
loyalty.wallets.delete |
Events
| Event |
When |
loyalty.wallet.opened |
Account opened |
loyalty.wallet.credited |
Credit |
loyalty.wallet.debited |
Debit |
loyalty.wallet.adjusted |
Adjust |
loyalty.wallet.transferred |
Transfer |
loyalty.wallet.closed |
Soft close |
Migration
| Item |
Detail |
| Alembic |
0007_phase_76_wallet (down_revision 0006_phase_75_referral) |
| Breaking |
None — additive tables |
Tests
Command: cd backend/services/loyalty && pytest -q → 114 passed
Known Limitations
- No payment gateway settlement (credits are ledger-only)
- No gift-card issuance (7.7)
- No scheduled freeze/close workers
Next Phase
Phase 7.7 — Gift Card Platform
Related Documents
