old backend core lib

docs/components/README.md

@@ -1,7 +1,7 @@
 # 组件开发指南
 
-组件是“一个直播源上的独立功能实例”。当前内建
-`danmaku_overlay`，未来礼物墙、点歌姬或统计组件都应使用同一套契约。
+组件是“一个直播源上的独立功能实例”。当前内建 `danmaku_overlay` 与
+`song_request`，未来礼物墙或统计组件也应使用同一套契约。
 
 ## 一个组件由什么组成
 
@@ -55,4 +55,5 @@ Handler 面向“业务事实”。例如点歌请求、礼物累计或审计写
 - 删除组件或轮换 token 时，关闭该组件 channel，使已有 socket 立即失效。
 - 组件 WebSocket 不得暴露其他组件列表或控制 API。
 
-当前组件的具体行为见 [`danmaku-overlay.md`](danmaku-overlay.md)。
+当前组件的具体行为见 [`danmaku-overlay.md`](danmaku-overlay.md) 与
+[`song-request.md`](song-request.md)。

docs/components/danmaku-overlay.md

@@ -14,6 +14,7 @@
 
 | 字段                     | 范围/单位   | 行为                       |
 | ------------------------ | ----------- | -------------------------- |
+| `themeId`                | 主题 ID     | 选择已安装的完整视觉主题   |
 | `fontScale`              | 50–300%     | 展开与收缩字号的统一比例   |
 | `maxVisible`             | 1–12        | 同时保留的消息卡数量       |
 | `collapseAfterSeconds`   | 2–120 秒    | 最新卡从展开态切换到紧凑态 |
@@ -28,6 +29,20 @@
 
 后端的 `OverlaySettings::sanitize` 是最终边界。控制台 range input 只改善交互，不能取代服务端校验。
 
+## 主题
+
+主题同时封装配色、花纹素材、装饰变体、粒子组合与动画名称。当前内置主题为
+`jade-scroll`（“青玉花卷”）；控制台仍以选择框呈现，新增主题后无需改变设置交互或卡片队列。
+
+增加主题时需要同步完成三处注册：
+
+1. 在后端 `OverlayThemeId` 中增加稳定 ID，使未知主题无法进入数据库。
+2. 在 `apps/overlay/src/themes/` 增加主题定义，并注册到 `overlayThemes`。
+3. 提供主题使用的 CSS 动画和素材；不要在 `Card` 中加入按主题 ID 分支。
+
+旧组件没有 `themeId` 时会自动使用
+`jade-scroll`。WebSocket 收到未知 ID 时前端也会安全降级到该主题，以支持前后端滚动部署。
+
 ## 卡片生命周期
 
 1. 新事件插入队首，以卷轴动画横向展开。

docs/components/song-request.md

@@ -0,0 +1,25 @@
+# `song_request` 点歌姬
+
+每个账户自动拥有一个不可删除、不可重复创建的 `song_request`
+实例，并与该账户的固定直播源绑定。组件只订阅规范化的
+`live.danmaku`；业务状态由 PostgreSQL 保存，不依赖 OBS 是否在线。
+
+## 弹幕命令
+
+- `点歌 <歌名>`：合并首尾和连续空白，接受 1–80 字自由文本。当前或待唱队列中已有大小写不敏感的同名歌曲时忽略。
+- `打分 <1-5>`：对事务执行时的当前歌曲评分。同一 Bilibili UID 只有一票，重复评分会覆盖旧分数。
+
+首首点歌立即成为当前歌曲。完成或取消当前歌曲时，队首自动接替；置顶待唱项只把它移动为下一首，不打断当前歌曲。完成或取消后的歌名可以再次点播。
+
+## 设置
+
+`themeId`、`fontScale`、`scrollSpeedPixelsPerSecond` 和 `edgePauseSeconds`
+控制 OBS 外观与往返滚动。`maxQueueSize`、`maxRequestsPerViewer` 与 `requestCooldownSeconds`
+是可选防刷限制；值 `0` 表示不限制。
+
+## OBS 与管理
+
+OBS 顶部固定显示当前歌曲、点歌用户、平均分和评分人数，下面保存全部待唱横条。列表超过实际浏览器源高度时从顶部滚到底部，再返回顶部；布局不假设固定分辨率。
+
+控制台的“打开点歌统计”进入会话保护页面。它每两秒刷新完整活动队列和近期历史；页面隐藏时停止轮询。管理者可以置顶或取消待唱项，也可以完成或取消当前歌曲。所有 REST 查询都从会话取得 owner，并由 PostgreSQL
+RLS 再次限制组件归属。