# iConsulting Agent 能力扩展 — P0/P1/P2 实施计划

> 生成日期: 2026-02-07
> 目标：将 iConsulting 从纯咨询 Agent 升级为具备完整业务闭环的智能助手

---

## 当前状态总结

### 已实现 ✅
- 多 Agent 协调架构 (Coordinator + 6 specialists)
- 16 个工具 (knowledge search, assessment, memory, web search, etc.)
- 支付工具 `generate_payment` 已定义但返回 MOCK 数据
- payment-service 已有完整的 Order/Payment/Adapter 架构（Alipay/WeChat/Stripe adapter 为 mock）
- WebSocket 已 emit `tool_call` 和 `tool_result` 事件
- 前端 `ToolCallResult` 组件已识别 `generate_payment` 但只显示占位符

### 缺失 ❌
- conversation-service 没有调用 payment-service 的 HTTP 客户端
- 没有 `check_payment_status` 工具（Agent 无法查询支付状态）
- 没有 `query_order_history` 工具（Agent 无法查询用户订单历史）
- 前端没有安装 `qrcode.react`，无法渲染真实二维码
- 前端 `tool_call`/`tool_result` WebSocket 事件只 console.log，未处理到消息 metadata
- 没有发票生成能力
- 没有前端交互式表单（chat 内嵌表单收集信息）

---

## P0 — 支付闭环（Payment Closure）

### 目标
Agent 能真正生成支付订单 → 返回支付二维码 → 前端渲染二维码 → Agent 能查询支付状态 → Agent 能查询订单历史

### 步骤

#### P0-1: PaymentClientService
**新建** `conversation-service/src/infrastructure/payment/payment-client.service.ts`

- 模仿 `KnowledgeClientService` 的 HTTP 客户端模式（使用 native `fetch`）
- `PAYMENT_SERVICE_URL` 从 ConfigService 读取，默认 `http://payment-service:3002`
- 方法:
  - `createOrder(params: { userId, serviceType, serviceCategory?, conversationId? })` → 调用 `POST /orders`
  - `createPayment(params: { orderId, method })` → 调用 `POST /payments`
  - `checkPaymentStatus(paymentId: string)` → 调用 `GET /payments/:id/status`
  - `getOrderStatus(orderId: string)` → 调用 `GET /orders/:id/status`
  - `getUserOrders(userId: string)` → 调用 `GET /orders` (header: x-user-id)

**新建** `conversation-service/src/infrastructure/payment/payment.module.ts`
- 提供 `PaymentClientService`，导出供 `AgentsModule` 使用

**修改** `agents.module.ts`
- 导入 `PaymentModule`
- `ImmigrationToolsService` 构造函数注入 `PaymentClientService`

#### P0-2: 重写 generate_payment 工具
**修改** `immigration-tools.service.ts` 的 `generatePayment()` 方法

流程:
1. 调用 `paymentClient.createOrder(...)` 创建订单
2. 调用 `paymentClient.createPayment({ orderId, method })` 生成支付
3. 返回真实的 `{ orderId, paymentId, qrCodeUrl, amount, expiresAt }`
4. 删除 MOCK 数据

#### P0-3: 添加 check_payment_status 工具
**修改** `immigration-tools.service.ts`:
- 添加工具定义: `check_payment_status`，输入 `{ orderId }`
- 添加实现: 调用 `paymentClient.getOrderStatus(orderId)` 返回状态

**修改** `coordinator-tools.ts`:
- 在 `DIRECT_TOOLS` 中添加 `check_payment_status` 工具定义
- 在 `TOOL_CONCURRENCY_MAP` 中标记为 `true`（只读）

#### P0-4: 添加 query_order_history 工具
**修改** `immigration-tools.service.ts`:
- 添加工具定义: `query_order_history`，输入 `{ userId }`
- 添加实现: 调用 `paymentClient.getUserOrders(userId)` 返回订单列表

**修改** `coordinator-tools.ts`:
- 在 `DIRECT_TOOLS` 中添加 `query_order_history` 工具定义
- 在 `TOOL_CONCURRENCY_MAP` 中标记为 `true`（只读）

#### P0-5: 前端 QR 码渲染
**安装** `qrcode.react` 到 web-client

