park-desktop/docs/mqtt-commands.md

# MQTT 标准操作手册（OPC 智能园区大屏系统）

> 通过 MQTT 对前端大屏进行集中控制：切页、页面操作、媒体控制、视觉开关、状态上报。

## 1. Broker 连接

| 项 | 值 | 说明 |
|---|---|---|
| 地址 | `192.168.1.3` | 局域网 EMQX Broker |
| TCP 端口 | `1883` | MQTT 标准端口（后端/命令行用） |
| WebSocket 端口 | `8083` | 前端浏览器用（`ws://192.168.1.3:8083/mqtt`） |
| 用户名/密码 | `backend/.env` 的 `MQTT_USERNAME` / `MQTT_PASSWORD` | 连接鉴权 |

## 2. 频道（Topic）

| Topic | 方向 | 载荷 | 用途 |
|---|---|---|---|
| `opc/display/command` | 服务端 → 前端 | 指令信封 | **控制指令**（切页/页面操作/媒体/视觉） |
| `opc/dashboard/tick` | 服务端 → 前端 | 园区数据快照 | 数据大屏实时刷新（2.2s） |
| `opc/display/heartbeat` | 前端 → 服务端 | `{client_id, page, ts}` | 大屏在线心跳（10s） |
| `opc/frontend/state` | 前端 → 服务端 | `{client_id, page, ts}` | **页面状态即时上报**（路由变化即发） |
| `opc/display/ack` | 前端 → 服务端 | 指令回执 | 指令确认（可选） |

## 3. 统一指令信封

所有控制指令发到 `opc/display/command`，JSON 格式：

```json
{
  "cmd_id": "uuid",          // 指令 ID（可选）
  "ts": 1755490000000,       // 时间戳 ms（可选）
  "action": "navigate",      // 命令名（必填）
  "params": { "page": "/ai" } // 参数（按命令）
}
```

后端 `hub.publish_command(action, params)` 自动生成信封；命令行手动发送时只需 `action` + `params`。

## 4. 命令全集

### 4.1 页面切换

| action | params | 效果 |
|---|---|---|
| `navigate` | `page: "/" \| "/twin" \| "/ai" \| "/voice" \| "/wall" \| "/screen"`（或别名 home/twin/ai/voice/wall/screen/数据大屏/企业展示墙…） | 切换到指定页面 |
| `navigate_rel` | `delta: 1 \| -1` | 向右 / 向左循环切换页面 |

### 4.2 全局视觉识别

| action | params | 效果 |
|---|---|---|
| `vision_set` | `enabled: true \| false` | 开启 / 关闭全局人物识别（YOLO 人脸/姿态/手势） |

### 4.3 AI 助手页（/ai）

| action | params | 效果 |
|---|---|---|
| `ai_input` | `text: "介绍一下入驻政策"` | 输入问题并自动发送 |
| `ai_preset` | `index: 0 \| 1 \| 2` | 选择预设问题并发送 |
| `ai_company` | `action: "next" \| "prev"` | 切换展示企业 |
| `ai_zone` | `zone: "加速区" \| "国际区" \| "成长区"` | 切换企业分区 |

### 4.4 语音对话页（/voice）

| action | params | 效果 |
|---|---|---|
| `voice_start` | — | 启动语音对话 |
| `voice_stop` | — | 关闭语音对话 |
| `voice_refresh` | — | 刷新页面 |

### 4.5 媒体轮播页（/screen）

| action | params | 效果 |
|---|---|---|
| `play` / `pause` | — | 播放 / 暂停 |
| `next` / `prev` | — | 下一项 / 上一项 |
| `set_mode` | `mode: sequential \| shuffle \| loop` | 播放模式 |
| `play_target` | `path: "媒体路径"` | 播放指定媒体 |
| `settings_changed` | 设置对象 | 应用设置变更 |
| `playlist_changed` | — | 重新加载播放列表 |

### 4.6 企业展示墙页（/wall）

> 39 家入驻企业信息缓慢滚动展示墙（数据来源：《入驻企业信息表》）

| action | params | 效果 |
|---|---|---|
| `wall_pause` | — | 暂停滚动 |
| `wall_resume` | — | 继续滚动 |
| `wall_speed` | `speed: slow \| normal \| fast` | 滚动速度：慢速 150s / 标准 80s / 快速 40s 一圈 |

### 4.7 全局

| action | params | 效果 |
|---|---|---|
| `alert` | `text: "通知内容"` | 全局通知弹窗 |
| `show_card` | 卡片数据 | 展示信息卡片 |
| `minimize` | — | 最小化窗口（Tauri） |

## 5. 命令行发送

### mosquitto_pub（推荐，需安装 `mosquitto-clients`）

```bash
# 切页到 AI 助手
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command \
  -m '{"action":"navigate","params":{"page":"/ai"}}'

# 向左切页
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"navigate_rel","params":{"delta":-1}}'

# 关闭人物识别
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"vision_set","params":{"enabled":false}}'

# AI 页提问
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"ai_input","params":{"text":"介绍一下入驻政策"}}'

# 切换企业分区
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"ai_zone","params":{"zone":"国际区"}}'

# 语音启动 / 媒体下一项
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"voice_start","params":{}}'
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"next","params":{}}'

# 切到企业展示墙 / 暂停滚动
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"navigate","params":{"page":"/wall"}}'
mosquitto_pub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> \
  -t opc/display/command -m '{"action":"wall_pause","params":{}}'
```

### Python（paho-mqtt，后端 venv 自带）

```bash
cd /Volumes/Pine/mycode/DPM/dpm/backend
.venv/bin/python - <<'EOF'
import paho.mqtt.client as mqtt

def send(action, params=None):
    c = mqtt.Client()
    c.username_pw_set("用户名", "密码")
    c.connect("192.168.1.3", 1883, 30)
    c.publish("opc/display/command", str({"action": action, "params": params or {}}))
    c.disconnect()

send("navigate", {"page": "/voice"})
send("ai_company", {"action": "next"})
send("voice_stop")
EOF
```

### MQTTX（图形界面）

1. 新建连接：`mqtt://192.168.1.3:1883`，填用户名/密码
2. 发布到 `opc/display/command`，消息体如上 JSON

## 6. 订阅调试

```bash
# 监听前端页面上报（验证"当前页面"）
mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/frontend/state'

# 监听心跳
mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/display/heartbeat'

# 监听全部指令
mosquitto_sub -h 192.168.1.3 -p 1883 -u <用户名> -P <密码> -t 'opc/display/command' -v
```