跳转至

13. 群组自动播报

1. 边界与权限

自动播报是中心服务进程的内部媒体来源，不注册为普通 UDP 设备，不占用用户 SSID、 设备密码、幽灵会话或任何用户可编辑的呼号。通信记录中的固定发送者快照为 system-broadcast / AUTO / 自动播报。

只有实体组的群主或站点管理员可管理该实体组的音频、计划和执行记录。虚拟组不提供 音频或计划创建入口；其策略只由管理员管理。站点还必须在配置中设置 Broadcast.Enabled: true，否则上传和手动触发返回 503 broadcast_disabled。

2. 时间、静默与话权

计划类型为 once、daily、weekly、interval：

  • once 使用 UTC scheduled_at；到期后不再排期。
  • daily 使用 IANA timezone 与本地 local_time。
  • weekly 在 daily 字段基础上使用 weekday_mask，位 1 << weekday，其中 Sunday=0。
  • interval 使用 interval_seconds 和 interval_start_at 设定计时 0 点，取整分钟且范围为 60 秒到 30 天；按 0 点递进， 服务恢复或扫描延迟时跳过已经错过的轮次，不补播。此类型不使用 local_time、 weekday_mask；timezone 仅用于解释可选禁播时段。
  • 所有计划均可提供成对的 blackout_start_time 与 blackout_end_time，使用计划的 timezone 和半开区间 [start, end)。开始时间晚于结束时间表示跨午夜，例如 22:00:00 至 07:00:00。窗口内的自动触发点直接省略，不生成执行记录，也不改变 间隔计划的原始节拍；手动触发不受禁播时段限制。
  • 夏令时不存在的本地时刻跳过；重复的本地时刻只执行第一次。

已有数据库升级后需按部署约定带一次 -auto-migrate 启动，以新增计划表中的禁播时段列； 全新空库会自动初始化。

每次到点都是独立轮次。同一个音频可被多个计划引用，也可以由不同计划引用不同音频； 不会合并、延迟或补播。服务重启、站点运行开关关闭或虚拟互联关闭期间错过的轮次都只 推进到下一次未来时间。

执行前服务端在当前活动通信域原子检查最近已接受语音：任一成员在最近 5 秒有语音帧， 本轮写为 skipped_recent_voice。静默后自动播报作为普通说话人取得现有严格半双工 话权；没有抢占优先级。开始播放后，真实设备同样受严格半双工限制，直到播放结束、 管理员停止或生命周期变更取消。单条音频默认最多 30 秒，硬上限为 60 秒。

3. 虚拟互联策略

实体组未被启用的虚拟组互联时，计划正常运行且只投递来源实体组。已关联但虚拟组关闭 的情况也相同。虚拟组实际开启时必须读取持久化策略：

  • suspend_all：成员实体组全部挂起，不产生媒体或自动播报通信记录。
  • allow_single_source：仅指定的一个成员实体组可以执行计划；其活动域和发送快照包含 该虚拟组全部实体成员。

策略保证一个活动互联域最多有一个自动播报来源。被允许的来源播放期间仍占用整个互联 域的话权。普通语音、文本和该播报均在发送时用同一投递群组快照；关闭状态的虚拟组绝不 扩展历史或新消息的投递范围。

4. 实体组管理 API

所有以下接口均为 JWT+Approved，并需要群主或管理员权限。

Method Path 说明
GET /api/groups/:id/broadcast-context 当前互联、策略与本实体组是否允许播报
GET/POST /api/groups/:id/broadcast-audios 音频列表或 multipart 上传
GET/DELETE /api/groups/:id/broadcast-audios/:audioId 详情/试听或删除
GET/POST /api/groups/:id/broadcast-schedules 计划列表或创建
PATCH/DELETE /api/groups/:id/broadcast-schedules/:scheduleId 修改或删除
POST /api/groups/:id/broadcast-schedules/:scheduleId/run 手动触发一次
GET /api/groups/:id/broadcast-runs 分页执行历史
POST /api/groups/:id/broadcast-runs/:runId/cancel 停止已认领或播放中的执行

