集成与 API

把 IFU 接进现有系统

1. 集成方式总览

三条通道共用同一命令总线：同一命令在任一传输上的校验、行为与响应结构完全一致。TCP/UDP 适合中控常驻对接与轻量触发；HTTP 适合脚本与第三方系统；WebSocket 用于管理界面实时刷新（scene-changed、settings-changed 事件）。

2. 统一返回格式

{
  "cmd": "switch",
  "status": "success | error | skipped",
  "message": "已切换场景: tpl-festival-newyear-01",
  "code": "机器错误码（仅 error/skipped 携带）",
  "data": {}
}

• success：执行成功，查询类命令带 data
• error：执行失败（参数错误 / 未知命令 / 目标不存在 / 内部错误）
• skipped：命令已识别但跳过执行（如切换到已是当前的场景、set_text 文字未变化、命令暂未实现）

3. 鉴权

4. 命令清单

5. set_text 匹配规则（远程改字）

block 字段按以下顺序匹配当前场景中的元素，命中即停：

1. 元素 id 精确匹配（如 el-title，可在场景 JSON 中查到）；
2. 文字内容完全一致（如 "欢迎领导莅临指导"）；
3. 兜底：场景中首个文字类元素（text / icon-text）。

匹配后更新 content 并立即落盘应用（内置模板自动生成同 id 用户覆盖文件）。文字与原值相同返回 skipped（code UNCHANGED）；场景中没有文字元素返回 error（code NOT_FOUND）。推荐用元素 id 对接，语义最稳。

6. 调用示例

6.1 切换场景（HTTP）

curl -X POST http://192.168.1.100:42301/api/v1/commands \
  -H 'Content-Type: application/json' \
  -d '{"cmd":"switch","id":"tpl-welcome-leader-01"}'

{"cmd":"switch","status":"success","message":"已切换场景: tpl-welcome-leader-01","data":{"currentSceneId":"tpl-welcome-leader-01"}}

6.2 远程改字（TCP 长连接，Node.js）

const net = require('net')
const c = net.connect(42302, '192.168.1.100')
c.setEncoding('utf8')
let buf = ''
c.on('data', d => {
  buf += d
  let i
  while ((i = buf.indexOf('\n')) >= 0) {
    console.log(JSON.parse(buf.slice(0, i)))
    process.exit(0)
  }
})
c.on('connect', () => c.write(JSON.stringify({
  cmd: 'set_text', block: '欢迎领导莅临指导', value: '热烈欢迎XX集团领导莅临指导'
}) + '\n'))

6.3 局域网发现（UDP 广播）

const dgram = require('dgram')
const s = dgram.createSocket('udp4')
s.on('message', m => { console.log(JSON.parse(m.toString())) })
s.send(JSON.stringify({ cmd: 'discover' }), 42303, '255.255.255.255')
// 每台 FoxDisplay 单播回包：{ cmd:"discover", status:"success", data:{ hostname, ports, currentSceneId, ... } }

7. 错误码

8. 集成注意事项

• TCP 建议每 30 秒发一次 ping 作心跳；服务端不主动断开连接；
• UDP 单包 ≤512 字节，超出请改走 TCP/HTTP；坏包静默丢弃（无响应即失败）；
• 命令处理为串行内存操作，无需担心并发；多中控同时连接 42302 是允许的；
• 场景 id 只允许字母、数字、下划线与连字符；
• 所有写操作（switch / save_scene / set_text / delete_*）实时落盘，大屏断电不丢。

分享