feat(fc2c-i): showcase random-sample service and endpoint

tests/test_api_showcase.py

@@ -0,0 +1,35 @@
+import pytest
+
+from backend.app import create_app
+from backend.app.models import ImageRecord
+
+pytestmark = pytest.mark.integration
+
+
+@pytest.fixture
+async def client():
+    app = create_app()
+    async with app.test_client() as c:
+        yield c
+
+
+@pytest.mark.asyncio
+async def test_showcase_returns_images(client, db):
+    for i in range(8):
+        db.add(ImageRecord(
+            path=f"/images/sc/{i}.jpg", sha256=f"c{i:063d}",
+            size_bytes=1, mime="image/jpeg", width=10, height=10,
+            origin="imported_filesystem", integrity_status="unknown",
+        ))
+    await db.flush()
+    await db.commit()
+    resp = await client.get("/api/showcase?limit=4")
+    assert resp.status_code == 200
+    body = await resp.get_json()
+    assert "images" in body and len(body["images"]) <= 4
+
+
+@pytest.mark.asyncio
+async def test_showcase_rejects_bad_limit(client):
+    resp = await client.get("/api/showcase?limit=oops")
+    assert resp.status_code == 400

tests/test_showcase_service.py

@@ -0,0 +1,45 @@
+import pytest
+
+from backend.app.models import ImageRecord
+from backend.app.services.showcase_service import ShowcaseService
+
+pytestmark = pytest.mark.integration
+
+
+async def _seed(db, n):
+    for i in range(n):
+        db.add(ImageRecord(
+            path=f"/images/s/{i}.jpg", sha256=f"s{i:063d}",
+            size_bytes=1, mime="image/jpeg", width=100, height=200,
+            origin="imported_filesystem", integrity_status="unknown",
+        ))
+    await db.flush()
+    await db.commit()
+
+
+@pytest.mark.asyncio
+async def test_random_sample_returns_items_with_shape(db):
+    await _seed(db, 20)
+    svc = ShowcaseService(db)
+    items = await svc.random_sample(limit=5)
+    assert 1 <= len(items) <= 5
+    first = items[0]
+    assert set(first.keys()) == {
+        "id", "sha256", "mime", "width", "height", "thumbnail_url"
+    }
+    assert first["thumbnail_url"].startswith("/images/thumbs/")
+
+
+@pytest.mark.asyncio
+async def test_random_sample_empty_table_returns_empty(db):
+    svc = ShowcaseService(db)
+    assert await svc.random_sample(limit=5) == []
+
+
+@pytest.mark.asyncio
+async def test_random_sample_rejects_bad_limit(db):
+    svc = ShowcaseService(db)
+    with pytest.raises(ValueError):
+        await svc.random_sample(limit=0)
+    with pytest.raises(ValueError):
+        await svc.random_sample(limit=201)