67 lines
2.5 KiB
Markdown
67 lines
2.5 KiB
Markdown
# 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 | |
|
||
|
||
## Boundaries
|
||
|
||
- 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 Prefix
|
||
|
||
`/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` |
|
||
|
||
## Permissions
|
||
|
||
`loyalty.*` including points, rewards, campaigns, referrals, wallets, audit trees.
|
||
|
||
## Run locally
|
||
|
||
```bash
|
||
cd backend/services/loyalty
|
||
pip install -r requirements.txt
|
||
pytest -q
|
||
uvicorn app.main:app --port 8004 --reload
|
||
```
|
||
|
||
## Related Documents
|
||
|
||
- [Phase 7.6](../../../docs/loyalty-phase-7-6.md)
|
||
- [Handover 7.6](../../../docs/phase-handover/phase-7-6.md)
|
||
- [Service Snapshot](../../../docs/service-snapshots/loyalty.yaml)
|
||
- [Module Registry](../../../docs/module-registry.md#loyalty)
|
||
- [ADR-011](../../../docs/architecture/adr/ADR-011.md)
|