feat: add customer profile candidate flow

2026-09-11 17:16:43 +08:00
parent ef098e6a4b
commit 3a21afa847
10 changed files with 295 additions and 6 deletions
@@ -0,0 +1,84 @@
+# 客服 Agent 二期：客户画像候选流程
+
+版本：v1.0  
+适用分支：`ZSY_develop2`  
+状态：候选提取链路已实现，确认/审核入口待后续迭代
+
+## 1. 业务边界
+
+本阶段只为**已登录用户**的客服对话生成画像候选，不为访客生成任何客户画像数据。
+客服 Agent 仍然不读取长期画像、不读取持仓/收益/订单/银行卡/投诉进度，也不直接修改
+`fin_customer_profile` 或 `profile_snapshots`。
+
+候选数据不是正式画像，不能用于客服回答、产品推荐、风险等级判断或交易决策。
+
+## 2. 处理流程
+
+```text
+已登录用户客服消息
+  -> 识别明确的长期偏好/约束/目标信号
+  -> 完成客服回答并在同一事务写入候选 Outbox
+  -> Worker 回查权威用户消息
+  -> 二次脱敏
+  -> 受控模型抽取 memory_key/value/type/confidence
+  -> 写入 memory_unit(status='candidate') + memory_evidence
+  -> 等待用户确认或管理员审核
+  -> 后续流程再决定是否晋升为 active/profile_snapshots
+```
+
+普通公开问答、闲聊、一次性操作问题不触发候选抽取；访客、非客服 Agent、非 self 数据范围
+和缺少已登录身份标记的事件均失败关闭。
+
+## 3. 事件契约
+
+事件类型：`customer_profile.candidate_requested`
+
+事件只携带定位和身份信息，不携带用户原文：
+
+```json
+{
+  "run_id": "运行 ID",
+  "message_id": 123,
+  "customer_id": 456,
+  "actor_type": "authenticated_customer"
+}
+```
+
+事件由 `AgentPersistenceService.complete_run()` 与客服回答、审计和运行终态在同一事务写入，
+由 `WorkerRuntime` 异步消费。重复消费使用事件 ID 作为证据幂等键。
+
+## 4. 数据与安全约束
+
+- 候选写入既有 `memory_unit`，状态固定为 `candidate`，不会覆盖同键的 `active` 记忆。
+- 证据写入既有 `memory_evidence`，幂等键格式为
+  `customer_profile.candidate_requested:{event_id}`。
+- 候选抽取前对消息执行客服隐私脱敏；证据摘录不得保存密码、验证码、完整手机号、
+  完整证件号或完整银行卡号。
+- 模型输出继续使用既有受控词表和严格 JSON 校验；抽取失败时不写任何记忆。
+- 访客候选事件必须被消费者拒绝，不能仅依赖上游路由判断。
+- `MemoryRecallService` 只召回 `active` 状态，因此候选不会进入任何 Agent 的长期记忆上下文。
+
+## 5. 当前已实现文件
+
+- `app/service/memory_service.py`：支持候选状态写入，并保证候选不覆盖正式记忆。
+- `app/worker/memory_extraction_worker.py`：支持事件类型、状态、来源和脱敏策略配置。
+- `app/worker/customer_profile_candidate_worker.py`：已登录客服候选专用消费者。
+- `app/service/agent_persistence_service.py`：完成客服运行时写入候选 Outbox 事件。
+- `app/worker/runtime.py`：候选触发判定与事件处理器。
+
+## 6. 尚未实现的后续能力
+
+1. 用户确认候选的接口和页面。
+2. 管理员候选列表、审核、驳回和审计接口。
+3. 候选晋升为 `active` 的冲突检测、版本切换和 `profile_snapshots` 生成。
+4. 候选撤回、过期、删除和隐私授权管理。
+5. 候选流程的 MySQL 集成测试和管理员端到端验收。
+
+在上述能力完成前，禁止把 `candidate` 状态直接作为正式画像对外展示或用于业务决策。
+
+## 7. 验证结果
+
+- 客服画像候选专项测试：通过。
+- 一期单元与契约回归：`683 passed`。
+- Ruff：通过。
+- Mypy：通过。