102 lines
5.8 KiB
Markdown
102 lines
5.8 KiB
Markdown
# Requirements Document
|
||
|
||
## Introduction
|
||
|
||
将现有的微信支付从 V2 版本升级到 V3 版本，以支持更安全的 RSA-SHA256 签名和 AES-GCM 加密。当前系统使用 V2 版本（XML格式、MD5签名），需要升级到 V3 版本（JSON格式、RSA-SHA256签名）以满足微信支付的最新安全要求。
|
||
|
||
## Glossary
|
||
|
||
- **WechatPay_V2**: 微信支付 V2 版本，使用 XML 数据格式和 MD5 签名算法
|
||
- **WechatPay_V3**: 微信支付 V3 版本，使用 JSON 数据格式和 RSA-SHA256 签名算法
|
||
- **APIv3_Key**: 微信支付 V3 版本的 API 密钥，用于 AES-GCM 解密回调通知
|
||
- **Merchant_Private_Key**: 商户 API 私钥，用于请求签名
|
||
- **Wechat_Public_Key**: 微信支付平台公钥，用于验证回调签名
|
||
- **JSAPI_Payment**: 小程序/公众号内支付方式
|
||
- **Payment_Callback**: 微信支付结果异步通知
|
||
- **Config_System**: 后台配置管理系统，存储支付参数到数据库
|
||
|
||
## Requirements
|
||
|
||
### Requirement 1: V3 配置模型扩展
|
||
|
||
**User Story:** As a 开发者, I want 后端配置模型支持 V3 字段, so that 系统能够存储和读取 V3 支付配置。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 系统加载微信支付配置 THEN THE Config_System SHALL 支持读取 PayVersion 字段（值为 "V2" 或 "V3"）
|
||
2. WHEN PayVersion 为 "V3" THEN THE Config_System SHALL 读取以下字段：ApiV3Key、CertSerialNo、PrivateKeyPath、WechatPublicKeyId、WechatPublicKeyPath
|
||
3. WHEN PayVersion 为 "V2" THEN THE Config_System SHALL 保持原有字段兼容（ApiKey）
|
||
4. WHEN 配置保存时 THEN THE Config_System SHALL 正确序列化 V3 字段到 JSON 格式
|
||
5. WHEN 配置加载时 THEN THE Config_System SHALL 正确反序列化 V3 字段
|
||
|
||
### Requirement 2: 后台管理页面配置
|
||
|
||
**User Story:** As a 系统管理员, I want 在后台管理页面配置微信支付 V3 参数, so that 系统能够使用 V3 接口进行支付。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 管理员打开微信支付配置页面 THEN THE Admin_System SHALL 显示「支付版本」选择项（V2/V3）
|
||
2. WHEN 管理员选择 V3 版本 THEN THE Admin_System SHALL 显示 V3 专属配置项：APIv3密钥、证书序列号、商户私钥路径、微信支付公钥ID、微信支付公钥路径
|
||
3. WHEN 管理员选择 V2 版本 THEN THE Admin_System SHALL 隐藏 V3 配置项并显示 V2 配置项
|
||
4. WHEN 管理员保存配置 THEN THE Admin_System SHALL 验证必填字段并保存到数据库
|
||
5. WHEN 页面加载时 THEN THE Admin_System SHALL 正确回显已保存的配置值
|
||
|
||
### Requirement 3: V3 JSAPI 下单接口
|
||
|
||
**User Story:** As a 小程序用户, I want 使用 V3 接口发起支付, so that 完成商品购买。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 用户发起支付请求且商户配置为 V3 THEN THE WechatPay_V3 SHALL 调用 V3 JSAPI 下单接口
|
||
2. WHEN 构建 V3 请求 THEN THE WechatPay_V3 SHALL 使用 JSON 格式并包含：appid、mchid、description、out_trade_no、notify_url、amount、payer
|
||
3. WHEN 签名 V3 请求 THEN THE WechatPay_V3 SHALL 使用 RSA-SHA256 算法对请求进行签名
|
||
4. WHEN 下单成功 THEN THE WechatPay_V3 SHALL 返回小程序调起支付所需参数：timeStamp、nonceStr、package、signType(RSA)、paySign
|
||
5. WHEN 商户配置为 V2 THEN THE WechatPay_V3 SHALL 回退到 V2 接口处理
|
||
|
||
### Requirement 4: V3 支付回调处理
|
||
|
||
**User Story:** As a 系统, I want 正确解密 V3 支付回调通知, so that 更新订单支付状态。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 收到 V3 格式回调（JSON格式且包含 resource 字段）THEN THE Payment_Callback SHALL 使用 V3 解密流程
|
||
2. WHEN 验证 V3 回调签名 THEN THE Payment_Callback SHALL 使用微信支付公钥验证 Wechatpay-Signature 头
|
||
3. WHEN 解密 V3 回调数据 THEN THE Payment_Callback SHALL 使用 AES-256-GCM 算法和 APIv3 密钥解密 resource.ciphertext
|
||
4. WHEN 解密成功 THEN THE Payment_Callback SHALL 提取订单号和支付状态并更新订单
|
||
5. WHEN 收到 V2 格式回调（XML格式）THEN THE Payment_Callback SHALL 使用 V2 解密流程
|
||
6. WHEN 回调处理成功 THEN THE Payment_Callback SHALL 返回正确的响应格式（V3: JSON, V2: XML）
|
||
|
||
### Requirement 5: V3 订单查询
|
||
|
||
**User Story:** As a 系统, I want 使用 V3 接口查询订单状态, so that 处理支付超时和异常情况。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 查询订单且商户配置为 V3 THEN THE WechatPay_V3 SHALL 调用 V3 订单查询接口
|
||
2. WHEN 构建查询请求 THEN THE WechatPay_V3 SHALL 使用商户订单号作为路径参数
|
||
3. WHEN 查询成功 THEN THE WechatPay_V3 SHALL 解析返回的订单状态（SUCCESS、NOTPAY、CLOSED 等）
|
||
4. IF 查询失败 THEN THE WechatPay_V3 SHALL 返回错误信息并记录日志
|
||
|
||
### Requirement 6: V3 订单关闭
|
||
|
||
**User Story:** As a 系统, I want 使用 V3 接口关闭未支付订单, so that 释放库存和资源。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 关闭订单且商户配置为 V3 THEN THE WechatPay_V3 SHALL 调用 V3 订单关闭接口
|
||
2. WHEN 构建关闭请求 THEN THE WechatPay_V3 SHALL 使用商户订单号作为路径参数并包含 mchid
|
||
3. WHEN 关闭成功 THEN THE WechatPay_V3 SHALL 返回成功状态（HTTP 204）
|
||
4. IF 关闭失败 THEN THE WechatPay_V3 SHALL 返回错误信息并记录日志
|
||
|
||
### Requirement 7: V3 退款接口
|
||
|
||
**User Story:** As a 系统管理员, I want 使用 V3 接口发起退款, so that 处理用户退款请求。
|
||
|
||
#### Acceptance Criteria
|
||
|
||
1. WHEN 发起退款且商户配置为 V3 THEN THE WechatPay_V3 SHALL 调用 V3 退款接口
|
||
2. WHEN 构建退款请求 THEN THE WechatPay_V3 SHALL 包含：out_trade_no、out_refund_no、reason、notify_url、amount
|
||
3. WHEN 退款成功 THEN THE WechatPay_V3 SHALL 返回退款单号和状态
|
||
4. THE WechatPay_V3 SHALL 支持部分退款（退款金额小于订单金额）
|
||
5. IF 退款失败 THEN THE WechatPay_V3 SHALL 返回错误信息并记录日志
|