Strengthen backend quality gates

Boyeep · Boyeep · commit 0990fa1e2b8e · 2026-03-22T01:25:22.000+07:00
diff --git a/.github/workflows/template-ci.yml b/.github/workflows/template-ci.yml
@@ -79,6 +79,10 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install -e ./backend[dev]
 
+      - name: Lint backend
+        run: python -m ruff check .
+        working-directory: backend
+
       - name: Run backend tests
         run: python -m pytest
         working-directory: backend
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -61,7 +61,7 @@ npm run check
 What they cover:
 
 - `check:contract`: regenerates frontend API types and fails if generated files drift from `docs/openapi.yaml`
-- `check`: frontend lint, frontend typecheck, frontend production build, backend tests, backend bytecode compile
+- `check`: frontend lint, frontend typecheck, frontend production build, backend Ruff lint, backend tests, backend bytecode compile
 
 ## Changing the API Contract
 
diff --git a/README.md b/README.md
@@ -103,6 +103,7 @@ The root check runs:
 - frontend lint
 - frontend typecheck
 - frontend production build
+- backend Ruff lint
 - backend `pytest`
 - backend `compileall`
 
diff --git a/backend/README.md b/backend/README.md
@@ -26,5 +26,6 @@ python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
 ## Test
 
 ```bash
+python -m ruff check .
 python -m pytest
 ```
diff --git a/backend/app/vision/service.py b/backend/app/vision/service.py
@@ -11,8 +11,8 @@
     Detection,
     ImageMetadata,
     Metric,
-    PolygonPoint,
     PipelineSummary,
+    PolygonPoint,
     SegmentationRegion,
 )
 from app.vision.pipelines import PipelineDefinition
@@ -45,6 +45,40 @@ def _contour_to_polygon(contour: np.ndarray) -> list[PolygonPoint]:
     ]
 
 
+def _partition_significant_contours(
+    contours: list[np.ndarray],
+    image_area: int,
+) -> tuple[list[np.ndarray], list[np.ndarray]]:
+    significant: list[np.ndarray] = []
+    near_full_frame: list[np.ndarray] = []
+
+    for contour in contours:
+        area_ratio = cv2.contourArea(contour) / image_area
+        if area_ratio < 0.02:
+            continue
+
+        x, y, width, height = cv2.boundingRect(contour)
+        box_area_ratio = (width * height) / image_area
+        if area_ratio >= 0.9 or box_area_ratio >= 0.94:
+            near_full_frame.append(contour)
+            continue
+
+        significant.append(contour)
+
+    return significant, near_full_frame
+
+
+def _select_significant_contours(
+    contours: list[np.ndarray],
+    image_area: int,
+) -> list[np.ndarray]:
+    significant, near_full_frame = _partition_significant_contours(
+        contours,
+        image_area,
+    )
+    return significant or near_full_frame[:1]
+
+
 def _starter_detection(image: np.ndarray) -> tuple[list[dict], list[dict], list[dict]]:
     grayscale = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
     blurred = cv2.GaussianBlur(grayscale, (5, 5), 0)
