# Web Console

Web 控制台提供一句话、快捷功能模式与手势控制入口，不在浏览器中生成 CAN。所有动作统一提交给后端编排、配置校验、安全门禁和执行链路。

当前页面包括：

- 顶部“自编排 / 自标定 / 自扩展 / 自修复”模块切换；user 进入自标定或自修复时自动切换为 admin，自修复停留期间不能降级为 user；自扩展包含外设学习与统一控制两种工作模式。
- 六类外设玩具的添加、红外能力学习、测试发射、单动作执行与本地能力目录。
- 基于已学习外设能力和车端能力的 GPT 联动计划，车端步骤复用现有安全编排链路。
- 一句话联动座椅、空调、天幕和氛围灯，支持 Enter 执行和 GPT/本地规则切换。
- 观影、午休、零重力快捷模式，以及当前副驾驶姿态的命名保存入口。
- 六阶段执行链路、整车联合孪生、领域状态、配置、CAN 计划和执行结果。
- 右侧手势控制抽屉，包含摄像头画面、关键点骨架、保持进度、动作速查与自定义映射。

UI 只展示可审计的“决策摘要”和“处理轨迹”，不展示模型私有思维过程。

当前座椅阶段一控制台为无构建静态页面，由 `cognitive_agent.server` 同源提供 API 和资源。运行：

```bash
make dev
```

Android PAD/模拟器联调使用：

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\android_pad_dev.ps1
```

脚本会启动已配置的 Pixel Tablet AVD、建立 `adb reverse tcp:8000 tcp:8000`、
以真实硬件关闭/模拟台架开启的方式启动服务，并在 Android Chrome 中打开
`http://127.0.0.1:8000`。停止联调环境：

```powershell
powershell -ExecutionPolicy Bypass -File .\tools\android_pad_dev.ps1 -Stop
```

局域网演示使用：

```bash
make dev-lan
```

其他设备访问启动日志打印的 `http://<LAN-IP>:8000`。页面与后端 API 由同一服务提供，无需单独配置前端地址。

自扩展接口统一位于 `/api/extension/*`，GSCU1B 默认以 TCP 模式监听
`0.0.0.0:4444`。可通过 `GSCU_TRANSPORT=simulation` 使用演示学习器，或通过
`GSCU_TRANSPORT=mqtt` 与 `GSCU_MQTT_*` 配置接入 MQTT。MQTT 依赖可通过
项目的 `ir` 可选依赖安装。自扩展不再需要独立的 `8010` 前端服务。

## N7 自标定

自标定前端、原始 Android `n7_seat.glb`、四轴 Hall 标定协议以及
CAN/MQTT/RTSP 后端均由当前服务同源提供，不再启动原 `8766` 工作站或使用
iframe。左侧“执行目标”复用自编排下拉控件，默认显示“真实台架”，也可以
切换到“标定仿真台架”。选择目标后仍需显式点击连接，服务启动不会自动打开
真实 CAN 适配器。

标定 API 位于 `/api/calibration/*`，包含状态流、CAN 连接、四轴/单轴标定、
绝对位置、端点、全轴 STOP、MQTT、RTSP 和连接设置。仿真台架实现同一套
CRC、ACK、ARM、心跳租约和 STOP 协议边界，并生成双目位姿数据；它与自编排
的 `dry_run`、`simulated_hardware` 执行模式相互独立。真实 ZLG CAN 连接复用
仓库现有的 ZCANPRO 32 位 bridge，实机运动接口另外限制为台架本机访问。

MQTT 与通用 CAN 依赖可安装为：

```powershell
python -m pip install -e ".[can,ir]"
```

RTSP 画面需要将 `ffmpeg.exe` 加入 `PATH`；未安装 FFmpeg 时，CAN、MQTT、
标定和 3D 数字孪生不受影响。

## 座椅自修复

原 `manual_hil` 工程中的六项量产软件故障闭环、硬件支路诊断、72 针连接器
定义（其中 21 针启用）、ZCANPRO bridge 以及固件资格检查已迁入当前服务，
统一使用 `/api/self-repair/*`，不再启动独立前端或 HTTP 服务。自修复入口始终
显示；user 点击入口后自动切换为 admin，停留在自修复期间权限选择器锁定。
后端对所有自修复 API 再次执行 admin 校验，实物诊断、实物故障注入、归零、
STOP ALL、日志目录和固件操作还要求台架本机决策点。

