# 使用文档

## 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` 为准。