张胜宇
9aaacc242f
- 删除生产死代码 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 个源文件）。
67 lines
3.6 KiB
Python
67 lines
3.6 KiB
Python
"""画像与用户事实的 ORM 映射。
|
||
|
||
只映射既有表结构，**不改变任何字段**（`AGENTS.md` 第 3/4 条）。两处与常见表不同的设计在
|
||
这里显式标注，避免后续有人按直觉写入而踩坑：
|
||
|
||
1. `user_facts.id` 在库里**没有 auto_increment**，插入时必须由应用显式提供主键；
|
||
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, DateTime, Float, String
|
||
from sqlalchemy.orm import Mapped, mapped_column
|
||
|
||
from app.model.base import Base
|
||
|
||
|
||
class UserFact(Base):
|
||
"""用户事实（user_facts）：由中期记忆提升而来的稳定事实，供画像组装读取。
|
||
|
||
表上**没有** (customer_id, fact_key) 唯一键（只有两个普通索引），因此"同一事实只保留一条"
|
||
必须由服务层用"先查后写"保证，不能依赖数据库约束。
|
||
"""
|
||
|
||
__tablename__ = "user_facts"
|
||
|
||
# 注意：库中该列无 auto_increment，主键由服务层显式赋值（单调递增）
|
||
id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
|
||
customer_id: Mapped[int] = mapped_column(BigInteger, nullable=False)
|
||
fact_key: Mapped[str] = mapped_column(String(128), nullable=False)
|
||
fact_value: Mapped[Any] = mapped_column(JSON, nullable=False)
|
||
source_portal: Mapped[str] = mapped_column(String(16), nullable=False)
|
||
source_episode_id: Mapped[int | None] = mapped_column(BigInteger)
|
||
confidence: Mapped[float] = mapped_column(Float, nullable=False, default=1.0)
|
||
is_critical: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
|
||
created_at: Mapped[datetime] = mapped_column(DateTime, nullable=False)
|
||
|
||
|
||
class ProfileSnapshot(Base):
|
||
"""画像快照（profile_snapshots）：画像的版本化留痕。
|
||
|
||
存在意义是回答"当时依据的是什么"——风控复盘与合规检查都需要它，所以画像变更
|
||
**只新增版本、不原地覆盖**。
|
||
"""
|
||
|
||
__tablename__ = "profile_snapshots"
|
||
|
||
id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
|
||
profile_uuid: Mapped[str | None] = mapped_column(CHAR(36), unique=True)
|
||
customer_id: Mapped[int] = mapped_column(BigInteger, nullable=False)
|
||
version: Mapped[int] = mapped_column(BigInteger, nullable=False)
|
||
snapshot: Mapped[Any] = mapped_column(JSON, nullable=False)
|
||
generation_basis: Mapped[Any | None] = mapped_column(JSON)
|
||
snapshot_hash: Mapped[str | None] = mapped_column(CHAR(64))
|
||
is_current: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
|
||
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)
|
||
# 普通可空列 + 唯一键，由写入方显式赋值（见模块 docstring 第 2 条），不是生成列。
|
||
current_customer_id: Mapped[int | None] = mapped_column(BigInteger)
|