──────

### 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,281 @@
+# Schedule Maker & Public Timetable API
+
+## Features
+
+The Transit API now includes a comprehensive schedule management system with both admin and public endpoints.
+
+### Weekly Admin Endpoints (requires authentication + admin privileges)
+
+The active admin UI uses weekly schedule templates. `dayOfWeek` follows the
+JavaScript/PostgreSQL convention: `0` Sunday, `1` through `5` weekdays, and `6`
+Saturday. Driver assignment is stored in `transit.shifts` and references
+`workers.users(id)`.
+
+#### Get weekly schedules
+
+```
+GET /admin/weekly-schedules
+Response: { schedules: [...] }
+```
+
+#### Get shift drivers
+
+```
+GET /admin/shift-drivers
+Response: { drivers: [{ id, name }] }
+```
+
+#### Create a weekly schedule
+
+````
+
+#### Create multiple departures
+
+```text
+POST /admin/weekly-schedules/bulk
+Body: {
+  busLineId: 1,
+  dayOfWeeks: [1, 2, 3, 4, 5],
+  startTimes: ["06:00", "06:30", "07:00"],
+  driverId: 12
+}
+````
+
+The API creates one schedule row for every day/time combination and derives the
+end time from the bus line's configured duration.
+POST /admin/weekly-schedules
+Body: {
+busLineId: 1,
+dayOfWeek: 1,
+startTime: "08:00",
+endTime: "09:00",
+driverId: 12
+}
+
+```
+
+#### Replace a schedule's driver
+
+```
+
+PUT /admin/weekly-schedules/:scheduleId/shift
+Body: { driverId: 12 }
+
+```
+
+Use `{ "driverId": null }` to unassign the driver. The current `shifts` table
+does not contain a week/date column, so this is an active assignment rather than
+historical per-week assignment. Add `week_start` to support that later.
+
+### Legacy Admin Endpoints
+
+#### Get all schedules
+
+```
+
+GET /admin/schedules
+Response: { schedules: [...] }
+
+```
+
+#### Create a schedule
+
+```
+
+POST /admin/schedules
+Body: {
+busLineId: number,
+busId: number,
+driverId: number (optional),
+startTime: "2026-05-06T08:00:00",
+endTime: "2026-05-06T17:00:00"
+}
+Response: { schedule: {...} }
+
+```
+
+#### Delete a schedule
+
+```
+
+DELETE /admin/schedules/:scheduleId
+Response: { success: true, schedule: {...} }
+
+```
+
+### Public Endpoints (no authentication required)
+
+#### Get schedules (with optional filters)
+
+```
+
+GET /schedules?date=2026-05-06&lineId=1
+Query params:
+
+- date: YYYY-MM-DD (optional)
+- lineId: number (optional)
+  Response: { schedules: [...] }
+
+```
+
+#### Get schedule detail
+
+```
+
+GET /schedules/:scheduleId
+Response: { schedule: {...} }
+
+```
+
+#### Get stops for a schedule's line
+
+```
+
+GET /schedules/:scheduleId/stops
+Response: { stops: [...] }
+Shows all stops on the bus line with order, location, and ETA.
+
+````
+
+## Admin UI Features
+
+The ScheduleMaker component provides:
+
+1. **Weekly schedule editor**
+
+- Select a bus line and one of weekdays, Saturday, or Sunday
+- Define start and end times
+- Assign drivers through shifts
+- Admin-only access
+
+2. **Timetable View**
+   - 24-hour time slots (hourly grouping)
+   - Services displayed in corresponding time slots
+   - Shows line number, vehicle name, and license plate
+   - Delete button for each service (admin only)
+   - Color-coded schedule cards with gradient styling
+
+3. **Drag-and-Drop Ready**
+   - Schedule cards are draggable (extensible for drag-to-reorder)
+   - Follows existing UI/UX patterns from LinkStop component
+
+4. **Confirmation Modals**
+   - Delete confirmation before removing schedules
+   - Shows service details in confirmation
+   - Prevents accidental deletions
+
+## Public Timetable Viewer
+
+The TimetableViewer component provides a public-facing schedule display:
+
+```jsx
+import TimetableViewer from "./components/TimetableViewer";
+
+<TimetableViewer apiBaseUrl="http://api.transit.local:5001" />;
+````
+
+Features:
+
+- Filter by date and bus line
+- Real-time loading state
+- Error handling
+- Status badges (planned/active)
+- Responsive table layout
+- No authentication required
+
+## Development Mode
+
+With `DEV_MOCK=1`, all schedule operations work in-memory without a database.
+
+Example:
+
+```bash
+ADMIN_USER_CODES=42 DEV_MOCK=1 JWT_SECRET=devsecret npm --prefix ./transit_api start
+```
+
+## Database Schema (Production)
+
+```sql
+CREATE TABLE transit.schedules (
+  id BIGINT PRIMARY KEY,
+  bus_line_id BIGINT REFERENCES transit.bus_lines(id),
+  start_time TIME,
+  end_time TIME,
+  status VARCHAR(20) DEFAULT 'planned',
+  day_of_week SMALLINT NOT NULL CHECK (day_of_week BETWEEN 0 AND 6),
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE TABLE transit.shifts (
+  id BIGINT PRIMARY KEY,
+  schedule_id BIGINT REFERENCES transit.schedules(id) ON DELETE CASCADE,
+  driver_id BIGINT REFERENCES workers.users(id)
+);
+```
+
+## Styling & UX
+
+The schedule manager uses:
+
+### Admin Timetable Styling
+
+- Responsive table with hourly time slots
+- Gradient schedule cards (blue/indigo theme)
+- Hover effects and smooth transitions
+- Grab cursor on draggable items
+- Danger buttons for delete actions (red)
+- Confirmation modals with semi-transparent overlay
+
+### Public Timetable Styling
+
+- Clean, simple table layout
+- Status badges (green for active, gray for planned)
+- Mobile-responsive with scrolling
+- Consistent with existing design language
+
+## Integration Points
+
+1. **Admin Dashboard**: ScheduleMaker appears at the bottom of Admin Control Center
+2. **Public API**: Available via public `/schedules` endpoints without authentication
+3. **Flutter App**: TimetableViewer can be embedded or used as reference for mobile implementation
+4. **Frontend Flexibility**: TimetableViewer component is reusable for any public-facing website
+
+## Example Usage
+
+### Create a schedule (Admin)
+
+```bash
+curl -X POST https://transit.xtransit.testinstance.nl/admin/schedules \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "busLineId": 1,
+    "busId": 5,
+    "driverId": 101,
+    "startTime": "2026-05-06T08:00:00",
+    "endTime": "2026-05-06T17:00:00"
+  }'
+```
+
+### Get today's schedules (Public)
+
+```bash
+curl https://transit.xtransit.testinstance.nl/schedules?date=$(date +%Y-%m-%d)
+```
+
+### Get schedules for specific line (Public)
+
+```bash
+curl https://transit.xtransit.testinstance.nl/schedules?lineId=3
+```
+
+## Future Enhancements
+
+- Bulk schedule import from CSV
+- Recurring schedule templates (weekly, daily patterns)
+- Driver shift assignment with time tracking
+- Real-time schedule updates and notifications
+- Schedule conflict detection
+- Integration with GPS tracking for actual vs scheduled times
+- Historical schedule analytics