lxc-streamutils/apps/overlay

React 控制台与 OBS 前端

Vite 在 Docker build stage 编译本目录，最终静态文件由 Rust 同域托管。生产容器不包含 Node。

路由

路由	权限	作用
/control/	登录用户	直播源、组件、测试、设置和 OBS token
/control/invitations	system admin	创建/撤销绑定房间的邀请码
/control/components/:id/song-requests	登录用户	点歌队列、统计与管理操作
/control/login	匿名	用户名 + TOTP/恢复码登录
/control/register	匿名受邀用户	邀请码注册与 TOTP enrollment
/control/setup	首次部署	创建唯一 system admin
/obs/:publicId	component token	透明 OBS 浏览器源

main.tsx 在初始化控制台前先识别 OBS 路由，因此 OBS 不会注册 PWA 或请求账户 session。

文件职责

文件	职责
src/api.ts	same-origin fetch、错误模型和兼容性 normalizer
src/auth.tsx	passwordless login、TOTP QR 与恢复码
src/control.tsx	tenant component studio 和 system-admin 邀请码页面
src/stream.ts	通用组件 WebSocket 鉴权、重连和 renderer 分流
src/overlay.tsx	弹幕、礼物/表情和 OBS 自适应渲染
src/songOverlay.tsx	点歌快照 reducer、revision 校验与往返滚动
src/pwa.tsx	install prompt、离线状态、显式更新和敏感状态 blocker
src/i18n.tsx	TOML 语言资源、浏览器回退和运行时切换
src/types.ts	sanitized API view model 与 overlay settings
pwa/control-sw.js	/control/ 静态壳层的缓存策略

Secret 与状态

• TOTP Secret、恢复码、邀请码和新 OBS 地址只保存在当前 React state。
• API normalizer 不把未知对象直接传播到组件。
• API mutation 离线时立即失败，不进入 Background Sync。
• PWA 更新在 dirty form 或一次性 secret 可见时被阻止。
• OBS token 从 URL fragment 读取，只在 WebSocket 第一帧发送。
• OBS 收到坏 JSON、坏图片或未知事件时局部降级，不让浏览器源崩溃。

PWA

manifest、start URL 与 Service Worker scope 均为 /control/。worker 使用 network-first HTML 和 cache-first build assets；/api/*、/obs/*、WebSocket 和用户数据永不缓存。每次 Vite build 把同一个 build ID 注入浏览器 bundle 与 worker，发现更新后等待用户确认激活。

语言资源

../../resources/i18n.toml 是控制台、OBS 组件、API 错误和 PWA metadata 的唯一文案来源。Vite 在构建时解析并注入它，Rust 则嵌入同一文件来验证允许保存的 locale。增加文案键时必须为每个 locale 提供值；增加语言时同时增加完整 [locales."<code>".messages] 段。业务命令如“点歌”是 Bilibili 输入协议，不属于 UI 翻译。

格式化与构建

npm run format
npm run format:check
npm run docs:check
npm run build

npm run format 使用仓库根目录的 Prettier 配置，同时格式化 TypeScript、TSX、CSS、HTML、JSON、Markdown、Compose YAML 和项目文档。

组件协议与弹幕姬行为分别见：

• 实时协议
• 弹幕姬组件
• 点歌姬组件