fix(profile): 修 profile_snapshots 重复定义（会打挂 Worker）；消费端兜底 memory_sources
## 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 属环境不可用、非代码缺陷。
This commit is contained in:
+97
-17
@@ -167,6 +167,51 @@
|
||||
向量化复用与知识向量同一套已批准端点解析（`agent_type="memory_recall"`,
|
||||
`task_type="embedding"`）。
|
||||
|
||||
### 6.1 `memory_sources` 缺失时的兜底（`_with_memory_sources`）
|
||||
|
||||
`memory_sources` 是本线新增的投影入参，而**投顾线两处生产者**
|
||||
（`profile_governance_service` / `risk_questionnaire_service`）发的 payload 是
|
||||
`{customer_id, profile_uuid, version, profile}`，**没有**这个键。若不处理，它们每次画像
|
||||
变更都会因 `memory_sources is invalid` 失败重试直至死信。
|
||||
|
||||
消费端因此做了兜底：**键缺失或为 `None`** 时，回退为查询该客户 `memory_unit` 中
|
||||
`status='active'` 的记忆，并**记一条 warning**（使"谁没提供"保持可见）。
|
||||
|
||||
为什么允许兜底：缺失表示生产者不知道要提供，属契约演进期的正常情况，且**语义成立**
|
||||
——长期记忆是**客户级**的、不是画像版本级的，每条记忆自带 `version`，适配器按
|
||||
`memory_uuid + version` 幂等，"用的是哪一版"仍然确定。
|
||||
|
||||
**兜底不掩盖真错误**（有测试守着）：键**存在但格式不对**（例如是字符串）时**不兜底**，
|
||||
原样放行交给适配器失败关闭。实现上用**键存在性**判断而不是 `isinstance`——后者会把
|
||||
"缺失"与"格式错"混为一谈，那正是本模块初版实现里的一个真 bug，被测试抓出来后修正。
|
||||
|
||||
---
|
||||
|
||||
## 6.2 顺带修掉的独立缺陷：`profile_snapshots` 被重复定义
|
||||
|
||||
**发现路径**：验证 `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` 明确注明该列由数据库维护、故意不映射）。
|
||||
|
||||
---
|
||||
|
||||
## 7. 真机验证证据（2026-09-12）
|
||||
@@ -178,8 +223,9 @@
|
||||
| 真实写入 + 回读 | 2 条可投影键写入成功并可回读（内容/版本正确） |
|
||||
| 不可投影键 | `constraint:liquidity` **未写入**（跳过生效，未毒死整批） |
|
||||
| 测试数据清理 | 已按 `customer_id=999999` 删除，集合残留 **0** 条 |
|
||||
| 单元测试 | 新增 17 个（适配器 10 + worker 5 + 生产端 2），全过 |
|
||||
| 全量回归 | `2 failed, 1307 passed, 2 skipped` —— 与基线一致，**无新增失败** |
|
||||
| **消费端全路径**（补验） | 见下方 7.1 |
|
||||
| 单元测试 | 新增 **22** 个（适配器 10 + worker 5 + 生产端 2 + 消费端兜底 5），全过 |
|
||||
| 全量回归 | `2 failed, 1312 passed, 2 skipped` —— 与基线一致，**无新增失败** |
|
||||
| mypy | `Success: no issues found in 227 source files` |
|
||||
|
||||
> 全量的 2 个失败是既有环境相关项（`test_offsite_document_recognition_adapter.py`
|
||||
@@ -188,24 +234,54 @@
|
||||
> 真机注意：Milvus 写入后**短时间内可能查不到**（索引尚未可见），
|
||||
> 验证脚本按重试处理；同理删除后立即查询可能仍返回旧行，需重查确认。
|
||||
|
||||
### 7.1 消费端全路径验证（2026-09-12 补做）
|
||||
|
||||
此前"整合验证"是**直接调适配器**，跳过了 outbox 的领取→分派→状态更新。
|
||||
后补做了两轮，覆盖失败分支与成功分支：
|
||||
|
||||
**失败分支**（Milvus 断开时实测）：
|
||||
|
||||
| id | `last_error` | 说明 |
|
||||
|---|---|---|
|
||||
| 5 | `ValueError` | payload 缺 `memory_sources`（兜底上线前的旧行） |
|
||||
| 6 | `InvalidRequestError` | 模型重复定义缺陷（见 §6.2），**修复后此错误消失** |
|
||||
| 9 | `RecoverableAgentError` | Milvus 不可达——如实失败，不伪造成功 |
|
||||
|
||||
这证明全路径都工作：行被领取 ✓、按 `target_store` 分派 handler ✓、
|
||||
handler 异常被捕获 ✓、`status`/`retry_count`/`last_error`/`next_retry_at` 正确落库 ✓。
|
||||
|
||||
**成功分支**（注入替身向量客户端，不依赖真实 Milvus）：
|
||||
|
||||
- outbox 行 → `status=processed`、`processed_at` 已写、`last_error` 清空 ✓
|
||||
- 不可投影的 `constraint:liquidity` **被跳过**（只写 1 行而非 2 行）✓
|
||||
- 向量维度 1024 ✓；字符串客户号 `"999996"` → int ✓
|
||||
- **手机号脱敏生效**：`稳健型投资者，手机号 [手机号已隐藏] 请勿外泄` ✓
|
||||
|
||||
**兜底的实证**：历史行 `id=5`（payload 无 `memory_sources`）经兜底回退查询后
|
||||
成功投递为 `processed`，日志留
|
||||
`profile projection payload has no memory_sources (customer_id=9102); fell back to 0 active memories`。
|
||||
|
||||
> 补验时的环境限制：Docker Desktop 中途崩溃（`milvus-standalone` 内嵌 etcd panic、
|
||||
> Neo4j `Exited(1)`），因此 `id=6`（neo4j 分支）停在 `failed`/`RecoverableAgentError`。
|
||||
> **那是环境不可用，不是代码缺陷**——图库不可用时如实失败、不伪造成功正是设计口径。
|
||||
|
||||
---
|
||||
|
||||
## 8. 尚未完成 / 依赖他人
|
||||
|
||||
1. **常驻 Worker 未运行**：核对时数据库里 `memory_sync_outbox` 2 行、
|
||||
`domain_event_outbox` 积压
|
||||
（`agent.run_requested` 428、`profile.rebuild_requested` 216、
|
||||
`agent.run_completed` 61、`memory.extraction_requested` 58）。
|
||||
**`memory_unit` 与 `user_facts` 目前都是 0 行** —— 代码链路是通的，
|
||||
但没有 Worker 在跑，所以记忆永远不会被抽取出来。起
|
||||
`python -m app.worker --once`（或常驻）即会开始消费。
|
||||
2. **投顾线两处生产者的取值**：`profile_governance_service.py` 与
|
||||
`risk_questionnaire_service.py` 已写小写 `milvus`/`neo4j` + `pending`（与本文口径一致），
|
||||
但它们的 `payload` 是 `{customer_id, profile_uuid, version, profile}`，
|
||||
**没有 `memory_sources`** → 投影时会因 `memory_sources is invalid` 失败重试至死信。
|
||||
需投顾线补 `memory_sources` 或明确这两个来源是否也要投影长期记忆。
|
||||
（属架构师线的改动，本线未动。）
|
||||
3. `docs/00` §6.4.6 的取值栏与实现不一致：按评审要求**未改基线文档**，
|
||||
1. **常驻 Worker 未运行**：`memory_unit`、`user_facts`、`episodes` 目前都是 **0 行**。
|
||||
代码链路是通的（§7.1 已用真实 outbox 行验证消费端），但没有 Worker 在跑，
|
||||
所以记忆永远不会被抽取出来。积压量（2026-09-12 实测）：
|
||||
`agent.run_requested` **431**、`profile.rebuild_requested` **220**、
|
||||
`agent.run_completed` **61**、`memory.extraction_requested` **58**。
|
||||
起 `python -X utf8 -m app.worker --once`（或常驻）即开始消费。
|
||||
⚠️ 会派发真实 agent 任务、产生模型调用费用，故未擅自启动。
|
||||
2. **投顾线两处生产者的 `memory_sources`**：其 payload 仍**没有**这个键。
|
||||
本线已在消费端加了兜底（§6.1），因此**不再会死信**；但根治仍应由投顾线补上
|
||||
（或明确这两个来源是否也要投影长期记忆）。属架构师线，本线未改其生产者代码。
|
||||
3. **`profile_snapshots` 重复定义缺陷**（§6.2）：本线已修，但它源自投顾线的模型文件，
|
||||
需让架构师知晓，以免在别处再引入同名定义。
|
||||
4. `docs/00` §6.4.6 的取值栏与实现不一致：按评审要求**未改基线文档**，
|
||||
实际口径以本文第 2 节为准。
|
||||
|
||||
---
|
||||
@@ -218,12 +294,16 @@
|
||||
- `app/infrastructure/milvus_profile_vector_client.py`
|
||||
- `app/worker/memory_sync_outbox_worker.py`（移植）
|
||||
- `tools/setup_milvus_profile_collection.py`
|
||||
- `tools/normalize_memory_sync_outbox.py`（历史取值订正，默认 dry-run、幂等）
|
||||
- `tests/unit/infrastructure/test_milvus_profile_projection.py`
|
||||
- `tests/unit/worker/test_memory_sync_outbox_worker.py`
|
||||
- `tests/unit/worker/test_runtime_profile_projection.py`（消费端兜底 5 用例）
|
||||
|
||||
**修改**
|
||||
- `app/service/profile_generation_service.py`（取值改小写、payload 加 `memory_sources` 与 `profile_version`）
|
||||
- `app/repository/profile_repository.py`（`active_memories()`）
|
||||
- `app/service/agent/bootstrap.py`（`get_milvus_profile_vector_client()`）
|
||||
- `app/worker/runtime.py`（`consume_profile_projections()` + `run_once` 接线）
|
||||
- `app/worker/runtime.py`（`consume_profile_projections()`、`_with_memory_sources()` 兜底、`run_once` 接线）
|
||||
- `app/model/risk_questionnaire.py`（**修重复定义**：改为 re-export `app.model.profile` 的 `ProfileSnapshot`，见 §6.2）
|
||||
- `tests/unit/service/test_profile_generation_service.py`（+2 用例、断言改引用常量）
|
||||
- `AGENTS.md`（新增 `memory_sync_outbox` 取值口径与 Windows 中文输出两条易错点；校正测试基线/mypy 数字）
|
||||
|
||||
Reference in New Issue
Block a user