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

2026-06-22 11:30:21 +08:00
parent cda640baa0
commit 52edf2482e
8 changed files with 76 additions and 10 deletions
@@ -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：分账和门店收款配置。