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，会被消费至死信，待架构师确认是否投影。
2026-09-12 10:45:40 +08:00
parent c82e9890e4
commit 8a0cbab636
15 changed files with 1477 additions and 12 deletions
@@ -0,0 +1,137 @@
+"""`MemorySyncOutboxWorker` 的定向测试。
+
+4 个用例移植自同事 `ZSY_develop` 的
+`tests/unit/worker/test_memory_sync_outbox_worker.py`；最后一个用例是本仓新增的
+**契约回归测试**——它是这次整条链故障的根因所在，必须有人守着。
+"""
+
+from datetime import datetime
+
+import pytest
+
+from app.model.memory import MemorySyncOutbox
+from app.worker.memory_sync_outbox_worker import MemorySyncOutboxWorker
+
+
+class FakeSession:
+    def __init__(self, event: MemorySyncOutbox | None) -> None:
+        self.event = event
+        self.commits = 0
+        self.rollbacks = 0
+
+    async def __aenter__(self) -> "FakeSession":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        return None
+
+    async def scalar(self, statement: object) -> MemorySyncOutbox | None:
+        del statement
+        return self.event
+
+    async def commit(self) -> None:
+        self.commits += 1
+
+    async def rollback(self) -> None:
+        self.rollbacks += 1
+
+
+def event(*, target: str = "neo4j", retry_count: int = 0) -> MemorySyncOutbox:
+    return MemorySyncOutbox(
+        id=1, event_uuid="event-1", aggregate_type="profile",
+        aggregate_uuid="profile-1", aggregate_version=1, target_store=target,
+        operation="upsert", payload={"customer_id": 7}, status="pending",
+        retry_count=retry_count, next_retry_at=None, last_error=None,
+        created_at=datetime(2026, 1, 1), processed_at=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_success_marks_event_processed() -> None:
+    item = event()
+    session = FakeSession(item)
+    seen: list[dict[str, object]] = []
+
+    async def handler(payload: dict[str, object]) -> None:
+        seen.append(payload)
+
+    worker = MemorySyncOutboxWorker({"neo4j": handler}, session_factory=lambda: session)
+    assert await worker.run_once() is True
+    assert seen == [{"customer_id": 7}]
+    assert item.status == "processed"
+    assert item.processed_at is not None
+    assert session.commits == 1
+
+
+@pytest.mark.asyncio
+async def test_handler_failure_uses_backoff_and_keeps_event() -> None:
+    item = event()
+    session = FakeSession(item)
+
+    async def handler(payload: dict[str, object]) -> None:
+        del payload
+        raise TimeoutError
+
+    worker = MemorySyncOutboxWorker({"neo4j": handler}, session_factory=lambda: session)
+    assert await worker.run_once() is True
+    assert item.status == "failed"
+    assert item.retry_count == 1
+    assert item.next_retry_at is not None
+    assert item.last_error == "TimeoutError"
+
+
+@pytest.mark.asyncio
+async def test_fifth_failure_enters_dead_state() -> None:
+    item = event(retry_count=4)
+    session = FakeSession(item)
+
+    async def handler(payload: dict[str, object]) -> None:
+        del payload
+        raise RuntimeError
+
+    worker = MemorySyncOutboxWorker({"neo4j": handler}, session_factory=lambda: session)
+    await worker.run_once()
+    assert item.status == "dead"
+    assert item.retry_count == 5
+    assert item.next_retry_at is None
+
+
+@pytest.mark.asyncio
+async def test_missing_handler_enters_dead_state_without_external_call() -> None:
+    item = event(target="milvus")
+    session = FakeSession(item)
+    worker = MemorySyncOutboxWorker({"neo4j": lambda _: None}, session_factory=lambda: session)
+
+    assert await worker.run_once() is True
+    assert item.status == "dead"
+    assert item.last_error == "target_handler_not_configured"
+
+
+# --- 本仓新增：契约回归 ------------------------------------------------------
+
+
+@pytest.mark.asyncio
+async def test_no_handler_is_registered_for_uppercase_target_store() -> None:
+    """契约回归：`target_store` 只能是小写 `milvus`/`neo4j`。
+
+    背景（这条链真实故障的根因）：`profile_generation_service` 曾照 `docs/00` §6.4.6
+    写作大写 `MILVUS`/`NEO4J` + 中文状态 `待处理`，而本 worker 按 `target_store` 的**值**
+    分派 handler、且只领 `{"pending","failed"}`。结果该事件两个条件都不满足，
+    **任何消费者都领不到，永久滞留且不报错**（唯一键 `(event_uuid, target_store)`
+    对大小写没有约束，所以静默）。
+
+    本用例把"大写分派不到"这一事实钉住：将来谁把取值改回大写，这里会立刻红。
+    """
+    item = event(target="MILVUS", retry_count=0)
+    session = FakeSession(item)
+    called: list[object] = []
+
+    async def handler(payload: dict[str, object]) -> None:
+        called.append(payload)
+
+    worker = MemorySyncOutboxWorker({"milvus": handler}, session_factory=lambda: session)
+    assert await worker.run_once() is True
+
+    assert called == []  # 大写键分派不到 milvus handler
+    assert item.status == "dead"
+    assert item.last_error == "target_handler_not_configured"