docs(M05-B): 记录微信支付验收并推进团购

2026-06-22 11:16:51 +08:00
parent 4c66e192b9
commit 3ec74bb751
8 changed files with 75 additions and 11 deletions
@@ -0,0 +1,34 @@
+# M05-B 微信支付与退款
+
+- 日期：2026-06-22
+- 起始 commit：`dea2ee5`
+- 工程 commit：`4c66e19`
+- ENGINEERING_DELTA=YES
+- 子阶段状态：DONE，工程 commit 已 push 且 `HEAD == origin/main`
+
+## 工程增量
+
+- 实现微信支付 v3 RSA-SHA256 请求签名、JSAPI `requestPayment` 参数签名和可注入 HTTP 传输。
+- 支持微信预支付、主动查单、全额/部分退款和交易账单下载请求。
+- 支付与退款通知保留原始请求体，按平台证书验签后使用 APIv3 Key 执行 AES-256-GCM 解密。
+- 支付通知以 provider/callbackId 幂等；成功后在事务内更新支付单、订单已付金额、订单状态历史和房间预占。
+- 退款使用 clientRequestId 幂等并校验剩余可退金额；PROCESSING 可推进到 SUCCESS，成功后不可被旧通知回退。
+- 外部退款调用失败进入 `MANUAL_REVIEW`，不把订单伪造为已退款。
+- 新增退款回调字段和 `qipai_reconciliation_runs`，记录账单日期、类型、下载状态和请求人。
+- 真实私钥、APIv3 Key 与证书只从环境凭据映射加载，不进入数据库、日志、Git 或前端。
+
+## 验证
+
+- Windows：`npm test` 全量通过。
+- 协议测试：生成 RSA 密钥与 AES-GCM 通知，验证请求签名、JSAPI 参数、验签解密、篡改拒绝、查单、退款和账单请求。
+- 仓库门禁：完整性、敏感信息、空白和大文件检查通过；既有参考 xjar 大文件仅保留已登记 WARN。
+- WSL MySQL 8.4.9 临时库：`up → verify → down → up → verify` 通过。
+- 迁移语句：up 78、verify 58、down 72。
+
+## 外部阻塞
+
+缺真实微信商户号、APIv3 Key、商户私钥和平台证书，尚未执行真实小额支付、回调、部分退款、全额退款和账单下载。工程可独立部分已完成，阻塞登记在 `docs/unresolved-issues.md`。
+
+## 后续
+
+执行游标推进到 M05-C：团购券和第三方直订。