lxc-streamutils/docs/components

组件开发指南

组件是“消费所属账户事件流的独立功能实例”。当前内建 danmaku_overlay、song_request、 gift_effect 与 gift_menu，未来礼物墙或统计组件也应使用同一套契约。

一个组件由什么组成

部分	Rust 契约	职责
定义	ComponentDefinition	kind、设置版本、默认值、校验、迁移、订阅
投影	EventProjection	把 LiveEvent 转成浏览器消息，不执行持久化副作用
Handler	EventHandler	可选的数据库写入、点歌或外部动作
实例	ComponentInstance	owner、kind、名称、设置和启用状态
实时通道	EventHub	按 component ID 隔离的有界广播
前端	React renderer/editor	管理设置、测试与 OBS 展示

新增组件步骤

1. 选择稳定、全小写的 kind，例如 gift_wall 或 song_request。
2. 为设置定义可序列化结构，提供安全默认值和 sanitize/校验逻辑。
3. 实现 ComponentDefinition：
   • settings_version 从 1 开始。
   • migrate_settings 必须能把已保存的旧版本升级到当前版本。
   • subscriptions 只返回当前设置需要的 LiveEventKind。
4. 实现无副作用的 EventProjection。返回 None 表示该事件无需发送浏览器。
5. 若需要可靠业务动作，实现 EventHandler：
   • 即使没有 OBS 客户端也会执行。
   • 数据库操作必须包含 owner/component 条件。
   • 上游可能重试或出现组合事件，因此 handler 自己负责幂等。
6. 在 ComponentRegistry::with_builtin_components 注册定义与投影，再注册 handler。
7. 增加数据库创建/设置 API；不要把组件专属关系数据无限塞入 JSON settings。
8. 在控制台增加设置编辑器，在 OBS 前端增加对应事件渲染器。
9. 增加以下测试：设置边界、版本迁移、订阅、跨租户拒绝、handler 幂等、投影 wire shape 和 OBS 渲染。

Projection 与 Handler 的边界

Projection 面向“现在打开的浏览器”。消息丢失或没有接收者都属于正常情况。它必须快速、确定、无副作用。

Handler 面向“业务事实”。例如点歌请求、礼物累计或审计写入必须在这里完成，而不是等待前端收到 WebSocket。一个 handler 失败会记录在 RouteReport，但不会阻止其他 handler 或 OBS 投影。

设置版本规则

• 数据库同时保存 settings 与 settings_version。
• 每次读取或路由前，通过 registry 迁移并校验设置。
• 新字段应提供默认值，删除/改义字段必须增加版本并编写迁移。
• 客户端输入只能作为待校验 JSON；后端返回的 sanitized 设置才是权威值。
• UI slider 的范围不能代替后端范围检查。

租户与 token 规则

• 组件必须属于经过认证的 owner，不能选择或覆盖账户直播源。
• 路由和数据库查询都要重复检查 owner；账户事件可被其所有启用组件订阅。
• 每个组件单独签发 access token，默认只有 events:subscribe。
• 删除组件或轮换 token 时，关闭该组件 channel，使已有 socket 立即失效。
• 组件 WebSocket 不得暴露其他组件列表或控制 API。

当前组件的具体行为见 danmaku-overlay.md 与 song-request.md、gift-effect.md 与 gift-menu.md。