mini-starter/docs/stories/011.001.payment-callback-logic.md

Story 011.001: 完善支付回调处理逻辑

Status

Draft

Story

As a 系统管理员， I want 支付回调接口能够正确处理微信支付通知并正确更新订单状态， so that 订单状态能够与支付状态保持同步，支持多租户隔离，确保支付流程的完整性和准确性

Acceptance Criteria

1. 支付回调接口正确处理微信支付通知
2. 订单状态从"待支付"正确更新为"已支付"（支付状态从0更新为2）
3. 支付时间、支付流水号等字段正确记录
4. 支持多租户隔离，不同租户的支付回调互不影响
5. 添加支付回调日志记录
6. 修复支付模块中的TODO：更新订单状态

Tasks / Subtasks

• 在 PaymentMtService 中实现 updateOrderPaymentStatus 方法 (AC: 2, 3, 4, 6)
  • 在 packages/mini-payment-mt/src/services/payment.mt.service.ts 中添加方法签名：updateOrderPaymentStatus(tenantId: number, externalOrderId: number, payState: number): Promise<void>
  • 注入 OrderMtService 依赖（来自 packages/orders-module-mt/src/services/order.mt.service.ts）
  • 实现订单状态更新逻辑，支持多租户隔离
  • 记录支付时间和微信交易流水号
• 完善 handlePaymentCallback 方法中的 TODO 注释 (AC: 1, 2, 6)
  • 在 packages/mini-payment-mt/src/services/payment.mt.service.ts:275 的 TODO 处，在支付成功时调用 updateOrderPaymentStatus 更新订单状态为 2（已支付）
  • 在支付失败时调用 updateOrderPaymentStatus 更新订单状态为 4（支付失败）
  • 在退款时调用 updateOrderPaymentStatus 更新订单状态为 3（已退款）
• 增强支付回调日志记录 (AC: 5)
  • 在 packages/mini-payment-mt/src/services/payment.mt.service.ts 的回调处理各个关键节点添加详细的调试日志
  • 记录回调数据、验证结果、状态更新过程
  • 确保日志包含租户ID用于多租户追踪
• 编写单元测试和集成测试 (AC: 1-6)
  • 在 packages/mini-payment-mt/tests/unit/payment-service.unit.test.ts 中为 updateOrderPaymentStatus 方法编写单元测试
  • 在 packages/mini-payment-mt/tests/integration/payment-callback.integration.test.ts 中为 handlePaymentCallback 方法编写集成测试
  • 验证多租户隔离功能
  • 测试各种支付状态转换场景

Dev Notes

技术栈和架构

• 后端框架: Hono 4.8.5 + TypeORM 0.3.25
• 数据库: PostgreSQL 17
• 多租户支持: 通过租户ID字段实现数据隔离
• 支付SDK: wechatpay-node-v3
• 项目结构: Monorepo 架构，模块化包设计

现有代码状态分析

• PaymentMtService (packages/mini-payment-mt/src/services/payment.mt.service.ts:275): 存在 TODO 注释需要实现订单状态更新
• 支付回调接口 (packages/mini-payment-mt/src/routes/payment/callback.mt.ts): 已实现基本回调处理，缺少订单状态更新
• OrderMtService (packages/orders-module-mt/src/services/order.mt.service.ts): 提供订单管理功能，需要集成
• 订单实体 (packages/orders-module-mt/src/entities/order.mt.entity.ts:72): 支付状态字段定义：0未支付、1支付中、2支付成功、3已退款、4支付失败、5订单关闭

关键集成点

• 多租户支付模块: PaymentMtService 需要与多租户订单模块集成
• 订单状态更新: 需要调用 OrderMtService 来更新订单支付状态
• 租户数据隔离: 所有操作必须包含租户ID参数确保数据隔离
• 事务一致性: 支付状态更新和订单状态更新需要保持一致性

文件位置和命名约定

• 支付服务: packages/mini-payment-mt/src/services/payment.mt.service.ts
• 支付回调路由: packages/mini-payment-mt/src/routes/payment/callback.mt.ts
• 订单服务: packages/orders-module-mt/src/services/order.mt.service.ts
• 测试文件: packages/mini-payment-mt/tests/integration/payment-callback.integration.test.ts

技术约束

• 向后兼容性: 现有支付API保持不变
• 多租户支持: 所有新功能必须支持租户隔离
• 错误处理: 需要完善的错误处理和日志记录
• 性能要求: 回调处理应在合理时间内完成

Testing

测试标准

• 测试框架: Vitest + hono/testing
• 测试位置: packages/mini-payment-mt/tests/integration/
• 覆盖率目标: 核心业务逻辑 > 80%
• 测试类型: 单元测试 + 集成测试

测试要求

• 单元测试: 验证 updateOrderPaymentStatus 方法的正确性
• 集成测试: 验证完整的支付回调流程
• 多租户测试: 验证不同租户的数据隔离
• 边界测试: 测试各种支付状态转换场景
• 错误测试: 测试回调验证失败、订单不存在等异常情况

测试文件命名

• payment-callback.integration.test.ts - 支付回调集成测试
• payment-service.unit.test.ts - 支付服务单元测试

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 development agent

Debug Log References

To be filled by development agent

Completion Notes List

To be filled by development agent

File List

To be filled by development agent

QA Results

Results from QA Agent QA review of the completed story implementation