From b3fba4b815afcdbb9ed104d8ab392481c5d0c52c Mon Sep 17 00:00:00 2001 From: Codex Date: Mon, 10 Aug 2026 12:28:39 +0800 Subject: [PATCH] =?UTF-8?q?docs(M08-D):=20=E5=9B=9E=E5=A1=AB=E8=AE=BE?= =?UTF-8?q?=E5=A4=87=E8=BF=90=E8=90=A5=E5=90=8E=E5=8F=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 ++-- .../2026-08-10-M08-D-admin-overview.md | 5 ++++ docs/current-baseline.md | 6 ++--- .../2026-08-10-M08-D-admin-overview.md | 1 + docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | 24 +++++++++++++++++++ docs/feature-status.md | 6 +++-- docs/module-status.md | 6 ++--- 7 files changed, 42 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 0be7103..b6203cc 100644 --- a/README.md +++ b/README.md @@ -121,8 +121,8 @@ 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-D`（DOING）；`M08-C` 的可独立工程内容已完成，真实团购商家授权、微信和硬件现场验收保持 `BLOCKED_EXTERNAL`。 -- 最近工程提交：`93f06d2` / `M08-D会员与员工用户管理`，Vue 后台已接入会员余额/权益/订单/充值/流水详情，以及员工创建、角色/门店授权、停启、备注和会话重置。 -- 下一工程目标：继续 M08-D；既有保洁工作台已覆盖计划项，补后台设备运营页面。 +- 最近工程提交：`5c9fd69` / `M08-D设备运营后台`，Vue 后台已接入设备资产、通道、Sub-1G 父子拓扑、告警、维护及门锁/控制箱/智慧插座现场命令。 +- 下一工程目标：继续 M08-D，补后台多小程序与租户配置页面。 ## 版本递进 diff --git a/docs/api-changelog/2026-08-10-M08-D-admin-overview.md b/docs/api-changelog/2026-08-10-M08-D-admin-overview.md index 55f41ab..b9e9606 100644 --- a/docs/api-changelog/2026-08-10-M08-D-admin-overview.md +++ b/docs/api-changelog/2026-08-10-M08-D-admin-overview.md @@ -47,3 +47,8 @@ | GET | `/admin-api/users?userType=STAFF` | 新增可选 STAFF-only 过滤参数；只接受固定枚举 `STAFF`，确保全部角色员工视图不混入顾客。 | | POST/PATCH | `/admin-api/staff`、`/admin-api/users/:id` | Vue 后台接入既有员工创建、资料、角色、门店和状态写接口，继续撤销权限变化后的会话并写审计。 | | POST | `/admin-api/users/:id/reset-sessions` | Vue 后台接入既有会话重置入口。 | + +## 设备运营增量 + +- 无新后端路由；Vue 后台接入既有 `/admin-api/devices`、`/device-topology`、`/device-channels`、`/device-links`、`/devices/:id/maintenance` 与 `/device-control/**`。 +- 所有读写继续使用租户和授权门店范围；控制目标唯一、设备类型、房间归属、危险操作和 MQTT 命令状态继续由服务端校验。 diff --git a/docs/current-baseline.md b/docs/current-baseline.md index 2822131..795aeff 100644 --- a/docs/current-baseline.md +++ b/docs/current-baseline.md @@ -2,7 +2,7 @@ > V5.0 首次核验日期：2026-06-16 > audited_commit: `4ae9296` -> next_engineering_target: 继续 M08-D Vue 平台后台，补设备运营页面 +> next_engineering_target: 继续 M08-D Vue 平台后台，补多小程序与租户配置页面 > 事实源：当前工作区、Git 历史、状态文档、Windows/WSL 检查脚本。 ## 总体结论 @@ -12,7 +12,7 @@ | 总纲版本 | 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 保洁运营工作台，并新增 M08-D 授权门店运营总览、门店/房间、订单、资金、第三方渠道和会员/员工用户工作区；会员页展示余额权益与流水，员工页支持角色/门店授权、停启和会话重置 | `admin/src/App.vue`、`admin/src/components/OperationsOverviewPanel.vue`、`admin/src/components/StoresRoomsPanel.vue`、`admin/src/components/OrdersPanel.vue`、`admin/src/components/PaymentsPanel.vue`、`admin/src/components/ThirdPartyPanel.vue`、`admin/src/components/MembersStaffPanel.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`、`scripts/check-admin-m08-d.mjs` | M08-D 保持 DOING；运营总览、门店房间、订单、资金、第三方渠道、会员员工和保洁工作台可切换，读写继续由后端校验权限并写审计；下一增量补设备运营页面 | +| 后台管理端 | 已建立 Vue3 + Vite + TypeScript + Element Plus 工程，接入 M08-B 保洁运营工作台，并新增 M08-D 运营总览、门店/房间、订单、资金、第三方渠道、会员/员工和设备运营工作区；设备页覆盖资产、拓扑、告警、维护和现场控制 | `admin/src/App.vue`、`admin/src/components/OperationsOverviewPanel.vue`、`admin/src/components/StoresRoomsPanel.vue`、`admin/src/components/OrdersPanel.vue`、`admin/src/components/PaymentsPanel.vue`、`admin/src/components/ThirdPartyPanel.vue`、`admin/src/components/MembersStaffPanel.vue`、`admin/src/components/DevicesPanel.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`、`scripts/check-admin-m08-d.mjs` | M08-D 保持 DOING；读写继续由后端校验权限并写审计，危险设备操作明确发布与 ACK 区别；下一增量补多小程序与租户配置页面 | | 微信小程序 | 已纳管微信原生模板，并完成顾客端订单、充值、权益明细、下单抵扣主体链路、保洁任务端照片上传/补做主体链路，以及管理员门店/房态/订单/代下单/验券/会员/员工/保洁/设备/经营统计 | `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，生产未执行 | @@ -35,6 +35,6 @@ ## 下一步 -1. 继续 M08-D：既有保洁工作台已覆盖计划项，在已完成的运营模块基础上补设备运营页面。 +1. 继续 M08-D：在已完成的运营模块基础上补多小程序与租户配置页面。 2. 继续复用 M02 权限、M03 门店、M04 订单、M05 支付/团购、M06 设备和 M07 会员能力，不重复初始化后台工程。 3. M06-G 真实硬件联调仍等待生产 MQTT 账号/ACL、DeviceID 和现场实物配线。 diff --git a/docs/db-changelog/2026-08-10-M08-D-admin-overview.md b/docs/db-changelog/2026-08-10-M08-D-admin-overview.md index 6e69fcd..a46804b 100644 --- a/docs/db-changelog/2026-08-10-M08-D-admin-overview.md +++ b/docs/db-changelog/2026-08-10-M08-D-admin-overview.md @@ -9,3 +9,4 @@ - 资金运营增量无 schema 变化；Vue 后台复用现有收款账户、分账接收方/策略/记录、退款和对账表，敏感值继续只保存哈希、脱敏值或环境引用。 - 团购与第三方平台运营增量无 schema 变化；Vue 后台复用 `qipai_third_party_configs`、`qipai_third_party_mappings`、直订和核销记录表。安全读取只投影环境凭据引用及过滤后的非敏感设置，券码继续只保留哈希和掩码。 - 会员与员工用户管理增量无 schema 变化；会员聚合继续读取用户、钱包、权益、充值、订单和流水表，员工写操作继续复用角色、门店范围、会话和审计表。新增 `userType=STAFF` 仅增加参数化查询过滤，不改变索引或数据模型。 +- 设备运营增量无 schema 变化；Vue 后台复用设备资产、通道、父子链路、状态快照、告警、维护、命令和审计表，不新增现场状态旁路或客户端成功标记。 diff --git a/docs/devlogs/2026-08-10-M08-D-Vue平台后台.md b/docs/devlogs/2026-08-10-M08-D-Vue平台后台.md index 56e0c68..f11205f 100644 --- a/docs/devlogs/2026-08-10-M08-D-Vue平台后台.md +++ b/docs/devlogs/2026-08-10-M08-D-Vue平台后台.md @@ -158,3 +158,27 @@ M08-D 保持 `DOING`。团购与第三方平台运营增量完成；下一工程 ### 状态 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`。设备运营增量完成；下一工程增量补多小程序与租户配置页面。 diff --git a/docs/feature-status.md b/docs/feature-status.md index 514882e..52e4505 100644 --- a/docs/feature-status.md +++ b/docs/feature-status.md @@ -26,6 +26,8 @@ > 2026-08-10 M08-D 增量：工程提交 `93f06d2` 为 `MEM-001`、`STAFF-001`、`BKG-002` 建立 Vue 后台会员与员工用户工作区；会员聚合余额、权益、订单、充值与流水沿用租户/授权门店范围，员工列表严格限定 STAFF 类型，并接入创建、角色/门店授权、停启、备注和会话重置。Windows 全量、Vue 生产构建与 WSL MySQL 8.4.10 往返通过；既有保洁工作台已覆盖计划项，M08-D 继续设备运营。 +> 2026-08-10 M08-D 增量：工程提交 `5c9fd69` 为 `DEV-003`、`BKG-004` 建立 Vue 后台设备运营工作区；设备入库、控制通道、Sub-1G 父子拓扑、开放告警、维护记录，以及门锁、控制箱和智慧插座现场命令均复用既有门店范围、控制目标唯一性、审计与 MQTT 命令状态机。Windows 全量、Vue 生产构建与 WSL MySQL 8.4.10 往返通过，M08-D 继续多小程序/租户配置。 + | ID | 功能 | 模块子阶段 | 状态 | 最近提交 | 测试/验收证据 | 阻塞原因 | 下一步 | |---|---|---|---|---|---|---|---| | ENV-001 | 固定 Windows 工作区 | M00-A/M00-B | DONE | 远端 HEAD | 已确认 `D:\qipai`，Git 根、main 分支、固定 origin 和 push 校验通过。 | - | 后续每模块继续复检。 | @@ -73,8 +75,8 @@ | REP-001 | 数据统计报表 | M10/M08 | PARTIAL | `65f2e7c` | 门店 7/30/90 日经营统计已同时接入管理员小程序与 Vue 后台，返回订单总量/状态/预订额、OWNER 下单会员、成功支付实收与渠道、每日收入、当前房态、验券成功/失败；最长查询 93 天，租户与门店范围由服务端校验，后台支持授权门店切换、趋势条和明确口径提示，MySQL 实测 `GROUP_BUY` 渠道与成功支付口径。 | 尚缺全门店汇总、自定义导出、使用率/使用时长和生产数据复算验收。 | M08-D/M10 扩展平台统计、导出和指标口径文档。 | | FRN-001 | 加盟商与自动分账 | M05-D/M10/M08 | PARTIAL | `4eac99d` | 已实现租户/门店收款账户、商户号、环境凭据引用、分账授权状态、接收方哈希脱敏、比例总和校验、支付后幂等分账和明细查询；Vue 后台已接入账户、接收方、策略、记录和执行入口，未授权不能开启，生产环境 Mock 强制关闭。 | 缺微信支付服务商和分账权限，尚未执行真实分账。 | 取得权限后执行真实分账与对账；M10 补完整加盟流程。 | | BKG-007 | 后台微信支付配置 | M05-D/M08 | PARTIAL | `4eac99d` | 已提供收款账户、分账接收方、门店/全局比例策略和授权状态 API；Vue 后台支持环境引用配置、授权状态、脱敏接收方、比例策略、分账记录、微信退款、对账单请求和分账执行；私钥/APIv3 Key 不读取或回显。M08-B 保洁转账预检仍提供商户资料与转账前阻断。 | 真实商户与服务商授权、微信后台场景报备和生产小额退款/分账仍需现场联调。 | 授权后完成生产退款、对账与分账验收。 | -| DEV-003 | 设备管理 | M06-B/M08 | PARTIAL | `9144fa8` | 已实现 DeviceID/IMEI/ICCID/型号/固件/信号/能力资产，控制箱通道、智慧插座负载、Sub-1G 父子拓扑、状态快照、开放告警和维护记录查询；插座过载、过温、过流、过压/欠压、功率和温度阈值告警已接入；门店数据范围生效。 | 尚无后台/手机页面，真实硬件在线/计量仍需 M06-G 实物更新。 | M06-F 接入订单自动联动；M08 实现响应式界面。 | -| BKG-004 | 后台设备管理 | M06-B/M08 | PARTIAL | `9144fa8` | 已提供设备入库、列表、拓扑、通道绑定、Sub-1G 绑定、状态、维护和插座控制 API；同一房间控制目标唯一，控制箱与智慧插座重复负载被数据库拒绝。 | Vue 后台页面和真实设备扫码入库待 M08/M06-G。 | M06-F 接入订单自动联动；M08 实现管理页面。 | +| DEV-003 | 设备管理 | M06-B/M08 | PARTIAL | `5c9fd69` | 已实现并在管理员小程序/Vue 后台展示 DeviceID、IMEI/ICCID、型号、固件、信号、能力、状态快照、控制通道、Sub-1G 父子拓扑、开放告警和维护记录；后台可按授权门店入库、绑定、维护并下发门锁/控电/插座命令。 | 真实硬件在线、ACK、计量和保护断电仍需 M06-G 实物更新。 | 取得实物和生产 MQTT 条件后执行硬件矩阵并回填命令 ACK 证据。 | +| BKG-004 | 后台设备管理 | M06-B/M08 | PARTIAL | `5c9fd69` | Vue 后台已接入设备入库、列表、拓扑、通道绑定、Sub-1G 绑定、告警、维护和现场控制；同一房间控制目标唯一，危险命令二次确认，并明确“发布不等于 ACK”。 | 真实设备扫码输入和现场结果未验证。 | M06-G/M10 以真实控制箱、门锁和插座完成扫码入库与控制验收。 | | IOT-006 | MQTT 消息幂等 | M01/M06-C | DONE | `e795cdb` | 上行按租户、设备、Topic 和 payload SHA-256 唯一；QoS 1 重复消息只增加 `receive_count`，不重复更新命令或设备副作用；WSL MySQL 8.4.9 实测两次 ACK 仅一条事件。 | - | M06-D/E 继续复用同一消费链路。 | | IOT-007 | 命令状态机 | M01/M06-C | DONE | `e795cdb` | 已实现 `PENDING/PUBLISHED/ACKED/FAILED/TIMEOUT/UNKNOWN/CANCELLED` 数据模型，发布失败、ACK 结果、超时和 13 位命令 ID 均有测试；发布成功不等于 ACK。 | - | M06-D/F 接入业务权限、补偿与过期取消。 | | DEV-001 | 一键开门与设备动作 | M06-D/M06-F/M08 | PARTIAL | `874b9b8` | 已提供控制箱控电、磁力锁、TTS、LED、订单任务、Sub-1G 门锁和智慧插座控制服务；M08-A 新增顾客端订单权限开门入口，按本人有效订单和时间窗口校验后下发普通开门命令，命令返回 PUBLISHED 而非假成功；顾客端续费/同门店换房入口已接入订单调整 API。 | 真实硬件属于 M06-G；小程序真机开门、续费/换房后的设备动作仍待现场联调。 | 取得硬件后执行真实开门、续费和换房设备联动矩阵。 | diff --git a/docs/module-status.md b/docs/module-status.md index a21e0d9..9708b3c 100644 --- a/docs/module-status.md +++ b/docs/module-status.md @@ -7,11 +7,11 @@ execution_cursor: stage_status: DOING last_completed_stage: M08-C next_stage: M08-D - last_engineering_commit: `93f06d2` + last_engineering_commit: `5c9fd69` 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-10T12:19:35+08:00 + updated_at: 2026-08-10T12:27:18+08:00 ``` | 模块 | 状态 | 最近提交 | 最近开发日志 | 备注 | @@ -24,7 +24,7 @@ execution_cursor: | M05 会员、余额、套餐、优惠券 | PARTIAL | `1680d73` | docs/devlogs/2026-06-22-M05-D-分账与收款配置.md | M05-A/B/C/D 工程闭环已完成：统一支付、微信支付退款、团购直订、门店收款账户、分账接收方、比例策略、授权门禁、幂等分账和对账查询均通过 Windows 与 WSL MySQL 回归；真实微信/团购/分账权限未提供，模块保持 PARTIAL/BLOCKED_EXTERNAL。 | | M06 设备、MQTT 与真实硬件联动 | PARTIAL | `d01f771` | docs/devlogs/2026-06-24-M06-G-真实硬件联调.md | M06-A 至 F 已完成 MQTT、拓扑、协议幂等、控制箱、Sub-1G 门锁、智慧插座和订单自动联动任务；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 | `93f06d2` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A 顾客端、M08-B 保洁端和 M08-C 管理员/员工端的可独立工程内容已完成，真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 旁路。M08-D 已建立 Vue 运营总览、保洁、门店/房间、订单、资金、第三方渠道及会员/员工运营；会员页展示余额权益与流水，员工页支持角色/门店授权、停启和会话重置，继续设备运营。 | +| M08 微信原生小程序完整业务 | PARTIAL | `5c9fd69` | docs/devlogs/2026-08-10-M08-D-Vue平台后台.md | M08-A 顾客端、M08-B 保洁端和 M08-C 管理员/员工端的可独立工程内容已完成，真实微信、团购和硬件现场验收按 BLOCKED_EXTERNAL 旁路。M08-D 已建立 Vue 运营总览及门店、订单、资金、渠道、用户、保洁和设备运营；设备页覆盖资产、通道、Sub-1G 拓扑、告警、维护与现场控制，继续多小程序/租户配置。 | | M09 后台管理端完整业务 | TODO | - | - | - | | M10 部署、域名、验收和运维闭环 | TODO | - | - | - |