软件自修复默认使用 `shadow`，仅推进内存中的故障注入、AI 诊断、恢复和复测
状态机，不会写入 ECU。页面左侧显示六项量产故障用例及总体进度，中间程序化
3D 座椅同步四轴与热管理状态，右侧五节点以深蓝、浅蓝、灰色分别表示已完成、
进行中和待执行。硬件视图提供 CAN 分层状态、功能支路、JA1/JB1/JC1 物理针脚
排布与证据详情。

所有机器相关路径均通过环境变量配置，完整清单及示例见
[`config/self-repair/README.md`](../../config/self-repair/README.md)。未配置固件、
IAR 或 ZCANPRO 路径时，对应实物操作保持禁用；服务导入与启动不会自动拉起
ZCANPRO。只有显式设置 `SELF_REPAIR_AUTO_START_BRIDGE=true`，或管理员启动
需要 bridge 的实物操作时，服务才会尝试运行配置的扩展脚本。

公网入口由后端统一认证，前端不保存密码或 API Key。未认证访问自动进入
`/login`，主控制台提供退出按钮。固定入口是
`https://511.kendeji.fun`，应用容器只监听服务器回环地址，再由 Caddy 提供
HTTPS。部署方式见
[`deploy/server/README.md`](../../deploy/server/README.md)。

页面支持 GPT/本地解析切换、六阶段流水线、主副驾热舒适、五轴位置状态和 3D 座椅孪生、GPT 结构化能力请求、决策与校验轨迹、FunctionConfig、CommandPlan、虚拟帧和 ExecutionReport。真实硬件执行由服务端门禁控制，不是仅靠前端按钮限制；Android 联调脚本会显式关闭真实硬件执行。

## 手势资源与安全规则

手势模型随当前工程交付，默认位置为：

```text
assets/gesture/gesture_recognizer.task
../../config/gesture/default.yaml
```

后端提供 `/api/gesture/runtime` 和 `/api/gesture/model`，前端以二进制缓冲区加载模型，避免依赖外部 `seat_gesture_control` 目录。MediaPipe Web、Lucide 和 Three.js 均按固定版本保存在 `vendor/`，运行时不访问外部 CDN；摄像头帧和手部关键点只在当前浏览器中处理。

## PAD、PWA 与离线行为

- 竖屏 PAD 在 900 CSS px 以下切换为上下布局，横屏保留指令栏与结果区；触控目标最小 48 dp，并处理安全区和动态视口。
- 顶部连接徽标由 `/api/health` 周期探测驱动；GET 可有限重试，POST 控制请求不自动重试。
- Service Worker 缓存页面壳、固定版本依赖和按需访问的 3D/手势资源；`/api/requests` 等控制 API 始终走网络且不会写入缓存。
- 从 Android Chrome 的“安装应用”可进入 standalone PWA；首次完整在线加载后可离线打开控制台壳，实际编排仍要求 Windows 服务可达。

模拟台架需要 `COGNITIVE_AGENT_SIMULATED_HARDWARE_ENABLED=true`。选择“模拟台架”后可注入反馈超时、适配器断开、电机堵转、固件不匹配和部分反馈。结果会标记 `simulation=true`、`seat_feedback=simulated_hardware` 和 `physical_can_opened=false`，不会调用真实 CAN、ZLG 或 IAR。

安全规则：张掌保持 1 秒激活；动作保持 600 ms 且至少连续 8 帧才执行；换动作不重新锁止；握拳立即停止但不解除激活；3 秒无有效动作自动锁止；单次连续运动最多 1.5 秒；检测到多只手时不执行。自定义映射保存在浏览器 `localStorage`。

摄像头仅能在安全来源使用：本机访问 `http://127.0.0.1:8000`，远程访问必须使用 HTTPS。关闭抽屉、页面隐藏或离开页面时会立即停止摄像头轨道。