# Step-by-step implementation guide

## Phase 1 — Run the core backend
1. Install Python 3.12+ and MySQL 8+.
2. Copy `.env.example` to `.env`.
3. Set the real MySQL password and a strong JWT secret.
4. Create/activate a virtual environment.
5. `pip install -r requirements.txt`
6. `alembic upgrade head`
7. `python seed.py`
8. `uvicorn app.main:app --reload`
9. Open `/docs`.
10. Login with the demo account and copy the access token.

## Phase 2 — Verify tenant isolation
- Create Brand A and Brand B users in the seed/data layer.
- Login as Brand A.
- Create/read a customer.
- Attempt to access Brand B customer IDs.
- The API must return 404/403 and never expose cross-tenant data.

## Phase 3 — Customer and loyalty flow
- Create a customer.
- Create a purchase transaction.
- Verify `transactions.points_earned`.
- Verify wallet balance.
- Verify wallet history.
- Verify customer `lifetime_points` and `points_balance`.

## Phase 4 — Reward flow
- Create a reward.
- Ensure customer has enough points.
- Redeem using a unique `Idempotency-Key`.
- Verify wallet debit, wallet_history, redemption, and stock decrement.
- Repeat the same key; no second debit should occur.

## Phase 5 — Complete the remaining enterprise modules
The supplied specification contains additional tables/modules not included in this compact runnable baseline:
stores, dealers, retailers, qr_codes, serial_numbers, invoices, coupons, gifts,
segments, segment_customers, campaigns, campaign_logs, sms_logs, whatsapp_logs,
rcs_logs, push_logs, notifications, api_logs.

Add each module using the same pattern:
model -> schema -> repository -> service -> route -> migration -> tests.

## Phase 6 — Messaging
Keep business logic provider-neutral. Implement Demo providers first, then add real
SMS/WhatsApp/RCS/Email adapters. Move bulk sends to Celery; never send thousands of
messages inside a request.

## Phase 7 — Production hardening
- Add request IDs and structured JSON logs.
- Add API log persistence without storing passwords/OTP/API keys.
- Add rate limiting with Redis.
- Add secure headers and production CORS.
- Add database indexes and run EXPLAIN on high-volume queries.
- Add integration/concurrency tests.
- Rotate JWT secrets and provider credentials through the secret manager.
- Put Nginx in front of Gunicorn/Uvicorn workers.

## Important
This archive is a runnable core backend, not a claim that every enterprise module from
the 1,417-line specification has been fully implemented. The remaining modules are
intentionally isolated so your team can build them without changing the tenant,
authentication, wallet, loyalty, or API conventions.