refactor: add folder rename configuration and service

Add configurable folder rename patterns via settings with anime_folder_rename_regex and custom_pattern options. Integrate into SerieScanner and SeriesApp for consistent episode organization.

src/core/SerieScanner.py

@@ -24,10 +24,9 @@ from src.config.settings import settings
 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.core.utils.key_utils import generate_key_from_folder
 from src.server.database.connection import get_sync_session
 from src.server.database.service import AnimeSeriesService, EpisodeService
-from src.core.utils.key_utils import generate_key_from_folder
 
 logger = logging.getLogger(__name__)
 error_logger = logging.getLogger("error")
@@ -58,6 +57,11 @@ class SerieScanner:
         # With DB lookup fallback:
         scanner = SerieScanner("/path/to/anime", loader,
                                db_lookup=lambda folder: my_db.get_by_folder(folder))
+
+        # With scan key overrides:
+        overrides = {"Folder Name": "correct-provider-key"}
+        scanner = SerieScanner("/path/to/anime", loader,
+                               scan_key_overrides=overrides)
     """
 
     def __init__(
@@ -65,6 +69,7 @@ class SerieScanner:
         basePath: str,
         loader: Loader,
         db_lookup: Optional[Callable[[str], Optional["Serie"]]] = None,
+        scan_key_overrides: Optional[dict[str, str]] = None,
     ) -> None:
         """
         Initialize the SerieScanner.
@@ -77,6 +82,10 @@ class SerieScanner:
                 ``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.
+            scan_key_overrides: Optional dict mapping folder names to provider
+                keys. When a folder name is found in this dict, the override
+                key is used instead of auto-generating from folder name.
+                Format: {"Folder Name": "actual-provider-key"}
 
         Raises:
             ValueError: If basePath is invalid or doesn't exist
@@ -96,6 +105,7 @@ class SerieScanner:
         self.keyDict: dict[str, Serie] = {}
         self.loader: Loader = loader
         self._db_lookup: Optional[Callable[[str], Optional[Serie]]] = db_lookup
+        self._scan_key_overrides: Optional[dict[str, str]] = scan_key_overrides
         self._current_operation_id: Optional[str] = None
         self.events = Events()
         
@@ -619,7 +629,8 @@ class SerieScanner:
         2. If found, return cached Serie object
         3. If not in DB, fall back to provider search via _db_lookup callback
         4. If still not found, try reading 'data' file for legacy deployments
-        5. Generate key from folder name as last resort
+        5. Check user-provided key overrides in scan_key_overrides
+        6. Generate key from folder name as last resort
 
         Args:
             folder_name: Filesystem folder name
@@ -692,7 +703,25 @@ class SerieScanner:
                 )
                 return Serie.load_from_file(serie_file)
 
-        # Step 4: Generate key from folder name as last resort
+        # Step 4: Check for user-provided key overrides before generating
+        if self._scan_key_overrides and folder_name in self._scan_key_overrides:
+            override_key = self._scan_key_overrides[folder_name]
+            year_from_folder = self._extract_year_from_folder_name(folder_name)
+            logger.info(
+                "Using scan key override for folder '%s' -> key='%s'",
+                folder_name,
+                override_key
+            )
+            return Serie(
+                key=override_key,
+                name="",  # Name will be fetched from provider if needed
+                site="aniworld.to",
+                folder=folder_name,
+                episodeDict=dict(),
+                year=year_from_folder
+            )
+
+        # Step 5: Generate key from folder name as last resort
         # This handles edge cases like non-Latin characters or special symbols
         try:
             generated_key = generate_key_from_folder(folder_name)

src/core/SeriesApp.py

@@ -166,7 +166,10 @@ class SeriesApp:
         self.loaders = Loaders()
         self.loader = self.loaders.GetLoader(key="aniworld.to")
         self.serie_scanner = SerieScanner(
-            directory_to_search, self.loader, db_lookup=db_lookup
+            directory_to_search,
+            self.loader,
+            db_lookup=db_lookup,
+            scan_key_overrides=settings.scan_key_overrides,
         )
         # Skip automatic loading from data files - series will be loaded
         # from database by the service layer during application setup