Codex
140 lines
13 KiB
Markdown
140 lines
13 KiB
Markdown
# M08-C 管理员/员工端
|
||
|
||
## 2026-08-10 门店概况、房态与订单总览
|
||
|
||
- `ENGINEERING_DELTA=YES`
|
||
- 同一微信小程序根据 `/app-api/auth/me` 的角色动态展示“门店管理”入口；`STAFF`、`STORE_ADMIN`、`TENANT_ADMIN`、`PLATFORM_ADMIN` 可进入，保洁角色继续使用独立任务入口。
|
||
- 新增门店运营页，按授权门店切换，展示房间总数、空闲、占用、待处理和活跃订单，并列出完整房态和近期订单。
|
||
- 新增 `/app-api/management/stores`、`/app-api/management/stores/:storeId/rooms` 和 `/app-api/management/rooms/:id/status`；读取要求 `store.operation.read`，房态调整和启停要求 `store.operation.write` 或租户/平台管理权限。
|
||
- 房态写操作记录 `ROOM_STATUS_UPDATED` 审计日志，metadata 包含门店、配置状态、运营状态和操作原因。
|
||
- 新增 `2026081001_m08c_staff_management_access` up/down/verify，为既有 STAFF 角色补 `profile.read`、`store.operation.read` 最小只读权限；后续登录动态补权逻辑同步更新。
|
||
- 新增 `scripts/check-miniapp-m08-c.mjs` 并接入 Windows 全量门禁，覆盖角色入口、页面注册、管理 API、只读/可写按钮和迁移。
|
||
- WSL MySQL 8.4.10 往返期间发现并修复两处既有内部问题：M08-A 充值迁移验证的 5 列/2 索引期望漏项导致 M08-B 规则错位；定价仓储误读不存在的 `qipai_rooms.room_category_id`，已改为迁移真实字段 `category_id` 并补契约断言。
|
||
|
||
## 测试证据
|
||
|
||
- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1`：退出码 0；后端全量测试、后台生产构建、M08-A/B/C 静态验收、迁移计划、固定域名、敏感信息、仓库完整性全部通过。
|
||
- WSL 原生临时副本 + MySQL 8.4.10：`up → verify → down → up → verify` 退出码 0；136 条 up、114 条 verify、130 条 down，临时库与账号自动清理。
|
||
- `GET /app-api/management/stores` 与授权门店房态读取：200；STORE_ADMIN 房态更新：200；只有 `store.operation.read` 的 STAFF 房态写入：403。
|
||
- 已知非阻塞提示：参考目录既有 xjar 超过 100MB；Element Plus 产物 chunk 超过 500kB；WSL npm 报告 4 个 high audit 项及 Node 26 allow-scripts 提示，未执行破坏性自动升级。
|
||
|
||
## 变更影响
|
||
|
||
- 数据库：新增 STAFF 最小只读权限迁移，可回滚。
|
||
- API：新增 3 个小程序管理端点；既有后台管理 API 不变。
|
||
- 部署：后端、小程序和数据库迁移有变化；生产更新时必须先备份，再由菜单更新流程执行迁移与后端/小程序发布，未自动部署生产。
|
||
- 工程提交：`b70ada0`，已推送并验证 `HEAD == origin/main`。
|
||
|
||
## 状态
|
||
|
||
M08-C 保持 `DOING`。门店概况、授权房态、订单总览和最小房态操作已完成；下一工程增量继续订单筛选、订单处置和管理员代下单，不移动到 M08-D。
|
||
|
||
## 2026-08-10 订单处置与管理员代下单
|
||
|
||
- `ENGINEERING_DELTA=YES`
|
||
- 订单查询新增可选 `storeId` 服务端筛选，继续叠加租户、本人订单或管理员授权门店范围，不以小程序本地过滤代替数据权限。
|
||
- 管理员小程序新增订单状态筛选、受控状态动作和订单备注；STAFF 只读账号仍不显示写按钮，服务端仓储继续要求 `store.operation.write`、`tenant.manage` 或平台权限。
|
||
- 新增管理员代下单页，可选当前授权门店的启用房间、计价方式和起止时间；前端不提交金额，价格由服务端重新计算。
|
||
- `/app-api/management/orders/*` 复用既有后台订单状态机、续时/换房/调时/备注和代下单仓储，写操作统一以 `ADMIN` 来源进入既有门店范围校验。
|
||
- 代下单新增同租户有效用户校验，阻止仅凭全局用户 ID 关联其他租户会员；状态历史记录实际管理员，另写 `ORDER_CREATED_ON_BEHALF` 审计，metadata 保留目标会员、门店与房间。
|
||
|
||
### 测试证据
|
||
|
||
- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1`：退出码 0；仓库完整性、敏感信息、后端全量、M08-C 静态验收、迁移计划与后台生产构建全部通过。
|
||
- WSL 原生临时副本 + MySQL 8.4.10：中断清理探针通过，`up → verify → down → up → verify` 通过；136 条 up、114 条 verify、130 条 down，验证管理员历史/审计归因和跨租户目标会员拒绝。
|
||
- 路由测试覆盖只读账号代下单 403、STORE_ADMIN 代下单 201、管理端订单动作/备注 200、订单 `storeId` 查询参数透传。
|
||
- 已知非阻塞提示：参考目录既有 xjar 超过 100MB；Element Plus 产物 chunk 超过 500kB；本次 WSL `npm ci` 报告 7 个 high audit 项及 allow-scripts 提示，未执行破坏性自动升级。
|
||
|
||
### 变更影响
|
||
|
||
- 数据库：无 schema 迁移；新增运行时 `ORDER_CREATED_ON_BEHALF` 审计数据和订单创建历史归因。
|
||
- API：新增小程序管理端订单动作/调整/备注/代下单别名；订单列表增加可选 `storeId`。
|
||
- 部署：后端与小程序有变化，数据库无迁移；未自动部署生产。
|
||
- 工程提交：`566e61b`，已推送并验证 `HEAD == origin/main`。
|
||
|
||
### 状态
|
||
|
||
M08-C 保持 `DOING`。订单筛选、处置、备注和代下单已形成授权闭环；下一工程增量继续会员检索/概况与员工运营，不移动到 M08-D。
|
||
|
||
## 2026-08-10 会员检索与员工概况
|
||
|
||
- `ENGINEERING_DELTA=YES`
|
||
- 新增 `/app-api/management/members` 和 `/app-api/management/members/:id`，复用既有会员聚合服务及 `user.read`、租户、门店范围校验；授权门店会员可由该店钱包账户或历史 OWNER 订单命中。
|
||
- 会员详情展示钱包、订单、优惠券、套餐和最近钱包流水；实付聚合状态修正为当前订单状态 `PAID/RESERVED/IN_PROGRESS/FINISHED`。
|
||
- 新增 `/app-api/management/staff`，服务端强制 `userType=STAFF`，避免租户管理员账号混入员工列表；返回角色、门店范围、状态、备注和脱敏手机号/最近登录 IP。
|
||
- 管理员小程序新增“会员与员工”页，支持会员搜索、聚合详情和员工搜索；代下单页改为从授权会员搜索结果中选择目标会员，取消手工填写全局用户 ID。
|
||
- MySQL 8.4.10 实测发现当前 Node 驱动无法执行 `LIMIT ? OFFSET ?`；会员、员工、订单、保洁仓储统一改为夹取整数后拼接分页常量，其余查询过滤继续参数化，并新增静态防回归断言。
|
||
|
||
### 测试证据
|
||
|
||
- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1`：退出码 0；仓库完整性、敏感信息、后端全量、M08-C 静态验收、迁移计划和后台生产构建全部通过。
|
||
- WSL 原生临时副本 + MySQL 8.4.10：首次运行准确暴露分页占位符错误且清理钩子完成；修复后 `up → verify → down → up → verify` 通过，136 条 up、114 条 verify、130 条 down，并验证历史 OWNER 订单会员发现。
|
||
- 路由/服务测试覆盖会员列表与详情、钱包/订单门店范围、STAFF 类型限定、脱敏输出及代下单会员选择。
|
||
- 已知非阻塞提示：参考目录既有 xjar 超过 100MB；Element Plus 产物 chunk 超过 500kB；WSL `npm ci` 报告 7 个 high audit 项及 allow-scripts 提示，未执行破坏性自动升级。
|
||
|
||
### 变更影响
|
||
|
||
- 数据库：无 schema 迁移；修正会员聚合状态与多个既有列表的 MySQL 分页兼容实现。
|
||
- API：新增 3 个小程序管理端会员/员工读取端点；代下单写接口契约不变。
|
||
- 部署：后端与小程序有变化，数据库无迁移；未自动部署生产。
|
||
- 工程提交：`1b0839e`，已推送并验证 `HEAD == origin/main`。
|
||
|
||
### 状态
|
||
|
||
M08-C 保持 `DOING`。会员检索、聚合详情、STAFF 员工概况和代下单会员选择已完成；下一工程增量继续保洁任务、设备状态与临时控制，不移动到 M08-D。
|
||
|
||
## 2026-08-10 保洁与设备运营
|
||
|
||
- `ENGINEERING_DELTA=YES`
|
||
- 管理员小程序新增“保洁与设备”页，按当前授权门店展示保洁任务、待验收/处理中/驳回/完成统计，并支持验收通过、驳回补做和免清洁。
|
||
- 设备区复用既有设备拓扑，展示在线/离线/故障、型号、房间、最近心跳、开放告警和未解决维护记录；写权限账号可执行控制箱临时开门、全屋通断电和智能插座通断电。
|
||
- 新增保洁任务/统计/处置、设备列表/拓扑和全部设备控制的小程序管理别名；服务端继续执行 capability、租户和门店范围校验，前端按钮隐藏不是权限边界。
|
||
- `DeviceControlService` 在命令创建/发布前写 `DEVICE_COMMAND_REQUESTED` 审计，记录实际账号与命令上下文；系统自动化和顾客订单开门也分别标记 SYSTEM/CUSTOMER 来源。
|
||
- 页面所有写动作均要求二次确认；临时开门固定非保持开启、4 秒延时。接口只返回命令发布状态，设备真实执行仍以相同 commandId 回包为准。
|
||
|
||
### 测试证据
|
||
|
||
- `powershell -ExecutionPolicy Bypass -File scripts/dev/windows/test-all.ps1`：退出码 0；仓库完整性、敏感信息、后端全量、M08-C 静态验收、迁移计划和后台生产构建全部通过。
|
||
- WSL 原生临时副本 + MySQL 8.4.10：`up → verify → down → up → verify` 通过，136 条 up、114 条 verify、130 条 down；实际验证管理员开门命令、MQTT Mock 发布及 ADMIN/用户 ID 审计归因。
|
||
- 路由测试覆盖小程序保洁任务/统计/验收/驳回/免清洁别名、设备列表/拓扑别名和开门/电控别名；服务测试覆盖命令审计数量和管理账号上下文。
|
||
- 已知非阻塞提示：参考目录既有 xjar 超过 100MB；Element Plus 产物 chunk 超过 500kB；WSL npm 报告 allow-scripts 提示，未执行破坏性自动升级。
|
||
|
||
### 变更影响
|
||
|
||
- 数据库：无 schema 迁移；新增运行时设备命令审计数据。
|
||
- API：新增小程序管理端保洁、设备读取和设备控制别名；既有后台 API 不变。
|
||
- 部署：后端与小程序有变化，数据库无迁移；未自动部署生产。
|
||
- 工程提交：`65932a8`，已推送并验证 `HEAD == origin/main`。
|
||
|
||
### 状态
|
||
|
||
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/发布状态表述为真实厂商或设备执行成功。
|