docs(M07-A): 记录双余额账本验收并推进充值优惠

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-A`
-- 最近工程提交：`d01f771`，完成 M06-G 真实硬件烟测运行器；缺生产 MQTT 账号、DeviceID 和实物时安全 SKIP/DRY_RUN。
-- 下一工程目标：M07-A 双余额账本。
+- 当前执行游标：`M07-B`
+- 最近工程提交：`63711ad`，完成 M07-A 双余额账本，支持现金/赠送分账、不可变流水、业务幂等和赠送优先扣款。
+- 下一工程目标：M07-B 充值优惠。
 
 ## 版本递进
 

docs/current-baseline.md

@@ -1,8 +1,8 @@
 # 当前开发成果基线
 
 > V5.0 首次核验日期：2026-06-16  
-> audited_commit: `d01f771`
-> next_engineering_target: M07-A 双余额账本
+> audited_commit: `63711ad`
+> next_engineering_target: M07-B 充值优惠
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。
 
 ## 总体结论

docs/db-changelog/2026-06-24-M07-A-wallet-ledger.md

@@ -0,0 +1,28 @@
+# M07-A 双余额账本数据库变更
+
+## 背景
+
+M07-A 需要现金余额和赠送余额分账户保存，所有变动必须可追溯且支持幂等业务号。
+
+## 影响表
+
+- `qipai_wallet_scope_policies`
+- `qipai_wallet_accounts`
+- `qipai_wallet_ledger_entries`
+
+## 正向 SQL
+
+见 `database/migrations/2026062421_m07a_wallet_ledger.up.sql`。
+
+## 回滚 SQL
+
+见 `database/migrations/2026062421_m07a_wallet_ledger.down.sql`。
+
+## 验证方式
+
+- `database/migrations/2026062421_m07a_wallet_ledger.verify.sql`
+- `npm test`
+
+## 风险
+
+新增表不回填历史余额；生产迁移前应先备份，后续 M07-B/C 接入充值、支付和权益核销后再产生真实流水。

docs/devlogs/2026-06-24-M07-A-双余额账本.md

@@ -0,0 +1,28 @@
+# M07-A 双余额账本
+
+- 日期：2026-06-24
+- 起始 commit：`8de3d05`
+- 工程 commit：`63711ad`
+- ENGINEERING_DELTA=YES
+- 子阶段状态：DONE
+
+## 工程增量
+
+- 新增 `qipai_wallet_scope_policies`，支持租户/门店余额共享范围配置。
+- 新增 `qipai_wallet_accounts`，现金余额和赠送余额分账户保存。
+- 新增 `qipai_wallet_ledger_entries`，所有充值、赠送、消费、退款和人工调整以不可变流水记录。
+- 新增 `WalletLedgerService`，支持入账、赠送优先扣款、人工调整、余额不足拒绝和业务号幂等。
+- 迁移计划、迁移契约和全量测试链路已接入 M07-A。
+
+## 验证
+
+- Windows `npm run build`：退出码 0。
+- Windows `node tests/wallet-ledger.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-A 全量后端回归通过。
+- 工程 commit 已 push，`HEAD == origin/main == 63711ad`。
+
+## 后续
+
+游标进入 M07-B 充值优惠：实现充值规则、有效期、适用门店、限购、启停，以及支付成功后才记账。

docs/feature-status.md

@@ -33,6 +33,8 @@
 | 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 增加分页查询。 |
 | 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 模式。 |

docs/module-status.md

@@ -3,11 +3,11 @@
 ```yaml
 execution_cursor:
   current_module: M07
-  current_stage: M07-A
+  current_stage: M07-B
   stage_status: TODO
-  last_completed_stage: M06-F
-  next_stage: M07-A
-  last_engineering_commit: d01f771
+  last_completed_stage: M07-A
+  next_stage: M07-B
+  last_engineering_commit: 63711ad
   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 会员、余额、充值、优惠券和套餐营销 | TODO | - | - | 当前游标进入 M07-A 双余额账本。 |
+| M07 会员、余额、充值、优惠券和套餐营销 | PARTIAL | `63711ad` | docs/devlogs/2026-06-24-M07-A-双余额账本.md | M07-A 已完成现金/赠送双余额账户、不可变流水、业务号幂等、赠送优先扣款和余额不足拒绝；继续 M07-B 充值优惠。 |
 | M08 微信原生小程序完整业务 | TODO | - | - | - |
 | M09 后台管理端完整业务 | TODO | - | - | - |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |