old backend core lib

docs/protocol.md

@@ -33,14 +33,18 @@ log。WebSocket 建立后，客户端必须在 8 秒内发送第一帧：
 {
   "version": 1,
   "type": "authenticated",
-  "componentId": "08d31d19-3e4b-4c11-9cf7-9bd786a39465"
+  "componentId": "08d31d19-3e4b-4c11-9cf7-9bd786a39465",
+  "componentKind": "song_request"
 }
 ```
 
-之后立即发送
-`overlay.settings.snapshot`，再开始发送实时事件。token 无效、被轮换或属于其他组件时，服务端以 policy
+之后立即发送通用的 `component.settings.snapshot`，再发送该 kind 的状态快照和实时事件。弹幕姬还会发送
+`overlay.settings.snapshot` 兼容帧。token 无效、被轮换或属于其他组件时，服务端以 policy
 close 结束连接。
 
+设置快照中的 `themeId` 是稳定的主题标识，目前支持
+`jade-scroll`。消费者应把未知主题降级为自身默认主题，不能因主题发布顺序不同而中断实时消息。
+
 ## 版本化事件信封
 
 ```json
@@ -65,19 +69,33 @@ close 结束连接。
 
 ## 事件类型
 
-| `type`                      | 主要 payload                                  | 说明                   |
-| --------------------------- | --------------------------------------------- | ---------------------- |
-| `overlay.settings.snapshot` | `settings`                                    | 认证后当前设置快照     |
-| `overlay.settings.updated`  | `settings`                                    | 控制台保存后的实时设置 |
-| `live.danmaku`              | `viewer`, `text`, `segments`                  | 普通文字和表情分段     |
-| `live.enter`                | `viewer`                                      | 进房事件               |
-| `live.gift`                 | `viewer`, `gift`, `quantity`, `sourceEventId` | 一次可记账的礼物事件   |
-| `live.gift.combo`           | `viewer`, `gift`, `quantity`, `comboId`       | 同一连击的视觉更新     |
-| `live.superchat`            | `viewer`, `message`, `price`, `sourceEventId` | 醒目留言               |
-| `live.guard.buy`            | `viewer`, `guardName`, `quantity`, `price`    | 舰长购买               |
-| `live.like`                 | `viewer`                                      | 点赞                   |
-| `live.share`                | `viewer`                                      | 分享                   |
-| `live.unknown`              | `command`, `metadata`                         | 有界且已清理的未知事件 |
+| `type`                        | 主要 payload                                  | 说明                   |
+| ----------------------------- | --------------------------------------------- | ---------------------- |
+| `component.settings.snapshot` | `settings`                                    | 所有组件的设置快照     |
+| `component.settings.updated`  | `settings`                                    | 所有组件的设置更新     |
+| `overlay.settings.snapshot`   | `settings`                                    | 认证后当前设置快照     |
+| `overlay.settings.updated`    | `settings`                                    | 控制台保存后的实时设置 |
+| `live.danmaku`                | `viewer`, `text`, `segments`                  | 普通文字和表情分段     |
+| `live.enter`                  | `viewer`                                      | 进房事件               |
+| `live.gift`                   | `viewer`, `gift`, `quantity`, `sourceEventId` | 一次可记账的礼物事件   |
+| `live.gift.combo`             | `viewer`, `gift`, `quantity`, `comboId`       | 同一连击的视觉更新     |
+| `live.superchat`              | `viewer`, `message`, `price`, `sourceEventId` | 醒目留言               |
+| `live.guard.buy`              | `viewer`, `guardName`, `quantity`, `price`    | 舰长购买               |
+| `live.like`                   | `viewer`                                      | 点赞                   |
+| `live.share`                  | `viewer`                                      | 分享                   |
+| `live.unknown`                | `command`, `metadata`                         | 有界且已清理的未知事件 |
+
+## 点歌姬状态
+
+`song_request` 认证后按顺序接收：
+
+1. `song.queue.snapshot.begin`：包含 `snapshotId`、`revision`、当前歌曲和待唱总数。
+2. 零到多个 `song.queue.snapshot.page`：每页最多 100 个待唱项。
+3. `song.queue.snapshot.end`：提交该快照。
+
+后续 `song.queue.changed` 携带连续 revision，`operation` 为 `added`、`promoted`、
+`completed`、`cancelled` 或
+`rating-updated`。客户端发现 revision 缺口必须重连取得新快照，不能猜测缺失队列状态。
 
 礼物目录价格的原始单位是人民币的千分之一。`gift.totalPrice` 保留该整数单位，`gift.priceCny`
 是供展示使用的人民币数值。