felis
f79852d8e6
Centralize control and OBS copy in a shared TOML catalog, persist the selected locale per account, and broadcast language changes to component streams. Allow account owners to atomically switch their Bilibili room and restart the shared listener without changing component URLs.
73 lines
4.0 KiB
Markdown
73 lines
4.0 KiB
Markdown
# 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 翻译。
|
||
|
||
## 格式化与构建
|
||
|
||
```bash
|
||
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 和项目文档。
|
||
|
||
组件协议与弹幕姬行为分别见：
|
||
|
||
- [实时协议](../../docs/protocol.md)
|
||
- [弹幕姬组件](../../docs/components/danmaku-overlay.md)
|
||
- [点歌姬组件](../../docs/components/song-request.md)
|