# 企业售后 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、权限、审批、状态恢复、审计和测试案例。