05. 无线电与实时通信

1. 在线收发 API（JWT + Approved）

GET /api/radio/config

返回示例：

{
  "code": 200,
  "data": { "ssid": 105, "default_group": 999, "enabled": true },
  "connected": true
}

PUT /api/radio/ssid

请求：

{ "ssid": 105 }

GET /api/radio/status

返回示例：

{
  "code": 200,
  "data": {
    "connected": true,
    "group_id": 999,
    "online_since": "2026-04-05 15:10:00",
    "callsign": "BG7XXX",
    "ssid": 105,
    "is_speaking": false,
    "voice_sending": false
  }
}

GET /api/radio/groups/stats

返回用户可访问群组的实时在线统计（含 WS 设备）。

GET /api/radio/groups/:id/devices

返回该群组在线设备（UDP + WS），字段含： - is_ghost - disable_send（设备级） - disable_recv（设备级） - last_activity

PUT /api/radio/group

请求：

{ "group_id": 1001, "dev_model": 105 }

说明： - dev_model=105：WebSocket 幽灵设备。 - 101-104：UDP 幽灵设备（安卓/iOS/Windows/macOS）。

GET /api/radio/conflict

功能：连接前检查幽灵设备冲突。

返回（冲突）：

{ "code": 409, "message": "您的账号已在其他页面建立了电台连接，请先断开其他页面的连接", "data": { "conflict": true } }

2. WebSocket /ws

2.1 鉴权

• 必须携带 ws_token HttpOnly Cookie。
• 若用户已有在线幽灵设备连接，返回 409 ghost_device_conflict。

2.2 消息格式

• 仅接受二进制消息。
• 协议头 90 字节，采用 DraARLv1 帧格式。
• 常用类型：
• 2 心跳
• 4 文本消息
• 5 Opus 语音

2.3 示例（伪代码）

const ws = new WebSocket('wss://server.example.com/ws');
ws.binaryType = 'arraybuffer';
// 认证依赖 Cookie，无需在 URL 附 token

3. UDP 协议（设备侧）

设备与服务器 UDP 通信遵循 DraARLv1： - 规范文档：docs 目录 Protocol.md - 核心点： - 固定头 90 字节 - 大端序 - 最大包长 800 字节 - 支持 TypeConfig 配置同步 TLV