feat(SerieScanner): DB lookup primary, deprecate key file fallback

DB now source of truth for folder -> Serie resolution.

Changes:
- AnimeSeriesService.get_by_folder(): new async lookup by folder name
- SerieScanner.__read_data_from_file(): query DB first, then provider callback, then legacy key file (temporary, removed v3.0.0)
- Serie: reconstruct from DB record with episode dict
- Key file: warn on use, scheduled removal v3.0.0

Add unit tests for DB hit/miss/callback/fallback edge cases

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

src/core/SerieScanner.py

@@ -23,6 +23,9 @@ from src.core.entities.series import Serie
 from src.core.exceptions.Exceptions import MatchNotFoundError, NoKeyFoundException
 from src.core.providers.base_provider import Loader
 
+from src.server.database.connection import get_sync_session
+from src.server.database.service import AnimeSeriesService
+
 logger = logging.getLogger(__name__)
 error_logger = logging.getLogger("error")
 no_key_found_logger = logging.getLogger("series.nokey")
@@ -278,25 +281,6 @@ 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",
@@ -470,25 +454,83 @@ class SerieScanner:
                 yield anime_name, mp4_files if has_files else []
 
     def __read_data_from_file(self, folder_name: str) -> Optional[Serie]:
-        """Read serie data from file or key file.
-        
+        """Load or discover a Serie for the given folder.
+
+        Strategy:
+        1. Query DB by folder name
+        2. If found, return cached Serie object
+        3. If not in DB, fall back to provider search via _db_lookup callback
+        4. (Legacy) If still not found, try reading 'key' file as last resort
+
         Args:
             folder_name: Filesystem folder name
-                        (used only to locate data files)
-            
+
         Returns:
             Serie object with valid key if found, None otherwise
-            
-        Note:
-            The returned Serie will have its 'key' as the primary identifier.
-            The 'folder' field is metadata only.
-        """
-        folder_path = os.path.join(self.directory, folder_name)
-        key = None
-        key_file = os.path.join(folder_path, 'key')
-        serie_file = os.path.join(folder_path, 'data')
 
+        Note:
+            DB is the source of truth. File-based lookups (key/data files)
+            are temporary backward compatibility for deployments with old data.
+            Will be removed in v3.0.0.
+        """
+        # Step 1: Try DB lookup by folder name
+        try:
+            session = get_sync_session()
+            try:
+                anime_series = AnimeSeriesService.get_by_folder_sync(session, folder_name)
+                if anime_series:
+                    # Reconstruct Serie from DB record
+                    episode_dict: dict[int, list[int]] = {}
+                    if anime_series.episodes:
+                        for ep in anime_series.episodes:
+                            season = ep.season or 1
+                            if season not in episode_dict:
+                                episode_dict[season] = []
+                            episode_dict[season].append(ep.episode_number or ep.number or 0)
+                    return Serie(
+                        key=anime_series.key,
+                        name=anime_series.name,
+                        site=anime_series.site,
+                        folder=anime_series.folder,
+                        episodeDict=episode_dict,
+                        year=anime_series.year
+                    )
+            finally:
+                session.close()
+        except Exception as exc:
+            logger.warning(
+                "DB lookup failed for folder '%s': %s",
+                folder_name,
+                exc
+            )
+
+        # Step 2: Fall back to provider search callback
+        if self._db_lookup is not None:
+            try:
+                serie = self._db_lookup(folder_name)
+                if serie and serie.key and serie.key.strip():
+                    logger.info(
+                        "Provider lookup resolved folder '%s' -> key='%s'",
+                        folder_name,
+                        serie.key
+                    )
+                    return serie
+            except Exception as exc:
+                logger.warning(
+                    "Provider lookup failed for folder '%s': %s",
+                    folder_name,
+                    exc
+                )
+
+        # Step 3: Legacy fallback - TEMPORARY (remove in v3.0.0)
+        folder_path = os.path.join(self.directory, folder_name)
+        key_file = os.path.join(folder_path, 'key')
         if os.path.exists(key_file):
+            logger.warning(
+                "Using legacy 'key' file for '%s' - this fallback is deprecated "
+                "and will be removed in v3.0.0",
+                folder_name
+            )
             with open(key_file, 'r', encoding='utf-8') as file:
                 key = file.read().strip()
                 logger.info(
@@ -499,6 +541,7 @@ class SerieScanner:
                 year_from_folder = self._extract_year_from_folder_name(folder_name)
                 return Serie(key, "", "aniworld.to", folder_name, dict(), year=year_from_folder)
 
+        serie_file = os.path.join(folder_path, 'data')
         if os.path.exists(serie_file):
             with open(serie_file, "rb") as file:
                 logger.info(

src/server/database/service.py

@@ -169,6 +169,26 @@ class AnimeSeriesService:
         )
         return result.scalar_one_or_none()
 
+    @staticmethod
+    async def get_by_folder(db: AsyncSession, folder: str) -> Optional[AnimeSeries]:
+        """Look up an anime series by its filesystem folder name (async).
+
+        Intended as primary lookup for ``SerieScanner`` when scanning
+        directories, replacing the legacy file-based lookups (key/data files).
+
+        Args:
+            db: Async database session.
+            folder: Filesystem folder name to match (e.g.
+                ``"Rooster Fighter (2026)"``).
+
+        Returns:
+            ``AnimeSeries`` instance or ``None`` if not found.
+        """
+        result = await db.execute(
+            select(AnimeSeries).where(AnimeSeries.folder == folder)
+        )
+        return result.scalar_one_or_none()
+
     @staticmethod
     async def get_all(
         db: AsyncSession,