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/providers/models.py

@@ -2,6 +2,8 @@
 Provider 模型管理 API
 """
 
+from __future__ import annotations
+
 from dataclasses import dataclass
 from typing import Any
 
@@ -35,6 +37,7 @@ from src.models.database import (
     Provider,
 )
 from src.services.model.service import ModelService
+from src.api.base.context import ApiRequestContext
 
 router = APIRouter(tags=["Model Management"])
 pipeline = ApiRequestPipeline()
@@ -205,7 +208,7 @@ async def delete_provider_model(
     model_id: str,
     request: Request,
     db: Session = Depends(get_db),
-):
+) -> Any:
     """
     删除模型
 
@@ -264,7 +267,7 @@ async def get_provider_available_source_models(
     provider_id: str,
     request: Request,
     db: Session = Depends(get_db),
-):
+) -> Any:
     """
     获取提供商支持的可用源模型
 
@@ -379,7 +382,7 @@ class AdminListProviderModelsAdapter(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:
@@ -396,7 +399,7 @@ class AdminCreateProviderModelAdapter(AdminApiAdapter):
     provider_id: str
     model_data: ModelCreate
 
-    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:
@@ -416,7 +419,7 @@ class AdminGetProviderModelAdapter(AdminApiAdapter):
     provider_id: str
     model_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         model = (
             db.query(Model)
@@ -435,7 +438,7 @@ class AdminUpdateProviderModelAdapter(AdminApiAdapter):
     model_id: str
     model_data: ModelUpdate
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         model = (
             db.query(Model)
@@ -459,7 +462,7 @@ class AdminDeleteProviderModelAdapter(AdminApiAdapter):
     provider_id: str
     model_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         model = (
             db.query(Model)
@@ -484,7 +487,7 @@ class AdminBatchCreateModelsAdapter(AdminApiAdapter):
     provider_id: str
     models_data: list[ModelCreate]
 
-    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:
@@ -503,7 +506,7 @@ class AdminBatchCreateModelsAdapter(AdminApiAdapter):
 class AdminGetProviderAvailableSourceModelsAdapter(AdminApiAdapter):
     provider_id: str
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         """
         返回 Provider 支持的所有 GlobalModel
 
@@ -571,7 +574,7 @@ class AdminBatchAssignModelsToProviderAdapter(AdminApiAdapter):
     provider_id: str
     payload: BatchAssignModelsToProviderRequest
 
-    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:
@@ -654,7 +657,7 @@ class AdminImportFromUpstreamAdapter(AdminApiAdapter):
     provider_id: str
     payload: ImportFromUpstreamRequest
 
-    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/providers/routes.py

@@ -1,5 +1,8 @@
 """管理员 Provider 管理路由。"""
 
+from __future__ import annotations
+
+from typing import Any
 import asyncio
 from datetime import datetime, timezone
 
@@ -19,6 +22,7 @@ from src.database import get_db
 from src.models.admin_requests import CreateProviderRequest, UpdateProviderRequest
 from src.models.database import GlobalModel, Provider, ProviderAPIKey
 from src.services.cache.provider_cache import ProviderCacheService
+from src.api.base.context import ApiRequestContext
 
 router = APIRouter(tags=["Provider CRUD"])
 pipeline = ApiRequestPipeline()
@@ -96,7 +100,7 @@ async def list_providers(
     limit: int = Query(100, ge=1, le=500),
     is_active: bool | None = None,
     db: Session = Depends(get_db),
-):
+) -> Any:
     """
     获取提供商列表
 
@@ -123,7 +127,7 @@ async def list_providers(
 
 
 @router.post("/")
-async def create_provider(request: Request, db: Session = Depends(get_db)):
+async def create_provider(request: Request, db: Session = Depends(get_db)) -> Any:
     """
     创建新提供商
 
@@ -155,7 +159,7 @@ async def create_provider(request: Request, db: Session = Depends(get_db)):
 
 
 @router.put("/{provider_id}")
-async def update_provider(provider_id: str, request: Request, db: Session = Depends(get_db)):
+async def update_provider(provider_id: str, request: Request, db: Session = Depends(get_db)) -> None:
     """
     更新提供商配置
 
@@ -191,7 +195,7 @@ async def update_provider(provider_id: str, request: Request, db: Session = Depe
 
 
 @router.delete("/{provider_id}")
-async def delete_provider(provider_id: str, request: Request, db: Session = Depends(get_db)):
+async def delete_provider(provider_id: str, request: Request, db: Session = Depends(get_db)) -> None:
     """
     删除提供商
 
@@ -213,7 +217,7 @@ class AdminListProvidersAdapter(AdminApiAdapter):
         self.limit = limit
         self.is_active = is_active
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         query = db.query(Provider)
         if self.is_active is not None:
@@ -251,7 +255,7 @@ class AdminListProvidersAdapter(AdminApiAdapter):
 
 
 class AdminCreateProviderAdapter(AdminApiAdapter):
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         payload = context.ensure_json_body()
 
@@ -333,7 +337,7 @@ class AdminUpdateProviderAdapter(AdminApiAdapter):
     def __init__(self, provider_id: str):
         self.provider_id = provider_id
 
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         payload = context.ensure_json_body()
 
@@ -412,7 +416,7 @@ class AdminDeleteProviderAdapter(AdminApiAdapter):
     def __init__(self, provider_id: str):
         self.provider_id = provider_id
 
-    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:
@@ -483,7 +487,7 @@ class AdminGetProviderMappingPreviewAdapter(AdminApiAdapter):
     def __init__(self, provider_id: str):
         self.provider_id = provider_id
 
-    async def handle(self, context) -> ProviderMappingPreviewResponse:  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> ProviderMappingPreviewResponse:  # type: ignore[override]
         db = context.db
 
         # 获取 Provider

src/api/admin/providers/summary.py

@@ -2,6 +2,7 @@
 Provider 摘要与健康监控 API
 """
 
+from typing import Any
 from dataclasses import dataclass
 from datetime import datetime, timedelta, timezone
 
@@ -22,6 +23,7 @@ from src.models.database import (
     ProviderEndpoint,
     RequestCandidate,
 )
+from src.api.base.context import ApiRequestContext
 from src.models.endpoint_models import (
     EndpointHealthEvent,
     EndpointHealthMonitor,
@@ -338,7 +340,7 @@ class AdminProviderHealthMonitorAdapter(AdminApiAdapter):
     lookback_hours: int
     per_endpoint_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:
@@ -447,7 +449,7 @@ class AdminProviderHealthMonitorAdapter(AdminApiAdapter):
 
 
 class AdminProviderSummaryAdapter(AdminApiAdapter):
-    async def handle(self, context):  # type: ignore[override]
+    async def handle(self, context: ApiRequestContext) -> Any:  # type: ignore[override]
         db = context.db
         providers = (
             db.query(Provider)
@@ -462,7 +464,7 @@ class AdminUpdateProviderSettingsAdapter(AdminApiAdapter):
     provider_id: str
     update_data: ProviderUpdateRequest
 
-    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: