96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
# Phase Handover — Loyalty 7.3 Rewards Engine
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Phase ID | loyalty-7.3 |
|
|
| Title | Rewards Engine |
|
|
| Status | Complete |
|
|
| Service(s) | loyalty (`loyalty-service`, port 8004) |
|
|
| Version | 0.7.3.0 |
|
|
| Date | 2026-07-26 |
|
|
| ADR(s) | ADR-001, ADR-003, ADR-006, ADR-011 |
|
|
|
|
## Reusable Components
|
|
|
|
| Component | Location | Reuse notes |
|
|
| --- | --- | --- |
|
|
| RewardRedemption | `app/models/rewards.py` | Lifecycle + ledger linkage pattern |
|
|
| RewardsEngineService | `app/services/rewards_engine.py` | Compose with PointEngine via `auto_commit=False` |
|
|
| PointEngine auto_commit | `app/services/point_engine.py` | Required for multi-aggregate transactions |
|
|
|
|
## Public APIs
|
|
|
|
| Method | Path | Auth / Permission | Notes |
|
|
| --- | --- | --- | --- |
|
|
| POST | `/api/v1/rewards/{id}/redeem` | `loyalty.rewards.redeem` | Debits points; pending |
|
|
| GET | `/api/v1/rewards/{id}/redemptions` | `loyalty.redemptions.view` | Per-reward list |
|
|
| GET | `/api/v1/redemptions` | `loyalty.redemptions.view` | Filtered list |
|
|
| GET | `/api/v1/redemptions/{id}` | `loyalty.redemptions.view` | Detail |
|
|
| POST | `/api/v1/redemptions/{id}/fulfill` | `loyalty.rewards.fulfill` | pending→fulfilled |
|
|
| POST | `/api/v1/redemptions/{id}/cancel` | `loyalty.rewards.cancel` | Refunds points |
|
|
|
|
## Events
|
|
|
|
| Event type | Domain / Integration | Payload summary | Version |
|
|
| --- | --- | --- | --- |
|
|
| `loyalty.reward.redeemed` | Domain | redemption + reward + points | 1 |
|
|
| `loyalty.reward.fulfilled` | Domain | redemption id | 1 |
|
|
| `loyalty.reward.redemption_cancelled` | Domain | redemption + refund | 1 |
|
|
|
|
## Extension Points
|
|
|
|
| Extension point | How to extend | Forbidden uses |
|
|
| --- | --- | --- |
|
|
| Eligibility | Extend validators | Bypass PointEngine for paid rewards |
|
|
| Campaign grants | Call RewardsEngine from 7.4 | Direct balance mutation |
|
|
| Inventory | stock_limit / max_per_member | Negative redeemed_count |
|
|
|
|
## Known Limitations
|
|
|
|
- No scheduled redemption expiry
|
|
- No external partner fulfillment callbacks (7.9)
|
|
|
|
## Migration Notes
|
|
|
|
| Item | Detail |
|
|
| --- | --- |
|
|
| Alembic revision(s) | `0004_phase_73_rewards` |
|
|
| Upgrade steps | `alembic upgrade head` |
|
|
| Downgrade support | Yes |
|
|
| Breaking changes | None (additive) |
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Type | Required for |
|
|
| --- | --- | --- |
|
|
| loyalty-7.2 | Phase | PointEngine ledger |
|
|
| shared-lib | Library | Events, security, exceptions |
|
|
|
|
## Next Phase Entry
|
|
|
|
1. This handover + [loyalty-phase-7-3.md](../loyalty-phase-7-3.md)
|
|
2. Build Campaign Engine; grant points/rewards only via PointEngine / RewardsEngine
|
|
3. Suggested next: `loyalty-7.4` Campaign Engine
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Recommended next phase | loyalty-7.4 |
|
|
| Blockers for next phase | None |
|
|
| Entry checklist | Keep ledger immutable; reuse RewardsEngine + PointEngine |
|
|
|
|
## Completion Sign-Off
|
|
|
|
- [x] Quality gates passed
|
|
- [x] Tests green (72)
|
|
- [x] Documentation updated
|
|
- [x] Progress / next-steps / registries updated
|
|
- [x] Service Snapshot regenerated
|
|
|
|
## Related Documents
|
|
|
|
- [loyalty-phase-7-3.md](../loyalty-phase-7-3.md)
|
|
- [loyalty-phase-7-2.md](../loyalty-phase-7-2.md)
|
|
- [ADR-011](../architecture/adr/ADR-011.md)
|