feat(scanner): add DB fallback for series key resolution

When SerieScanner encounters a folder without a local key or data file,
it now optionally falls back to a database lookup by folder name. This
prevents newly-added series from being silently skipped on rescan when
their metadata only lives in the DB.

Changes:
- SerieScanner accepts an optional db_lookup callable
- SeriesApp forwards db_lookup to SerieScanner
- AnimeSeriesService adds get_by_folder_sync() helper
- dependencies.py wires a sync DB lookup into get_series_app()
- Unit tests cover fallback hit, miss, and exception paths

src/core/SerieScanner.py

@@ -15,7 +15,7 @@ import os
 import re
 import traceback
 import uuid
-from typing import Iterable, Iterator, Optional
+from typing import Callable, Iterable, Iterator, Optional
 
 from events import Events
 
@@ -43,12 +43,17 @@ class SerieScanner:
         scanner = SerieScanner("/path/to/anime", loader)
         scanner.scan()
         # Results are in scanner.keyDict
+
+        # With DB lookup fallback:
+        scanner = SerieScanner("/path/to/anime", loader,
+                               db_lookup=lambda folder: my_db.get_by_folder(folder))
     """
 
     def __init__(
         self,
         basePath: str,
         loader: Loader,
+        db_lookup: Optional[Callable[[str], Optional["Serie"]]] = None,
     ) -> None:
         """
         Initialize the SerieScanner.
@@ -56,8 +61,12 @@ class SerieScanner:
         Args:
             basePath: Base directory containing anime series
             loader: Loader instance for fetching series information
-            callback_manager: Optional callback manager for progress updates
-            
+            db_lookup: Optional callable ``(folder_name) -> Serie | None``.
+                When provided, it is called as a fallback when neither a
+                ``key`` file nor a ``data`` file is found in the folder.
+                This allows the database to supply the series key for
+                folders that have never had a local key file.
+
         Raises:
             ValueError: If basePath is invalid or doesn't exist
         """
@@ -75,6 +84,7 @@ class SerieScanner:
         self.directory: str = abs_path
         self.keyDict: dict[str, Serie] = {}
         self.loader: Loader = loader
+        self._db_lookup: Optional[Callable[[str], Optional[Serie]]] = db_lookup
         self._current_operation_id: Optional[str] = None
         self.events = Events()
         
@@ -268,6 +278,30 @@ class SerieScanner:
                     )
 
                     serie = self.__read_data_from_file(folder)
+                    if serie is None or not serie.key or not serie.key.strip():
+                        # Fallback: ask the database for a matching series
+                        if self._db_lookup is not None:
+                            try:
+                                serie = self._db_lookup(folder)
+                                if serie:
+                                    logger.info(
+                                        "DB lookup resolved folder '%s' -> key='%s'",
+                                        folder,
+                                        serie.key,
+                                    )
+                            except Exception as exc:
+                                logger.warning(
+                                    "DB lookup failed for folder '%s': %s",
+                                    folder,
+                                    exc,
+                                )
+                                serie = None
+
+                    if serie is None or not serie.key or not serie.key.strip():
+                        logger.warning(
+                            "No key or data file found for folder '%s', skipping",
+                            folder,
+                        )
                     if (
                         serie is not None
                         and serie.key

src/core/SeriesApp.py

@@ -14,7 +14,7 @@ import asyncio
 import logging
 import os
 from concurrent.futures import ThreadPoolExecutor
-from typing import Any, Dict, List, Optional
+from typing import Any, Callable, Dict, List, Optional
 
 from events import Events
 
@@ -143,12 +143,16 @@ class SeriesApp:
     def __init__(
         self,
         directory_to_search: str,
+        db_lookup: Optional[Callable[[str], Optional["Serie"]]] = None,
     ):
         """
         Initialize SeriesApp.
 
         Args:
             directory_to_search: Base directory for anime series
+            db_lookup: Optional callable ``(folder_name) -> Serie | None``
+                passed through to ``SerieScanner`` as a fallback key source
+                when no local ``key`` or ``data`` file exists.
         """
 
         self.directory_to_search = directory_to_search
@@ -162,7 +166,7 @@ class SeriesApp:
         self.loaders = Loaders()
         self.loader = self.loaders.GetLoader(key="aniworld.to")
         self.serie_scanner = SerieScanner(
-            directory_to_search, self.loader
+            directory_to_search, self.loader, db_lookup=db_lookup
         )
         # Skip automatic loading from data files - series will be loaded
         # from database by the service layer during application setup

src/server/database/service.py

@@ -148,7 +148,27 @@ class AnimeSeriesService:
             select(AnimeSeries).where(AnimeSeries.key == key)
         )
         return result.scalar_one_or_none()
-    
+
+    @staticmethod
+    def get_by_folder_sync(db: Session, folder: str) -> Optional[AnimeSeries]:
+        """Look up an anime series by its filesystem folder name (sync).
+
+        Intended as a fallback for ``SerieScanner`` when neither a ``key``
+        file nor a ``data`` file exists on disk for a given folder.
+
+        Args:
+            db: Synchronous database session (from ``get_sync_session``).
+            folder: Filesystem folder name to match (e.g.
+                ``"Rooster Fighter (2026)"``).
+
+        Returns:
+            ``AnimeSeries`` instance or ``None`` if not found.
+        """
+        result = db.execute(
+            select(AnimeSeries).where(AnimeSeries.folder == folder)
+        )
+        return result.scalar_one_or_none()
+
     @staticmethod
     async def get_all(
         db: AsyncSession,

src/server/utils/dependencies.py

@@ -57,6 +57,44 @@ _rate_limit_lock = Lock()
 _RATE_LIMIT_WINDOW_SECONDS = 60.0
 
 
+def _make_db_lookup():
+    """Build a synchronous ``(folder) -> Serie | None`` callable for SerieScanner.
+
+    The returned function opens a short-lived sync DB session, queries for a
+    series whose ``folder`` column matches the given name, and converts the
+    ORM row to a ``Serie`` domain object.  Returns ``None`` when the DB is not
+    yet initialised or no matching row is found.
+    """
+    from src.core.entities.series import Serie
+
+    def _lookup(folder: str) -> Optional["Serie"]:
+        try:
+            from src.server.database.connection import get_sync_session
+            from src.server.database.service import AnimeSeriesService
+
+            db = get_sync_session()
+            try:
+                row = AnimeSeriesService.get_by_folder_sync(db, folder)
+            finally:
+                db.close()
+
+            if row is None:
+                return None
+            return Serie(
+                key=row.key,
+                name=row.name or "",
+                site=row.site,
+                folder=row.folder,
+                episodeDict={},
+                year=row.year,
+            )
+        except RuntimeError:
+            # DB not initialised yet (e.g. first boot before init_db())
+            return None
+
+    return _lookup
+
+
 def get_series_app() -> SeriesApp:
     """
     Dependency to get SeriesApp instance.
@@ -134,7 +172,7 @@ def get_series_app() -> SeriesApp:
                         ),
                     )
 
-            _series_app = SeriesApp(anime_dir)
+            _series_app = SeriesApp(anime_dir, db_lookup=_make_db_lookup())
         except Exception as e:
             raise HTTPException(
                 status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,