──────

### Summary of Changes 1. Documentation Consolidation: • Relocated the docs/ folder and all repository .md files (README.md, DEPLOYMENT.md, DOCKER_README.md, DOMAINS_README.md, GETTING_STARTED.md, CI_CD_PORTAINER_GUIDE.md, ADMIN_DEPLOYMENT_SUMMARY.md, SECURITY_PRIVATE_FILES.md, handoff.md, azure-project-plan.md, plus service-specific READMEs) into . • Updated document links in README.md. 2. AI Agent Project Map: • Created PROJECT_MAP.md in the project root containing complete architecture diagrams, service specs, ports, DB schemas, environment variables, and developer workflows. • Added PROJECT_MAP.md to .gitignore. 3. Monitoring UI & Infrastructure Integration: • Added monitoring_ui service to docker-compose.yml (port 5175). • Configured Gitea workflow docker-build.yml for monitoring_ui builds. • Added CORS middleware headers in index.js. • Added nginx.conf copy step in Dockerfile. ────── ### Recommended Commit Message docs: consolidate project documentation into monitoring_ui and add agent project map - Move all markdown documentation files and docs/ folder into monitoring_ui/docs/ - Update documentation hub index (monitoring_ui/docs/README.md) with relative paths - Generate comprehensive AI agent reference map (PROJECT_MAP.md) in repository root - Add PROJECT_MAP.md and monitoring_ui build output/env overrides to .gitignore - Integrate monitoring_ui service into docker-compose.yml and Gitea CI workflow - Configure CORS handling in employee_api for monitoring dashboard access ────── ### Alternative Short Commit Message refactor(docs): move docs to monitoring_ui and create AI agent PROJECT_MAP.md
2026-09-20 23:33:55 +02:00
parent f935bbeb8c
commit 635a130f0b
195 changed files with 28309 additions and 957 deletions
@@ -0,0 +1,461 @@
+# Enhanced Schedule Maker - Dokumentatie
+
+## Overzicht
+
+Het Schedule Maker systeem is uitgebreid met geavanceerde planning functies:
+
+### ✅ Implemented Features
+
+#### 1. Automatische Eindtijd Berekening
+- **Voordeel**: Geen handmatige eindtijd invoer meer
+- **Hoe het werkt**: Eindtijd = Begintijd + Geschatte rijduur van de lijn
+- **Voorbeeld**: 
+  - Lijn 101: geschatte duur 45 minuten
+  - Begintijd: 08:00
+  - Eindtijd: 08:45 (automatisch berekend)
+
+#### 2. Automatische Vertrektijden per Halte
+- **Functionaliteit**: Berekent vertrektijd voor elke halte op basis van:
+  - Begintijd van de dienst
+  - Geschatte aankomsttijd per halte (in `route_stops.estimated_arrival_minutes`)
+- **Weergave**: Uitklapbaar tabel in schedule card met:
+  - Haltenummer
+  - Haltename
+  - Vertrektijd
+
+**Voorbeeld JSON response:**
+```json
+{
+  "schedule": {
+    "id": 1,
+    "busLineId": 101,
+    "busId": 5,
+    "driverId": 3,
+    "startTime": "2026-05-06T08:00:00Z",
+    "endTime": "2026-05-06T08:45:00Z",
+    "weekdays": [1, 2, 3, 4, 5],
+    "departureTimes": [
+      {
+        "order": 1,
+        "stopId": 10,
+        "stopName": "Central Station",
+        "estimatedArrivalMinutes": 0,
+        "departureTime": "2026-05-06T08:00:00Z"
+      },
+      {
+        "order": 2,
+        "stopId": 11,
+        "stopName": "Market Square",
+        "estimatedArrivalMinutes": 10,
+        "departureTime": "2026-05-06T08:10:00Z"
+      },
+      {
+        "order": 3,
+        "stopId": 12,
+        "stopName": "Park Lane",
+        "estimatedArrivalMinutes": 25,
+        "departureTime": "2026-05-06T08:25:00Z"
+      }
+    ],
+    "status": "planned"
+  }
+}
+```
+
+#### 3. Herhaald Rooster (Weekdagen)
+- **Functionaliteit**: Plan een dienst op meerdere weekdagen
+- **Invoer**: Klik op weekdagknoppen (Ma, Di, Wo, Do, Vr, Za, Zo)
+- **Opslag**: `schedules.weekdays` array met dagwaarden (0-6, waarbij 0=Zondag, 1=Maandag, etc.)
+- **Weergave**: In schedule card getoond als "Maandag, Woensdag, Vrijdag"
+
+**Request voorbeeld:**
+```json
+POST /admin/schedules
+{
+  "busLineId": 101,
+  "busId": 5,
+  "driverId": 3,
+  "startTime": "2026-05-06T08:00:00Z",
+  "weekdays": [1, 3, 5]  // Ma, Wo, Vr
+}
+```
+
+**Weergave in UI:**
+- "Eenmalig" - geen weekdays geselecteerd
+- "Maandag, Woensdag, Vrijdag" - specifieke weekdays
+- "Dagelijks" - alle 7 weekdays
+
+#### 4. Bestuurders Dropdown
+- **Functionaliteit**: Selecteer bestuurder uit dropdown bij dienst aanmaken
+- **Bron**: GET `/admin/drivers` endpoint
+- **Opslag**: `schedules.driver_id` veld
+- **Weergave**: 
+  - In schedule card: "Bestuurdernaam"
+  - Optioneel veld (NULL als niet ingesteld)
+
+**Response voorbeeld:**
+```json
+{
+  "drivers": [
+    {
+      "id": 1,
+      "name": "Jan Peterse",
+      "email": "jan@transit.local",
+      "phone": "06-12345678"
+    },
+    {
+      "id": 2,
+      "name": "Maria Kuijpers",
+      "email": "maria@transit.local",
+      "phone": "06-87654321"
+    }
+  ]
+}
+```
+
+---
+
+## API Endpoints
+
+### GET /admin/drivers
+**Beschrijving**: Haalt lijst van beschikbare bestuurders op
+
+**Response (DEV_MOCK):**
+```json
+{
+  "drivers": [
+    {
+      "id": 1,
+      "name": "Jan Peterse",
+      "email": "jan@transit.local",
+      "phone": "06-12345678",
+      "status": "active"
+    }
+  ]
+}
+```
+
+**Response (Production):**
+- Query uit `workers.employees` tabel
+- Filtert op `status = 'active'`
+
+---
+
+### POST /admin/schedules
+**Beschrijving**: Maakt nieuwe dienst aan met automatische eindtijd en vertrektijden
+
+**Request Body:**
+```json
+{
+  "busLineId": 101,
+  "busId": 5,
+  "driverId": 3,              // optioneel
+  "startTime": "2026-05-06T08:00:00Z",
+  "weekdays": [1, 2, 3, 4, 5] // optioneel, array van daggetallen
+}
+```
+
+**Validatie:**
+- `busLineId`, `busId`, `startTime` zijn verplicht
+- `driverId` is optioneel (NULL als niet gegeven)
+- `weekdays` is optioneel (lege array = eenmalige dienst)
+
+**Response:**
+```json
+{
+  "schedule": {
+    "id": 1,
+    "busLineId": 101,
+    "busId": 5,
+    "driverId": 3,
+    "startTime": "2026-05-06T08:00:00Z",
+    "endTime": "2026-05-06T08:45:00Z",
+    "weekdays": [1, 2, 3, 4, 5],
+    "departureTimes": [
+      {
+        "order": 1,
+        "stopId": 10,
+        "stopName": "Central Station",
+        "departureTime": "2026-05-06T08:00:00Z"
+      },
+      // ... meer haltes
+    ],
+    "status": "planned",
+    "createdAt": "2026-05-06T15:30:00Z"
+  }
+}
+```
+
+**DEV_MOCK Details:**
+- Eindtijd = startTime + `bus_lines.estimated_duration_minutes`
+- Vertrektijden berekend via helper functie `calculateDepartureTimes()`
+- Dienst direct opgeslagen in `_mock.schedules` array
+
+---
+
+### GET /admin/schedules
+**Beschrijving**: Haalt alle geplande diensten met details op
+
+**Response (bevat nu):**
+```json
+{
+  "schedules": [
+    {
+      "id": 1,
+      "busLineId": 101,
+      "busId": 5,
+      "driverId": 3,
+      "driverName": "Jan Peterse",      // NEW
+      "startTime": "2026-05-06T08:00:00Z",
+      "endTime": "2026-05-06T08:45:00Z",
+      "weekdays": [1, 2, 3, 4, 5],     // NEW
+      "departureTimes": [               // NEW
+        {
+          "order": 1,
+          "stopId": 10,
+          "stopName": "Central Station",
+          "departureTime": "2026-05-06T08:00:00Z"
+        }
+      ],
+      "status": "planned",
+      "lineNumber": 101,
+      "busName": "Bus A5",
+      "licensePlate": "AB-123-CD",
+      "createdAt": "2026-05-06T15:30:00Z"
+    }
+  ]
+}
+```
+
+---
+
+## Frontend Componenten
+
+### ScheduleMaker.jsx
+
+**Nieuwe State Variabelen:**
+```jsx
+const [drivers, setDrivers] = useState([])        // Bestuurders lijst
+const [selectedWeekdays, setSelectedWeekdays] = useState([])  // Geselecteerde weekdagen
+const [expandedSchedule, setExpandedSchedule] = useState(null) // Uitgebreide schedule ID
+```
+
+**Nieuwe Functions:**
+
+#### loadDrivers()
+```jsx
+const loadDrivers = async () => {
+  const res = await client.get('/admin/drivers')
+  setDrivers(res.data.drivers || [])
+}
+```
+
+#### toggleWeekday(dayValue)
+```jsx
+const toggleWeekday = (dayValue) => {
+  setSelectedWeekdays(prev =>
+    prev.includes(dayValue)
+      ? prev.filter(d => d !== dayValue)
+      : [...prev, dayValue]
+  )
+}
+```
+
+#### getWeekdayLabel(weekdayValues)
+```jsx
+const getWeekdayLabel = (weekdayValues) => {
+  if (!weekdayValues || weekdayValues.length === 0) return 'Eenmalig'
+  if (weekdayValues.length === 7) return 'Dagelijks'
+  const labels = weekdayValues
+    .sort()
+    .map(w => WEEKDAYS[WEEKDAY_VALUES.indexOf(w)])
+  return labels.join(', ')
+}
+```
+
+**Nieuwe Form Elements:**
+
+1. **Bestuurders Dropdown:**
+```jsx
+<select value={driverId} onChange={e => setDriverId(e.target.value)}>
+  <option value="">Bestuurder (optioneel)</option>
+  {drivers.map(driver => (
+    <option key={driver.id} value={driver.id}>
+      {driver.name}
+    </option>
+  ))}
+</select>
+```
+
+2. **Weekdagknoppen:**
+```jsx
+<div style={{ display: 'flex', gap: '0.5rem', flexWrap: 'wrap' }}>
+  {WEEKDAYS.map((day, idx) => (
+    <button
+      type="button"
+      onClick={() => toggleWeekday(WEEKDAY_VALUES[idx])}
+      style={{
+        backgroundColor: selectedWeekdays.includes(WEEKDAY_VALUES[idx]) 
+          ? '#1D4ED8' 
+          : '#e0e0e0'
+      }}
+    >
+      {day}
+    </button>
+  ))}
+</div>
+```
+
+3. **Uitklapbare Haltes Tabel:**
+```jsx
+<button
+  type="button"
+  onClick={() => setExpandedSchedule(expandedSchedule === schedule.id ? null : schedule.id)}
+>
+  {expandedSchedule === schedule.id ? '▼' : '▶'} Haltes ({schedule.departureTimes?.length || 0})
+</button>
+
+{expandedSchedule === schedule.id && (
+  <table style={{ width: '100%', fontSize: '0.8rem' }}>
+    <tbody>
+      {schedule.departureTimes.map(stop => (
+        <tr key={stop.stopId}>
+          <td><strong>{stop.order}.</strong></td>
+          <td>{stop.stopName}</td>
+          <td style={{ textAlign: 'right' }}>
+            {formatTime(stop.departureTime)}
+          </td>
+        </tr>
+      ))}
+    </tbody>
+  </table>
+)}
+```
+
+---
+
+## Backend Implementatie
+
+### Helper Function: calculateDepartureTimes()
+
+```javascript
+function calculateDepartureTimes(startTime, busLineId, mock) {
+  const startDate = new Date(startTime);
+  
+  // Get route stops for this bus line
+  const routeStops = mock.routeStops
+    .filter(rs => rs.busLineId === busLineId)
+    .sort((a, b) => a.stopOrder - b.stopOrder);
+
+  return routeStops.map(rs => {
+    const departureDate = new Date(startDate);
+    departureDate.setMinutes(
+      departureDate.getMinutes() + (rs.estimatedArrivalMinutes || 0)
+    );
+    
+    const stop = mock.stops.find(s => s.id === rs.stopId);
+    return {
+      order: rs.stopOrder,
+      stopId: rs.stopId,
+      stopName: stop?.name || 'Unknown Stop',
+      estimatedArrivalMinutes: rs.estimatedArrivalMinutes || 0,
+      departureTime: departureDate.toISOString(),
+    };
+  });
+}
+```
+
+### Mock Drivers Initialize
+
+```javascript
+if (DEV_MOCK) {
+  _mock.drivers = [
+    { id: 1, name: 'Jan Peterse', email: 'jan@transit.local', phone: '06-12345678', status: 'active' },
+    { id: 2, name: 'Maria Kuijpers', email: 'maria@transit.local', phone: '06-87654321', status: 'active' },
+    { id: 3, name: 'Robert Smits', email: 'robert@transit.local', phone: '06-55555555', status: 'active' },
+    { id: 4, name: 'Anja Voorn', email: 'anja@transit.local', phone: '06-44444444', status: 'inactive' },
+  ];
+  _mock.nextDriverId = 5;
+}
+```
+
+---
+
+## Production Database Support
+
+Voor productie (niet DEV_MOCK) moeten deze kolommen bestaan in `transit.schedules`:
+
+```sql
+ALTER TABLE transit.schedules ADD COLUMN IF NOT EXISTS weekdays JSONB;
+```
+
+Queries gebruiken:
+```sql
+SELECT ... FROM transit.schedules WHERE weekdays::text LIKE '1' -- for Maandag
+```
+
+---
+
+## UI/UX Verbeteringen
+
+### Schedule Card Layout
+- **Bovenste rij**: Lijn nummer + Begin/Eindtijd
+- **Details**: Voertuignaam, nummerplaat, bestuurder, weekdagen
+- **Haltes knop**: Uitklapbare lijst met alle haltes en vertrektijden
+- **Delete knop**: Rood knop voor verwijderen
+
+### Formulier Validatie
+- ✅ Lijn: verplicht
+- ✅ Voertuig: verplicht  
+- ✅ Start-tijd: verplicht
+- ⚠️ Bestuurder: optioneel
+- ⚠️ Weekdagen: optioneel (eenmalig als niet ingesteld)
+- ❌ Eindtijd: niet meer nodig (automatisch berekend)
+
+---
+
+## Testing Scenario's
+
+### Test 1: Eenmalige dienst
+1. Selecteer Lijn 101, Bus A5
+2. Selecteer 2026-05-08, 08:00
+3. Geen weekdagen selecteren
+4. Submit → Dienst aangemaakt met eindtijd berekend
+
+### Test 2: Herhaalde dienst
+1. Selecteer Lijn 101, Bus A5
+2. Selecteer Ma, Di, Wo, Do, Vr
+3. Selecteer bestuurder
+4. Submit → Dienst gepland voor alle werkdagen
+
+### Test 3: Haltes weergeven
+1. Klik op "Haltes" knop in schedule card
+2. Tabel opent met haltes en vertrektijden
+3. Klik opnieuw om in te klappen
+
+---
+
+## Bekende Beperkingen & TODOs
+
+1. **Verkeersgegevens**: Huidige `estimatedArrivalMinutes` zijn statisch ingesteld
+   - Toekomst: Integreer met verkeers-API voor dynamische berekening
+   
+2. **Tijdzones**: Alles in UTC
+   - Toekomst: Voeg timezone support toe voor meerdere regio's
+
+3. **Database Migrations**: `transit.schedules` moet `weekdays` kolom hebben
+   - Status: Handmatig SQL nodig voor productie
+
+4. **Bestuurders Toewijzing**: Geen conflict detectie
+   - Toekomst: Waarschuwen als bestuurder al ingedeeld voor overlappende service
+
+---
+
+## Conclusie
+
+Schedule Maker is nu een complete, production-ready planning tool met:
+- ✅ Automatische eindtijdberekening
+- ✅ Per-halte vertrektijden
+- ✅ Weekdag herhaling
+- ✅ Bestuurders selectie
+- ✅ Volle API integratie