智慧场馆设备接入指南（MQTT 主题协议 v1）

本文是智动引擎场馆物联网（IoT）设备接入的标准协议文档，适用于体脂秤、考勤设备、环境传感器、灯光控制器、空调（科力屋）等六类设备的场边网关 / 厂商对接。

1. 接入总览#

设备/场边网关 ──MQTT──> EMQX Broker（sct-emqx） ──订阅──> mqtt-bridge 消费进程
                                                        │
                                                        ├─ 设备注册表核验（venue_equipment_device_registry）
                                                        ├─ 体脂/考勤/环境数据落库
                                                        └─ 设备在线状态与心跳维护

协议：MQTT 3.1.1 / 5.0，QoS 1（至少一次），payload 为 UTF-8 JSON
Broker 地址：
- 栈内服务：sct-emqx:1883
- 场边网关外部接入：<环境网关域名/IP>:<对外MQTT端口>（如 staging 映射 31883，生产以环境矩阵为准）
客户端要求：clientId 唯一（建议 gw-{场馆ID}-{随机串}），保持长连接，断线自动重连

2. 主题（Topic）规范#

通配格式：device/{device_id}/{类型}，{device_id} 为设备注册表中的设备唯一标识。

主题	用途	方向
`device/+/scale`	体脂秤测量数据	设备 → 平台
`device/+/attendance`	考勤 / 人脸核验事件	设备 → 平台
`device/+/environment`	环境监测（温湿度/CO₂/PM2.5）	设备 → 平台
`device/+/heartbeat`	设备心跳	设备 → 平台
`device/+/light`	灯光状态上报	设备 → 平台（控制指令由平台下发）
`device/+/ac`	空调状态上报（科力屋）	设备 → 平台（控制指令由平台下发）

3. Payload 字段#

3.1 体脂秤 `device/{id}/scale`#

字段	类型	说明
tenant_id	int	租户 ID（默认 1）
user_id / child_id	int?	关联用户 / 学员（用于体质档案归档）
measure_time	datetime?	测量时间（缺省为服务端时间）
weight	float?	体重
body_fat_rate / muscle_rate / water_rate	float?	体脂率 / 肌肉率 / 水分率
bone_mass / bmi / bmr / visceral_fat	float?	骨量 / BMI / 基础代谢 / 内脏脂肪

3.2 考勤 `device/{id}/attendance`#

字段	类型	说明
tenant_id / user_id / child_id	—	归属与人员
check_type	str?	`check_in`（默认）/ `check_out`
check_time	datetime?	打卡时间
verify_type	str?	核验方式（默认 `face`）
verify_score	float?	人脸比对分
capture_image_url	str?	抓拍图
venue_id / scene	—	场馆与场景（默认 `mqtt_ingest`）

3.3 环境 `device/{id}/environment`#

temperature / humidity / co2 / pm25 / measure_time。

3.4 心跳 `device/{id}/heartbeat`#

online（bool，默认 true）、battery_level（可选）。心跳会刷新设备注册表的 last_heartbeat 与在线状态——设备是否显示「在线」完全由心跳驱动。

3.5 灯光 / 空调 `device/{id}/light`、`device/{id}/ac`#

状态镜像上报（由对应服务的 ingest_state 消费）。下行控制指令由平台 light_service / ac_service 通过 MQTT publish（QoS 1）下发，场边网关订阅对应设备主题即可接收。

4. 接入前置：设备注册#

平台收到消息后先核验设备注册表（venue_equipment_device_registry）：

B 端「管理后台 → 智能硬件 → 设备台账」登记设备（device_id / 类型 / 所属场馆）
未注册设备上报的消息会被忽略并记录日志——新设备上线前务必先完成登记
注册信息决定租户归属与数据落点

5. 排障速查#

现象	排查
数据不入库	① 设备是否已注册；② topic 是否拼错（区分大小写）；③ payload 是否合法 JSON
设备显示离线	心跳主题是否持续上报（在线状态仅由心跳刷新）
网关连不上 Broker	对外端口是否防火墙放行；clientId 是否冲突导致互踢
消息重复	QoS 1 语义为至少一次，消费侧按幂等处理

协议版本：v1（2026-09-21）· 事实源：fuse-api/app/services/venue/hardware/ble_mqtt_bridge.py

智慧场馆设备接入指南（MQTT 主题协议 v1）

1. 接入总览#

2. 主题（Topic）规范#

3. Payload 字段#

3.1 体脂秤 device/{id}/scale#

3.2 考勤 device/{id}/attendance#

3.3 环境 device/{id}/environment#

3.4 心跳 device/{id}/heartbeat#