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/services/cache/affinity_manager.py

@@ -18,6 +18,8 @@
 - 这样可以支持"独立余额Key"场景，每个Key有自己的缓存亲和性
 """
 
+from __future__ import annotations
+
 import asyncio
 import json
 import os
@@ -76,7 +78,7 @@ class CacheAffinityManager:
     # 默认缓存TTL（秒）- 使用统一常量
     DEFAULT_CACHE_TTL = CacheTTL.CACHE_AFFINITY
 
-    def __init__(self, redis_client=None, default_ttl: int = DEFAULT_CACHE_TTL):
+    def __init__(self, redis_client: Any | None = None, default_ttl: int = DEFAULT_CACHE_TTL) -> None:
         """
         初始化缓存亲和性管理器
 
@@ -149,7 +151,7 @@ class CacheAffinityManager:
                 return None
             return dict(payload)
 
-    async def _set_l1_entry(self, cache_key: str, payload: dict[str, Any] | None):
+    async def _set_l1_entry(self, cache_key: str, payload: dict[str, Any] | None) -> None:
         async with self._l1_lock:
             if not payload:
                 self._l1_cache.pop(cache_key, None)
@@ -194,7 +196,7 @@ class CacheAffinityManager:
         return len(expired_keys)
 
     @asynccontextmanager
-    async def _acquire_request_lock(self, cache_key: str):
+    async def _acquire_request_lock(self, cache_key: str) -> None:
         lock = self._request_locks.get(cache_key)
         if lock is None:
             lock = asyncio.Lock()
@@ -647,7 +649,7 @@ class CacheAffinityManager:
 _affinity_manager: CacheAffinityManager | None = None
 
 
-async def get_affinity_manager(redis_client=None) -> CacheAffinityManager:
+async def get_affinity_manager(redis_client: Any | None = None) -> CacheAffinityManager:
     """
     获取全局CacheAffinityManager实例（若Redis不可用则降级为内存模式）
 

src/services/cache/aware_scheduler.py

@@ -133,10 +133,10 @@ class CacheAwareScheduler:
 
     def __init__(
         self,
-        redis_client=None,
+        redis_client: Any | None = None,
         priority_mode: str | None = None,
         scheduling_mode: str | None = None,
-    ):
+    ) -> None:
         """
         初始化调度器
 
@@ -182,7 +182,7 @@ class CacheAwareScheduler:
             "last_reservation_result": None,
         }
 
-    async def _ensure_initialized(self):
+    async def _ensure_initialized(self) -> None:
         """确保所有异步组件已初始化"""
         if self._affinity_manager is None:
             self._affinity_manager = await get_affinity_manager(self.redis)
@@ -512,7 +512,7 @@ class CacheAwareScheduler:
             f"User.allowed_models={user.allowed_models if user else 'N/A'}"
         )
 
-        def merge_restrictions(key_restriction, user_restriction):
+        def merge_restrictions(key_restriction: Any, user_restriction: Any) -> Any:
             """合并两个限制列表，返回有效的限制集合"""
             key_set = set(key_restriction) if key_restriction else None
             user_set = set(user_restriction) if user_restriction else None
@@ -1405,7 +1405,7 @@ class CacheAwareScheduler:
                 result.extend(sorted_group)
             else:
                 # 单个候选或没有 affinity_key，按次要排序条件排序
-                def secondary_sort(c: ProviderCandidate):
+                def secondary_sort(c: ProviderCandidate) -> Any:
                     return (
                         c.provider.provider_priority,
                         c.key.internal_priority if c.key else 999999,
@@ -1541,7 +1541,7 @@ class CacheAwareScheduler:
         endpoint_id: str | None = None,
         key_id: str | None = None,
         provider_id: str | None = None,
-    ):
+    ) -> Any:
         """
         失效指定亲和性标识符对特定API格式和模型的缓存亲和性
 
@@ -1572,7 +1572,7 @@ class CacheAwareScheduler:
         api_format: str,
         global_model_id: str,
         ttl: int | None = None,
-    ):
+    ) -> Any:
         """
         记录缓存亲和性（供编排器调用）
 
@@ -1645,7 +1645,7 @@ _scheduler: CacheAwareScheduler | None = None
 
 
 async def get_cache_aware_scheduler(
-    redis_client=None,
+    redis_client: Any | None = None,
     priority_mode: str | None = None,
     scheduling_mode: str | None = None,
 ) -> CacheAwareScheduler:

src/services/cache/backend.py

@@ -10,6 +10,8 @@
 - 其他需要缓存的服务
 """
 
+from __future__ import annotations
+
 import asyncio
 import json
 import time
@@ -87,7 +89,7 @@ class LocalCache(BaseCacheBackend):
             self._cache.move_to_end(key)
             return self._cache[key]
 
-    async def set(self, key: str, value: Any, ttl: int = None) -> None:
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
         """设置缓存值（线程安全）"""
         async with self._lock:
             if ttl is None:
@@ -195,7 +197,7 @@ class RedisCache(BaseCacheBackend):
             logger.error(f"[RedisCache] 获取缓存失败: {key}, 错误: {e}")
             return None
 
-    async def set(self, key: str, value: Any, ttl: int = None) -> None:
+    async def set(self, key: str, value: Any, ttl: int | None = None) -> None:
         """设置缓存值"""
         if ttl is None:
             ttl = self._default_ttl

src/services/cache/invalidation.py

@@ -5,16 +5,19 @@
 """
 
 
