diff --git a/README.md b/README.md index e28caa5..f43220d 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-A` -- 最近工程提交:`d01f771`,完成 M06-G 真实硬件烟测运行器;缺生产 MQTT 账号、DeviceID 和实物时安全 SKIP/DRY_RUN。 -- 下一工程目标:M07-A 双余额账本。 +- 当前执行游标:`M07-B` +- 最近工程提交:`63711ad`,完成 M07-A 双余额账本,支持现金/赠送分账、不可变流水、业务幂等和赠送优先扣款。 +- 下一工程目标:M07-B 充值优惠。 ## 版本递进 diff --git a/docs/current-baseline.md b/docs/current-baseline.md index 024b672..49f9059 100644 --- a/docs/current-baseline.md +++ 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 检查脚本。 ## 总体结论 diff --git a/docs/db-changelog/2026-06-24-M07-A-wallet-ledger.md b/docs/db-changelog/2026-06-24-M07-A-wallet-ledger.md new file mode 100644 index 0000000..12ad1c8 --- /dev/null +++ b/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 接入充值、支付和权益核销后再产生真实流水。 diff --git a/docs/devlogs/2026-06-24-M07-A-双余额账本.md b/docs/devlogs/2026-06-24-M07-A-双余额账本.md new file mode 100644 index 0000000..a7e7d39 --- /dev/null +++ b/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 充值优惠:实现充值规则、有效期、适用门店、限购、启停,以及支付成功后才记账。 diff --git a/docs/feature-status.md b/docs/feature-status.md index c6280c6..a3e91cd 100644 --- a/docs/feature-status.md +++ 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 模式。 | diff --git a/docs/module-status.md b/docs/module-status.md index e102de6..2bd6aae 100644 --- a/docs/module-status.md +++ b/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 | - | - | - |