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

2026-06-22 11:16:51 +08:00
parent 4c66e192b9
commit 3ec74bb751
8 changed files with 75 additions and 11 deletions
@@ -120,9 +120,9 @@ WSL 已验证：EMQX `5.8.9`、MQTTX CLI `1.13.0`、EMQX 服务 `active (running

 项目已开发部分模块。具体完成度不得从 README 猜测，必须以现有代码、测试、数据库迁移、Git 历史以及 `docs/current-baseline.md`、`docs/module-status.md`、`docs/feature-status.md` 为准。

- 当前执行游标：`M05-B`
- 最近工程提交：`6c506ff`，完成 M05-A 统一支付领域、服务端金额和幂等回调。
- 下一工程目标：M05-B 微信支付、退款和对账。
+- 当前执行游标：`M05-C`
+- 最近工程提交：`4c66e19`，完成 M05-B 微信支付 v3、退款、通知验签和对账基础。
+- 下一工程目标：M05-C 团购券和第三方直订。

 ## 版本递进

@@ -0,0 +1,10 @@
+# M05-B 微信支付与退款 API
+
+- `POST /app-api/pay/wechat/prepay`：为已创建的微信支付单生成 JSAPI 支付参数。
+- `GET /app-api/pay/wechat/payments/:paymentId`：主动查询微信支付状态。
+- `POST /app-api/pay/wechat/notify`：微信支付通知；使用原始请求体验签并解密。
+- `POST /app-api/pay/wechat/refund-notify`：微信退款通知；支持处理中状态推进和重复通知幂等。
+- `POST /admin-api/pay/refund`：租户管理员发起全额或部分原路退款。
+- `POST /admin-api/pay/reconciliation`：请求指定门店、日期和类型的微信交易账单。
+
+支付和退款通知不依赖登录态，但必须通过微信平台证书验签。后台退款与对账要求租户管理或平台管理权限。
@@ -1,7 +1,7 @@
 # 配置总表

 > 当前总纲：V5.4.md
-> 最后更新：2026-06-18
+> 最后更新：2026-06-22
 > 维护规则：任何配置路径、账号、密码、域名、端口或加载顺序变化，必须与 `README.md`、`V5.4.md` 和实际配置在同一提交中更新。

 ## 当前已知凭据
@@ -61,6 +61,15 @@ MYSQL_DATABASE=<以项目实际数据库名为准>

 检测结果只能使用 `PASS/WARN/FAIL`，不得回显密码。只有五项全部通过，数据库环境才可标记 `DONE`。

+## 微信支付 v3
+
+- 运行变量：`QIPAI_WECHAT_PAY_CREDENTIALS`。
+- 值为 JSON 对象，键与 `qipai_payment_configs.credential_ref` 对应；例如数据库保存 `env:WX_STORE` 时，JSON 可使用 `env:WX_STORE` 或 `WX_STORE` 作为键。
+- 每项包含 `appId`、`merchantId`、`serialNo`、`privateKeyPem`、32 字节 `apiV3Key` 和按平台证书序列号索引的 `platformCertificates`。
+- 真实值只写入 `/etc/qipai/qipai.secrets` 或本地 Git 忽略配置，权限 `600`；商户私钥、APIv3 Key 和平台证书正文不得进入 Git、日志或前端包。
+- 支付配置 `settings` 可登记 `description`、`paymentNotifyUrl`、`refundNotifyUrl`；未登记时固定回调地址为 `https://api.txyundm.cn/app-api/pay/wechat/notify` 和 `https://api.txyundm.cn/app-api/pay/wechat/refund-notify`。
+- 当前仓库未登记真实微信支付凭据；真实预支付、退款、通知和账单下载联调仍为外部阻塞。
+
 ## 配置加载优先级

 1. `/etc/qipai/qipai.secrets`
@@ -79,3 +88,4 @@ MYSQL_DATABASE=<以项目实际数据库名为准>
 - 2026-06-16：建立 V5.1 配置总表；登记 WSL EMQX Dashboard `admin/admin123`；固定 Windows、WSL 和 Ubuntu 配置路径。
 - 2026-06-18：总纲升级为 V5.3；增加持续开发执行游标与固定模块推进规则。
 - 2026-06-18：总纲升级为 V5.4；登记 WSL MySQL `root/root123` 与生产 MySQL `root/Da@Shuai!6y8c..XT`，增加 `/etc/qipai/mysql-client.cnf`、特殊字符处理和真实登录检测规则。
