📝 docs(payment): add wechat payment refund integration story

- create story document for微信支付退款功能集成
- define acceptance criteria for退款功能实现
- outline development tasks and subtasks
- document technical specifications and constraints
- add testing requirements for退款功能验证

docs/stories/011.3.wechat-payment-refund-integration.story.md

@@ -0,0 +1,169 @@
+# Story 011.3: 集成微信支付退款功能
+
+## 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中添加refund方法 (AC: 1, 2, 3)
+  - [ ] 实现退款请求构建逻辑
+  - [ ] 集成微信支付退款SDK调用
+  - [ ] 实现退款签名和参数验证
+  - [ ] 添加退款回调处理逻辑
+- [ ] 在payment.mt.routes.ts中添加退款API端点 (AC: 1, 4)
+  - [ ] 创建退款API路由
+  - [ ] 实现退款请求验证
+  - [ ] 添加退款回调处理路由
+- [ ] 扩展payment.mt.entity.ts中的退款相关字段 (AC: 5, 6)
+  - [ ] 添加退款状态字段
+  - [ ] 添加退款流水号字段
+  - [ ] 添加退款金额字段
+  - [ ] 添加退款时间字段
+- [ ] 集成退款功能到订单取消流程 (AC: 5, 7)
+  - [ ] 在OrderMtService中调用PaymentMtService退款方法
+  - [ ] 处理退款成功/失败状态
+  - [ ] 更新订单和退款记录状态
+- [ ] 实现退款测试 (AC: 1-7)
+  - [ ] 编写退款功能单元测试
+  - [ ] 编写退款API集成测试
+  - [ ] 编写退款回调集成测试
+  - [ ] 验证多租户退款数据隔离
+
+## 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
+**退款API端点** [Source: architecture/api-design-integration.md]
+- **方法**: POST
+- **端点**: `/api/v1/payment/refund`
+- **认证**: JWT Bearer Token
+- **请求格式**:
+  ```json
+  {
+    "orderNo": "订单号",
+    "refundAmount": 退款金额,
+    "reason": "退款原因"
+  }
+  ```
+- **响应格式**:
+  ```json
+  {
+    "refundId": "退款ID",
+    "refundTransactionId": "微信退款流水号",
+    "status": "退款状态"
+  }
+  ```
+
+**退款回调端点**
+- **方法**: POST
+- **端点**: `/api/v1/payment/refund-callback`
+- **处理微信支付退款回调通知**
+
+### 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`
+- **退款API路由**: `packages/mini-payment-mt/src/routes/payment/refund.mt.ts` (需要创建)
+- **退款回调路由**: `packages/mini-payment-mt/src/routes/payment/refund-callback.mt.ts` (需要创建)
+- **退款类型定义**: `packages/mini-payment-mt/src/entities/payment.types.ts` (需要扩展)
+- **退款测试**: `packages/mini-payment-mt/tests/integration/payment-refund.integration.test.ts` (需要创建)
+
+### Testing Requirements
+**测试框架** [Source: architecture/coding-standards.md]
+- **单元测试**: 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*