📝 docs(story): add payment callback logic documentation

- 创建支付回调处理逻辑文档，明确需求和验收标准
- 定义updateOrderPaymentStatus方法实现任务和集成点
- 记录技术栈、现有代码状态和关键集成要求
- 添加测试标准和多租户支持说明

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

@@ -0,0 +1,112 @@
+# 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)
+  - [ ] 添加方法签名：`updateOrderPaymentStatus(tenantId: number, externalOrderId: number, payState: number): Promise<void>`
+  - [ ] 注入 OrderMtService 依赖
+  - [ ] 实现订单状态更新逻辑，支持多租户隔离
+  - [ ] 记录支付时间和微信交易流水号
+- [ ] 完善 handlePaymentCallback 方法中的 TODO 注释 (AC: 1, 2, 6)
+  - [ ] 在支付成功时调用 updateOrderPaymentStatus 更新订单状态为 2（已支付）
+  - [ ] 在支付失败时调用 updateOrderPaymentStatus 更新订单状态为 4（支付失败）
+  - [ ] 在退款时调用 updateOrderPaymentStatus 更新订单状态为 3（已退款）
+- [ ] 增强支付回调日志记录 (AC: 5)
+  - [ ] 在回调处理的各个关键节点添加详细的调试日志
+  - [ ] 记录回调数据、验证结果、状态更新过程
+  - [ ] 确保日志包含租户ID用于多租户追踪
+- [ ] 编写单元测试和集成测试 (AC: 1-6)
+  - [ ] 为 updateOrderPaymentStatus 方法编写单元测试
+  - [ ] 为 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*