@@ -151,33 +185,43 @@ def _foreground_segmentation(
 
     best_mask = thresholded
     best_score = -1.0
+    best_has_non_full_contours = False
 
     for candidate in candidates:
         cleaned = cv2.morphologyEx(
             candidate,
             cv2.MORPH_OPEN,
             np.ones((5, 5), dtype=np.uint8),
         )
-        contours, _ = cv2.findContours(
+        raw_contours, _ = cv2.findContours(
             cleaned,
             cv2.RETR_EXTERNAL,
             cv2.CHAIN_APPROX_SIMPLE,
         )
-        significant = [
-            contour
-            for contour in contours
-            if cv2.contourArea(contour) / image_area >= 0.02
-        ]
-        score = sum(cv2.contourArea(contour) for contour in significant) / image_area
-        if score > best_score:
+        significant, near_full_frame = _partition_significant_contours(
+            raw_contours,
+            image_area,
+        )
+        candidate_contours = significant or near_full_frame[:1]
+        has_non_full_contours = bool(significant)
+        score = (
+            sum(cv2.contourArea(contour) for contour in candidate_contours) / image_area
+        )
+        if (
+            has_non_full_contours and not best_has_non_full_contours
+        ) or (
+            has_non_full_contours == best_has_non_full_contours and score > best_score
+        ):
             best_score = score
             best_mask = cleaned
+            best_has_non_full_contours = has_non_full_contours
 
-    contours, _ = cv2.findContours(
+    raw_contours, _ = cv2.findContours(
         best_mask,
         cv2.RETR_EXTERNAL,
         cv2.CHAIN_APPROX_SIMPLE,
     )
+    contours = _select_significant_contours(raw_contours, image_area)
 
     detections = []
     segmentations = []
@@ -242,7 +286,10 @@ def _dominant_color(image: np.ndarray) -> tuple[list[dict], list[dict], list[dic
     "starter-detection": PipelineDefinition(
         id="starter-detection",
         name="Starter Detection",
-        summary="Detection-first sample pipeline that returns object-style boxes and confidence scores.",
+        summary=(
+            "Detection-first sample pipeline that returns object-style boxes "
+            "and confidence scores."
+        ),
         tags=["detection", "default", "cpu"],
         runtime="opencv-cpu",
         sample_outputs=["object boxes", "confidence scores", "coverage metrics"],
@@ -251,7 +298,10 @@ def _dominant_color(image: np.ndarray) -> tuple[list[dict], list[dict], list[dic
     "document-layout": PipelineDefinition(
         id="document-layout",
         name="Document Layout",
-        summary="Document-oriented box extraction for capture, scanning, and kiosk workflows.",
+        summary=(
+            "Document-oriented box extraction for capture, scanning, and kiosk "
+            "workflows."
+        ),
         tags=["detection", "document", "cpu"],
         runtime="opencv-cpu",
         sample_outputs=["quadrilateral candidates", "layout blocks"],
@@ -260,7 +310,10 @@ def _dominant_color(image: np.ndarray) -> tuple[list[dict], list[dict], list[dic
     "foreground-segmentation": PipelineDefinition(
         id="foreground-segmentation",
         name="Foreground Segmentation",
-        summary="Segmentation extension pipeline that returns region polygons plus detection-style boxes.",
+        summary=(
+            "Segmentation extension pipeline that returns region polygons plus "
+            "detection-style boxes."
+        ),
         tags=["segmentation", "extension", "cpu"],
         runtime="opencv-cpu",
         sample_outputs=["region polygons", "mask coverage", "derived boxes"],
@@ -269,7 +322,10 @@ def _dominant_color(image: np.ndarray) -> tuple[list[dict], list[dict], list[dic
     "dominant-color": PipelineDefinition(
         id="dominant-color",
         name="Dominant Color",
-        summary="Metrics-only extension pipeline for quality and image analytics workflows.",
+        summary=(
+            "Metrics-only extension pipeline for quality and image analytics "
+            "workflows."
+        ),
         tags=["analytics", "extension", "cpu"],
         runtime="opencv-cpu",
         sample_outputs=["channel metrics", "brightness"],
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
@@ -21,10 +21,18 @@ dependencies = [
 dev = [
   "httpx>=0.28,<1.0",
   "pytest>=8.3,<9.0",
+  "ruff>=0.11,<1.0",
 ]
 
 [tool.hatch.build.targets.wheel]
 packages = ["app"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
diff --git a/backend/tests/fixtures/detection-scene.png b/backend/tests/fixtures/detection-scene.png
diff --git a/backend/tests/fixtures/document-layout.png b/backend/tests/fixtures/document-layout.png
diff --git a/backend/tests/fixtures/segmentation-scene.png b/backend/tests/fixtures/segmentation-scene.png
diff --git a/backend/tests/helpers.py b/backend/tests/helpers.py
@@ -0,0 +1,11 @@
+from pathlib import Path
+
+FIXTURE_DIR = Path(__file__).parent / "fixtures"
+
+
+def fixture_path(name: str) -> Path:
+    return FIXTURE_DIR / name
+
+
+def fixture_bytes(name: str) -> bytes:
+    return fixture_path(name).read_bytes()
diff --git a/backend/tests/test_health.py b/backend/tests/test_health.py
@@ -2,7 +2,6 @@
 
 from app.main import app
 
-
 client = TestClient(app)
 
 
diff --git a/backend/tests/test_inference_route.py b/backend/tests/test_inference_route.py
@@ -0,0 +1,37 @@
+from fastapi.testclient import TestClient
+
+from app.main import app
+from tests.helpers import fixture_bytes
+
+client = TestClient(app)
+
+
+def test_analyze_route_accepts_fixture_upload() -> None:
+    response = client.post(
+        "/api/v1/analyze",
+        data={"pipeline_id": "starter-detection"},
+        files={
+            "file": (
+                "detection-scene.png",
+                fixture_bytes("detection-scene.png"),
+                "image/png",
+            )
+        },
+    )
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["pipeline"]["id"] == "starter-detection"
+    assert payload["image"]["filename"] == "detection-scene.png"
+    assert len(payload["detections"]) >= 2
+
+
+def test_analyze_route_rejects_non_image_upload() -> None:
+    response = client.post(
+        "/api/v1/analyze",
+        data={"pipeline_id": "starter-detection"},
+        files={"file": ("notes.txt", b"not-an-image", "text/plain")},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["detail"] == "Only image uploads are supported."
diff --git a/backend/tests/test_vision_service.py b/backend/tests/test_vision_service.py
@@ -1,47 +1,55 @@
-import cv2
-import numpy as np
-
 from app.config import Settings
 from app.vision.service import analyze_image
+from tests.helpers import fixture_bytes
 
 
-def test_starter_detection_pipeline_returns_metrics() -> None:
-    canvas = np.zeros((240, 320, 3), dtype=np.uint8)
-    cv2.rectangle(canvas, (30, 30), (280, 180), (255, 255, 255), thickness=-1)
-
-    success, encoded = cv2.imencode(".jpg", canvas)
-    assert success
-
+def test_starter_detection_pipeline_uses_detection_fixture() -> None:
     result = analyze_image(
-        image_bytes=encoded.tobytes(),
-        filename="synthetic.jpg",
-        content_type="image/jpeg",
+        image_bytes=fixture_bytes("detection-scene.png"),
+        filename="detection-scene.png",
+        content_type="image/png",
         pipeline_id="starter-detection",
         settings=Settings(),
     )
 
     assert result.pipeline.id == "starter-detection"
     assert result.image.width == 320
+    assert result.image.height == 240
+    assert len(result.detections) >= 2
+    assert result.detections[0].label == "primary-object"
     assert result.segmentations == []
     assert any(metric.name == "edge_density" for metric in result.metrics)
 
 
-def test_foreground_segmentation_pipeline_returns_regions() -> None:
-    canvas = np.zeros((240, 320, 3), dtype=np.uint8)
-    cv2.circle(canvas, (160, 120), 70, (255, 255, 255), thickness=-1)
+def test_document_layout_pipeline_uses_document_fixture() -> None:
+    result = analyze_image(
+        image_bytes=fixture_bytes("document-layout.png"),
+        filename="document-layout.png",
+        content_type="image/png",
+        pipeline_id="document-layout",
+        settings=Settings(),
+    )
+
+    assert result.pipeline.id == "document-layout"
+    assert len(result.detections) >= 1
+    assert any(
+        detection.label == "document-candidate"
+        for detection in result.detections
+    )
+    assert any(metric.name == "layout_candidates" for metric in result.metrics)
 
-    success, encoded = cv2.imencode(".jpg", canvas)
-    assert success
 
+def test_foreground_segmentation_pipeline_uses_segmentation_fixture() -> None:
     result = analyze_image(
-        image_bytes=encoded.tobytes(),
-        filename="segmentation.jpg",
-        content_type="image/jpeg",
+        image_bytes=fixture_bytes("segmentation-scene.png"),
+        filename="segmentation-scene.png",
+        content_type="image/png",
         pipeline_id="foreground-segmentation",
         settings=Settings(),
     )
 
     assert result.pipeline.id == "foreground-segmentation"
-    assert len(result.segmentations) >= 1
+    assert len(result.segmentations) >= 2
     assert result.segmentations[0].polygon
+    assert result.segmentations[0].box.width < result.image.width
     assert any(metric.name == "segmented_regions" for metric in result.metrics)
diff --git a/scripts/check.mjs b/scripts/check.mjs
@@ -33,6 +33,11 @@ const commands = [
     command: "npm",
     args: ["run", "build"],
   },
+  {
+    cwd: backendDir,
+    command: backendPython,
+    args: ["-m", "ruff", "check", "."],
+  },
   {
     cwd: backendDir,
     command: backendPython,
