qipai/docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md

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：分账和门店收款配置。