chore: 修我文件里的 mypy 类型错误(8 处)

源自评审 §1.4「数字不可比」引发的核查,结论比预想更有价值:

**mypy 报错的主因不是代码质量,而是本机缺 SQLAlchemy 2.0 的类型信息。**
装上 `sqlalchemy2-stubs` 后 181 → 43(该类存根是 2.0 之前的旧包,会换一批新错:
`mapped_column`/`DeclarativeBase` 不存在),卸载后回到 184。**本机 mypy 数字不可作为
质量结论,双方也不可比。** 但那 184 里有 8 个是**我文件里的真实错误**,已修:

- `knowledge_retrieval_service`:返回类型 `Mapping` → `dict`(回表后要就地补写
  `score`/`intent`,而 `Mapping` 是只读协议);`ids` 显式标注并过滤 `None`;
  去掉 3 处已失效的 `type: ignore`(strict 下 unused-ignore 本身是错误)
- `knowledge_management`:服务工厂返回类型 `Any` → `KnowledgeManagementService`
  (`TYPE_CHECKING` 期导入,运行时仍惰性,不引入循环依赖),消掉 3 个 `no-any-return`

未动的:`model_gateway` 2 处 `dict-item`(`ModelEndpointConfig` 实际具备协议要求的
全部字段,属 SQLAlchemy `Mapped[T]` 在缺存根时的消解问题,不是真缺陷,不用 cast 掩盖)。
This commit is contained in:
qyqy
2026-09-11 19:13:43 +08:00
parent 7677aeaee1
commit 636dcbbe7e
3 changed files with 32 additions and 9 deletions
+9 -2
View File
@@ -27,7 +27,7 @@ F1.2 点名了这三个端点。既有 `app/api/controllers/knowledge.py` 只有
`filename` + `content: bytes`,与传输形状无关)。
"""
from typing import Any
from typing import TYPE_CHECKING, Any
from fastapi import APIRouter, Depends, Path, Query
from pydantic import BaseModel, ConfigDict, Field
@@ -37,6 +37,13 @@ from app.api.dependencies.rate_limit import enforce_rate_limit
from app.core.contracts import RequestContext
from app.service.knowledge_management_service import decode_content
if TYPE_CHECKING: # pragma: no cover - 仅类型检查期需要
# 仅在类型检查期导入 Service,用于给工厂函数标注真实返回类型。
# 运行时仍然惰性导入(见 `knowledge_management_service()`):`bootstrap` 会间接导入本模块,
# 模块级导入 Service 会形成循环依赖。标注返回类型的目的不是好看——`-> Any` 会让
# 三个端点的 `-> dict[str, Any]` 触发 `no-any-return`,把真实签名检查整个关掉。
from app.service.knowledge_management_service import KnowledgeManagementService
router = APIRouter(prefix="/api/v1/knowledge", tags=["knowledge-management"],
dependencies=[Depends(enforce_rate_limit)])
@@ -57,7 +64,7 @@ class KnowledgeUploadPayload(BaseModel):
description="faq / product / policy 之一")
def knowledge_management_service() -> Any:
def knowledge_management_service() -> "KnowledgeManagementService":
"""服务工厂:模块级函数是唯一的替换点(接口测试注入替身,不连库、不连 Milvus)。
为什么放在 Controller 里而不是 Service 的模块顶层:组合根必须在进程启动/首次调用时