fix(M09-REGRESSION): 完成商品逐单对账与权限收口

2026-08-11 08:25:12 +08:00
parent e91b979128
commit 41b9cf7349
21 changed files with 566 additions and 39 deletions
@@ -0,0 +1,17 @@
+# 2026-08-11 M09-REGRESSION 商品逐单对账 API
+
+## 新增接口
+
+- `GET /admin-api/product-orders/:orderId/reconciliation`
+- `GET /app-api/management/product-orders/:orderId/reconciliation`
+
+接口要求 `goods.order.read`、`goods.order.manage`、`tenant.manage` 或 `platform.manage`，并继续执行租户与门店范围校验。响应包含订单金额聚合、支付退款聚合、净收入、库存占用/销售余额与不可变流水、订单来源寄存聚合、九项一致性检查及总一致性结果；接口只读，不自动修账。
+
+## 权限一致性修复
+
+- 商品订单管理路由与库存管理路由/服务将 `platform.manage` 视为租户级管理能力，与既有后台菜单和商品订单服务口径一致。
+- 只有 `platform.manage` 不会绕过 tenantId；目标租户仍由已验证会话取得。普通门店员工没有授权门店时继续返回门店范围禁止错误。
+
+## 兼容修复
+
+库存列表和库存流水分页不再把 MySQL `LIMIT/OFFSET` 作为预处理参数传递。服务先把 page/pageSize 约束为安全整数，再将计算出的分页常量写入 SQL，以兼容 MySQL 8.4 驱动执行路径。
@@ -0,0 +1,22 @@
+# 2026-08-11 M09-REGRESSION 商品全链路对账
+
+## 工程结果
+
+- 商品订单服务新增管理侧逐单对账，只读聚合不可变订单项、成功支付与退款、库存流水 metadata 以及订单来源寄存记录/明细。
+- 对账输出九项确定性检查，覆盖订单金额、数量、行数、实收、退款、库存占用余额、库存销售余额和寄存账实；任一漂移会返回失败项的应有值与实际值。
+- Vue 商品运营工作台新增逐单对账视图，并在普通订单详情展示支付单、退款单和不可变状态事件，便于从聚合差异追溯原始业务流水。
+- 修正商品订单与库存的 `platform.manage` 权限口径，使菜单可见、路由鉴权和服务层门店范围保持一致；空门店范围的平台运营账号可按租户显式门店参数工作，普通门店员工仍被拒绝。
+- 真实 MySQL 回归发现库存列表/流水的分页预处理参数在 MySQL 8.4 + Node 26 下返回 `ER_WRONG_ARGUMENTS`；分页整数经边界校验后安全内联，列表与流水同类路径一并修复。
+
+## 验证结果
+
+- `node scripts/check-m09-regression.mjs`：PASS。
+- 后端 TypeScript build、全量单元与路由测试：PASS；新增一致、金额/退款/寄存漂移、取消释放库存三组纯对账样例。
+- Vue TypeScript 检查、生产构建与导航测试：PASS；订单详情和对账视图独立懒加载分块 gzip 约 8.19 KiB。
+- WSL 原生副本 + MySQL 8.4.10：`up → verify → down → up → verify` PASS，217 条 up、159 条 verify、199 条 down；实测全额退款净收入、LOCK/DEDUCT 销售余额、订单寄存取完余额和 `platform.manage` 空门店范围。
+- 中断清理探针 PASS，临时数据库、账号和 `/home/f/qipai-wsl-test` 已清理。
+- Windows `scripts/dev/windows/test-all.ps1`：PASS。
+
+## 阶段状态
+
+`M09-REGRESSION=DONE`，M09 内部工程闭环；真实微信商品支付继续按既有规则保持 `BLOCKED_EXTERNAL`，不阻断唯一游标进入 `M10-A`。
@@ -56,6 +56,8 @@

 > 2026-08-11 M09-D4：当前伴随工程为 `PRD-001`、`INV-001`、`GOODS-102`、`GOODS-104` 接入端到端体验。登录顾客可读取门店目录，在小程序选购、创建/取消商品订单、整单寄存、部分取出、换码和取消寄存；领取码只在签发当次页面内存显示。Vue 后台第 13 个权限路由统一目录、库存、订单和寄存，按各域 capability 独立加载，写操作继续由服务端复验。Windows 全量 71.6 秒与 MySQL 8.4.10 的 217 up、159 verify、199 down 往返通过，游标进入 M09-REGRESSION。

