e41ecfad4c
Include Loyalty/Communication/Sports Center backends and registry updates alongside production nginx and compose wiring. Co-authored-by: Cursor <cursoragent@cursor.com>
82 lines
2.5 KiB
Markdown
82 lines
2.5 KiB
Markdown
# Loyalty Service — Enterprise Loyalty Platform
|
|
|
|
> Phase 7.1 Membership Engine complete (foundation 7.0 + lifecycle). 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 shell (no mutable balance) | Notification delivery |
|
|
| Reward catalog shell | Analytics store (later) |
|
|
| Campaign shell (versioned rules later) | Identity / Wallet UI / Gift card engine (later phases) |
|
|
| Loyalty audit trail | |
|
|
|
|
## Boundaries
|
|
|
|
- Independent database: `loyalty_db` (ADR-001, ADR-011)
|
|
- Row-level tenancy via `tenant_id` from request context (ADR-003)
|
|
- Membership lifecycle transitions validated in `MembershipEngineService`
|
|
- Program soft-delete rejected while blocking members exist
|
|
- Direct balance modification is prohibited — ledger in Phase 7.2
|
|
- 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
|
|
|
|
## Structure
|
|
|
|
```
|
|
app/
|
|
api/v1/ # Loyalty HTTP APIs only
|
|
models/ # foundation aggregates
|
|
repositories/
|
|
services/
|
|
validators/
|
|
schemas/
|
|
events/
|
|
permissions/
|
|
providers/
|
|
tests/
|
|
alembic/versions/0001_initial.py
|
|
```
|
|
|
|
## 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` |
|
|
| Rewards | `/api/v1/rewards` |
|
|
| Campaigns | `/api/v1/campaigns` |
|
|
| Health | `/health` |
|
|
|
|
## Permissions
|
|
|
|
`loyalty.*` including `loyalty.programs.*`, `loyalty.tiers.*`, `loyalty.members.*`,
|
|
`loyalty.point_accounts.*`, `loyalty.rewards.*`, `loyalty.campaigns.*`, `loyalty.audit.*`
|
|
|
|
## 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.0](../../../docs/loyalty-phase-7-0.md)
|
|
- [Module Registry](../../../docs/module-registry.md#loyalty)
|
|
- [ADR-011](../../../docs/architecture/adr/ADR-011.md)
|
|
- [Architecture](../../../docs/architecture/architecture.md)
|