feat(thumb-backfill): backfill_thumbnails planner task — keyset-paginates ImageRecord, NULLs bad thumb paths, enqueues generate_thumbnail for NULL/missing/corrupt

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

backend/app/tasks/thumbnail.py

@@ -74,3 +74,58 @@ def generate_thumbnail(self, image_id: int) -> dict:
         session.add(record)
         session.commit()
         return {"status": "ok", "image_id": image_id, "path": str(result.path)}
+
+
+@celery.task(
+    name="backend.app.tasks.thumbnail.backfill_thumbnails",
+    bind=True,
+)
+def backfill_thumbnails(self) -> dict:
+    """Scan ImageRecord and enqueue generate_thumbnail for rows whose
+    thumbnail is missing, gone from disk, or has wrong magic bytes.
+
+    Keyset paginates by id ASC, page size 500. NULLs out thumbnail_path for
+    rows that point at a missing or corrupt file before enqueueing — keeps
+    the DB self-consistent on partial runs and makes re-runs safe.
+
+    Returns {"enqueued": N, "ok": M, "regenerated": K} where:
+      - enqueued = total generate_thumbnail.delay() calls
+      - ok       = rows whose existing thumbnail file is valid (skipped)
+      - regenerated = subset of enqueued that had a non-NULL thumbnail_path
+                      cleared (i.e. missing + corrupt)
+    """
+    from sqlalchemy import select, update
+
+    SessionLocal = _sync_session_factory()
+    enqueued = 0
+    ok = 0
+    regenerated = 0
+    last_id = 0
+    with SessionLocal() as session:
+        while True:
+            rows = session.execute(
+                select(ImageRecord.id, ImageRecord.thumbnail_path)
+                .where(ImageRecord.id > last_id)
+                .order_by(ImageRecord.id.asc())
+                .limit(500)
+            ).all()
+            if not rows:
+                break
+            for image_id, thumb_path in rows:
+                if thumb_path is None:
+                    generate_thumbnail.delay(image_id)
+                    enqueued += 1
+                elif _thumb_is_valid(Path(thumb_path)):
+                    ok += 1
+                else:
+                    session.execute(
+                        update(ImageRecord)
+                        .where(ImageRecord.id == image_id)
+                        .values(thumbnail_path=None)
+                    )
+                    generate_thumbnail.delay(image_id)
+                    enqueued += 1
+                    regenerated += 1
+            session.commit()
+            last_id = rows[-1][0]
+    return {"enqueued": enqueued, "ok": ok, "regenerated": regenerated}