# Specification Implementation Matrix

| Requirement | Implementation |
|---|---|
| Laravel 13 API-first + `/api/v1` | `composer.json`, `routes/api.php` |
| Sanctum mobile bearer auth | `AuthController`, Sanctum token table/config |
| Device-named/revocable tokens | login device name + current/all-device logout |
| Staff password reset + email verification | Auth endpoints, reset-token storage, signed verification |
| Active/suspended account enforcement | `EnsureUserActive`; tokens revoked when users are disabled |
| Admin/doctor/assistant/patient roles | enums, middleware, policies, `AccessService` |
| Admin user/role management | `/admin/users`, `/admin/roles` |
| Assistant assignment permissions | DB flags + server-side checks for patient/book/check-in/reschedule/cancel/edit/payment |
| Organization/tenant isolation | organization foreign keys and scoped access throughout APIs |
| Multiple doctors/locations | admin CRUD + doctor-location assignment CRUD |
| Fees, slot length, booking window, cancellation cutoff | `doctor_location_assignments` + services |
| Multiple daily working sessions | `doctor_working_hours` APIs + `ScheduleService` |
| Leave/holiday/blocked/special hours | schedule exception CRUD + availability subtraction |
| Server-computed availability | `GET /doctors/{doctor}/availability` |
| Patient create/edit/search/archive | patient APIs + policies/service |
| WhatsApp checkbox behavior | `has_whatsapp`, automatic phone default/normalization |
| Duplicate-patient warning + admin override | `PATIENT_DUPLICATE_POSSIBLE`; only admins can force duplicate |
| Visit metrics derived from completed visits | `PatientMetricsService` |
| Appointment booking/reschedule/cancel | transactional `AppointmentService` |
| Backfill/past appointment control | explicit `allow_backfill`; admin only + audit reason |
| Fee derivation + authorized discounts | server-side doctor-location fee calculation |
| Double-booking protection | assignment row lock + overlap check + MySQL race test |
| Appointment state machine/history | enums + immutable status histories + audit |
| Automatic/manual/editable token | `TokenService`, `QueueService`, queue unique index |
| Configurable token scope/range | organization settings (`doctor_location`/`location`, min/max/start) |
| Token concurrency protection | row-locked queue counter + MySQL process concurrency test |
| 04 -> 05 -> 06 regression | demo fixture + `QueueRegressionTest` |
| Queue/appointment synchronized state | queue service and appointment service transactional synchronization |
| Partial/full payment | transaction-backed `PaymentService` |
| Configurable payment methods | organization setting + request/service validation |
| Payment/provider idempotency | unique client/provider references + service checks/tests |
| Waiver + refund | permission/reason checks, negative refunds linked to original |
| Receipt numbers | unique payment/waiver/refund receipt identifiers |
| Push (Expo/FCM/APNs) | provider router/adapters + device tokens |
| WhatsApp Cloud API | provider adapter + WhatsApp/consent rules |
| Email/in-app notifications | mail provider + Laravel database notifications |
| Reminder idempotency on reschedule | schedule-versioned idempotency keys + supersession |
| Reminder retries/provider failures | queued job retries/backoff, failed/skipped/sent logs, stale processing recovery |
| Concurrent duplicate reminder suppression | per-idempotency-key cache/Redis delivery lock |
| Notification preferences/consent | preference endpoints and channel enforcement |
| Audit logging + secret redaction | `AuditService`, audit endpoint, sensitive-key redaction |
| Assistant dashboard | `/dashboard` role payload |
| Doctor dashboard | `/dashboard` role payload |
| Patient dashboard | `/dashboard` role payload |
| Admin dashboard | `/admin/reports/dashboard` |
| Daily appointment report | `/admin/reports/appointments` |
| Queue wait/token report | `/admin/reports/queue` |
| Doctor utilization | `/admin/reports/doctor-utilization` |
| Patient/new-returning report | `/admin/reports/patients` |
| Revenue by date/doctor/location/method | `/admin/reports/revenue` |
| Outstanding/partial payments | `/admin/reports/outstanding-payments` |
| Refund report | `/admin/reports/refunds` |
| Cancellation/no-show report | `/admin/reports/cancellations` |
| Assistant activity | `/admin/reports/assistant-activity` |
| Notification delivery/failure | `/admin/reports/notifications` |
| CSV report exports | `/admin/reports/export` |
| Consistent success/error envelopes | `ApiResponse`, exception rendering |
| Rate limiting | login/API/write limiters |
| HTTPS enforcement in production | `RequireHttpsInProduction`, `CLINIC_ENFORCE_HTTPS` |
| Health + operational metrics | `/up`, `/admin/system/metrics` |
| Database indexes/unique constraints | migrations, including queue/idempotency/provider/user-link uniques |
| Production seed strategy | `EssentialSeeder`, `clinic:create-admin`; demo seeder blocked by environment workflow |
| Feature/unit test suite | `tests/Feature/Api/V1`, `tests/Unit` |
| True MySQL concurrency suite | `tests/Concurrency`, `phpunit.mysql.xml` |
| Static analysis/formatting | Larastan/PHPStan + Pint |
| CI quality gates | `.github/workflows/ci.yml` |
| OpenAPI route-coverage gate | `clinic:check-openapi`, `docs/openapi.yaml` |
| ERD/schema docs | `docs/ERD.md` |
| Provider setup | `docs/PROVIDERS.md` |
| Mobile integration/error mapping | `docs/MOBILE_INTEGRATION.md`, `docs/ERROR_CODES.md` |
| Backup/restore | `docs/BACKUP_RESTORE.md` |
| Data-retention/privacy launch rules | `docs/DATA_RETENTION_PRIVACY.md` |
| Deployment/rollback | `docs/DEPLOYMENT.md` |

## External production acceptance

The codebase contains the required integration points and quality gates. Actual SMTP/WhatsApp/push credentials, HTTPS termination, Redis/worker supervision, production MySQL backup restore, monitoring/alerting and load/security behavior must still be validated in the target hosting environment before real patient data is accepted. These are environment acceptance activities rather than missing source-code modules.
