🤖 给 AI 的参考

这是 Hearo（听见）的《客户端与接入模型》文档，可作为开发参考。文档链接：https://hearo.apps.aisp24.com/docs/clients.md

客户端与接入模型

一套统一模型接入所有终端：硬件设备、手机/电脑 App、网页都是「客户端」，用同一种身份 Token 连接，房间由平台分配

Hearo 把所有外部参与者统一抽象成 客户端（Client）。无论是 IoT 硬件、手机 App、电脑软件还是网页，接入方式都一样：拿一个客户端身份 Token 连上来，进入哪个房间由平台的 客户端 → 房间映射决定。本页讲清整套模型与端到端开发流程——面向用户（控制台操作）、方案商（设备接入）、开发者（App/固件集成）。

核心概念

概念	持有方	说明
客户端 Client	—	任意外部参与者（hardware/app/web）。有唯一 clientId、可分配房间、有在线状态。
工作空间 API Key	服务端持有	在控制台「API Key」创建。用于服务端调用管理接口、签发客户端 Token。绝不下发到设备。
客户端 Token	客户端持有	只证明「你是哪个客户端」，不含房间。用它连接 MQTT、WSS 或 WebRTC（实验）。可有有效期或长期。
客户端→房间映射	平台维护	每个客户端有一个房间号。改它即切换房间（在线秒切）。多个客户端同房间 = 群聊/通话。
在线状态 presence	连接生命周期	连上=在线、断开=离线。即使设备静默也能知道在不在线。

ℹ️ 两层凭据，别混淆：① 工作空间 API Key（强权限，服务端）：管理客户端 + 签发 Token，放在你的后端。② 客户端 Token（仅身份，设备端）：用来建立连接，由你的后端用 API Key 现签发给设备。设备只拿到 Token，永不持有 API Key。

端到端接入流程

典型方案商/开发者集成步骤（服务端用 API Key，设备只拿 Token）：

text

① 控制台 → API Key → 创建一把（只显示一次，复制保存）
② 你的后端：用 API Key 创建客户端           POST /v1/clients
③ 你的后端：为该客户端签发 Token             POST /v1/clients/{id}/token
④ 把 Token 下发到设备/App/网页
⑤ 设备用 Token 连接（MQTT/WSS/WebRTC（实验））→ 自动进入它绑定的房间
⑥ 需要时：改客户端房间号即可实时切房          PATCH /v1/clients/{id}
   在线状态由连接自动维护（presence）

第 1 步 · 创建 API Key（控制台）

控制台 → API Key → 创建。密钥形如 hk_xxx，只显示一次，保存到你的后端环境变量。后续所有管理调用用 Authorization: Bearer hk_xxx。

第 2 步 · 创建客户端 + 签发 Token（服务端）

bash

API=https://hearo.apps.aisp24.com   # 本部署的 API 基址
KEY=hk_xxxxxxxx         # 工作空间 API Key

# 1) 创建一个客户端（kind: hardware|app|web；room 可选，先留空也行）
curl -s -X POST $API/api/v1/clients \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"clientId":"M4T62816063057","kind":"hardware","name":"门口设备","room":"lobby"}'
# → {"client":{"id":"ckd...","clientId":"M4T62816063057","room":"lobby",...}}

# 2) 用上一步返回的 id 签发 Token
#    省略 ttlSeconds = 长期 Token（写死固件）；填了 = 有效期 Token（到期前续）
curl -s -X POST $API/api/v1/clients/ckd.../token \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"ttlSeconds":2592000}'
# → {"token":"<CLIENT_TOKEN>","clientId":"M4T62816063057","expiresAt":"..."}

💡 网页/App 一步直连：临时场景（网页访客、App 会话）不必预建客户端：一次调用拿到「临时客户端 + 房间 + Token」，会话结束自动回收。

bash

curl -s -X POST $API/api/v1/clients/ephemeral \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"room":"demo-1","kind":"web","ttlSeconds":3600}'
# → {"token":"<CLIENT_TOKEN>","clientId":"eph_...","room":"demo-1","expiresAt":"..."}

第 3 步 · 设备用 Token 连接

同一个 Token 适用于三种 IP 传输，连上即进入该客户端绑定的房间：

传输	本部署地址	说明
MQTT	`124.174.6.145:2883`	password=Token 或设备接入密码。见 MQTT 接入 / aispea 接入。
WebSocket	`wss://hearo-gw.apps.aisp24.com/v1/connect?token=…`	见 WebSocket。
WebRTC（实验）	`POST https://hearo-gw.apps.aisp24.com/v1/webrtc/offer`，请求头 `Authorization: Bearer <Token>`	见 WebRTC（实验）。

💡 MQTT 设备的第二种凭据：固件密码字段放不下 JWT？在控制台 → 设备页给设备生成设备接入密码（hkd_ 开头的短密码，可反复查看、可一键重置立即失效），MQTT 连接用它当 password 即可，等价于该设备的身份凭据。设备页也能直接「生成 Token」，无需走 API。

⚠️ 务必用 TLS：WSS 的 Token 使用连接 query 参数，WebRTC（实验）的 Token 只能使用 Authorization: Bearer 请求头，MQTT 使用 password。WSS 与 WebRTC（实验）必须走 TLS（wss/https）。MQTT broker 默认为明文 TCP，生产建议部署侧加 TLS 终结，或用可随时重置的设备接入密码降低泄露影响。

第 4 步 · 房间与分组（切房 / 群聊）

房间由客户端的 room 字段决定，不在 Token 里。所以可以在设备保持在线的情况下随时切换房间——改映射即可，无需重连：

bash

# 把设备移到另一个房间（在线秒切）
curl -s -X PATCH $API/api/v1/clients/ckd... \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"room":"meeting-2"}'

# 群聊/通话：把多台设备的 room 设成同一个值，它们就在一个房间里实时互通

控制台 → 房间 / 分组 页可视化地批量分配房间；改动对在线设备实时生效。房间还能登记成受管房间并配置默认 AI 智能体、用「网页进入」一键测试、生成匿名分享链接——见房间与分组。

管理 API 参考

全部用工作空间 API Key 鉴权（Authorization: Bearer hk_xxx）。

GET /api/v1/clients — 列出客户端，支持查询参数 room / kind / status 筛选。
POST /api/v1/clients — 创建/登记客户端。Body：{clientId, name?, kind?, room?}。
GET /api/v1/clients/{id} — 详情（含在线状态）。
PATCH /api/v1/clients/{id} — 改名 / 设置房间（设置房间 = 实时切房）。Body：{name?, room?, kind?}。
DELETE /api/v1/clients/{id} — 删除。
POST /api/v1/clients/{id}/token — 签发客户端 Token。Body：{ttlSeconds?}——省略=长期。
POST /api/v1/clients/ephemeral — 一步创建临时客户端 + 绑房间 + 返回 Token。Body：{room, kind?, ttlSeconds?}，ttlSeconds 默认 3600（1 小时）。

在线状态（presence）

连接建立即标记客户端在线，断开/超时即离线（由网关在连接生命周期自动上报）。在控制台 → 设备 / 房间分组页可看到 ONLINE/OFFLINE 与最近在线时间。这套对 MQTT、WSS 与 WebRTC（实验）通用。