From ba99beb221c744676261ec539d3700b871bc3181 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 24 Jun 2026 15:39:54 +0800 Subject: [PATCH] =?UTF-8?q?docs(M07-B):=20=E8=AE=B0=E5=BD=95=E5=85=85?= =?UTF-8?q?=E5=80=BC=E4=BC=98=E6=83=A0=E9=AA=8C=E6=94=B6=E5=B9=B6=E6=8E=A8?= =?UTF-8?q?=E8=BF=9B=E5=88=B8=E5=A5=97=E9=A4=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 6 ++-- docs/current-baseline.md | 10 +++---- .../2026-06-24-M07-B-recharge-plans.md | 22 +++++++++++++++ docs/devlogs/2026-06-24-M07-B-充值优惠.md | 28 +++++++++++++++++++ docs/feature-status.md | 5 ++-- docs/module-status.md | 10 +++---- 6 files changed, 66 insertions(+), 15 deletions(-) create mode 100644 docs/db-changelog/2026-06-24-M07-B-recharge-plans.md create mode 100644 docs/devlogs/2026-06-24-M07-B-充值优惠.md diff --git a/README.md b/README.md index f43220d..d15454c 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` 为准。 -- 当前执行游标：`M07-B` -- 最近工程提交：`63711ad`，完成 M07-A 双余额账本，支持现金/赠送分账、不可变流水、业务幂等和赠送优先扣款。 -- 下一工程目标：M07-B 充值优惠。 +- 当前执行游标：`M07-C` +- 最近工程提交：`d9743d3`，完成 M07-B 充值优惠，支持充值规则、有效期、门店适用、限购、启停、支付成功入账和重复回调幂等。 +- 下一工程目标：M07-C 优惠券和套餐。 ## 版本递进 diff --git a/docs/current-baseline.md b/docs/current-baseline.md index 49f9059..b7bfb78 100644 --- a/docs/current-baseline.md +++ b/docs/current-baseline.md @@ -1,8 +1,8 @@ # 当前开发成果基线 > V5.0 首次核验日期：2026-06-16 -> audited_commit: `63711ad` -> next_engineering_target: M07-B 充值优惠 +> audited_commit: `d9743d3` +> next_engineering_target: M07-C 优惠券和套餐 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。 ## 总体结论 @@ -35,6 +35,6 @@ ## 下一步 -1. 进入 M02-D：实现用户/员工管理、角色分配、禁用、重置会话和审计。 -2. 在后续业务事务中使用现有 outbox/任务基础注册真实 handler，不在 M01-C 预造空业务处理器。 -3. 评估 Kysely 安全修复版的 Node 22 要求；未升级生产运行时前继续使用 `mysql2/promise`。 +1. 进入 M07-C：实现优惠券和套餐权益定义、发放、核销与余额/订单联动。 +2. 继续复用 M07-A 钱包流水和 M07-B 充值入账幂等能力，所有权益扣减必须由服务端事务控制。 +3. M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线。 diff --git a/docs/db-changelog/2026-06-24-M07-B-recharge-plans.md b/docs/db-changelog/2026-06-24-M07-B-recharge-plans.md new file mode 100644 index 0000000..122011b --- /dev/null +++ b/docs/db-changelog/2026-06-24-M07-B-recharge-plans.md @@ -0,0 +1,22 @@ +# M07-B recharge plans + +- 工程 commit：`d9743d3` +- 迁移文件： + - `database/migrations/2026062422_m07b_recharge_plans.up.sql` + - `database/migrations/2026062422_m07b_recharge_plans.down.sql` + - `database/migrations/2026062422_m07b_recharge_plans.verify.sql` + +## 新增表 + +- `qipai_recharge_plans`：充值规则表，包含支付金额、赠送金额、范围、适用门店、有效期、用户限购、启停状态和软删除字段。 +- `qipai_recharge_orders`：充值订单表，包含充值单号、客户端请求号、支付记录、支付/入账时间、金额快照、状态和 trace。 + +## 约束与索引 + +- `uq_qipai_recharge_order_no (tenant_id, recharge_no)` 保证充值单号租户内唯一。 +- `uq_qipai_recharge_order_request (tenant_id, user_id, client_request_id)` 保证客户端重复提交不重复生成充值订单。 +- `idx_qipai_recharge_plan_scope` 和 `idx_qipai_recharge_order_user` 支持规则筛选和用户充值查询。 + +## 回滚 + +down 迁移按依赖顺序删除 `qipai_recharge_orders` 后删除 `qipai_recharge_plans`，并移除 `2026062422` 迁移记录。 diff --git a/docs/devlogs/2026-06-24-M07-B-充值优惠.md b/docs/devlogs/2026-06-24-M07-B-充值优惠.md new file mode 100644 index 0000000..a10ebf6 --- /dev/null +++ b/docs/devlogs/2026-06-24-M07-B-充值优惠.md @@ -0,0 +1,28 @@ +# M07-B 充值优惠 + +- 日期：2026-06-24 +- 起始 commit：`db1d08e` +- 工程 commit：`d9743d3` +- ENGINEERING_DELTA=YES +- 子阶段状态：DONE + +## 工程增量 + +- 新增 `qipai_recharge_plans`，支持充值规则、有效期、适用门店、限购和启停状态。 +- 新增 `qipai_recharge_orders`，记录充值单号、客户端请求号、支付记录、支付时间和入账时间。 +- 新增 `RechargeService`，创建充值订单时校验规则有效性、门店范围和用户限购。 +- 支付成功回调后才调用 `WalletLedgerService.credit` 入账，重复创建请求和重复支付回调均保持幂等。 +- 迁移计划、迁移契约、迁移 runner 和全量测试链路已接入 M07-B。 + +## 验证 + +- Windows `npm run build`：退出码 0。 +- Windows `node tests/recharge-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-B 全量后端回归通过。 +- 工程 commit 已 push，`HEAD == origin/main == d9743d3`。 + +## 后续 + +游标进入 M07-C 优惠券和套餐：实现权益定义、发放、核销、服务端事务扣减，以及与订单/余额流水的联动。 diff --git a/docs/feature-status.md b/docs/feature-status.md index a3e91cd..4ff6659 100644 --- a/docs/feature-status.md +++ b/docs/feature-status.md @@ -33,8 +33,9 @@ | 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-002 | 门店独立会员余额 | M07-A | DONE | `63711ad` | 已建立租户/门店余额范围策略、现金/赠送双余额账户和不可变流水；充值、赠送、消费、退款、人工调整均预留 entry type；消费按赠送后现金扣款，业务号幂等，余额不足拒绝；Windows 全量后端回归通过。 | - | M07-B 接入充值规则和支付成功入账。 | -| WAL-003 | 余额账单 | M07-A/M08 | PARTIAL | `63711ad` | 账单底表已包含业务类型、业务号、现金/赠送变动、变动后余额、操作人、trace 和 metadata，可对账追溯。 | 查询 API 和前端账单页面待 M08；真实充值/消费接入待 M07-B/C。 | M07-B/C 写入真实充值和权益消费流水；M08 增加分页查询。 | +| 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 增加分页查询。 | | 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 2bd6aae..3eb4a6d 100644 --- a/docs/module-status.md +++ b/docs/module-status.md @@ -3,11 +3,11 @@ ```yaml execution_cursor: current_module: M07 - current_stage: M07-B + current_stage: M07-C stage_status: TODO - last_completed_stage: M07-A - next_stage: M07-B - last_engineering_commit: 63711ad + last_completed_stage: M07-B + next_stage: M07-C + last_engineering_commit: d9743d3 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 | `63711ad` | docs/devlogs/2026-06-24-M07-A-双余额账本.md | M07-A 已完成现金/赠送双余额账户、不可变流水、业务号幂等、赠送优先扣款和余额不足拒绝；继续 M07-B 充值优惠。 | +| M07 会员、余额、充值、优惠券和套餐营销 | PARTIAL | `d9743d3` | docs/devlogs/2026-06-24-M07-B-充值优惠.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值规则、有效期、适用门店、限购、启停、支付成功入账和重复回调幂等；继续 M07-C 优惠券和套餐。 | | M08 微信原生小程序完整业务 | TODO | - | - | - | | M09 后台管理端完整业务 | TODO | - | - | - | | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |