Mortezakoohjani 071c484530 Ship Loyalty phases 7.2-7.6 (points through wallet) with production deploy.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-07-26 21:27:22 +03:30

Loyalty Service — Enterprise Loyalty Platform

Phase 7.6 Wallet complete (7.0–7.5 engines + immutable wallet ledger). Independent shared service — not part of CRM.

Reusable by Restaurant, Marketplace, Ecommerce, Academy, Booking, Healthcare, Salon, Gym, and future modules via API + Events only.

Ownership

Owns	Does not own
LoyaltyProgram, MembershipTier, Member + lifecycle	CRM sales entities
MembershipLifecycleEvent history	Accounting / Posting Engine
PointAccount + immutable `PointLedgerEntry`	Notification delivery
Reward catalog + `RewardRedemption` lifecycle	Analytics store (later)
Campaign engine + applications	Identity / Gift card UI (7.7+)
Referral programs / codes / attributions	Payment gateway settlement
WalletAccount + immutable `WalletLedgerEntry`
Loyalty audit trail

Independent database: loyalty_db (ADR-001, ADR-011)
Row-level tenancy via tenant_id from request context (ADR-003)
Point and wallet balances come only from immutable ledgers — never mutate a balance column
Soft delete releases unique keys so codes can be reused; audit via /api/v1/audit
Inter-service communication: REST + Events only (transactional outbox)
Platform providers are contracts only under app/providers/
Route permissions enforced (loyalty.*); invalid X-Tenant-ID rejected

/api/v1 on port 8004

Resource	Path
Programs	`/api/v1/programs`
Tiers	`/api/v1/tiers`
Members	`/api/v1/members`
Point accounts	`/api/v1/point-accounts` (+ ledger ops)
Rewards / Redemptions	`/api/v1/rewards`, `/api/v1/redemptions`
Campaigns	`/api/v1/campaigns`
Referrals	`/api/v1/referral-programs`, `/referral-codes`, `/referrals`
Wallets	`/api/v1/wallets` (+ `/balance`, `/ledger`, `/credit`, `/debit`, `/adjust`, `/transfer`)
Health	`/health`

loyalty.* including points, rewards, campaigns, referrals, wallets, audit trees.

cd backend/services/loyalty
pip install -r requirements.txt
pytest -q
uvicorn app.main:app --port 8004 --reload