+- 2026-06-22：M05-B 增加 `QIPAI_WECHAT_PAY_CREDENTIALS` 凭据映射、微信支付/退款回调地址和私钥证书隔离规则。
@@ -0,0 +1,9 @@
+# M05-B 微信支付退款数据库变更
+
+- 迁移版本：`2026062216`
+- `qipai_refunds` 增加客户端幂等键、provider、退款通知键、失败码和脱敏响应。
+- 新增 `qipai_reconciliation_runs`，记录支付配置、账单日期、账单类型、状态、下载地址和请求人。
+- 退款客户端请求、退款通知和对账请求均有唯一索引。
+- 迁移支持 `up / verify / down`，并已在 WSL MySQL 8.4.9 临时库完成往返。
+
+表中不保存微信支付私钥、APIv3 Key 或证书正文。
@@ -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：团购券和第三方直订。
@@ -32,4 +32,4 @@
 | MAP-001 | 地图选店和最近门店 | M03-C/M08 | PARTIAL | `df373fa` | 已实现 AppID/tenant 隔离门店发现、城市/营业筛选、按门店时区判断营业中、后端 Haversine 距离排序；小程序支持定位和手工城市降级。 | 地图 SDK 可视化和真机定位授权尚未验收。 | M08 接入地图界面并完成真机验证。 |
 | QR-001 | 门店/房间场景码与 NFC | M03-D/M08 | PARTIAL | `d563078` | 已实现场景码生成、重建失效、撤销、扫码统计和二维码/NFC 统一页面解析；返回权限固定为空，旧码失效已在 MySQL 8.4.9 实测。 | 真实微信小程序码图片生成依赖可用 AppSecret 与真机环境。 | M08 接入微信小程序码接口并完成真机扫描验收。 |
 | WIFI-001 | 受控 Wi-Fi 凭据 | M03-D/M04 | PARTIAL | `91801fe` | 正式订单与分享令牌均执行最小权限；分享开门权限独立于查看和续费，撤销、过期或订单终态即时失效；MySQL 8.4.9 实测通过。 | 真实开门与设备权限仍需 M06 厂商适配器和硬件联调。 | M06 接入真实设备权限。 |
-| ORD-001 | 预约下单与多方式支付 | M04/M05 | PARTIAL | `6c506ff` | 已完成订单全生命周期和统一支付基础：服务端应付金额、支付尝试、回调唯一键、错误金额拒绝、重复成功回调不重复记账、分层支付配置和安全测试适配器均在 MySQL 8.4.9 实测。 | 微信真实预支付/验签/退款、余额套餐权益和团购支付尚未完成。 | M05-B 接入微信支付与退款。 |
+| ORD-001 | 预约下单与多方式支付 | M04/M05 | PARTIAL | `4c66e19` | 已完成订单全生命周期、统一支付基础和微信支付 v3 工程闭环：RSA 请求签名、JSAPI 参数签名、原始通知体验签、AES-GCM 解密、重复通知幂等、主动查单、全额/部分退款、退款状态推进和对账下载记录；Windows 全量测试及 WSL MySQL 8.4.9 往返迁移通过。 | 缺真实微信商户号、APIv3 Key、商户私钥和平台证书，尚未完成真实预支付/退款联调；团购支付尚未完成。 | M05-C 实现团购券和第三方直订；取得微信支付凭据后补真实联调。 |
@@ -3,15 +3,15 @@
 ```yaml
 execution_cursor:
  current_module: M05
-  current_stage: M05-B
+  current_stage: M05-C
  stage_status: TODO
-  last_completed_stage: M05-A
-  next_stage: M05-B
-  last_engineering_commit: 6c506ff
+  last_completed_stage: M05-B
+  next_stage: M05-C
+  last_engineering_commit: 4c66e19
  last_push_verified: true
  base_branch: main
  blocked_reason: ""
-  updated_at: 2026-06-20T14:30:45+08:00
+  updated_at: 2026-06-22T17:00:00+08:00
 ```

 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
