Story 5.11: 支付集成前端实现

Status

Done

Story

As a 出行用户 I want 能够在前端调用微信支付SDK完成订单支付 so that 方便快捷地完成出行订单支付

Acceptance Criteria

实现微信支付JSAPI集成 - 已使用 wechatpay-node-v3 SDK 完整实现
处理支付回调通知 - 已实现签名验证、数据解密和状态更新
支付状态与订单状态同步 - 已实现完整的订单状态流转机制
支付异常处理（超时、失败、重复支付） - 已实现错误处理和状态管理
支付安全验证 - 已实现签名验证、金额一致性检查、防重放攻击
支付状态查询 - 已提供支付状态查询接口
前端微信支付SDK调用 - 前端代码有TODO注释待实现

Tasks / Subtasks

实现前端微信支付调用功能 (AC: 7)
- 在订单页面实现微信支付SDK调用
- 集成后端支付API创建支付订单
- 处理支付参数并调用微信支付
- 实现支付成功/失败回调处理
完善支付状态管理 (AC: 3, 4, 6)
- 实现支付状态查询功能
- 处理支付超时和失败场景
- 防止重复支付逻辑
- 支付状态与订单状态同步
支付安全验证前端实现 (AC: 5)
- 验证支付金额一致性
- 实现支付参数安全传输
- 处理支付回调安全验证
编写前端支付组件测试 (AC: 1-7)
- 编写支付调用单元测试
- 测试支付成功/失败场景
- 测试支付状态查询功能
- 验证所有组件测试通过

Dev Notes

后端支付服务状态

