feat: Enhanced anime add flow with sanitized folders and targeted scan

- Add sanitize_folder_name utility for filesystem-safe folder names
- Add sanitized_folder property to Serie entity
- Update SerieList.add() to use sanitized display names for folders
- Add scan_single_series() method for targeted episode scanning
- Enhance add_series endpoint: DB save -> folder create -> targeted scan
- Update response to include missing_episodes and total_missing
- Add comprehensive unit tests for new functionality
- Update API tests with proper mock support

src/core/entities/SerieList.py

@@ -62,30 +62,49 @@ class SerieList:
         if not skip_load:
             self.load_series()
 
-    def add(self, serie: Serie) -> None:
+    def add(self, serie: Serie, use_sanitized_folder: bool = True) -> str:
         """
         Persist a new series if it is not already present (file-based mode).
         
-        Uses serie.key for identification. The serie.folder is used for
-        filesystem operations only.
+        Uses serie.key for identification. Creates the filesystem folder
+        using either the sanitized display name (default) or the existing
+        folder property.
         
         Args:
             serie: The Serie instance to add
+            use_sanitized_folder: If True (default), use serie.sanitized_folder
+                for the filesystem folder name based on display name.
+                If False, use serie.folder as-is for backward compatibility.
+        
+        Returns:
+            str: The folder path that was created/used
         
         Note:
             This method creates data files on disk. For database storage,
             use add_to_db() instead.
         """
         if self.contains(serie.key):
-            return
+            # Return existing folder path
+            existing = self.keyDict[serie.key]
+            return os.path.join(self.directory, existing.folder)
 
-        data_path = os.path.join(self.directory, serie.folder, "data")
-        anime_path = os.path.join(self.directory, serie.folder)
+        # Determine folder name to use
+        if use_sanitized_folder:
+            folder_name = serie.sanitized_folder
+            # Update the serie's folder property to match what we create
+            serie.folder = folder_name
+        else:
+            folder_name = serie.folder
+
+        data_path = os.path.join(self.directory, folder_name, "data")
+        anime_path = os.path.join(self.directory, folder_name)
         os.makedirs(anime_path, exist_ok=True)
         if not os.path.isfile(data_path):
             serie.save_to_file(data_path)
             # Store by key, not folder
             self.keyDict[serie.key] = serie
+        
+        return anime_path
 
     def contains(self, key: str) -> bool:
         """

src/core/entities/series.py

@@ -1,6 +1,8 @@
 import json
 import warnings
 
+from src.server.utils.filesystem import sanitize_folder_name
+
 
 class Serie:
     """
@@ -127,6 +129,35 @@ class Serie:
     def episodeDict(self, value: dict[int, list[int]]):
         self._episodeDict = value
 
+    @property
+    def sanitized_folder(self) -> str:
+        """
+        Get a filesystem-safe folder name derived from the display name.
+        
+        This property returns a sanitized version of the series name
+        suitable for use as a filesystem folder name. It removes/replaces
+        characters that are invalid for filesystems while preserving
+        Unicode characters.
+        
+        Use this property when creating folders for the series on disk.
+        The `folder` property stores the actual folder name used.
+        
+        Returns:
+            str: Filesystem-safe folder name based on display name
+            
+        Example:
+            >>> serie = Serie("attack-on-titan", "Attack on Titan: Final", ...)
+            >>> serie.sanitized_folder
+            'Attack on Titan Final'
+        """
+        # Use name if available, fall back to folder, then key
+        name_to_sanitize = self._name or self._folder or self._key
+        try:
+            return sanitize_folder_name(name_to_sanitize)
+        except ValueError:
+            # Fallback to key if name cannot be sanitized
+            return sanitize_folder_name(self._key)
+
     def to_dict(self):
         """Convert Serie object to dictionary for JSON serialization."""
         return {