M12: complete daily operations cycle

backend/app/api/routers/vehicles.py

@@ -1,10 +1,12 @@
 from __future__ import annotations
 
+import uuid
+
 from fastapi import APIRouter, Depends, HTTPException, Query
 from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
-from app.api.deps import get_current_user, get_db
+from app.api.deps import get_current_user, get_db, require_operations_manager
 from app.models.booking import Booking
 from app.models.customer import Customer
 from app.models.data_quality import DataQualityIssue
@@ -13,14 +15,17 @@ from app.models.maintenance import MaintenanceRecord
 from app.models.vehicle import Vehicle
 from app.schemas import (
     BookingSummaryOut,
+    CreateMaintenanceRequest,
     CurrentUser,
     DataQualityIssueOut,
     InspectionOut,
     MaintenanceOut,
+    ReleaseVehicleRequest,
     VehicleDetailOut,
     VehicleOut,
     VehiclePageOut,
 )
+from app.services.audit import record_audit_event
 
 router = APIRouter(prefix="/api/v1/vehicles", tags=["vehicles"])
 
@@ -192,3 +197,104 @@ def get_vehicle(
             for q in issues
         ],
     )
+
+
+@router.post("/{public_ref}/maintenance", response_model=MaintenanceOut, status_code=201)
+def create_maintenance_record(
+    public_ref: str,
+    body: CreateMaintenanceRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(require_operations_manager),
+) -> MaintenanceOut:
+    vehicle = db.scalar(select(Vehicle).where(Vehicle.public_ref == public_ref).with_for_update())
+    if vehicle is None:
+        raise HTTPException(status_code=404, detail="Vehicle not found")
+    record = MaintenanceRecord(
+        public_ref=f"MAINT-{uuid.uuid4().hex[:8].upper()}",
+        vehicle_id=vehicle.id,
+        occurred_at=body.occurred_at,
+        odometer_km=body.odometer_km,
+        category=body.category,
+        summary=body.summary.strip(),
+    )
+    db.add(record)
+    vehicle.odometer_km = max(vehicle.odometer_km, body.odometer_km)
+    if body.next_service_km is not None:
+        if body.next_service_km < vehicle.odometer_km:
+            raise HTTPException(status_code=422, detail="Next service must not be below odometer")
+        vehicle.next_service_km = body.next_service_km
+    if body.mark_maintenance:
+        vehicle.operational_status = "maintenance"
+    vehicle.version += 1
+    db.flush()
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="maintenance_record_created",
+        entity_type="vehicle",
+        entity_id=vehicle.id,
+        after={"maintenance_ref": record.public_ref, "status": vehicle.operational_status},
+    )
+    db.commit()
+    return MaintenanceOut(
+        public_ref=record.public_ref,
+        occurred_at=record.occurred_at,
+        odometer_km=record.odometer_km,
+        category=record.category,
+        summary=record.summary,
+    )
+
+
+@router.post("/{public_ref}/release", response_model=VehicleOut)
+def release_vehicle(
+    public_ref: str,
+    body: ReleaseVehicleRequest,
+    db: Session = Depends(get_db),
+    user: CurrentUser = Depends(require_operations_manager),
+) -> VehicleOut:
+    vehicle = db.scalar(select(Vehicle).where(Vehicle.public_ref == public_ref).with_for_update())
+    if vehicle is None:
+        raise HTTPException(status_code=404, detail="Vehicle not found")
+    if vehicle.operational_status not in {"cleaning", "maintenance", "blocked"}:
+        raise HTTPException(status_code=409, detail="Vehicle does not require release")
+    active_booking = db.scalar(
+        select(Booking.id).where(Booking.vehicle_id == vehicle.id, Booking.status == "active")
+    )
+    open_high_issue = db.scalar(
+        select(DataQualityIssue.id).where(
+            DataQualityIssue.entity_type == "vehicle",
+            DataQualityIssue.entity_id == vehicle.id,
+            DataQualityIssue.status == "open",
+            DataQualityIssue.severity == "high",
+        )
+    )
+    if active_booking is not None or open_high_issue is not None:
+        raise HTTPException(status_code=409, detail="Vehicle still has a blocking condition")
+    before = {"status": vehicle.operational_status}
+    vehicle.operational_status = "available"
+    vehicle.version += 1
+    record_audit_event(
+        db,
+        actor_type="user",
+        actor_label=user.display_name,
+        action="vehicle_released",
+        entity_type="vehicle",
+        entity_id=vehicle.id,
+        before=before,
+        after={"status": "available", "reason": body.reason.strip()},
+    )
+    db.commit()
+    return VehicleOut(
+        public_ref=vehicle.public_ref,
+        make=vehicle.make,
+        model=vehicle.model,
+        model_year=vehicle.model_year,
+        registration_number=vehicle.registration_number,
+        location=vehicle.location,
+        operational_status=vehicle.operational_status,
+        odometer_km=vehicle.odometer_km,
+        next_service_km=vehicle.next_service_km,
+        active=vehicle.active,
+        attention=False,
+    )