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

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

Status

Draft

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

To be filled by dev agent

Debug Log References

To be filled by dev agent

Completion Notes List

To be filled by dev agent

File List

To be filled by dev agent

QA Results

Results from QA Agent QA review of the completed story implementation