feat(M09-D1): 完成商品目录与库存流水底座

2026-08-11 03:51:18 +08:00
parent 2de796143f
commit 93af128002
37 changed files with 14683 additions and 58 deletions
@@ -0,0 +1,34 @@
+# 2026-08-11 M09-D1 商品目录与库存 API
+
+## 商品目录
+
+- `GET/POST /admin-api/stores/:storeId/product-categories`
+- `PUT/DELETE /admin-api/stores/:storeId/product-categories/:categoryId`
+- `GET/POST /admin-api/products`
+- `PUT/DELETE /admin-api/products/:productId`
+- `GET/POST /admin-api/products/:productId/skus`
+- `PUT/DELETE /admin-api/products/:productId/skus/:skuId`
+- `GET /admin-api/stores/:storeId/product-listings`
+- `PUT/DELETE /admin-api/stores/:storeId/product-listings/:productId`
+- `GET/PUT /admin-api/stores/:storeId/product-sales-settings`
+
+分类、门店上架和销售设置的只读接口同时提供 `/app-api/management/stores/:storeId/...` 管理端别名。写接口统一由后台 API 承载；更新/归档必须携带 `expectedVersion`，服务端以版本 CAS 返回明确冲突。
+
+## 库存管理
+
+- `GET /admin-api/inventory/stocks`
+- `GET /admin-api/inventory/stocks/:inventoryId/ledger`
+- `PUT /admin-api/inventory/stocks/:skuId/policy`
+- `POST /admin-api/inventory/stocks/:skuId/inbound`
+- `POST /admin-api/inventory/stocks/:skuId/adjust`
+- `POST /admin-api/inventory/stocks/:skuId/stocktake`
+- `POST /admin-api/inventory/stocks/:skuId/loss`
+
+库存写请求必填门店、requestId 和原因；需要绝对状态或并发保护的操作携带 `expectedVersion`。批量锁定、释放、扣减作为领域服务供 M09-D2 商品订单事务调用，不开放可由客户端伪造业务归属的裸管理接口。
+
+## 权限与错误边界
+
+- 商品读取/写入使用 `product.catalog.read` / `product.catalog.write`，库存读取/调整使用 `inventory.read` / `inventory.adjust`。
+- STAFF 默认只读，STORE_ADMIN 只能访问授权门店；TENANT_ADMIN 与 PLATFORM_ADMIN 仍分别受租户和显式平台范围约束。全局商品/SKU 目录读取不向普通 STAFF 开放。
+- 所有仓储和服务查询重复校验 tenantId/storeId，不依赖菜单隐藏或路由参数实现隔离。
+- 版本冲突、幂等指纹冲突、库存不足、锁定归属不匹配返回冲突类错误；越权、未找到和参数越界分别保持 403、404 和 400 语义。
@@ -1,8 +1,8 @@
 # 配置总表

-> 当前总纲：V5.6.md
-> 最后更新：2026-08-10
-> 维护规则：任何配置路径、账号、密码、域名、端口或加载顺序变化，必须与 `README.md`、`V5.6.md` 和实际配置在同一提交中更新。
+> 当前总纲：V5.7.md
+> 最后更新：2026-08-11
+> 维护规则：任何配置路径、账号、密码、域名、端口或加载顺序变化，必须与 `README.md`、`V5.7.md` 和实际配置在同一提交中更新。

 ## 当前已知凭据

@@ -109,7 +109,7 @@ MYSQL_DATABASE=<以项目实际数据库名为准>

 ## 文件位置

-完整位置表见根目录 `README.md` 的“配置文件位置”章节，以及 `V5.6.md` 继承的“0.6 README、配置文件与明文凭据同步规则”。
+完整位置表见根目录 `README.md` 的“配置文件位置”章节，以及 `V5.7.md` 继承的“0.6 README、配置文件与明文凭据同步规则”。

 ## 变更记录

@@ -120,4 +120,5 @@ MYSQL_DATABASE=<以项目实际数据库名为准>
 - 2026-06-22：M05-C 增加 `QIPAI_THIRD_PARTY_CREDENTIALS`、人工/Mock/API 模式、回调 HMAC 和券码哈希规则。
 - 2026-06-22：M05-D 增加门店收款账户、`profitShareReceivers` 环境映射、分账授权状态和非生产 Mock 门禁。
 - 2026-08-10：总纲升级为 V5.6；同步最新源码接管、M09-A-RECOVERY 完成证据和 M06-C-R1 固定执行游标，既有凭据与配置位置不变。
