Add md file features in region, route, store, fleet, pricing, procurement, SFA, promotions, returns, finance, reporting, notifications, integration, and mobile capabilities

2026-08-19 15:18:31 +05:30
parent 45f374133f
commit d2390e7b12
25 changed files with 1565 additions and 88 deletions
@@ -0,0 +1,78 @@
+# 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.