UX: implement visual product roadmap

backend/app/api/routers/vehicles.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from fastapi import APIRouter, Depends, HTTPException, Query
-from sqlalchemy import select
+from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
 from app.api.deps import get_current_user, get_db
@@ -19,6 +19,7 @@ from app.schemas import (
     MaintenanceOut,
     VehicleDetailOut,
     VehicleOut,
+    VehiclePageOut,
 )
 
 router = APIRouter(prefix="/api/v1/vehicles", tags=["vehicles"])
@@ -34,19 +35,41 @@ def _attention_vehicle_ids(db: Session) -> set:
     return set(rows)
 
 
-@router.get("", response_model=list[VehicleOut])
+@router.get("", response_model=list[VehicleOut] | VehiclePageOut)
 def list_vehicles(
     status: str | None = Query(default=None),
     attention_only: bool = Query(default=False),
+    query: str | None = Query(default=None, min_length=1, max_length=100),
+    page: int | None = Query(default=None, ge=1),
+    page_size: int = Query(default=25, ge=1, le=25),
     db: Session = Depends(get_db),
     _user: CurrentUser = Depends(get_current_user),
-) -> list[VehicleOut]:
+) -> list[VehicleOut] | VehiclePageOut:
     stmt = select(Vehicle).order_by(Vehicle.public_ref)
     if status:
         stmt = stmt.where(Vehicle.operational_status == status)
-    vehicles = db.scalars(stmt).all()
+    if query:
+        term = f"%{query.strip()}%"
+        stmt = stmt.where(
+            or_(
+                Vehicle.public_ref.ilike(term),
+                Vehicle.make.ilike(term),
+                Vehicle.model.ilike(term),
+                Vehicle.location.ilike(term),
+                Vehicle.registration_number.ilike(term),
+            )
+        )
     attention_ids = _attention_vehicle_ids(db)
-    out = [
+    if attention_only:
+        stmt = stmt.where(
+            or_(Vehicle.id.in_(attention_ids), Vehicle.operational_status == "blocked")
+        )
+    total = db.scalar(select(func.count()).select_from(stmt.subquery())) or 0
+    page_number = page or 1
+    vehicles = db.scalars(
+        stmt if page is None else stmt.offset((page_number - 1) * page_size).limit(page_size)
+    ).all()
+    items = [
         VehicleOut(
             public_ref=v.public_ref,
             make=v.make,
@@ -62,9 +85,16 @@ def list_vehicles(
         )
         for v in vehicles
     ]
-    if attention_only:
-        out = [v for v in out if v.attention]
-    return out
+    if page is None:
+        return items
+    total_pages = max(1, (total + page_size - 1) // page_size)
+    return VehiclePageOut(
+        items=items,
+        page=min(page_number, total_pages),
+        page_size=page_size,
+        total=total,
+        total_pages=total_pages,
+    )
 
 
 @router.get("/{public_ref}", response_model=VehicleDetailOut)