03 - User Journeys (Transport Module)

• 1. Fleet onboarding: add vehicle + driver, define route, assign students
• 2. Daily ops: check fleet and route health
• 3. Find a student's route
• 4. Decommission (soft delete) with guards
• 5. Parent bus lookup (forward-looking)
• 6. Live tracking / bus attendance / fee calc (planned)
• Journey coverage summary

Primary journeys for the Transport module, mapped to exact endpoints. Each step cites the source. States/loading/error handling follow 00-shared/06 §3.

1. Fleet onboarding: add vehicle + driver, define route, assign students

Mirrors the setup flow in docs/user-flows/END_TO_END_USER_FLOWS.md:205-222.

1. Add vehicle - form (plate, model, capacity >= 1, type) -> POST /api/v1/transport/vehicles (transport.controller.ts:30-34).
   • 409 duplicate plate -> inline error (transport.service.ts:38-45).
2. Add driver - form (first/last name, licenseNumber, phone, optional email, licenseExpiry, address, emergencyContact, joinedAt, notes) -> POST /api/v1/transport/drivers (transport.controller.ts:90-94).
   • 409 duplicate license OR duplicate phone (transport.service.ts:177-190).
3. Create route - name, startPoint, endPoint, ordered stops, optional vehicleId + driverId, estimatedDuration, notes -> POST /api/v1/transport/routes (transport.controller.ts:60-64).
   • 409 duplicate name (transport.service.ts:113-116).
4. Assign students - pick student + route + shift (morning/evening/both) + optional stopName/notes -> POST /api/v1/transport/assign (transport.controller.ts:120-124).
   • 409 already-assigned (transport.service.ts:252-258).

Error states at each step: 401 (token) -> re-login; 409 -> inline conflict message; 429/offline -> AppOfflineBanner + retry (see 14_QA_Checklist.md §1).

2. Daily ops: check fleet and route health

1. Open Transport Overview (/transport/overview) - aggregates counts by calling GET /transport/vehicles, GET /transport/routes, GET /transport/drivers (transport.controller.ts:36-40, 66-70, 96-100).
2. Drill into vehicle detail (GET /transport/vehicles/:id, transport.controller.ts:42-46), driver detail (GET /transport/drivers/:id, :102-106), route detail with stops (GET /transport/routes/:id, :72-76).

3. Find a student's route

1. Search/select student (students module) -> GET /transport/assignments/:studentId (transport.controller.ts:126-130) -> list of assignments with populated route (route-assignment.repository.ts:20-24).
2. Show route name, shift, stopName, status; empty state "No route assigned".
3. Remove an assignment -> confirm dialog -> DELETE /transport/assignments/:id (transport.controller.ts:132-136) -> item leaves list (optimistic, rollback on 404).

4. Decommission (soft delete) with guards

1. Vehicle: delete -> if a route references it, 409 "Vehicle is assigned to a route." (transport.service.ts:94-99); else soft delete + VehicleDeleted event (transport.service.ts:100-109).
2. Driver: same guard on route reference (transport.service.ts:241-246).
3. Route: delete -> if students are assigned, 409 "Route has active student assignments." (transport.service.ts:168-171); else soft delete (transport.service.ts:172-173).
4. UI consequence: 409 -> explain the dependency, offer navigation to the blocking route list/detail instead of a generic error.

5. Parent bus lookup (forward-looking)

Parent opens child profile -> route assignment + stop (GET /transport/assignments/:childId per docs/user-flows/END_TO_END_USER_FLOWS.md:392-406); live bus position, arrival alerts (transport.delay, :430) and QR boarding (forward-looking).

6. Live tracking / bus attendance / fee calc (planned)

Per IMPLEMENTATION_PLAN.md:229: live tracking, bus attendance, fee calc, emergency. No backend surface today - all steps (planned).

Journey coverage summary