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

Phase Handover — Loyalty 7.2 Point Engine

Metadata

Field	Value
Phase ID	loyalty-7.2
Title	Point Engine (immutable ledger)
Status	Complete
Service(s)	loyalty (loyalty-service, port 8004)
Version	0.7.2.0
Date	2026-07-26
ADR(s)	ADR-001, ADR-003, ADR-006, ADR-011

Reusable Components

Component	Location	Reuse notes
PointLedgerEntry	app/models/ledger.py	Append-only pattern for wallet/gift (7.6/7.7)
PointLedgerRepository	app/repositories/ledger.py	Balance sum + filtered list
PointEngineService	app/services/point_engine.py	Earn/redeem/adjust/expire orchestration
Ledger validators	app/validators/ledger.py	Signed amounts + open-account checks

Public APIs

Method	Path	Auth / Permission	Notes
GET	/api/v1/point-accounts/{id}/balance	loyalty.points.view	Computed balance
GET	/api/v1/point-accounts/{id}/ledger	loyalty.points.view	Paginated entries
POST	/api/v1/point-accounts/{id}/earn	loyalty.points.earn	Idempotent optional
POST	/api/v1/point-accounts/{id}/redeem	loyalty.points.redeem	Rejects insufficient
POST	/api/v1/point-accounts/{id}/adjust	loyalty.points.adjust	Signed delta
POST	/api/v1/point-accounts/{id}/expire-points	loyalty.points.expire	Debit expire

Events

Event type	Domain / Integration	Payload summary	Version
loyalty.points.earned	Domain	account, amount, balance_after	1
loyalty.points.redeemed	Domain	account, amount, balance_after	1
loyalty.points.adjusted	Domain	account, amount, balance_after	1
loyalty.points.expired	Domain	account, amount, balance_after	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
Reward redemption	Call PointEngine from 7.3	Bypass ledger for rewards

Known Limitations

• No scheduled expire worker
• No per-lot FIFO expiration
• Member transfer does not move ledger rows

Migration Notes

Item	Detail
Alembic revision(s)	0003_phase_72_points
Upgrade steps	alembic upgrade head in loyalty service
Downgrade support	Yes (drops table)
Data backfill	None
Breaking changes	None (additive)

Dependencies

Dependency	Type	Required for
loyalty-7.1	Phase	Membership + point accounts
shared-lib	Library	Events, security, exceptions

Next Phase Entry

1. This handover + loyalty-phase-7-2.md
2. Service snapshot + manifests
3. Build Rewards Engine on top of PointEngine redeem — do not mutate balances directly
4. Suggested next: loyalty-7.3 Rewards Engine

Field	Value
Recommended next phase	loyalty-7.3
Blockers for next phase	None
Entry checklist	Read 7.2 handover; keep ledger immutable; reuse PointEngineService

Completion Sign-Off

• Quality gates passed
• Tests green (61)
• Documentation updated
• Progress / next-steps / registries updated
• Service Snapshot regenerated
• No TODO for claimed deliverables

Related Documents

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