docs(M08-C): 完成管理员小程序模块

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` 为准。
 
-- 当前执行游标：`M08-C`（DOING）；`M08-B` 的可独立工程内容已完成，真实商户、微信和硬件现场验收保持 `BLOCKED_EXTERNAL`。
+- 当前执行游标：`M08-D`（DOING）；`M08-C` 的可独立工程内容已完成，真实团购商家授权、微信和硬件现场验收保持 `BLOCKED_EXTERNAL`。
-- 最近工程提交：`65932a8` / `M08-C保洁与设备运营`，管理员可查看授权门店保洁任务/统计并验收、驳回或免清洁，也可查看设备拓扑、告警、维护状态并执行带操作人审计的临时开门和电控。
+- 最近工程提交：`ce52f07` / `M08-C管理员验券与经营统计`，管理员可在授权门店扫码或输入脱敏留存的团购券，查看核销归因，并查看按成功支付口径聚合的门店经营统计。
-- 下一工程目标：继续 M08-C，补管理员验券与门店经营统计。
+- 下一工程目标：进入 M08-D，补 Vue 平台后台的运营总览与核心业务导航。
 
 ## 版本递进
 

docs/api-changelog/2026-08-10-M08-C-management.md

@@ -40,3 +40,14 @@
 | POST | `/app-api/management/device-control/*` | `device.write`，设备门店在授权范围 | 复用既有控制箱、Sub-1G 和智能插座命令服务；小程序当前接入临时开门、全屋电控和插座开关。 |
 
 管理端设备写操作在命令创建前写入 `DEVICE_COMMAND_REQUESTED` 审计，记录实际账号类型/ID、traceId、门店、房间、设备、命令类型和可选订单；设备离线、未绑定或跨店仍由服务端拒绝。
+
+## 管理员验券与门店经营统计增量
+
+| 方法 | 路径 | 权限 | 结果 |
+|---|---|---|---|
+| POST | `/app-api/management/group-vouchers/redeem` | `store.operation.write` 且订单门店在授权范围，或租户/平台管理权限 | 对待支付订单执行在线团购验券；应付金额始终由服务端订单推导，支持 `clientRequestId` 幂等。 |
+| POST | `/app-api/management/group-vouchers/redeem-manual` | 同上 | 显式人工确认验券；提交金额必须精确等于服务端未付金额，并记录操作人和备注。 |
+| GET | `/app-api/management/third-party/records` | 登录管理账号并受租户/授权门店范围约束 | 按 `storeId/provider/status` 查询直订与核销记录，只返回券码掩码、操作人、结果和时间。 |
+| GET | `/app-api/management/statistics` | `store.operation.read` 且门店在授权范围，或租户/平台管理权限 | 查询最长 93 天的订单、会员、成功收款渠道、每日收入、当前房态和验券统计。 |
+
+经营统计中的实收金额只累计 `qipai_payments.status=SUCCEEDED` 且 `paid_at` 落在区间内的记录；订单数和预订金额按订单 `created_at` 口径统计，当前房态为查询时快照。小程序提供近 7/30/90 日切换、扫码/手输券码、待支付订单选择与最近脱敏核销记录。

docs/current-baseline.md

@@ -2,7 +2,7 @@
 
 > V5.0 首次核验日期：2026-06-16  
 > audited_commit: `4ae9296`
-> next_engineering_target: 继续 M08-C 管理员验券与门店经营统计
+> next_engineering_target: 进入 M08-D Vue 平台后台，先补运营总览与核心业务导航
 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。
 
 ## 总体结论
@@ -12,8 +12,8 @@
 | 总纲版本 | V5.4 已成为当前权威总纲，旧版已保留为历史备份 | 根目录存在 `V5.4.md` 及旧版总纲 | 可继续按 V5.4 的执行游标开发 |
 | Git 远端 | `origin=ssh://git@git.txyundm.cn:2222/panda/qipai.git`，分支 `main` | `git rev-list main...origin/main` 为 `0 0` | 本地与远端同步 |
 | 正式后端 | 已完成 Fastify、迁移兼容、outbox/worker、多应用租户、微信身份/会话，以及六角色 RBAC 和门店范围 | `backend/src/auth/**`、`database/migrations/2026061805_m02c_rbac.*.sql`、`backend/tests/**` | M01、M02-A/B/C DONE；MySQL 已验证 capability 和跨租户门店授权拒绝；下一阶段 M02-D |
-| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 工程，并接入 M08-B 保洁任务、免清洁标记、批量免清洁、免清洁统计展示、协作者管理、结算详情、统计明细、每日趋势、保洁员资料管理、手机号维护、微信绑定状态、微信转账预检界面和现场联调执行记录追溯 | `admin/src/App.vue`、`admin/src/components/CleaningTasksPanel.vue`、`admin/src/components/CleaningSettlementsPanel.vue`、`admin/src/components/CleaningStatisticsPanel.vue`、`admin/src/components/CleanersPanel.vue`、`admin/src/components/CleaningFieldHandoffPanel.vue`、`scripts/check-admin-m08-b.mjs` | M08-B 可独立工程内容已完成；联调检查项支持多次执行历史、搜索、快照、报告、CSV 和归档，真实商户/微信/硬件现场验收保持外部阻塞；执行游标进入 M08-C |
+| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 工程，并接入 M08-B 保洁任务、免清洁标记、批量免清洁、免清洁统计展示、协作者管理、结算详情、统计明细、每日趋势、保洁员资料管理、手机号维护、微信绑定状态、微信转账预检界面和现场联调执行记录追溯 | `admin/src/App.vue`、`admin/src/components/CleaningTasksPanel.vue`、`admin/src/components/CleaningSettlementsPanel.vue`、`admin/src/components/CleaningStatisticsPanel.vue`、`admin/src/components/CleanersPanel.vue`、`admin/src/components/CleaningFieldHandoffPanel.vue`、`scripts/check-admin-m08-b.mjs` | M08-B 可独立工程内容已完成；联调检查项支持多次执行历史、搜索、快照、报告、CSV 和归档，真实商户/微信/硬件现场验收保持外部阻塞；M08-C 完成后执行游标进入 M08-D，继续扩展平台后台完整业务 |
-| 微信小程序 | 已纳管微信原生模板，并完成顾客端订单、充值、权益明细、下单抵扣主体链路、保洁任务端照片上传/补做主体链路，以及管理员门店/房态/订单/代下单/会员/员工/保洁/设备运营 | `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 PARTIAL；M08-A 顾客端工程闭环按外部阻塞旁路；M08-B 可独立工程内容已完成；M08-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 PARTIAL；M08-A 顾客端工程闭环按外部阻塞旁路；M08-B 可独立工程内容已完成；M08-C 可独立工程内容已完成并通过 Windows 与 MySQL 模块回归，游标进入 M08-D；真实团购、微信和硬件现场验收保持外部阻塞 |
 | 数据库迁移 | 已新增 M01-B 核心 schema up/down/verify SQL、最小脱敏 seed、旧库结构 fixture、迁移计划/执行 CLI、验证结果数量门禁和 MySQL 8 集成测试 | `database/migrations/2026061601_m01b_core_schema.*.sql`、`database/seeds/2026061601_m01b_minimal_seed.sql`、`database/fixtures/2026061801_m01b_legacy_schema.sql`、`backend/src/db/migration-runner.ts`、`backend/tests/mysql-migration-roundtrip.test.mjs` | M01-B DONE；WSL MySQL 8.4.9 已验证 8 条旧库 fixture、11 条 up、3 条 verify、10 条 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 后接入 |
@@ -35,6 +35,6 @@
 
 ## 下一步
 
-1. 继续 M08-C：在已完成门店概况、授权房态、订单筛选/处置/备注、管理员代下单、会员/员工概况、保洁任务和设备临时控制基础上，补管理员验券与门店经营统计。
+1. 进入 M08-D：在既有 Vue3 后台和保洁运营工作台基础上，先补平台/租户/门店运营总览与核心业务导航。
-2. 继续复用 M03 门店发现、M04 订单、M05 支付、M06 设备联动和 M07 会员营销后端能力，不重复初始化小程序。
+2. 继续复用 M02 权限、M03 门店、M04 订单、M05 支付/团购、M06 设备和 M07 会员能力，不重复初始化后台工程。
 3. M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线。

docs/db-changelog/2026-08-10-M08-C-management.md

@@ -28,3 +28,11 @@
 - 管理员设备命令在既有 `qipai_audit_logs` 写入 `DEVICE_COMMAND_REQUESTED`，actor 记录真实管理员/员工/顾客或系统来源，metadata 记录门店、房间、设备、设备类型、命令类型和可选订单。
 - 审计发生在设备命令创建/发布前；命令最终状态继续以 `qipai_iot_commands` 的 `PUBLISHED/ACKED/FAILED/TIMEOUT` 及设备回包为准，不把“已发布”表述为“设备已执行”。
 - WSL MySQL 8.4.10 已实际验证管理员临时开门的 IoT 命令落库、MQTT Mock 发布和操作人审计归因，并完成 136 up、114 verify、130 down 的完整往返。
+
+## 管理员验券与门店经营统计增量
+
+- 无 schema 迁移，复用 `qipai_group_vouchers`、`qipai_group_redemptions`、`qipai_payments`、`qipai_orders`、`qipai_rooms` 与 `qipai_order_user_access`。
+- 在线与手工管理员验券均只保存券码 SHA-256、掩码、操作人、门店、订单、平台结果和幂等请求号；原始券码不落库、不进入记录查询响应。
+- 验券成功沿用事务内团购支付入账，生成 `GROUP_BUY` 成功支付、更新订单实付与状态、消耗房间预占并写订单状态历史；重复请求或重复券不重复入账。
+- 经营统计按租户和门店参数化查询；实收仅取成功支付的 `paid_at` 区间，订单/会员按订单 `created_at` 区间，验券按核销 `created_at` 区间，房态为当前快照。
+- WSL MySQL 8.4.10 已验证管理员验券操作人/门店归因、券码脱敏、订单与成功支付统计、`GROUP_BUY` 渠道聚合，并完成 136 up、114 verify、130 down 的完整往返。

docs/devlogs/2026-08-10-M08-C-管理员员工端.md

@@ -109,3 +109,31 @@ M08-C 保持 `DOING`。会员检索、聚合详情、STAFF 员工概况和代下
 ### 状态
 
 M08-C 保持 `DOING`。保洁任务处置、设备运营概况和带操作人审计的临时开门/电控已完成；下一工程增量继续管理员验券与门店经营统计，不移动到 M08-D。
+
+## 2026-08-10 管理员验券与门店经营统计
+
+- `ENGINEERING_DELTA=YES`
+- 管理员小程序新增“验券与经营”页，支持授权门店切换、近 7/30/90 日统计、平台选择、待支付订单选择、微信扫码或手输券码，以及明确标注的人工确认验券。
+- 新增管理端在线验券、人工验券和第三方记录别名；在线验券的应付金额完全由服务端订单推导，人工验券金额必须与未付金额精确一致，所有写操作继续要求门店写权限。
+- 核销记录按租户、授权门店、平台和状态筛选，返回券码掩码、操作人、结果和完成时间；原始券码只参与请求，数据库继续只保存 SHA-256 与掩码。
+- 新增门店经营统计仓储与 `/app-api/management/statistics`，最长查询 93 天；订单、会员、成功支付渠道/每日收入、当前房态和验券汇总均使用明确时间口径与服务端门店范围。
+- 实收金额只累计成功支付，不把未支付订单总价当收入；团购验券成功复用既有事务支付入账和订单状态历史，重复请求继续由 `clientRequestId` 幂等保护。
+
+### 测试证据
+
+- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1`：64 秒退出码 0；仓库完整性、敏感信息、后端全量、M08-C 静态验收、迁移计划和 Vue 后台生产构建全部通过。
+- WSL 原生临时副本 + MySQL 8.4.10：首次准确发现测试订单超过 30 天提前窗口，修正后又识别窄统计区间的会话时区边界；改为窗口内非冲突订单和跨日确定性区间后，`up → verify → down → up → verify` 通过，136 条 up、114 条 verify、130 条 down。
+- MySQL 实际验证管理员验券成功、操作人/门店归因、券码掩码不泄露原值、两笔成功核销、成功支付实收与 `GROUP_BUY` 渠道聚合。
+- 路由/服务测试覆盖管理端在线与人工验券、记录筛选参数透传、统计读取、最长 93 天限制和跨门店 403。
+- 已知非阻塞提示：参考目录既有 xjar 超过 100MB；Element Plus 产物 chunk 超过 500kB；WSL `npm ci` 报告 7 个 high audit 项及 allow-scripts 提示，未执行破坏性自动升级。
+
+### 变更影响
+
+- 数据库：无 schema 迁移；新增运行时管理员核销、团购成功支付和统计读取行为。
+- API：新增 4 个小程序管理端点，并扩展第三方记录的 `storeId/provider/status` 服务端筛选。
+- 部署：后端与小程序有变化，数据库无迁移；未自动部署生产。
+- 工程提交：`ce52f07`，已推送并验证 `HEAD == origin/main`。
+
+### 状态
+
+M08-C 的可独立工程范围已完成并通过模块级回归，游标进入 `M08-D`。真实团购平台授权、微信后台与硬件现场结果继续保持 `BLOCKED_EXTERNAL`，不把 Mock/发布状态表述为真实厂商或设备执行成功。

docs/feature-status.md

@@ -12,6 +12,8 @@
 
 > 2026-08-10 M08-C 增量：工程提交 `65932a8` 为 `CLN-002`、`CLN-003`、`CLN-005`、`DEV-003`、`ROOM-002`、`ADM-001` 补管理员保洁与设备运营页；授权门店可查看保洁任务/统计并验收、驳回、免清洁，查看设备拓扑/告警/维护并临时开门、控制箱/插座电控。设备命令新增实际操作人审计归因，Windows 全量与 WSL MySQL 8.4.10 往返通过。M08-C 继续管理员验券与经营统计。
 
+> 2026-08-10 M08-C 增量：工程提交 `ce52f07` 为 `GRP-003`、`REP-001`、`ADM-001` 补管理员扫码/手输验券、脱敏核销记录和门店 7/30/90 日经营统计；金额由服务端订单推导，写权限与门店范围、操作人归因、券码哈希/掩码和成功支付统计口径均通过 Windows 全量与 WSL MySQL 8.4.10 往返。M08-C 可独立工程内容完成，游标进入 M08-D。
+
 | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 |
 |---|---|---|---|---|---|---|---|
 | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 |
@@ -54,7 +56,9 @@
 | MEM-001 | 会员管理 | M07-D/M08 | PARTIAL | `7446852` | 已实现后台会员聚合查询服务和 `/admin-api/members`、`/admin-api/members/:id`；新增顾客端 `/app-api/profile` 和小程序个人中心，可查看注册/最近登录、订单数、消费额、余额、充值、优惠券、套餐和最近钱包流水，手机号脱敏，租户/门店范围及本人读取通过测试。 | 管理员赠券、余额人工调整、禁用、备注和后台前端页面需在 M09/M08 管理端接入并复用既有审计能力。 | M08-A 继续补顾客端权益明细；M09 接入后台会员管理页面。 |
 | 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 模式。 |
+| GRP-003 | 管理员验券 | M05-C/M08 | PARTIAL | `ce52f07` | 已提供管理员小程序扫码/手输券码、在线核销、显式人工确认、待支付订单选择和最近核销记录；金额由服务端订单未付金额推导，写权限叠加授权门店，记录保留操作人/门店/平台结果，券码仅存 SHA-256 和掩码；Windows 全量与 WSL MySQL 8.4.10 实测通过。 | 缺美团/抖音/快手真实商家 API 授权，未执行厂商真实核销。 | 取得授权后配置 API 模式并执行真实验券。 |
+| ADM-001 | 管理员小程序模式 | M08/M06 | PARTIAL | `ce52f07` | 已完成角色入口、授权门店概况/房态、订单处置与代下单、会员/员工概况、保洁验收、设备状态、临时开门/电控、管理员验券和门店经营统计；按钮按 capability 展示，服务端重复校验租户、门店与写权限，关键写操作保留实际操作人审计。 | 真实团购商家、微信和硬件现场验收条件未提供。 | M08-D 继续平台后台；具备外部条件后补真机与现场验收。 |
+| REP-001 | 数据统计报表 | M10/M08 | PARTIAL | `ce52f07` | 新增门店 7/30/90 日经营统计，返回订单总量/状态/预订额、付费会员、成功支付实收与渠道、每日收入、当前房态、验券成功/失败；最长查询 93 天，租户与门店范围由服务端校验，MySQL 实测 `GROUP_BUY` 渠道与成功支付口径。 | 尚缺全门店汇总、自定义导出、使用率/使用时长和生产数据复算验收。 | M08-D/M10 扩展平台统计、导出和指标口径文档。 |
 | FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `1680d73` | 已实现租户/门店收款账户、商户号、环境凭据引用、分账授权状态、接收方哈希脱敏、比例总和校验、支付后幂等分账和明细查询；未授权不能开启，生产环境 Mock 强制关闭。 | 缺微信支付服务商和分账权限，尚未执行真实分账。 | M10/M08 补加盟流程与界面；取得权限后执行真实分账与对账。 |
 | BKG-007 | 后台微信支付配置 | M05-D/M08 | PARTIAL | `M08-B微信转账预检拦截增量` | 已提供收款账户、分账接收方、门店/全局比例策略和授权状态 API；私钥、APIv3 Key 和接收方真实标识只使用环境引用；M08-B 新增保洁结算微信转账预检，后台可查看并导出脱敏商户号、凭据引用、授权状态、账户范围、场景 ID、报备项数量、通知地址、平台证书数量、保洁员 openid 和检查项是否满足真实转账前置条件；真实 API 转账弹窗会自动执行预检，存在 FAIL 阻断项时禁用发起。 | 真实商户与服务商授权、微信后台场景报备和生产小额转账仍需现场联调。 | M08/M09 接入更完整支付配置页面；授权后完成生产验收。 |
 | DEV-003 | 设备管理 | M06-B/M08 | PARTIAL | `9144fa8` | 已实现 DeviceID/IMEI/ICCID/型号/固件/信号/能力资产，控制箱通道、智慧插座负载、Sub-1G 父子拓扑、状态快照、开放告警和维护记录查询；插座过载、过温、过流、过压/欠压、功率和温度阈值告警已接入；门店数据范围生效。 | 尚无后台/手机页面，真实硬件在线/计量仍需 M06-G 实物更新。 | M06-F 接入订单自动联动；M08 实现响应式界面。 |

docs/module-status.md

@@ -3,15 +3,15 @@
 ```yaml
 execution_cursor:
   current_module: M08
-  current_stage: M08-C
+  current_stage: M08-D
   stage_status: DOING
-  last_completed_stage: M07-D
+  last_completed_stage: M08-C
-  next_stage: M08-C
+  next_stage: M08-D
-  last_engineering_commit: `65932a8`
+  last_engineering_commit: `ce52f07`
   last_push_verified: true
   base_branch: main
-  blocked_reason: "M08-A 真机合法域名、真实微信支付和实物开门验证缺微信后台/商户/硬件现场条件；M08-B 可独立工程内容已完成并补齐多次现场执行记录追溯，真实商户凭据、微信后台配置、生产小额转账和实物硬件结果保持 BLOCKED_EXTERNAL，已按规则旁路进入 M08-C。M06-G 真实硬件联调仍缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线。"
+  blocked_reason: "M08-A 真机合法域名、真实微信支付和实物开门验证缺微信后台/商户/硬件现场条件；M08-B 可独立工程内容已完成，真实商户凭据、微信后台配置、生产小额转账和实物硬件结果保持 BLOCKED_EXTERNAL；M08-C 可独立工程内容已完成，真实美团/抖音/快手商家授权与真机验券保持 BLOCKED_EXTERNAL，已按规则旁路进入 M08-D。M06-G 真实硬件联调仍缺生产 MQTT 账号/ACL、DeviceID、控制箱、门锁、插座和现场配线。"
-  updated_at: 2026-08-10T10:52:16+08:00
+  updated_at: 2026-08-10T11:09:47+08:00
 ```
 
 | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 |