iconsulting/docs/implementation-plan-p0-p1-p2.md

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 级别