qipai/docs/devlogs/2026-08-10-M08-D-Vue平台后台.md

# M08-D Vue 平台后台

## 2026-08-10 运营总览与工作区导航

- `ENGINEERING_DELTA=YES`
- 后台壳层从单一保洁页面升级为“运营总览/保洁运营”可切换工作区；访问令牌分为草稿和已保存值，避免输入过程中逐字符触发请求。
- 新增授权门店运营总览，支持 7/30/90 日周期，展示成功实收与预订金额、订单/活跃/完成、OWNER 下单会员、验券成功/失败、当前房态、支付渠道和每日收入趋势。
- 核心业务导航明确区分已可用的保洁运营与后续门店、订单、会员、设备、支付增量，不把未实现页面伪装成可用入口。
- 新增 `/admin-api/statistics`，与 `/app-api/management/statistics` 共享同一路由处理与仓储权限边界；前端只调用固定 `/admin-api` 基地址。
- 新增 `scripts/check-admin-m08-d.mjs` 并接入 Windows 全量门禁，覆盖页面、统计 API、响应式样式、可用模块导航和后台路由别名。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：64.6 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建、域名/敏感信息/仓库完整性全部通过。
- WSL 原生临时副本 + MySQL 8.4.10：28.3 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- 后端路由测试同时验证 `/app-api/management/statistics` 与 `/admin-api/statistics` 返回一致统计，并保留最长 93 天限制。
- Vue 生产构建成功；已知 Element Plus chunk 超过 500kB、参考 xjar 超过 100MB 和 WSL npm 7 个 high audit 项仍为既有非阻塞提示，未执行破坏性自动升级。

### 变更影响

- 数据库：无迁移、无新增表。
- API：新增后台经营统计别名，鉴权和统计口径不变。
- 后台：新增响应式运营总览与模块切换；保洁工作台功能保持不变。
- 部署：后端与后台静态产物有变化，未自动部署生产。
- 工程提交：`65f2e7c`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。运营总览与现有保洁工作区已接通；下一工程增量补门店与房间管理页面，不提前进入 M09。

## 2026-08-10 门店与房间管理

- `ENGINEERING_DELTA=YES`
- 新增响应式门店/房间工作区，支持授权门店搜索、营业状态筛选、详情、每周营业时段、Wi-Fi 配置状态、新增、编辑和归档。
- 房间管理支持房号/分类/标签搜索、房态筛选、完整整数分价格配置、标签/图片、启停、运营房态、停用时段和归档。
- 门店列表读取补充营业时段与 `wifiConfigured`，不返回 Wi-Fi 密码；更新接口允许省略 `wifiPassword` 并使用 `COALESCE` 保留原值，避免后台编辑清空既有密码。
- 所有写操作继续复用 M03 的租户、门店范围、capability 与审计边界，前端错误显示保留业务错误码和 traceId。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：63.4 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建、域名/敏感信息检查均通过。
- WSL 原生临时副本 + MySQL 8.4.10：26.5 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- `backend/tests/store-room.test.mjs` 新增营业时段、Wi-Fi 配置状态与省略密码更新断言；Vue 生产构建成功。
- 既有 Element Plus chunk 超过 500kB、参考 xjar 超过 100MB 和 WSL npm 7 个 high audit 项仍为非阻塞提示，未执行破坏性自动升级。

### 变更影响

- 数据库：无迁移、无新增表。
- API：`GET /admin-api/stores` 增加营业时段、Wi-Fi 配置状态及既有门店详情字段；`POST/PUT /admin-api/stores` 的 `wifiPassword` 可省略，更新省略时保持原值。
- 后台：新增门店/房间响应式管理入口和完整表单。
- 部署：后端与后台静态产物有变化，未自动部署生产。
- 工程提交：`1ca783e`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。门店与房间管理增量完成；下一工程增量补后台订单筛选、详情与运营处置页面。

## 2026-08-10 后台订单运营