+- 2026-08-11：总纲升级为 V5.7；增加中文 Git 提交门禁并将当前游标推进至 M09-D2，既有凭据与配置位置不变。
 - 2026-08-10：M06-C-R1 增加门锁烟测 subtype 变量，确保实物 `CtrlDevice` 始终携带 14/15；未增加任何仓库内明文凭据。
@@ -1,21 +1,22 @@
 # 当前开发成果基线

 > V5.0 首次核验日期：2026-06-16  
-> audited_commit: `1f10715`
-> audited_at: `2026-08-11T02:08:40+08:00`
-> next_engineering_target: 按 V5.6 固定队列执行 M09-D1，建立分类、商品、SKU、门店售卖、营业时段与不可变库存流水底座
+> audited_commit: `2de7961`
+> audited_worktree: M09-D1 当前工作树（待本次中文工程提交）
+> audited_at: `2026-08-11T03:41:30+08:00`
+> next_engineering_target: 按 V5.7 固定队列执行 M09-D2，建立商品订单与库存锁定、扣减、释放、取消回补闭环
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。

 ## 总体结论

 | 范围 | 当前状态 | 证据 | 结论 |
 |---|---|---|---|
-| 总纲版本 | V5.6 已成为当前权威总纲，V5.4 及更早版本仅作历史备份 | 根目录 `V5.6.md` 的第 29 章固定队列 | 必须按 V5.6 游标开发，不得回退到历史队列 |
+| 总纲版本 | V5.7 已成为当前权威总纲，V5.6 及更早版本仅作历史基线 | 根目录 `V5.7.md` 的增量控制层与第 30 章固定队列 | 必须按 V5.7 游标开发，不得回退到历史队列 |
 | Git 远端 | `origin=ssh://git@git.txyundm.cn:2222/panda/qipai.git`，分支 `main` | `git rev-list main...origin/main` 为 `0 0` | 本地与远端同步 |
-| 正式后端 | 已完成 Fastify、迁移兼容、outbox/worker、多应用租户、身份/RBAC/门店范围及 M03-M08 业务 API；M09-A/B/C 已完成保洁事务并发、规则快照与版本验收、协作成员份额统计/结算唯一性、负向冲正、出款 CAS、商户隔离回调和人工付款 | `backend/src/**`、`database/migrations/**`、`backend/tests/**`、工程提交 `9b2f055`、`bc7cb8f`、`1f10715` | M01-M04、M07 已完成；M05/M06/M08 可独立工程内容完成但外部联调保持 PARTIAL；当前进入 M09-D1 |
-| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 权限路由工程；12 个业务入口按路由懒加载；保洁工作台覆盖规则、任务、版本验收、同源结算导出、冲正历史、状态事件和人工付款 | `admin/src/router.ts`、`admin/src/components/CleaningWorkspace.vue`、`admin/src/components/CleaningSettlementsPanel.vue`、`admin/src/components/CleaningStatisticsPanel.vue`、工程提交 `3faf868`、`bc7cb8f`、`1f10715` | 最大 JS 分块 218,014 B，M09-C 全量门禁通过，进入 M09-D1 |
+| 正式后端 | 已完成 Fastify、迁移兼容、outbox/worker、多应用租户、身份/RBAC/门店范围及 M03-M08 业务 API；M09-A/B/C 已完成保洁收口，M09-D1 已完成商品分类、商品、SKU、门店售卖/营业时段、库存策略、可用/锁定/损耗库存、幂等请求与不可变流水 | `backend/src/products/**`、`backend/src/inventory/**`、`backend/src/routes/{products,inventory}.ts`、`database/migrations/2026081107_m09d1_*`、`backend/tests/product-*.test.mjs`、`backend/tests/inventory-*.test.mjs`、`backend/tests/mysql-migration-roundtrip.test.mjs` | M09-D1 当前工作树的 build、全测、静态门禁和真实 MySQL 门禁通过，游标进入 M09-D2；提交 SHA 待本次中文工程提交取得 |
+| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 权限路由工程；12 个业务入口按路由懒加载；保洁工作台覆盖规则、任务、版本验收、同源结算导出、冲正历史、状态事件和人工付款；商品/库存菜单由服务端按 capability 返回 | `admin/src/router.ts`、`admin/src/components/CleaningWorkspace.vue`、`backend/src/routes/admin-auth.ts` | M09-D1 管理端 build/test 通过；商品库存专用运营页面归入后续业务切片，当前进入 M09-D2 |
 | 微信小程序 | 已纳管微信原生模板，并完成顾客端订单、充值、权益明细、下单抵扣主体链路、保洁任务端照片上传/补做主体链路，以及管理员门店/房态/订单/代下单/验券/会员/员工/保洁/设备/经营统计 | `miniapp/pages/index`、`miniapp/pages/store/detail`、`miniapp/pages/room/detail`、`miniapp/pages/orders/*`、`miniapp/pages/recharge/*`、`miniapp/pages/profile/*`、`miniapp/pages/cleaner/*`、`miniapp/pages/manager/*`、`miniapp/utils/api.js`、`scripts/check-miniapp-m08-a.mjs`、`scripts/check-miniapp-m08-c.mjs` | M08-A/B/C/D 可独立工程内容完成，执行游标进入 M09-A；真实团购、微信和硬件现场验收保持外部阻塞，M08 维持 PARTIAL |
