主题
店长端小程序 — 控制开门
上级文档：店长端小程序
背景与目标
当会员到店出现刷脸失败、账号状态异常、设备短时波动等情况时，店长或值班店员需要通过手机端快速协助开门。本模块用于提供受控、可追溯的远程开门能力。
需求范围
- 查看门禁设备状态
- 发起远程开门
- 填写开门原因
- 查看开门执行结果
- 查询开门历史记录
页面路由
| 路由 | 页面 | 说明 |
|---|---|---|
/pages/door-control/index | 控制开门页 | 展示设备状态、操作说明、发起开门 |
/pages/door-control/history | 开门记录页 | 展示历史记录、筛选条件、结果状态 |
功能需求
1. 门禁状态查看
目标：
在执行开门前先看到当前门禁设备是否在线、是否可操作。
前置条件：
- 已登录
- 当前门店具备门禁控制权限
触发方式：
- 进入控制开门页
- 下拉刷新
主流程：
- 调用
GET /api/v1/manager/door/status - 展示门店可控门禁设备列表
- 展示每个设备的在线状态、最后心跳时间、可执行动作
业务规则：
- 至少支持门店主入口门禁
- 多门设备场景下需明确展示设备名称
- 设备离线时禁止点击“立即开门”
异常/边界：
- 状态接口失败时提示“暂时无法获取门禁状态”
- 设备长时间无心跳时按离线展示
验收标准：
- 用户可明确区分在线、离线、异常三类状态
- 离线设备不可发起开门
2. 远程开门
目标：
让有权限的门店人员在必要场景下可远程协助开门，同时降低误操作风险。
前置条件：
- 当前角色具备开门权限
- 门禁设备在线
触发方式：
- 在控制开门页点击“立即开门”
主流程：
- 用户选择门禁设备
- 用户选择开门原因
- 用户二次确认当前门店、设备和原因
- 调用
POST /api/v1/manager/door/open - 服务端下发门禁指令并返回执行状态
- 前端展示“执行中 / 成功 / 失败 / 超时”
业务规则：
- 开门原因必填，至少包含：
会员刷脸失败、会员账号异常、设备故障应急、员工通行、其他 - 同一门禁 10 秒内不可重复发起开门
- 2 分钟内连续失败 3 次时，需提示联系技术支持
- 服务端必须记录操作人、角色、门店、设备、原因、结果、时间
- 小程序不允许绕过服务端直接控制门禁
异常/边界：
- 指令下发成功但设备未回执时，显示“等待设备确认”
- 执行超时后允许手动刷新结果，不自动重复下发
- 角色无权限时，按钮不可点击且需展示原因
验收标准：
- 开门前必须经过二次确认
- 开门成功后 3 秒内可看到成功结果
- 无权限账号不能调用开门接口
3. 开门记录
目标：
支持店长回溯历史开门动作，核查异常和追踪责任。
前置条件：
- 已登录
触发方式：
- 进入开门记录页
- 在开门成功/失败后查看历史
主流程：
- 调用
GET /api/v1/manager/door/logs - 按时间倒序展示记录
- 支持按时间范围、设备、结果状态、操作人筛选
- 点击记录查看详情
业务规则：
- 记录字段至少包含：门店、设备、操作人、角色、原因、结果、发起时间、完成时间
- 失败记录需展示失败原因或错误码
- 记录默认展示近 30 天
异常/边界：
- 无记录时展示空态
- 日志加载失败时支持重试
验收标准：
- 成功和失败的开门记录均可查询
- 失败记录可看到明确失败原因
风险与约束
- 远程开门属于高风险能力，必须以服务端权限校验为准
- 二次验证码、人脸审批或审批流由服务端扩展，不在前端固化逻辑
- 店长端仅解决“快速协助开门”，不替代完整门禁运维后台