docs(M05-C): 记录团购直订验收并推进分账

2026-06-22 11:30:21 +08:00
parent cda640baa0
commit 52edf2482e
8 changed files with 76 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-C`
+- 当前执行游标：`M05-D`
- 最近工程提交：`4c66e19`，完成 M05-B 微信支付 v3、退款、通知验签和对账基础。
+- 最近工程提交：`cda640b`，完成 M05-C 团购验券、第三方直订和人工处理队列。
- 下一工程目标：M05-C 团购券和第三方直订。
+- 下一工程目标：M05-D 分账和门店收款配置。
 ## 版本递进
@@ -0,0 +1,11 @@
 # M05-C 团购与第三方直订 API
 - `POST /app-api/group-vouchers/redeem`：顾客团购券核销。
 - `POST /admin-api/group-vouchers/redeem-manual`：管理员人工验券。
 - `POST /app-api/third-party/:provider/tenants/:tenantId/bookings/notify`：第三方直订回调。
 - `POST /app-api/third-party/bookings/:bookingId/claim`：顾客认领已映射直订。
 - `GET /admin-api/third-party/records`：查询验券和直订记录。
 - `PUT /admin-api/third-party/config`：配置平台模式、环境凭据引用和接口设置。
 - `PUT /admin-api/third-party/mappings`：维护外部门店/房间映射。
 回调必须携带 HMAC 签名；券码不在响应和列表中回显明文。
@@ -70,6 +70,15 @@ MYSQL_DATABASE=<以项目实际数据库名为准>
 - 支付配置 `settings` 可登记 `description`、`paymentNotifyUrl`、`refundNotifyUrl`；未登记时固定回调地址为 `https://api.txyundm.cn/app-api/pay/wechat/notify` 和 `https://api.txyundm.cn/app-api/pay/wechat/refund-notify`。
 - 当前仓库未登记真实微信支付凭据；真实预支付、退款、通知和账单下载联调仍为外部阻塞。
 ## 团购与第三方平台
 - 运行变量：`QIPAI_THIRD_PARTY_CREDENTIALS`。
 - 值为 JSON 对象，键与 `qipai_third_party_configs.credential_ref` 对应；每项可包含 `webhookSecret` 和 `apiToken`。
 - 数据库配置支持 `MANUAL`、`MOCK`、`API` 三种模式；生产接入真实平台时必须使用 `API`，测试环境可使用 `MOCK`。
 - `credential_ref` 只允许 `env:` 引用；真实 Token 和回调密钥只写入 `/etc/qipai/qipai.secrets` 或 Git 忽略的本地配置。
 - 直订回调当前统一使用 `X-Third-Party-Signature` HMAC-SHA256 入口；取得真实平台授权后由专用适配器按厂商协议替换，不得降低验签要求。
 - 券码只保存 SHA-256 和脱敏显示值，不得写入日志、回调摘要或后台列表。
 ## 配置加载优先级
 1. `/etc/qipai/qipai.secrets`