-| 数据库迁移 | 已形成 M01-B 至 M09-C 连续 up/down/verify 计划、最小脱敏 seed、旧库 fixture、执行 CLI、验证结果门禁和 MySQL 8 集成测试；结算冲正、状态事件、活动成员份额唯一键和稳定出款请求号已纳入往返 | `database/migrations/**`、`backend/src/db/migration-runner.ts`、`backend/tests/mysql-migration-roundtrip.test.mjs` | WSL MySQL 8.4.10 已完成 160 up、132 verify、154 down；历史取消回填、并发单赢家、冲正重生成与协作任务最终结算实测通过 |
+| 数据库迁移 | 已形成 M01-B 至 M09-D1 连续 up/down/verify 计划；M09-D1 新增 9 张商品/库存表和不可变流水双触发器，迁移 runner 按增量 marker/checksum 执行，并可在 interrupted up/down DDL 后原地重试；同库迁移全流程由专用连接和数据库命名锁串行化 | `database/migrations/2026081107_m09d1_product_inventory_foundation.{up,down,verify}.sql`、`backend/src/db/migration-runner.ts`、`backend/tests/mysql-migration-roundtrip.test.mjs` | WSL MySQL 8.4.10 已完成 179 up、141 verify、171 down 的 up/verify/down/up/verify；增量跳过、崩溃恢复、双连接迁移互斥、触发器前置、并发单赢家、幂等、负库存拒绝、流水不可变和 cleanup probe 通过 |
 | M00 部署脚本 | 已有菜单、状态、HTTPS、Certbot、EMQX、备份检查模板 | `setup.sh`、`scripts/setup/`、`deploy/` | PARTIAL，生产未执行 |
 | 发布清单 dry-run | 可基于当前 HEAD 输出 `deployed=false` 的 release manifest，记录后端/后台/迁移尚未生成而跳过 | `scripts/setup/deploy-business.sh --dry-run .`、`scripts/dev/windows/check-release-manifest.ps1` | 可在 M00 验证结构；真实构建与生产发布待 M01/M09 后接入 |
 | 参考资料 | 已有清单、脱敏日志、页面/接口/表结构摘要 | `docs/reference-*`、`docs/db-schema-inventory.md` | PARTIAL，仍需按模块迁移正式实现 |
@@ -25,7 +26,7 @@
 ## 状态校准

 - `docs/module-status.md` 中 M00 仍为 `PARTIAL` 是正确的：生产 Ubuntu 初始化、部署与运维验收尚未执行；后端、后台和小程序源码已在后续模块建立。
