客服 Agent 二期：客户画像候选流程

版本：v1.0
适用分支：ZSY_develop2
状态：候选提取、用户确认、管理员审核、画像快照生成和投影事件写入已实现

1. 业务边界

本阶段只为已登录用户的客服对话生成画像候选，不为访客生成任何客户画像数据。客服 Agent 仍然不读取长期画像、不读取持仓/收益/订单/银行卡/投诉进度，也不直接修改 fin_customer_profile 或 profile_snapshots。

候选数据不是正式画像，不能用于客服回答、产品推荐、风险等级判断或交易决策。

2. 处理流程

已登录用户客服消息
  -> 识别明确的长期偏好/约束/目标信号
  -> 完成客服回答并在同一事务写入候选 Outbox
  -> Worker 回查权威用户消息
  -> 二次脱敏
  -> 受控模型抽取 memory_key/value/type/confidence
  -> 写入 memory_unit(status='candidate') + memory_evidence
  -> 用户确认或拒绝
  -> 管理员审核
  -> 批准后处理同键冲突并晋升为 active
  -> 生成 profile_snapshots 并写入 memory_sync_outbox

普通公开问答、闲聊、一次性操作问题不触发候选抽取；访客、非客服 Agent、非 self 数据范围和缺少已登录身份标记的事件均失败关闭。

3. 事件契约

事件类型：customer_profile.candidate_requested

事件只携带定位和身份信息，不携带用户原文：

{
  "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. 确认与审核接口

用户接口：

GET /api/v1/users/me/memory-candidates：查看自己的 candidate/verified 候选。
POST /api/v1/users/me/memory-candidates/{candidate_id}/decisions：提交 confirmed 或 rejected，需要 memory:candidate:confirm。

管理员接口：

GET /api/v1/admin/customer-profile-candidates：查看所有待处理候选，需要管理员角色和 memory:candidate:review。
POST /api/v1/admin/customer-profile-candidates/{candidate_id}/reviews：提交 approved 或 rejected，需要管理员角色和 memory:candidate:review。

用户确认只转换为 verified，管理员批准才转换为 active。批准时同客户同记忆键的旧 active 记录会失效，并写入 memory_conflict，全流程在一个 MySQL 事务内完成。

6. 当前已实现文件

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：候选触发判定与事件处理器。
app/service/customer_profile_candidate_service.py：用户确认、管理员审核、冲突处理和晋升。
app/api/controllers/public_platform.py：用户候选查询和确认接口。
app/api/controllers/admin.py：管理员候选查询和审核接口。

管理员批准后，服务会创建新的 profile_snapshots 当前版本，并为 milvus、neo4j 各写入一条 memory_sync_outbox 待投影事件；旧当前版本在同一事务内标记为非当前。

7. 尚未实现的后续能力

前端用户确认页面和管理员审核页面。
memory_sync_outbox 到真实 Milvus/Neo4j 的消费者联调和失败重试验收。
候选撤回、过期、删除和隐私授权管理。
候选流程的 MySQL 集成测试和管理员端到端验收。

在上述能力完成前，禁止把 candidate 状态直接作为正式画像对外展示或用于业务决策。

8. 验证结果

客服画像候选专项测试：通过。
一期单元与契约回归：687 passed。
Ruff：通过。
Mypy：通过。

4.8 KiB Raw Blame History