feat(deep-scan): trigger accepts 'deep'; scan_directory(mode) + enqueue backfill_phash

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

backend/app/api/import_admin.py

@@ -15,14 +15,13 @@ import_admin_bp = Blueprint("import_admin", __name__, url_prefix="/api/import")
 async def trigger_scan():
     body = await request.get_json(silent=True) or {}
     mode = body.get("mode", "quick")
-    if mode != "quick":
+    if mode not in ("quick", "deep"):
-        # FC-2d will accept 'deep'. For now, reject anything else.
+        return jsonify({"error": f"mode {mode!r} not supported; use 'quick' or 'deep'"}), 400
-        return jsonify({"error": f"mode {mode!r} not supported in FC-2a; use 'quick'"}), 400
 
     # Enqueue the scan task in Celery. The task creates the batch itself.
     from ..tasks.scan import scan_directory
 
-    async_result = scan_directory.delay(triggered_by="manual")
+    async_result = scan_directory.delay(triggered_by="manual", mode=mode)
     return jsonify({"celery_task_id": async_result.id, "mode": mode}), 202
 
 

backend/app/tasks/scan.py

@@ -34,8 +34,12 @@ def _sync_session_factory():
 
 
 @celery.task(name="backend.app.tasks.scan.scan_directory", bind=True)
-def scan_directory(self, triggered_by: str = "manual") -> int:
+def scan_directory(self, triggered_by: str = "manual",
-    """Walks the import root and creates ImportTasks. Returns the batch id."""
+                   mode: str = "quick") -> int:
+    """Walks the import root and creates ImportTasks. `mode` is 'quick'
+    or 'deep'; deep also enqueues a library-wide phash backfill and (via
+    Importer.deep) re-derives on already-imported files. Returns the
+    batch id."""
     SessionLocal = _sync_session_factory()
     with SessionLocal() as session:
         settings = session.execute(
@@ -46,7 +50,7 @@ def scan_directory(self, triggered_by: str = "manual") -> int:
         batch = ImportBatch(
             triggered_by=triggered_by,
             source_path=str(import_root),
-            scan_mode="quick",  # FC-2a is quick only; FC-2d adds 'deep'
+            scan_mode=mode,
             status="running",
         )
         session.add(batch)
@@ -84,4 +88,9 @@ def scan_directory(self, triggered_by: str = "manual") -> int:
             import_media_file.delay(task.id)
         session.commit()
 
+        if mode == "deep":
+            from .maintenance import backfill_phash
+
+            backfill_phash.delay()
+
     return batch_id

tests/test_api_import_admin.py

@@ -90,3 +90,33 @@ async def test_clear_completed(client, db):
     resp = await client.post("/api/import/clear-completed", json={"age_days": 7})
     body = await resp.get_json()
     assert body["deleted"] == 1
+
+
+@pytest.mark.asyncio
+async def test_trigger_accepts_deep(client, monkeypatch):
+    # Stub the task dispatch — assert the API accepts 'deep' and forwards
+    # mode, without running the real (eager) scan_directory.
+    from backend.app.tasks import scan as scan_mod
+
+    seen = {}
+
+    class _Res:
+        id = "celery-deep"
+
+    def _fake_delay(*, triggered_by, mode):
+        seen["triggered_by"] = triggered_by
+        seen["mode"] = mode
+        return _Res()
+
+    monkeypatch.setattr(scan_mod.scan_directory, "delay", _fake_delay)
+    resp = await client.post("/api/import/trigger", json={"mode": "deep"})
+    assert resp.status_code == 202
+    body = await resp.get_json()
+    assert body["mode"] == "deep"
+    assert seen == {"triggered_by": "manual", "mode": "deep"}
+
+
+@pytest.mark.asyncio
+async def test_trigger_still_rejects_unknown_mode(client):
+    resp = await client.post("/api/import/trigger", json={"mode": "wat"})
+    assert resp.status_code == 400