# 13 — Fleet Management (Beyond CRUD)

**Status**: Not Started
**Depends On**: 00 — Existing Gap Fixes

---

## Goal

Vehicle CRUD already exists (`Features/Vehicle`). This step covers everything in
[mainPlan.md §5](./mainPlan.md#5-vehicle--fleet-management) that isn't
plain CRUD or already scoped into [03_ride_lifecycle.md](./03_ride_lifecycle.md)/
[04_loading_event.md](./04_loading_event.md): maintenance, fuel, telemetry, and utilization.

---

## Background / Context

`Vehicle` today only has `RegNumber`/`NumberPlate`. No capacity, ownership, maintenance, or fuel
data exists. There is no `Driver` entity — see gap #10 in
[00_existing_gaps.md](./00_existing_gaps.md).

---

## Data Model Changes

### Vehicle — New Fields

`CapacityVolume`, `CapacityWeight` (needed by `calculateLoadPlan` in
[04_loading_event.md](./04_loading_event.md)), `OwnershipType` (`Owned`, `Leased`, `Contracted`).

### Maintenance Task

`VehicleId`, `MaintenanceType`, `DueAt` (date or mileage-based), `CompletedAt`.

### Fuel Log

`VehicleId`, `Amount`, `Liters`, `Date`.

### Telemetry Record

`VehicleId`, `GpsCoords`, `Speed`, `Timestamp` — high-volume; likely a separate store/retention
policy from the rest of the schema (see Open Questions).

---

## API Endpoints

| Function reference | Endpoint intent |
|---|---|
| `scheduleMaintenance(vehicleId, maintenanceType, dueAt)` | `POST /api/vehicles/{id}/maintenance` |
| `logFuelExpense(vehicleId, amount, liters, date)` | `POST /api/vehicles/{id}/fuel-logs` |
| `recordVehicleTelemetry(vehicleId, gpsCoords, speed, timestamp)` | `POST /api/vehicles/{id}/telemetry` — likely ingested via [22_integration_api.md](./22_integration_api.md) rather than direct client calls |
| `getVehicleUtilization(vehicleId, period)` | `GET /api/vehicles/{id}/utilization?period=...` |
| `retireVehicle(vehicleId, reason)` | Extends existing `DELETE /api/vehicles/{id}` with a reason field |

---

## Business Rules

- `retireVehicle` must be blocked while the vehicle is on an open/active ride
  ([03_ride_lifecycle.md](./03_ride_lifecycle.md)).
- Overdue `Maintenance Task`s should block a vehicle from being assigned to a new ride — exact
  enforcement level (hard block vs. warning) to confirm.

---

## Open Questions

- Is real-time telemetry (`recordVehicleTelemetry`) actually in scope, or is odometer
  start/end (`DeliveryRun.Meterstart`/`Meterend`, already modeled) sufficient for this business?
- What third-party telematics provider, if any, is being integrated (affects [22_integration_api.md](./22_integration_api.md))?

---

## Implementation Notes

> Fill this section in during planning discussion before writing any code.