Backup: 2025-06-07 19:48 - Script test

[Restore from backup: vip-coordinator-backup-2025-06-07-19-48-script-test]
2025-06-07 19:48:00 +02:00
parent 8fb00ec041
commit dc4655cef4
103 changed files with 16396 additions and 6143 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,154 @@
+# VIP Coordinator - Technical Documentation
+
+## Project Overview
+VIP Transportation Coordination System - A web application for managing VIP transportation with driver assignments, real-time tracking, and user management.
+
+## Tech Stack
+- **Frontend**: React with TypeScript, Tailwind CSS
+- **Backend**: Node.js with Express, TypeScript
+- **Database**: PostgreSQL
+- **Authentication**: Google OAuth 2.0 via Google Identity Services
+- **Containerization**: Docker & Docker Compose
+- **State Management**: React Context API
+- **JWT**: Custom JWT Key Manager with automatic rotation
+
+## Authentication System
+
+### Current Implementation (Working)
+We use Google Identity Services (GIS) SDK on the frontend to avoid CORS issues:
+
+1. **Frontend-First OAuth Flow**:
+   - Frontend loads Google Identity Services SDK
+   - User clicks "Sign in with Google" button
+   - Google shows authentication popup
+   - Google returns a credential (JWT) directly to frontend
+   - Frontend sends credential to backend `/auth/google/verify`
+   - Backend verifies credential, creates/updates user, returns JWT
+
+2. **Key Files**:
+   - `frontend/src/components/GoogleLogin.tsx` - Google Sign-In button with GIS SDK
+   - `backend/src/routes/simpleAuth.ts` - Auth endpoints including `/google/verify`
+   - `backend/src/services/jwtKeyManager.ts` - JWT token generation with rotation
+
+3. **User Flow**:
+   - First user → Administrator role with status='active'
+   - Subsequent users → Coordinator role with status='pending'
+   - Pending users see styled waiting page until admin approval
+
+### Important Endpoints
+- `POST /auth/google/verify` - Verify Google credential and create/login user
+- `GET /auth/me` - Get current user from JWT token
+- `GET /auth/users/me` - Get detailed user info including status
+- `GET /auth/setup` - Check if system has users
+
+## Database Schema
+
+### Users Table
+```sql
+users (
+  id VARCHAR(255) PRIMARY KEY,
+  google_id VARCHAR(255) UNIQUE,
+  email VARCHAR(255) UNIQUE NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  role VARCHAR(50) CHECK IN ('driver', 'coordinator', 'administrator'),
+  profile_picture_url TEXT,
+  status VARCHAR(20) DEFAULT 'pending' CHECK IN ('pending', 'active', 'deactivated'),
+  approval_status VARCHAR(20) DEFAULT 'pending' CHECK IN ('pending', 'approved', 'denied'),
+  phone VARCHAR(50),
+  organization VARCHAR(255),
+  onboarding_data JSONB,
+  approved_by VARCHAR(255),
+  approved_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  last_login TIMESTAMP,
+  is_active BOOLEAN DEFAULT true,
+  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+)
+```
+
+## Common Issues & Solutions
+
+### 1. CORS/Cross-Origin Issues
+**Problem**: OAuth redirects and popups cause CORS errors
+**Solution**: Use Google Identity Services SDK directly in frontend, send credential to backend
+
+### 2. Missing Database Columns
+**Problem**: Backend expects columns that don't exist
+**Solution**: Run migrations to add missing columns:
+```sql
+ALTER TABLE users ADD COLUMN IF NOT EXISTS status VARCHAR(20) DEFAULT 'pending';
+ALTER TABLE users ADD COLUMN IF NOT EXISTS approval_status VARCHAR(20) DEFAULT 'pending';
+```
+
+### 3. JWT Token Missing Fields
+**Problem**: Frontend expects fields in JWT that aren't included
+**Solution**: Update `jwtKeyManager.ts` to include all required fields (status, approval_status, etc.)
+
+### 4. First User Not Admin
+**Problem**: First user created as coordinator instead of administrator
+**Solution**: Check `isFirstUser()` method properly counts users in database
+
+### 5. Auth Routes 404
+**Problem**: Frontend calling wrong API endpoints
+**Solution**: Auth routes are at `/auth/*` not `/api/auth/*`
+
+## User Management
+
+### User Roles
+- **Administrator**: Full access, can approve users, first user gets this role
+- **Coordinator**: Can manage VIPs and drivers, needs admin approval
+- **Driver**: Can view assigned trips, needs admin approval
+- **Viewer**: Read-only access (if implemented)
+
+### User Status Flow
+1. User signs in with Google → Created with status='pending'
+2. Admin approves → Status changes to 'active'
+3. Admin can deactivate → Status changes to 'deactivated'
+
+### Approval System
+- First user is auto-approved as administrator
+- All other users need admin approval
+- Pending users see a styled waiting page
+- Page auto-refreshes every 30 seconds to check approval
+
+## Docker Setup
+
+### Environment Variables
+Create `.env` file with:
+```
+GOOGLE_CLIENT_ID=your-client-id
+GOOGLE_CLIENT_SECRET=your-client-secret
+GOOGLE_REDIRECT_URI=https://yourdomain.com/auth/google/callback
+FRONTEND_URL=https://yourdomain.com
+DB_PASSWORD=your-secure-password
+```
+
+### Running the System
+```bash
+docker-compose up -d
+```
+
+Services:
+- Frontend: http://localhost:5173
+- Backend: http://localhost:3000
+- PostgreSQL: localhost:5432
+- Redis: localhost:6379
+
+## Key Learnings
+
+1. **Google OAuth Strategy**: Frontend-first approach with GIS SDK avoids CORS issues entirely
+2. **JWT Management**: Custom JWT manager with key rotation provides better security
+3. **Database Migrations**: Always check table schema matches backend expectations
+4. **User Experience**: Clear, styled feedback for pending users improves perception
+5. **Error Handling**: Proper error messages and status codes help debugging
+6. **Docker Warnings**: POSTGRES_PASSWORD warnings are cosmetic and don't affect functionality
+
+## Future Improvements
+
+1. Email notifications when users are approved
+2. Role-based UI components (hide/show based on user role)
+3. Audit logging for all admin actions
+4. Batch user approval interface
+5. Password-based login as fallback
+6. User profile editing
+7. Organization-based access control