基于 [docs/architecture/payment-integration-design.md#技术实现]，后端支付服务已完整实现：

支付服务架构 [Source: architecture/payment-integration-design.md#支付架构概览]:

后端支付服务: packages/server/src/modules/payment/payment.service.ts
支付API: packages/server/src/api/payment/create.ts
订单状态管理: 支持 待支付 → 支付中 → 已支付/支付失败 状态流转
安全机制: 签名验证、AES-256-GCM数据加密、防重放攻击

支付状态枚举 [Source: architecture/payment-integration-design.md#支付状态管理]:

export enum PaymentStatus {
  PENDING = '待支付',       // 订单创建，等待支付
  PROCESSING = '支付中',    // 支付进行中
  SUCCESS = '支付成功',     // 支付成功
  FAILED = '支付失败',      // 支付失败
  REFUNDED = '已退款',      // 已退款
  CLOSED = '已关闭'         // 支付关闭
}

前端技术栈要求

基于 [docs/architecture/tech-stack.md#现有技术栈维护]，必须使用项目标准技术栈：

小程序框架 [Source: architecture/tech-stack.md#现有技术栈维护]:

前端框架: Taro + React
状态管理: React Query
样式系统: Tailwind CSS + shadcn/ui

Taro小程序开发规范

基于 [docs/architecture/taro-mini-program-standards.md#api调用规范]，必须遵循Taro小程序开发规范：

API调用规范 [Source: architecture/taro-mini-program-standards.md#api调用规范]:

使用RPC客户端进行API调用
统一的错误处理机制
合理的缓存策略

微信支付API调用规范 [Source: architecture/taro-mini-program-standards.md#小程序api使用规范]:

使用Taro.requestPayment API调用微信支付
正确处理支付成功/失败回调
实现支付状态查询功能

项目结构对齐

基于 [docs/architecture/source-tree.md#实际项目结构]，前端支付相关文件必须遵循以下组织：

前端支付文件位置 [Source: architecture/source-tree.md#实际项目结构]:

订单页面: mini/src/pages/order/index.tsx
支付成功页面: mini/src/pages/pay-success/index.tsx
API客户端: mini/src/api.ts (已包含paymentClient)
支付工具函数: mini/src/utils/payment.ts (需要创建)

当前实现状态

后端支付服务: ✅ 完整实现

微信支付JSAPI集成已完成
支付回调处理已实现
支付状态管理已完善
安全验证机制已就绪

前端支付调用: 🔄 待实现

订单页面已导入paymentClient
支付API调用有TODO注释
微信支付SDK调用待实现
支付状态处理待完善

微信支付SDK调用流程

基于 [docs/architecture/payment-integration-design.md#支付流程]，前端支付调用必须遵循以下流程：

预支付流程 [Source: architecture/payment-integration-design.md#预支付流程]:

调用后端支付API创建支付订单
获取支付参数（timeStamp、nonceStr、package、signType、paySign）
调用Taro.requestPayment API
处理支付结果回调
更新订单支付状态

支付回调处理 [Source: architecture/payment-integration-design.md#支付回调流程]:

支付成功：跳转到支付成功页面
支付失败：显示错误信息，允许重新支付
支付取消：返回订单页面

安全设计要求

基于 [docs/architecture/payment-integration-design.md#安全设计]，必须遵循安全设计：

支付安全要求 [Source: architecture/payment-integration-design.md#安全设计]:

金额一致性验证
防止重复支付
支付状态同步
错误处理机制

Testing

测试要求 [Source: architecture/testing-strategy.md#主项目测试体系]:

小程序测试位置: mini/tests/ 目录
小程序测试框架: Jest + @testing-library/react + 自定义Taro组件mock
覆盖率目标: 核心业务逻辑 > 80%
需要创建的测试文件: 支付调用组件测试、支付状态管理测试、支付错误处理测试

具体测试要求 [Source: architecture/testing-strategy.md#测试金字塔策略]:

支付调用组件测试 (P1优先级)
- 测试微信支付SDK调用
- 验证支付参数正确性
- 测试支付成功/失败回调
支付状态管理测试 (P1优先级)
- 测试支付状态查询功能
- 验证支付状态同步逻辑
- 测试重复支付防止机制
支付错误处理测试 (P1优先级)
- 测试网络异常场景
- 测试支付超时处理
- 测试支付失败重试
E2E支付流程测试 (P2优先级)
- 测试完整支付流程
- 验证支付状态正确更新
- 测试支付成功页面跳转

Change Log

Date	Version	Description	Author
2025-10-24	1.0	初始故事创建，基于史诗005 US005-11需求	Bob (Scrum Master)
2025-10-24	1.0	故事验证通过，状态更新为Approved	Sarah (Product Owner)

Dev Agent Record

此部分由开发代理在实施过程中填写

Agent Model Used

Claude Sonnet 4.5 (2025-09-29)

Debug Log References

修复了TypeScript类型错误：Taro.requestPayment signType参数类型问题
修复了未使用参数警告：createPaymentTimeout函数中的orderId参数
修复了支付金额验证错误：后端API未返回金额字段导致前端验证失败
修复了随机字符串长度验证错误：放宽安全验证限制以适应微信支付实际返回

Completion Notes List

✅ 实现了完整的前端微信支付调用流程
✅ 创建了支付工具函数库，包含安全验证、状态管理等功能
✅ 集成了后端支付API，支持订单创建和支付参数获取
✅ 实现了支付状态管理和错误处理机制
✅ 添加了支付安全验证，包括金额一致性、参数完整性检查
✅ 编写了完整的单元测试，覆盖支付工具函数和组件
✅ 修复了代码中的TypeScript错误和警告
✅ 修复了支付金额验证问题：后端API现在返回金额字段用于前端安全验证
✅ 修复了安全验证限制：放宽随机字符串、签名类型等验证以适应微信支付实际返回
✅ 增强了类型安全：使用InferResponseType替代any类型定义

File List

新增文件:
- mini/src/utils/payment.ts - 支付工具函数库
- mini/tests/unit/payment.test.ts - 支付工具函数测试
- mini/tests/unit/order-page.test.tsx - 订单页面组件测试
- mini/tests/unit/pay-success-page.test.tsx - 支付成功页面测试
修改文件:
- mini/src/pages/order/index.tsx - 集成支付调用功能，修复类型定义和金额验证
- mini/src/api.ts - 已包含paymentClient，无需修改
- mini/src/pages/pay-success/index.tsx - 支付成功页面，无需修改
- mini/src/utils/payment.ts - 放宽安全验证限制
- packages/server/src/api/payment/create.ts - 添加金额字段到响应Schema
- packages/server/src/modules/payment/payment.service.ts - 返回金额字段用于前端验证

Change Log

Date	Version	Description	Author
2025-10-24	1.0	初始故事创建，基于史诗005 US005-11需求	Bob (Scrum Master)
2025-10-24	1.0	故事验证通过，状态更新为Approved	Sarah (Product Owner)
2025-10-24	1.1	前端支付集成完整实现	James (Developer)
2025-10-25	1.2	修复支付金额验证和安全验证问题	James (Developer)

QA Results

此部分由QA代理在审查完成后填写

005.011.payment-integration-frontend.story.md 9.1 KB Historique Raw

Story 5.11: 支付集成前端实现

Status

Story

Acceptance Criteria

Tasks / Subtasks

Dev Notes

后端支付服务状态

前端技术栈要求

Taro小程序开发规范

项目结构对齐

当前实现状态

微信支付SDK调用流程

安全设计要求

Testing

Change Log

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

Change Log

QA Results

005.011.payment-integration-frontend.story.md 9.1 KB

Historique Raw