Refactor OAuth provider linking and unlinking logic into a dedicated service; enhance error handling and logging throughout the application; improve sound management and scanning services with better file handling and unique naming; implement centralized error and logging services for consistent API responses and application-wide logging configuration.

app/services/sound_scanner_service.py

@@ -140,76 +140,91 @@ class SoundScannerService:
 
     @staticmethod
     def _process_audio_file(file_path: str, base_dir: str) -> dict:
-        """Process a single audio file and add it to database if new.
-
-        Args:
-            file_path: Full path to the audio file
-            base_dir: Base directory for relative path calculation
-
-        Returns:
-            dict: Processing result with added flag and reason
-
-        """
-        # Calculate file hash for deduplication
+        """Process a single audio file and add it to database if new."""
         file_hash = SoundScannerService._calculate_file_hash(file_path)
-
-        # Get file metadata
         metadata = SoundScannerService._extract_audio_metadata(file_path)
-
-        # Calculate relative filename from base directory
         relative_path = Path(file_path).relative_to(Path(base_dir))
 
-        # Check if file already exists in database by hash
-        existing_sound = Sound.find_by_hash(file_hash)
-        if existing_sound:
-            return {
-                "added": False,
-                "reason": f"File already exists as '{existing_sound.name}'",
-            }
+        # Check for existing file by hash (duplicate content)
+        if existing_sound := Sound.find_by_hash(file_hash):
+            return SoundScannerService._handle_duplicate_file(existing_sound)
 
-        # Check if filename already exists in database
-        existing_filename_sound = Sound.find_by_filename(str(relative_path))
-        if existing_filename_sound:
-            # Remove normalized files and clear normalized info
-            SoundScannerService._clear_normalized_files(existing_filename_sound)
-            existing_filename_sound.clear_normalized_info()
-
-            # Update existing sound with new file information
-            existing_filename_sound.update_file_info(
-                filename=str(relative_path),
-                duration=metadata["duration"],
-                size=metadata["size"],
-                hash_value=file_hash,
+        # Check for existing filename (file replacement)
+        if existing_filename_sound := Sound.find_by_filename(
+            str(relative_path)
+        ):
+            return SoundScannerService._handle_file_replacement(
+                existing_filename_sound,
+                str(relative_path),
+                metadata,
+                file_hash,
             )
 
-            return {
-                "added": False,
-                "updated": True,
-                "sound_id": existing_filename_sound.id,
-                "reason": f"Updated existing sound '{existing_filename_sound.name}' with new file data",
-            }
-
-        # Generate sound name from filename (without extension)
-        sound_name = Path(file_path).stem
-
-        # Check if name already exists and make it unique if needed
-        counter = 1
-        original_name = sound_name
-        while Sound.find_by_name(sound_name):
-            sound_name = f"{original_name}_{counter}"
-            counter += 1
-
         # Create new sound record
+        return SoundScannerService._create_new_sound(
+            file_path,
+            str(relative_path),
+            metadata,
+            file_hash,
+        )
+
+    @staticmethod
+    def _handle_duplicate_file(existing_sound: Sound) -> dict:
+        """Handle case where file content already exists in database."""
+        return {
+            "added": False,
+            "reason": f"File already exists as '{existing_sound.name}'",
+        }
+
+    @staticmethod
+    def _handle_file_replacement(
+        existing_sound: Sound,
+        relative_path: str,
+        metadata: dict,
+        file_hash: str,
+    ) -> dict:
+        """Handle case where filename exists but content may be different."""
+        # Remove normalized files and clear normalized info
+        SoundScannerService._clear_normalized_files(existing_sound)
+        existing_sound.clear_normalized_info()
+
+        # Update existing sound with new file information
+        existing_sound.update_file_info(
+            filename=relative_path,
+            duration=metadata["duration"],
+            size=metadata["size"],
+            hash_value=file_hash,
+        )
+
+        return {
+            "added": False,
+            "updated": True,
+            "sound_id": existing_sound.id,
+            "reason": f"Updated existing sound '{existing_sound.name}' with new file data",
+        }
+
+    @staticmethod
+    def _create_new_sound(
+        file_path: str,
+        relative_path: str,
+        metadata: dict,
+        file_hash: str,
+    ) -> dict:
+        """Create a new sound record in the database."""
+        sound_name = SoundScannerService._generate_unique_sound_name(
+            Path(file_path).stem,
+        )
+
         sound = Sound.create_sound(
-            sound_type="SDB",  # Soundboard type
+            sound_type="SDB",
             name=sound_name,
-            filename=str(relative_path),
+            filename=relative_path,
             duration=metadata["duration"],
             size=metadata["size"],
             hash_value=file_hash,
             is_music=False,
             is_deletable=False,
-            commit=False,  # Don't commit individually, let scanner handle transaction
+            commit=False,
         )
 
         return {
@@ -218,6 +233,18 @@ class SoundScannerService:
             "reason": "New file added successfully",
         }
 
+    @staticmethod
+    def _generate_unique_sound_name(base_name: str) -> str:
+        """Generate a unique sound name by appending numbers if needed."""
+        sound_name = base_name
+        counter = 1
+
+        while Sound.find_by_name(sound_name):
+            sound_name = f"{base_name}_{counter}"
+            counter += 1
+
+        return sound_name
+
     @staticmethod
     def _calculate_file_hash(file_path: str) -> str:
         """Calculate SHA256 hash of file contents."""
@@ -249,7 +276,7 @@ class SoundScannerService:
                     logger.info(f"Removed normalized file: {normalized_path}")
                 except Exception as e:
                     logger.warning(
-                        f"Could not remove normalized file {normalized_path}: {e}"
+                        f"Could not remove normalized file {normalized_path}: {e}",
                     )
 
     @staticmethod