docs(M09-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` 为准。
 
-- 当前执行游标：`M09-B`（DOING）；`M09-A-RECOVERY`、`M06-C-R1`、`M06-E-R1`、`M06-R-REGRESSION` 与 `M08-D-R1` 已完成，真实团购商家授权、微信和硬件现场验收保持 `BLOCKED_EXTERNAL`。
-- 最近工程提交：`3faf868`，后台 12 个业务入口已迁入 Vue Router 权限路由和按路由懒加载；最大 JS 分块 217,195 B，375/768/1440 响应式与全仓门禁通过。
-- 下一工程目标：执行 M09-B，复用既有清洁任务、照片、验收、驳回与免清洁链路，按 V5.6 收口图片规则、权限、失败恢复和缺口测试。
+- 当前执行游标：`M09-C`（DOING）；`M09-A-RECOVERY`、`M06-C-R1`、`M06-E-R1`、`M06-R-REGRESSION`、`M08-D-R1` 与 `M09-B` 已完成，真实团购商家授权、微信和硬件现场验收保持 `BLOCKED_EXTERNAL`。
+- 最近工程提交：`bc7cb8f`，保洁三级规则快照、图片安全与租户隔离、返工照片版本、到期清理、免清洁策略和新订单安全断电已完成；Windows 全量和 WSL MySQL 8.4 往返通过。
+- 下一工程目标：执行 M09-C，统一负责人/协作者、免清洁、驳回、完成与结算统计口径，补并发结算唯一性、撤销反向记录和 API/CSV 同源查询。
 
 ## 版本递进
 

V5.6.md

@@ -171,23 +171,19 @@ M09-A-RECOVERY
 
 ```yaml
 execution_cursor_v56:
-  evidence_head: b35af9037f256657f38f922e7b8a9bed9eb9aee9
+  evidence_head: bc7cb8fab9ec1770b0b5b292f1031c4b08ef1dbb
   base_branch: main
   remote: ssh://git@git.txyundm.cn:2222/panda/qipai.git
   current_module: M09
-  current_stage: M09-A-RECOVERY
-  stage_status: DOING_UNCOMMITTED
-  last_completed_functional_stage: M08-D-FUNCTIONAL
-  last_engineering_commit: 0511008
-  last_docs_commit: b35af90
-  next_stage_after_current: M06-C-R1
-  mandatory_return_after_remediation: M08-D-R1
+  current_stage: M09-C
+  stage_status: DOING
+  last_completed_functional_stage: M09-B
+  last_engineering_commit: bc7cb8f
+  last_docs_commit: b507e87
+  next_stage_after_current: M09-D1
   frozen_stages:
     M08-B: PARTIAL_BLOCKED_EXTERNAL_SCOPE_FROZEN
-  internal_blockers:
-    - M06_PROTOCOL_DOCUMENT_MISMATCH
-    - CHECK_SCRIPTS_FILE_URL_PATH
-    - M08D_ROUTER_LAZYLOAD_CHUNK
+  internal_blockers: []
   external_blockers:
     - REAL_WECHAT_PAY_AND_PROFIT_SHARING
     - REAL_GROUP_BUY_AUTHORIZATION
@@ -6721,11 +6717,11 @@ M09-A-RECOVERY
 
 ```text
 DOCUMENT_VERSION=V5.6
-EVIDENCE_HEAD=b35af9037f256657f38f922e7b8a9bed9eb9aee9
+EVIDENCE_HEAD=bc7cb8fab9ec1770b0b5b292f1031c4b08ef1dbb
 WORKTREE_PROTECTED=true
-CURRENT_STAGE=M09-A-RECOVERY
-STAGE_RESULT=DOING_UNCOMMITTED
-NEXT_STAGE=M06-C-R1
+CURRENT_STAGE=M09-C
+STAGE_RESULT=DOING
+NEXT_STAGE=M09-D1
 TARGET=CODE_COMPLETE_THEN_RELEASE_CANDIDATE_THEN_PRODUCTION_ACCEPTED
 ```
 

docs/api-changelog/2026-08-10-M09-B-cleaning-rules.md

@@ -0,0 +1,27 @@
+# 2026-08-10 M09-B 清洁规则与照片验收 API
+
+## 新增管理接口
+
+- `GET /admin-api/cleaning/templates`
+  - 按租户和管理员门店范围返回租户、门店、房间三级清洁模板。
+  - 返回照片必传规则、最少/最多张数、免清洁策略、状态和版本号。
+- `PUT /admin-api/cleaning/templates`
+  - 新建或更新同一作用范围的模板；更新时版本号递增并写审计日志。
+  - 配置只参与后续新任务生成，不修改既有任务快照。
+- `GET /admin-api/cleaning/tasks/:taskId/submissions`
+  - 返回最近 20 个验收提交版本，包含版本号、状态、照片、提交备注、驳回原因、提交/验收人和时间。
+- `POST /admin-api/cleaning/photos/cleanup`
+  - 批量清理到期且未提交的照片；先原子领取并标记孤儿，文件删除成功后再软删除记录，失败项五分钟后可重试。
+
+## 既有接口收口
+
+- `POST /app-api/cleaning/tasks/:taskId/photos` 只允许本人 `STARTED` 任务；文件必须为 JPEG/PNG/WebP，声明 MIME、扩展名和实际解码格式一致，原图最多 8 MiB/4000 万像素。
+- 图片统一旋转、限边并重编码为 WebP，移除 EXIF/ICC 等附加元数据；存储路径固定为 `tenants/{tenantId}/stores/{storeId}`。
+- 每次上传写入任务照片资产，提交时再次校验租户、任务、上传人和 `PENDING` 状态，禁止复用其他任务或其他租户 URL。
+- `POST /app-api/cleaning/tasks/:taskId/submit` 使用任务创建时固化的照片规则；驳回后必须先调用 `rework` 回到 `STARTED`，再提交新版本。
+- `complete` / `reject` 同事务更新当前提交版本为 `ACCEPTED` / `REJECTED`，旧版本和旧照片继续保留。
+- `exempt` 按任务快照中的 `DISABLED`、`BEFORE_START`、`ANY_ACTIVE` 策略执行，继续保证免清洁任务不进入结算。
+
+## 设备安全边界
+
+- 订单结束、取消或换房旧房间触发断电前，重新查询该房间最新有效订单；存在 `PAID`、`RESERVED` 或 `IN_PROGRESS` 新订单时返回 `ROOM_HAS_ACTIVE_ORDER`，不下发取消任务或插座断电。

docs/current-baseline.md

@@ -1,8 +1,8 @@
 # 当前开发成果基线
 
 > V5.0 首次核验日期：2026-06-16  
-> audited_commit: `3faf868`
-> next_engineering_target: 按 V5.6 固定队列执行 M09-B，复用既有保洁业务链路收口图片、验收、驳回和清洁规则
+> audited_commit: `bc7cb8f`
+> next_engineering_target: 按 V5.6 固定队列执行 M09-C，统一保洁统计与结算口径、并发唯一性和撤销反向记录
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。
 
 ## 总体结论
@@ -11,10 +11,10 @@
 |---|---|---|---|
 | 总纲版本 | V5.6 已成为当前权威总纲，V5.4 及更早版本仅作历史备份 | 根目录 `V5.6.md` 的第 29 章固定队列 | 必须按 V5.6 游标开发，不得回退到历史队列 |
 | 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 已完成事务收口，M06-C/E-R1 已完成控制箱、门锁与插座协议纠偏并通过 M06-R 全量回归 | `backend/src/**`、`database/migrations/**`、`backend/tests/**`、工程提交 `9b2f055`、`dabc656`、`aed36f0`、`36b3b2f`、`da5751f` | M01-M04、M07 已完成；M05/M06/M08 可独立工程内容完成但外部联调保持 PARTIAL；当前进入 M08-D-R1 |
-| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 工程，完成正式租户账号登录、短期访问令牌、轮换刷新令牌、当前会话、注销、401 单航班续期/清理和服务端权限菜单；12 个业务入口均为 Vue Router 深链接，菜单与 capability 双重门禁，业务页按路由懒加载，失败可重载恢复 | `admin/src/App.vue`、`admin/src/router.ts`、`admin/src/navigation.mjs`、`admin/src/session.ts`、`scripts/check-admin-m08-d-r1.mjs`、工程提交 `3faf868` | M08-D-R1 已完成；最大 JS 分块由 923.28 KiB 降至 217,195 B，入口 gzip 74.94 KiB，375/768/1440 无横向溢出，进入 M09-B |
+| 正式后端 | 已完成 Fastify、迁移兼容、outbox/worker、多应用租户、身份/RBAC/门店范围及 M03-M08 业务 API；M09-A/B 已完成保洁事务并发、三级模板快照、照片安全/隔离/清理、版本化验收、免清洁策略与新订单安全断电 | `backend/src/**`、`database/migrations/**`、`backend/tests/**`、工程提交 `9b2f055`、`bc7cb8f` | M01-M04、M07 已完成；M05/M06/M08 可独立工程内容完成但外部联调保持 PARTIAL；当前进入 M09-C |
+| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 权限路由工程；12 个业务入口按路由懒加载；保洁工作台新增门店/房间规则配置、任务快照、返工次数与逐版照片验收追溯 | `admin/src/router.ts`、`admin/src/components/CleaningWorkspace.vue`、`admin/src/components/CleaningRulesPanel.vue`、`admin/src/components/CleaningTasksPanel.vue`、工程提交 `3faf868`、`bc7cb8f` | 最大 JS 分块 217,453 B，M09-B 全量门禁通过，进入 M09-C |
 | 微信小程序 | 已纳管微信原生模板，并完成顾客端订单、充值、权益明细、下单抵扣主体链路、保洁任务端照片上传/补做主体链路，以及管理员门店/房态/订单/代下单/验券/会员/员工/保洁/设备/经营统计 | `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 至 M08-D 连续 up/down/verify 计划、最小脱敏 seed、旧库 fixture、执行 CLI、验证结果门禁和 MySQL 8 集成测试；M09-A 事务并发与 M06-C/E-R1 协议落库均纳入同一往返测试 | `database/migrations/**`、`database/seeds/2026061601_m01b_minimal_seed.sql`、`backend/src/db/migration-runner.ts`、`backend/tests/mysql-migration-roundtrip.test.mjs` | WSL MySQL 8.4.10 已完成 144 up、124 verify、140 down；另实测插座十进制 `workInfo`、三类失败结果、closeReason 3-7 告警、温度冲突死信和复位口令脱敏 |
+| 数据库迁移 | 已形成 M01-B 至 M09-B 连续 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 已完成 149 up、128 verify、145 down；模板快照、照片版本、到期清理和免清洁策略实测通过 |
 | 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，仍需按模块迁移正式实现 |
@@ -24,7 +24,7 @@
 ## 状态校准
 
 - `docs/module-status.md` 中 M00 仍为 `PARTIAL` 是正确的：生产 Ubuntu 初始化、部署与运维验收尚未执行；后端、后台和小程序源码已在后续模块建立。
-- M01-M04 与 M07 已具备模块工程验收；M05、M06、M08 因真实厂商/硬件/生产条件保持 `PARTIAL`；M09-A-RECOVERY、M06-C/E-R1、M06-R-REGRESSION 与 M08-D-R1 已完成，当前按 V5.6 执行 M09-B，M10 尚未进入。
+- M01-M04 与 M07 已具备模块工程验收；M05、M06、M08 因真实厂商/硬件/生产条件保持 `PARTIAL`；M09-A/B、M06-C/E-R1、M06-R-REGRESSION 与 M08-D-R1 已完成，当前按 V5.6 执行 M09-C，M10 尚未进入。
 - 任何“目录存在”只能证明骨架存在，不能证明模块完成。
 
 ## Git 历史敏感信息核验
@@ -35,6 +35,6 @@
 
 ## 下一步
 
-1. 执行 M09-B：审计并复用既有照片上传、提交验收、驳回补做和免清洁链路，不建立第二套领域实现。
-2. 对照 V5.6 补齐图片数量/格式/大小、任务状态与权限、失败恢复、重复提交和回归测试缺口。
-3. M09-B 完成后进入 M09-C；M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线，不阻断内部主队列。
+1. 执行 M09-C：统一任务、负责人、协作者、免清洁、驳回、完成、待结算和已结算统计口径。
+2. 保证同一任务不可进入两张有效结算单，并发生成单赢家；结算撤销生成反向记录和明确状态历史，不物理删除。
+3. 页面、CSV 与 API 复用同一查询口径；M06-G 真实硬件联调继续等待外部条件，不阻断内部主队列。

docs/db-changelog/2026-08-10-M09-B-cleaning-rules.md

@@ -0,0 +1,11 @@
+# 2026-08-10 M09-B 清洁规则与照片验收
+
+- 版本：`2026081005_m09b_cleaning_rules`。
+- 新增 `qipai_cleaning_templates`：租户/门店/房间三级唯一作用范围，保存清洁要求、照片必传与数量、免清洁策略、版本、状态和创建/更新人。
+- 扩展 `qipai_cleaning_tasks`：固化模板 ID/版本、照片规则、免清洁策略和补做次数。模板变更不追改既有任务。
+- 新增 `qipai_cleaning_task_photos`：保存租户、任务、门店、上传人、隔离路径、URL、MIME、尺寸、哈希、状态、关联提交版本和保留期限。
+- 新增 `qipai_cleaning_task_submissions`：按任务版本唯一保存提交照片、备注、驳回原因、提交/验收人及时间，区分 `SUBMITTED`、`ACCEPTED`、`REJECTED`。
+- 未提交照片默认保留 7 天；提交照片状态变为 `ATTACHED` 并长期保留以支持返工前后追溯；清理采用孤儿领取、文件删除、数据库软删除三段式重试。
+- down：先删除提交与照片表，再移除任务外键/检查约束/快照列，最后删除模板表和迁移版本。
+- verify：检查三张新表、七个任务快照列、关键唯一索引和迁移版本。
+- WSL 原生临时副本、MySQL 8.4 完成 `up → verify → down → up → verify`：149 条 up、128 条 verify、145 条 down；临时数据库和账号已自动清理。

docs/devlogs/2026-08-10-M09-B-清洁规则与照片验收.md

@@ -0,0 +1,23 @@
+# 2026-08-10 M09-B 清洁规则与照片验收
+
+## 工程结果
+
+- 工程提交：`bc7cb8f`，已推送并验证远端 `main` 与本地 HEAD 一致。
+- 复用既有保洁任务状态机，新增租户/门店/房间模板解析和任务级规则快照；模板更新明确只影响新任务并写审计。
+- 小程序按任务快照限制照片最少/最多张数；上传端与服务端共同限制格式、大小和数量。
+- 图片声明 MIME、扩展名与实际解码格式必须一致，统一重编码 WebP 以移除 EXIF/ICC；路径按租户/门店隔离，上传记录失败时立即删除文件。
+- 任务照片资产与验收提交版本落库；提交 URL 必须属于同租户、同任务、同上传人。驳回原因、补做次数、旧照片和新照片可逐版查询，后台详情可预览并导出。
+- 未提交照片默认 7 天后可清理；清理失败保留孤儿记录并在五分钟后重试，已关联提交版本的照片不进入清理批次。
+- 免清洁由任务快照决定允许阶段；免清洁仍清零奖励、移除未结算成员且不进入结算。
+- 订单结束、取消和换房旧房间断电前重新读取最新订单；房间已有新订单时不发送取消任务或插座断电。
+
+## 验证证据
+
+- Windows `scripts/dev/windows/test-all.ps1`：65.7 秒，退出码 0；后端全测、迁移计划、管理员 typecheck/build/navigation、静态门禁、健康检查、敏感信息与仓库完整性均通过。
+- 管理员生产构建最大 JS 分块 `217,453 B`，继续低于 `500 KiB`；仅保留第三方 `@vueuse/core` PURE 注释位置警告，未隐藏 warning 阈值。
+- WSL 原生临时副本 + MySQL 8.4：149 up、128 verify、145 down 往返通过；实测模板快照不追改、驳回/通过照片版本并存、到期孤儿照片清理、任务级免清洁拒绝和既有事务并发场景。
+- `scripts/check-m09-b-cleaning-rules.mjs` 已加入全量脚本，固定迁移、图片安全、版本化验收和安全断电回归门禁。
+
+## 阶段结论
+
+`M09-B=DONE`。唯一执行游标进入 `M09-C`；真实微信转账、团购授权和硬件现场结果继续为 `BLOCKED_EXTERNAL`，不阻断内部统计与结算收口。

docs/feature-status.md

@@ -44,6 +44,8 @@
 
 > 2026-08-10 M08-D-R1：工程提交 `3faf868` 保留全部既有后台功能页，并将 12 个入口迁入 Vue Router 深链接、服务端菜单与 capability 双重守卫和路由级懒加载；401 单航班续期、刷新恢复和懒加载失败均有确定恢复边界。Element Plus 政策改为按需解析，最大 JS 分块从 923.28 KiB 降至 217,195 B，入口 gzip 74.94 KiB；375/768/1440 响应式实测、全仓回归、敏感信息与仓库完整性门禁通过。游标进入 M09-B。
 
+> 2026-08-10 M09-B：工程提交 `bc7cb8f` 为 `CLN-002`、`CLN-005` 补齐租户/门店/房间清洁模板与任务快照、照片格式/大小/数量和租户路径隔离、EXIF 移除、到期清理、返工版本与旧新照片追溯、任务级免清洁策略；订单结束/取消/换房断电前读取房间最新有效订单，避免新订单被旧任务关电。Windows 全量与 WSL MySQL 8.4 的 149 up、128 verify、145 down 往返通过，游标进入 M09-C。
+
 | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |

docs/module-status.md

@@ -2,16 +2,16 @@
 
 ```yaml
 execution_cursor:
-  current_module: M08
-  current_stage: M09-B
+  current_module: M09
+  current_stage: M09-C
   stage_status: DOING
-  last_completed_stage: M08-D-R1
-  next_stage: M09-C
-  last_engineering_commit: `3faf868`
+  last_completed_stage: M09-B
+  next_stage: M09-D1
+  last_engineering_commit: `bc7cb8f`
   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-10T20:58:40+08:00
+  updated_at: 2026-08-10T21:50:38+08:00
 ```
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |
@@ -25,6 +25,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 | `9b2f055` | docs/devlogs/2026-06-25-M08-B-保洁端.md | M09-A-RECOVERY 已完成事务与并发收口；当前执行 M09-B，复用既有任务照片、验收、驳回、免清洁和清洁规则链路做领域收口与缺口测试。 |
+| M09 保洁任务、结算、商品和库存 | DOING | `bc7cb8f` | docs/devlogs/2026-08-10-M09-B-清洁规则与照片验收.md | M09-A/B 已完成任务事务并发、三级模板与任务快照、图片安全/隔离/清理、版本化验收、免清洁策略和新订单安全断电；当前进入 M09-C，统一统计与结算口径、并发唯一性和撤销反向记录。 |
 | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |