From 67ba1b8eee5a13109d7e33f12844b030d1854faf Mon Sep 17 00:00:00 2001
From: Windows <19353512109@163.com>
Date: Sat, 12 Sep 2026 13:23:43 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=A0=87=E6=98=8E=20neo4j=5Fprofile=5F?=
 =?UTF-8?q?projection=20=E5=BD=93=E5=89=8D=E6=9C=AA=E8=A2=AB=E7=94=9F?=
 =?UTF-8?q?=E4=BA=A7=E8=A3=85=E9=85=8D=EF=BC=88=E6=96=B9=E6=A1=88=20A=20?=
 =?UTF-8?q?=E5=8F=96=E8=88=8D=EF=BC=89=E5=8F=8A=E5=90=AF=E7=94=A8=E5=89=8D?=
 =?UTF-8?q?=E6=8F=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

该适配器与主干 `ProfileGraphProjectionService` 是同一件事的两套实现，对图的建模不同：
本模块按客户各建**私有** `Preference`/`goal` 节点、数据源是 `memory_unit`；
主干服务写**共享** tag 节点、数据源是 `user_facts` 且只投影已确认事实。

## 它不是"本来就没被装配"

| 提交 | 事件 |
|---|---|
| `f167390`（ZSY） | 新建该适配器 |
| `5e848f5`（ZSY） | `feat: wire neo4j projection into worker` —— 在 `__main__.py` 装配，此后一直是**活的** |
| `4d8edb4`（主干） | PR #7 合并后接线仍在，**仍是活的** |
| `57677f6`（本次合并） | 主动摘掉那段装配 ⇒ 失去生产引用 |

`__main__.py` 在本次合并中并没有冲突（git 自动取的是带接线的主干版本），
是本线解决完冲突后**主动手工删除**的。

## 但根本原因是它与方案 A 互斥

只要落实方案 A，它就必然失去引用 —— "删 `__main__.py` 接线、保留 runtime 那套"与
"保留 `__main__.py` 骨架、把它的 neo4j handler 换成主干服务"两种做法结果相同。
所以这不是方案 A 的副作用，而是"两套图投影本来就只能活一套"。

## 改动

- `app/infrastructure/neo4j_profile_projection.py` 文件头加 `.. warning::`：
  写明当前未被生产装配、为什么、其单测保护的是**模块自身契约**而非"已装配"，
  以及**启用前提** —— 必须先决定"图的节点模型以谁为准"，只加回 `__main__.py` 装配
  会重新变成两套图投影并存。
- `docs/39-主干合并对策记录.md` §3.3 补完整时间线与上述论证；§6 第 1 条改为准确表述。
- **保留文件**（实现本身完整：`MERGE` 幂等、按 `profile_version` 判重不被旧版本覆盖、
  写入前经 `sanitize_customer_service_message` 脱敏），去留待架构师定：
  删除 / 保留为参考实现（当前取此）/ 反过来改用它（则方案 A 需重议）。

验证：`mypy app` → 245 文件 0 错；该模块 4 个单测通过；文档守卫 53 份无编号冲突。
---
 .../neo4j_profile_projection.py               | 27 ++++++++++++++
 docs/39-主干合并对策记录.md                   | 36 ++++++++++++++++---
 2 files changed, 59 insertions(+), 4 deletions(-)

diff --git a/app/infrastructure/neo4j_profile_projection.py b/app/infrastructure/neo4j_profile_projection.py
index 4dcba13..1df4fac 100644
--- a/app/infrastructure/neo4j_profile_projection.py
+++ b/app/infrastructure/neo4j_profile_projection.py
@@ -1,6 +1,33 @@
 """Neo4j 客户画像最小投影适配器。
 
 该模块只接受已审核画像快照的结构化来源，不接受模型生成的 Cypher 或关系名称。
+
+.. warning::
+
+   **本模块当前未被生产代码装配**（2026-09-12 起）。
+
+   它与主干 `app/service/profile_graph_projection_service.py` 是**同一件事的两套实现**，
+   而两者对图的建模不同：
+
+   - **本模块**：`MERGE (c:Customer)-[:PREFERS/HAS_GOAL]->(p:Preference/goal)`，
+     按客户各建**私有**节点，数据源是 `memory_unit`（原始记忆）；
+   - **主干服务**：`MERGE (a:Customer)-[:PREFERS]->(b:tag)`，写**共享** tag 节点，
+     数据源是 `user_facts`（**已确认**事实），并显式承诺
+     "只投影已确认的事实……否则同一件事在画像和图里会有两种说法"。
+
+   两套同时上线 ⇒ 同一事实在图中两种表示。2026-09-12 合并主干 PR #7 时据此取舍为
+   **方案 A：只保留主干服务**，`memory_sync_outbox` 的 `neo4j` 分支改由
+   `WorkerRuntime.consume_profile_projections()` 调用 `ProfileGraphProjectionService`；
+   原先在 `app/worker/__main__.py` 里对本模块的装配（`memory_sync_handlers["neo4j"]`）
+   已删除。取舍的完整理由见 `docs/39-主干合并对策记录.md` §3.3。
+
+   **保留本文件**是因为实现本身是完整的（`MERGE` 幂等、按 `profile_version` 判重不被旧版本覆盖、
+   写入前经 `sanitize_customer_service_message` 脱敏），对后续讨论仍有参考价值；
+   其单测 `tests/unit/infrastructure/test_neo4j_profile_projection.py` 仍在跑，
+   保护的是模块自身的契约，**不代表它已被装配**。
+
+   **若要启用**：不要只加回 `__main__.py` 的装配 —— 那会重新变成两套图投影并存。
+   正确顺序是先决定"图的节点模型以谁为准"，再改主干服务或本模块使二者一致。
 """
 
 from dataclasses import dataclass