- `ENGINEERING_DELTA=YES`
- 新增订单运营工作区，支持授权门店与十种订单状态筛选、分页、当前页 CSV 导出和页面内金额/待支付/进行中摘要。
- 新增订单详情抽屉和完整状态流水，展示门店、房间、时段、应收/实收、最近支付渠道/状态、操作来源、操作人、原因和 traceId。
- 接入服务端订单状态机处置、运营备注、时段调整、锁定价/当前价续费和同门店可用房间换房；前端只提交业务动作与原因，不提交目标状态或客户端计算金额。
- 新增 `/admin-api/orders` 列表/详情和 `/admin-api/orders/:orderId/history` 后台别名，与小程序管理端共享仓储的租户、门店范围、并发冲突和审计边界。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：63.5 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建、域名/敏感信息检查均通过。
- WSL 原生临时副本 + MySQL 8.4.10：26.9 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- `backend/tests/order-query.test.mjs` 覆盖后台列表/详情别名，`backend/tests/order-state.test.mjs` 覆盖后台状态历史别名；Vue 生产构建成功。
- 既有 Element Plus chunk 超过 500kB、参考 xjar 超过 100MB 和 WSL npm 7 个 high audit 项仍为非阻塞提示。

### 变更影响

- 数据库：无迁移、无新增表。
- API：新增订单列表、详情和状态历史的 `/admin-api` GET 别名；既有写接口与权限契约不变。
- 后台：新增订单筛选、导出、详情、状态流水和运营处置工作区。
- 部署：后端与后台静态产物有变化，未自动部署生产。
- 工程提交：`20a292e`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。订单运营增量完成；下一工程增量补支付、退款与分账运营页面。

## 2026-08-10 支付、退款与分账运营

- `ENGINEERING_DELTA=YES`
- 新增资金运营工作区，展示收款账户、已授权账户、分账接收方和近百笔分账金额，并可按门店范围筛选。
- 接入收款账户、凭据环境引用、授权状态、分账开关、脱敏接收方和全局/门店比例策略维护；页面不读取或回显私钥、APIv3 Key 和真实接收方标识。
- 接入近百笔分账记录、失败码、微信退款、微信账单请求和分账执行；退款金额、可退余额、比例总和、授权状态、生产 Mock 门禁和幂等均由服务端继续校验。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：62.8 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建、域名/敏感信息检查均通过。
- WSL 原生临时副本 + MySQL 8.4.10：26.5 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- Vue 生产构建成功；既有 Element Plus chunk 超过 500kB、参考 xjar 超过 100MB 和 WSL npm 7 个 high audit 项仍为非阻塞提示。

### 变更影响

- 数据库：无迁移、无新增表。
- API：无新后端路由；Vue 后台接入既有 `/admin-api/pay/**` 配置、退款、对账和分账接口。
- 后台：新增响应式资金运营入口，敏感凭据只接受环境引用。
- 部署：后台静态产物有变化，未自动部署生产。
- 工程提交：`4eac99d`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。支付、退款与分账运营增量完成；下一工程增量补团购与第三方平台运营页面。

## 2026-08-10 团购与第三方平台运营

- `ENGINEERING_DELTA=YES`
- 新增第三方渠道工作区，支持美团、大众点评、抖音、快手的直订记录、待映射队列、核销记录及平台/门店/状态筛选。
- 接入平台配置和门店/房间资源映射；凭据只登记环境引用，读取接口过滤 secret、token、password、private key、API key 和 credential 等敏感设置键。
- 新增管理员 API 与人工验券别名，继续复用服务端订单金额、租户权限、授权门店、幂等键、券码 SHA-256 和脱敏显示边界。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：63.3 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建通过；暂存后仓库完整性、敏感信息和空白门禁复核通过。
- WSL 原生临时副本 + MySQL 8.4.10：26.2 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- `backend/tests/third-party.test.mjs` 覆盖管理员 API 验券别名与安全配置读取；Vue 生产构建成功。
- 既有 Element Plus chunk 超过 500kB、参考 xjar 超过 100MB 和 WSL npm 7 个 high audit 项仍为非阻塞提示，未执行破坏性自动升级。

### 变更影响

- 数据库：无迁移、无新增表。
- API：新增 `GET /admin-api/third-party/setup`、`POST /admin-api/group-vouchers/redeem` 和既有人工验券的管理端对称别名；敏感配置不读取返回。
- 后台：新增响应式第三方渠道运营入口，覆盖记录、配置、映射和验券。
- 部署：后端与后台静态产物有变化，未自动部署生产。
- 工程提交：`7b97808`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。团购与第三方平台运营增量完成；下一工程增量补会员与员工用户管理页面。

