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