mini-starter/docs/stories/011.003.wechat-payment-refund-integration.story.md

Story 011.003: 集成微信支付退款功能

Status

Ready for Review

Story

As a 系统管理员, I want 在PaymentMtService中集成微信支付退款功能, so that 用户取消已支付订单时能够自动调用微信支付SDK完成退款流程

Acceptance Criteria

1. 在PaymentMtService中添加退款功能
2. 集成微信支付退款SDK
3. 实现退款请求构建和签名
4. 处理退款回调通知
5. 退款状态正确更新到订单和退款记录
6. 退款金额、退款流水号等字段正确记录
7. 支持部分退款和全额退款

Tasks / Subtasks

• 在PaymentMtService中实现退款方法 (AC: 1, 2, 3)
  • 实现退款请求构建逻辑 packages/mini-payment-mt/src/services/payment.mt.service.ts:240-265
  • 集成微信支付退款SDK调用 packages/mini-payment-mt/src/services/payment.mt.service.ts:250-258
• 处理退款实时返回结果 (AC: 4, 5)
  • 处理退款API同步返回结果 packages/mini-payment-mt/src/services/payment.mt.service.ts:250-258
  • 根据退款结果立即更新订单状态 packages/orders-module-mt/src/services/order.mt.service.ts:218-226
  • 验证现有退款回调处理逻辑（可选） packages/mini-payment-mt/src/services/payment.mt.service.ts:295-298
• 扩展payment.mt.entity.ts中的退款相关字段 (AC: 5, 6)
  • 添加退款状态字段 packages/mini-payment-mt/src/entities/payment.mt.entity.ts:45-48
  • 添加退款流水号字段 packages/mini-payment-mt/src/entities/payment.mt.entity.ts:49-52
  • 添加退款金额字段 packages/mini-payment-mt/src/entities/payment.mt.entity.ts:53-56
  • 添加退款时间字段 packages/mini-payment-mt/src/entities/payment.mt.entity.ts:57-60
• 集成退款功能到订单取消流程 (AC: 5, 7)
  • 在OrderMtService中调用PaymentMtService退款方法 packages/orders-module-mt/src/services/order.mt.service.ts:210-217
  • 处理退款成功/失败状态 packages/orders-module-mt/src/services/order.mt.service.ts:218-226
  • 更新订单和退款记录状态 packages/orders-module-mt/src/services/order.mt.service.ts:229-235
• 实现退款测试 (AC: 1-7)
  • 编写退款API集成测试 packages/mini-payment-mt/tests/integration/payment-refund.integration.test.ts:30-60 (新文件)
  • 验证多租户退款数据隔离 packages/mini-payment-mt/tests/integration/payment-refund.integration.test.ts:100-130

Dev Notes

Previous Story Insights

• Story 1: 支付回调处理逻辑已完全实现，订单状态同步正常
• Story 2: 订单取消功能已实现，已支付订单触发退款流程占位符
• 多租户数据隔离已验证通过
• 测试覆盖完整，所有集成测试通过

Data Models

PaymentMtEntity [Source: packages/mini-payment-mt/src/entities/payment.mt.entity.ts]

• 需要扩展退款相关字段：
  • refundStatus: 退款状态
  • refundTransactionId: 微信退款流水号
  • refundAmount: 退款金额
  • refundTime: 退款时间

OrderRefundMt [Source: packages/orders-module-mt/src/entities/order-refund.mt.entity.ts]

• 现有字段：
  • orderNo: 订单号
  • refundOrderNo: 退款订单号
  • refundAmount: 退款金额
  • state: 退款状态 (1-退款中, 2-退款成功, 3-退款失败)

API Specifications

退款服务调用

• 调用方式: 服务层直接调用 PaymentMtService.refund()
• 调用位置: packages/orders-module-mt/src/services/order.mt.service.ts:210-217

• 参数:

  await paymentService.refund(
  tenantId,
  order.orderNo,
  order.payAmount
  )
  

• 返回结果:

  {
  refund_id: string;     // 微信退款流水号
  out_refund_no: string; // 商户退款订单号
  }
  

Component Specifications

PaymentMtService [Source: packages/mini-payment-mt/src/services/payment.mt.service.ts]

• 现有方法：
  • initializeWxPay(tenantId: number): 初始化微信支付SDK
  • handlePaymentCallback(): 处理支付回调
