From 248a55c60a7eca75695685e82ae5fcb370dadec8 Mon Sep 17 00:00:00 2001 From: zpc Date: Fri, 2 Jan 2026 22:34:41 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BB=BB=E5=8A=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .kiro/specs/payment-integration/design.md | 291 ++++++++++++++++++ .../specs/payment-integration/requirements.md | 136 ++++++++ .kiro/specs/payment-integration/tasks.md | 272 ++++++++++++++++ 3 files changed, 699 insertions(+) create mode 100644 .kiro/specs/payment-integration/design.md create mode 100644 .kiro/specs/payment-integration/requirements.md create mode 100644 .kiro/specs/payment-integration/tasks.md diff --git a/.kiro/specs/payment-integration/design.md b/.kiro/specs/payment-integration/design.md new file mode 100644 index 00000000..5b095ad6 --- /dev/null +++ b/.kiro/specs/payment-integration/design.md @@ -0,0 +1,291 @@ +# Design Document: 支付集成迁移 + +## Overview + +本设计文档描述了将PHP支付系统迁移到.NET 8的技术方案。支付系统主要包括微信支付统一下单、支付回调处理、余额/积分/哈尼券支付、以及订单发货通知等功能。 + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────┐ +│ API Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ +│ │PayController│ │NotifyController│ │OrderController │ │ +│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ +└─────────┼────────────────┼─────────────────────┼────────────┘ + │ │ │ +┌─────────▼────────────────▼─────────────────────▼────────────┐ +│ Service Layer │ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ +│ │WechatPayService │ │PaymentService │ │NotifyService│ │ +│ └────────┬────────┘ └────────┬────────┘ └──────┬──────┘ │ +└───────────┼────────────────────┼──────────────────┼─────────┘ + │ │ │ +┌───────────▼────────────────────▼──────────────────▼─────────┐ +│ Data Layer │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐ │ +│ │ Order │ │ User │ │ProfitPay │ │OrderNotify │ │ +│ └──────────┘ └──────────┘ └──────────┘ └─────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Components and Interfaces + +### 1. IWechatPayService - 微信支付服务接口 + +```csharp +public interface IWechatPayService +{ + /// + /// 创建微信支付统一下单 + /// + Task CreatePaymentAsync(WechatPayRequest request); + + /// + /// 验证支付签名 + /// + bool VerifySign(Dictionary parameters, string sign); + + /// + /// 生成支付签名 + /// + string MakeSign(Dictionary parameters); + + /// + /// 发送订单发货通知到微信 + /// + Task PostOrderShippingAsync(string orderNo, string openId); +} +``` + +### 2. IPaymentNotifyService - 支付回调服务接口 + +```csharp +public interface IPaymentNotifyService +{ + /// + /// 处理微信支付回调 + /// + Task HandleWechatNotifyAsync(string xmlData); + + /// + /// 处理一番赏订单支付成功 + /// + Task ProcessLotteryOrderAsync(int orderId, int userId, int goodsId, int num); + + /// + /// 处理无限赏订单支付成功 + /// + Task ProcessInfiniteOrderAsync(int orderId, int userId, int goodsId); + + /// + /// 处理充值订单支付成功 + /// + Task ProcessRechargeOrderAsync(string orderNo); + + /// + /// 处理发货运费支付成功 + /// + Task ProcessShippingFeeOrderAsync(string orderNo); +} +``` + +### 3. IPaymentService - 统一支付服务接口 + +```csharp +public interface IPaymentService +{ + /// + /// 扣减用户余额 + /// + Task DeductBalanceAsync(int userId, decimal amount, string content); + + /// + /// 扣减用户积分 + /// + Task DeductIntegralAsync(int userId, decimal amount, string content); + + /// + /// 扣减用户哈尼券 + /// + Task DeductMoney2Async(int userId, decimal amount, string content); + + /// + /// 记录支付流水 + /// + Task RecordPaymentAsync(int userId, string orderNo, decimal amount, int payType, string content); +} +``` + +## Data Models + +### Request/Response Models + +```csharp +// 微信支付请求 +public class WechatPayRequest +{ + public string OrderNo { get; set; } + public decimal Amount { get; set; } + public string Body { get; set; } + public string Attach { get; set; } + public string OpenId { get; set; } + public int UserId { get; set; } +} + +// 微信支付结果 +public class WechatPayResult +{ + public int Status { get; set; } + public string Msg { get; set; } + public WechatPayData Data { get; set; } +} + +public class WechatPayData +{ + [JsonPropertyName("appId")] + public string AppId { get; set; } + + [JsonPropertyName("timeStamp")] + public string TimeStamp { get; set; } + + [JsonPropertyName("nonceStr")] + public string NonceStr { get; set; } + + [JsonPropertyName("package")] + public string Package { get; set; } + + [JsonPropertyName("signType")] + public string SignType { get; set; } + + [JsonPropertyName("paySign")] + public string PaySign { get; set; } + + [JsonPropertyName("is_weixin")] + public int IsWeixin { get; set; } +} + +// 支付回调通知结果 +public class NotifyResult +{ + public bool Success { get; set; } + public string Message { get; set; } + public string XmlResponse { get; set; } +} +``` + +### Database Entities + +```csharp +// 支付通知记录表 +public class OrderNotify +{ + public int Id { get; set; } + public string OrderNo { get; set; } + public string NotifyUrl { get; set; } + public string NonceStr { get; set; } + public DateTime PayTime { get; set; } + public decimal PayAmount { get; set; } + public int Status { get; set; } + public int RetryCount { get; set; } + public DateTime CreateTime { get; set; } + public DateTime UpdateTime { get; set; } +} +``` + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: 支付签名正确性 + +*For any* set of payment parameters and secret key, generating a signature and then verifying it with the same parameters should return true. + +**Validates: Requirements 1.4, 7.1, 7.2** + +### Property 2: 支付回调幂等性 + +*For any* payment notification, processing it multiple times should produce the same result as processing it once (order status should not change after first successful processing). + +**Validates: Requirements 2.8** + +### Property 3: 资产扣减原子性 + +*For any* mixed payment transaction, either all asset deductions succeed or none of them succeed (transaction rollback on failure). + +**Validates: Requirements 6.7** + +### Property 4: 余额扣减正确性 + +*For any* balance payment, the user's balance after payment should equal the original balance minus the payment amount. + +**Validates: Requirements 3.3, 3.4** + +### Property 5: 支付记录完整性 + +*For any* successful payment, there should be a corresponding record in the profit_pay table with correct order number, amount, and payment type. + +**Validates: Requirements 8.1, 8.2** + +## Error Handling + +### Payment Errors + +| Error Code | Description | Handling | +|------------|-------------|----------| +| NOTENOUGH | 余额不足 | 返回错误提示，不扣款 | +| SIGNERROR | 签名错误 | 拒绝请求，记录日志 | +| ORDERPAID | 订单已支付 | 返回成功，不重复处理 | +| SYSTEMERROR | 系统错误 | 重试或返回错误 | + +### Transaction Handling + +```csharp +public async Task ProcessPaymentAsync(PaymentRequest request) +{ + using var transaction = await _context.Database.BeginTransactionAsync(); + try + { + // 1. 验证订单状态 + // 2. 扣减用户资产 + // 3. 更新订单状态 + // 4. 记录支付流水 + // 5. 触发后续业务（抽奖等） + + await transaction.CommitAsync(); + return true; + } + catch (Exception ex) + { + await transaction.RollbackAsync(); + _logger.LogError(ex, "Payment processing failed"); + throw; + } +} +``` + +## Testing Strategy + +### Unit Tests + +- 测试签名生成和验证逻辑 +- 测试余额/积分/哈尼券扣减逻辑 +- 测试支付参数构建逻辑 + +### Property-Based Tests + +- 使用FsCheck或类似库测试签名的正确性 +- 测试支付回调的幂等性 +- 测试资产扣减的原子性 + +### Integration Tests + +- 测试完整的支付流程 +- 测试支付回调处理流程 +- 测试混合支付场景 + +### Test Configuration + +- 使用InMemory数据库进行单元测试 +- 使用测试商户配置进行集成测试 +- 模拟微信支付API响应 diff --git a/.kiro/specs/payment-integration/requirements.md b/.kiro/specs/payment-integration/requirements.md new file mode 100644 index 00000000..0521c50f --- /dev/null +++ b/.kiro/specs/payment-integration/requirements.md @@ -0,0 +1,136 @@ +# Requirements Document + +## Introduction + +本文档定义了将PHP支付系统迁移到.NET 8的需求。支付系统是订单系统的核心组成部分，负责处理微信支付、余额支付、积分支付等多种支付方式，以及支付回调处理和支付状态管理。 + +## Glossary + +- **Payment_Service**: 支付服务，负责处理各种支付方式的统一接口 +- **Wechat_Pay_Service**: 微信支付服务，负责与微信支付API交互 +- **Order_Notify_Service**: 支付回调服务，负责处理微信支付回调通知 +- **User**: 用户实体，包含余额、积分等资产信息 +- **Order**: 订单实体，包含订单金额、支付状态等信息 +- **Profit_Pay**: 支付记录实体，记录用户的支付流水 + +## Requirements + +### Requirement 1: 微信支付统一下单 + +**User Story:** As a user, I want to pay for my order using WeChat Pay, so that I can complete my purchase conveniently. + +#### Acceptance Criteria + +1. WHEN a user initiates WeChat payment, THE Wechat_Pay_Service SHALL create a unified order with correct parameters +2. WHEN the unified order is created successfully, THE Wechat_Pay_Service SHALL return valid payment parameters (appId, timeStamp, nonceStr, package, signType, paySign) +3. WHEN the unified order creation fails, THE Wechat_Pay_Service SHALL return an appropriate error message +4. THE Wechat_Pay_Service SHALL generate correct MD5 signature for payment parameters +5. THE Wechat_Pay_Service SHALL support multiple merchant configurations based on order prefix + +### Requirement 2: 微信支付回调处理 + +**User Story:** As a system, I want to process WeChat payment notifications, so that order status can be updated correctly after payment. + +#### Acceptance Criteria + +1. WHEN a payment notification is received, THE Order_Notify_Service SHALL verify the signature before processing +2. WHEN the signature verification passes and payment is successful, THE Order_Notify_Service SHALL update the order status to paid +3. WHEN the order is a lottery order (一番赏/无限赏), THE Order_Notify_Service SHALL trigger the prize drawing process +4. WHEN the order is a recharge order, THE Order_Notify_Service SHALL add balance to user account +5. WHEN the order is a shipping fee order, THE Order_Notify_Service SHALL update the delivery record status +6. THE Order_Notify_Service SHALL record payment information in profit_pay table +7. THE Order_Notify_Service SHALL deduct user assets (balance, integral, money2) if used in the order +8. IF the payment notification is a duplicate, THEN THE Order_Notify_Service SHALL return success without reprocessing +9. THE Order_Notify_Service SHALL return correct XML response to WeChat + +### Requirement 3: 余额支付 + +**User Story:** As a user, I want to pay using my account balance, so that I can use my accumulated funds. + +#### Acceptance Criteria + +1. WHEN a user chooses balance payment, THE Payment_Service SHALL verify sufficient balance +2. IF the balance is insufficient, THEN THE Payment_Service SHALL return an error message +3. WHEN balance payment is successful, THE Payment_Service SHALL deduct the amount from user balance +4. THE Payment_Service SHALL record the balance deduction in profit_money table +5. THE Payment_Service SHALL update order status to paid after successful balance payment + +### Requirement 4: 积分支付 + +**User Story:** As a user, I want to pay using my points (吧唧币), so that I can redeem my accumulated points. + +#### Acceptance Criteria + +1. WHEN a user chooses integral payment, THE Payment_Service SHALL verify sufficient integral balance +2. IF the integral is insufficient, THEN THE Payment_Service SHALL return an error message +3. WHEN integral payment is successful, THE Payment_Service SHALL deduct the amount from user integral +4. THE Payment_Service SHALL record the integral deduction in profit_integral table +5. THE Payment_Service SHALL apply the correct exchange rate for integral to money conversion + +### Requirement 5: 哈尼券支付 + +**User Story:** As a user, I want to pay using my Honey vouchers (哈尼券), so that I can use my promotional credits. + +#### Acceptance Criteria + +1. WHEN a user chooses money2 payment, THE Payment_Service SHALL verify sufficient money2 balance +2. IF the money2 is insufficient, THEN THE Payment_Service SHALL return an error message +3. WHEN money2 payment is successful, THE Payment_Service SHALL deduct the amount from user money2 +4. THE Payment_Service SHALL record the money2 deduction in profit_money2 table + +### Requirement 6: 混合支付 + +**User Story:** As a user, I want to combine multiple payment methods, so that I can use all my available assets. + +#### Acceptance Criteria + +1. WHEN a user uses mixed payment, THE Payment_Service SHALL process each payment method in order +2. THE Payment_Service SHALL first deduct balance if use_money_is is enabled +3. THE Payment_Service SHALL then deduct integral if use_integral_is is enabled +4. THE Payment_Service SHALL then deduct money2 if use_money2_is is enabled +5. THE Payment_Service SHALL calculate remaining amount for WeChat payment +6. IF the total deductions cover the order amount, THEN THE Payment_Service SHALL complete payment without WeChat +7. THE Payment_Service SHALL ensure atomicity of all deductions in a transaction + +### Requirement 7: 支付签名验证 + +**User Story:** As a system, I want to verify payment signatures, so that payment security is ensured. + +#### Acceptance Criteria + +1. THE Payment_Service SHALL generate MD5 signature using sorted parameters and secret key +2. THE Payment_Service SHALL verify incoming signatures match calculated signatures +3. THE Payment_Service SHALL support multiple secret keys for different merchants +4. IF signature verification fails, THEN THE Payment_Service SHALL reject the request + +### Requirement 8: 支付记录管理 + +**User Story:** As a user, I want to view my payment history, so that I can track my spending. + +#### Acceptance Criteria + +1. THE Payment_Service SHALL record all payment transactions in profit_pay table +2. THE Payment_Service SHALL include order number, amount, payment type, and timestamp +3. THE Payment_Service SHALL support querying payment records by user and type + +### Requirement 9: 订单发货通知 + +**User Story:** As a system, I want to notify WeChat about order shipment, so that users can track their orders in WeChat. + +#### Acceptance Criteria + +1. WHEN an order is paid, THE Payment_Service SHALL send shipping notification to WeChat +2. THE Payment_Service SHALL include correct merchant ID and order number +3. IF the notification fails, THEN THE Payment_Service SHALL store the order for retry +4. THE Payment_Service SHALL support retry mechanism for failed notifications + +### Requirement 10: API响应格式兼容 + +**User Story:** As a frontend developer, I want the payment API responses to match the PHP API format, so that no frontend changes are needed. + +#### Acceptance Criteria + +1. THE Payment_Service SHALL return responses in the same format as PHP API +2. THE Payment_Service SHALL use snake_case for all response field names +3. THE Payment_Service SHALL return status code 1 for success and 0 for failure +4. THE Payment_Service SHALL include msg field with appropriate message diff --git a/.kiro/specs/payment-integration/tasks.md b/.kiro/specs/payment-integration/tasks.md new file mode 100644 index 00000000..b8c30a7f --- /dev/null +++ b/.kiro/specs/payment-integration/tasks.md @@ -0,0 +1,272 @@ +# Implementation Plan: 支付集成迁移 + +## Overview + +本任务列表将PHP支付系统迁移到.NET 8，按照接口优先级逐个迁移。每迁移一个接口前，需要先查看PHP代码了解详细业务逻辑；迁移完成后，需要在API接口文档.md中标记迁移状态。 + +## Tasks + +- [ ] 1. 基础设施准备 + - [ ] 1.1 创建支付相关的DTO和Request/Response模型 + - 在HoneyBox.Model/Models/Payment目录下创建相关模型 + - 包括WechatPayRequest、WechatPayResult、WechatPayData等 + - 包括NotifyResult、PaymentRecordDto等 + - _Requirements: 1.1-10.4_ + - [ ] 1.2 创建服务接口定义 + - 在HoneyBox.Core/Interfaces目录下创建IWechatPayService、IPaymentNotifyService接口 + - _Requirements: 1.1-10.4_ + - [ ] 1.3 创建数据库实体模型（如果尚未存在） + - 确认OrderNotify实体存在 + - 配置EF Core映射 + - _Requirements: 1.1-10.4_ + - [ ] 1.4 注册服务到DI容器 + - 在ServiceModule.cs中注册WechatPayService、PaymentNotifyService + - _Requirements: 1.1-10.4_ + +- [ ] 2. 微信支付配置服务实现 + - [ ] 2.1 查看PHP代码了解微信支付配置逻辑 + - 阅读server/php/app/api/controller/Pay.php中的构造函数和setMerchantByOrderNum方法 + - 理解多商户配置、订单前缀匹配逻辑 + - _Requirements: 1.5_ + - [ ] 2.2 实现WechatPayConfig配置类 + - 实现微信支付配置读取 + - 实现多商户配置支持 + - 实现根据订单前缀获取商户配置 + - _Requirements: 1.5_ + +- [ ] 3. 微信支付签名服务实现 + - [ ] 3.1 查看PHP代码了解签名生成逻辑 + - 阅读server/php/app/api/controller/Pay.php中的MakeSign、ToUrlParams方法 + - 理解MD5签名算法 + - _Requirements: 1.4, 7.1, 7.2, 7.3_ + - [ ] 3.2 实现签名生成和验证方法 + - 实现MakeSign方法（参数排序、拼接、MD5加密） + - 实现VerifySign方法 + - _Requirements: 1.4, 7.1, 7.2, 7.3_ + - [ ]* 3.3 编写签名属性测试 + - **Property 1: 支付签名正确性** + - **Validates: Requirements 1.4, 7.1, 7.2** + +- [ ] 4. 微信支付统一下单服务实现 + - [ ] 4.1 查看PHP代码了解统一下单逻辑 + - 阅读server/php/app/api/controller/Pay.php中的wxCreateOrder、wxpay方法 + - 理解统一下单参数构建、XML转换、API调用逻辑 + - _Requirements: 1.1-1.5_ + - [ ] 4.2 实现WechatPayService - 统一下单 + - 实现CreatePaymentAsync方法 + - 实现XML构建和解析 + - 实现微信API调用 + - 实现支付参数返回 + - _Requirements: 1.1-1.5_ + +- [ ] 5. Checkpoint - 微信支付服务测试验证 + - 确保微信支付配置、签名、统一下单服务测试通过 + - 如有问题请询问用户 + +- [ ] 6. 支付回调服务实现 + - [ ] 6.1 查看PHP代码了解支付回调处理逻辑 + - 阅读server/php/app/api/controller/Notify.php中的order_notify方法 + - 理解签名验证、订单类型判断、状态更新逻辑 + - _Requirements: 2.1-2.9_ + - [ ] 6.2 实现PaymentNotifyService - 回调处理 + - 实现HandleWechatNotifyAsync方法 + - 实现XML解析和签名验证 + - 实现订单类型路由（一番赏、无限赏、充值、发货等） + - _Requirements: 2.1-2.9_ + - [ ]* 6.3 编写回调幂等性属性测试 + - **Property 2: 支付回调幂等性** + - **Validates: Requirements 2.8** + +- [ ] 7. 一番赏订单支付成功处理 + - [ ] 7.1 查看PHP代码了解一番赏支付成功处理逻辑 + - 阅读server/php/app/api/controller/Notify.php中的drawprize_notice方法 + - 理解订单状态更新、资产扣减、抽奖触发逻辑 + - _Requirements: 2.3, 2.6, 2.7_ + - [ ] 7.2 实现ProcessLotteryOrderAsync方法 + - 实现订单状态更新 + - 实现用户资产扣减（余额、积分、哈尼券） + - 实现优惠券状态更新 + - 调用现有抽奖服务 + - _Requirements: 2.3, 2.6, 2.7_ + +- [ ] 8. 无限赏订单支付成功处理 + - [ ] 8.1 查看PHP代码了解无限赏支付成功处理逻辑 + - 阅读server/php/app/api/controller/Notify.php中的infinite_drawprize_notice方法 + - 理解无限赏特有的处理逻辑 + - _Requirements: 2.3, 2.6, 2.7_ + - [ ] 8.2 实现ProcessInfiniteOrderAsync方法 + - 实现无限赏订单状态更新 + - 实现用户资产扣减 + - 调用现有无限赏抽奖服务 + - _Requirements: 2.3, 2.6, 2.7_ + +- [ ] 9. 充值订单支付成功处理 + - [ ] 9.1 查看PHP代码了解充值支付成功处理逻辑 + - 阅读server/php/app/api/controller/Notify.php中user_recharge相关处理 + - 理解充值金额增加逻辑 + - _Requirements: 2.4_ + - [ ] 9.2 实现ProcessRechargeOrderAsync方法 + - 实现充值订单状态更新 + - 实现用户余额增加 + - 记录支付流水 + - _Requirements: 2.4_ + +- [ ] 10. 发货运费支付成功处理 + - [ ] 10.1 查看PHP代码了解发货运费支付成功处理逻辑 + - 阅读server/php/app/api/controller/Notify.php中order_list_send相关处理 + - 理解发货记录状态更新逻辑 + - _Requirements: 2.5_ + - [ ] 10.2 实现ProcessShippingFeeOrderAsync方法 + - 实现发货记录状态更新 + - 记录支付流水 + - _Requirements: 2.5_ + +- [ ] 11. Checkpoint - 支付回调服务测试验证 + - 确保所有支付回调处理服务测试通过 + - 如有问题请询问用户 + +- [ ] 12. 资产扣减服务实现 + - [ ] 12.1 查看PHP代码了解资产扣减逻辑 + - 阅读server/php/app/common/model/User.php中的changeMoney、changeIntegral、changeMoney2方法 + - 理解资产变更记录逻辑 + - _Requirements: 3.1-5.4_ + - [ ] 12.2 实现PaymentService - 资产扣减 + - 实现DeductBalanceAsync方法 + - 实现DeductIntegralAsync方法 + - 实现DeductMoney2Async方法 + - 实现资产变更记录 + - _Requirements: 3.1-5.4_ + - [ ]* 12.3 编写资产扣减属性测试 + - **Property 4: 余额扣减正确性** + - **Validates: Requirements 3.3, 3.4** + +- [ ] 13. 支付记录服务实现 + - [ ] 13.1 查看PHP代码了解支付记录逻辑 + - 阅读server/php/app/api/controller/Notify.php中ProfitPay::insert相关代码 + - 理解支付记录字段和类型 + - _Requirements: 8.1-8.3_ + - [ ] 13.2 实现PaymentService - 支付记录 + - 实现RecordPaymentAsync方法 + - 支持不同支付类型记录 + - _Requirements: 8.1-8.3_ + - [ ]* 13.3 编写支付记录属性测试 + - **Property 5: 支付记录完整性** + - **Validates: Requirements 8.1, 8.2** + +- [ ] 14. 订单发货通知服务实现 + - [ ] 14.1 查看PHP代码了解订单发货通知逻辑 + - 阅读server/php/app/api/controller/Pay.php中的post_order方法 + - 理解微信发货通知API调用逻辑 + - _Requirements: 9.1-9.4_ + - [ ] 14.2 实现WechatPayService - 发货通知 + - 实现PostOrderShippingAsync方法 + - 实现失败重试机制 + - _Requirements: 9.1-9.4_ + +- [ ] 15. Checkpoint - 支付服务测试验证 + - 确保所有支付服务测试通过 + - 如有问题请询问用户 + +- [ ] 16. 控制器实现 - NotifyController + - [ ] 16.1 实现微信支付回调接口 POST /api/notify/order_notify + - 调用PaymentNotifyService.HandleWechatNotifyAsync + - 返回正确的XML响应 + - 更新API接口文档标记迁移状态 + - _Requirements: 2.1-2.9_ + +- [ ] 17. 控制器实现 - PayController（如需要独立支付接口） + - [ ] 17.1 实现支付接口 POST /api/pay + - 调用WechatPayService.CreatePaymentAsync + - 更新API接口文档标记迁移状态 + - _Requirements: 1.1-1.5_ + +- [ ] 18. Checkpoint - 控制器测试验证 + - 确保所有控制器接口可正常访问 + - 使用Postman或HTTP文件测试各接口 + - 如有问题请询问用户 + +- [ ] 19. API响应格式验证 + - [ ] 19.1 验证所有接口响应格式 + - 确保status、msg、data结构一致 + - 确保字段命名与PHP API一致（snake_case） + - 确保微信支付参数格式正确 + - _Requirements: 10.1-10.4_ + +- [ ] 20. 集成测试 + - [ ] 20.1 编写微信支付集成测试 + - 测试统一下单流程（模拟微信API） + - 测试签名生成和验证 + - _Requirements: 1.1-1.5, 7.1-7.4_ + - [ ] 20.2 编写支付回调集成测试 + - 测试回调处理流程 + - 测试幂等性 + - _Requirements: 2.1-2.9_ + - [ ] 20.3 编写资产扣减集成测试 + - 测试余额扣减 + - 测试积分扣减 + - 测试哈尼券扣减 + - 测试混合支付 + - _Requirements: 3.1-6.7_ + - [ ]* 20.4 编写混合支付原子性属性测试 + - **Property 3: 资产扣减原子性** + - **Validates: Requirements 6.7** + +- [ ] 21. 文档更新和最终验证 + - [ ] 21.1 更新API接口文档 + - 确认所有迁移接口都已标记 + - 记录新接口地址 + - _Requirements: 10.1-10.4_ + - [ ] 21.2 创建HTTP测试文件 + - 在HoneyBox.Api目录下创建payment-system.http测试文件 + - 包含所有支付系统相关接口的测试请求 + +- [ ] 22. Final Checkpoint - 完整功能验证 + - 确保所有测试通过 + - 确保API文档已更新 + - 确保与前端兼容性 + - 如有问题请询问用户 + +## Notes + +- Tasks marked with `*` are optional and can be skipped for faster MVP +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation +- Property tests validate universal correctness properties +- Unit tests validate specific examples and edge cases +- 每迁移完成一个接口，都需要在docs/API接口文档.md中标记迁移状态和新接口地址 +- 迁移前必须先查看PHP代码了解详细业务逻辑，确保功能一致性 +- 支付系统涉及资金安全，需要特别注意签名验证和事务处理 +- 支付回调需要确保幂等性，防止重复处理 + +## 接口迁移清单 + +| 序号 | PHP接口 | 新接口地址 | 状态 | +|------|---------|-----------|------| +| 1 | POST /api/notify/order_notify | POST /api/notify/order_notify | ⏳ | +| 2 | POST /api/pay | POST /api/pay | ⏳ | + +## 关键业务逻辑说明 + +### 支付回调订单类型 + +| attach值 | 订单类型 | 处理方法 | +|----------|---------|---------| +| user_recharge | 余额充值 | ProcessRechargeOrderAsync | +| order_yfs | 一番赏订单 | ProcessLotteryOrderAsync | +| order_lts | 擂台赏订单 | ProcessLotteryOrderAsync | +| order_zzs | 转转赏订单 | ProcessLotteryOrderAsync | +| order_flw | 福利屋订单 | ProcessLotteryOrderAsync | +| order_scs | 商城赏订单 | ProcessLotteryOrderAsync | +| order_wxs | 无限赏订单 | ProcessInfiniteOrderAsync | +| order_fbs | 翻倍赏订单 | ProcessInfiniteOrderAsync | +| order_ckj | 抽卡机订单 | ProcessCardExtractorOrderAsync | +| order_list_send | 发货运费 | ProcessShippingFeeOrderAsync | + +### 支付类型枚举 + +| PayType | 说明 | +|---------|------| +| 1 | 微信支付 | +| 2 | 余额支付 | +| 3 | 积分支付 | +| 4 | 哈尼券支付 |