将设备数据接入你的 SaaS
适用场景
适用于把 WLTE 设备能力嵌入自己的产品（多租户 SaaS、内部运营系统等）的场景。终端用户使用的是你的产品和你的账号体系，不会直接接触 WLTE 的凭据。
- 一个 WLTE 账号、一个 API Client，对应的是你的整个部署，而不是逐个终端客户分配一套凭据。
- WLTE 账号下的设备是平铺的，没有租户概念；"哪些设备属于哪个客户"需要你自己维护映射关系。
- 需要把 WLTE 的实时事件持续转发进自己的数据管道（数据库、消息队列、自己的 WebSocket 或 webhook），而不是让每个终端客户的页面各自维护一条到 WLTE 的连接。
不要把 clientId、clientSecret 或 access token 下发给终端客户；也不要假设同一账号下的设备天然按租户隔离——它们不是。
推荐架构
只在你的后端持有 WLTE 凭据，维护一份 deviceId → tenant_id 的映射表，用一条 WebSocket 连接服务所有租户，再由你自己的系统向下分发。
分步骤实现
- 设计并维护
deviceId → tenant_id（或你自己的客户/站点标识）映射表。WLTE 账号本身不区分租户，这张表是整个集成的核心数据。 - 使用服务端持有的单一 API Client 获取 access token：只读场景用
device:read，需要下发控制指令时加device:control或device:config。 - 调用查询设备列表和查询设备类型定义列表建立初始状态基线，按映射表拆分到各租户的视图。
- 创建一次性 WebSocket Ticket，建立唯一一条连接（不是每个租户各开一条），持续接收连接事件、状态变化事件和电源事件。
- 事件到达后先按
deviceId查表定位租户，再写入自己的存储或消息队列，由你自己的 API/WebSocket/webhook 向该租户的客户端推送。 - 终端客户发起控制请求时，先在你自己的权限系统里鉴权（这是你产品面向客户的租户级权限，不是 WLTE 的 scope），再由后端代理请求给 WLTE，并使用幂等键。
- 需要长期保存或作为计费依据的命令结果、事件记录，必须在自己这一层落库；WLTE 不提供事件历史补发，命令记录也只短期保留。
关键接口与事件
| 用途 | 文档 |
|---|---|
| 建立设备状态基线 | 查询设备列表 |
| 按能力渲染多租户视图 | 查询设备类型定义列表 |
| 将设备添加到账号 | 添加设备到账号 |
| WebSocket 鉴权 | 创建 WebSocket Ticket |
| 在线和离线变化 | 设备连接事件 |
| 外设状态变化 | 设备状态变化事件 |
| 断电与上电通知 | 设备电源事件 |
| 代理控制指令 | 执行继电器命令 |
| 查询命令结果 | 查询命令结果 |
失败与恢复策略
- 限流按 API Client 计算，多个租户共用同一个账号意味着共用同一份限流预算；某个租户的高频请求可能耗尽全部账号的额度，需要在自己这层做节流和排队，不能直接把终端客户的请求频率透传给 WLTE。
- 上游 WebSocket 断线时，只需要重连这一条服务端连接，而不是逐租户重连；重连期间应向下游标记数据可能滞后。
- 断线期间的事件不会补发。重连后先通过 REST 重建状态基线，再恢复事件驱动更新。
- 命令记录和幂等键在 WLTE 侧只保留约 48 小时；需要更长的审计或计费周期时，必须自己持久化命令结果和最终状态。
- 收到
429 RATE_LIMITED时按Retry-After等待重试，不要在你自己的服务里对每个租户各自实现一套独立的重试逻辑。
生产环境注意事项
- 终端客户不应在任何情况下看到或获得 WLTE 的
clientId、clientSecret或 access token；所有 WLTE 调用都必须经过你的后端代理。 - WLTE 的四个权限范围（
device:read/device:control/device:config/device:manage）是账号级别的粗粒度权限，不能替代你自己面向终端客户的细粒度权限模型——两者是两层独立的授权体系。 - 把
deviceId → tenant_id映射当作系统里最重要的一张表来维护；账号下增删设备、客户增删站点，都要同步更新这份映射，避免数据串到错误的租户。 - 提前规划限流预算：租户数量增长会线性增加请求量，但账号的限流额度不会跟着增长。
- 参见权限范围确认可用的 scope 组合，参见限流与重试确认限流维度。