+> 2026-08-11 M09-REGRESSION：当前伴随工程新增商品订单逐单对账，只读聚合订单明细、成功支付/退款、库存不可变流水及订单来源寄存余额，九项账实检查可直接定位金额、数量、占用、销售和寄存漂移；运营端同步展示支付、退款与不可变事件。回归修正 `platform.manage` 在库存/商品订单路由和服务层的空门店范围放行，并将已校验分页整数安全内联，解决 MySQL 8.4 预处理 `LIMIT/OFFSET` 参数兼容问题。Windows 全量与 MySQL 8.4.10 的 217 up、159 verify、199 down 往返通过，M09 内部工程完成，游标进入 M10-A。
+
 | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
@@ -81,10 +83,10 @@
 | CLN-003 | 保洁统计 | M08-B/M09 | DONE | `1f10715` | 保洁员与管理端统计统一按有效成员份额复算：免清洁不计奖励，DRAFT/CONFIRMED 仍计未付款，只有 PAID 计已结算；负责人/协作者、任务状态、结算状态、门店、日期和每日趋势口径一致。统计页、任务/结算明细和整数分 CSV 可相互校验；真实 MySQL 覆盖协作成员分步付款和最终任务结算。 | - | M10 以生产数据抽样复算，不重开统计状态机。 |
 | CLN-004 | 保洁结算 | M09-C | PARTIAL | `1f10715` | 同一任务成员份额由数据库生成唯一键保证最多一条有效结算明细，并发生成只有一个赢家；活动结算冻结成员奖励。取消保留原单/明细并生成负向冲正和状态事件，可重新生成；出款前 CAS、稳定请求号、商户隔离回调、成功重放、失败重试、人工已付、同源列表/导出和整数分均已闭环。协作任务按收款人分别付款，全部有效份额 PAID 后任务才进入 SETTLED。 | 真实微信商户凭据、生产小额转账和回调仍为 BLOCKED_EXTERNAL。 | 取得生产商户条件后执行小额转账、迟到回调和账单对账验收；内部工程不阻断 M09-D1。 |
 | CLN-005 | 保洁驳回/免清洁 | M08-B/M09 | PARTIAL | `eb838f5` | 已支持管理侧驳回、批量驳回和保洁员驳回补做；已新增 `POST /admin-api/cleaning/tasks/:taskId/exempt`，后台任务列表提供免清洁按钮、批量免清洁和 `EXEMPT` 筛选，仓储将可处理任务置为 `EXEMPT`、奖励归零并移除未结算协作者；待结算候选继续只取 `COMPLETED` 且未结算任务，免清洁任务不进入结算；管理统计 summary、门店明细、每日趋势和统计导出均新增免清洁数量，便于核对不结算口径。 | 真实商户现场执行仍待继续。 | 继续 M08-B/M09，补现场验收记录和更完整运营管理界面。 |
-| PRD-001 | 商品目录与门店售卖 | M09-D1/M09-D4 | DONE | `93af128` + M09-D4 当前暂存工程 | 分类、商品、SKU、门店上架、履约方式、销售开关/人工暂停及最多 8 段每周营业时段已实现；M09-D4 新增登录态顾客门店目录，小程序与运营后台复用同一商品主数据。 | - | M09-REGRESSION 对账目录销售时段、价格快照和门店隔离。 |
+| PRD-001 | 商品目录与门店售卖 | M09-D1/M09-D4 | DONE | `93af128`、`e91b979` | 分类、商品、SKU、门店上架、履约方式、销售开关/人工暂停及最多 8 段每周营业时段已实现；M09-D4 新增登录态顾客门店目录，小程序与运营后台复用同一商品主数据。 | - | M10 按通知和统计需求复用商品主数据。 |
 | INV-001 | 库存策略与不可变流水 | M09-D1/M09-D2 | DONE | `93af128`、`1a3ea7b` | TRACKED/UNLIMITED 策略、入库、调整、盘点、损耗、批量锁定/释放/扣减已实现；M09-D2 已把订单创建、支付、取消、超时和退款接入稳定业务号与同事务库存变更。请求指纹、版本 CAS、数量边界和不可变流水保证并发回调只扣一次、重复释放/返库幂等且不出现负库存。 | - | M09-D3 寄存数量已使用独立账本，不回写已完成订单项快照。 |
