docs(M05-D): 完成支付模块回归并推进设备

2026-06-22 11:51:02 +08:00
parent 1680d734bf
commit a8c3e7d2fe
8 changed files with 66 additions and 10 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-D`
- 最近工程提交：`cda640b`，完成 M05-C 团购验券、第三方直订和人工处理队列。
- 下一工程目标：M05-D 分账和门店收款配置。
+- 当前执行游标：`M06-A`
+- 最近工程提交：`1680d73`，完成 M05-D 收款账户、接收方、比例策略和幂等分账。
+- 下一工程目标：M06-A Broker 与 MQTT 基础。

 ## 版本递进

@@ -0,0 +1,9 @@
+# M05-D 分账与收款配置 API
+
+- `PUT /admin-api/pay/collection-account`：维护租户/门店收款账户和授权状态。
+- `PUT /admin-api/pay/profit-share-receiver`：维护脱敏分账接收方及环境引用。
+- `PUT /admin-api/pay/profit-share-policy`：维护全局或门店比例策略。
+- `POST /admin-api/pay/profit-shares`：对成功微信支付发起幂等分账。
+- `GET /admin-api/pay/profit-shares`：查询账户、接收方、策略和分账记录。
+
+以上接口只允许租户管理员或平台管理员调用。
@@ -69,6 +69,9 @@ MYSQL_DATABASE=<以项目实际数据库名为准>
 - 真实值只写入 `/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`。
 - 当前仓库未登记真实微信支付凭据；真实预支付、退款、通知和账单下载联调仍为外部阻塞。
+- `profitShareReceivers` 可在每个微信凭据项中按 `receiver:*` 引用登记真实分账接收方账号；数据库仅保存该引用、SHA-256 和脱敏值。
+- `QIPAI_PROFIT_SHARE_MOCK_ENABLED=true` 仅允许非生产测试环境启用；生产环境始终强制关闭。
+- 收款账户只有 `authorizationStatus=AUTHORIZED` 时才能开启分账；接收方也必须单独标记授权。

 ## 团购与第三方平台

@@ -99,3 +102,4 @@ MYSQL_DATABASE=<以项目实际数据库名为准>
 - 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` 凭据映射、微信支付/退款回调地址和私钥证书隔离规则。
 - 2026-06-22：M05-C 增加 `QIPAI_THIRD_PARTY_CREDENTIALS`、人工/Mock/API 模式、回调 HMAC 和券码哈希规则。
+- 2026-06-22：M05-D 增加门店收款账户、`profitShareReceivers` 环境映射、分账授权状态和非生产 Mock 门禁。
@@ -0,0 +1,7 @@
+# M05-D 分账与收款配置数据库变更
+
+- 迁移版本：`2026062218`
+- 新增 `qipai_collection_accounts`、`qipai_profit_share_receivers`、`qipai_profit_share_policies`。
+- 扩展 `qipai_profit_shares`：账户、接收方、批次/单项幂等键、比例、失败码和脱敏响应。
+- 收款账户和全局/门店策略使用显式 scope key，避免 NULL 唯一索引绕过。
+- 接收方真实账号不入库，只保存 SHA-256、脱敏值和环境引用。
@@ -0,0 +1,33 @@
+# M05-D 分账和门店收款配置
+
+- 日期：2026-06-22
+- 起始 commit：`52edf24`
+- 工程 commit：`1680d73`
+- ENGINEERING_DELTA=YES
+- 子阶段状态：DONE，工程 commit 已 push 且 `HEAD == origin/main`
+
+## 工程增量
+
+- 支持按租户、小程序和门店配置微信收款商户号、环境凭据引用、启用状态与分账授权状态。
+- 分账接收方只保存 SHA-256、脱敏值和 `receiver:*` 环境引用。
+- 支持全局/门店比例策略，同一范围比例总和不得超过 10000 bps。
+- 只有成功且具有微信交易号的支付允许分账；未授权账户或接收方被拒绝。
+- 分账批次使用 clientRequestId 幂等，每个支付/接收方有唯一约束。
+- 接入微信支付 v3 `/v3/profitsharing/orders` 请求签名；API 失败记录 `MANUAL_REVIEW`，不伪造成功。
+- Mock 分账仅非生产显式开启后可用，生产环境强制关闭。
+- 后台 API 可维护账户、接收方、策略并查询账户、策略、脱敏接收方与分账明细。
+
+## 验证
+
+- Windows 全量测试及仓库门禁通过。
+- WSL MySQL 8.4.9 临时库执行 `up → verify → down → up → verify` 通过。
+- 迁移语句：up 89、verify 65、down 83。
+- 实测未授权开启被拒绝、比例超限被拒绝、接收方不落明文、两接收方金额正确、重复批次不重复分账。
+
+## 外部阻塞
+
+缺微信支付服务商/分账权限和已授权接收方，真实分账标记 `BLOCKED_EXTERNAL`。
+
+## 模块回归与后续
+
+M05-A/B/C/D Windows 全量回归与 WSL MySQL 全迁移往返通过。执行游标进入 M06-A：Broker 与 MQTT 基础。
@@ -36,3 +36,5 @@
 | GRP-001 | 团购券兑换 | M05-C | PARTIAL | `cda640b` | 已实现美团/点评、抖音、快手统一适配器，支持顾客粘贴/扫码值、管理员人工核销、Mock/API 核销、clientRequestId 幂等和券码 SHA-256 存储；重复券不能再次记账，WSL MySQL 8.4.9 实测通过。 | 缺各平台商家 API 授权，未执行真实厂商核销。 | 取得授权后配置 API endpoint/token 并执行真实验券。 |
 | GRP-002 | 美团直订 | M05-C | PARTIAL | `cda640b` | 已实现 HMAC 回调、事件幂等、外部门店/房间映射、未映射人工队列、顾客认领和团购支付订单生成；映射成功订单可进入 PAID。 | 缺美团开放平台授权和真实回调协议确认。 | 取得授权后按厂商协议实现专用签名适配并联调。 |
 | GRP-003 | 管理员验券 | M05-C/M08 | PARTIAL | `cda640b` | 已提供后台人工验券、配置、映射和记录查询 API，门店数据范围校验生效，券码列表只返回脱敏值。 | 管理员小程序扫码界面待 M08，真实平台核销待授权。 | M08 接入扫码界面；授权后切换 API 模式。 |
+| FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `1680d73` | 已实现租户/门店收款账户、商户号、环境凭据引用、分账授权状态、接收方哈希脱敏、比例总和校验、支付后幂等分账和明细查询；未授权不能开启，生产环境 Mock 强制关闭。 | 缺微信支付服务商和分账权限，尚未执行真实分账。 | M10/M08 补加盟流程与界面；取得权限后执行真实分账与对账。 |
+| BKG-007 | 后台微信支付配置 | M05-D/M08 | PARTIAL | `1680d73` | 已提供收款账户、分账接收方、门店/全局比例策略和授权状态 API；私钥、APIv3 Key 和接收方真实标识只使用环境引用，查询仅返回脱敏信息。 | Vue 后台页面待 M08；真实商户与服务商授权未提供。 | M08 接入响应式配置页面；授权后完成生产验收。 |
@@ -2,16 +2,16 @@

 ```yaml
 execution_cursor:
-  current_module: M05
-  current_stage: M05-D
+  current_module: M06
+  current_stage: M06-A
  stage_status: TODO
-  last_completed_stage: M05-C
-  next_stage: M05-D
-  last_engineering_commit: cda640b
+  last_completed_stage: M05-D
+  next_stage: M06-A
+  last_engineering_commit: 1680d73
  last_push_verified: true
  base_branch: main
  blocked_reason: ""
-  updated_at: 2026-06-22T18:30:00+08:00
+  updated_at: 2026-06-22T19:30: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 | `cda640b` | docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md | M05-A/B/C 已完成统一支付、微信支付退款、团购券核销和第三方直订：支持人工/Mock/API 适配器、券码哈希脱敏、重复核销幂等、HMAC 回调、门店房间映射、待处理队列及顾客认领成已支付订单；真实平台授权仍受阻，下一阶段 M05-D 分账和收款配置。 |
+| M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 |
 | M06 设备、MQTT 与真实硬件联动 | TODO | - | - | - |
 | M07 保洁、通知、任务和语音播报 | TODO | - | - | - |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
@@ -12,3 +12,4 @@
 | 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 |
 | ISSUE-010 | 2026-06-22 | M05-C/GRP-001/GRP-002 | 美团/点评、抖音等团购核销与直订未完成真实平台联调。 | 高 | 已完成统一适配器、人工/Mock/API 核销、券码哈希、重复核销幂等、HMAC 回调、映射、人工队列和认领成单；后台配置与记录 API 已具备。 | 缺平台商家授权、Token、正式签名协议和回调测试环境。 | 获取授权后新增厂商专用适配器并执行验券、重复推送、取消和异常重试验收。 | BLOCKED_EXTERNAL |
+| ISSUE-011 | 2026-06-22 | M05-D/FRN-001 | 微信支付真实分账尚未联调。 | 高 | 已完成收款账户、接收方、比例策略、授权门禁、成功支付校验、API 请求签名、幂等批次、失败人工处理和查询；Mock 仅限非生产。 | 缺微信支付服务商/分账权限、已授权接收方和生产商户凭据。 | 取得权限后登记环境接收方映射，执行小额支付后多接收方分账、重复请求和失败对账验收。 | BLOCKED_EXTERNAL |