From 52edf2482e06899916436b822175be596920a41b Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 22 Jun 2026 11:30:21 +0800 Subject: [PATCH] =?UTF-8?q?docs(M05-C):=20=E8=AE=B0=E5=BD=95=E5=9B=A2?= =?UTF-8?q?=E8=B4=AD=E7=9B=B4=E8=AE=A2=E9=AA=8C=E6=94=B6=E5=B9=B6=E6=8E=A8?= =?UTF-8?q?=E8=BF=9B=E5=88=86=E8=B4=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 ++-- .../2026-06-22-M05-C-third-party.md | 11 +++++++ docs/configuration.md | 10 ++++++ .../2026-06-22-M05-C-third-party.md | 8 +++++ .../2026-06-22-M05-C-团购与第三方直订.md | 33 +++++++++++++++++++ docs/feature-status.md | 5 ++- docs/module-status.md | 12 +++---- docs/unresolved-issues.md | 1 + 8 files changed, 76 insertions(+), 10 deletions(-) create mode 100644 docs/api-changelog/2026-06-22-M05-C-third-party.md create mode 100644 docs/db-changelog/2026-06-22-M05-C-third-party.md create mode 100644 docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md diff --git a/README.md b/README.md index 103a7fc..41ce490 100644 --- a/README.md +++ b/README.md @@ -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` -- 最近工程提交：`4c66e19`，完成 M05-B 微信支付 v3、退款、通知验签和对账基础。 -- 下一工程目标：M05-C 团购券和第三方直订。 +- 当前执行游标：`M05-D` +- 最近工程提交：`cda640b`，完成 M05-C 团购验券、第三方直订和人工处理队列。 +- 下一工程目标：M05-D 分账和门店收款配置。 ## 版本递进 diff --git a/docs/api-changelog/2026-06-22-M05-C-third-party.md b/docs/api-changelog/2026-06-22-M05-C-third-party.md new file mode 100644 index 0000000..dc8eca1 --- /dev/null +++ b/docs/api-changelog/2026-06-22-M05-C-third-party.md @@ -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 签名；券码不在响应和列表中回显明文。 diff --git a/docs/configuration.md b/docs/configuration.md index 0e12ab0..4a20bf9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 和券码哈希规则。 diff --git a/docs/db-changelog/2026-06-22-M05-C-third-party.md b/docs/db-changelog/2026-06-22-M05-C-third-party.md new file mode 100644 index 0000000..e520d25 --- /dev/null +++ b/docs/db-changelog/2026-06-22-M05-C-third-party.md @@ -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。 +- 核销请求、券、直订事件和外部预订号均有唯一约束。 diff --git a/docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md b/docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md new file mode 100644 index 0000000..beaa28a --- /dev/null +++ b/docs/devlogs/2026-06-22-M05-C-团购与第三方直订.md @@ -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：分账和门店收款配置。 diff --git a/docs/feature-status.md b/docs/feature-status.md index 495dd15..fc32162 100644 --- a/docs/feature-status.md +++ b/docs/feature-status.md @@ -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 模式。 | diff --git a/docs/module-status.md b/docs/module-status.md index 7c7ee1c..b795353 100644 --- a/docs/module-status.md +++ b/docs/module-status.md @@ -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 - next_stage: M05-C - last_engineering_commit: 4c66e19 + last_completed_stage: M05-C + next_stage: M05-D + 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 | - | - | - | diff --git a/docs/unresolved-issues.md b/docs/unresolved-issues.md index e574f81..0796ce1 100644 --- a/docs/unresolved-issues.md +++ b/docs/unresolved-issues.md @@ -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 |