管理后台 — 硬件控制面板

模块概述

硬件控制面板为运营人员提供门店设备的实时状态监控与远程操作能力，主要包括工控机在线状态、AB 门状态、灯光控制、UPS 电源监控。硬件操作通过云端 API 下发指令至工控机执行，管理后台不直接控制硬件。

页面路由

路由	页面	说明
`/hardware`	硬件总览面板	所有门店设备状态一览，卡片式布局
`/hardware/:storeId`	单店硬件面板	指定门店的设备详情与控制
`/hardware/alerts`	告警中心	全部门店设备告警列表

硬件总览面板

设计思路

总览面板采用卡片式布局，每个门店一张卡片，展示该门店的核心设备状态摘要。支持快速定位异常门店（离线/告警）。

筛选与排序

筛选项	类型	说明
门店状态	单选	全部 / 正常 / 告警 / 离线
门店名称	输入框	模糊搜索

排序规则：告警/离线门店优先排在顶部，其次按门店名称排序。

单店硬件面板

页面结构

单店硬件面板包含以下区域：

门店设备概览 — 工控机状态、最后心跳
AB 门控制 — 门锁状态、远程开门、门磁状态
灯光控制 — 各分区灯光状态、手动开关、定时任务配置
UPS 监控 — 电量、市电状态、温度
淋浴控制（如已接入）— 淋浴间状态、使用中/空闲
操作日志 — 远程操作记录

AB 门控制区

状态展示

指标	字段	说明
A 门锁状态	`aDoorLockState`	`锁定` / `解锁` / `未知`
B 门锁状态	`bDoorLockState`	`锁定` / `解锁` / `未知`
A 门磁状态	`aDoorMagnetState`	`关闭` / `打开` / `异常`
B 门磁状态	`bDoorMagnetState`	`关闭` / `打开` / `异常`
当前模式	`currentMode`	`待机` / `有人进入中` / `有人离开中`

远程开门操作

交互规则：

点击「远程开门」按钮后弹出确认对话框
必须填写操作原因
操作成功后按钮变为「已开门（30s 倒计时）」，倒计时期间不可重复操作
所有远程操作写入操作日志

灯光控制区

状态展示

分区	字段 key	当前状态	控制方式
入口/隔离间	`zone_entrance`	🟢 开 / ⚫ 关	开关按钮
健身区主区域	`zone_main`	🟢 开 / ⚫ 关	开关按钮
更衣室	`zone_locker`	🟢 开 / ⚫ 关	开关按钮
淋浴区域	`zone_shower`	🟢 开 / ⚫ 关	开关按钮

灯光控制交互

定时任务配置弹窗

UPS 监控区

指标	字段 key	类型	告警阈值	说明
电池电量	`batteryLevel`	Int	< 20%	百分比，带进度条
市电状态	`mainsPower`	Boolean	断电	`市电正常` / `⚠️ 市电断电`
输出电压	`outputVoltage`	Decimal	偏离 ±10%	伏特
UPS 温度	`temperature`	Decimal	> 60°C	摄氏度
最后上报时间	—	DateTime	—	—

单店硬件面板完整页面结构

告警中心

告警类型

告警类型	严重程度	触发条件	说明
工控机离线	🔴 严重	超过 90 秒无心跳	设备可能故障或断网
UPS 电量低	🟡 警告	电池电量 < 20%	需检查 UPS 或联系维护
市电断电	🔴 严重	`mainsPower = false`	立即关注，UPS 仅能维持有限时间
UPS 温度过高	🟡 警告	温度 > 60°C	UPS 过热风险
输出电压异常	🟡 警告	偏离 ±10%	电压不稳，可能影响设备
门磁异常	🟡 警告	门磁长时间处于打开状态	门可能损坏或未关好
网络异常	🟡 警告	工控机上报网络延迟过高	可能影响刷脸等实时操作

告警列表字段

列名	类型	说明
严重程度	图标标签	🔴 严重 / 🟡 警告
告警类型	String	见上表
门店	String	告警所属门店
设备	String	具体设备标识
告警内容	String	如「工控机离线超过 5 分钟」
触发时间	DateTime	—
状态	Enum	未处理 / 处理中 / 已处理
处理人	String	处理该告警的管理员
处理备注	String	—

告警处理

操作	说明
标记为处理中	操作人认领该告警
标记为已处理	填写处理备注后关闭告警
跳转到门店硬件面板	快速定位问题门店
批量处理	勾选多条同类告警批量标记已处理

实时状态刷新策略

方案	说明	[建议值]
WebSocket 推送	工控机状态变更时云端主动推送到前端	✅ 采用
SSE	服务端单向推送	备选
轮询	前端定时请求接口	降级方案（WebSocket 断线时）

[建议值] 优先采用 WebSocket 方案。工控机上报状态 → 云端处理 → WebSocket 推送至管理后台前端。若 WebSocket 断线，自动降级为每 30 秒轮询。

前端实现要点

WebSocket 连接在登录后建立，页面切换时保持
接收设备状态变更消息后，更新对应门店卡片
新告警到达时，右上角弹出通知气泡
页面不可见时（切换到其他 tab），暂停渲染，恢复时重新拉取最新状态

权限控制