diff --git a/docs/39-主干合并对策记录.md b/docs/39-主干合并对策记录.md
index afa0498..0f1ce7e 100644
--- a/docs/39-主干合并对策记录.md
+++ b/docs/39-主干合并对策记录.md
@@ -83,9 +83,35 @@
    Milvus 客户端由 `bootstrap.get_milvus_profile_vector_client()` 惰性构造、缺配置时显式降级
    —— 与 `runtime.py` 自己写明的"由组装层注入、不在此兜底"口径一致。
 
-**副作用**：`app/infrastructure/neo4j_profile_projection.py`（ZSY 那套）**不再被生产代码引用**，
-只剩它自己的单测在跑 ⇒ 成为**死代码**。本线**未删**（属架构师线，且其单测仍在），
-**请架构师决定**：是删掉，还是明确"两套图投影各服务什么场景"。
+**随之失去生产引用的文件**：`app/infrastructure/neo4j_profile_projection.py`（ZSY 那套）。
+
+必须说清楚**这不是"它本来就是死代码"**，时间线如下：
+
+| 提交 | 事件 |
+|---|---|
+| `f167390`（ZSY） | 新建该适配器 |
+| `5e848f5`（ZSY） | `feat: wire neo4j projection into worker` —— 在 `__main__.py` 装配，**此后一直是活的** |
+| `4d8edb4`（主干） | PR #7 合并后接线仍在（`memory_sync_handlers["neo4j"] = Neo4jProfileProjection(neo4j_driver).upsert`），**仍是活的** |
+| **`57677f6`（本次合并）** | **摘掉** `__main__.py 的那段装配 ⇒ 本文件失去生产引用 |
+
+`__main__.py` 在本次合并中**并没有冲突**（git 自动取的是带接线的主干版本），
+是本线在解决完冲突后**主动手工删除**那段接线的。
+
+**但更根本的原因是：它与方案 A 天然互斥。** 该文件本身就是"第二套图投影"，
+只要落实方案 A，它就必然失去引用 —— 换哪种做法都一样
+（"删 `__main__.py` 接线、保留 runtime 那套"与"保留 `__main__.py` 骨架、把它的 neo4j
+handler 换成主干服务"两种做法，结果相同）。所以这不是方案 A 的副作用，
+而是"两套图投影本来就只能活一套"。
+
+**本线的处理**：**保留文件**（实现本身完整：`MERGE` 幂等、按 `profile_version` 判重、
+写入前脱敏），并在其文件头加 `.. warning::` 写明"当前未被生产装配、为什么、
+以及启用前必须先决定图的节点模型以谁为准"；其单测继续跑，但保护的是模块自身契约，
+**不代表它已被装配**。
+
+**待架构师决定**：
+1. 删除该文件 + 其单测（它承载的是被否决的方案，留着可能被误读为"可用实现"）；
+2. 保留为参考实现（**本线当前取此**）；
+3. 或反向 —— 若认为该用它而非主干服务，则"方案 A"需要重新讨论（这已超出本线能定的范围）。
 
 ---
 
@@ -148,7 +174,9 @@
 
 ## 6. 遗留 / 待架构师确认
 
-1. **`neo4j_profile_projection.py` 成为死代码**（§3.3）—— 删或明确分工。
+1. **`neo4j_profile_projection.py` 失去生产引用**（§3.3）—— 本质是它与方案 A 互斥，
+   不是它本来就没被装配。本线已在文件头加警告说明并保留文件，
+   待架构师在"删除 / 保留为参考 / 反过来改用它"三者间决定。
 2. **投顾线两处生产者的 payload 仍缺 `memory_sources`** —— 本线的消费端已有兜底（不再死信），
    但根治应由投顾线补上或明确"这两个来源是否也要投影长期记忆"。
 3. **`docs/00` §6.4.6 的取值栏与实现不一致** —— 按既定裁定未改基线文档，