@@ -21,7 +21,7 @@ execution_cursor:
 | M02 登录、租户、权限 | DONE | `5a300a8` | docs/devlogs/2026-06-18-M02-D-用户与员工管理.md | M02-A/B/C/D 已完成租户、身份、可撤销会话、RBAC、门店数据范围、员工管理、禁用、会话重置和审计；Windows 全量测试与 WSL MySQL 8.4.9 往返迁移通过。 |
 | M03 门店、房间、价格、营业时间 | DONE | `d563078` | docs/devlogs/2026-06-18-M03-D-场景码NFC与WiFi.md | M03-A/B/C/D 已完成门店房间、装修广告、媒体、地图选店、场景码/NFC 页面导航和受控 Wi-Fi；真实微信小程序码图片生成留待 M08 真机联调。 |
 | M04 订单、时段锁定、支付闭环 | DONE | `91801fe` | docs/devlogs/2026-06-20-M04-D-订单分享.md | M04-A/B/C/D 已完成可信定价、并发预占、订单状态机、续费取消换房、管理员调整、代下单和最小权限分享；Windows 全量回归与 WSL MySQL 8.4.9 模块回归通过。 |
-| M05 会员、余额、套餐、优惠券 | PARTIAL | `6c506ff` | docs/devlogs/2026-06-20-M05-A-统一支付领域.md | M05-A 已完成统一支付表、服务端金额、幂等支付单/回调、分层配置和安全测试适配器；下一阶段 M05-B 微信支付与退款。 |
+| M05 会员、余额、套餐、优惠券 | PARTIAL | `4c66e19` | docs/devlogs/2026-06-22-M05-B-微信支付与退款.md | M05-A/B 已完成统一支付领域、微信支付 v3 请求签名、JSAPI 预支付参数、通知验签解密、主动查单、全额/部分退款、退款通知和对账下载记录；真实商户联调受凭据阻塞，下一阶段 M05-C 团购券和第三方直订。 |
 | M06 设备、MQTT 与真实硬件联动 | TODO | - | - | - |
 | M07 保洁、通知、任务和语音播报 | TODO | - | - | - |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
@@ -10,3 +10,4 @@
 | ISSUE-006 | 2026-06-16 | V5.0/IOT-001 | WSL 本地 EMQX 服务级核验通过，但 MQTT 客户端账号用途、错误密码拒绝、ACL 越权拒绝、TLS、遗嘱和幂等尚未验证。 | 中 | 已新增本地 MQTT 基线文档、服务级检查脚本和 MQTTX CLI 冒烟入口；未配置账号时明确 SKIP。 | 当前只有服务/端口证据，缺少真实认证和协议测试结果。 | 配置 Git 忽略的本地最小权限 MQTT 账号后执行 `scripts/dev/wsl/mqtt-smoke.sh`。 | OPEN |
 | ISSUE-007 | 2026-06-18 | M00/SCM-001/M08 | 工作区曾存在未跟踪的 `miniapp/` 模板文件。 | 低 | 已检查 AppID、修复乱码、增加固定 API 配置并纳管推送。 | 小程序模板早于正式 M08 队列生成。 | M08 基于已纳管模板继续开发，不重复初始化。 | RESOLVED |
 | ISSUE-008 | 2026-06-18 | M03-D/QR-001 | 真实微信小程序码图片生成尚未联调。 | 中 | sceneCode 生命周期、重建失效、扫码统计、二维码/NFC 页面解析和测试全链路已完成。 | 缺少可用于微信接口的 AppSecret 与真机联调环境。 | M08 配置真实 AppSecret 后调用微信小程序码接口并完成真机扫描验收。 | BLOCKED_EXTERNAL |
+| ISSUE-009 | 2026-06-22 | M05-B/ORD-001 | 微信支付 v3 真实预支付、通知、退款和账单下载尚未联调。 | 高 | 已完成请求签名、JSAPI 参数、原始通知体验签、AES-GCM 解密、幂等记账、全额/部分退款、退款状态推进、人工处理失败状态和对账记录；使用生成密钥与可控传输完成协议测试。 | 缺真实商户号、APIv3 Key、商户私钥、平台证书及可用商户环境。 | 用户提供凭据后写入 `/etc/qipai/qipai.secrets`，在生产回调域名完成小额支付、重复通知、部分退款、全额退款和账单下载验收。 | BLOCKED_EXTERNAL |