fix: 修复 mypy 类型检查错误并升级到 Python 3.14

主要变更：
- 修复 1483 个 mypy 类型检查错误
- 添加缺失的类型注解 (Any, Callable, Session 等)
- 修复隐式 Optional 类型 (param: Type = None -> param: Type | None = None)
- 修复 __new__ 单例模式返回类型
- 添加 type: ignore 注释处理第三方库类型问题
- 更新 pyproject.toml 依赖到 Python 3.14 兼容版本
- 更新 mypy/black 配置为 Python 3.14

src/api/admin/endpoints/concurrency.py

@@ -2,6 +2,7 @@
 Key RPM 限制管理 API
 """
 
+from typing import Any
 from dataclasses import dataclass
 
 from fastapi import APIRouter, Depends, Request
@@ -14,6 +15,7 @@ from src.database import get_db
 from src.models.database import ProviderAPIKey
 from src.models.endpoint_models import KeyRpmStatusResponse
 from src.services.rate_limit.concurrency_manager import get_concurrency_manager
+from src.api.base.context import ApiRequestContext
 
 router = APIRouter(tags=["RPM Control"])
 pipeline = ApiRequestPipeline()
@@ -71,7 +73,7 @@ async def reset_key_rpm(
 class AdminKeyRpmAdapter(AdminApiAdapter):
     key_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == self.key_id).first()
         if not key:
@@ -91,7 +93,7 @@ class AdminKeyRpmAdapter(AdminApiAdapter):
 class AdminResetKeyRpmAdapter(AdminApiAdapter):
     key_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         concurrency_manager = await get_concurrency_manager()
         await concurrency_manager.reset_key_rpm(key_id=self.key_id)
         return {"message": "RPM 计数已重置"}

src/api/admin/endpoints/health.py

@@ -2,6 +2,9 @@
 Endpoint 健康监控 API
 """
 
+from __future__ import annotations
+
+from typing import Any
 from collections import defaultdict
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
@@ -25,6 +28,7 @@ from src.models.endpoint_models import (
 )
 from src.services.health.endpoint import EndpointHealthService
 from src.services.health.monitor import health_monitor
+from src.api.base.context import ApiRequestContext
 
 router = APIRouter(tags=["Endpoint Health"])
 pipeline = ApiRequestPipeline()
@@ -58,7 +62,7 @@ async def get_endpoint_health_status(
     request: Request,
     lookback_hours: int = Query(6, ge=1, le=72, description="回溯的小时数"),
     db: Session = Depends(get_db),
-):
+) -> Any:
     """
     获取端点健康状态（简化视图，与用户端点统一）
 
@@ -218,7 +222,7 @@ async def recover_all_keys_health(
 
 
 class AdminHealthSummaryAdapter(AdminApiAdapter):
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         summary = health_monitor.get_all_health_status(context.db)
         return HealthSummaryResponse(**summary)
 
@@ -229,7 +233,7 @@ class AdminEndpointHealthStatusAdapter(AdminApiAdapter):
 
     lookback_hours: int
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         from src.services.health.endpoint import EndpointHealthService
 
         db = context.db
@@ -256,7 +260,7 @@ class AdminApiFormatHealthMonitorAdapter(AdminApiAdapter):
     lookback_hours: int
     per_format_limit: int
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         now = datetime.now(timezone.utc)
         since = now - timedelta(hours=self.lookback_hours)
@@ -463,7 +467,7 @@ class AdminKeyHealthAdapter(AdminApiAdapter):
     key_id: str
     api_format: str | None = None
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         health_data = health_monitor.get_key_health(context.db, self.key_id, self.api_format)
         if not health_data:
             raise NotFoundException(f"Key {self.key_id} 不存在")
@@ -501,7 +505,7 @@ class AdminRecoverKeyHealthAdapter(AdminApiAdapter):
     key_id: str
     api_format: str | None = None
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == self.key_id).first()
         if not key:
@@ -544,7 +548,7 @@ class AdminRecoverKeyHealthAdapter(AdminApiAdapter):
 class AdminRecoverAllKeysHealthAdapter(AdminApiAdapter):
     """批量恢复所有熔断 Key 的健康状态"""
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
 
         # 查找所有有熔断格式的 Key（检查 circuit_breaker_by_format JSON 字段）

src/api/admin/endpoints/keys.py

@@ -2,6 +2,9 @@
 Provider API Keys 管理
 """
 
