Refactor LED control UI to Vue3

2026-07-17 02:10:08 +08:00
parent fe906e028b
commit ba9f0044f3
16 changed files with 1906 additions and 752 deletions
@@ -0,0 +1,279 @@
+# 使用文档
+
+## 1. 环境要求
+
+- Python `3.10` 到 `3.12` 推荐。
+- macOS 本机如果没有 `python` 命令，使用 `python3` 或明确的 Python 3.12 路径。
+- 浏览器建议使用 Chrome / Chromium / Edge。
+- 生产输出服务器建议关闭休眠、屏保和自动更新弹窗。
+
+当前项目依赖见：
+
+```text
+requirements.txt
+pyproject.toml
+```
+
+## 2. 首次启动
+
+在项目根目录执行：
+
+```bash
+cd /Users/tjy/Documents/code/work/dp
+/Users/tjy/.local/bin/python3.12 -m venv .venv
+.venv/bin/python -m pip install -r requirements.txt
+.venv/bin/python -m led_platform.cli serve
+```
+
+服务默认监听：
+
+```text
+0.0.0.0:8000
+```
+
+如果要指定端口：
+
+```bash
+.venv/bin/python -m led_platform.cli serve --host 0.0.0.0 --port 8000
+```
+
+## 3. 日常启动
+
+```bash
+cd /Users/tjy/Documents/code/work/dp
+.venv/bin/python -m led_platform.cli serve
+```
+
+查看本机局域网地址：
+
+```bash
+.venv/bin/python -m led_platform.cli urls
+```
+
+也可以直接查看：
+
+```bash
+ipconfig getifaddr en0
+```
+
+## 4. 常用地址
+
+本机访问：
+
+```text
+控制台:     http://127.0.0.1:8000/
+左输出:     http://127.0.0.1:8000/output/left
+右输出:     http://127.0.0.1:8000/output/right
+健康检查:   http://127.0.0.1:8000/healthz
+同步状态:   http://127.0.0.1:8000/api/sync/status
+API 文档:   http://127.0.0.1:8000/docs
+```
+
+局域网访问时，把 `127.0.0.1` 换成控制服务 IP，例如：
+
+```text
+http://192.168.0.182:8000/
+```
+
+## 5. 控制台使用
+
+打开：
+
+```text
+http://控制服务IP:8000/
+```
+
+控制台包含：
+
+- 画面回显：把 left/right 两个只读预览无缝拼成一块完整画面，桌面布局下位于控制台顶部。
+- 场景切换：切换 overview、energy、security。
+- 输出与同步：查看输出端连接数量、FPS、frame time、RTT、clock offset。
+- 生产命令回显：查看真实 `/output/left` 和 `/output/right` 的 prepared、放行、committed 状态。
+- 局部动作：翻页、能源模式、告警、暂停/恢复时间轴。
+
+画面回显使用：
+
+```text
+/output/left?preview=1
+/output/right?preview=1
+```
+
+控制台会把两个预览 iframe 贴在一起，形成 `14880 x 3510` 的完整大屏回显。它是只读预览，不会参与真实输出端 ACK。所以上方画面变化只代表控制台预览已更新；生产命令回显里的等待、放行和完成，代表真实输出端是否已经 ACK。
+
+## 6. 生产输出端使用
+
+左 GPU 输出服务器打开：
+
+```text
+http://控制服务IP:8000/output/left
+```
+
+右 GPU 输出服务器打开：
+
+```text
+http://控制服务IP:8000/output/right
+```
+
+输出端打开后会：
+
+1. 请求 `/api/bootstrap/{tile_id}` 获取 tile、场景和当前状态。
+2. 连接 `/ws/output/{tile_id}`。
+3. 上报 `hello`，注册为真实输出节点。
+4. 定时进行时钟同步。
+5. 定时上报 FPS、frame time、dropped frames。
+6. 收到场景命令后执行 prepare/barrier/commit。
+
+## 7. 场景切换流程
+
+控制台点击“切换”后：
+
+1. 后端生成新场景状态和 `command_id`。
+2. 后端广播 `prepare_scene`。
+3. left/right 真实输出端预加载或预渲染。
+4. left/right 都回 `prepared`。
+5. 后端记录 `released_at_ms` 并广播 `commit_scene`。
+6. left/right 等到 `apply_at_ms` 同步显示。
+7. left/right 回 `committed` 或 `late`。
+
+在控制台“命令回显”里可以看到每个阶段。
+
+## 8. 接入真实超分渲染
+
+输出端预留了 hook：
+
+```js
+window.ledPlatformPrepareScene = async ({ commandId, tile, state, scene }) => {
+  // 1. 根据 scene/state 准备真实资源
+  // 2. 执行超分或离屏渲染
+  // 3. 确认下一次 commit 可以无卡顿显示
+};
+```
+
+只要这个 Promise 不 resolve，输出端就不会发送 `prepared`。后端也就不会释放 `commit_scene`。
+
+如果超分失败，输出端会回：
+
+```text
+status=error
+```
+
+## 9. 配置文件
+
+场景配置：
+
+```text
+config/scenes.json
+```
+
+字段：
+
+```text
+id          场景 ID
+name        控制台显示名
+url         场景 URL，目前示例都使用 /wall-app
+view        输出端内部视图名
+description 描述
+preload     准备阶段预加载资源
+```
+
+Tile 配置：
+
+```text
+config/tiles.json
+```
+
+字段：
+
+```text
+id               left / right
+x, y             在完整逻辑大屏中的起点
+width, height    tile 尺寸
+wall_width       完整大屏宽度
+wall_height      完整大屏高度
+desktop_width    单台 GPU 服务器桌面宽度
+desktop_height   单台 GPU 服务器桌面高度
+physical_outputs 4 路 4K 输出映射
+```
+
+环境变量前缀：
+
+```text
+LED_
+```
+
+示例：
+
+```bash
+LED_APP_PORT=9000 .venv/bin/python -m led_platform.cli serve
+LED_SWITCH_PREPARE_DELAY_MS=3000 .venv/bin/python -m led_platform.cli serve
+```
+
+## 10. 验证命令
+
+```bash
+.venv/bin/python -m pytest -q
+.venv/bin/python -m compileall led_platform tests
+node --check led_platform/web/static/output/main.js
+node --check led_platform/web/static/admin/main.js
+```
+
+健康检查：
+
+```bash
+curl http://127.0.0.1:8000/healthz
+```
+
+同步状态：
+
+```bash
+curl http://127.0.0.1:8000/api/sync/status
+```
+
+## 11. 常见问题
+
+### 控制台看不到画面回显
+
+先强制刷新控制台页面。画面回显在控制台顶部，标题为“画面回显”。
+
+如果仍然看不到，检查：
+
+```text
+http://控制服务IP:8000/output/left?preview=1
+http://控制服务IP:8000/output/right?preview=1
+```
+
+这两个地址应能单独打开预览画面。
+
+### 命令回显一直显示等待
+
+检查真实输出端是否打开的是：
+
+```text
+/output/left
+/output/right
+```
+
+不要把生产输出端打开成 `?preview=1`，预览模式不会 ACK。
+
+### 切换场景不放行
+
+说明至少一个真实输出端没有回 `prepared`。查看：
+
+```text
+/api/sync/status
+```
+
+重点看 `nodes` 是否有 left/right，`commands[].acks` 是否有两个 tile。
+
+### 局域网机器打不开
+
+检查：
+
+- 服务是否监听 `0.0.0.0:8000`。
+- 控制服务机器防火墙是否允许 8000。
+- 输出服务器是否和控制服务在同一网络。
+- URL 是否使用控制服务的局域网 IP，而不是 `127.0.0.1`。
+
+### 控制台预览和生产输出不同步
+
+控制台预览是观察用途，运行在控制台浏览器中，不参与 ACK，也不代表生产输出端性能。最终验收应以真实 `/output/left` 和 `/output/right` 为准。