## 2026-08-10 会员与员工用户管理

- `ENGINEERING_DELTA=YES`
- 新增会员与员工用户工作区；会员支持昵称/手机号/ID、状态筛选，展示现金/赠送余额、券、套餐、订单、消费、充值、注册/登录及最近钱包流水。
- 员工支持姓名/手机号/ID、角色和状态筛选，以及创建、角色/门店授权、资料备注、停启和活动会话重置；权限变更继续即时撤销会话并记录审计。
- 后台员工“全部角色”查询新增受限的 `userType=STAFF` 契约，避免通用用户列表将顾客混入员工运营视图。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：63.5 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建通过；暂存后仓库完整性、敏感信息和空白门禁复核通过。
- WSL 原生临时副本 + MySQL 8.4.10：25.9 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- `backend/tests/user-management.test.mjs` 新增 STAFF-only 后台列表断言，会员路由回归与 Vue 生产构建通过。
- 既有 Element Plus chunk 超过 500kB、参考 xjar 超过 100MB 和 WSL npm 7 个 high audit 项仍为非阻塞提示。

### 变更影响

- 数据库：无迁移、无新增表。
- API：`GET /admin-api/users` 新增可选且只允许 `STAFF` 的 `userType` 查询参数；其他会员与员工接口不变。
- 后台：新增响应式会员/员工入口，继续只显示脱敏手机号和 IP。
- 部署：后端与后台静态产物有变化，未自动部署生产。
- 工程提交：`93f06d2`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。会员与员工用户管理增量完成；既有保洁工作台已覆盖计划项，下一工程增量补设备运营页面。

## 2026-08-10 设备运营后台

- `ENGINEERING_DELTA=YES`
- 启用原先禁用的设备导航，新增设备资产、控制通道、Sub-1G 父子拓扑、开放告警和维护记录工作区。
- 接入设备入库、控制箱/智慧插座通道绑定、701C/701G 门锁父子绑定、巡检/维修/更换记录。
- 接入临时开门、全屋通断电和智慧插座通断电；危险操作二次确认，结果明确为命令受理并等待 ACK，不把 MQTT 发布当作现场成功。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：63.8 秒退出码 0；后端全测、M08-B/C/D 静态门禁、Vue TypeScript 与生产构建通过；暂存后完整性、敏感信息和空白门禁通过。
- WSL 原生临时副本 + MySQL 8.4.10：25.8 秒退出码 0，`up → verify → down → up → verify` 完成，136 条 up、114 条 verify、130 条 down。
- `backend/tests/device.test.mjs`、`device-control.test.mjs` 与 Vue 生产构建通过；既有大 chunk、大参考文件和 7 个 high audit 项仍为非阻塞提示。

### 变更影响

- 数据库/API：无迁移、无新路由，Vue 后台复用既有设备资产、拓扑、维护和控制 API。
- 后台：新增响应式设备运营入口。
- 部署：后台静态产物有变化，未自动部署生产。
- 工程提交：`5c9fd69`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。设备运营增量完成；下一工程增量补多小程序与租户配置页面。

## 2026-08-10 多小程序与租户配置

- `ENGINEERING_DELTA=YES`
- 新增多小程序/租户品牌工作区，覆盖应用绑定、启停、默认应用、品牌、Logo、主题、服务电话、分享信息、默认门店和非敏感扩展配置。
- 新增租户范围管理 API；租户管理员只能更新已有绑定，新增逻辑应用/绑定要求 `platform.manage` 或平台管理员角色，默认门店必须属于当前租户，写操作进入审计。
- AppSecret、微信支付密钥和证书继续只从服务端环境变量读取，不在数据库配置、API schema 或前端表单出现。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：89.7 秒退出码 0；新增平台管理测试明确 PASS，后端全测、静态门禁与 Vue 生产构建通过；暂存后完整性、敏感信息和空白门禁通过。
- WSL 原生临时副本 + MySQL 8.4.10：25.0 秒退出码 0，136 条 up、114 条 verify、130 条 down。
- 既有大 chunk、大参考文件和 7 个 high audit 项仍为非阻塞提示。

### 变更影响

