Task 4.4: Update WebSocket API Endpoints to use key identifier

- Updated src/server/api/websocket.py docstrings to document key as primary series identifier
- Updated src/server/models/websocket.py with detailed docstrings explaining key and folder fields in message payloads
- Updated src/server/services/websocket_service.py broadcast method docstrings to document key field usage
- Added WebSocket message example with key in infrastructure.md
- All 83 WebSocket tests pass
- Task 4.4 marked as complete in instructions.md

src/server/services/websocket_service.py

@@ -3,6 +3,15 @@
 This module provides a comprehensive WebSocket manager for handling
 real-time updates, connection management, room-based messaging, and
 broadcast functionality for the Aniworld web application.
+
+Series Identifier Convention:
+    - `key`: Primary identifier for series (provider-assigned, URL-safe)
+             e.g., "attack-on-titan"
+    - `folder`: Display metadata only (e.g., "Attack on Titan (2013)")
+    
+All broadcast methods that handle series-related data should include `key`
+as the primary identifier in the message payload. The `folder` field is
+optional and used for display purposes only.
 """
 from __future__ import annotations
 
@@ -363,6 +372,16 @@ class WebSocketService:
         Args:
             download_id: The download item identifier
             progress_data: Progress information (percent, speed, etc.)
+                          Should include 'key' (series identifier) and
+                          optionally 'folder' (display name)
+        
+        Note:
+            The progress_data should include:
+            - key: Series identifier (primary, e.g., 'attack-on-titan')
+            - folder: Series folder name (optional, display only)
+            - percent: Download progress percentage
+            - speed_mbps: Download speed
+            - eta_seconds: Estimated time remaining
         """
         message = {
             "type": "download_progress",
@@ -382,6 +401,14 @@ class WebSocketService:
         Args:
             download_id: The download item identifier
             result_data: Download result information
+                        Should include 'key' (series identifier) and
+                        optionally 'folder' (display name)
+        
+        Note:
+            The result_data should include:
+            - key: Series identifier (primary, e.g., 'attack-on-titan')
+            - folder: Series folder name (optional, display only)
+            - file_path: Path to the downloaded file
         """
         message = {
             "type": "download_complete",
@@ -401,6 +428,14 @@ class WebSocketService:
         Args:
             download_id: The download item identifier
             error_data: Error information
+                       Should include 'key' (series identifier) and
+                       optionally 'folder' (display name)
+        
+        Note:
+            The error_data should include:
+            - key: Series identifier (primary, e.g., 'attack-on-titan')
+            - folder: Series folder name (optional, display only)
+            - error_message: Description of the failure
         """
         message = {
             "type": "download_failed",
@@ -412,7 +447,9 @@ class WebSocketService:
         }
         await self._manager.broadcast_to_room(message, "downloads")
 
-    async def broadcast_queue_status(self, status_data: Dict[str, Any]) -> None:
+    async def broadcast_queue_status(
+        self, status_data: Dict[str, Any]
+    ) -> None:
         """Broadcast queue status update to all clients.
         
         Args: