设备控制全流程

路径 A：通过 hapi REST API（第三方/语音平台）

sequenceDiagram
    participant MP as 小程序
    participant hapi
    participant EMQX
    participant GW as 网关

    MP->>hapi: 1. POST /room/control
    Note over hapi: 查房间/设备, 生成BLE hex
    hapi->>EMQX: 5. 发布 ble_in
    EMQX->>GW: 转发指令
    GW->>GW: 6. 执行BLE Mesh
    GW->>EMQX: 7. 上报 ble_out
    EMQX->>hapi: 8. 状态上报
    Note over hapi: 解析状态, 更新Redis
    hapi-->>MP: { code: 0 }
    MP->>hapi: 12. POST /room/status
    hapi-->>MP: [{ on_off: "on" }]
    hapi->>EMQX: Webhook

路径 B：通过 ztUtil SDK 直连网关（小程序本地控制）

sequenceDiagram
    participant MP as 小程序
    participant ztUtil as ztUtil SDK
    participant EMQX
    participant GW as 网关

    Note over MP,ztUtil: 已通过 connectMqtt 建立连接
    MP->>ztUtil: 1. controlDevice({ action, device, payload })
    Note over ztUtil: protocol.buildCommand() 生成 BLE hex
    ztUtil->>EMQX: 2. 发布 ble_in (MQTT)
    EMQX->>GW: 转发指令
    GW->>GW: 3. 执行BLE Mesh
    GW->>EMQX: 4. 上报 ble_out
    EMQX->>ztUtil: 5. 接收状态推送
    ztUtil->>MP: 6. register callback { code: 2000, data: { naddr, status } }
    Note over MP: 更新 buttons_state

两条路径的区别

对比项	路径 A（hapi REST）	路径 B（ztUtil SDK）
调用方	任意 HTTP 客户端	小程序内 ztUtil SDK
认证	X-Beancomm-Client-Token + X-Beancomm-Client-Unionid	MQTT mq_id + mq_pass
指令生成	hapi genCommand()	ztUtil protocol.buildCommand()
状态推送	需轮询 POST /room/status	实时回调 register({ code: 2000 })
适用场景	第三方应用/语音平台	小程序直接控制
通信模式	仅 MQTT	MQTT 或 BLE 直连

修订（2026-09-26 代码回源）：路径 A 的认证头为 X-Beancomm-Client-Token + X-Beancomm-Client-Unionid（/client/* 中间件），非 JWT Bearer。依据 service-lightsmart-hapi/src/utils/auth.js:93-112、app.js:38。