RTC API 对接：持续录制、档案、播放与下载

适用 1.0.0.158。一个会议用 roomId 标识，一次录制用 recordingId 标识；同一会议可以有多次录制。会中主持人或具 rtc.manage 的业务 API 可以启停；会后查看使用独立 rtc.recordings.view/play/download 权限或该业务后端签发的短时档案票据。入会 RTC Token 不能替代档案票据。

会中：允许、启动、查询、停止

接口	入参	返回与确认	权限/特殊情况
`PUT /api/v2/rtc/rooms/{roomId}/recording-policy`	JSON `{ "enabled": true/false }`	房间录制策略	会议所有者或超级管理员；允许录制不等于已经开始。
`POST /api/v2/rtc/rooms/{roomId}/recording/continuous/start`	房间 ID，无请求体	`recordingId`、`Starting/Recording`、时间原点	`rtc.manage`；同房间已有活动任务时返回当前任务，不新开第二份。
`GET /api/v2/rtc/rooms/{roomId}/recording/continuous/current`	房间 ID	当前任务或空	业务后台可轮询；空只表示没有活动录制。
`POST /api/v2/rtc/rooms/{roomId}/recording/continuous/{recordingId}/stop`	指定任务 ID	`Stopping`，随后 `Stopped`	`rtc.manage`；`Stopping` 时原轨还在封口，不能立刻下载。
`POST /api/v2/rtc/session/rooms/{roomId}/recording/continuous/start` / `.../{recordingId}/stop`	会中设备 Token；停止带录制 ID	同一任务状态	仅当前主持人；主持移交后旧主持人返回403。
`GET /api/v2/rtc/session/rooms/{roomId}/recording/continuous/current`	当前设备 Token	当前状态或空	已准入普通成员也能知道会议正在录制。
`GET /api/v2/rtc/rooms/{roomId}/recording/continuous/runs` / `GET /api/v2/rtc/session/rooms/{roomId}/recording/continuous/runs`	房间 ID、对应业务或档案身份	历史任务列表	与查询当前活动任务不同；访问范围由档案权限决定。

旧 recording/start、recording/stop、recording/targets 是逐 Publication 的兼容入口，不应拿来代替整场持续录制。会中原始音视频按现有编码复制到独立轨，不额外生成实时混流；成员/屏幕兼容副本与整场 MP4 在会后处理。静音或断网时段保留真实缺口，不能用旧画面冒充实时画面。

业务后端：按会议签短时档案票据

POST /api/v2/rtc/rooms/{roomId}/recordings/access
Authorization: Bearer <业务后端平台会话或 API Token>
Content-Type: application/json

{"actions":["view","play","download"],"lifetimeSeconds":120}

请求 actions 只允许 view/play/download，默认 view+play，请求 play 或 download 时服务端也加入 view；有效期限制 30–600 秒，默认 120。响应包含 token、roomId、实际 actions、expiresAtUtc。签发者不能授予自己没有的权限，使用时继续复核原会话/API Token、账号、权限和会议范围。将短票据交给获准客户端，长期管理 Token 留在业务后端。

动作	权限	能做什么	不能做什么
`view`	`rtc.recordings.view`	列表、清单、公开事件、附件预览	不能播放媒体或下载 ZIP。
`play`	`rtc.recordings.play`，同时需 `view`	HTTP Range 播放本次录制文件和整场 MP4	不是下载授权。
`download`	`rtc.recordings.download`，同时需 `view`	下载本次文件、附件、ZIP 与整场 MP4	不包含其他会议或私聊内容。

票据查询用 Authorization: Bearer <档案票据>；资源返回的短时 URL 中可能带 rtc_archive_token，只用于获准的只读路径，过期后重新签发，禁止公开转发。rtc.manage 管理员具备管理路径，但业务终端只拿最小档案动作。

查询任务、时间线和设备

接口	入参	返回	特殊情况
`GET /api/v2/rtc/recordings`	`roomId`、`search`、`state`、`fromUtc/toUtc`、`participantId/deviceSessionId`、`page/pageSize`	`total/page/pageSize/items[]`，每项含 `recordingId`、状态、开始时间、人数/设备数	页大小 1–100；时间过滤录制开始时间左闭右开；授权、筛选先于计数和分页。
`GET /api/v2/rtc/session/rooms/{roomId}/playback/recordings/{recordingId}/manifest`	`afterSequence`、`maxEvents`	`originAtUtc`、`durationMilliseconds`、`tracks[]`、`composites[]`、`events[]`、`hasMoreEvents/nextSequence`	每页事件可能不完整；按 `nextSequence` 续读。文件偏移和事件偏移共用原点。
`GET .../full-exports`	`recordingId`	每次导出的 ID、区间、状态、文件	`Pending/Running/Failed` 不应出现假播放链接。

上述 GET .../full-exports 的完整前缀为 /api/v2/rtc/session/rooms/{roomId}/playback/recordings/{recordingId}。tracks[] 按 participantId + deviceSessionId + mediaKind 分路；同一成员换机可有多台设备，设备会话不是硬件 ID。events[] 包含服务端允许回放的公开聊天、白板、控制和设备发言事件。私发消息/附件不会因主持身份自动变公开；旧客户端或旧任务缺事件时显示“未知”，不要推断历史。

媒体、附件、ZIP 与整场导出

以下读取接口共享前缀 /api/v2/rtc/session/rooms/{roomId}/playback/recordings/{recordingId}，均会复核文件/附件是否确实归属本次会议和录制。

方法与后缀	所需动作	返回/用途	特殊情况
`GET /files/{fileId}/media`	`play`	原轨或成员副本，支持 HTTP Range	播放器保存当前位置；短票据过期时换 URL。
`GET /files/{fileId}/download`	`download`	指定文件附件响应	不能用猜到的 `fileId` 读其他任务。
`GET /attachments/{attachmentId}/content`	`view`	本次公开图片、视频、PDF或文本预览	其他类型可能返回415；私聊或区间外引用不可见。
`GET /attachments/{attachmentId}/download`	`download`	获准公开附件下载	附件仍按原会议可见范围检查。
`GET /package`	`download`	本次原轨、成员/屏幕副本、公开事件及附件 ZIP	大包流式返回；不可用附件在清单中说明，不伪造文件。
`GET /full-exports/{exportId}/media` / `/download`	`play` / `download`	已完成的固定布局 MP4，播放支持 Range	只有 `Available` 的整场导出可读取。

业务后台按需排队整场导出：

POST /api/v2/rtc/rooms/{roomId}/recording/continuous/{recordingId}/full-exports
Authorization: Bearer <具备 rtc.manage 的业务 API Token>
Content-Type: application/json

{"startMilliseconds":0,"endMilliseconds":60000}

起止是相对录制原点的毫秒，start < end 且不能越过有效范围；返回导出任务 ID 后查询状态。失败的会后成员/屏幕副本和整场导出分别有 .../composites/{compositeId}/retry、.../full-exports/{exportId}/retry 管理入口，重试需仍有原轨和授权。整场导出完成后再取得可播放成品。

失败处理

结果	处理
401	票据过期、签发者源凭据撤销；从业务后端重新取得，不使用 RTC 入会 Token。
403	缺动作或当前用户无此会议档案权限；停止重试并请求授权。
404	会议、录制、文件、附件不属于同一可见范围；重新查列表和清单。
415	不支持站内预览的附件格式；有 `download` 权限时走下载入口。
`Starting/Recording/Stopping`	会中任务状态，`Stopping` 后继续等 `Stopped` 和文件索引。
`Pending/Running/Failed/Available`	副本或导出状态；只把 `Available` 作为可播放产物。