系统架构总览

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、网关节点列表、语音平台设备发现

网关型号

型号	芯片	固件版本	说明
BCW018X-A203	ESP32-C2 (ESP8684)	V1.2.0	当前在用网关，BLE Mesh + WiFi + MQTT
T7-21600 (旧版)	—	V1.2.3/V1.2.4	旧版网关/网关插座

BCW018X-A203 能力概述

• 通信：WiFi STA + BLE Mesh（私有协议）+ MQTT(TLS, 8883)
• OTA：双通道（轮询 ota_check + MQTT 推送 AT+OTAURL），双分区 A/B 带回滚确认机制
• 指示灯：六态指示（配网/连路由器/连服务器/连服务器成功/配对模式/升级固件）
• AT 命令：13 条（AT/CWMODE/CWJAP/CIPSTA/CIPSTAMAC/CPCODE/MQTTSTART/BLE_PAIR/RSSI/RESTORE/FUNC/GET_SCAN/NODE）
• MQTT 主题：6 业务主题（ble_in/ble_out/at_in/at_out/system/system_out）

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 实例