1. 背景与目标

1.1 背景

共享茶室作为一种新兴的无人值守商业模式，痛点在于如何实现远程、安全、可追溯的门禁控制。传统的方案往往只能实现单向的远程开门，缺乏对开门结果的闭环验证，导致运营方无法确认用户是否真正进入、门锁是否正常开启。

1.2 解决目标

本方案的目标是利用芯步的智能硬件及开放接口，构建一个“下发指令—执行动作—状态回传—结果上报”的全链路闭环系统。核心目标是：当用户在共享茶室小程序完成支付后，系统不仅远程开门，还能实时上报“门已打开”、“门超时未开”或“门锁故障”等精确状态至业务后台，确保订单计费的准确性与安全性。

2. 整体设计

本方案采用“端-云-应用”三层架构：

• 感知层：芯步智能门禁设备（如联网出门开关、磁力锁控制器）。负责接收指令、控制锁舌、检测门磁状态。

• 网络层：芯步开放平台。负责设备连接、指令转发、状态消息推送。

• 应用层（应用）：共享茶室业务服务器（SaaS）与用户端小程序。负责业务逻辑处理（订单生成、权限校验）、记录存储、用户通知。

3. 核心实现机制：验证结果上报

为了实现“验证结果上报”，不能仅使用简单的GET请求控制设备，必须建立异步回调机制。芯步平台支持设备状态变更主动推送，这是本方案的技术底座。

3.1 集成流程详解

第一步：设备初始化与绑定在茶室每个包间的门锁控制器中集成芯步4G/WiFi模块。设备上电联网后，通过芯步控制台获取唯一的DeviceID（设备ID）。将该ID与茶室SaaS后台的“xx包间”进行物理绑定。

第二步：用户触发开门（下发指令）用户在小程序下单成功后，SaaS后台调用芯步“向设备下发指令”接口（HTTP/MQTT）：

• 请求地址http(s)://api.thingboot.com/{AppID}/device/control/

• 核心参数

  • device：[设备ID]

  • order：发送{"power": 1}（使继电器通电，断开门锁）或{"reset": 5000}（瞬间通电5秒后自动恢复锁闭）。

第三步：设备执行与状态捕获（关键环节）智能门禁设备执行开门动作。由于存在网络延迟或设备离线的可能，业务平台不能默认“指令发送成功=开门成功”，必须依赖上行消息确认：

1. 即时响应：芯步平台返回{"code":200}，这仅代表指令已下达。

2. 异步结果上报：设备执行指令后，其状态发生改变（如status从0变为1）。芯步平台通过MQTT或HTTP回调，主动将最新状态推送到业务服务器预设的Callback URL。

第四步：业务逻辑处理SaaS后台接收到“门已开”的回调后，更新订单状态为“使用中”；若在规定时间内（如2分钟）未收到“门开”回调，则判定设备故障并触发告警。

3.2 接口调用时序图

sequenceDiagram
    participant User as 微信小程序/用户
    participant Biz_Server as 共享茶室SaaS后台
    participant YY_IoT as 芯步开放平台
    participant Door_Device as 芯步门禁控制器/磁力锁

    User->>Biz_Server: 1. 支付下单，请求开门
    Biz_Server->>Biz_Server: 2. 校验订单，查询对应设备ID
    Biz_Server->>YY_IoT: 3. HTTP/MQTT 下发开门指令 (device:xxx, order:{power:1})
    YY_IoT-->>Biz_Server: 4. 返回 {"code":200} (指令已接收)
    YY_IoT->>Door_Device: 5. 透传指令至设备
    Door_Device->>Door_Device: 6. 执行继电器吸合/磁力锁断电(门开)
    Door_Device-->>YY_IoT: 7. 上报执行后的新状态 (status=open)
    YY_IoT->>Biz_Server: 8. 异步推送开门结果 (Callback)
    Biz_Server->>Biz_Server: 9. 更新订单状态为"进行中"，记录开门时间
    Biz_Server-->>User: 10. 小程序界面显示"门已开，请进入"

4. 关键数据结构定义

为了确保“上报”的准确性，芯步的extra字段和自定义回调结构至关重要。

4.1 下发指令时的订单绑定（请求）

为了避免异步消息回来后不知道是哪笔订单开的门，在order中传入extra字段透传订单号：

4.2 设备状态上报回调（接收）

业务服务器需要暴露一个HTTP接口（如/api/yoyo/callback）来接收芯步的POST请求。的数据结构解析如下：

注意：芯步支持设备主动推送。如果是物理按键出门或人体感应出门，设备也会上报status变化，SaaS后台收到后应上报为“用户正常离店，订单结束”。

5. 场景细节与异常处理

在共享茶室场景中，“上报”的内容不仅仅是“门开了”，还需要包括“谁开的”、“为什么失败”。

5.1 防潜逃与计费闭环

• 物理门磁检测：芯步设备不仅仅控制锁，还应接入门磁传感器。

  • 逻辑：SaaS后台下发开门指令 -> 收到status=1（锁开）-> 收到door_sensor=1（门磁拉开） -> 确认用户进入。

  • 上报事件：记录“用户XX已入场”。

• 超时未关上报：如果开门后，门磁传感器超过5分钟未检测到闭合信号（门未关），设备应上报abnormal_event，后台触发语音告警“请随手关门”。

5.2 远程关门与状态核实

当用户在小程序点击“结束订单”时：

1. SaaS后台下发关门指令：{"power": 0}（继电器断电，锁体磁吸闭合）。

2. 设备执行，并将status=0上报云端。

3. SaaS后台若在5秒内未收到status=0回调，应判定设备离线或机械故障，立即通知运维人员介入，避免用户误以为已关门导致后续财损。

5.3 离线重连机制

若茶室位于地下室信号差，设备离线：

1. 用户在芯步控制台查看设备显示“离线”。

2. 方案一：使用芯步支持的局域网或蓝牙方案，通过小程序蓝牙直连设备开门（如果设备支持）。

3. 方案二：后台下发指令时，利用芯步的离线存储（若有该功能），等待设备上线后补发命令并上报结果。

6. 实施收益

通过在共享茶室门禁控制中集成芯步开放接口并建立验证结果上报机制，可带来以下收益：

1. 无人化运营：无需前台接待，用户支付即自动获得权限，离店自动结算。

2. 账单零争议：每一条开门/关门结果都有云端的异步上报日志作为法律/技术证据，解决了“我说开了，你说没开”的扯皮问题。

3. 设备健康度可视：通过code:200但无status回调的数据分析，可以筛选出信号弱的设备，提前进行维护。

7. 总结

本方案充分利用了芯步开放接口的双向通信能力。关键在于转变思路：不把“接口返回200”当作成功，而是把设备主动上报的状态变更作为成功与否的唯一标准。通过这种架构，共享茶室SaaS系统能够实时、精准地控制每一个物理包间，实现真正的智能化、无人化运营。