fix(memory-projection): 订正 outbox 取值口径并接通画像投影链路

背景:memory_sync_outbox 这条链此前**完全没有消费者**,且生产端照 docs/00 §6.4.6
写成大写 MILVUS/NEO4J + 中文「待处理」,而消费端按 target_store 的**值**分派 handler、
且只领 status in {pending, failed} —— 两个条件都不满足,事件任何消费者都领不到、
永久滞留且不报错(唯一键 (event_uuid, target_store) 对大小写无约束,MySQL 也不报错)。
根因是代码与测试都硬编码字面量,所以测试跟着一起错、谁也没拦住。

订正
- profile_generation_service:取值改为全仓一致的小写(milvus/neo4j/upsert/pending)
- 测试改为引用常量并断言消费端契约,不再硬编码(硬编码是本次跑偏的直接原因)
- 新增契约回归测试:断言大写值分派不到 handler、会进死信,谁改回大写立刻红
- 新增 tools/normalize_memory_sync_outbox.py:订正历史脏行(默认 dry-run、幂等)

接通投影链路(此前零消费者)
- 新增 Milvus 集合 user_long_term_memory_v1 及建集合工具(幂等、不覆盖已有集合)
- 新增 MilvusProfileProjection / MilvusProfileVectorClient,并修掉移植带来的两处必炸点:
  customer_id 由「必须 int」放宽为接受数字字符串(本仓所有生产者都写 str,
  不放宽则每个事件必然失败);不可投影的 memory_key 由「整批 raise」改为跳过留痕
  (否则一条 constraint: 记忆毒死该客户整批,而受控词表 13 个键里有 7 个不满足前缀)
- 新增 MemorySyncOutboxWorker(领取/指数退避/死信骨架保留原样)并接入 WorkerRuntime
- milvus → 向量投影;neo4j → 复用主干 ProfileGraphProjectionService(方案 A,
  不引入第二套投影,避免同一事实在图中两种说法、违反主干既有的只投影已确认事实的不变式)
- 生产端从 memory_unit(status=active) 组装 memory_sources,随事件带上确定快照
- 前置移植 conversation_privacy:写外部存储前脱敏手机号/证件号/银行卡等

验证
- 新增 17 个单测;全量 2 failed, 1307 passed, 2 skipped
  (2 个失败为既有环境项:断言请求体中文原文而 httpx 序列化成 \uXXXX,非本次引入)
- mypy app → 0 错(227 文件);audit_schema → 89 张业务表无缺失/意外,未改动表结构
- 真机:真实 embedding(1024 维) + 真实 Milvus 写入并回读通过
- 整合链路(测试记忆 → 生产端组装 → outbox → 消费端投递 → Milvus 回读)通过,
  且 MySQL 已回滚、Milvus 无残留

文档
- 新增 docs/32-记忆投影链路实现说明.md:真实口径、根因、契约与验证证据(供接手)
- AGENTS.md:新增该易错点;新增 Windows 中文输出乱码的正确命令(-X utf8);
  校正测试基线与 mypy 文件数

未做:未改 docs/00 基线、未动数据库迁移、未改投顾线代码、未启动常驻 Worker。
遗留:投顾线两处生产者的 payload 缺 memory_sources,会被消费至死信,待架构师确认是否投影。
This commit is contained in:
2026-09-12 10:45:40 +08:00
parent c82e9890e4
commit 8a0cbab636
15 changed files with 1477 additions and 12 deletions
+32 -5
View File
@@ -72,6 +72,24 @@
- 解释器:本机用 **`.\.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`。
@@ -86,13 +104,22 @@
(`app/core/knowledge_schema.py`)——**不要在任何地方硬编码字段名**,那会把另一套环境打挂。
- ⚠️ **Docker Desktop 不会常驻**:它没运行时 Milvus 不可用(`docker` CLI 报连不上守护进程)。
跑真机验证前先确认 Docker Desktop 在运行。
- 测试基线:`3 failed, 1219 passed, 2 skipped`(2026-09-11 合并主干后实测)。
三个失败**都不是代码缺陷**,接手时不要"修"它们:
① `tests/unit/repository/test_fund_readonly_contract.py`(**底座既有缺陷,不要修也不要报**);
② ③ `tests/unit/service/test_offsite_document_recognition_adapter.py` 的 2 个用例 —— **环境相关**:
- ⚠️ **`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`。
- 测试基线:`2 failed, 1307 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 180 source files`(0 错)。**
- **mypy:`mypy app` → `Success: no issues found in 227 source files`(0 错)。**
⚠️ 曾在本机报 184 个错,**已查明是环境版本旧**,与代码质量无关 —— 复现矩阵:
| SQLAlchemy | mypy | 报错数 |