- 数据库：无迁移，复用 M02-A 应用、绑定与租户配置表及既有审计表。
- API：新增 `GET /admin-api/platform-apps`、`PUT /admin-api/platform-apps/:id/config`、`POST /admin-api/platform-apps/bind`。
- 后台：新增响应式多应用租户配置入口；部署包含后端与后台静态产物变化，未自动部署生产。
- 工程提交：`c7f27bc`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。多小程序与租户配置增量完成；下一工程增量补广告与装修管理页面。

## 2026-08-10 广告与装修管理

- `ENGINEERING_DELTA=YES`
- 新增媒体素材、门店装修和广告投放三工作区；支持图片上传/预览、公共/门店范围、组件化装修草稿、版本回看、发布/历史回滚，以及广告新增、编辑、排期、排序和上下架。
- 新增素材与装修列表、广告更新 API；门店运营不能创建租户公共素材，不能编辑租户/平台或其他门店广告，门店广告只能引用租户公共或当前门店素材。
- 新增 `2026081002_m08d_content_asset_scope`，以生成列把素材唯一键从租户级修正为租户 + 公共/门店作用域 + checksum；同作用域继续去重，不同门店不再错误复用资产。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：89.7 秒退出码 0；后端全测、M08-D 静态门禁、Vue TypeScript/生产构建、仓库完整性与密钥扫描通过。
- WSL 原生临时副本 + MySQL 8.4.10：23.5 秒退出码 0；`up → verify → down → up → verify` 完成，138 条 up、117 条 verify、134 条 down。
- MySQL 实测同门店同 checksum 幂等去重、同 checksum 公共/门店素材独立、装修列表/发布归档、广告更新和素材 ID 回读。
- 既有 Element Plus 大 chunk、参考 xjar 超过 100MB 和 WSL npm audit 提示保持非阻塞，未执行破坏性自动升级。

### 变更影响

- 数据库：新增可逆素材作用域唯一键迁移；down 先把广告引用归并到保留资产，再恢复历史租户级唯一键。
- API：新增素材/装修读取和广告更新，广告列表补 `imageAssetId`。
- 后台：新增响应式广告装修入口；部署包含后端、后台静态产物和迁移变化，未自动部署生产。
- 工程提交：`c1c0242`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。广告与装修管理增量完成；下一工程增量补加盟申请、分派和跟进运营。

## 2026-08-10 加盟申请与跟进运营

- `ENGINEERING_DELTA=YES`
- 小程序首页新增加盟入口和申请页，按品牌 AppID 对应租户提交城市、联系人、电话、留言和客户端幂等号；重复提交返回原申请编号。
- Vue 后台新增加盟队列，支持关键字/状态/负责人筛选、分页、详情、同租户有效员工分派、下次跟进、电话/微信/面谈/备注记录和完整历史。
- 后端新增公开提交与管理员读取/分派/跟进 API；租户管理员跨租户请求拒绝，平台管理员跨租户必须显式指定 tenantId，状态跳级在事务内拒绝。
- 新增 `2026081003_m08d_franchise_leads` 两表迁移；业务联系电话不进入审计 metadata，签约状态不冒充真实租户开通。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：66.3 秒退出码 0；后端全测、加盟路由、M08-A/B/C/D 静态门禁、Vue 生产构建与仓库门禁通过。
- WSL 原生临时副本 + MySQL 8.4.10：23.7 秒退出码 0；141 条 up、120 条 verify、137 条 down 完成 `up → verify → down → up → verify`。
- MySQL 实测重复申请幂等、有效员工分派、无效负责人拒绝、首次联系流转、非法跳级回滚、跟进历史和审计不含联系电话。
- 既有 Element Plus 大 chunk、参考 xjar 超过 100MB 和 npm audit 提示保持非阻塞。

### 变更影响

- 数据库：新增加盟申请与跟进历史表及可逆迁移。
- API：新增 1 个小程序提交、2 个后台读取和 2 个后台写接口。
- 小程序/后台：新增加盟申请页与响应式加盟运营工作区；未自动部署生产。
- 工程提交：`aa4a6bd`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。加盟申请与跟进运营完成；下一工程增量补审计日志与系统配置。

## 2026-08-10 审计日志与系统配置

