Admin User v1

2025-11-05 19:04:06 -06:00
parent e4e7e32a4f
commit 8174e0d5f9
48 changed files with 11289 additions and 1112 deletions
--- a/docs/ADMIN-DEPLOYMENT-CHECKLIST.md
+++ b/docs/ADMIN-DEPLOYMENT-CHECKLIST.md
@@ -0,0 +1,343 @@
+# Admin Feature Deployment Checklist
+
+Production deployment checklist for the Admin feature (Phases 1-5 complete).
+
+## Pre-Deployment Verification (Phase 6)
+
+### Code Quality Gates
+
+- [ ] **TypeScript compilation**: `npm run build` - Zero errors
+- [ ] **Linting**: `npm run lint` - Zero warnings
+- [ ] **Backend tests**: `npm test -- features/admin` - All passing
+- [ ] **Frontend tests**: `npm test` - All passing
+- [ ] **Container builds**: `make rebuild` - Success
+- [ ] **Backend startup**: `make start` - Server running on port 3001
+- [ ] **Health checks**: `curl https://motovaultpro.com/api/health` - 200 OK
+- [ ] **Frontend build**: Vite build completes in <20 seconds
+- [ ] **No deprecated code**: All old code related to admin removed
+- [ ] **Documentation complete**: ADMIN.md, feature READMEs updated
+
+### Security Verification
+
+- [ ] **Parameterized queries**: Grep confirms no SQL concatenation in admin feature
+- [ ] **Input validation**: All endpoints validate with Zod schemas
+- [ ] **HTTPS only**: Verify Traefik configured for HTTPS
+- [ ] **Auth0 integration**: Dev/prod Auth0 domains match configuration
+- [ ] **JWT validation**: Token verification working in auth plugin
+- [ ] **Admin guard**: `fastify.requireAdmin` blocking non-admins with 403
+- [ ] **Audit logging**: All admin actions logged to database
+- [ ] **Last admin protection**: Confirmed system cannot revoke last admin
+
+### Database Verification
+
+- [ ] **Migrations exist**: Both migration files present
+  - `backend/src/features/admin/migrations/001_create_admin_users.sql`
+  - `backend/src/features/admin/migrations/002_create_platform_change_log.sql`
+- [ ] **Tables created**: Run migrations verify
+  ```bash
+  docker compose exec mvp-backend psql -U postgres -d motovaultpro -c \
+    "\dt admin_users admin_audit_logs platform_change_log"
+  ```
+- [ ] **Initial admin seeded**: Verify bootstrap admin exists
+  ```bash
+  docker compose exec mvp-backend psql -U postgres -d motovaultpro -c \
+    "SELECT email, role, revoked_at FROM admin_users WHERE auth0_sub = 'system|bootstrap';"
+  ```
+- [ ] **Indexes created**: Verify all indexes exist
+  ```bash
+  docker compose exec mvp-backend psql -U postgres -d motovaultpro -c \
+    "SELECT tablename, indexname FROM pg_indexes WHERE tablename IN ('admin_users', 'admin_audit_logs', 'platform_change_log');"
+  ```
+- [ ] **Foreign keys configured**: Cascade rules work correctly
+- [ ] **Backup tested**: Database backup includes new tables
+
+### API Verification
+
+#### Phase 2 Endpoints (Admin Management)
+
+- [ ] **GET /api/admin/admins** - Returns all admins
+  ```bash
+  curl -H "Authorization: Bearer $JWT" https://motovaultpro.com/api/admin/admins
+  ```
+- [ ] **POST /api/admin/admins** - Creates admin (with valid email)
+- [ ] **PATCH /api/admin/admins/:auth0Sub/revoke** - Revokes admin
+- [ ] **PATCH /api/admin/admins/:auth0Sub/reinstate** - Reinstates admin
+- [ ] **GET /api/admin/audit-logs** - Returns audit trail
+- [ ] **403 Forbidden** - Non-admin user blocked from all endpoints
+
+#### Phase 3 Endpoints (Catalog CRUD)
+
+- [ ] **GET /api/admin/catalog/makes** - List makes
+- [ ] **POST /api/admin/catalog/makes** - Create make
+- [ ] **PUT /api/admin/catalog/makes/:makeId** - Update make
+- [ ] **DELETE /api/admin/catalog/makes/:makeId** - Delete make
+- [ ] **GET /api/admin/catalog/change-logs** - View change history
+- [ ] **Cache invalidation**: Redis keys flushed after mutations
+- [ ] **Transaction support**: Failed mutations rollback cleanly
+
+#### Phase 4 Endpoints (Station Oversight)
+
+- [ ] **GET /api/admin/stations** - List all stations
+- [ ] **POST /api/admin/stations** - Create station
+- [ ] **PUT /api/admin/stations/:stationId** - Update station
+- [ ] **DELETE /api/admin/stations/:stationId** - Soft delete (default)
+- [ ] **DELETE /api/admin/stations/:stationId?force=true** - Hard delete
+- [ ] **GET /api/admin/users/:userId/stations** - User's saved stations
+- [ ] **DELETE /api/admin/users/:userId/stations/:stationId** - Remove user station
+- [ ] **Cache invalidation**: `mvp:stations:*` keys flushed
+
+### Frontend Verification (Mobile + Desktop)
+
+#### Desktop Verification
+
+- [ ] **Admin console visible** - SettingsPage shows "Admin Console" card when admin
+- [ ] **Non-admin message** - Non-admin users see "Not authorized" message
+- [ ] **Navigation links work** - Admin/Users, Admin/Catalog, Admin/Stations accessible
+- [ ] **Admin pages load** - Route guards working, 403 page for non-admins
+- [ ] **useAdminAccess hook** - Loading state shows spinner while checking admin status
+
+#### Mobile Verification (375px viewport)
+
+- [ ] **Admin section visible** - MobileSettingsScreen shows admin section when admin
+- [ ] **Admin section hidden** - Completely hidden for non-admin users
+- [ ] **Touch targets** - All buttons are ≥44px height
+- [ ] **Mobile pages load** - Routes accessible on mobile
+- [ ] **No layout issues** - Text readable, buttons tappable on 375px screen
+- [ ] **Loading states** - Proper spinner on admin data loads
+
+#### Responsive Design
+
+- [ ] **Desktop 1920px** - All pages display correctly
+- [ ] **Mobile 375px** - All pages responsive, no horizontal scroll
+- [ ] **Tablet 768px** - Intermediate sizing works
+- [ ] **No console errors** - Check browser DevTools
+- [ ] **Performance acceptable** - Page load <3s on mobile
+
+### Integration Testing
+
+- [ ] **End-to-end workflow**:
+  1. Login as admin
+  2. Navigate to admin console
+  3. Create new admin user
+  4. Verify audit log entry
+  5. Revoke new admin
+  6. Verify last admin protection prevents revocation of only remaining admin
+  7. Create catalog item
+  8. Verify cache invalidation
+  9. Create station
+  10. Verify soft/hard delete behavior
+
+- [ ] **Error handling**:
+  - [ ] 400 Bad Request - Invalid input (test with malformed JSON)
+  - [ ] 403 Forbidden - Non-admin access attempt
+  - [ ] 404 Not Found - Nonexistent resource
+  - [ ] 409 Conflict - Referential integrity violation
+  - [ ] 500 Internal Server Error - Database connection failure
+
+- [ ] **Audit trail verification**:
+  - [ ] All admin management actions logged
+  - [ ] All catalog mutations recorded with old/new values
+  - [ ] All station operations tracked
+  - [ ] Actor admin ID correctly stored
+
+### Performance Verification
+
+- [ ] **Query performance**: Admin list returns <100ms (verify in logs)
+- [ ] **Large dataset handling**: Test with 1000+ audit logs
+- [ ] **Cache efficiency**: Repeated queries use cache
+- [ ] **No N+1 queries**: Verify in query logs
+- [ ] **Pagination works**: Limit/offset parameters functioning
+
+### Monitoring & Logging
+
+- [ ] **Admin logs visible**: `make logs | grep -i admin` shows entries
+- [ ] **Audit trail stored**: `SELECT COUNT(*) FROM admin_audit_logs;` > 0
+- [ ] **Error logging**: Failed operations logged with context
+- [ ] **Performance metrics**: Slow queries logged
+
+### Documentation
+
+- [ ] **ADMIN.md complete**: All endpoints documented
+- [ ] **API examples provided**: Sample requests/responses included
+- [ ] **Security notes documented**: Input validation, parameterized queries explained
+- [ ] **Deployment section**: Clear instructions for operators
+- [ ] **Troubleshooting guide**: Common issues and solutions
+- [ ] **Backend feature README**: Phase descriptions, extending guide
+- [ ] **docs/README.md updated**: Admin references added
+
+## Deployment Steps
+
+### 1. Pre-Deployment
+
+```bash
+# Verify all tests pass
+npm test -- features/admin
+docker compose exec mvp-frontend npm test
+
+# Verify builds succeed
+make rebuild
+
+# Backup database
+./scripts/backup-database.sh
+
+# Verify rollback plan documented
+cat docs/ADMIN.md | grep -A 20 "## Rollback"
+```
+
+### 2. Database Migration
+
+```bash
+# Run migrations (automatic on container startup, or manual)
+docker compose exec mvp-backend npm run migrate
+
+# Verify tables and seed data
+docker compose exec mvp-backend psql -U postgres -d motovaultpro -c \
+  "SELECT COUNT(*) FROM admin_users; SELECT COUNT(*) FROM admin_audit_logs;"
+```
+
+### 3. Container Deployment
+
+```bash
+# Stop current containers
+docker compose down
+
+# Pull latest code
+git pull origin main
+
+# Rebuild containers with latest code
+make rebuild
+
+# Start services
+make start
+
+# Verify health
+make logs | grep -i "Backend is healthy"
+curl https://motovaultpro.com/api/health
+```
+
+### 4. Post-Deployment Verification
+
+```bash
+# Verify health endpoints
+curl https://motovaultpro.com/api/health | jq .features
+
+# Test admin endpoint (with valid JWT)
+curl -H "Authorization: Bearer $JWT" \
+  https://motovaultpro.com/api/admin/admins | jq .total
+
+# Verify frontend loads
+curl -s https://motovaultpro.com | grep -q "motovaultpro" && echo "Frontend OK"
+
+# Check logs for errors
+make logs | grep -i error | head -20
+```
+
+### 5. Smoke Tests (Manual)
+
+1. **Desktop**:
+   - Visit https://motovaultpro.com
+   - Login with admin account
+   - Navigate to Settings
+   - Verify "Admin Console" card visible
+   - Click "User Management"
+   - Verify admin list loads
+
+2. **Mobile**:
+   - Open https://motovaultpro.com on mobile device or dev tools (375px)
+   - Login with admin account
+   - Navigate to Settings
+   - Verify admin section visible
+   - Tap "Users"
+   - Verify admin list loads
+
+3. **Non-Admin**:
+   - Login with non-admin account
+   - Navigate to `/garage/settings/admin/users`
+   - Verify 403 Forbidden page displayed
+   - Check that admin console NOT visible on settings page
+
+## Rollback Procedure
+
+If critical issues found after deployment:
+
+```bash
+# 1. Revert code to previous version
+git revert HEAD
+docker compose down
+make rebuild
+make start
+
+# 2. If database schema issue, restore from backup
+./scripts/restore-database.sh backup-timestamp.sql
+
+# 3. Verify health
+curl https://motovaultpro.com/api/health
+
+# 4. Test rollback endpoints
+curl -H "Authorization: Bearer $JWT" \
+  https://motovaultpro.com/api/vehicles/
+
+# 5. Monitor logs for 30 minutes
+make logs | tail -f
+```
+
+## Supported Browsers
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Known Limitations
+
+- Admin feature requires JavaScript enabled
+- Mobile UI optimized for portrait orientation
+- Catalog changes may take 5 minutes to propagate in cache
+
+## Sign-Off
+
+- [ ] **Tech Lead**: All quality gates passed ______________________ Date: _______
+- [ ] **QA**: End-to-end testing complete ______________________ Date: _______
+- [ ] **DevOps**: Deployment procedure verified ______________________ Date: _______
+- [ ] **Product**: Feature acceptance confirmed ______________________ Date: _______
+
+## Post-Deployment Monitoring
+
+Monitor for 24 hours:
+- [ ] Health check endpoint responding
+- [ ] No 500 errors in logs
+- [ ] Admin operations completing <500ms
+- [ ] No database connection errors
+- [ ] Memory usage stable
+- [ ] Disk space adequate
+- [ ] All feature endpoints responding
+
+## Release Notes
+
+```markdown
+## Admin Feature (v1.0)
+
+### New Features
+
+- Admin role and access control (Phase 1)
+- Admin user management with audit trail (Phase 2)
+- Vehicle catalog CRUD operations (Phase 3)
+- Gas station oversight and management (Phase 4)
+- Admin UI for desktop and mobile (Phase 5)
+
+### Breaking Changes
+
+None
+
+### Migration Required
+
+Yes - Run `npm run migrate` automatically on container startup
+
+### Rollback Available
+
+Yes - See ADMIN-DEPLOYMENT-CHECKLIST.md
+
+### Documentation
+
+See `docs/ADMIN.md` for complete reference
+```