wangjianlong_0626
57f56bbcbe
## 1. 独立缺陷：`profile_snapshots` 被两个 ORM 类重复映射
排查 `memory_sync_outbox` 中 `target_store='neo4j'` 那行 `last_error='InvalidRequestError'`
时发现，根因不在图库，而在模型层：
- `app/model/profile.py` → `ProfileSnapshot` 映射 `profile_snapshots`
- `app/model/risk_questionnaire.py` → **另一个** `ProfileSnapshot` 也映射 `profile_snapshots`
SQLAlchemy 不允许两个类映射同一张表。实测：
| 场景 | 结果 |
|---|---|
| 单独导入 `app.main` / `app.worker.runtime` | 正常 |
| 单独导入 `profile_assembly_service` / `risk_questionnaire_service` | 正常 |
| **两者同时导入** | `InvalidRequestError: Table 'profile_snapshots' is already defined` |
Worker 在同一进程里既要处理 `profile.rebuild_requested`（走 `app.model.profile`），
又要处理投顾风险问卷（走 `risk_questionnaire.py`）——所以这是**会打挂 Worker 的缺陷**，
不是理论风险。
修法：`app/model/risk_questionnaire.py` 不再重复定义，改为从 `app.model.profile`
转出（re-export），既有 4 处 `from app.model.risk_questionnaire import ProfileSnapshot`
无需改动。原定义多映射的 `current_customer_id` 经全仓核查无人使用，故不保留
（`app.model.profile` 明确注明该列由数据库维护、故意不映射）。
## 2. 消费端兜底 `memory_sources`
`memory_sources` 是本线新增的投影入参，而投顾线两处生产者的 payload
（`{customer_id, profile_uuid, version, profile}`）没有这个键，原样会导致它们每次画像
变更都 `memory_sources is invalid` → 重试至死信。
新增 `WorkerRuntime._with_memory_sources()`：**键缺失或为 None** 时回退查询该客户
`memory_unit` 中 `status='active'` 的记忆，并记 warning（使"谁没提供"保持可见）。
语义成立：长期记忆是**客户级**而非画像版本级的，每条记忆自带 `version`，
适配器按 `memory_uuid + version` 幂等，故"用的是哪一版"仍确定。
**兜底不掩盖真错误**：键**存在但格式不对**时**不兜底**，原样交给适配器失败关闭。
实现上用键存在性判断而非 `isinstance`——后者会把"缺失"与"格式错"混为一谈，
那是初版实现里的一个真 bug，被新测试抓出后修正。
## 3. 补上此前欠缺的消费端全路径验证
此前"整合验证"是直接调适配器，跳过了 outbox 的领取→分派→状态更新。
- **失败分支**（Milvus 断开时实测）：行被领取、按 target_store 分派、异常被捕获、
`status`/`retry_count`/`last_error`/`next_retry_at` 正确落库。
- **成功分支**（注入替身向量客户端）：outbox 行 → `processed`、`processed_at` 已写；
不可投影的 `constraint:` 被跳过（只写 1 行）；维度 1024；字符串客户号转 int；
**手机号脱敏生效**（`稳健型投资者，手机号 [手机号已隐藏] 请勿外泄`）。
- **兜底实证**：历史行 `id=5`（payload 无 `memory_sources`）经兜底后成功投递为 `processed`。
- **修复实证**：`id=6` 的 `last_error` 从 `InvalidRequestError` 变为
`RecoverableAgentError`（图库不可用）——证明重复定义缺陷确已消除，剩下的是环境问题。
## 4. 测试与验证
- 新增 `tests/unit/worker/test_runtime_profile_projection.py`（5 用例：已提供原样透传、
缺失兜底、空记忆给空列表而非删键、无客户号不兜底、格式错不兜底）
- 全量：`2 failed, 1312 passed, 2 skipped`（2 个失败为既有环境项，非本次引入）
- mypy：`Success: no issues found in 227 source files`
- 表结构审计：89 张业务表无缺失/意外（未改动任何表结构）
- 文档守卫：41 份文档无编号冲突
## 5. 文档
`docs/32-记忆投影链路实现说明.md` 增补 §6.1（兜底）、§6.2（重复定义缺陷）、
§7.1（消费端全路径验证）并更新验证表与文件清单；
`AGENTS.md` 新增"一张表只能有一个 ORM 类"易错点、校正测试基线数字。
## 未做
未改 `docs/00` 基线、未动数据库迁移、未改投顾线生产者代码、未启动常驻 Worker。
遗留：投顾线两处生产者的 payload 仍缺 `memory_sources`（已有兜底，不再死信，
但根治应由投顾线确认）；Milvus/Neo4j 容器本轮不可用（Docker Desktop 崩溃），
`id=6` 停在 failed 属环境不可用、非代码缺陷。
143 lines
12 KiB
Markdown
143 lines
12 KiB
Markdown
# 项目级开发约束
|
||
|
||
以下规则对人工开发者和编码 Agent 均为强制约束：
|
||
|
||
1. 数据库以 `docs/00-新数据库基线设计.md` 为不可变业务基线。
|
||
2. 允许创建新表，允许在已有表中增加新字段。
|
||
3. 禁止重命名或删除已有表。
|
||
4. 禁止重命名、删除、复用已有字段，禁止改变已有字段的类型、可空性和既有业务含义。
|
||
5. 历史结构无法满足新需求时，使用新增字段、新表、兼容视图或应用双读解决。
|
||
6. 架构固定使用 MVC+S；Agent 属于 Service 层。
|
||
7. 业务 Agent 必须继承公共 `BaseAgent` 并由 `AgentFactory` 创建，不得绕过公共鉴权、记忆、模型路由、工具、合规、审计和事件流程。
|
||
8. 当前系统业务功能只针对场内基金模拟交易；场外基金运营流程独立，不得写入场内交易表。
|
||
|
||
修改数据库文档或迁移前，必须对比基线并证明没有改变任何已有表名和已有字段定义。
|
||
|
||
---
|
||
|
||
## 📖 接手先读（按此顺序，只读这些就够）
|
||
|
||
> **⭐ 第 0 步先读这个**：`docs/superpowers/handoff/2026-09-11-交接文档-客服Agent与RAG收尾.md`
|
||
> —— 客服 Agent + RAG 这条线的交接文档（**含合并完成后的第二次更新**）：环境口径、交付内容与
|
||
> **可复现验证证据**、合并后修掉的 3 个真机故障、**已知问题清单（逐条标注当前状态）**、Git/PR 状态。
|
||
> 当前工作分支是 **`NL_develop`**（个人分支 → PR 合回 `qyqy_develop`），**不要再用 `6516ccb`**。
|
||
> 它是对"当前状态"最准确的一份，读完它再读下面这些。
|
||
>
|
||
> **⚠️ 文档现状（2026-09-11 第二次修订）**：本文件原先声明"已删除 5 份编号文档"，
|
||
> 那条**已作废** —— 经评审，`docs/04`/`06`/`10`/`13`/`99` **全部保留**（架构师明确要求保留：
|
||
> 删除收益为零，而保留成本同样为零）。它们的内容**未被核对过、可能过期**，
|
||
> 因此**列在下面的 D 类"不要用来判断当前进度"**里，只作历史参考。
|
||
> 被删除的只有 10 份**过程产物**，理由与清单见 `docs/superpowers/ARCHIVE-2026-09-11-文档清理归档.md`。
|
||
|
||
### A. 核心 7 份（无论接手哪条线都必读）
|
||
|
||
| 序 | 文档 | 承载的唯一权威内容 |
|
||
|---|---|---|
|
||
| 1 | `docs/00-新数据库基线设计.md` | **不可变业务基线**：表/字段业务语义的唯一来源 |
|
||
| 2 | `docs/05-接口文档.md` | **接口唯一权威**：信封/错误码/幂等/SSE、§8.3 知识库管理三端点、§8.4 四个只读工具索引与两段式白名单 |
|
||
| 3 | `docs/01-通用Agent平台开发设计.md` | MVC+S 分层约束、`BaseAgent` 执行骨架、`AgentFactory` |
|
||
| 4 | `docs/02-数据库建表设计.md` | 51 张业务表总览 + DDL + §8 幂等与 Outbox 语义 |
|
||
| 5 | `docs/03-平台端到端流程文档.md` | 一次请求从受理→Worker→审计→事件的全链路与降级矩阵 |
|
||
| 6 | `docs/08-数据库结构审计基线.md` | 三个审计工具 + `migration_state_check` 的职责；"证明未改基线"的证据出处 |
|
||
| 7 | `docs/07-测试问题修复记录.md` | **无替代**：P0-1/2/3 鉴权与 Worker 租约闭环、P1-1~P1-5（含 `api_request_receipt` 事务幂等） |
|
||
|
||
### B. 按角色补充
|
||
|
||
| 你接手的是 | 再读这些 |
|
||
|---|---|
|
||
| **客服 Agent + RAG 这条线** | `docs/14`（接入入口）→ `docs/18`（RAG 三集合路由方案）→ `docs/19`（可运行示例）→ `docs/09`（底座用法与四工具） |
|
||
| **整个底座** | 补 `docs/20`（第一版→当前的破坏性改动 + §5 四条尚未修复的偏差 + "跑验收前先停常驻 Worker"） |
|
||
| **只改某个业务域** | `docs/00` → `docs/05` → `docs/02` → `docs/14` → `docs/19`；行情加 `docs/12`，前端/联调加 `docs/17` |
|
||
| **看"现在做到哪了"** | `docs/验收与审计/phase1-acceptance-report.md`（Phase 1 七条验收标准的逐条可复现证据）+ 同目录 `phase1-acceptance-criteria.md`（老师验收标准原文摘录） |
|
||
|
||
> 注：完整的过程台账（`progress.md`、各 Task 报告、审计报告）在 **`.superpowers/sdd/2026-09-10-客服Agent与RAG-qyqy版/`**，
|
||
> 但该目录**被 `.gitignore` 忽略**（属工作区过程产物）—— 因此**结论性文档已复制到 `docs/验收与审计/`** 以保证 git 可见。
|
||
> 若要查过程细节再去看 `.superpowers/`；日常接手**只需读本文档列出的这些**。
|
||
|
||
### C. 同主题的重复文档（读一份即可，避免信息冲突）
|
||
|
||
| 主题 | 唯一权威 | 重复品（仅历史参考） |
|
||
|---|---|---|
|
||
| Agent 组员接入 | **`docs/14`** | `docs/11`（旧版说明书）、`docs/15`（详细手册）、`docs/16`（入门易懂版）—— 三份已各自在开头标注"以 `14` 为准" |
|
||
| 接口说明 | **`docs/05`** | `docs/17`（易懂版，自述"不替代 05"） |
|
||
|
||
### D. ⚠️ 不要用来判断"当前进度"
|
||
|
||
| 文件 | 为什么 |
|
||
|---|---|
|
||
| `TODO.md` | **自 2026-09-09 起未随 Phase 1 更新**：5 处"49 张表"（实为 51 张业务表）、T8.1 客服 Agent 整节未勾选但**已交付**、多处标"进行中"其实已完成。**当前进度一律以 `phase1-acceptance-report.md` 为准。** |
|
||
| `docs/04` / `06` / `10` / `13` / `99` | 内容**未核对过、可能过期**（自相矛盾 / 结论失效 / 清单不全）。经 2026-09-11 评审**保留**（不再删除），仅作历史参考。**不要用它们判断现状** |
|
||
|
||
### E. 环境与命令口径（易错点）
|
||
|
||
- 解释器：本机用 **`.\.venv\Scripts\python.exe`**；架构师环境用 `D:\conda\envs\jr_py313\python.exe`。
|
||
两者等价，**各用本机可用的那个**（`.venv` 被 `.gitignore` 忽略、不进仓库，不存在"需要统一"的问题）。
|
||
- ⚠️ **Windows 控制台跑测试请加 `-X utf8`，否则中文输出是乱码**：
|
||
|
||
```powershell
|
||
.\.venv\Scripts\python.exe -X utf8 -m pytest tests -q
|
||
```
|
||
|
||
原因：本机控制台是代码页 **936（GBK）**，Python 的 `sys.stdout.encoding` 随之为 `gbk`，
|
||
而终端按 UTF-8 解码 ⇒ 中文（断言消息、`docs/` 中文文件名、测试内 `print`）全部乱码。
|
||
**乱码只影响"显示"，不影响测试结果**（`passed`/`failed` 计数是英文，照常可信）。
|
||
|
||
为什么必须用 `-X utf8` 而不是别的办法：
|
||
- `chcp 65001` **单独无效**（Python 仍以 GBK 输出，终端按 UTF-8 解码，反而更乱）；
|
||
- 在 `tests/conftest.py` 里 `sys.stdout.reconfigure(encoding="utf-8")` **只能修测试内部的 `print`**，
|
||
**修不了 pytest 自己的输出**（失败摘要、短测试摘要）—— pytest 的终端写入器在启动时就绑定了编码，
|
||
早于 conftest 被加载。**实测两组对照：摘要照样乱码。**
|
||
- `-X utf8` 在解释器启动时生效，早于 pytest 的一切，且只影响当次进程、无副作用。
|
||
- 等价替代：环境变量 `PYTHONUTF8=1` 或 `PYTHONIOENCODING=utf-8`（PyCharm 用户可写进 Run Configuration）。
|
||
同一原因，**跑 `tools/*.py` 等脚本时也要加 `-X utf8`**（例如 `python -X utf8 tools\check_authoritative_docs.py`）。
|
||
- 数据库现为 **69 张表**（含 `alembic_version`）＝ **68 张业务表** = **场内 51 + 场外/推广 17**。
|
||
后 17 张（`offsite_*` / `promotion_*`）**不进 `docs/00` 基线**（规则 8：场外基金运营流程独立），
|
||
逐表登记见 `docs/28-场外与推广域数据表登记.md`。核验命令：`python tools/audit_schema.py`。
|
||
- 已注册业务 Agent：`FundQueryDemoAgent`、`CustomerServiceAgent`、`RiskAgent`、`PlatformProbeAgent`（见 `app/service/agent/bootstrap.py`）。
|
||
- 已注册公共只读工具：`search_knowledge`（客服知识检索）、`check_suitability`、`query_customer_profile`（画像）、`query_fund_quote`；
|
||
**工具可用范围 = 代码上限 ∩ 当前 active `config_release` 的发布白名单**，缺发布配置则失败关闭。
|
||
- ⚠️ **`config_release` 是环境数据，不随代码合并**：本机 active 版本 id 与架构师环境**不同**
|
||
（本机是我方发布的客服白名单；他那边还有风控的 9 条白名单）。**"白名单已发布"必须带环境限定**，换环境要重发。
|
||
发布脚本 `tools/publish_customer_service_config.py`（**同 key 的继承项必须被本次定义覆盖**，否则旧值会被子集校验 422 拦下整次发布）。
|
||
- ⚠️ **Milvus 集合 schema 也因环境而异**：本机是 `knowledge_id`/`snippet`（无 `visibility`），
|
||
架构师环境是 `doc_id`/`content`/`visibility`/`chapter`…。**检索层已改为运行时探测字段名**
|
||
（`app/core/knowledge_schema.py`）——**不要在任何地方硬编码字段名**，那会把另一套环境打挂。
|
||
- ⚠️ **Docker Desktop 不会常驻**：它没运行时 Milvus 不可用（`docker` CLI 报连不上守护进程）。
|
||
跑真机验证前先确认 Docker Desktop 在运行。
|
||
- ⚠️ **`memory_sync_outbox` 的取值必须是小写英文**（`milvus`/`neo4j`、`upsert`、
|
||
`pending`/`failed`/`processed`/`dead`）。`docs/00` §6.4.6 那一栏曾写作大写
|
||
`MILVUS`/`NEO4J`、`UPSERT` + 中文 `待处理`，**与全仓实现从未对齐，照它写会静默失效**：
|
||
消费端按 `handlers.get(target_store)` 分派、且只领 `status in {"pending","failed"}`，
|
||
大写 + 中文两个条件都不满足 ⇒ **事件任何消费者都领不到、永久滞留且不报错**
|
||
（唯一键 `(event_uuid, target_store)` 对大小写无约束，MySQL 也不报错）。
|
||
取值口径以**主干既有读取方**为准（`projection_reconciliation_service.py`、
|
||
`graph_projection_worker.py`），不是文档。详见 `docs/32-记忆投影链路实现说明.md`。
|
||
- ⚠️ **一张表只能有一个 ORM 类**：`app/model/` 下曾出现**两个类都映射 `profile_snapshots`**
|
||
（`profile.py` 与 `risk_questionnaire.py`），各自单独导入都没事，**同时导入即抛**
|
||
`InvalidRequestError: Table 'profile_snapshots' is already defined for this MetaData instance`
|
||
—— Worker 既要重建画像又要处理投顾问卷，因此**真的被打挂过**（库里 `memory_sync_outbox`
|
||
留下 `last_error='InvalidRequestError'` 的行）。2026-09-12 已修为 re-export，见 `docs/32` §6.2。
|
||
**新增模型前先搜一遍 `__tablename__` 有没有被占用。**
|
||
- 测试基线：`2 failed, 1312 passed, 2 skipped`（2026-09-12 记忆投影链路落地后实测；
|
||
此前为 `3 failed, 1219 passed`——第 3 个失败
|
||
`tests/unit/repository/test_fund_readonly_contract.py` 已由投顾线合入主干时修复，**不要再当既有缺陷引用**）。
|
||
剩下 2 个失败**都不是代码缺陷**，接手时不要"修"它们：
|
||
`tests/unit/service/test_offsite_document_recognition_adapter.py` 的 2 个用例 —— **环境相关**：
|
||
它们断言请求体里是中文原文，而 httpx 会把中文序列化成 `\uXXXX`，字节序列自然不匹配。
|
||
功能无影响；若要修，正确做法是断言 `json.loads(body)` 后的字段值（字节级断言不该用来测 JSON）。
|
||
- **mypy：`mypy app` → `Success: no issues found in 227 source files`（0 错）。**
|
||
⚠️ 曾在本机报 184 个错，**已查明是环境版本旧**，与代码质量无关 —— 复现矩阵：
|
||
|
||
| SQLAlchemy | mypy | 报错数 |
|
||
|---|---|---|
|
||
| 2.0.34（本机旧） | 1.14.1 | **173** |
|
||
| 2.0.34 | 1.20.2 | 173 |
|
||
| 2.0.52 | 1.14.1 | **6** |
|
||
| 2.0.52 | 1.20.2 | **0**（当前） |
|
||
|
||
⇒ 主因是 **SQLAlchemy 的补丁版本**（旧补丁版类型标注不完整，`BIGINT`/`DATETIME` 被判成未类型化
|
||
函数，`app/model/*.py` 每个列定义报一条）。**不要装 `sqlalchemy2-stubs`** —— 那是给
|
||
SQLAlchemy **1.4** 用的，装上会按 1.4 API 核对 2.0 代码、换一批新错。
|
||
`pyproject.toml` 的 `sqlalchemy>=2.0,<3` 允许范围内补丁版差异会造成量级差异；
|
||
若门禁数字要求稳定，需把 SQLAlchemy 钉到具体补丁版（属公共约定，改前先问）。
|