docs: design enterprise aftersales agent

docs/superpowers/specs/2026-07-08-enterprise-aftersales-agent-design.md

@@ -0,0 +1,349 @@
+# 企业售后 Agent 实战项目设计
+
+## 目标
+
+构建一个面向充电业务售后场景的企业 Agent 项目。用户描述问题后，Agent 能判断售后意图，检索售后政策，查询充电订单和充电记录，生成处理建议。低风险动作自动创建售后工单，高风险退款或补偿进入审批，审批后按冻结动作恢复执行，并记录全链路审计。
+
+首版目标不是做普通聊天机器人，而是做一个受控的企业执行者：能查、能建议、能调用工具，但高风险动作必须可审批、可恢复、可追责。
+
+## 范围
+
+首版采用双服务垂直切片：
+
+- Java `zsElectric-boot`：企业业务系统和 MCP Server，负责业务工具、审批、冻结动作、审计、售后政策和数据库。
+- Python `zsElectric-agent-service`：独立兄弟服务，使用 FastAPI 作为服务框架，使用 OpenAI Agents SDK 作为 Agent 编排层，作为 MCP Client 调用 Java MCP Server。
+- PostgreSQL + pgvector：作为售后政策 RAG 知识库。
+- Swagger 或 Postman：用于审批演示，不开发审批管理页面。
+
+不在首版范围内：
+
+- 不把所有 Java REST Controller 自动暴露为工具。
+- Python 不直连 Java 业务数据库。
+- 不做完整前端审批后台。
+- 不接入 MCP 之外的泛化工具网关。
+
+## 架构
+
+```text
+用户
+  -> Python zsElectric-agent-service (FastAPI)
+       -> OpenAI Agents SDK
+       -> RAG Retriever (PostgreSQL + pgvector)
+       -> MCP Client
+  -> Java zsElectric-boot MCP Server
+       -> tool registry / whitelist / risk policy
+       -> approval / pending action / audit log
+       -> existing service / mapper / DB
+```
+
+Python 只负责 Agent 编排：意图判断、对话状态、工具选择、RAG 上下文组装、最终建议生成。
+
+Java 负责企业能力暴露：通过 MCP tools 暴露受控业务动作，内部仍然走现有 service 层，保留鉴权、参数校验、风险分级、审批、审计和幂等保护。
+
+HTTP 可以作为 MCP 的传输方式存在，但对 Python 来说，调用边界是 MCP tool，不是普通业务 REST API。
+
+## Java 模块
+
+在 `zsElectric-boot` 中新增 `platform.agent` 模块：
+
+```text
+platform.agent
+├─ mcp              # MCP endpoint 和 tool 暴露层
+├─ tool             # 工具注册、白名单、风险等级、schema
+├─ approval         # 审批和 pending_action
+├─ audit            # Agent 全链路审计
+├─ policy           # 售后政策文档和 RAG 元数据
+└─ aftersales       # 售后工单、退款、补偿业务适配
+```
+
+Java MCP Server 暴露的工具必须来自白名单，并带明确参数 schema、风险等级、trace_id、operator/user 上下文。模型不能直接访问 Mapper、数据库或内部通用 Controller。
+
+## Python 模块
+
+在兄弟目录创建 `E:\wzq\workCode\zswl\zsElectric-agent-service`：
+
+```text
+app
+├─ main.py          # FastAPI app
+├─ agents           # OpenAI Agents SDK agent 定义
+├─ mcp_client       # 连接 Java MCP Server
+├─ rag              # pgvector 检索和上下文组装
+├─ schemas          # 请求、响应、工具结果结构
+├─ api              # chat、resume、trace、health 路由
+└─ evals            # 测试问题集和期望结果
+```
+
+FastAPI 接口：
+
+```text
+POST /api/v1/agent/chat
+POST /api/v1/agent/resume/{approval_id}
+GET  /api/v1/agent/runs/{trace_id}
+GET  /health
+```
+
+## MCP 工具
+
+首版工具清单：
+
+```text
+query_charge_order(order_no | user_id | phone)
+query_charge_session(order_no)
+retrieve_aftersales_policy(issue_type, keywords)
+create_aftersales_work_order(order_no, issue_type, suggestion, evidence)
+request_refund(order_no, amount, reason, evidence)
+request_compensation(order_no, compensation_type, amount, reason)
+get_approval_status(approval_id)
+resume_after_approval(approval_id)
+write_agent_audit(trace_id, step, input, output, status)
+```
+
+风险等级：
+
+```text
+LOW:
+  query_charge_order
+  query_charge_session
+  retrieve_aftersales_policy
+  create_aftersales_work_order
+  write_agent_audit
+
+HIGH:
+  request_refund
+  request_compensation
+  resume_after_approval
+```
+
+低风险工具可以直接执行。高风险工具不直接退款或补偿，而是由 Java 创建审批单和冻结动作，返回 `approval_required`。
+
+## 数据表
+
+核心表：
+
+```text
+agent_tool_registry
+agent_approval
+agent_pending_action
+agent_audit_log
+aftersales_work_order
+aftersales_policy_doc
+aftersales_policy_chunk
+```
+
+### agent_tool_registry
+
+记录 MCP 工具治理信息：
+
+- `id`
+- `tool_name`
+- `description`
+- `risk_level`
+- `enabled`
+- `input_schema_json`
+- `output_schema_json`
+- `created_at`
+- `updated_at`
+
+### agent_approval
+
+记录审批单：
+
+- `approval_id`
+- `trace_id`
+- `status`: `pending`, `approved`, `rejected`, `expired`, `executed`
+- `risk_level`
+- `request_user_id`
+- `request_username`
+- `approver_id`
+- `approver_username`
+- `reason`
+- `decision_comment`
+- `created_at`
+- `approved_at`
+- `expires_at`
+
+### agent_pending_action
+
+记录审批通过后要恢复执行的冻结动作：
+
+- `id`
+- `approval_id`
+- `trace_id`
+- `tool_name`
+- `params_json`
+- `params_hash`
+- `execute_status`: `pending`, `executed`, `failed`, `expired`
+- `execute_result_json`
+- `error_message`
+- `idempotency_key`
+- `created_at`
+- `executed_at`
+- `expires_at`
+
+审批恢复时使用 `pending_action` 中的冻结参数，不重新让模型生成参数。执行前必须校验审批状态、过期时间、params hash、工具白名单、风险等级和幂等键。
+
+### agent_audit_log
+
+记录全链路审计：
+
+- `id`
+- `trace_id`
+- `approval_id`
+- `step`
+- `tool_name`
+- `input_json`
+- `output_json`
+- `status`
+- `error_message`
+- `operator_id`
+- `operator_username`
+- `created_at`
+
+审计步骤包括用户输入、意图判断、RAG 命中文档、工具调用、审批创建、审批结果、恢复执行和最终回复。
+
+### aftersales_work_order
+
+记录售后工单：
+
+- `id`
+- `trace_id`
+- `order_no`
+- `issue_type`
+- `suggestion`
+- `evidence_json`
+- `status`
+- `created_by_agent`
+- `created_at`
+- `updated_at`
+
+### aftersales_policy_doc / aftersales_policy_chunk
+
+`aftersales_policy_doc` 保存政策原文和版本，`aftersales_policy_chunk` 保存分片文本、embedding 和元数据，用于 pgvector 检索。
+
+## 主流程
+
+低风险流程：
+
+```text
+1. FastAPI /chat 接收用户问题，生成 trace_id
+2. Agent 判断意图，例如“充电失败咨询”
+3. Agent 通过 RAG 检索售后政策
+4. Agent 通过 MCP 调 query_charge_order 和 query_charge_session
+5. Agent 生成处理建议
+6. Agent 通过 MCP 调 create_aftersales_work_order
+7. Java 创建工单并写 audit_log
+8. FastAPI 返回建议、工单号、trace_id
+```
+
+高风险流程：
+
+```text
+1. FastAPI /chat 接收用户问题，生成 trace_id
+2. Agent 判断意图，例如“充电失败要求退款”
+3. Agent 检索政策并查询订单、充电记录
+4. Agent 判断需要退款或补偿
+5. Agent 通过 MCP 调 request_refund 或 request_compensation
+6. Java 判断为 HIGH 风险，创建 agent_approval
+7. Java 创建 agent_pending_action，冻结 tool_name 和 params_json
+8. Java 返回 approval_required、approval_id、建议说明
+9. 人在 Swagger/Postman 调 Java 审批接口 approve 或 reject
+10. FastAPI /resume/{approval_id} 调 MCP resume_after_approval
+11. Java 校验审批和 pending_action，执行真实退款或补偿
+12. Java 写 audit_log 并返回工具结果
+13. Agent 生成最终客服回复
+```
+
+## Java 审批接口
+
+审批演示接口放在 Java：
+
+```text
+GET  /api/v1/agent/approvals
+GET  /api/v1/agent/approvals/{approval_id}
+POST /api/v1/agent/approvals/{approval_id}/approve
+POST /api/v1/agent/approvals/{approval_id}/reject
+```
+
+审批通过只改变审批状态，不直接执行退款或补偿。真实执行由 `resume_after_approval(approval_id)` 触发，保证“审批”和“执行恢复”边界清楚。
+
+## 错误处理
+
+```text
+RAG 无命中:
+  返回“政策依据不足”，只允许生成建议，不允许自动退款或补偿。
+
+订单不存在:
+  停止工具链路，写 audit_log，返回需要人工核查。
+
+MCP 工具失败:
+  记录 trace_id、tool_name、input、error，不让 Agent 猜测执行结果。
+
+审批过期:
+  pending_action 标记 expired，需要重新发起申请。
+
+审批拒绝:
+  resume_after_approval 返回 rejected，Agent 生成拒绝后的客服回复。
+
+参数被篡改:
+  params_hash 校验失败，拒绝执行并写高危审计。
+
+重复恢复:
+  pending_action 已执行则返回历史结果，保证幂等。
+```
+
+## 测试
+
+Java 测试：
+
+- 工具白名单测试。
+- 高低风险分级测试。
+- approval 和 pending_action 落库测试。
+- approve/reject 状态流转测试。
+- resume_after_approval 幂等测试。
+- params_hash 篡改保护测试。
+- audit_log 写入测试。
+
+Python FastAPI 测试：
+
+- `/chat` 低风险自动建工单。
+- `/chat` 高风险返回 `approval_required`。
+- `/resume/{approval_id}` 审批后恢复执行。
+- MCP client 工具调用失败。
+- RAG 无命中降级。
+
+集成演示：
+
+- 充电失败但只需普通售后处理，自动建工单。
+- 充电失败要求退款，进入审批。
+- 审批通过，resume 后执行退款或补偿。
+- 审批拒绝，Agent 生成拒绝说明。
+- 通过 trace_id 查询完整审计链路。
+
+## 里程碑
+
+### M1 Java MCP Server 与治理表
+
+交付 MCP endpoint、tool registry、approval、pending_action、audit_log，以及基础售后政策表。
+
+### M2 Python FastAPI Agent
+
+交付 FastAPI 服务、OpenAI Agents SDK agent、MCP client、基础 RAG 检索、`/chat` 和 `/resume`。
+
+### M3 售后业务闭环
+
+交付订单查询、充电记录查询、政策检索、工单创建、退款/补偿审批和审批恢复。
+
+### M4 验证与演示
+
+交付种子数据、Swagger/Postman 脚本、eval case、README 跑通文档。
+
+## 验收标准
+
+- Python 服务不直连 Java 业务数据库。
+- Java 只暴露白名单 MCP tools，不把全部业务接口自动暴露给模型。
+- 低风险售后问题可以自动创建工单。
+- 高风险退款或补偿必须产生审批单和冻结动作。
+- 审批通过后可以按 `approval_id` 恢复执行。
+- 审批拒绝、审批过期、重复恢复、参数篡改都有确定结果。
+- 每次 Agent 运行都能通过 `trace_id` 查到完整审计链路。
+- 项目文档能解释 RAG、MCP Tool Calling、权限、审批、状态恢复、审计和测试案例。