docs(M07-C): 记录权益核销验收并推进会员管理

2026-06-24 15:46:43 +08:00
parent 4ae9296f83
commit 239ef4dcf1
6 changed files with 69 additions and 15 deletions
@@ -1,8 +1,8 @@
 # 当前开发成果基线

 > V5.0 首次核验日期：2026-06-16  
-> audited_commit: `d9743d3`
-> next_engineering_target: M07-C 优惠券和套餐
+> audited_commit: `4ae9296`
+> next_engineering_target: M07-D 会员管理
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。

 ## 总体结论
@@ -35,6 +35,6 @@

 ## 下一步

-1. 进入 M07-C：实现优惠券和套餐权益定义、发放、核销与余额/订单联动。
-2. 继续复用 M07-A 钱包流水和 M07-B 充值入账幂等能力，所有权益扣减必须由服务端事务控制。
+1. 进入 M07-D：实现会员画像、注册/最近下单、订单数、消费额、余额、券、套餐和状态聚合。
+2. 继续复用 M07-A 钱包流水、M07-B 充值入账和 M07-C 权益核销状态，会员管理只输出服务端可信聚合。
 3. M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线。
@@ -0,0 +1,25 @@
+# M07-C benefits
+
+- 工程 commit：`4ae9296`
+- 迁移文件：
+  - `database/migrations/2026062423_m07c_benefits.up.sql`
+  - `database/migrations/2026062423_m07c_benefits.down.sql`
+  - `database/migrations/2026062423_m07c_benefits.verify.sql`
+
+## 新增表
+
+- `qipai_coupon_templates`：优惠券模板，包含券类型、满减金额、时长、最低消费、门店/房型/房间/星期/节假日适用范围、有效期和使用次数。
+- `qipai_coupon_grants`：用户持券，记录券码、有效期、剩余次数、冻结订单和使用状态。
+- `qipai_package_plans`：套餐计划，记录售价、总时长、总金额和适用范围。
+- `qipai_package_holdings`：用户持有套餐，记录剩余时长/金额、冻结订单、有效期和状态。
+- `qipai_benefit_usages`：订单权益核销流水，记录优惠券或套餐对订单的冻结、确认和退回。
+
+## 约束与索引
+
+- `uq_qipai_coupon_grant_code (tenant_id, coupon_code)` 保证券码租户内唯一。
+- `uq_qipai_benefit_usage_request (tenant_id, user_id, client_request_id)` 保证客户端重复请求幂等。
+- `uq_qipai_benefit_usage_order_benefit (tenant_id, order_id, benefit_type, benefit_id)` 防止同一订单重复冻结同一权益。
+
+## 回滚
+
+down 迁移按依赖顺序删除权益核销流水、套餐持有、套餐计划、持券和优惠券模板，并移除 `2026062423` 迁移记录。
@@ -0,0 +1,28 @@
+# M07-C 优惠券和套餐
+
+- 日期：2026-06-24
+- 起始 commit：`ba99beb`
+- 工程 commit：`4ae9296`
+- ENGINEERING_DELTA=YES
+- 子阶段状态：DONE
+
+## 工程增量
+
+- 新增优惠券模板和持券表，支持满减券、时长券、适用门店/房型/房间/星期/节假日、有效期和使用次数。
+- 新增套餐计划和用户套餐持有表，支持购买后持有、剩余时长/金额、冻结、核销、退回和过期状态建模。
+- 新增 `qipai_benefit_usages`，用订单、权益和 clientRequestId 双幂等约束记录权益冻结/确认/退回。
+- 新增 `MarketingBenefitService`，为订单提交提供权益冻结、确认核销和失败退回的可靠补偿流程。
+- 迁移计划、迁移契约、迁移 runner 和全量测试链路已接入 M07-C。
+
+## 验证
+
+- Windows `npm run build`：退出码 0。
+- Windows `node tests/marketing-benefit-service.test.mjs`：退出码 0。
+- Windows `node tests/migration-contract.test.mjs`：退出码 0。
+- Windows `node tests/migration-runner.test.mjs`：退出码 0。
+- Windows `npm test`：退出码 0，M01-A 至 M07-C 全量后端回归通过。
+- 工程 commit 已 push，`HEAD == origin/main == 4ae9296`。
+
+## 后续
+
+游标进入 M07-D 会员管理：聚合会员画像、注册/最近下单、订单数、消费额、余额、券、套餐和状态。
@@ -33,9 +33,10 @@
 | 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 | `cda640b` | 已完成订单全生命周期、微信支付 v3 工程闭环和团购支付：团购券核销与直订认领均生成统一支付记录并事务化推进订单；Windows 全量测试及 WSL MySQL 8.4.9 往返迁移通过。 | 缺真实微信和团购平台授权联调；余额/套餐支付属于 M07。 | M05-D 完成分账与收款配置；取得平台凭据后补真实联调。 |
