66 lines
3.5 KiB
Markdown
66 lines
3.5 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/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，发现更新后等待用户确认激活。
|
||
|
||
## 格式化与构建
|
||
|
||
```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)
|