feat(client): RMIC::2026 界面重做、可计算的版本机制与固件版本联动
- feat(client): 界面换成墨黑蓝底 + 单支红的矩形语言，切角全部去掉，仅装甲条保留平行四边形 - feat(client): 自托管 HarmonyOS Sans SC 与 JetBrains Mono，中文与拉丁数字逐字回退 - feat(client): 新增启动序列、首启门、用户端 HUD、裁判端控制台、设置抽屉与固件维护页 - feat(client): 裁判端中缝与下方控制台可拖，鼠标落在哪一路下方就看哪一路 - feat(client): 设置抽屉常驻实时预览，与画面共用同一份准星绘制代码 - feat(client): 动效改用 Material 3 的缓动曲线与时长，逐条替换掉自造的贝塞尔 - feat(version): 版本号与 CHANGELOG 由 scripts/version.mjs 从 git 历史算出，不再手写 - feat(firmware): Hello 报文携带语义化版本、构建号与自报协议号，负载向后兼容 - feat(client): 固件版本显示在绑定列表与裁判端每一格；协议不匹配时给出具体原因 - feat(firmware): 固件包版本与客户端同源，都从 version.json 读 - fix(client): getCurrentWindow() 在没有 Tauri 注入时同步抛异常，浏览器预览整棵树被卸载 - fix(client): 启动序列的淡出 effect 清掉了自己刚设的 setTimeout，界面永远停在启动页 - fix(client): 设置抽屉左侧导航的锚点没挂到 section 上，且用错了坐标系 - fix(protocol): Hello 改用宽松帧头解析，让协议不匹配的板子能被解释而不是静默消失 - fix(build): Windows 上 bindgen 加载不了 libclang 的同目录依赖，构建脚本补上搜索路径 - fix(build): esp-idf-sys 在长路径下拒绝构建，固件构建改用短的目标目录 - build(client): 队标图标，含光学尺寸分级与手工拼的多尺寸 ICO - build(ci): 守门 job 增加版本一致性检查，产物名改为 rmic-2026-* - docs: 补充界面语言、版本机制与协议通告布局的说明
This commit is contained in:
+176
-9
@@ -1,5 +1,6 @@
|
||||
# desktop
|
||||
# RMIC::2026
|
||||
|
||||
黑龙江大学 602 实验室 · Simba Robotics 的**视野链路终端**。
|
||||
桌面端。**两种身份，两套页面，一个进程。**
|
||||
|
||||
| 身份 | 画面 | 血量 | 装甲板 | 绑定 |
|
||||
@@ -10,16 +11,173 @@
|
||||
界面是 WebView 里的 React（画面画在 canvas 上），后端是 Rust。**它不是把旧客户端套进
|
||||
一个窗口**：网络、重组、发现、配置、密码、录制全部重写成了可单测的模块。
|
||||
|
||||
> **名字与数据目录**：显示名是 `RMIC::2026`；安装包与可执行文件叫 `RMIC-2026`（Windows
|
||||
> 文件名不允许 `:`）。配置、录制、日志仍落在旧的 `cam-desktop` 目录下——这是**故意的**，
|
||||
> 换名字不该顺手把现场的密码哈希与绑定丢掉。见「配置」一节。
|
||||
|
||||
```text
|
||||
desktop/
|
||||
core/ cam-core：不含任何界面与 Tauri 的东西（83 个测试）
|
||||
src-tauri/ Tauri 后端：推流、命令、录制（32 个测试）
|
||||
src/ React 前端：两套页面 + HUD
|
||||
src/lib/ IPC 封装、WebSocket 客户端、状态存储、格式化
|
||||
src/components/ 视频窗格、血条、胜负横幅、瞄准器、装甲板表、队名编辑、录制面板、设置抽屉
|
||||
src/pages/ 用户端 / 裁判端
|
||||
src/lib/ IPC 封装、WebSocket 客户端、状态存储、格式化、准星绘制、界面小节拍
|
||||
src/components/ 取景器、装甲条、命中、结算、装甲板表、队名、录制、设置抽屉、启动序列、门、提示
|
||||
src/pages/ 用户端 / 裁判端 / 固件维护 / 延迟校准
|
||||
src/styles/ tokens（令牌）、base（原子）、chrome（外壳）、stage（舞台）、console、settings、maintenance
|
||||
public/fonts/ 自托管的 HarmonyOS Sans SC 与 JetBrains Mono
|
||||
src-tauri/icons/ 队标（由 simba-robotics.com/logo.svg 生成，含光学尺寸分级）
|
||||
```
|
||||
|
||||
## 界面：一套终端语言
|
||||
|
||||
这一栏不是装饰说明，而是"改界面之前该知道的几件事"。
|
||||
|
||||
### 配色：墨黑蓝打底，只有一支红
|
||||
|
||||
| 角色 | 值 | 用在哪 |
|
||||
|---|---|---|
|
||||
| 底色 | `--void #05070d` → `--panel-3 #172032` | 全部面积。五级低饱和冷蓝黑，靠 1px 线分层，不靠阴影 |
|
||||
| 文字 | `--ink #e7ecf5` → `--ink-4 #3a4457` | 四档，第四档暗到不像真信息 |
|
||||
| **强调** | `--primary #e8232b` | **只有**：焦点、选中、录制中、错误、临界血量、结算 |
|
||||
| 状态 | `--error` / `--warn #f2b33d` / `--ok #3fc98a` | 各有语义，不与强调色混用 |
|
||||
| 队伍 | `--team-0 #ff6b5e` / `--team-1 #4a9bff` | **硬件约束**：装甲板 LED 就是红与蓝 |
|
||||
|
||||
一条硬规则：**红只给必须被看见的东西**。开关合上是白的、滑杆填充是钢灰、分段控件的选中
|
||||
记号是底沿一条 2px 线、分区编号是灰的、顶栏没有任何强调线。当红色出现时，它后面一定有一
|
||||
件真事——这就是"只高亮真正重要的信息"落到代码里的样子。
|
||||
|
||||
队红刻意做得比强调红更暖更浅，否则两条血并列时会被误读成"系统在报警"。
|
||||
|
||||
### 形状：矩形，唯一的斜边给装甲条
|
||||
|
||||
全局是矩形：没有圆角、没有切角、没有药丸、没有阴影卡片。**唯一的斜边是装甲条那排平行四边形**
|
||||
——它必须在一屏矩形里被一眼认成"这是血，不是别的东西"。别的元素一旦也开始斜切，那个形状
|
||||
就不再携带信息了。
|
||||
|
||||
### 动效：严格照 Material 3 的曲线与时长
|
||||
|
||||
`styles/tokens.css` 里直接写着 M3 的七条缓动与 short/medium/long 四组时长：
|
||||
|
||||
| 令牌 | 曲线 | 语义 |
|
||||
|---|---|---|
|
||||
| `--m3-emphasized` | `cubic-bezier(0.2, 0, 0, 1)` | 需要存在感的转场 |
|
||||
| `--m3-emphasized-decelerate` | `cubic-bezier(0.05, 0.7, 0.1, 1)` | **进入**（快起慢收） |
|
||||
| `--m3-emphasized-accelerate` | `cubic-bezier(0.3, 0, 0.8, 0.15)` | **退出**（慢起快走） |
|
||||
| `--m3-standard` / `-decelerate` / `-accelerate` | `(0.2,0,0,1)` / `(0,0,0,1)` / `(0.3,0,1,1)` | 常规位移 |
|
||||
| `--m3-linear` | `(0,0,1,1)` | 恒速（仅用于跟踪与循环） |
|
||||
|
||||
旧名 `--e-out` / `--e-in` / `--d-1..5` 保留为**指向 M3 的别名**，所以没有一条规则落在自造
|
||||
的贝塞尔上。两个例外是刻意的：`steps()` 用于录制红点与终端光标（离散闪烁），`linear` 用于
|
||||
"没信号"那圈恒速转动的虚线环——M3 的曲线描述的是有始有终的转场，不是无限循环。
|
||||
|
||||
### 动效：每一页只有一个签名动作
|
||||
|
||||
重复使用同一种效果会让界面显得机械，所以只共享底层曲线与时长，**每页各有一个属于自己的
|
||||
动作**：
|
||||
|
||||
| 界面 | 签名动作 | 它解决什么 |
|
||||
|---|---|---|
|
||||
| 启动序列 | 一行行亮起的自检 + 真实进度 | 让"还在等"与"卡住了"分得开 |
|
||||
| 首启门 | 两张模块卡，悬停浮起并露出角括号 | 说明这件选择是要"装"进这台机器的 |
|
||||
| 用户端 | 逐格熄灭的装甲条、四周泛红、六秒休眠 | 静止时屏幕上的东西越少越好 |
|
||||
| 裁判端 | 中缝可拖、鼠标停在哪一路下方就看哪一路 | 不用再开第三个页面去"看某一边" |
|
||||
| 设置 | 常驻实时预览 + 竖向分节导航 | 改准星/网格/装甲条时立刻看得见结果 |
|
||||
| 固件维护 | 步骤轨 + 环形进度 + 终端日志 | 烧录的哪一步、到哪儿了，一眼可读 |
|
||||
| 解锁 | 一次性的校验扫描 + 错误时的一次抖动 | 明确"现在这一步是在验证身份" |
|
||||
|
||||
`prefers-reduced-motion` 会把这些时长压到 0，不是关掉功能。
|
||||
|
||||
### 字体：中文一套、拉丁一套，逐字回退
|
||||
|
||||
| | 字体 | 承担什么 |
|
||||
|---|---|---|
|
||||
| 中文 | **HarmonyOS Sans SC**（400 / 500 / 700） | 叙述、标签、按钮文字。字面方正，11px 仍然立得住 |
|
||||
| 拉丁与数字 | **JetBrains Mono**（400 / 500 / 700） | 全部读数：帧率、血量、地址、倍率、时间码。等宽，列里的数字跳动时不左右抖 |
|
||||
|
||||
两者都以 woff2 自托管在 `public/fonts/`，随 `frontendDist` 进安装包，**运行时不碰网络**
|
||||
（CSP 里 `default-src 'self'` 也不允许）。中文由 `cn-font-split` 切成 82 个 unicode-range
|
||||
分片 × 3 个字重，浏览器只下载页面真正用到的那几十个，而不是一上来吞 14 MB。
|
||||
|
||||
合到一句话里靠**逐字回退**，不做语言判断：`--font-ui` 把 JetBrains Mono 写在前面，它里面
|
||||
没有汉字，浏览器就逐字往下找，落到 HarmonyOS。于是"血量 87"里数字是等宽的、汉字是
|
||||
HarmonyOS 的，一条 `font-family` 同时满足两个要求。
|
||||
|
||||
启动序列会等 `document.fonts.ready`：先画成系统黑体、两百毫秒后再跳成 HarmonyOS，会让整块
|
||||
布局重排一次——那一个抖动比多等一瞬难看得多。
|
||||
|
||||
### 队标
|
||||
|
||||
应用图标与启动页的标记是队标（`https://simba-robotics.com/logo.svg`），由它生成整套
|
||||
`src-tauri/icons/`。原图是 1024×1024 的画布、标志只占中间一条，所以脚本把 viewBox 收到本体
|
||||
上再居中；**小尺寸用更大的缩放比**（光学尺寸：256px 以上 82%、64–128px 88%、48px 以下 97%），
|
||||
否则 16/24/32 上那些 1px 笔画会糊成一团。`icon.ico` 是手工拼的多尺寸容器——Pillow 的写入器
|
||||
只能从一张主图缩出所有档位，而 Windows 任务栏恰恰只取最小的那几档。
|
||||
|
||||
笔画在 17px 以下就只剩 1px，所以顶栏只放字标 `RMIC::2026`（`::` 是界面里唯一被染红的两个
|
||||
字符），完整队标留给启动页的 30px。
|
||||
|
||||
### 每页最顺手的那个操作
|
||||
|
||||
- **用户端不用点。** 操作手的手在遥控器上，所以这一页的交互全部收在画面上一个手势里：
|
||||
滚轮缩放、拖动平移、双击复位。没有任何"瞄准再点"的按钮。六秒没有输入也没有挨打时，角上
|
||||
的标签与代号自己淡下去；一有动静整块醒来。
|
||||
- **裁判端让控制台跟着鼠标走。** 按下左格，下方列表就只显示那一边的装甲板（再按一次回到
|
||||
全部，键盘 `1` / `2` / `0` 同样）。中间那条竖线可以拖——哪一路更重要就把它拉宽，双击回到
|
||||
五五开。画面与下方控制台之间的横线也能拖：看回放的时候把播放器拉大。
|
||||
- **设置是一块带预览的控制台。** 左侧竖向导航，右侧常驻一块实时预览；预览用的是画面里
|
||||
**同一个**绘制函数（`lib/reticle.ts`），所以"预览里对、画面上偏"这种最坏情况不可能发生。
|
||||
预览旁边那根血量滑杆是刻意加的：低血阈值与脉动只有真的把血拖下去才看得见。
|
||||
|
||||
## 版本与改动日志：算出来的，不是写出来的
|
||||
|
||||
版本号和改动日志都从 **git 历史**算，不靠人记着去改。
|
||||
|
||||
```sh
|
||||
node scripts/version.mjs --write # 计算并写回所有派生文件
|
||||
node scripts/version.mjs --check # 只校验：有未归档的提交就退 1（CI 里跑这个）
|
||||
node scripts/version.mjs --print # 把算出来的版本打到 stdout
|
||||
```
|
||||
|
||||
### 规则
|
||||
|
||||
提交标题用 Conventional Commits（`type(scope): 说明`）：
|
||||
|
||||
| 这批提交里有 | 升哪一位 |
|
||||
|---|---|
|
||||
| `BREAKING CHANGE:` 或 `type!:` | major |
|
||||
| `feat` | minor |
|
||||
| `fix` / `perf` | patch |
|
||||
| 其它 | 不动版本，只加构建号 |
|
||||
|
||||
构建号是 `git rev-list --count HEAD`：单调递增、不会撞车、不用手工维护。正文里以 `- `
|
||||
开头且本身写成 `type(scope): 说明` 的行算**额外条目**——这样一次 squash 提交也能把几件事
|
||||
分别归类，不必为了日志好看去拆提交。
|
||||
|
||||
### 派生出来的东西
|
||||
|
||||
| 文件 | 谁用 |
|
||||
|---|---|
|
||||
| `version.json`（仓库根） | 固件 `build.rs` 读它，编译期注入 `RMIC_VERSION*` |
|
||||
| `CHANGELOG.md` / `CHANGELOG.json` | 人读的那份与机器读的那份，同一次计算产出 |
|
||||
| `desktop/src/lib/version.ts` | 界面上的版本标签与协议号 |
|
||||
| `desktop/package.json`、`tauri.conf.json` 的 `version` | 装包文件名与 Windows 的「应用和功能」 |
|
||||
|
||||
建这套机制之前的人工整理记录保存在 [`docs/CHANGELOG-legacy.md`](../docs/CHANGELOG-legacy.md)。
|
||||
|
||||
### 固件与客户端怎么对上
|
||||
|
||||
同一条链贯穿到底：`git → version.json → 固件二进制 → Hello 报文 → 客户端界面`。
|
||||
|
||||
板子每 2 秒广播的 `Hello` 里带着**语义化版本、构建号、以及它编译进去的线路协议号**
|
||||
（布局见 `protocol/README.md`）。客户端读出来之后：
|
||||
|
||||
- 设置面板的绑定下拉里显示 `固件 v0.2.0 · 34`；
|
||||
- 裁判端每一格下方显示这块板子的固件版本；
|
||||
- 协议对不上时，用户端画面正中给出**具体原因**（"它是协议 2，本客户端是协议 1"），
|
||||
而不是只表现为没有画面——它的视频帧会被严格解析丢弃，但那句解释正是靠通告读出来的。
|
||||
|
||||
**为什么值得占这 10 个字节**：一块烧错固件的板子，原来只表现为"没画面"，现场会去查网线、
|
||||
AP、供电。现在同一个现象会直接指向"重新烧固件"。
|
||||
## 快速开始
|
||||
|
||||
```sh
|
||||
@@ -50,7 +208,7 @@ pnpm tauri build --target x86_64-pc-windows-msvc --bundles nsis --ci -- --locked
|
||||
|
||||
`--target` 覆盖本目录原来的 macOS target，`--bundles nsis` 选择 Windows 安装包；末尾的 Cargo 参数清空从根固件项目继承的 `build-std`。
|
||||
|
||||
- 程序：`src-tauri/target/x86_64-pc-windows-msvc/release/cam-desktop.exe`。
|
||||
- 程序：`src-tauri/target/x86_64-pc-windows-msvc/release/RMIC-2026.exe`（名字由 `tauri.conf.json` 的 `productName` 决定；直接 `cargo build` 出来的原始产物仍叫 `cam-desktop.exe`，那是内部构建物，不是交付物）。
|
||||
- 安装包：同一 release 目录下的 `bundle/nsis/*-setup.exe`。
|
||||
- 核心测试：进入 `core/` 后运行 `cargo +stable test --locked --target x86_64-pc-windows-msvc --config 'unstable.build-std=[]'`。
|
||||
|
||||
@@ -282,8 +440,13 @@ IP，藏起来毫无意义；数据也可能已经收下并解码了，`.slint`/
|
||||
已知精度上限：两次读数之间发生两次伤害时只能看到净差。心跳 200 ms，所以这段窗口里的两次
|
||||
打击会被合并成一次——对"闪一下红"足够，对判定不够，判定看的是界面上的绝对血量。
|
||||
|
||||
反馈有**两样**：整屏闪红、准星旁的伤害数字。**大号数字不放在画面正中**——第一版放了，
|
||||
结果它正好压在瞄准点上，而被打中的那一下恰恰是最需要看着准星的时候。
|
||||
反馈有**两样**：画面四周泛红（颜色只从四条边渗进来，中间保持原样）、准星旁的伤害数字。
|
||||
**大号数字不放在画面正中**——第一版放了，结果它正好压在瞄准点上，而被打中的那一下恰恰是最
|
||||
需要看着准星的时候。
|
||||
|
||||
**它不给方向。** 命中事件里的 `index` 是哪一条上报先发现了掉血，不是"从哪一侧打来的"（主板
|
||||
一次广播四条、血值相同，谁先到达取决于 UDP）。把它画成方向箭头会是一条看起来很专业、实际上
|
||||
完全错误的线索，比不画糟得多。
|
||||
|
||||
**没有"画面抖动"了。** 原来有第三样：被打中时整幅图（连瞄准器一起）晃一下。它去掉了，
|
||||
理由有两条：
|
||||
@@ -369,7 +532,7 @@ AP、板子，而不是二十行分配代码。现在它有一个直接对着这
|
||||
|
||||
## 配置
|
||||
|
||||
`~/.config/cam-desktop/config.toml`，`--config` 可改。
|
||||
`~/.config/cam-desktop/config.toml`，`--config` 可改。**目录名沿用旧的 `cam-desktop`**：改名不该顺手把现场的密码哈希与绑定丢掉。要干净重来就删掉这个目录。
|
||||
|
||||
```toml
|
||||
role = "team"
|
||||
@@ -423,8 +586,12 @@ Tauri 的界面跑在 WKWebView 里，改一行 CSS 要走一次 cargo 构建。
|
||||
```sh
|
||||
pnpm dev # 用户端
|
||||
open 'http://127.0.0.1:1420/?preview=referee' # 裁判端（密码 1234）
|
||||
open 'http://127.0.0.1:1420/?preview=first-run' # 首启的身份选择
|
||||
open 'http://127.0.0.1:1420/?preview=password' # 首启的设密码
|
||||
```
|
||||
|
||||
后两个参数只是让对应的门禁强制显示出来，不用为了看一眼就去删配置文件。
|
||||
|
||||
两重门保证它进不了正式构建：`import.meta.env.DEV` 为真**且**没有 `__TAURI_INTERNALS__`，
|
||||
并且调用点是 `await import(...)`——条件为假时整个模块不会被打进产物。
|
||||
|
||||
@@ -492,7 +659,7 @@ RUST_LOG=debug ./target/aarch64-apple-darwin/debug/cam-desktop | grep 'stream:'
|
||||
需要测量相机到客户端的整条链路时，使用裁判配置启动校准模式：
|
||||
|
||||
```powershell
|
||||
.\cam-desktop.exe --config .\referee.toml --latency-report .\latency-run.ndjson
|
||||
.\RMIC-2026.exe --config .\referee.toml --latency-report .\latency-run.ndjson
|
||||
```
|
||||
|
||||
报告路径必须是新文件。让相机完整拍到左侧四个彩色角块，避开右侧回显，固定相机和窗口位置。标记每 50 ms 更新；程序沿正常接收、解码和 `VideoSurface` 绘制路径记录每个标记的首次有效回显，拒绝曝光混合而无法可靠解码的帧。NDJSON 包含相邻 rAF 夹定的时间、解码完成到画布绘制时间和标记分析耗时，不保存图像或配置。面板扫描和像素响应未测量，精确物理光学延迟需用高速相机复核。正常启动不运行标记识别；校准模式不会额外订阅一份 UDP 视频。
|
||||
|
||||
Reference in New Issue
Block a user