集成与 API

把 IFU 接进现有系统

1. 集成方式总览

服务随主程序启动；端口与开关在桌面端「设置 → Web 控制台」修改，保存后服务自动重启生效。不使用远程管理时可整体关闭。

2. 鉴权

令牌为简化 JWT（三段式）：签名部分由控制密码派生，因此密码即密钥——不要在日志中泄露密码与令牌。

3. 接口清单

4. 设置字段（PUT /api/settings，全部可选，按需携带）

成功响应：{"success":true}，并通过 WebSocket 广播 settings_changed（不含密码）。

5. 计时器对象与参数

5.1 计时器对象（GET /api/timers 返回）

{
  "timers": [{
    "id": "uuid",
    "label": "15分0秒",
    "mode": "countDown | countUp",
    "state": "idle | running | paused | finished",
    "displayMs": 899990,
    "formatted": "15:00",
    "targetMs": 900000,
    "elapsedMs": 10,
    "shortcutKey": "1",
    "shortcutModifier": "Control"
  }],
  "currentIndex": 0
}

• formatted：超过 1 小时显示 HH:MM:SS，否则 MM:SS
• displayMs：倒计时为剩余值，正计时为已计值

5.2 添加计时器（POST /api/timers）

返回：{"success":true,"id":"<新计时器id>"}

6. WebSocket 推送（/ws）

连接后由服务端单向推送，消息结构：

{"event": "timers_changed", "data": {"timers": [ ... 同 5.1 ... ], "currentIndex": 0}}
{"event": "settings_changed", "data": { ... 同 GET /api/settings ... }}

• timers_changed：计时器增删改、状态与进度变化时推送（进度随计时持续刷新）；
• settings_changed：任意设置变更时推送（本地、API、控制台改动同源）；
• 客户端向 /ws 发送的消息服务端不处理；连接无鉴权，请依赖内网边界保护。

7. 错误码与响应约定

错误 body 统一为 {"error":"<中文说明>"}。

8. 调用示例

8.1 登录并添加计时器（curl）

# 登录
TOKEN=$(curl -s -X POST http://192.168.1.100:9527/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"password":"admin123"}' | sed 's/.*"token":"\([^"]*\)".*/\1/')

# 添加 10 分钟倒计时
curl -X POST http://192.168.1.100:9527/api/timers \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"label":"嘉宾发言","mode":"countdown","targetMs":600000}'

# 立即开始它（toggle）
curl -X POST http://192.168.1.100:9527/api/timers//toggle \
  -H "Authorization: Bearer $TOKEN"

8.2 修改剩余提醒点与播报文本

curl -X PUT http://192.168.1.100:9527/api/settings \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"countdownAlertMinutes":[10,5,3,1],"countdownAlertText":"请注意，还剩下{time}分钟","countdownAlertMethod":3}'

8.3 实时订阅计时状态（Node.js）

const WebSocket = require('ws')
const ws = new WebSocket('ws://192.168.1.100:9527/ws')
ws.on('message', m => {
  const msg = JSON.parse(m)
  if (msg.event === 'timers_changed') {
    const cur = msg.data.timers[msg.data.currentIndex]
    console.log(cur.label, cur.state, cur.formatted)
  }
})

9. 集成注意事项

• 单端口承载网页 + API + WebSocket；客户端并发无硬限制，控制台与集成方共存没有问题；
• REST 无幂等键：重复 toggle 会来回切换状态，集成方建议以 GET /api/timers 的 state 为准再操作；
• settings/reset 会恢复默认设置并清除持久化数据（当前会话正在运行的计时器不受影响，重启后回到默认队列）；集成时避免在会中误调；
• WebSocket 推送频率与计时节拍一致（约 500ms），第三方界面无需自行轮询；
• 所有设置类修改即时持久化，主程序重启后仍生效。

分享