fix(P3-2): Add documentation for unused versioning module

apps/api/app/middleware/versioning.py

@@ -1,6 +1,18 @@
 """
-API 版本管理中间件
+API versioning middleware.
+
+NOTE: This module is currently not used. To enable API versioning:
+1. Import VersionMiddleware in main.py
+2. Add it to the app middleware stack
+
+Example usage:
+    from app.middleware.versioning import APIVersionMiddleware
+    app.add_middleware(APIVersionMiddleware)
+
+This middleware adds X-API-Version header to responses based on the
+version extracted from the URL path (e.g., /v1/... or /v2/...).
 """
+from __future__ import annotations
 
 from datetime import datetime
 
@@ -9,9 +21,9 @@ from starlette.middleware.base import BaseHTTPMiddleware
 
 
 class APIVersionMiddleware(BaseHTTPMiddleware):
-    """API 版本管理中间件"""
+    """API versioning middleware."""
 
-    # 版本配置
+    # API version definitions
     VERSIONS = {
         "v1": {
             "status": "stable",
@@ -28,17 +40,17 @@ class APIVersionMiddleware(BaseHTTPMiddleware):
     }
 
     async def dispatch(self, request: Request, call_next):
-        # 提取版本号
+        # Extract version from URL path
         version = self._extract_version(request.url.path)
 
-        # 处理请求
+        # Process request
         response = await call_next(request)
 
-        # 添加版本信息头
+        # Add version header
         if version:
             response.headers["X-API-Version"] = version
 
-            # 添加弃用警告
+            # Add deprecation headers if version is deprecated
             version_info = self.VERSIONS.get(version, {})
             if version_info.get("deprecated"):
                 response.headers["X-API-Deprecated"] = "true"
@@ -51,8 +63,8 @@ class APIVersionMiddleware(BaseHTTPMiddleware):
 
         return response
 
-    def _extract_version(self, path: str) -> str:
-        """从路径中提取版本号"""
+    def _extract_version(self, path: str) -> str | None:
+        """Extract version from URL path."""
         parts = path.split("/")
         for part in parts:
             if part.startswith("v") and part[1:].isdigit():
@@ -61,14 +73,14 @@ class APIVersionMiddleware(BaseHTTPMiddleware):
 
 
 class VersionNotFoundMiddleware(BaseHTTPMiddleware):
-    """处理已下线的 API 版本"""
+    """Middleware to reject requests for unsupported API versions."""
 
-    SUNSET_VERSIONS = []  # 已下线的版本列表
+    UNSUPPORTED_VERSIONS = []  # Add deprecated versions here
 
     async def dispatch(self, request: Request, call_next):
         version = self._extract_version(request.url.path)
 
-        if version in self.SUNSET_VERSIONS:
+        if version in self.UNSUPPORTED_VERSIONS:
             from fastapi.responses import JSONResponse
 
             return JSONResponse(
@@ -85,8 +97,8 @@ class VersionNotFoundMiddleware(BaseHTTPMiddleware):
 
         return await call_next(request)
 
-    def _extract_version(self, path: str) -> str:
-        """从路径中提取版本号"""
+    def _extract_version(self, path: str) -> str | None:
+        """Extract version from URL path."""
         parts = path.split("/")
         for part in parts:
             if part.startswith("v") and part[1:].isdigit():