motovaultpro/docs/ADMIN-DEPLOYMENT-CHECKLIST.md

# 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
```