- M01-M04 与 M07 已具备模块工程验收；M05、M06、M08 因真实厂商/硬件/生产条件保持 `PARTIAL`；M09-A/B/C、M06-C/E-R1、M06-R-REGRESSION 与 M08-D-R1 已完成，当前按 V5.6 执行 M09-D1，M10 尚未进入。
+- M01-M04 与 M07 已具备模块工程验收；M05、M06、M08 因真实厂商/硬件/生产条件保持 `PARTIAL`；M09-A/B/C/D1、M06-C/E-R1、M06-R-REGRESSION 与 M08-D-R1 已完成，当前按 V5.7 执行 M09-D2，M10 尚未进入。
 - 任何“目录存在”只能证明骨架存在，不能证明模块完成。

 ## Git 历史敏感信息核验
@@ -36,6 +37,6 @@

 ## 下一步

-1. 执行 M09-D1：建立租户隔离的分类、商品、SKU、门店售卖、营业时段和库存策略底表。
-2. 建立可用/锁定库存与不可变库存流水，使用版本号和事务条件更新禁止负库存，并补齐金额/数量边界。
-3. 补 migration down/verify、真实 MySQL 并发库存测试和 API/管理端最小闭环；M06-G 真实硬件联调继续等待外部条件，不阻断内部主队列。
+1. 执行 M09-D2：建立商品订单与订单项金额、商品、SKU、规格、履约方式等服务端快照，明确与支付订单分离的状态机。
+2. 复用 M09-D1 库存服务，在下单/支付/取消/超时链路中按稳定业务号完成锁定、扣减、释放和取消回补，保证重放幂等与并发单赢家。
+3. 补商品订单 API、权限、真实 MySQL 事务/崩溃恢复和订单金额服务端复算；M06-G 真实硬件联调继续等待外部条件，不阻断内部主队列。
@@ -0,0 +1,14 @@
+# 2026-08-11 M09-D1 商品目录与库存底座
+
+- 版本：`2026081107_m09d1_product_inventory_foundation`。
+- 新增 9 张表：`qipai_product_categories`、`qipai_products`、`qipai_product_skus`、`qipai_product_store_listings`、`qipai_product_store_settings`、`qipai_product_store_hours`、`qipai_product_inventory`、`qipai_product_inventory_requests`、`qipai_product_inventory_ledger`。
+- 分类按租户/门店隔离，商品与 SKU 属于租户目录，门店上架连接同租户商品和本门店分类；复合外键阻止跨租户、跨门店引用，软删除生成列使活动代码/条码唯一且归档后可复用。
+- 门店销售设置保存总开关、人工暂停期限/原因和版本；营业时段按星期与 slotNo 唯一，显式记录跨日，数据库检查分钟范围和跨日一致性。
+- 库存保存 `TRACKED` / `UNLIMITED` 策略、低库存阈值、可用/锁定/损耗数量及版本；CHECK 和条件更新共同限制数量为 `0..1,000,000,000`，不允许负库存。
+- `qipai_product_inventory_requests` 在租户/门店/requestId 维度唯一并保存规范化请求指纹，保证跨 SKU 批量请求只处理一次；大小写敏感排序规则确保 opaque requestId 与业务号不被错误折叠。
+- `qipai_product_inventory_ledger` 保存操作类型、三类数量增量、变动后快照、业务归属、请求、操作人和 `version_after`；请求与版本唯一键防重复，`qipai_product_inventory_ledger_no_update/no_delete` 双触发器禁止修改或删除流水。
+- 迁移 runner 按 `qipai_schema_migrations` marker 与 checksum 增量执行 pending 文件；完整迁移、M09-C 旧库直升、interrupted up DDL 和 interrupted down DDL 均可原地重跑，checksum/name 不一致则拒绝继续。
+- up/verify/down 使用专用连接持有按 `DATABASE()` 派生的 MySQL 命名锁，锁等待超时会明确失败；并发发布必须串行到读取 marker/checksum 之前，禁止不同构建交错执行 DDL。
+- 触发器 DDL 是生产迁移前置：启用 binlog 时必须配置 `log_bin_trust_function_creators=1`，并使用具备所需权限的独立迁移身份。runner 在任何触发器 DDL 和建表执行前检查，不满足时拒绝迁移，禁止临时删触发器过门禁。
+- down 先删除双触发器，再按依赖逆序删除 9 张表、权限和迁移 marker；verify 校验表、生成列、索引、CHECK、复合外键、触发器及角色权限。
+- MySQL 8.4.10 已完成 179 up、141 verify、171 down 的 `up → verify → down → up → verify`，双连接迁移互斥、增量/崩溃重试、cleanup probe、并发库存、幂等冲突、流水对账和不可变约束均通过。
@@ -0,0 +1,40 @@
+# 2026-08-11 M09-D1 商品目录与库存底座
+
+## 工程结果
+
+- 工程状态：当前工作树已完成，待以 `feat(M09-D1): 完成商品目录与库存流水底座` 中文标题提交并取得 SHA。
+- 新增分类、商品、SKU、门店上架、门店销售设置、每周最多 8 段且支持跨日的营业时段；分类/商品/SKU 支持软删除后的代码或条码复用，写操作统一使用 `expectedVersion` 乐观锁。
+- 新增 `TRACKED` / `UNLIMITED` 库存策略、可用/锁定/损耗三类数量，以及入库、调整、盘点、损耗、批量锁定、释放和扣减服务；批量操作同事务完成，任何一个 SKU 失败均整体回滚。
+- 库存请求以租户、门店和大小写敏感 requestId 建立全局幂等记录；请求指纹不一致明确拒绝，锁定归属按业务类型和业务号核对，重复释放、跨订单释放和超额扣减不会改动库存。
+- 每次库存变动写入带 `version_after` 的不可变流水，数据库双触发器拒绝 UPDATE/DELETE；流水增量与库存最终值可对账，版本唯一键防止遗漏或重复版本。
+- 商品/库存路由接入 Fastify，补 `product.catalog.read/write`、`inventory.read/adjust` capability、角色默认授权、服务端菜单和租户/门店范围校验；STAFF 只读、STORE_ADMIN 授权门店、TENANT_ADMIN 与 PLATFORM_ADMIN 边界均有测试。
+- 迁移 runner 改为按单个迁移 marker/checksum 只执行 pending 文件，旧库可直接增量应用 M09-D1；interrupted up/down DDL 后可在同一库原地重试，不需要清空或重建。
+- up/verify/down 在同一专用连接上持有按数据库名派生的 MySQL 命名锁，两个发布进程会串行执行；不同构建必须等前一进程完成后再校验 marker/checksum，避免交错 DDL 形成混合 schema。
+- 迁移包含触发器时，runner 在执行任何触发器 DDL 前检查生产前置；binlog 开启时必须启用 `log_bin_trust_function_creators=1` 并使用独立迁移身份，否则在建表前拒绝执行。
+
+## 数据库结果
+
+`2026081107_m09d1_product_inventory_foundation` 新增 9 张表：
+
+1. `qipai_product_categories`
+2. `qipai_products`
+3. `qipai_product_skus`
+4. `qipai_product_store_listings`
+5. `qipai_product_store_settings`
+6. `qipai_product_store_hours`
+7. `qipai_product_inventory`
+8. `qipai_product_inventory_requests`
+9. `qipai_product_inventory_ledger`
+
+## 验证证据
+
+- `node scripts/check-m09-d1-product-inventory.mjs`：PASS，静态门禁确认迁移、路由、RBAC、服务、真实 MySQL 断言和 Windows/WSL 门禁均已接线。
+- 后端 `npm run build`、后端全量 `npm test`：PASS。
+- 管理端 `npm run build`、`npm test`：PASS。
+- WSL 原生临时副本 + MySQL 8.4.10：完成 `up → verify → down → up → verify`，179 条 up、141 条 verify、171 条 down；双连接迁移锁、interrupted up/down DDL 原地重跑、增量 marker/checksum、触发器生产前置和 cleanup probe 均 PASS。
+- 真实 MySQL 业务用例覆盖门店唯一性、跨日时段、商品/SKU 版本冲突、并发锁定单赢家、重复 requestId 重放与冲突、批量原子回滚、锁定/释放/扣减、损耗/盘点、负库存拒绝、流水对账与不可变触发器。
+- Windows 汇总门禁在全部 M09-D1 与 V5.7 文件显式暂存后执行最终复跑；不得将提交前的未跟踪完整性提示记为功能失败。
+
+## 阶段结论
+
+`M09-D1=DONE`。唯一执行游标进入 `M09-D2`，下一阶段建立商品订单、订单项快照、支付衔接与库存占用生命周期。生产触发器前置属于部署强制条件，不是可绕过的外部阻塞。
@@ -48,6 +48,8 @@

 > 2026-08-11 M09-C：工程提交 `1f10715` 为 `CLN-003`、`CLN-004` 统一协作成员份额的待结算/已结算口径，补活动份额数据库唯一键、并发生成单赢家、成员奖励冻结、不可变负向冲正与状态事件；微信转账在出站前 CAS 为处理中，回调按商户隔离且成功重放幂等，并支持失败后的人工付款。列表/API/CSV 共用查询，所有保洁 CSV 金额输出整数分。Windows 全量与 WSL MySQL 8.4.10 的 160 up、132 verify、154 down 往返通过，游标进入 M09-D1。

