系统架构总览

graph TD
    EMQX["EMQX MQTT"]
    hapi["hapi 业务API"]
    mapi["mapi 认证"]
    ztmp["ztmp 后端"]
    ztUtil["ztUtil SDK\n跨平台设备通信"]
    Wechat["微信小程序 / uni-app"]
    Browser["浏览器"]
    NodeJS["Node.js"]

    EMQX -->|"MQTT"| hapi
    EMQX -->|"$SYS"| mapi
    hapi -->|"REST"| Wechat
    Wechat -->|"RPC"| ztmp
    Wechat -->|"BLE/MQTT"| ztUtil
    Browser -->|"MQTT"| ztUtil
    NodeJS -->|"MQTT"| ztUtil
    ztUtil -->|"MQTT WSS"| EMQX
    ztUtil -->|"BLE 直连"| GW["网关/设备"]

三服务职责划分

服务	端口	职责
hapi	3008	设备控制中枢：MQTT 指令收发、设备状态解析、场景执行、Webhook 推送、网关配网信息查询
mapi	3009	EMQX 辅助：MQTT 连接认证（POST /mqtt/auth）、设备上下线事件监听、在线状态维护
ztmp	30090	微信小程序后端：会员认证、家庭/房间/设备/场景 CRUD、网关节点列表、语音平台设备发现

ztUtil SDK

ztUtil（app-lightsmart-ztutil）是应用与硬件设备之间的唯一通信桥梁，封装了 BLE 配网、MQTT 通信、设备控制等底层功能。通过平台适配层支持多种运行环境，业务代码无需关心平台差异。

• 三种通信模式：MQTT 远程（MODE_MQTT=4）、BLE 蓝牙（MODE_BLE=2）、YiMesh（MODE_YIMESH=1）
• 主要能力：设备控制、状态查询、场景执行、网关配网、设备扫描添加
• 支持平台：微信小程序 / uni-app（完整功能）、浏览器（MQTT 远程控制）、Node.js（MQTT 远程控制）
• 单文件构建：支持 npm run build:bundle 编译为自包含的 UMD/ESM 单文件产物
• 详细文档：ztUtil SDK

数据库隔离

• hapi/mapi 共享 smart_hotel_db（52 张表：设备、房间、酒店、许可证等）
• ztmp 使用独立数据库 ztmp（7 张表：会员、项目、对象、配网记录等）
• 两者共享同一 MySQL 实例和 Redis 实例