音频上传使用 multipart/form-data，字段为 file 与可选 name。原文件先写入私有 对象存储，再由受控 ffprobe/ffmpeg 处理为 16kHz / mono / Opus VOIP / 60ms 的 播放文件。执行路径只读取已验证的播放文件；不会在到点时转码。列表中的 status 为 processing、ready 或 failed，仅 ready 音频可播放。详情中的 preview_url 为 短时试听 URL。

创建或更新计划的例子：

{
  "audio_id": 12,
  "name": "晚间点名",
  "schedule_type": "daily",
  "timezone": "Asia/Shanghai",
  "local_time": "20:00:00",
  "enabled": true
}

一次计划使用 scheduled_at（RFC3339）；每周计划额外提供 weekday_mask。返回计划的 effective_enabled=false 表示计划本身虽可用，但当前正被开启的虚拟组策略挂起。

间隔计划示例：

{
  "audio_id": 12,
  "name": "每 15 分钟提醒",
  "schedule_type": "interval",
  "timezone": "Asia/Shanghai",
  "interval_seconds": 900,
  "interval_start_at": "2026-08-09T00:00:00Z",
  "blackout_start_time": "22:00:00",
  "blackout_end_time": "07:00:00",
  "enabled": true
}

运行状态包括 succeeded、skipped_recent_voice、skipped_domain_busy、 skipped_interconnected、skipped_no_receiver、skipped_site_disabled、cancelled 和 failed。skipped_no_receiver 表示取得话权时，冻结的 UDP/UDP 幽灵接收快照、当前可接收的 WebSocket 会话及在线边缘投影中均没有接收者；服务端会立即释放话权，不进入播放或发送媒体。 error_code 会细分手动停止、计划停用、 音频撤销、群组停用、开启互联、站点紧急停止及服务关闭等原因。手动触发也复用全部资格 和话权校验。

删除音频、停用或删除计划、停用或删除群组、切换互联拓扑、删除用户都会先取消并等待 受影响的当前播放释放。计划和音频为软删除，既有执行历史保留；删除实体组时该组资源和 执行历史按外键顺序硬删除，并在事务提交后清理对象文件。若对象清理暂时失败，响应的 cleanup_pending 或 broadcast_cleanup_pending 为 true，可通过对象审计追踪。

5. 虚拟组与站点运维 API

管理员使用 PUT /api/group-links/:id/broadcast-policy 保存策略，例如：

{ "mode": "allow_single_source", "allowed_source_group_id": 1001 }

或全部暂停：

{ "mode": "suspend_all" }

GET /api/group-links/:id 返回 broadcast_policy 和 broadcast_members；列表返回策略摘要。 状态开关不重复询问策略。移除当前唯一来源前必须先更改策略。

站点管理员还可使用：

Method Path 说明
GET /api/broadcast/metrics 持久化执行统计、调度器与转码队列指标
GET /api/broadcast/health 调度器、媒体处理器和运行开关健康快照
PUT /api/broadcast/runtime 请求体 { "enabled": false }，关闭/开启运行态
POST /api/broadcast/emergency-stop 紧急停止当前任务并建立取消栅栏

运行态重新开启时，停用期间已经错过的计划不会补发。部署级 Broadcast.Enabled 与持久化 运行态是两层开关：前者决定该能力是否被部署，后者用于日常紧急停用。

6. 通信记录与责任边界

播放成功或已发送媒体的执行会写一条带 is_auto_broadcast=true 的通信记录及发送时的 comm_record_delivery_groups 快照。不会把音频复制成通信录音，记录的 audio_path 为空、 audio_size=0；原始文件和播放文件仍只在自动播报音频库。

射频台站设备由相应台站管理员自行接入、配置并对其射频运行负责，平台只向已经审核的 用户提供服务。自动播报音频和计划仅允许平台管理员或实体组群主管理，并由相应管理员 维护和审查播报内容。