formatting and comments

2026-07-16 00:12:26 -07:00
parent edb6d2b5b4
commit 994854d104
45 changed files with 2514 additions and 628 deletions
@@ -0,0 +1,61 @@
+# React 控制台与 OBS 前端
+
+Vite 在 Docker build stage 编译本目录，最终静态文件由 Rust 同域托管。生产容器不包含 Node。
+
+## 路由
+
+| 路由                   | 权限            | 作用                                 |
+| ---------------------- | --------------- | ------------------------------------ |
+| `/control/`            | 登录用户        | 直播源、组件、测试、设置和 OBS token |
+| `/control/invitations` | system admin    | 创建/撤销绑定房间的邀请码            |
+| `/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/overlay.tsx`   | WebSocket、消息队列、礼物/表情和 OBS 自适应渲染      |
+| `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)