102 lines
3.4 KiB
Markdown
102 lines
3.4 KiB
Markdown
# Phase Handover — Loyalty 7.6 Wallet
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Phase ID | loyalty-7.6 |
|
|
| Title | Wallet |
|
|
| Status | Complete |
|
|
| Service(s) | loyalty (`loyalty-service`, port 8004) |
|
|
| Version | 0.7.6.0 |
|
|
| Date | 2026-07-26 |
|
|
| ADR(s) | ADR-001, ADR-003, ADR-006, ADR-011 |
|
|
|
|
## Reusable Components
|
|
|
|
| Component | Location | Reuse notes |
|
|
| --- | --- | --- |
|
|
| WalletAccount / WalletLedgerEntry | `app/models/wallet.py` | Immutable ledger pattern (gift cards 7.7) |
|
|
| WalletEngineService | `app/services/wallet_engine.py` | Credit/debit/adjust/transfer |
|
|
| Wallet validators | `app/validators/wallet.py` | Open-account + currency checks |
|
|
|
|
## Public APIs
|
|
|
|
| Method | Path | Auth / Permission | Notes |
|
|
| --- | --- | --- | --- |
|
|
| POST | `/api/v1/wallets` | `loyalty.wallets.create` | Open account |
|
|
| GET | `/api/v1/wallets/{id}/balance` | `loyalty.wallets.view` | Computed balance |
|
|
| GET | `/api/v1/wallets/{id}/ledger` | `loyalty.wallets.view` | Paginated entries |
|
|
| POST | `/api/v1/wallets/{id}/credit` | `loyalty.wallets.credit` | Idempotent optional |
|
|
| POST | `/api/v1/wallets/{id}/debit` | `loyalty.wallets.debit` | Rejects insufficient |
|
|
| POST | `/api/v1/wallets/{id}/adjust` | `loyalty.wallets.adjust` | Signed delta |
|
|
| POST | `/api/v1/wallets/{id}/transfer` | `loyalty.wallets.transfer` | Two-leg atomic |
|
|
| POST | `/api/v1/wallets/{id}/delete` | `loyalty.wallets.delete` | Soft close |
|
|
|
|
## Events
|
|
|
|
| Event type | Domain / Integration | Version |
|
|
| --- | --- | --- |
|
|
| `loyalty.wallet.opened` | Domain | 1 |
|
|
| `loyalty.wallet.credited` | Domain | 1 |
|
|
| `loyalty.wallet.debited` | Domain | 1 |
|
|
| `loyalty.wallet.adjusted` | Domain | 1 |
|
|
| `loyalty.wallet.transferred` | Domain | 1 |
|
|
| `loyalty.wallet.closed` | Domain | 1 |
|
|
|
|
## Extension Points
|
|
|
|
| Extension point | How to extend | Forbidden uses |
|
|
| --- | --- | --- |
|
|
| Ledger entry types | Add enum + validators + tests | Mutate existing rows |
|
|
| Balance source | Always SUM(ledger) | Add mutable balance column |
|
|
| Gift cards | Issue via 7.7 on top of wallet or separate ledger | Bypass wallet ledger for stored value without docs |
|
|
|
|
## Known Limitations
|
|
|
|
- No payment-provider settlement
|
|
- Gift cards deferred to 7.7
|
|
- No auto freeze/close scheduler
|
|
|
|
## Migration Notes
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Alembic revision(s) | `0007_phase_76_wallet` |
|
|
| Upgrade steps | `alembic upgrade head` in loyalty service |
|
|
| Downgrade support | Yes |
|
|
| Breaking changes | None (additive) |
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Type | Required for |
|
|
| --- | --- | --- |
|
|
| loyalty-7.5 | Phase | Prior engines + programs/members |
|
|
| shared-lib | Library | Events, security, exceptions |
|
|
|
|
## Next Phase Entry
|
|
|
|
1. This handover + [loyalty-phase-7-6.md](../loyalty-phase-7-6.md)
|
|
2. Build Gift Card Platform; keep ledger immutability
|
|
3. Suggested next: `loyalty-7.7` Gift Card Platform
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Recommended next phase | loyalty-7.7 |
|
|
| Blockers for next phase | None |
|
|
| Entry checklist | Read 7.6 handover; never mutate wallet balances directly |
|
|
|
|
## Completion Sign-Off
|
|
|
|
- [x] Quality gates passed
|
|
- [x] Tests green (114)
|
|
- [x] Documentation updated
|
|
- [x] Progress / next-steps / registries updated
|
|
- [x] Service Snapshot regenerated
|
|
|
|
## Related Documents
|
|
|
|
- [loyalty-phase-7-6.md](../loyalty-phase-7-6.md)
|
|
- [loyalty-phase-7-5.md](../loyalty-phase-7-5.md)
|
|
- [ADR-011](../architecture/adr/ADR-011.md)
|