-| GOODS-102 | 商品订单与支付库存闭环 | M09-D2/M09-D4 | DONE | `1a3ea7b` + M09-D4 当前暂存工程 | 商品订单与支付单分离，订单项与状态事件不可变；M09-D4 小程序接入选购、购物车、创建与取消，Vue 后台接入筛选、详情、接单、配送/待取、完成、取消和退款。库存、支付、退款仍由服务端状态机和幂等事务控制。 | 真实微信商品支付入口仍缺生产商户条件。 | M09-REGRESSION 完成模拟支付全链路对账；真实支付纳入 BLOCKED_EXTERNAL。 |
-| GOODS-104 | 商品寄存与安全取出 | M09-D3/M09-D4 | DONE | `60264cb` + M09-D4 当前暂存工程 | 寄存状态、商品快照、一次性哈希领取码、部分取出自动轮换、并发防超领、审计与 outbox 已由 M09-D3 完成；M09-D4 接入顾客寄存列表/详情/取出/换码/取消和运营领取工作台，原码不写本地持久化。 | - | M09-REGRESSION 对账订单来源、剩余数量、凭证版本和不可变流水。 |
+| GOODS-102 | 商品订单与支付库存闭环 | M09-D2/M09-D4 | DONE | `1a3ea7b`、`e91b979` + M09-REGRESSION 当前工程 | 商品订单与支付单分离，订单项与状态事件不可变；小程序与 Vue 运营端已接入完整状态处置，逐单对账覆盖金额、成功支付/退款、库存占用/销售余额并显示原始流水。 | 真实微信商品支付入口仍缺生产商户条件。 | M10-A 将商品订单与退款事件接入统一通知中心；真实支付纳入 BLOCKED_EXTERNAL。 |
+| GOODS-104 | 商品寄存与安全取出 | M09-D3/M09-D4 | DONE | `60264cb`、`e91b979` + M09-REGRESSION 当前工程 | 寄存状态、商品快照、一次性哈希领取码、部分取出自动轮换、并发防超领、审计与 outbox 已完成；逐单对账验证订单来源寄存总量、剩余量与明细聚合一致。 | - | M10-A 消费既有寄存 outbox 并接入通知重试。 |
 | STAFF-001 | 员工账号 | M02-D/M08 | PARTIAL | `93f06d2` | 已实现创建员工、分配角色/门店、禁用、备注、重置会话和审计；管理员小程序已展示员工概况，Vue 后台可按角色/状态搜索并完成完整生命周期管理，权限变化即时撤销活动会话。 | 真实员工微信绑定和生产账号生命周期验收待补。 | M10 以真实员工账号验证绑定、门店切换、禁用和重新登录。 |
 | BKG-002 | 后台用户管理 | M02-D/M08 | PARTIAL | `0511008` | 已实现分页筛选、注册/登录时间、状态、角色、门店范围、手机号/IP 脱敏及会员/STAFF 分栏；租户管理员可为同租户有效 STAFF 设置唯一登录名和强密码，更新凭据会撤销其活动会话且不返回密码哈希。 | 尚缺平台级跨租户用户视图和真实生产数据验收。 | M10 以生产平台/租户账号复验跨租户用户视图、凭据重置和审计。 |
 | TEN-001 | 多门店支持 | M02/M03 | PARTIAL | `15139b3` | 门店 CRUD 与门店管理员数据范围已实现；跨门店写操作在 Windows 和 WSL MySQL 实测被拒绝。 | 地图选店、前端切换与完整订单数据范围待后续阶段。 | M03-C 接入地图选店，M04 起业务资源继承门店范围。 |
