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