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，会被消费至死信，待架构师确认是否投影。

docs/32-记忆投影链路实现说明.md

@@ -0,0 +1,229 @@
+# 记忆投影链路（Outbox → Milvus 长期记忆 / Neo4j）实现说明
+
+**适用分支**：`NL_develop`（用户端线）｜**日期**：2026-09-12｜**状态**：已实现并通过真机验证
+
+---
+
+## 1. 这条链路是干什么的
+
+记忆（对话里被抽取出来的长期事实）要能被后续召回，必须从 MySQL 同步到两处外部存储：
+
+```
+对话消息
+  └─→ memory.extraction_requested（domain_event_outbox）
+        └─→ MemoryExtractionWorker → MemoryService.upsert() → memory_unit（MySQL，唯一真相）
+              └─→ profile.rebuild_requested（domain_event_outbox）
+                    ├─→ ProfileAssemblyService.rebuild()        → profile_snapshots
+                    ├─→ ProfileGraphProjectionService          → Neo4j（图）
+                    └─→ ProfileGenerationService.generate()    → memory_sync_outbox
+                          ├─ milvus → MilvusProfileProjection   → Milvus 长期记忆向量
+                          └─ neo4j  → ProfileGraphProjectionService（幂等复投）
+```
+
+`memory_sync_outbox` 是"画像版本 → 外部存储"的投递队列，唯一键
+`uk_memory_sync_event (event_uuid, target_store)`：**同一 `event_uuid` 对两个目标库各写一条**。
+
+---
+
+## 2. ⚠️ 最容易踩的坑：枚举取值必须全仓统一（小写 + 英文）
+
+这条链曾**完全失效但不报错**，根因就是取值口径不统一。
+
+### 唯一正确口径
+
+| 字段 | 取值 | 大小写 |
+|---|---|---|
+| `target_store` | `milvus` / `neo4j` | **小写** |
+| `operation` | `upsert` / `archive` / `delete` | **小写** |
+| `status` | `pending` / `failed` / `processed` / `dead` | **小写英文** |
+
+（`aggregate_type` 用 `memory` / `profile` / `relationship` / `deletion`。）
+
+### 为什么照 `docs/00` §6.4.6 写会坏
+
+`docs/00` §6.4.6 那一栏曾写作大写 `MILVUS`/`NEO4J`、`UPSERT` 与中文 `待处理`，
+与**全仓实现从未对齐**。按那份文档写会造成：
+
+1. `MemorySyncOutboxWorker` 按 `handlers.get(event.target_store)` 分派 handler
+   —— 大写值找不到 handler；
+2. 领取条件是 `status.in_({"pending","failed"})` —— 中文 `待处理` 不满足。
+
+⇒ **两个条件都不满足，事件任何消费者都领不到，永久滞留且不报错。**
+唯一键 `(event_uuid, target_store)` 对大小写没有约束，MySQL 也不会报错，所以是**静默失效**。
+
+判断依据应以**主干既有读取方**为准，不是文档：
+`projection_reconciliation_service.py:20`（`{"pending","failed"}`）、
+`graph_projection_worker.py`（`pending`/`processed`/`dead`）。
+
+### 现状
+
+- 生产端取值集中在 `app/service/profile_generation_service.py` 的常量
+  （`TARGET_MILVUS`/`TARGET_NEO4J`/`SYNC_OPERATION_UPSERT`/`SYNC_STATUS_PENDING`）；
+- **测试不再硬编码字面量**，并断言 `SYNC_STATUS_PENDING == "pending"`、
+  `set(SYNC_TARGETS) == {"milvus","neo4j"}`
+  （硬编码正是当初跑偏的直接原因）；
+- `tests/unit/worker/test_memory_sync_outbox_worker.py` 有一条契约回归测试，
+  断言大写 `MILVUS` 分派不到 handler、会进死信 —— 谁改回大写，测试立刻红；
+- 历史 2 行已就地把取值改齐（只改值，主键/唯一键/payload 未动），
+  正式订正工具 `tools/normalize_memory_sync_outbox.py`
+  （**默认 dry-run，加 `--apply` 才写库**，幂等可复跑；换环境若也有同批旧值可直接用）。
+
+---
+
+## 3. Milvus 长期记忆向量集合
+
+| 项 | 值 |
+|---|---|
+| 集合名 | `user_long_term_memory_v1` |
+| 主键 | `memory_uuid`（VARCHAR 64，UUID 字符串，**按 UUID 幂等 upsert**） |
+| 向量 | `embedding`，`FLOAT_VECTOR` dim **1024**，索引 `AUTOINDEX` + `COSINE` |
+| 其他字段 | `customer_id`(INT64) / `version`(INT64,可空) / `valid_until_ts`(INT64,可空) / `updated_at_ts`(INT64,可空) / `confidence`(DOUBLE) / `content`(VARCHAR 2048) / `memory_type`(VARCHAR 32) / `memory_key`(VARCHAR 64) / `status`(VARCHAR 16) |
+
+建集合：`python tools/setup_milvus_profile_collection.py`
+——**幂等**，集合已存在时只做结构比对报告、不覆盖不删重建（共享 Milvus 实例里还有别的项目的集合）。
+
+### `memory_sources` 契约（适配器的输入）
+
+```json
+{
+  "customer_id": 9102,
+  "profile_version": 2,
+  "memory_sources": [{
+    "memory_uuid": "uuid 字符串",
+    "memory_key": "preference:risk_level",
+    "content": "正文",
+    "memory_type": "preference",
+    "confidence": 0.9,
+    "version": 1,
+    "valid_until": null
+  }]
+}
+```
+
+数据源：`memory_unit` 中 `status='active'` 的行
+（`ProfileRepository.active_memories()`）。**由生产端组装**而不是消费端回查：
+消费端到时记忆可能已改版本，事件里带确定快照才能与 `aggregate_version` 语义一致。
+
+> 为什么用 `memory_unit` 而不是 `user_facts`：两者用途不同 —— `user_facts` 是
+> **已确认的结构化事实**（喂画像与图投影），`memory_unit` 是**长期记忆条目**
+> （正是长期记忆向量集合要存的东西）。这不与"图投影只读 `user_facts`"的不变式冲突。
+
+---
+
+## 4. 移植自 `ZSY_develop` 的改动（含两处契约放宽）
+
+来源：同事 `ZSY_develop` 分支。整文件移植、骨架未改的部分：
+`app/core/conversation_privacy.py`、`app/worker/memory_sync_outbox_worker.py`
+（领取/`skip_locked`/指数退避/5 次转死信的可靠性骨架原样保留）、
+`app/infrastructure/milvus_profile_projection.py`。
+
+对适配器做了**两处契约放宽**，都是"避免整批失败"，不改变写入语义：
+
+1. **`customer_id` 接受 int 或数字字符串**
+   原实现要求 `isinstance(customer_id, int)`，而本仓**所有**生产者写的都是
+   `str(customer_id)`。不放宽则**每个事件必然失败**、重试 5 次后进死信。
+   放宽仅限**纯数字**串，非数字（如 uuid）仍拒绝。
+2. **不可投影的 `memory_key` 跳过而非整批报错**
+   受控词表 `app/service/memory_taxonomy.py` 共 13 个键，其中 `constraint:*`（3 个）与
+   `profile:*`（4 个）不以 `preference:`/`goal:` 开头。原实现对第一个不合规的键直接
+   `raise` —— 一条 `constraint:` 记忆就会毒死该客户整批同步。现改为**跳过并留痕**。
+
+**收窄而非扩容的理由**：`preference:*`/`goal:*` 是偏好与目标，适合语义召回；
+`constraint:*`/`profile:*` 是结构化约束与属性，应由结构化通道查询（`user_facts` → 图），
+放进向量集合只会造成召回噪声。若日后要给它们做语义召回，应扩容而非靠现在的跳过。
+
+---
+
+## 5. Neo4j 分支：方案 A（不引入第二套投影）
+
+同事分支另有一套 `neo4j_profile_projection.py`（按客户各建私有
+`Preference`/`Goal` 节点、数据源 `memory_unit`）。**未采用**，理由：
+
+主干 `ProfileGraphProjectionService` 已由 `profile.rebuild_requested` 驱动同一条链，
+其数据源是 `user_facts`（**已确认事实**）、`MERGE` **共享 tag 节点**，且文件头写明不变式：
+
+> "只投影'已确认'的事实……保证图里的偏好标签与画像口径一致；
+> 否则同一件事在画像和图里会有两种说法。"
+
+两套并存 = 同一事实在图中两种表示，正好违反这条不变式。
+因此 `memory_sync_outbox` 的 `neo4j` 分支**复用主干服务**：
+图投影是 `MERGE` 幂等的，再投一次不产生重复节点/关系，只用于收敛 outbox 的投递状态。
+
+---
+
+## 6. 消费端装配
+
+`WorkerRuntime.consume_profile_projections()`（`app/worker/runtime.py`），在
+`run_once()` 每轮执行，按条提交、单条失败不冒泡。
+
+- `milvus` handler → `MilvusProfileProjection`（注入 `MilvusProfileVectorClient` + 向量化）；
+- `neo4j` handler → `ProfileGraphProjectionService`；其 `degraded` 会**如实抛错**
+  走失败/退避，不记成已投递；
+- `milvus_uri` 未配置时**显式降级**：不消费、事件留 `pending`（可观测、可重放），
+  启动路径留一条 warning，绝不伪造同步成功（与 `knowledge_writer` 同一取向）；
+- 目标存储没有对应 handler 时判**死信**并记 `target_handler_not_configured`
+  —— 这正是当初大写值事件的下场（有回归测试守着）。
+
+向量化复用与知识向量同一套已批准端点解析（`agent_type="memory_recall"`,
+`task_type="embedding"`）。
+
+---
+
+## 7. 真机验证证据（2026-09-12）
+
+| 验证项 | 结果 |
+|---|---|
+| 集合创建幂等 | 首次 `created`，复跑 `exists` |
+| 真实 embedding 维度 | **1024**（与集合定义一致） |
+| 真实写入 + 回读 | 2 条可投影键写入成功并可回读（内容/版本正确） |
+| 不可投影键 | `constraint:liquidity` **未写入**（跳过生效，未毒死整批） |
+| 测试数据清理 | 已按 `customer_id=999999` 删除，集合残留 **0** 条 |
+| 单元测试 | 新增 17 个（适配器 10 + worker 5 + 生产端 2），全过 |
+| 全量回归 | `2 failed, 1307 passed, 2 skipped` —— 与基线一致，**无新增失败** |
+| mypy | `Success: no issues found in 227 source files` |
+
+> 全量的 2 个失败是既有环境相关项（`test_offsite_document_recognition_adapter.py`
+> 断言请求体里的中文原文，而 httpx 序列化成 `\uXXXX`），与本次改动无关。
+
+> 真机注意：Milvus 写入后**短时间内可能查不到**（索引尚未可见），
+> 验证脚本按重试处理；同理删除后立即查询可能仍返回旧行，需重查确认。
+
+---
+
+## 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 的取值栏与实现不一致：按评审要求**未改基线文档**，
+   实际口径以本文第 2 节为准。
+
+---
+
+## 9. 相关文件
+
+**新增**
+- `app/core/conversation_privacy.py`（移植）
+- `app/infrastructure/milvus_profile_projection.py`（移植 + 2 处放宽）
+- `app/infrastructure/milvus_profile_vector_client.py`
+- `app/worker/memory_sync_outbox_worker.py`（移植）
+- `tools/setup_milvus_profile_collection.py`
+- `tests/unit/infrastructure/test_milvus_profile_projection.py`
+- `tests/unit/worker/test_memory_sync_outbox_worker.py`
+
+**修改**
+- `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` 接线）
+- `tests/unit/service/test_profile_generation_service.py`（+2 用例、断言改引用常量）