The-transit-Project/transit_api/README.md

# Transit API

Transit API voor het beheren van busroutes, navigatie en GPS tracking voor busbestuurders.

## Project Structuur

```
transit_api/
├── index.js           # Main API endpoints
├── middleware.js      # JWT authentication middleware
├── db.js             # PostgreSQL connection
├── schema.sql        # Database schema setup
├── package.json      # Dependencies
└── .env              # Environment variables
```

## Setup

### 1. Dependencies installeren

```bash
npm install
```

### 2. Database Schema opzetten

Voer het volgende uit in PostgreSQL:

```bash
# Via psql command line
psql -U your_user -d your_database -f schema.sql
```

Of kopieer-plak de SQL queries rechtstreeks in pgAdmin.

### 3. Environment variabelen (.env)

```
PG_HOST=localhost
PG_PORT=5432
PG_USER=your_user
PG_PASS=your_password
PG_DB=your_database
JWT_SECRET=your_jwt_secret
PORT=5001
```

Note: `ADMIN_USER_CODES` has been moved to the `auth_api` service. Configure admin user codes in `auth_api/.env` as a comma-separated list.

### 4. API starten

```bash
npm start
```

API draait op `http://localhost:5001`

## API Endpoints

Alle endpoints vereisen een `Authorization: Bearer {token}` header.

### Schedule

Schedules are weekly templates. Each row in `transit.schedules` represents one
departure time for one bus line and one `day_of_week`:

- `1` to `5`: weekdays
- `6`: Saturday
- `0`: Sunday

Driver assignments are stored separately in `transit.shifts` with
`(schedule_id, driver_id)`, where `driver_id` references `workers.users(id)`.
The current `shifts` shape represents the active assignment. To retain different
assignments for different calendar weeks, add a `week_start` (or assignment date
range) column and include it in the unique key.

**GET** `/driver/schedules/daily?date=2026-09-18`

- Returns only weekly schedule templates assigned to the authenticated driver through `transit.shifts`.

**PATCH** `/driver/weekly-schedules/:scheduleId/status`

- Updates the status of an assigned weekly schedule.

**GET** `/admin/weekly-schedules`

- Lists weekly templates and their current driver assignments.

**GET** `/admin/shift-drivers`

- Lists drivers from `workers.users` for shift assignment.

**POST** `/admin/weekly-schedules`

- Creates one template. Body: `{ "busLineId": 1, "dayOfWeek": 1, "startTime": "08:00", "endTime": "09:00", "driverId": 12 }`.

**POST** `/admin/weekly-schedules/bulk`

- Creates multiple departures in one transaction. The API derives each end time
  from the selected bus line duration. Body: `{ "busLineId": 1, "dayOfWeeks": [1,2,3,4,5], "startTimes": ["06:00", "06:30", "07:00"], "driverId": 12 }`.

**PUT** `/admin/weekly-schedules/:scheduleId/shift`

- Replaces the driver assignment. Pass `{ "driverId": 12 }` or `{ "driverId": null }`.

The legacy `/admin/schedules` and `/schedule/daily` endpoints remain for older
clients, but new clients must use the weekly schedule endpoints above.

**GET** `/schedule/daily?date=2024-05-05`

- Ophalen van dagplanning voor chauffeur
- Response:

```json
{
  "date": "2024-05-05",
  "routes": [
    {
      "id": 1,
      "startTime": "2024-05-05T08:00:00Z",
      "status": "scheduled",
      "busLine": {
        "lineNumber": 1,
        "startStop": "Central Station",
        "endStop": "Airport"
      },
      "busType": {
        "name": "Standard Bus",
        "seatCapacity": 50,
        "licensePlate": "BUS-001"
      }
    }
  ]
}
```

**GET** `/routes/:routeId`

- Details van een specifieke route
- Response: `{ "route": {...} }`

### Public Schedule Overview

**GET** `/schedules/overview?date=2026-05-06&lineId=1`

- Haalt een datum-gebonden overzicht op van geplande diensten
- Weekly templates are selected by `day_of_week` and driver assignments by `shifts`
- Incidentele diensten worden alleen meegenomen op hun exacte datum
- Filters: `driverId`/`chauffeurId`, `stopId`/`busStopId`, `lineId`, `status`
- Response: `{ "date": "2026-05-06", "summary": {...}, "schedules": [...] }`

De legacy endpoint **GET** `/schedules` blijft beschikbaar voor bestaande clients.

Voorbeeld:

```bash
curl "http://localhost:5001/schedules/overview?date=2026-05-06&chauffeurId=12&busStopId=3"
```