- `ENGINEERING_DELTA=YES`
- 新增租户级审计查询仓储与 API，支持操作、资源类型、操作人、关键字、时间窗和分页；响应掩码 IPv4/IPv6，并递归过滤 token、密码、密钥、证书、手机号、OpenID、接收方和券码等 metadata。
- 新增系统概况和租户配置 API，展示门店、用户、活动会话、应用绑定、当日审计与最新迁移；租户管理员只能更新本租户名称和有效 IANA 时区，租户启停及跨租户目标只允许平台管理员且必须显式指定。
- Vue 后台新增“日志配置”工作区，提供筛选、脱敏详情、当前页 CSV 导出、系统指标、租户配置和 schema 迁移状态。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：65.6 秒退出码 0；后端全测、系统运营路由、M08-D 静态门禁、Vue TypeScript/生产构建通过。提交前新增文件触发的 untracked 提示在工程提交后已消除。
- WSL 原生临时副本 + MySQL 8.4.10：23.5 秒退出码 0；141 条 up、120 条 verify、137 条 down 完成 `up → verify → down → up → verify`。
- MySQL 实测租户范围、审计筛选、递归手机号/API key 脱敏、IP 掩码、系统概况、配置更新和操作人审计；路由测试覆盖跨租户拒绝、366 天上限、无效时区、租户管理员启停拒绝和平台显式跨租户更新。
- 既有 Element Plus 大 chunk 和参考 xjar 超 100MB 警告保持非阻塞，未执行破坏性自动升级。

### 变更影响

- 数据库：无迁移；复用租户、会话、应用绑定、迁移历史和审计表。
- API：新增 `GET /admin-api/audit-logs`、`GET /admin-api/system/overview`、`PUT /admin-api/system/tenant`。
- 后台：新增响应式安全审计与系统配置入口；未自动部署生产。
- 工程提交：`7e170e8`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 保持 `DOING`。审计日志与系统配置增量完成；下一工程增量补后台登录、访问令牌续期、401 清理和当前会话入口，替换手工粘贴令牌。

## 2026-08-10 后台登录与可撤销会话

- `ENGINEERING_DELTA=YES`
- 新增租户代码、后台账号和密码登录页，替换手工粘贴访问令牌；恢复页面时通过 `/auth/me` 重新取得服务端权限，菜单按 roles/capabilities 生成。
- 新增 scrypt 密码凭据、连续失败锁定、成功/失败审计、短期 JWT、随机刷新令牌 SHA-256 存储和并发安全单次轮换；注销、密码更新、用户禁用及权限版本变化继续即时撤销会话。
- Vue 请求层新增 request ID、401 单飞续期、令牌轮换同步与失败清理；员工工作区可由租户管理员设置唯一登录名和强密码，旧会话自动撤销。

### 测试证据

- Windows `scripts/dev/windows/test-all.ps1`：34.2 秒完成后端全测、迁移计划、M08 静态门禁和 Vue TypeScript/生产构建；新增文件暂存后，直接执行仓库完整性、敏感信息和空白门禁均通过。
- WSL 原生临时副本 + MySQL 8.4.10：23.7 秒退出码 0；144 条 up、124 条 verify、140 条 down 完成 `up → verify → down → up → verify`。
- MySQL 实测真实 scrypt 凭据、错误密码失败审计、成功登录、刷新令牌轮换、旧令牌拒绝和数据库无明文密码；路由测试覆盖锁定、当前会话、弱密码拒绝、凭据设置及注销。
- Windows 参考包检查结束时曾遇临时解压目录占用提示，不影响仓库、构建或测试；既有 Element Plus 大 chunk 和参考 xjar 超 100MB 仍为非阻塞提示。

### 变更影响

- 数据库：新增 `2026081004_m08d_admin_password_auth` 可逆迁移，扩展既有会话表并新增后台凭据表。
- API：新增后台登录、刷新、当前会话、注销和 STAFF 登录凭据设置接口。
- 后台：正式登录页替换手工令牌；菜单和当前用户由服务端会话驱动，401 自动续期或安全退出。
- 部署：后端、后台静态产物和迁移有变化；未自动部署生产。
- 工程提交：`0511008`，已推送并验证 `HEAD == origin/main`。

### 状态

M08-D 可独立工程内容完成。M08 真实微信、团购和硬件现场验收继续保持 `PARTIAL/BLOCKED_EXTERNAL`，执行游标按规则进入 M09-A 保洁任务状态机复核与补齐。