@@ -89,3 +98,4 @@ MYSQL_DATABASE=<以项目实际数据库名为准>
 - 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` 凭据映射、微信支付/退款回调地址和私钥证书隔离规则。
 - 2026-06-22：M05-C 增加 `QIPAI_THIRD_PARTY_CREDENTIALS`、人工/Mock/API 模式、回调 HMAC 和券码哈希规则。
@@ -0,0 +1,8 @@
 # M05-C 团购与第三方直订数据库变更
 - 迁移版本：`2026062217`
 - 新增 `qipai_third_party_configs` 和 `qipai_third_party_mappings`。
 - 新增 `qipai_group_vouchers`、`qipai_group_redemptions`。
 - 新增 `qipai_direct_bookings`，保存映射、待处理、认领和订单关联状态。
 - 券码只保存 SHA-256 与脱敏值；回调客户引用只保存 SHA-256。
 - 核销请求、券、直订事件和外部预订号均有唯一约束。
@@ -0,0 +1,33 @@
 # M05-C 团购券和第三方直订
 - 日期：2026-06-22
 - 起始 commit：`3ec74bb`
 - 工程 commit：`cda640b`
 - ENGINEERING_DELTA=YES
 - 子阶段状态：DONE，工程 commit 已 push 且 `HEAD == origin/main`
 ## 工程增量
 - 建立美团/点评、抖音和快手可扩展的第三方适配器，支持 `MANUAL / MOCK / API`。
 - 顾客可提交团购券，管理员可人工核销；API 模式只从环境引用读取 Token。
 - 券码仅保存 SHA-256 和脱敏值，clientRequestId 与 voucher 双唯一约束阻止重复记账。
 - 成功核销在事务内生成 GROUP_BUY 支付、更新订单金额/状态、消费预占并写状态历史。
 - 第三方直订回调使用 HMAC-SHA256 验证，eventId 和 bookingNo 均幂等。
 - 外部门店/房间映射成功后进入 `READY_TO_CLAIM`，缺映射进入 `PENDING_MAPPING` 人工队列。
 - 顾客认领后复用可信定价与并发预占，生成已支付订单；认领冲突会释放新建预占。
 - 增加后台第三方配置、映射和验券/直订记录查询 API。
 ## 验证
 - Windows 后端全量测试和仓库门禁通过。
 - WSL MySQL 8.4.9 临时库完成 `up → verify → down → up → verify`。
 - 迁移语句：up 84、verify 61、down 78。
 - 实测券码不落明文、同券只核销一次、重复事件幂等、映射成功可认领成 PAID 订单、映射失败进入人工队列。
 ## 外部阻塞
 缺美团/点评、抖音等平台授权和正式签名协议，真实核销与直订回调标记 `BLOCKED_EXTERNAL`；人工与 Mock 闭环可用于开发验收。
 ## 后续
 执行游标推进到 M05-D：分账和门店收款配置。
@@ -32,4 +32,7 @@
 | 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 | `4c66e19` | 已完成订单全生命周期、统一支付基础和微信支付 v3 工程闭环：RSA 请求签名、JSAPI 参数签名、原始通知体验签、AES-GCM 解密、重复通知幂等、主动查单、全额/部分退款、退款状态推进和对账下载记录；Windows 全量测试及 WSL MySQL 8.4.9 往返迁移通过。 | 缺真实微信商户号、APIv3 Key、商户私钥和平台证书，尚未完成真实预支付/退款联调；团购支付尚未完成。 | M05-C 实现团购券和第三方直订；取得微信支付凭据后补真实联调。 |
+| ORD-001 | 预约下单与多方式支付 | M04/M05 | PARTIAL | `cda640b` | 已完成订单全生命周期、微信支付 v3 工程闭环和团购支付：团购券核销与直订认领均生成统一支付记录并事务化推进订单；Windows 全量测试及 WSL MySQL 8.4.9 往返迁移通过。 | 缺真实微信和团购平台授权联调；余额/套餐支付属于 M07。 | M05-D 完成分账与收款配置；取得平台凭据后补真实联调。 |
 | 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 模式。 |
@@ -3,15 +3,15 @@
 ```yaml
 execution_cursor:
  current_module: M05
-  current_stage: M05-C
+  current_stage: M05-D
  stage_status: TODO
-  last_completed_stage: M05-B
+  last_completed_stage: M05-C
-  next_stage: M05-C
+  next_stage: M05-D
-  last_engineering_commit: 4c66e19
+  last_engineering_commit: cda640b
  last_push_verified: true
  base_branch: main
  blocked_reason: ""
-  updated_at: 2026-06-22T17:00:00+08:00
+  updated_at: 2026-06-22T18: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 | `4c66e19` | docs/devlogs/2026-06-22-M05-B-微信支付与退款.md | M05-A/B 已完成统一支付领域、微信支付 v3 请求签名、JSAPI 预支付参数、通知验签解密、主动查单、全额/部分退款、退款通知和对账下载记录；真实商户联调受凭据阻塞，下一阶段 M05-C 团购券和第三方直订。 |
+| M05 会员、余额、套餐、优惠券 | PARTIAL | `cda640b` | docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md | M05-A/B/C 已完成统一支付、微信支付退款、团购券核销和第三方直订：支持人工/Mock/API 适配器、券码哈希脱敏、重复核销幂等、HMAC 回调、门店房间映射、待处理队列及顾客认领成已支付订单；真实平台授权仍受阻，下一阶段 M05-D 分账和收款配置。 |
 | M06 设备、MQTT 与真实硬件联动 | TODO | - | - | - |
 | M07 保洁、通知、任务和语音播报 | TODO | - | - | - |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
@@ -11,3 +11,4 @@
 | 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 |
 | ISSUE-010 | 2026-06-22 | M05-C/GRP-001/GRP-002 | 美团/点评、抖音等团购核销与直订未完成真实平台联调。 | 高 | 已完成统一适配器、人工/Mock/API 核销、券码哈希、重复核销幂等、HMAC 回调、映射、人工队列和认领成单；后台配置与记录 API 已具备。 | 缺平台商家授权、Token、正式签名协议和回调测试环境。 | 获取授权后新增厂商专用适配器并执行验券、重复推送、取消和异常重试验收。 | BLOCKED_EXTERNAL |