@@ -2,17 +2,17 @@

 ```yaml
 execution_cursor:
-  current_module: M09
-  current_stage: M09-REGRESSION
+  current_module: M10
+  current_stage: M10-A
  stage_status: TODO
-  last_completed_stage: M09-D4
-  next_stage: M10-A
-  last_engineering_commit: `60264cb`
-  pending_engineering_commit: "M09-D4 已完成工程（随本次中文工程提交固化）"
+  last_completed_stage: M09-REGRESSION
+  next_stage: M10-B
+  last_engineering_commit: `e91b979`
+  pending_engineering_commit: "M09-REGRESSION 已完成工程（随本次中文工程提交固化）"
  last_push_verified: true
  base_branch: main
  blocked_reason: "M08-A 真机合法域名、真实微信支付和实物开门验证缺微信后台/商户/硬件现场条件；M08-B 可独立工程内容已完成，真实商户凭据、微信后台配置、生产小额转账和实物硬件结果保持 BLOCKED_EXTERNAL；M08-C 可独立工程内容已完成，真实美团/抖音/快手商家授权与真机验券保持 BLOCKED_EXTERNAL，已按规则旁路进入 M08-D。M06-G 真实硬件联调仍缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线。"
-  updated_at: 2026-08-11T15:10:00+08:00
+  updated_at: 2026-08-11T08:30:00+08:00
 ```

 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
@@ -26,6 +26,6 @@ execution_cursor:
 | M06 设备、MQTT 与真实硬件联动 | PARTIAL | `da5751f` | docs/devlogs/2026-06-24-M06-E-智慧插座.md | M06-C/E-R1 已按原件校正控制箱、Sub-1G 与智慧插座 Wire/事件/脱敏；M06-R 已通过 Windows 后端全量、MQTT fixture、四项静态检查的中文/空格路径回归及 WSL MySQL 8.4.10 完整往返。M06-G 仍缺生产 MQTT 账号/ACL、DeviceID 和实物配线，保持 BLOCKED_EXTERNAL。 |
 | M07 会员、余额、充值、优惠券和套餐营销 | DONE | `ed0d455` | docs/devlogs/2026-06-24-M07-D-会员管理.md | M07-A 已完成现金/赠送双余额账本；M07-B 已完成充值优惠；M07-C 已完成优惠券/套餐权益底表和冻结、确认、退回的可靠补偿核销服务；M07-D 已完成会员画像、订单、消费、余额、充值、优惠券和套餐聚合查询。 |
 | M08 微信原生小程序完整业务 | PARTIAL | `3faf868` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A/B/C/D 功能切片与 M08-D-R1 架构返工已完成；12 个权限路由按领域懒加载，最大 JS 分块 217,195 B，三档响应式门禁通过。真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 保持 PARTIAL。 |
-| M09 保洁任务、结算、商品和库存 | DOING | `60264cb` + M09-D4 已完成工程 | docs/devlogs/2026-08-11-M09-D4-商品端到端体验.md | M09-A/B/C 与 M09-D1/D2/D3 已完成并推送。M09-D4 已接入登录态顾客目录、小程序选购/商品订单/寄存取出闭环，以及按目录、库存、订单、寄存权限分域的 Vue 运营工作台；Windows 全量和 MySQL 8.4 往返通过，游标进入 M09-REGRESSION。 |
-| M10 部署、域名、验收和运维闭环 | TODO | - | - | - |
+| M09 保洁任务、结算、商品和库存 | DONE | `e91b979` + M09-REGRESSION 已完成工程 | docs/devlogs/2026-08-11-M09-REGRESSION-商品全链路对账.md | M09-A/B/C 与 M09-D1/D2/D3/D4 均已完成并推送。模块回归新增商品订单金额、支付退款、库存不可变流水和订单来源寄存的逐单对账，修正库存分页 MySQL 8.4 预处理兼容及 `platform.manage` 权限一致性；Windows 全量和 MySQL 8.4 往返通过，游标进入 M10-A。 |
+| M10 部署、域名、验收和运维闭环 | TODO | M09-REGRESSION 当前工程 | docs/devlogs/2026-08-11-M09-REGRESSION-商品全链路对账.md | 下一步实现通知中心。 |