+> 2026-08-11 M09-D1：当前工作树为 `PRD-001`、`INV-001` 建立租户/门店隔离的商品目录和库存底座；9 张表覆盖分类、商品、SKU、门店上架、销售设置、跨日时段、库存、幂等请求和不可变流水。增量迁移可跳过历史 marker，interrupted up/down DDL 可原地重试，同库发布由数据库命名锁串行化；触发器生产前置、API/RBAC、并发库存、幂等冲突、负库存拒绝和流水 UPDATE/DELETE 拒绝已通过。WSL MySQL 8.4.10 完成 179 up、141 verify、171 down 往返及 cleanup probe，游标进入 M09-D2；结果随本次中文工程提交固化。
+
 | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
@@ -73,6 +75,8 @@
 | 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 | DONE | M09-D1 当前工作树（待本次中文工程提交） | 分类、商品、SKU、门店上架、履约方式、销售开关/人工暂停及最多 8 段每周营业时段已实现；代码/条码软删除后可复用，写操作用 expectedVersion CAS，跨日营业判断和租户/门店/角色越权拒绝有路由、仓储和真实 MySQL 证据。 | - | M09-D2 复用目录快照创建商品订单，不重建第二套商品主数据。 |
+| INV-001 | 库存策略与不可变流水 | M09-D1 | DONE | M09-D1 当前工作树（待本次中文工程提交） | TRACKED/UNLIMITED 策略、入库、调整、盘点、损耗、批量锁定/释放/扣减已实现；请求指纹全局幂等、复合外键、数量边界、版本 CAS 和事务保证负库存拒绝与批量原子性，流水版本唯一且双触发器禁止 UPDATE/DELETE。MySQL 8.4.10 覆盖并发单赢家、重放/冲突、锁定归属、对账与 interrupted up/down 恢复。 | - | M09-D2 把订单状态机接入库存锁定、扣减、释放和取消回补。 |
 | 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 起业务资源继承门店范围。 |