• 需要添加：
  • refund(tenantId: number, orderNo: string, refundAmount: number): 退款方法
  • handleRefundCallback(): 处理退款回调

UserRefundsMtService [Source: packages/orders-module-mt/src/services/user-refunds.mt.service.ts]

• 现有方法：
  • getUserRefundsList(): 获取用户退款列表
  • createUserRefund(): 创建退款记录

File Locations

• 退款服务实现: packages/mini-payment-mt/src/services/payment.mt.service.ts:240-265 (添加refund方法)
• 退款实时处理: packages/mini-payment-mt/src/services/payment.mt.service.ts:250-258 (退款API同步返回)
• 退款回调处理: packages/mini-payment-mt/src/services/payment.mt.service.ts:295-298 (现有退款回调处理，可选)
• 退款类型定义: packages/mini-payment-mt/src/entities/payment.types.ts:1-42 (需要扩展退款相关类型)
• 退款实体字段: packages/mini-payment-mt/src/entities/payment.mt.entity.ts:45-60 (需要添加退款相关字段)
• 退款测试: packages/mini-payment-mt/tests/integration/payment-refund.integration.test.ts (需要创建)
• 订单服务集成: packages/orders-module-mt/src/services/order.mt.service.ts:210-235 (集成退款调用)
• 退款记录服务: packages/orders-module-mt/src/services/user-refunds.mt.service.ts:1-50 (创建退款记录)

Testing Requirements

测试框架

• 单元测试: Vitest
• 集成测试: Vitest + hono/testing
• 测试位置: tests 文件夹与源码并列
• 覆盖率目标: 核心业务逻辑 > 80%

退款测试场景

• 全额退款成功测试
• 部分退款成功测试
• 退款失败场景测试
• 退款回调处理测试
• 多租户退款数据隔离测试

Technical Constraints

技术栈 [Source: architecture/tech-stack.md]

• 运行时: Node.js 20.18.3
• 框架: Hono 4.8.5
• 数据库: PostgreSQL 17 + TypeORM 0.3.25
• 支付SDK: wechatpay-node-v3

多租户要求

• 所有退款操作必须支持租户数据隔离
• 退款配置从SystemConfigServiceMt获取
• 退款记录与租户ID关联

Project Structure Notes

项目结构完全对齐，所有需要的包和模块都已存在：

• packages/mini-payment-mt: 多租户支付模块
• packages/orders-module-mt: 多租户订单模块
• packages/core-module-mt: 多租户系统配置模块

Change Log

Date	Version	Description	Author
2025-11-21	1.0	初始故事草稿创建	Bob (Scrum Master)

Dev Agent Record

This section is populated by the development agent during implementation

Agent Model Used

• Claude Code (d8d-model)

Debug Log References

• 支付服务退款方法实现：packages/mini-payment-mt/src/services/payment.mt.service.ts:430-573
• 订单服务退款集成：packages/orders-module-mt/src/services/order.mt.service.ts:210-231
• 退款记录创建：packages/orders-module-mt/src/services/order.mt.service.ts:288-309

Completion Notes List

1. ✅ 扩展PaymentMtEntity添加退款相关字段（退款状态、退款流水号、退款金额、退款时间）
2. ✅ 在PaymentMtService中实现完整的退款方法，包括参数验证、微信支付SDK调用、状态更新
3. ✅ 实现退款回调处理逻辑，支持签名验证和数据解密
4. ✅ 在OrderMtService中集成退款功能，当取消已支付订单时自动触发退款流程
5. ✅ 创建退款记录，关联订单和退款信息
6. ✅ 编写完整的退款集成测试，覆盖成功场景、错误场景和多租户数据隔离
7. ✅ 修复模块间依赖关系，确保订单模块可以正确导入支付模块

File List

• 新增文件:

  • packages/mini-payment-mt/tests/integration/payment-refund.integration.test.ts - 退款集成测试

• 修改文件:

  • packages/mini-payment-mt/src/entities/payment.mt.entity.ts - 添加退款相关字段
  • packages/mini-payment-mt/src/entities/payment.types.ts - 扩展退款相关类型定义
  • packages/mini-payment-mt/src/services/payment.mt.service.ts - 实现退款方法和回调处理
  • packages/orders-module-mt/src/services/order.mt.service.ts - 集成退款功能到订单取消流程
  • packages/orders-module-mt/package.json - 添加支付模块依赖

QA Results

Results from QA Agent QA review of the completed story implementation