+from __future__ import annotations
+
+from typing import Any
 import json
 import uuid
 from dataclasses import dataclass
@@ -25,6 +28,7 @@ from src.models.endpoint_models import (
     EndpointAPIKeyUpdate,
 )
 from src.services.cache.provider_cache import ProviderCacheService
+from src.api.base.context import ApiRequestContext
 
 router = APIRouter(tags=["Provider Keys"])
 pipeline = ApiRequestPipeline()
@@ -207,7 +211,7 @@ class AdminUpdateEndpointKeyAdapter(AdminApiAdapter):
     key_id: str
     key_data: EndpointAPIKeyUpdate
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == self.key_id).first()
         if not key:
@@ -378,7 +382,7 @@ class AdminRevealEndpointKeyAdapter(AdminApiAdapter):
 
     key_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == self.key_id).first()
         if not key:
@@ -436,7 +440,7 @@ class AdminRevealEndpointKeyAdapter(AdminApiAdapter):
 class AdminDeleteEndpointKeyAdapter(AdminApiAdapter):
     key_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         key = db.query(ProviderAPIKey).filter(ProviderAPIKey.id == self.key_id).first()
         if not key:
@@ -472,7 +476,7 @@ class AdminDeleteEndpointKeyAdapter(AdminApiAdapter):
 
 
 class AdminGetKeysGroupedByFormatAdapter(AdminApiAdapter):
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
 
         # Key 属于 Provider：按 key.api_formats 分组展示
@@ -677,7 +681,7 @@ class AdminListProviderKeysAdapter(AdminApiAdapter):
     skip: int
     limit: int
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         provider = db.query(Provider).filter(Provider.id == self.provider_id).first()
         if not provider:
@@ -702,7 +706,7 @@ class AdminCreateProviderKeyAdapter(AdminApiAdapter):
     provider_id: str
     key_data: EndpointAPIKeyCreate
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         provider = db.query(Provider).filter(Provider.id == self.provider_id).first()
         if not provider:

src/api/admin/endpoints/routes.py

@@ -2,6 +2,9 @@
 ProviderEndpoint CRUD 管理 API
 """
 
+from __future__ import annotations
+
+from typing import Any
 import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -18,6 +21,7 @@ from src.core.exceptions import InvalidRequestException, NotFoundException
 from src.core.logger import logger
 from src.database import get_db
 from src.models.database import Provider, ProviderAPIKey, ProviderEndpoint
+from src.api.base.context import ApiRequestContext
 from src.models.endpoint_models import (
     ProviderEndpointCreate,
     ProviderEndpointResponse,
@@ -215,7 +219,7 @@ class AdminListProviderEndpointsAdapter(AdminApiAdapter):
     skip: int
     limit: int
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         provider = db.query(Provider).filter(Provider.id == self.provider_id).first()
         if not provider:
@@ -270,7 +274,7 @@ class AdminCreateProviderEndpointAdapter(AdminApiAdapter):
     provider_id: str
     endpoint_data: ProviderEndpointCreate
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         provider = db.query(Provider).filter(Provider.id == self.provider_id).first()
         if not provider:
@@ -340,7 +344,7 @@ class AdminCreateProviderEndpointAdapter(AdminApiAdapter):
 class AdminGetProviderEndpointAdapter(AdminApiAdapter):
     endpoint_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         endpoint = (
             db.query(ProviderEndpoint, Provider)
@@ -390,7 +394,7 @@ class AdminUpdateProviderEndpointAdapter(AdminApiAdapter):
     endpoint_id: str
     endpoint_data: ProviderEndpointUpdate
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         endpoint = (
             db.query(ProviderEndpoint).filter(ProviderEndpoint.id == self.endpoint_id).first()
@@ -459,7 +463,7 @@ class AdminUpdateProviderEndpointAdapter(AdminApiAdapter):
 class AdminDeleteProviderEndpointAdapter(AdminApiAdapter):
     endpoint_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         endpoint = (
             db.query(ProviderEndpoint).filter(ProviderEndpoint.id == self.endpoint_id).first()