feat: add profile candidate review workflow

docs/05-接口文档.md

@@ -615,7 +615,26 @@ Authorization: Bearer <token>
 
 记忆提取没有客户端写接口。`memory.extraction_requested` 由 `complete_run()` 与最终结果在同一事务写入 Outbox，再由 Worker 调用内部 `MemoryService`。更正、遗忘和监管删除属于独立隐私流程，本接口不临时复用 `memory_conflict`。
 
-### 8.2 解析知识引用
+### 8.2 客服画像候选（Phase 2）
+
+客服 Agent 不读取或直接修改正式画像。已登录用户明确陈述长期偏好、约束或目标时，系统
+异步生成 `memory_unit.status='candidate'` 候选；访客不会生成候选。候选不进入客服召回，
+必须经过用户确认和管理员审核后才能晋升为 `active`。
+
+```text
+GET  /api/v1/users/me/memory-candidates
+POST /api/v1/users/me/memory-candidates/{candidate_id}/decisions
+GET  /api/v1/admin/customer-profile-candidates
+POST /api/v1/admin/customer-profile-candidates/{candidate_id}/reviews
+```
+
+用户确认请求体为 `{ "decision": "confirmed" | "rejected" }`，需要
+`memory:candidate:confirm`；确认只将状态改为 `verified`。管理员审核请求体复用
+`ReviewPayload`，需要管理员角色和 `memory:candidate:review`；`approved` 会在事务内
+处理同键旧记忆冲突并将候选改为 `active`，`rejected` 将其改为 `rejected`。接口只返回
+结构化候选值，不返回对话证据摘录、密码、验证码或其他原始敏感内容。
+
+### 8.3 解析知识引用
 
 ```http
 GET /api/v1/knowledge-references/{reference_token}
@@ -931,6 +950,10 @@ GET /internal/metrics
 | C007 | `POST /api/v1/conversation-messages/{message_id}/feedback` | `conversation:feedback` | 必须 | `201` | 反馈创建 |
 | M001 | `GET /api/v1/users/me/memory-profile` | `memory:read:self` | 否 | `200` | 敏感访问 |
 | M002 | `GET /api/v1/customers/{customer_id}/memory-profile` | `memory:read:customer` | 否 | `200` | 敏感访问 |
+| M003 | `GET /api/v1/users/me/memory-candidates` | `memory:read:self` | 否 | `200` | 候选查询 |
+| M004 | `POST /api/v1/users/me/memory-candidates/{candidate_id}/decisions` | `memory:candidate:confirm` | 必须 | `200` | 用户确认/拒绝 |
+| A034 | `GET /api/v1/admin/customer-profile-candidates` | `memory:candidate:review` | 否 | `200` | 候选审核列表 |
+| A035 | `POST /api/v1/admin/customer-profile-candidates/{candidate_id}/reviews` | `memory:candidate:review` | 必须 | `200` | 候选审核 |
 | K001 | `GET /api/v1/knowledge-references/{reference_token}` | `knowledge:reference:read` | 否 | `200` | 否 |
 | A001 | `POST /api/v1/admin/config-releases` | `config:write` | 必须 | `201` | 配置草稿 |
 | A002 | `GET /api/v1/admin/config-releases` | `config:read` | 否 | `200` | 否 |

docs/客服Agent二期_客户画像候选流程_v1.md

@@ -2,7 +2,7 @@
 
 版本：v1.0  
 适用分支：`ZSY_develop2`  
-状态：候选提取链路已实现，确认/审核入口待后续迭代
+状态：候选提取、用户确认和管理员审核入口已实现，画像快照同步待后续迭代
 
 ## 1. 业务边界
 
@@ -22,8 +22,10 @@
   -> 二次脱敏
   -> 受控模型抽取 memory_key/value/type/confidence
   -> 写入 memory_unit(status='candidate') + memory_evidence
-  -> 等待用户确认或管理员审核
-  -> 后续流程再决定是否晋升为 active/profile_snapshots
+  -> 用户确认或拒绝
+  -> 管理员审核
+  -> 批准后处理同键冲突并晋升为 active
+  -> 后续流程再生成 profile_snapshots
 ```
 
 普通公开问答、闲聊、一次性操作问题不触发候选抽取；访客、非客服 Agent、非 self 数据范围
@@ -58,25 +60,45 @@
 - 访客候选事件必须被消费者拒绝，不能仅依赖上游路由判断。
 - `MemoryRecallService` 只召回 `active` 状态，因此候选不会进入任何 Agent 的长期记忆上下文。
 
-## 5. 当前已实现文件
+## 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`：管理员候选查询和审核接口。
 
-## 6. 尚未实现的后续能力
+## 7. 尚未实现的后续能力
 
-1. 用户确认候选的接口和页面。
-2. 管理员候选列表、审核、驳回和审计接口。
-3. 候选晋升为 `active` 的冲突检测、版本切换和 `profile_snapshots` 生成。
-4. 候选撤回、过期、删除和隐私授权管理。
-5. 候选流程的 MySQL 集成测试和管理员端到端验收。
+1. 前端用户确认页面和管理员审核页面。
+2. 候选晋升后的 `profile_snapshots` 版本生成和 `memory_sync_outbox` 同步。
+3. 候选撤回、过期、删除和隐私授权管理。
+4. 候选流程的 MySQL 集成测试和管理员端到端验收。
 
 在上述能力完成前，禁止把 `candidate` 状态直接作为正式画像对外展示或用于业务决策。
 
-## 7. 验证结果
+## 8. 验证结果
 
 - 客服画像候选专项测试：通过。
 - 一期单元与契约回归：`683 passed`。