# 记忆投影链路（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"`）。

### 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）

| 验证项 | 结果 |
|---|---|
| 集合创建幂等 | 首次 `created`，复跑 `exists` |
| 真实 embedding 维度 | **1024**（与集合定义一致） |
| 真实写入 + 回读 | 2 条可投影键写入成功并可回读（内容/版本正确） |
| 不可投影键 | `constraint:liquidity` **未写入**（跳过生效，未毒死整批） |
| 测试数据清理 | 已按 `customer_id=999999` 删除，集合残留 **0** 条 |
| **消费端全路径**（补验） | 见下方 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`
> 断言请求体里的中文原文，而 httpx 序列化成 `\uXXXX`），与本次改动无关。

> 真机注意：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_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 节为准。

---

## 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`
- `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()`、`_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 数字）