Admin User v1

docs/changes/2024-admin-roadmap.md

@@ -0,0 +1,45 @@
+# Admin Role & UI Implementation Plan
+
+Context: extend MotoVaultPro with an administrative user model, cross-tenant CRUD authority, and surfaced controls within the existing settings experience. Follow phases in order; each phase is shippable and assumes Docker-based validation per `CLAUDE.md`.
+
+## Phase 1 – Access Control Foundations
+- Create `backend/src/features/admin/` capsule scaffolding (api/, domain/, data/, migrations/, tests/).
+- Add migration `001_create_admin_users.sql` for table `admin_users (auth0_sub PK, email, created_at, created_by, revoked_at)`.
+- Seed first record (`admin@motorvaultpro.com`, `created_by = system`) via migration or bootstrap script.
+- Extend auth plugin flow to hydrate `request.userContext` containing `userId`, `email`, `isAdmin`, `adminRecord`.
+- Add reusable guard `authorizeAdmin` in `backend/src/core/middleware/admin-guard.ts`; return 403 with `{ error: 'Forbidden', message: 'Admin access required' }`.
+- Unit tests: guard behavior, context resolver, seed idempotency.
+
+## Phase 2 – Admin Management APIs
+- Implement `/api/admin/admins` controller with list/add/revoke/reinstate endpoints; enforce “at least one active admin” rule in repository.
+- Add audit logging via existing `logger` (log `actorAdminId`, `targetAdminId`, `action`, `context`).
+- Provide read-only `/api/admin/users` for user summaries (reusing existing repositories, no data mutation yet).
+- Integration tests validating: guard rejects non-admins, add admin, revoke admin while preventing last admin removal.
+
+## Phase 3 – Platform Catalog CRUD
+- Add service `vehicleCatalog.service.ts` under admin feature to manage `vehicles.make|model|model_year|trim|engine|trim_engine`.
+- Expose `/api/admin/catalog/...` endpoints for hierarchical CRUD; wrap mutations in transactions with referential validation.
+- On write, call new cache helper in `backend/src/features/platform/domain/platform-cache.service.ts` to invalidate keys `platform:*`.
+- Record admin change history in table `platform_change_log` (migration `002_create_platform_change_log.sql`).
+- Tests: unit (service + cache invalidation), integration (create/update/delete + redis key flush assertions).
+
+## Phase 4 – Station Oversight
+- Implement `/api/admin/stations` for global station CRUD and `/api/admin/users/:userId/stations` to manage saved stations.
+- Ensure mutations update `stations` and `saved_stations` tables with soft delete semantics and invalidation of `stations:saved:{userId}` plus cached search keys.
+- Provide optional `force=true` query to hard delete (document usage, default soft delete).
+- Tests covering cache busting, permission enforcement, and happy-path CRUD.
+
+## Phase 5 – UI Integration (Settings-Based)
+- Create hook `frontend/src/core/auth/useAdminAccess.ts` that calls `/auth/verify`, caches `isAdmin`, handles loading/error states.
+- Desktop: update `frontend/src/pages/SettingsPage.tsx` to inject an “Admin Console” card when `isAdmin` true (links to admin subroutes) and display access CTA otherwise.
+- Mobile: add admin section to `frontend/src/features/settings/mobile/MobileSettingsScreen.tsx` using existing `GlassCard` pattern; hide entirely for non-admins.
+- Route stubs (e.g. `/garage/settings/admin/*`) should lazy-load forthcoming admin dashboards; guard them with `useAdminAccess`.
+- Frontend tests (Jest/RTL) verifying conditional rendering on admin vs non-admin contexts.
+
+## Phase 6 – Quality Gates & Documentation
+- Run backend/ frontend lint + tests inside containers (`make rebuild`, `make logs`, `make test-backend`, `docker compose exec mvp-frontend npm test`).
+- Author `docs/ADMIN.md` summarizing role management workflow, API catalog, cache rules, and operational safeguards.
+- Update existing docs (`docs/PLATFORM-SERVICES.md`, `docs/VEHICLES-API.md`, `docs/GAS-STATIONS.md`, `docs/README.md`) with admin references.
+- Prepare release checklist: database migration order, seed verification for initial admin, smoke tests on both device classes (mobile + desktop), rollback notes.
+- Confirm Traefik `/auth/verify` headers expose admin flag where needed for downstream services.
+