TorbatYar/docs/phase-handover/phase-7-3.md

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
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

• Quality gates passed
• Tests green (72)
• Documentation updated
• Progress / next-steps / registries updated
• Service Snapshot regenerated

Related Documents

• loyalty-phase-7-3.md
• loyalty-phase-7-2.md
• ADR-011