feat(lidar): add RAVNOVES field review

src/k1link/web/lidar_api.py

@@ -6,13 +6,15 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import Any, Final
 
-from fastapi import APIRouter, HTTPException, Query
+from fastapi import APIRouter, HTTPException, Query, Response
 
 from k1link.compute import (
+    LidarFieldReviewV1,
     LidarGroundBenchmarkV1,
     LidarGroundError,
     LidarReplayError,
     LidarReplayPackV2,
+    lidar_field_review_catalog_item,
     lidar_ground_benchmark_catalog_item,
     lidar_ground_frame_detail,
     lidar_pack_catalog_item,
@@ -21,8 +23,10 @@ from k1link.compute import (
 
 LIDAR_CATALOG_SCHEMA: Final = "missioncore.lidar-replay-pack-catalog/v1"
 LIDAR_GROUND_CATALOG_SCHEMA: Final = "missioncore.lidar-ground-benchmark-catalog/v1"
+LIDAR_FIELD_REVIEW_CATALOG_SCHEMA: Final = "missioncore.lidar-field-review-catalog/v1"
 _PACK_ID = re.compile(r"^lidar-replay-pack-[a-f0-9]{64}$")
 _BENCHMARK_ID = re.compile(r"^ground-benchmark-[a-f0-9]{64}$")
+_FIELD_REVIEW_ID = re.compile(r"^lidar-field-review-[a-f0-9]{64}$")
 RootProvider = Callable[[], Path | None]
 
 
@@ -36,10 +40,16 @@ def configured_lidar_ground_root() -> Path | None:
     return Path(value).expanduser().absolute() if value else None
 
 
+def configured_lidar_field_review_root() -> Path | None:
+    value = os.environ.get("MISSIONCORE_LIDAR_FIELD_REVIEW_ROOT", "").strip()
+    return Path(value).expanduser().absolute() if value else None
+
+
 def build_lidar_router(
     *,
     root_provider: RootProvider = configured_lidar_replay_root,
     ground_root_provider: RootProvider = configured_lidar_ground_root,
+    field_review_root_provider: RootProvider = configured_lidar_field_review_root,
 ) -> APIRouter:
     router = APIRouter(prefix="/api/v1/lidar", tags=["lidar"])
 
@@ -269,4 +279,139 @@ def build_lidar_router(
                 detail="LiDAR ground frame не прошёл проверку целостности",
             ) from exc
 
+    @router.get("/field-reviews")
+    def list_lidar_field_reviews(
+        limit: int = Query(default=10, ge=1, le=50),
+    ) -> dict[str, Any]:
+        root = field_review_root_provider()
+        if root is None or not root.is_dir():
+            return {
+                "schema_version": LIDAR_FIELD_REVIEW_CATALOG_SCHEMA,
+                "configured": root is not None,
+                "items": [],
+                "valid_total": 0,
+                "invalid_total": 0,
+                "access": "read-only",
+            }
+        items: list[dict[str, object]] = []
+        invalid_total = 0
+        candidates = sorted(
+            (
+                candidate
+                for candidate in root.iterdir()
+                if candidate.is_dir() and _FIELD_REVIEW_ID.fullmatch(candidate.name) is not None
+            ),
+            key=lambda candidate: candidate.stat().st_mtime_ns,
+            reverse=True,
+        )
+        for candidate in candidates:
+            try:
+                review = LidarFieldReviewV1(candidate)
+                try:
+                    items.append(lidar_field_review_catalog_item(review))
+                finally:
+                    review.close()
+            except (LidarGroundError, OSError):
+                invalid_total += 1
+        return {
+            "schema_version": LIDAR_FIELD_REVIEW_CATALOG_SCHEMA,
+            "configured": True,
+            "items": items[:limit],
+            "valid_total": len(items),
+            "invalid_total": invalid_total,
+            "access": "read-only",
+        }
+
+    @router.get("/field-reviews/{review_id}/windows/{window_index}")
+    def get_lidar_field_review_window(
+        review_id: str,
+        window_index: int,
+    ) -> dict[str, object]:
+        if _FIELD_REVIEW_ID.fullmatch(review_id) is None or window_index < 0:
+            raise HTTPException(
+                status_code=404,
+                detail="LiDAR field-review window не найден",
+            )
+        root = field_review_root_provider()
+        if root is None or not root.is_dir():
+            raise HTTPException(
+                status_code=503,
+                detail="LiDAR field-review storage не настроен",
+            )
+        candidate = root / review_id
+        if not candidate.is_dir():
+            raise HTTPException(
+                status_code=404,
+                detail="LiDAR field review не найден",
+            )
+        try:
+            review = LidarFieldReviewV1(candidate)
+            try:
+                return review.window_detail(window_index)
+            finally:
+                review.close()
+        except IndexError as exc:
+            raise HTTPException(
+                status_code=404,
+                detail="LiDAR field-review window не найден",
+            ) from exc
+        except (LidarGroundError, OSError) as exc:
+            raise HTTPException(
+                status_code=409,
+                detail="LiDAR field review не прошёл проверку целостности",
+            ) from exc
+
+    @router.get("/field-reviews/{review_id}/windows/{window_index}/preview")
+    def get_lidar_field_review_preview(
+        review_id: str,
+        window_index: int,
+    ) -> Response:
+        if _FIELD_REVIEW_ID.fullmatch(review_id) is None or window_index < 0:
+            raise HTTPException(
+                status_code=404,
+                detail="LiDAR field-review preview не найден",
+            )
+        root = field_review_root_provider()
+        if root is None or not root.is_dir():
+            raise HTTPException(
+                status_code=503,
+                detail="LiDAR field-review storage не настроен",
+            )
+        candidate = root / review_id
+        if not candidate.is_dir():
+            raise HTTPException(
+                status_code=404,
+                detail="LiDAR field review не найден",
+            )
+        try:
+            review = LidarFieldReviewV1(candidate)
+            try:
+                windows = review.report.get("windows")
+                if not isinstance(windows, list) or not 0 <= window_index < len(windows):
+                    raise IndexError(window_index)
+                window = windows[window_index]
+                if not isinstance(window, dict) or not isinstance(window.get("key"), str):
+                    raise LidarGroundError("LiDAR field-review preview key is invalid")
+                preview = review.preview_paths.get(window["key"])
+                if preview is None:
+                    raise LidarGroundError("LiDAR field-review preview is missing")
+                content = preview.read_bytes()
+            finally:
+                review.close()
+        except IndexError as exc:
+            raise HTTPException(
+                status_code=404,
+                detail="LiDAR field-review preview не найден",
+            ) from exc
+        except (LidarGroundError, OSError) as exc:
+            raise HTTPException(
+                status_code=409,
+                detail="LiDAR field-review preview не прошёл проверку",
+            ) from exc
+        return Response(
+            content=content,
+            media_type="image/jpeg",
+            headers={"Cache-Control": "private, max-age=31536000, immutable"},
+        )
+
     return router