**修改** `MessageBubble.tsx` 的 `ToolCallResult` 组件:
- 导入 `QRCodeSVG` from `qrcode.react`
- `generate_payment` 结果中，使用 `<QRCodeSVG value={qrCodeUrl} />` 渲染真实二维码
- 添加 `check_payment_status` 结果的渲染（状态卡片）
- 添加 `query_order_history` 结果的渲染（订单列表卡片）

#### P0-6: 处理 tool_call/tool_result WebSocket 事件
**修改** `useChat.ts`:
- `tool_call` 事件: 存储到临时状态（当前消息正在执行的工具调用）
- `tool_result` 事件: 将结果收集到 pending toolCalls 数组
- `stream_end` 事件: 将收集的 toolCalls 注入消息 metadata

---

## P1 — 信息收集 UX 增强

### 目标
Agent 能在聊天中展示结构化的评估结果卡片，用户能直观看到评分和建议

### 步骤

#### P1-1: 评估结果卡片组件
**新建** `web-client/src/features/chat/presentation/components/AssessmentResultCard.tsx`

- 针对 `collect_assessment_info` 和 `invoke_assessment_expert` 的工具结果
- 展示：评估类别、各项得分、总分、建议
- 使用现有 Tailwind 样式
- 分数条形图（纯 CSS，不需要 recharts）

#### P1-2: 在 ToolCallResult 中集成
**修改** `MessageBubble.tsx`:
- 识别 `collect_assessment_info` 工具结果，渲染 `AssessmentResultCard`
- 识别评估相关结果，渲染评分卡片

---

## P2 — 财务合规

### 目标
Agent 能查询用户交易记录，支持退款处理（为未来发票功能预留接口）

### 步骤

#### P2-1: 交易历史查询增强
**修改** `PaymentClientService`:
- 添加 `getOrderDetail(orderId)` → 获取含支付详情的完整订单

**修改** `immigration-tools.service.ts`:
- `query_order_history` 工具返回更丰富的信息（支付时间、状态、金额明细）

#### P2-2: 退款处理工具
**修改** `PaymentClientService`:
- 添加 `requestRefund(orderId, reason)` → 调用 payment-service 退款 API

**修改** `immigration-tools.service.ts`:
- 添加 `request_refund` 工具定义和实现
- 安全限制：需要确认对话 + 订单在可退款时间窗口内

**修改** `coordinator-tools.ts`:
- 添加 `request_refund` 工具定义
- `TOOL_CONCURRENCY_MAP` 中标记为 `false`（有副作用）

#### P2-3: 前端交易记录展示
**修改** `MessageBubble.tsx`:
- 增强 `query_order_history` 的渲染：显示支付方式图标、退款状态
- 添加 `request_refund` 结果渲染

---

## 文件变更清单

### P0 新建文件 (2)
| 文件 | 说明 |
|------|------|
| `infrastructure/payment/payment-client.service.ts` | Payment-service HTTP 客户端 |
| `infrastructure/payment/payment.module.ts` | Payment 模块 |

### P0 修改文件 (5)
| 文件 | 改动 |
|------|------|
| `agents/agents.module.ts` | +PaymentModule import |
| `claude/tools/immigration-tools.service.ts` | +PaymentClientService 注入, 重写 generatePayment, +2 新工具 |
| `agents/tools/coordinator-tools.ts` | +2 新工具定义, +concurrency map |
| `web-client/.../MessageBubble.tsx` | +QRCodeSVG, +3 工具结果渲染 |
| `web-client/.../useChat.ts` | +tool_call/tool_result 事件处理 |

### P1 新建文件 (1)
| 文件 | 说明 |
|------|------|
| `web-client/.../AssessmentResultCard.tsx` | 评估结果卡片组件 |

### P1 修改文件 (1)
| 文件 | 改动 |
|------|------|
| `web-client/.../MessageBubble.tsx` | +评估结果卡片渲染 |

### P2 修改文件 (3)
| 文件 | 改动 |
|------|------|
| `infrastructure/payment/payment-client.service.ts` | +getOrderDetail, +requestRefund |
| `claude/tools/immigration-tools.service.ts` | +request_refund 工具 |
| `agents/tools/coordinator-tools.ts` | +request_refund 定义 |

---

## 验证计划

每个 P 级别完成后:
1. `pnpm build` — conversation-service 和 web-client 均编译通过
2. 详细 commit 备注说明改动内容
3. `git push` 推送到 remote
4. 进入下一个 P 级别