操作	老板	财务	店长	客服	说明
查看硬件总览	✅	❌	✅（本店）	❌	—
查看单店硬件面板	✅	❌	✅（本店）	❌	—
远程开门	✅	❌	✅	✅（紧急情况）	高危操作，需权限+确认
灯光控制	✅	❌	✅	❌	—
定时任务配置	✅	❌	✅	❌	—
查看告警列表	✅	❌	✅（本店）	✅	—
处理告警	✅	❌	✅（本店）	✅	—
查看操作日志	✅	❌	✅（本店）	✅	—

用户故事

US-HW-01：管理员远程开门

作为管理员，我想远程打开某门店的门锁，以便在紧急情况下（如用户被困）快速处理。

验收标准：

[ ] 远程开门按钮仅在门店工控机在线时可用
[ ] 点击后必须填写操作原因
[ ] 操作后弹窗确认
[ ] 操作成功后按钮进入 30 秒冷却倒计时
[ ] 操作记录写入操作日志

US-HW-02：店长查看本店设备状态

作为店长，我想查看本门店所有设备的实时状态，以便及时发现设备异常。

验收标准：

[ ] 登录后自动定位到本店硬件面板
[ ] 工控机离线时卡片显示红色告警标记
[ ] AB 门状态、灯光、UPS 状态实时更新
[ ] 页面顶部显示最后心跳时间

US-HW-03：管理员处理设备告警

作为管理员，我想在告警中心查看并处理所有门店的设备告警。

验收标准：

[ ] 告警按严重程度排序（严重在前）
[ ] 新告警到达时弹出通知
[ ] 可标记为「处理中」或「已处理」
[ ] 处理时需填写备注
[ ] 可跳转到对应门店的硬件面板

API 接口规划

# 硬件总览
GET /api/v1/admin/hardware/overview
  Query: { statusFilter? }
  Response: { stores: StoreHardwareSummary[] }

# 单店硬件详情
GET /api/v1/admin/hardware/:storeId
  Response: StoreHardwareDetail {
    ipc: { online, uptime, lastHeartbeat },
    doors: { a: DoorState, b: DoorState, currentMode },
    lights: { zone: LightState }[],
    ups: UpsStatus
  }

# 远程开门
POST /api/v1/admin/hardware/:storeId/remote-open
  Body: { door: 'a' | 'b', reason: string }
  Response: { success: boolean, message: string }

# 灯光控制
POST /api/v1/admin/hardware/:storeId/light-control
  Body: { zone: string, state: 'on' | 'off' }
  Response: { success: boolean }

# 获取/保存灯光定时任务
GET /api/v1/admin/hardware/:storeId/light-schedules
  Response: LightSchedule[]

PUT /api/v1/admin/hardware/:storeId/light-schedules
  Body: LightSchedule[]
  Response: { success: boolean }

# 告警列表
GET /api/v1/admin/hardware/alerts
  Query: { severity?, status?, storeId?, page, pageSize }
  Response: { items: Alert[], total: number }

# 处理告警
PATCH /api/v1/admin/hardware/alerts/:alertId
  Body: { status: 'processing' | 'resolved', note?: string }
  Response: { success: boolean }

# 操作日志
GET /api/v1/admin/hardware/:storeId/operation-logs
  Query: { page, pageSize }
  Response: { items: HardwareOperationLog[], total: number }

# WebSocket 订阅
WS /ws/admin/hardware
  订阅后接收设备状态变更和告警推送

客户端小程序

店长端小程序

管理后台 — 硬件控制面板

模块概述

页面路由

硬件总览面板

设计思路

筛选与排序

单店硬件面板

页面结构

AB 门控制区

状态展示

远程开门操作

灯光控制区

状态展示

灯光控制交互

定时任务配置弹窗

UPS 监控区

单店硬件面板完整页面结构

告警中心

告警类型

告警列表字段

告警处理

实时状态刷新策略

前端实现要点

权限控制

用户故事

US-HW-01：管理员远程开门

US-HW-02：店长查看本店设备状态

US-HW-03：管理员处理设备告警

API 接口规划

管理后台 — 硬件控制面板 ​

模块概述 ​

页面路由 ​

硬件总览面板 ​

设计思路 ​

筛选与排序 ​

单店硬件面板 ​

页面结构 ​

AB 门控制区 ​

状态展示 ​

远程开门操作 ​

灯光控制区 ​

状态展示 ​

灯光控制交互 ​

定时任务配置弹窗 ​

UPS 监控区 ​

单店硬件面板完整页面结构 ​

告警中心 ​

告警类型 ​

告警列表字段 ​

告警处理 ​

实时状态刷新策略 ​

前端实现要点 ​

权限控制 ​

用户故事 ​

US-HW-01：管理员远程开门 ​

US-HW-02：店长查看本店设备状态 ​

US-HW-03：管理员处理设备告警 ​

API 接口规划 ​

管理后台 — 硬件控制面板

模块概述

页面路由

硬件总览面板

设计思路

筛选与排序

单店硬件面板

页面结构

AB 门控制区

状态展示

远程开门操作

灯光控制区

状态展示

灯光控制交互

定时任务配置弹窗

UPS 监控区

单店硬件面板完整页面结构

告警中心

告警类型

告警列表字段

告警处理

实时状态刷新策略

前端实现要点

权限控制

用户故事

US-HW-01：管理员远程开门

US-HW-02：店长查看本店设备状态

US-HW-03：管理员处理设备告警

API 接口规划