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.

4.0 KiB Raw Blame History Unescape Escape