chore: 清理违反底座规则的死代码并修正接口文档编号

- 删除生产死代码 app/service/knowledge_tool_service.py 与
  app/infrastructure/milvus_knowledge_adapter.py:后者硬编码 Milvus 字段名,
  违反 AGENTS.md §E,且仅被前者引用;生产检索链路实际走
  knowledge_search_tool -> KnowledgeSearchService -> knowledge_schema 运行时探测。
- 删除上述两模块的单测,以及依赖 legacy 位置参数构造的
  tests/unit/service/test_knowledge_retrieval.py。
- app/service/knowledge_retrieval_service.py 整文件回退底座版本,
  移除 legacy 双构造与重复检索实现。
- docs/05-接口文档.md:客服画像候选改登记为 §8.5,恢复 §8.2 解析知识引用;
  既有 §8.1-§8.4 编号全部保持,修复此前出现两个 8.3 的问题。
- app/model/profile.py:current_customer_id 改为普通可空列映射,与
  alembic/baseline_generated.sql 及真实库一致;原 Computed 声明会让 ORM 把该列
  从 INSERT 中排除,与「必须显式写入」的实际 schema 不符。
- 新增 docs/客服Agent接入底座扩展说明_v1.md,供集成分支评审逐项确认。

验证:pytest tests/unit tests/contract -> 1275 passed, 2 skipped, 0 failed;
ruff check app tests tools alembic 通过;mypy app 通过(244 个源文件)。
This commit is contained in:
张胜宇
2026-09-12 11:15:24 +08:00
parent e85989b344
commit 9aaacc242f
9 changed files with 189 additions and 483 deletions
+9 -8
View File
@@ -4,15 +4,18 @@
这里显式标注,避免后续有人按直觉写入而踩坑:
1. `user_facts.id` 在库里**没有 auto_increment**,插入时必须由应用显式提供主键;
2. `profile_snapshots.current_customer_id` 是**生成列**(`IF(is_current=1, customer_id, NULL)`),
与唯一键 `uk_profile_snapshot_current` 共同保证「每个客户最多一条当前快照」。生成列由数据库
维护,因此这里只映射为只读计算列,写入时不会提供该字段。
2. `profile_snapshots.current_customer_id` **不是生成列**,而是普通可空列 + 唯一键
`uk_profile_snapshot_current`:当前版本必须由写入方**显式写入**客户 ID(历史版本写 NULL),
才能保证「每个客户最多一条当前快照」。因此这里按普通可空列映射,**不能**声明 `Computed`——
声明成生成列会让 SQLAlchemy 把它从 INSERT 中排除,反而永远写不进去。
(`docs/00` 第 783 行把它描述为「生成列」,与实际 DDL 及真实库不一致;
以 `alembic/baseline_generated.sql`、`tools/seed_profile_demo.py` 和真实库为准。)
"""
from datetime import datetime
from typing import Any
from sqlalchemy import CHAR, JSON, BigInteger, Boolean, Computed, DateTime, Float, String
from sqlalchemy import CHAR, JSON, BigInteger, Boolean, DateTime, Float, String
from sqlalchemy.orm import Mapped, mapped_column
from app.model.base import Base
@@ -59,7 +62,5 @@ class ProfileSnapshot(Base):
generated_at: Mapped[datetime | None] = mapped_column(DateTime)
created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
updated_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
# 生成列由数据库维护;映射为只读计算列,便于按当前快照查询,不参与 INSERT/UPDATE。
current_customer_id: Mapped[int | None] = mapped_column(
BigInteger, Computed("IF(is_current = 1, customer_id, NULL)")
)
# 普通可空列 + 唯一键,由写入方显式赋值(见模块 docstring 第 2 条),不是生成列。
current_customer_id: Mapped[int | None] = mapped_column(BigInteger)