05. 在线收发、通信记录与通联日志

1. 实时通信运行态

语音与文本进入同一群组路由。后端根据设备状态、群组、禁发/禁收、半双工状态决定是否转发，并可按站点配置记录音频和统计信息。

2. 在线收发

在线收发 /radio 使用浏览器 WebSocket 幽灵设备，固定 SSID 为 105。

功能：

• 自动连接 /ws。
• 选择唯一发送频道和多个接收频道。
• PTT 语音发射。
• 文本消息发送。
• 按真实来源频道归档消息并同步频道历史。
• 同时解码多个来源流，按频道开关和音量进行混音播放。
• 展示当前发言人。
• 展示连接状态。
• 同账号多个 Web、Android 或其他幽灵客户端同时在线。

使用注意：

• 页面需要麦克风和音频播放权限。
• 浏览器会持久化随机 client_instance_id；会话不会因同账号其他设备上线而断开。
• 发送频道会自动包含在接收集合中；切换发送频道不会取消其他已选收听频道。
• 单个会话默认最多接收 16 个频道。未携带实例 ID 或必需能力的旧客户端会被拒绝。
• 浏览器在线收发依赖 ws_token HttpOnly Cookie，不能在 URL 里传 token。
• 语音输入模式下可按住 PTT 或空格键说话。

相关 API：

Method	Path	Auth	说明
GET	/api/radio/config	JWT+Approved	在线收发配置。
GET	/api/radio/status	JWT+Approved	幽灵设备状态。
GET	/api/radio/sessions	JWT+Approved	当前账号的幽灵在线会话。
GET	/api/radio/groups/stats	JWT+Approved	群组实时统计。
GET	/api/radio/groups/:id/devices	JWT+Approved	群组在线设备。
PUT	/api/radio/sessions/:session_id/routing	JWT+Approved	原子更新指定会话的发送与接收频道。
DELETE	/api/radio/sessions/:session_id	JWT+Approved	断开自己的指定幽灵会话。
GET	/ws	Cookie(ws_token)	WebSocket 实时通联。

3. WebSocket 消息

WebSocket 同时承载两类消息：服务端文本控制事件，以及双向 DraARLv1 二进制帧。 客户端必须先处理文本控制事件（例如 auth_success、routing_updated），再处理媒体帧； 不能把控制 JSON 当作协议错误或交给二进制解码器。

常用包类型：

Type	说明
2	心跳。
4	文本消息。
5	Opus 16K 语音。

示例：

const ws = new WebSocket('wss://server.example.com/ws');
ws.binaryType = 'arraybuffer';

认证依赖 Cookie，无需也不能在 URL 中附加 token。现代客户端还会提交 client_instance_id、protocol_version=1 以及 multi_receive_v1,source_group_v1 能力；认证成功后服务端以文本控制消息返回 session_id 和完整路由状态。

4. 通信记录

通信记录页面分为：

• 平台发信记录：/comm-records/platform
• 后台全局记录：/admin/comm-records/platform

普通用户只能查看自己设备相关记录；管理员可在后台查看全局记录。

通信记录用于本人发信记录和审计，不等同于频道聊天历史。频道页面通过 GET /api/groups/:id/messages 按群组 ACL 查询所有可见发送者的已完成消息，使用 cursor 加载更早内容；单条消息和授权音频地址通过 GET /api/groups/:id/messages/:message_id 获取。

通信记录字段包括：

• 设备 ID、设备名称、设备型号。
• 群组 ID、群组名称。
• 开始时间、结束时间、持续时长。
• 音频文件 URL。
• 状态和统计字段。

相关 API：

Method	Path	Auth	说明
GET	/api/comm-records	JWT	通信记录列表。
GET	/api/comm-records/:id	JWT	通信记录详情。
GET	/api/comm-records/user-stats	JWT	当前用户通信统计。
GET	/api/comm-records/user-trend	JWT	当前用户通信趋势。
DELETE	/api/comm-records/:id	Admin	删除通信记录。
GET	/api/comm-records/system-stats	Admin	系统通信统计。
GET	/api/comm-records/system-trend	Admin	系统通信趋势。
GET	/api/groups/:id/messages	JWT+Approved	按频道查询语音/文本历史。
GET	/api/groups/:id/messages/:message_id	JWT+Approved	查询频道消息详情和授权音频地址。

5. 通信记录策略

管理员可在站点配置中设置音频记录策略：

• 是否启用音频记录。
• 数据保留天数。
• 最小录制阈值。
• 最大录制时长。
• 批量上传间隔。

如果启用音频记录，音频数据会写入当前 Storage 驱动（local、MinIO 或其他 S3 兼容 profile），索引和统计信息写入数据库。S3 读取使用预签名 URL，不应开放 bucket 匿名访问。

相关 API：

Method	Path	Auth	说明
GET	/api/config/comm-settings	Admin	读取通信设置。
PUT	/api/config/comm-settings	Admin	更新通信设置。

6. 通联日志

通联日志用于记录业余无线电 QSO 信息。用户可维护自己的记录，管理员可在后台管理所有记录。

字段包括：

• 我方呼号。
• UTC 时间。
• 发射/接收频率。
• CQ/ITU 分区。
• 通信模式。
• 对方呼号。
• 双方信号报告。
• 双方功率。
• QTH。
• 电台和天线。
• 备注。

电台预设可保存常用的电台、天线、功率、QTH，并在新增日志时快速填充。

相关 API：

Method	Path	Auth	说明
GET	/api/logbooks	JWT	我的通联日志列表。
GET	/api/logbooks/:id	JWT	我的通联日志详情。
POST	/api/logbooks	JWT	创建通联日志。
PUT	/api/logbooks/:id	JWT	更新通联日志。
DELETE	/api/logbooks/:id	JWT	删除通联日志。
DELETE	/api/logbooks/batch	JWT	批量删除通联日志。
GET	/api/admin/logbooks	Admin	管理员日志列表。
PUT	/api/admin/logbooks/:id	Admin	管理员更新日志。

7. 电台预设

电台预设用于通联日志快速填充。

相关 API：

Method	Path	Auth	说明
GET	/api/user/radio-presets	JWT	获取预设。
POST	/api/user/radio-presets	JWT	创建预设。
PUT	/api/user/radio-presets/:id	JWT	更新预设。
DELETE	/api/user/radio-presets/:id	JWT	删除预设。
PUT	/api/user/radio-presets/reorder	JWT	重排预设。