Samir Boulahtit
f141cc4e6a
Move 39 documentation files from top-level docs/ into each module's docs/ folder, accessible via symlinks from docs/modules/. Create data-model.md files for 10 modules with full schema documentation. Replace originals with redirect stubs. Remove empty guide stubs. Modules migrated: tenancy, billing, loyalty, marketplace, orders, messaging, cms, catalog, inventory, hosting, prospecting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
111 lines
4.3 KiB
Markdown
111 lines
4.3 KiB
Markdown
# Loyalty Programs
|
|
|
|
Stamp-based and points-based loyalty programs with Google Wallet and Apple Wallet integration. Includes anti-fraud features like staff PINs, cooldown periods, and daily limits.
|
|
|
|
## Overview
|
|
|
|
| Aspect | Detail |
|
|
|--------|--------|
|
|
| Code | `loyalty` |
|
|
| Classification | Optional |
|
|
| Dependencies | `customers` |
|
|
| Status | Active |
|
|
|
|
## Features
|
|
|
|
- `loyalty_stamps` — Stamp-based loyalty (collect N, get reward)
|
|
- `loyalty_points` — Points-based loyalty (earn per euro spent)
|
|
- `loyalty_hybrid` — Combined stamps and points programs
|
|
- `loyalty_cards` — Digital loyalty card management
|
|
- `loyalty_enrollment` — Customer enrollment flow
|
|
- `loyalty_staff_pins` — Staff PIN verification
|
|
- `loyalty_anti_fraud` — Cooldown periods, daily limits, lockout protection
|
|
- `loyalty_google_wallet` — Google Wallet pass integration
|
|
- `loyalty_apple_wallet` — Apple Wallet pass integration
|
|
- `loyalty_stats` — Program statistics
|
|
- `loyalty_reports` — Loyalty reporting
|
|
|
|
## Permissions
|
|
|
|
| Permission | Description |
|
|
|------------|-------------|
|
|
| `loyalty.view_programs` | View loyalty programs |
|
|
| `loyalty.manage_programs` | Create/edit loyalty programs |
|
|
| `loyalty.view_rewards` | View rewards |
|
|
| `loyalty.manage_rewards` | Manage rewards |
|
|
|
|
## Data Model
|
|
|
|
See [Data Model](data-model.md) for full entity relationships.
|
|
|
|
- **LoyaltyProgram** — Program configuration (type, targets, branding)
|
|
- **LoyaltyCard** — Customer cards with stamp/point balances
|
|
- **LoyaltyTransaction** — Immutable audit log of all operations
|
|
- **StaffPin** — Hashed PINs for fraud prevention
|
|
- **MerchantLoyaltySettings** — Admin-controlled merchant settings
|
|
- **AppleDeviceRegistration** — Apple Wallet push notification tokens
|
|
|
|
## API Endpoints
|
|
|
|
### Store Endpoints (`/api/v1/store/loyalty/`)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/program` | Get store's loyalty program |
|
|
| `POST` | `/program` | Create loyalty program |
|
|
| `PATCH` | `/program` | Update loyalty program |
|
|
| `GET` | `/stats` | Get program statistics |
|
|
| `GET` | `/cards` | List customer cards |
|
|
| `POST` | `/cards/enroll` | Enroll customer in program |
|
|
| `POST` | `/stamp` | Add stamp to card |
|
|
| `POST` | `/stamp/redeem` | Redeem stamps for reward |
|
|
| `POST` | `/points` | Earn points from purchase |
|
|
| `POST` | `/points/redeem` | Redeem points for reward |
|
|
| `*` | `/pins/*` | Staff PIN management |
|
|
|
|
### Admin Endpoints (`/api/v1/admin/loyalty/`)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/programs` | List all loyalty programs |
|
|
| `GET` | `/programs/{id}` | Get specific program |
|
|
| `GET` | `/stats` | Platform-wide statistics |
|
|
|
|
### Storefront Endpoints (`/api/v1/storefront/loyalty/`)
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| `GET` | `/card` | Get customer's loyalty card |
|
|
| `GET` | `/transactions` | Transaction history |
|
|
| `POST` | `/enroll` | Self-enrollment |
|
|
|
|
## Scheduled Tasks
|
|
|
|
| Task | Schedule | Description |
|
|
|------|----------|-------------|
|
|
| `loyalty.sync_wallet_passes` | Hourly | Sync cards that missed real-time updates |
|
|
| `loyalty.expire_points` | Daily 02:00 | Expire points for inactive cards |
|
|
|
|
## Configuration
|
|
|
|
Environment variables (prefix: `LOYALTY_`):
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `LOYALTY_DEFAULT_COOLDOWN_MINUTES` | 15 | Cooldown between stamps |
|
|
| `LOYALTY_MAX_DAILY_STAMPS` | 5 | Max stamps per card per day |
|
|
| `LOYALTY_PIN_MAX_FAILED_ATTEMPTS` | 5 | PIN lockout threshold |
|
|
| `LOYALTY_PIN_LOCKOUT_MINUTES` | 30 | PIN lockout duration |
|
|
| `LOYALTY_DEFAULT_POINTS_PER_EURO` | 10 | Points earned per euro |
|
|
| `LOYALTY_GOOGLE_ISSUER_ID` | — | Google Wallet issuer ID |
|
|
| `LOYALTY_GOOGLE_SERVICE_ACCOUNT_JSON` | — | Google service account path |
|
|
| `LOYALTY_APPLE_*` | — | Apple Wallet certificate paths |
|
|
|
|
## Additional Documentation
|
|
|
|
- [Data Model](data-model.md) — Entity relationships and database schema
|
|
- [Business Logic](business-logic.md) — Anti-fraud system, wallet integration, enrollment flow
|
|
- [User Journeys](user-journeys.md) — Detailed user journey flows with dev/prod URLs
|
|
- [Program Analysis](program-analysis.md) — Business analysis and platform vision
|
|
- [UI Design](ui-design.md) — Admin and store interface mockups and implementation roadmap
|