### Navigation

**POST** `/navigation/route`

- Opslaan van berekende route van OSRM
- Body:

```json
{
  "routeId": 1,
  "startLat": 52.5200,
  "startLon": 13.4050,
  "endLat": 52.5300,
  "endLon": 13.4150,
  "totalDistance": 15000,
  "totalDuration": 900,
  "geojson": {
    "type": "LineString",
    "coordinates": [[13.4050, 52.5200], ...]
  }
}
```

**GET** `/bus-lines/:busLineId/stops`

- Alle stops van een buslijn (voor navigatie waypoints)
- Response:

```json
{
  "stops": [
    {
      "id": 1,
      "order": 1,
      "name": "Central Station",
      "latitude": 52.52,
      "longitude": 13.405
    }
  ]
}
```

### GPS Tracking

**POST** `/gps/track`

- Real-time positie opslaan
- Body:

```json
{
  "routeId": 1,
  "latitude": 52.521,
  "longitude": 13.406,
  "speed": 45.5,
  "heading": 180,
  "accuracy": 5.0
}
```

**GET** `/gps/route/:routeId`

- Alle opgeslagen positie punten van een route
- Response:

```json
{
  "positions": [
    {
      "id": 1,
      "latitude": 52.521,
      "longitude": 13.406,
      "speed": 45.5,
      "heading": 180,
      "recordedAt": "2024-05-05T08:15:00Z"
    }
  ]
}
```

### Route Status

**PATCH** `/routes/:routeId/status`

- Update route status
- Body: `{ "status": "in_progress" }`
- Valid statuses: `scheduled`, `in_progress`, `completed`, `cancelled`

### Admin

Alle admin-endpoints vereisen naast een geldig JWT-token ook dat je `userCode` voorkomt in `ADMIN_USER_CODES`.

**POST** `/admin/stops`

- Maak een herbruikbare stop aan
- Body:

```json
{
  "name": "Central Station",
  "latitude": 52.52,
  "longitude": 13.405
}
```

**POST** `/admin/bus-lines/:busLineId/stops`

- Koppel een bestaande stop aan een buslijn
- Body:

```json
{
  "stopId": 1,
  "stopOrder": 1,
  "estimatedArrivalMinutes": 0
}
```

## Database Schema

### bus_types

- `id` - Primary key
- `name` - Bus type name (Standard Bus, etc.)
- `seat_capacity` - Number of seats
- `license_plate` - Unique license plate

### bus_lines

- `id` - Primary key
- `line_number` - Unique line number (1, 5, 12, etc.)
- `start_stop` - Start stop name
- `end_stop` - End stop name
- `estimated_duration_minutes` - Expected route duration

### stops

- `id` - Primary key
- `name` - Stop name
- `latitude`, `longitude` - Stop location

### route_stops

- `id` - Primary key
- `bus_line_id` - Which bus line the stop belongs to
- `stop_id` - Reusable stop reference
- `stop_order` - Stop sequence on that bus line
- `estimated_arrival_minutes` - Optional ETA per stop

### routes

- `id` - Primary key
- `user_id` - Chauffeur (references workers.users)
- `bus_line_id` - Which line (references bus_lines)
- `bus_type_id` - Which bus (references bus_types)
- `start_time` - Scheduled start
- `status` - scheduled/in_progress/completed/cancelled

### navigation_routes

- `id` - Primary key
- `route_id` - Link to route (unique)
- `polyline_geojson` - GeoJSON LineString van de route
- `total_distance_meters` - Route distance
- `total_duration_seconds` - Estimated duration

### gps_tracking

- `id` - Primary key
- `route_id` - Which route
- `latitude`, `longitude` - Current position
- `speed_kmh` - Current speed
- `recorded_at` - Timestamp

## Integration met Flutter App

```dart
// In schedule_service.dart

// Save navigation route
await scheduleService.saveNavigationRoute(
  routeId: 1,
  navRoute: navigationRoute,
);

// Track GPS
await scheduleService.trackGPS(
  routeId: 1,
  currentPos: navigationPoint,
  speed: 45.5,
  heading: 180,
);

// Update route status
await scheduleService.updateRouteStatus(1, 'in_progress');
```

## Error Handling

Alle endpoints retourneren error responses:

```json
{
  "error": "error_code",
  "details": "More information"
}
```

Common errors:

- `missing_token` - No Authorization header
- `invalid_token` - Token verification failed
- `missing_required_fields` - Required data missing
- `invalid_status` - Invalid status value
- `route_not_found` - Route not found
- `unauthorized` - User doesn't own this resource