+from __future__ import annotations
+
+from typing import Any
 from src.core.logger import logger
 
 
 class CacheInvalidationService:
     """缓存失效服务"""
 
-    def __init__(self):
+    def __init__(self) -> None:
         self._model_mappers = []
 
-    def register_model_mapper(self, model_mapper):
+    def register_model_mapper(self, model_mapper: Any) -> None:
         """注册 ModelMapper 实例"""
         if model_mapper not in self._model_mappers:
             self._model_mappers.append(model_mapper)
@@ -58,7 +61,7 @@ class CacheInvalidationService:
         except Exception as e:
             logger.error(f"[CacheInvalidation] 失效 models list 缓存失败: {e}")
 
-    def on_model_changed(self, provider_id: str, global_model_id: str):
+    def on_model_changed(self, provider_id: str, global_model_id: str) -> Any:
         """Model 变更时的缓存失效"""
         self._refresh_provider_cache(provider_id)
 
@@ -88,7 +91,7 @@ class CacheInvalidationService:
         for mapper in self._model_mappers:
             mapper.refresh_cache(provider_id)
 
-    def clear_all_caches(self):
+    def clear_all_caches(self) -> None:
         """清空所有缓存"""
         for mapper in self._model_mappers:
             mapper.clear_cache()

src/services/cache/provider_cache.py

@@ -6,6 +6,8 @@ Provider 缓存服务 - 减少 Provider 和 ProviderAPIKey 查询
 """
 
 
+from __future__ import annotations
+
 from sqlalchemy.orm import Session
 
 from src.config.constants import CacheTTL

src/services/cache/sync.py

@@ -9,6 +9,9 @@
 2. GlobalModel/Model 变更时，同步失效所有实例的缓存
 """
 
+from __future__ import annotations
+
+from typing import Any
 import asyncio
 import json
 
@@ -46,7 +49,7 @@ class CacheSyncService:
         self._handlers: dict[str, Callable] = {}
         self._running = False
 
-    async def start(self):
+    async def start(self) -> Any:
         """启动缓存同步服务（订阅 Redis 频道）"""
         if self._running:
             logger.warning("[CacheSync] 服务已在运行")
@@ -73,7 +76,7 @@ class CacheSyncService:
             logger.error(f"[CacheSync] 启动失败: {e}")
             raise
 
-    async def stop(self):
+    async def stop(self) -> Any:
         """停止缓存同步服务"""
         if not self._running:
             return
@@ -95,7 +98,7 @@ class CacheSyncService:
 
         logger.info("[CacheSync] 缓存同步服务已停止")
 
-    def register_handler(self, channel: str, handler: Callable):
+    def register_handler(self, channel: str, handler: Callable) -> None:
         """
         注册缓存失效处理器
 
@@ -106,7 +109,7 @@ class CacheSyncService:
         self._handlers[channel] = handler
         logger.debug(f"[CacheSync] 注册处理器: {channel}")
 
-    async def _listen(self):
+    async def _listen(self) -> None:
         """监听 Redis pub/sub 消息"""
         logger.info("[CacheSync] 开始监听缓存失效消息")
 
@@ -136,21 +139,21 @@ class CacheSyncService:
         except Exception as e:
             logger.error(f"[CacheSync] 监听失败: {e}")
 
-    async def publish_global_model_changed(self, model_name: str):
+    async def publish_global_model_changed(self, model_name: str) -> Any:
         """发布 GlobalModel 变更通知"""
         await self._publish(self.CHANNEL_GLOBAL_MODEL, {"model_name": model_name})
 
-    async def publish_model_changed(self, provider_id: str, global_model_id: str):
+    async def publish_model_changed(self, provider_id: str, global_model_id: str) -> Any:
         """发布 Model 变更通知"""
         await self._publish(
             self.CHANNEL_MODEL, {"provider_id": provider_id, "global_model_id": global_model_id}
         )
 
-    async def publish_clear_all(self):
+    async def publish_clear_all(self) -> Any:
         """发布清空所有缓存通知"""
         await self._publish(self.CHANNEL_CLEAR_ALL, {})
 
-    async def _publish(self, channel: str, data: dict):
+    async def _publish(self, channel: str, data: dict) -> None:
         """发布消息到 Redis 频道"""
         try:
             message = json.dumps(data)
@@ -164,7 +167,7 @@ class CacheSyncService:
 _cache_sync_service: CacheSyncService | None = None
 
 
-async def get_cache_sync_service(redis_client: aioredis.Redis = None) -> CacheSyncService | None:
+async def get_cache_sync_service(redis_client: aioredis.Redis | None = None) -> CacheSyncService | None:
     """
     获取缓存同步服务实例
 
@@ -191,7 +194,7 @@ async def get_cache_sync_service(redis_client: aioredis.Redis = None) -> CacheSy
     return _cache_sync_service
 
 
-async def close_cache_sync_service():
+async def close_cache_sync_service() -> None:
     """关闭缓存同步服务"""
     global _cache_sync_service
 

src/services/cache/user_cache.py

@@ -20,6 +20,9 @@
 """
 
 
+from __future__ import annotations
+
+from typing import Any
 from sqlalchemy.orm import Session
 
 from src.config.constants import CacheTTL
@@ -102,7 +105,7 @@ class UserCacheService:
         return user
 
     @staticmethod
-    async def invalidate_user_cache(user_id: str, email: str | None = None):
+    async def invalidate_user_cache(user_id: str, email: str | None = None) -> Any:
         """
         清除用户缓存