-| WAL-001 | 充值优惠 | M07-B | PARTIAL | `d9743d3` | 已建立充值规则和充值订单表，支持有效期、适用门店、限购、启停、clientRequestId 幂等；支付成功后调用钱包入账，重复支付回调不重复充值；Windows 全量后端回归通过。 | 真实微信充值支付回调仍需 M05 生产凭据和 M08 前端入口联调。 | M07-C 接入优惠券和套餐权益，M08 增加充值页面和账单查询。 |
-| WAL-002 | 门店独立会员余额 | M07-A | DONE | `63711ad` | 已建立租户/门店余额范围策略、现金/赠送双余额账户和不可变流水；充值、赠送、消费、退款、人工调整均预留 entry type；消费按赠送后现金扣款，业务号幂等，余额不足拒绝；Windows 全量后端回归通过。 | - | M07-B 已接入充值规则和支付成功入账；继续 M07-C 权益消费联动。 |
-| WAL-003 | 余额账单 | M07-A/M08 | PARTIAL | `d9743d3` | 账单底表已包含业务类型、业务号、现金/赠送变动、变动后余额、操作人、trace 和 metadata；M07-B 充值成功后写入真实充值流水。 | 查询 API 和前端账单页面待 M08；优惠券/套餐消费流水待 M07-C。 | M07-C 写入权益消费流水；M08 增加分页查询。 |
+| WAL-001 | 充值优惠 | M07-B | PARTIAL | `d9743d3` | 已建立充值规则和充值订单表，支持有效期、适用门店、限购、启停、clientRequestId 幂等；支付成功后调用钱包入账，重复支付回调不重复充值；Windows 全量后端回归通过。 | 真实微信充值支付回调仍需 M05 生产凭据和 M08 前端入口联调。 | M08 增加充值页面和账单查询。 |
+| WAL-002 | 门店独立会员余额 | M07-A | DONE | `63711ad` | 已建立租户/门店余额范围策略、现金/赠送双余额账户和不可变流水；充值、赠送、消费、退款、人工调整均预留 entry type；消费按赠送后现金扣款，业务号幂等，余额不足拒绝；Windows 全量后端回归通过。 | - | M07-D 聚合会员余额和权益状态。 |
+| WAL-003 | 余额账单 | M07-A/M08 | PARTIAL | `d9743d3` | 账单底表已包含业务类型、业务号、现金/赠送变动、变动后余额、操作人、trace 和 metadata；M07-B 充值成功后写入真实充值流水。 | 查询 API 和前端账单页面待 M08；优惠券/套餐不直接写钱包流水。 | M08 增加分页查询。 |
+| WAL-004 | 优惠券和套餐权益 | M07-C | PARTIAL | `4ae9296` | 已建立优惠券模板、持券、套餐计划、持有和权益核销流水；支持满减券、时长券、适用门店/房型/房间/星期/节假日、套餐剩余时长/金额，以及订单冻结、确认核销、退回和重复请求幂等；Windows 全量后端回归通过。 | 前端发放/购买/核销入口和订单 API 深度集成待 M08/M04 后续接入。 | M07-D 聚合会员券和套餐状态；M08 接入页面。 |
 | 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,11 +3,11 @@
 ```yaml
 execution_cursor:
  current_module: M07
-  current_stage: M07-C
+  current_stage: M07-D
  stage_status: TODO
-  last_completed_stage: M07-B
-  next_stage: M07-C
-  last_engineering_commit: d9743d3
+  last_completed_stage: M07-C
+  next_stage: M07-D
+  last_engineering_commit: 4ae9296
  last_push_verified: true
  base_branch: main
  blocked_reason: "M06-G 真实硬件联调缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线；已完成烟测运行器并按 BLOCKED_EXTERNAL 旁路。"
@@ -23,7 +23,7 @@ execution_cursor:
 | M04 订单、时段锁定、支付闭环 | DONE | `91801fe` | docs/devlogs/2026-06-20-M04-D-订单分享.md | M04-A/B/C/D 已完成可信定价、并发预占、订单状态机、续费取消换房、管理员调整、代下单和最小权限分享；Windows 全量回归与 WSL MySQL 8.4.9 模块回归通过。 |
 | M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 |
 | M06 设备、MQTT 与真实硬件联动 | PARTIAL | `d01f771` | docs/devlogs/2026-06-24-M06-G-真实硬件联调.md | M06-A 至 F 已完成 MQTT、拓扑、协议幂等、控制箱、Sub-1G 门锁、智慧插座和订单自动联动任务；M06-G 已补真实硬件烟测运行器，缺生产 MQTT 账号/ACL、DeviceID 和实物配线，保持 BLOCKED_EXTERNAL。 |
-| M07 会员、余额、充值、优惠券和套餐营销 | PARTIAL | `d9743d3` | docs/devlogs/2026-06-24-M07-B-充值优惠.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值规则、有效期、适用门店、限购、启停、支付成功入账和重复回调幂等；继续 M07-C 优惠券和套餐。 |
+| M07 会员、余额、充值、优惠券和套餐营销 | PARTIAL | `4ae9296` | docs/devlogs/2026-06-24-M07-C-优惠券和套餐.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值优惠；M07-C 已完成优惠券/套餐权益底表和冻结、确认、退回的可靠补偿核销服务；继续 M07-D 会员管理。 |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
 | M09 后台管理端完整业务 | TODO | - | - | - |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |