HaniBlindBox/.kiro/specs/payment-integration/requirements.md

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