@@ -3,15 +3,16 @@
 ```yaml
 execution_cursor:
  current_module: M09
-  current_stage: M09-D1
-  stage_status: DOING
-  last_completed_stage: M09-C
-  next_stage: M09-D2
+  current_stage: M09-D2
+  stage_status: TODO
+  last_completed_stage: M09-D1
+  next_stage: M09-D3
  last_engineering_commit: `1f10715`
+  pending_engineering_commit: "M09-D1 当前工作树（待本次中文工程提交）"
  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-11T02:08:40+08:00
+  updated_at: 2026-08-11T03:41:30+08:00
 ```

 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
@@ -25,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 | `1f10715` | docs/devlogs/2026-08-11-M09-C-统计与结算收口.md | M09-A/B/C 已完成任务事务并发、规则与验收、协作份额统计与结算唯一性、负向冲正、出款竞态与同源导出；当前进入 M09-D1，建设商品/SKU/库存底座。 |
+| M09 保洁任务、结算、商品和库存 | DOING | M09-D1 当前工作树（待本次中文工程提交） | docs/devlogs/2026-08-11-M09-D1-商品目录与库存底座.md | M09-A/B/C 已完成保洁收口；M09-D1 已完成 9 张表、商品/SKU/门店售卖与跨日时段、库存策略、幂等请求、不可变流水、API/RBAC、增量/崩溃重试迁移和真实 MySQL 门禁。当前进入 M09-D2，建设商品订单与库存占用生命周期。 |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |