ci: npm 装 pnpm 前先清掉残留影子文件（EEXIST），并去掉 npm 不认的 store-dir

ci: Windows 改用 npm 装的 JS 版 pnpm（standalone 二进制在低完整性沙箱里必崩）
ci: Windows 的 pnpm install 加 corepack 退路（standalone 在低完整性沙箱里栈溢出）
2026-10-15 23:29:39 +08:00 · 2026-10-15 23:27:06 +08:00 · 2026-10-15 23:24:13 +08:00 · 2026-10-15 23:21:16 +08:00 · 2026-10-15 23:18:53 +08:00 · 2026-10-15 23:15:36 +08:00
121 changed files with 25630 additions and 5720 deletions
@@ -5,7 +5,26 @@ WIFI_SSID=your-ssid
 WIFI_PASS=your-password
 # Optional
 # Armor plates (armor/). Which team this board belongs to: 0 = team one (red),
 # 1 = team two (blue). Decides the LED colour and the `team` field in the health
 # reports, so it is baked in at build time - reflash to switch teams.
 #ARMOR_TEAM=0
 # Armor plates: raw 12-bit ADC level above which a piezo sample counts as a hit
 # (default 2000, same as the reference firmware). Calibrate from the `peak[...]`
 # field in the serial status line: idle noise well below, a real tap well above.
 #ARMOR_THRESHOLD=2000
 # Capture resolution: qqvga | qvga | cif | hvga | vga | svga | xga | sxga | uxga
 #CAM_RES=vga
 # JPEG quality 0-63, lower is better quality
 #CAM_QUALITY=12
 # Set to 0 if your board inverts VSYNC in hardware.
 #CAM_VSYNC_INVERT=1
 # Pin the authentication mode instead of trusting the scan: none | wep | wpa |
 # wpa2 | wpawpa2 | wpa3 | wpa2wpa3 | wapi. Only needed when the scan cannot see
 # the AP (a hidden SSID, for instance) - otherwise the scan reports the real
 # mode and this only makes it fail faster.
 #WIFI_AUTH=wpa2
@@ -0,0 +1,16 @@
 # actionlint 配置。
 #
 # 这个仓库的 CI 跑在 Gitea 上，但 actionlint 用的是 GitHub 的规则，所以有一条
 # 政策性的误报要忽略掉：
 #
 #   the runner of "actions/upload-artifact@v3" action is too old to run on GitHub Actions
 #
 # 它对 GitHub 是成立的（v3 声明的 node16 运行时 GitHub 已经不再执行），但我们是
 # Gitea：Gitea 的 runner 用自己的 node 跑 JS action，v3 能正常把产物传上去；反过来
 # v4 在 Gitea 上**根本跑不了** —— v4 里的 @actions/artifact 会拒绝非 github.com
 # 的服务器（GHESNotSupportedError，原文见 .github/workflows/build-client.yml 文件头
 # 第 3 条，那是 2026-10-15 第一次真实运行的日志里抄下来的）。
 paths:
  .github/workflows/*.yml:
    ignore:
      - 'the runner of "actions/upload-artifact@v3" action is too old to run on GitHub Actions'
@@ -0,0 +1,547 @@
 # 构建桌面客户端（desktop/，Tauri v2 + React）。
 #
 # 产物都挂在这次运行下面（Actions 页面直接下载），保留 14 天：
 #   Linux x64     deb + AppImage   cam-desktop_<版本>_amd64.deb / .AppImage   ← 默认每次编
 #   Windows x64   NSIS 安装包      cam-desktop_<版本>_x64-setup.exe           ← 默认每次编
 #   macOS 通用    .app + .dmg      arm64 与 x86_64 合成一个包                ← 还没有机器，手动勾选才编
 #
 # ── 触发 ─────────────────────────────────────────────────────────────────────
 #   * push 到 main/master —— 只认 desktop/、protocol/ 与本文件的改动，改固件不会
 #     白占 runner
 #   * 打 v* tag、开 PR
 #   * 手动 Run workflow：逐个平台勾选，不进 paths 过滤（"就想编一次"走它）
 # 平台开关一律看勾选框（理由见下面第 4 条）。
 #
 # ── 跑在 Gitea 上要先对上的两件事 ────────────────────────────────────────────
 # 1. runner 标签是注册 runner 时自己起的名字，猜不到，所以三个 job 都写成
 #    "仓库变量优先、常见标签兜底"：
 #        runs-on: ${{ vars.RUNNER_LINUX || 'ubuntu-latest' }}
 #    标签对不上时 job 是**排队**而不是报错 —— 排队会一直占着这次运行不结束，
 #    所以上线新平台前先看一眼 runner 页面上那几行标签。
 #
 #    2026-10-15 实测在线的（括号里是它们自己声明的标签）：
 #      * simba-runner-01    （ubuntu-latest / ubuntu-24.04 / ubuntu-22.04）
 #      * windows-runner-01  （windows-latest / windows-2025 / windows-2022）
 #      * macOS：还没有
 #    所以 Windows 默认就跑；macOS 的 job 写成"手动勾选才跑"。
 #
 #    为什么不能拿 Linux runner 交叉编出来：
 #      * Windows：Rust 侧用 mingw 交叉编还能出个裸 exe，但 tauri 的 NSIS 打包器
 #        本身只能在 Windows 上跑，出不了安装包；
 #      * macOS：要 Apple SDK 与 codesign/lipo，只能在 macOS 上编。
 #    Windows runner 上要预装好 MSVC Build Tools（link.exe）、WebView2 运行时与
 #    rustup（dtolnay/rust-toolchain 靠它装工具链）；macOS 上要 Xcode Command Line
 #    Tools + rustup。Linux 的 job 通常跑在容器里，没装 rustup 也没关系 —— 见兜底那步。
 # 2. 这个文件放在 .github/workflows/ 下就够：Gitea 的 [actions] WORKFLOW_DIRS
 #    默认值就是 [".gitea/workflows", ".github/workflows"]（源码里的默认值，且
 #    .yml 与 .yaml 都认），所以两个目录都是原生支持的，不用挪。
 # 3. 两处"GitHub 能跑、Gitea 上不行"的地方，都是 2026-10-15 第一次真实运行的
 #    日志里钉出来的：
 #    * 传产物用 upload-artifact@v3，**不能用 v4**。v4 里的 @actions/artifact 会
 #      拒绝非 github.com 的服务器，日志原文：
 #        GHESNotSupportedError: @actions/artifact v2.0.0+, upload-artifact@v4+
 #        and download-artifact@v4+ are not currently supported on GHES
 #      Gitea 实现的是 v3 那套接口（ACTIONS_RUNTIME_URL），所以 v3 能传上去。
 #    * 一个缓存都没开。这台实例的缓存服务在 job 容器里连不上，日志原文：
 #        Failed to restore: getCacheEntry failed: connect ETIMEDOUT 172.18.0.2:37315
 #      setup-node 的 cache 每次要干等 4 分 39 秒才放弃（两个 job 各一次）。
 #      等缓存能从容器访问到了再加回来，写法就是：
 #        setup-node 的 with 里加：cache: pnpm / cache-dependency-path: desktop/pnpm-lock.yaml
 #        各 job 里加：
 #          - uses: actions/cache@v4
 #            with:
 #              path: |
 #                ~/.cargo/registry/index
 #                ~/.cargo/registry/cache
 #                ~/.cargo/git/db
 #              key: ${{ runner.os }}-cargo-registry-${{ hashFiles('protocol/Cargo.lock', 'desktop/core/Cargo.lock', 'desktop/src-tauri/Cargo.lock') }}
 #              restore-keys: ${{ runner.os }}-cargo-registry-
 # 4. 平台开关只用 github.event.inputs，**不用仓库变量**。2026-10-15 那次 Windows#    runner 明明在线、job 也确实派给了它（它自己的日志里写着
 #    "Runner labels: windows-latest, windows-2025, windows-2022"），产物却一直是
 #    skipped —— 卡在 job 级 if 的 `vars.ENABLE_WINDOWS == 'true'` 上：Gitea 的
 #    runner 在 job 级 if 里拿不到（或拿不对）vars 上下文，而这个条件写反的代价是
 #    "静悄悄不编"，最难发现。同一份文件里 `github.event.inputs.linux != 'false'`
 #    这个形式在 runner 日志里能看到正常求值（evaluating expression '...' evaluated
 #    to 'true'），所以平台开关统一成这种：
 #      * Linux / Windows：`github.event.inputs.<平台> != 'false'` → 默认跑，
 #        手动触发时取消勾选就不跑
 #      * macOS：`github.event.inputs.macos == 'true'` → 默认不跑，等有机器了改成
 #        上一种形式即可
 #    runs-on 里的 vars（RUNNER_*）不受影响，标签不匹配时用那个覆盖。
 # 5. Windows runner 的 job 跑在**低完整性**上（实测 Mandatory Label\Low Mandatory
 #    Level, S-1-16-4096），而 Windows 不允许低完整性往中完整性写：用户目录
 #    （~/.rustup、~/.cargo、%TEMP%、%LOCALAPPDATA%）统统 Access denied (os error 5)
 #    —— ACL 是干净的（SYSTEM / Administrators / 本人 全 F，没有任何 Deny），拦它的是
 #    完整性级别，所以"放宽权限"一点用都没有。表现是一串看着毫不相干的错误：
 #      * Git Bash 的 mktemp 写 /tmp 被拒（它的 /tmp 跟着 TEMP 走；TEMP 不可写时退回
 #        <Git 安装目录>\tmp，那个目录普通权限进不去）；
 #      * rustup: could not create temp file C:\Users\admin\.rustup\tmp\xxx_file
 #    处置：Windows job 把能重定向的都指到 runner 自己的工作目录
 #    （C:\Users\admin\runner\windows\cache，job 内写探测实测可写）——
 #    RUSTUP_HOME / CARGO_HOME / npm_config_cache / npm_config_store_dir /
 #    RUNNER_TOOL_CACHE / LOCALAPPDATA / APPDATA，加上 TEMP/TMP/TMPDIR、
 #    pnpm/action-setup 的 dest，以及 **USERPROFILE**。
 #    最后这个是被 pnpm 逼出来的：它的 store 操作锁不在 store-dir 下面，也不看
 #    LOCALAPPDATA，而是按 <USERPROFILE>\AppData\Local\pnpm-store-operation-locks
 #    算 —— 只把 LOCALAPPDATA 指走它照样去开原来的路径（报错原文见 run 8 的日志），
 #    把 USERPROFILE 指走它才跟着走（本机实测：探针 profile 下立刻出现
 #    all-stores.lock）。
 #    想从根上解决：让 gitea-runner 以**中完整性**启动（在普通终端里跑
 #    run-runner.ps1，而不是从被沙箱化的低完整性 shell 里拉起来），那样这些重定向
 #    就都可以撤掉。这台机器上 runner 由计划任务 GiteaRunner-Windows（admin /
 #    Limited）拉起，但进程链上的完整性已经落到了 Low。
 #
 # ── 三个平台都显式写 --target，这不是啰嗦 ────────────────────────────────────
 # desktop/.cargo/config.toml 里钉着 `target = "aarch64-apple-darwin"`（本机开发用；
 # 它存在的理由是 desktop/ 嵌在固件目录树里，不然会继承根目录那份
 # xtensa-esp32s3-espidf 的交叉编译配置）。CI 上不覆盖它，Linux 与 Windows 的 runner
 # 会去编 macOS 的目标，然后在依赖深处以 libc 找不到 MAP_FAILED 这类形式失败。
 # 所以每个 job 都把真正的目标交两遍：CARGO_BUILD_TARGET 给裸 cargo（测试）用，
 # --target 给 tauri build 用（打包路径也跟着它走）。
 #
 # ── 还有一条：仓库根目录的 rust-toolchain.toml 钉的是 `esp` ─────────────────
 # 那是给 ESP32 固件的定制工具链，CI 上没有、也不打算装（espup 要下几百 MB）。
 # rustup 是按**当前目录**往上找 rust-toolchain.toml 的：
 #   * desktop/** 有自己的 rust-toolchain.toml（stable），所以那里的 cargo 直接可用；
 #   * protocol/ 没有，会一路找到根目录那个 esp —— 所以那条测试写成 `cargo +stable`，
 #     显式越过它。
 # 任何在仓库根目录直接跑 cargo 的步骤都会去要 esp 工具链，别加。
 #
 # ── 没做的事 ────────────────────────────────────────────────────────────────
 # 不签名、不公证：Windows 的 exe 与 macOS 的 app 在别人机器上会被 SmartScreen /
 # Gatekeeper 拦一次（右键打开即可）。要做的话给 macOS 那几个 job 加
 # APPLE_CERTIFICATE / APPLE_SIGNING_IDENTITY / APPLE_ID / APPLE_PASSWORD /
 # APPLE_TEAM_ID（tauri 认这些环境变量，构建步骤不用改）。也没有自动发 Release：
 # 要发的话在最后加一个下载全部 artifact 再创建 release 的 job。
 name: 构建客户端
 on:
  push:
    branches: [main, master]
    tags: ["v*"]
    # GitHub 语义下 tag 推送不受 paths 过滤影响；如果你们的 Gitea 版本把 tag 也
    # 一起过滤掉了（打 tag 不触发），把这三行 paths 删掉即可。
    paths:
      - "desktop/**"
      - "protocol/**"
      - ".github/workflows/build-client.yml"
  pull_request:
    paths:
      - "desktop/**"
      - "protocol/**"
      - ".github/workflows/build-client.yml"
  workflow_dispatch:
    inputs:
      # Linux 与 Windows 的 runner 都在线，默认勾上；macOS 还没有机器，默认不勾
      # （勾了会一直排队）。开关为什么不用仓库变量见文件头第 4 条。
      linux:
        description: "构建 Linux（deb + AppImage）"
        type: boolean
        default: true
      windows:
        description: "构建 Windows（NSIS 安装包）"
        type: boolean
        default: true
      macos:
        description: "构建 macOS（通用 dmg）——还没有 macOS runner，勾了会排队"
        type: boolean
        default: false
 # 同一分支连推两次时把上一次没跑完的取消掉：自建 runner 数量有限，让过期的构建
 # 占着机器没有意义。老版本 runner 忽略这个键，不影响构建。
 concurrency:
  group: build-client-${{ github.ref }}
  cancel-in-progress: true
 env:
  # 与本机开发对齐：node 24 / pnpm 12（pnpm-lock.yaml 就是 pnpm 12.8.1 写的，
  # lockfileVersion 9.0）。改这两个数之前先确认 lock 文件还认。
  NODE_VERSION: "24"
  PNPM_VERSION: "12"
  CARGO_TERM_COLOR: always
  RUST_BACKTRACE: "1"
 jobs:
  # ───────────────────────────────────────────────────────────────────────────
  # 守门：类型检查、前端构建、两个不依赖窗口的 crate 的单元测试。
  # 下面每个构建 job 都 needs 它 —— 编到一半才发现 tsc 报错，是最浪费 runner 的
  # 一种失败。src-tauri 的 30 个测试放在 Linux 那个 job 里跑（它本来就要装
  # webkit 依赖，而且那几条录制测试要真的起 ffmpeg）。
  # ───────────────────────────────────────────────────────────────────────────
  checks:
    name: 检查（类型 + 单元测试）
    runs-on: ${{ vars.RUNNER_LINUX || 'ubuntu-latest' }}
    timeout-minutes: 45
    steps:
      - uses: actions/checkout@v4
      # runner 镜像里多半没有 rustup，而 dtolnay/rust-toolchain 靠它装工具链。
      # 这里只装一个最小的 rustup 本身，工具链交给下面那个 action —— 这样自建
      # 镜像不用为了 CI 专门烤一个带 Rust 的镜像。
      # 国内网络慢的话，在 runner 的环境变量里给 RUSTUP_DIST_SERVER 指一个镜像
      # （如 https://mirrors.ustc.edu.cn/rust-static）会快很多。
      - name: 确保有 rustup
        run: |
          if command -v rustup >/dev/null 2>&1; then
            rustup --version
            exit 0
          fi
          if command -v curl >/dev/null 2>&1; then
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
              | sh -s -- -y --profile minimal --default-toolchain none
          elif command -v wget >/dev/null 2>&1; then
            wget -qO- https://sh.rustup.rs \
              | sh -s -- -y --profile minimal --default-toolchain none
          else
            echo "装 rustup 需要 curl 或 wget，这个镜像里两个都没有" >&2
            exit 1
          fi
          if [ -n "$GITHUB_PATH" ]; then
            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
          fi
      # pnpm 装在 setup-node 之前：这一步只靠 runner 镜像里自带的 node（实测
      # /opt/hostedtoolcache 里有 24.x），而下面的 pnpm install 要用它。
      - name: 装 pnpm
        uses: pnpm/action-setup@v4
        with:
          version: ${{ env.PNPM_VERSION }}
      - name: 装 Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: 前端依赖（严格按 lock 装）
        working-directory: desktop
        run: pnpm install --frozen-lockfile
      - name: 类型检查（tsc --noEmit）
        working-directory: desktop
        run: pnpm run check
      - name: 前端构建（vite）
        working-directory: desktop
        run: pnpm build
      - name: 装 Rust（stable）
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: x86_64-unknown-linux-gnu
      # protocol 没有自己的 rust-toolchain.toml，会被根目录那个 `esp` 接住，
      # 所以这里必须 +stable 显式指定。
      - name: protocol 单元测试（15）
        working-directory: protocol
        run: cargo +stable test --locked --target x86_64-unknown-linux-gnu
      # core 在 desktop/ 下面，desktop/rust-toolchain.toml 已经是 stable，不用 +stable。
      - name: cam-core 单元测试（80）
        working-directory: desktop/core
        run: cargo test --locked --target x86_64-unknown-linux-gnu
  # ───────────────────────────────────────────────────────────────────────────
  # Linux x64：deb + AppImage
  # ───────────────────────────────────────────────────────────────────────────
  linux:
    name: Linux x64（deb + AppImage）
    needs: checks
    if: ${{ github.event.inputs.linux != 'false' }}
    runs-on: ${{ vars.RUNNER_LINUX || 'ubuntu-latest' }}
    timeout-minutes: 120
    env:
      TARGET: x86_64-unknown-linux-gnu
      CARGO_BUILD_TARGET: x86_64-unknown-linux-gnu
    steps:
      - uses: actions/checkout@v4
      - name: 确保有 rustup
        run: |
          if command -v rustup >/dev/null 2>&1; then
            rustup --version
            exit 0
          fi
          if command -v curl >/dev/null 2>&1; then
            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
              | sh -s -- -y --profile minimal --default-toolchain none
          elif command -v wget >/dev/null 2>&1; then
            wget -qO- https://sh.rustup.rs \
              | sh -s -- -y --profile minimal --default-toolchain none
          else
            echo "装 rustup 需要 curl 或 wget，这个镜像里两个都没有" >&2
            exit 1
          fi
          if [ -n "$GITHUB_PATH" ]; then
            echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
          fi
      - name: 装系统依赖
        run: |
          # 容器里跑的 runner 通常是 root，没有 sudo；托管 runner 上有。
          SUDO=""
          [ "$(id -u)" -eq 0 ] || SUDO=sudo
          $SUDO apt-get update
          $SUDO apt-get install -y --no-install-recommends \
            libwebkit2gtk-4.1-dev \
            libayatana-appindicator3-dev \
            librsvg2-dev \
            patchelf \
            libxdo-dev \
            libssl-dev \
            xdg-utils \
            build-essential curl wget file \
            ffmpeg
          # AppImage 打包要运行 linuxdeploy（它本身是个 AppImage）；24.04 起包名带 t64。
          $SUDO apt-get install -y libfuse2 || $SUDO apt-get install -y libfuse2t64 || true
      - name: 装 Rust（stable）
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: x86_64-unknown-linux-gnu
      - name: 装 pnpm
        uses: pnpm/action-setup@v4
        with:
          version: ${{ env.PNPM_VERSION }}
      - name: 装 Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: 前端依赖（严格按 lock 装）
        working-directory: desktop
        run: pnpm install --frozen-lockfile
      # 上面 apt 装了 ffmpeg，所以 recording.rs 里那几条"真的起 ffmpeg 并读回帧数"
      # 的测试不会走 has_ffmpeg() 的跳过分支，是真的在验。
      # 如果这台 runner 上它们长期不稳定，删掉这一步即可 —— 它们不在守门 job 里，
      # 不影响另外两个平台的产物。
      - name: Tauri 后端单元测试（30）
        working-directory: desktop/src-tauri
        run: cargo test --locked --target ${{ env.TARGET }}
      # beforeBuildCommand（pnpm build）由 tauri 自己跑，这里不用再 build 一次。
      - name: 打包（tauri build）
        working-directory: desktop
        run: pnpm tauri build --target ${{ env.TARGET }} --bundles deb,appimage
      - name: 上传产物
        uses: actions/upload-artifact@v3
        with:
          name: cam-desktop-linux-x64
          # 一个都没找到就报错：产物路径写错却"构建成功"是最难发现的一种失败。
          if-no-files-found: error
          retention-days: 14
          path: |
            desktop/src-tauri/target/${{ env.TARGET }}/release/bundle/deb/*.deb
            desktop/src-tauri/target/${{ env.TARGET }}/release/bundle/appimage/*.AppImage
  # ───────────────────────────────────────────────────────────────────────────
  # Windows x64：NSIS 安装包
  # ───────────────────────────────────────────────────────────────────────────
  windows:
    name: Windows x64（NSIS 安装包）
    needs: checks
    # 默认就跑：windows-runner-01 在线（自报标签 windows-latest）。
    # 开关用 inputs 而不是仓库变量的原因见文件头第 4 条 —— 这个坑正是它踩出来的。
    if: ${{ github.event.inputs.windows != 'false' }}
    # 这台机器上要预装：MSVC Build Tools（tauri 的 Rust 侧要 link.exe）、WebView2
    # 运行时（装了包的应用要它才能起窗口；打包本身不需要）与 rustup。
    runs-on: ${{ vars.RUNNER_WINDOWS || 'windows-latest' }}
    timeout-minutes: 120
    env:
      TARGET: x86_64-pc-windows-msvc
      CARGO_BUILD_TARGET: x86_64-pc-windows-msvc
      # 见文件头第 5 条：这台 runner 的 job 跑在**低完整性**（Low Mandatory Level,
      # S-1-16-4096）上，而 Windows 不允许低完整性往中完整性写 —— 用户目录全中招：
      # ~/.rustup、~/.cargo、%TEMP%、%LOCALAPPDATA% 下新建任何东西都是
      # "Access denied (os error 5)"，ACL 再宽松也没用（没有 Deny ACE，是完整性
      # 级别拦的）。所以 CI 用到的每个"家目录"都挪到 runner 自己的工作目录下，
      # 那几处在 job 内的写探测里实测可写。换一台 Windows runner 时改这几行。
      RUSTUP_HOME: C:\Users\admin\runner\windows\cache\ci-rustup
      CARGO_HOME: C:\Users\admin\runner\windows\cache\ci-cargo
      # LOCALAPPDATA/APPDATA 也得改：pnpm 12 的 store 锁与 cache/state 都挂在
      # %LOCALAPPDATA% 下（报错原文：pnpm-store-operation-locks\all-stores.lock:
      # 拒绝访问），tauri 打包时下载的 NSIS 也放这儿。本机实测：把 LOCALAPPDATA
      # 指到可写目录后，pnpm 会在那里建 pnpm-cache / pnpm-state，install 正常。
      LOCALAPPDATA: C:\Users\admin\runner\windows\cache\ci-localappdata
      APPDATA: C:\Users\admin\runner\windows\cache\ci-appdata
      npm_config_cache: C:\Users\admin\runner\windows\cache\ci-npm
      RUNNER_TOOL_CACHE: C:\Users\admin\runner\windows\cache\ci-toolcache
    steps:
      - uses: actions/checkout@v4
      # 宿主模式的 Windows runner 上，PATH 里的 `bash` 是 C:\Windows\System32\bash.exe
      # —— WSL 的启动器，而 WSL 在 runner 账户下起不来，报 E_ACCESSDENIED（日志里是
      # 一串 GBK 被当 UTF-8 解出来的乱码 + https://github.com/microsoft/WSL/issues）。
      # 于是任何 `shell: bash` 的步骤、以及用 bash 写的 composite action
      # （dtolnay/rust-toolchain 就是），都会在 0 秒内失败。
      # Git for Windows 自带 bash，把它的 bin 前置到 PATH —— GITHUB_PATH 的语义就是
      # **前置**插入，所以它会盖过 System32 那个 —— 后面这些步骤才跑得起来。
      #
      # 换掉 bash 之后还有第二个坑：这个 job 的环境里 TEMP/TMP 是空的，而 Git Bash 的
      # /tmp 是从 TEMP 推出来的；没有 TEMP 它会退回 <Git 安装目录>\tmp
      # （C:\Program Files\Git\tmp），那个目录普通权限写不进去，于是 dtolnay 里那句
      # log=$(mktemp) 直接挂掉：
      #     mktemp: failed to create file via template '/tmp/tmp.XXXXXXXXXX': Permission denied
      # 所以顺手给 job 指定一个自己建的可写目录（workspace 的同级 ci-tmp）。
      # 两个坑都是 2026-10-15 真跑 Windows job 时踩出来的，本地按这样改完后
      # mktemp、rustup toolchain install、rustup target add 全部正常。
      - name: 让 bash 指向 Git for Windows，并给 job 一个可写的临时目录
        shell: pwsh
        run: |
          if (-not $env:GITHUB_PATH) { throw '这个 runner 没提供 GITHUB_PATH，没法给后续步骤改 PATH' }
          if (-not $env:GITHUB_ENV) { throw '这个 runner 没提供 GITHUB_ENV，没法给后续步骤加变量' }
          if (-not $env:GITHUB_WORKSPACE) { throw '这个 runner 没提供 GITHUB_WORKSPACE' }
          $gitBash = 'C:\Program Files\Git\bin'
          if (-not (Test-Path (Join-Path $gitBash 'bash.exe'))) {
            throw "找不到 $gitBash\bash.exe：这台机器上没装 Git for Windows，bash 会落到 WSL 上"
          }
          Add-Content -Path $env:GITHUB_PATH -Value $gitBash -Encoding ascii
          $tmpRoot = Join-Path (Split-Path -Parent $env:GITHUB_WORKSPACE) 'ci-tmp'
          New-Item -ItemType Directory -Force -Path $tmpRoot | Out-Null
          Add-Content -Path $env:GITHUB_ENV -Value "TEMP=$tmpRoot" -Encoding ascii
          Add-Content -Path $env:GITHUB_ENV -Value "TMP=$tmpRoot" -Encoding ascii
          Add-Content -Path $env:GITHUB_ENV -Value "TMPDIR=$($tmpRoot -replace '\\', '/')" -Encoding ascii
          # 第三个坑：pnpm 的 store 操作锁是按 <USERPROFILE>\AppData\Local\
          # pnpm-store-operation-locks 算的 —— 实测只把 LOCALAPPDATA 指走它不跟，
          # 只把 USERPROFILE 指走它就跟着走（换完 USERPROFILE 后探针目录里立刻出现
          # all-stores.lock）。所以 USERPROFILE 也得指到能写的地方，并且先把
          # AppData\Local、AppData\Roaming 建好。
          $profileRoot = Join-Path (Split-Path -Parent $env:GITHUB_WORKSPACE) 'ci-profile'
          New-Item -ItemType Directory -Force -Path (Join-Path $profileRoot 'AppData\Local'), (Join-Path $profileRoot 'AppData\Roaming') | Out-Null
          Add-Content -Path $env:GITHUB_ENV -Value "USERPROFILE=$profileRoot" -Encoding ascii
          "bash = $(Join-Path $gitBash 'bash.exe')"
          "TEMP/TMP/TMPDIR = $tmpRoot"
          "USERPROFILE     = $profileRoot"
      - name: 装 Rust（stable）
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: x86_64-pc-windows-msvc
      - name: 装 Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      # 这里**不用** pnpm/action-setup：它装的是 standalone 的 pnpm 二进制，而那个
      # 二进制在这台 runner 的低完整性沙箱里走到"把包装进 virtual store"时必崩：
      #     thread '<unknown>' (6716) has overflowed its stack
      # corepack 拉下来的是同一个二进制（也崩），所以改成用 npm 装 JS 版 pnpm ——
      # 它跑在 node 上，是另一条代码路径。装到 node 自己的目录里（RUNNER_TOOL_CACHE
      # 已经指到可写位置，见 job env）。
      - name: 装 pnpm（npm 装 JS 版，绕开 standalone 二进制）
        shell: pwsh
        run: |
          # 前面几次尝试在 node 目录里留下过 pnpm/pnpx 的影子文件，npm 会以
          # EEXIST 拒绝覆盖，先清掉（node 目录在 RUNNER_TOOL_CACHE 下，可写）。
          $nodeDir = Split-Path (Get-Command node).Source
          foreach ($n in 'pnpm', 'pnpx', 'pnpm.cmd', 'pnpx.cmd', 'pnpm.ps1', 'pnpx.ps1') {
            Remove-Item (Join-Path $nodeDir $n) -Force -ErrorAction SilentlyContinue
          }
          npm install -g pnpm@12.8.1
          if ($LASTEXITCODE -ne 0) { throw "npm 装 pnpm 失败（exit $LASTEXITCODE）" }
          "pnpm = $((Get-Command pnpm).Source)"
          pnpm --version
      - name: 前端依赖（严格按 lock 装）
        working-directory: desktop
        shell: pwsh
        # 这台 runner 的 job 跑在低完整性沙箱里（见文件头第 5 条），standalone 的
        # pnpm 到"把包装进 virtual store"那一步会直接栈溢出：
        #     thread '<unknown>' (6716) has overflowed its stack
        # （store 已经在可写目录、也改成 copy 导入了，仍然复现；同样的命令在普通
        #   Medium 会话里跑得好好的。）所以先试 standalone，崩了就退回 corepack：
        # 让 node 去跑 pnpm 的 JS 实现，绕开那个二进制。
        run: |
          $pnpmArgs = @('install', '--frozen-lockfile',
                        '--store-dir', 'C:\Users\admin\runner\windows\cache\ps',
                        '--package-import-method=copy', '--reporter=append-only')
          pnpm @pnpmArgs
          if ($LASTEXITCODE -eq 0) { exit 0 }
          "::warning::standalone pnpm 失败（exit $LASTEXITCODE），改用 corepack + node 跑 pnpm"
          corepack enable
          corepack prepare pnpm@12.8.1 --activate
          pnpm @pnpmArgs
          exit $LASTEXITCODE
      # nsis 是纯安装包，不需要 WiX；tauri 会自己把 NSIS 下到用户缓存里（这个缓存
      # 也跟着 LOCALAPPDATA 走，见上面 job env），所以这台 runner 要能访问 GitHub
      # （离线环境改成 --bundles msi 也一样要下 WiX）。
      - name: 打包（tauri build）
        working-directory: desktop
        run: pnpm tauri build --target ${{ env.TARGET }} --bundles nsis
      - name: 上传产物
        uses: actions/upload-artifact@v3
        with:
          name: cam-desktop-windows-x64
          if-no-files-found: error
          retention-days: 14
          path: |
            desktop/src-tauri/target/${{ env.TARGET }}/release/bundle/nsis/*.exe
  # ───────────────────────────────────────────────────────────────────────────
  # macOS 通用包：.app + .dmg
  # ───────────────────────────────────────────────────────────────────────────
  macos:
    name: macOS 通用（.app + .dmg）
    needs: checks
    # 还没有 macOS runner，所以只有"手动触发 + 勾上"才跑；等机器注册好，把这一行
    # 换成 `github.event.inputs.macos != 'false'` 就变成默认跑（同 Windows）。
    if: ${{ github.event.inputs.macos == 'true' }}
    # 那台机器上要有 Xcode Command Line Tools（链接要它）与 rustup。
    runs-on: ${{ vars.RUNNER_MACOS || 'macos-latest' }}
    timeout-minutes: 150
    env:
      # 注意：这里**不能**设 CARGO_BUILD_TARGET —— universal-apple-darwin 是 tauri
      # 自己的伪目标（编两遍再 lipo 合成），裸 cargo 不认它。这个 job 里也没有裸
      # cargo 步骤，所有目标都由 tauri build 的 --target 交代。
      TARGET: universal-apple-darwin
    steps:
      - uses: actions/checkout@v4
      # 通用包要两个架构的 std 都在。
      - name: 装 Rust（stable + 两个 mac 目标）
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: aarch64-apple-darwin,x86_64-apple-darwin
      - name: 装 pnpm
        uses: pnpm/action-setup@v4
        with:
          version: ${{ env.PNPM_VERSION }}
      - name: 装 Node
        uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
      - name: 前端依赖（严格按 lock 装）
        working-directory: desktop
        run: pnpm install --frozen-lockfile
      # 只想要当前架构、想省一半编译时间的话，把 --target 换成 aarch64-apple-darwin
      # （Apple Silicon 的 runner）并去掉上面 targets 里的 x86_64 即可。
      - name: 打包（tauri build）
        working-directory: desktop
        run: pnpm tauri build --target ${{ env.TARGET }} --bundles app,dmg
      # 第二行是兜底：不同 tauri-cli 版本给通用包放的目录略有差异，宁可多写一行，
      # 也不要上传时静默少东西。（注意 path 是块标量，里面写 # 是路径不是注释。）
      - name: 上传产物
        uses: actions/upload-artifact@v3
        with:
          name: cam-desktop-macos-universal
          if-no-files-found: error
          retention-days: 14
          path: |
            desktop/src-tauri/target/${{ env.TARGET }}/release/bundle/dmg/*.dmg
            desktop/src-tauri/target/*/release/bundle/dmg/*.dmg
@@ -1,15 +1,34 @@
 # 构建产物。
 #
-# 三条都必要：根目录是 firmware crate，protocol/ 和 client/ 各自也是独立的
+# 每一行都必要：根目录是 firmware crate，protocol/ 也是独立的 crate（有自己的
-# crate（各有自己的 .cargo/config.toml 与 target 目录），所以只写 `target/`
+# .cargo/config.toml 与 target 目录），armor/ 是一套独立 workspace（协议层 +
-# 匹配不到它们。
+# ESP32-C3 固件），同理。所以只写 `target/` 匹配不到它们。
 #
 # 全部锚定在根目录（前置 /），这是有意的：components/esp32-camera/target/ 看着
 # 像构建产物，其实是上游组件的**按芯片分目录**（esp32/ esp32s2/ esp32s3/ …），
 # 里面是 ll_cam.c 等源码，包含本项目打的补丁。不要把它一起忽略掉。
 #
 # desktop/ 自己还有一份 .gitignore（node_modules、dist、三个 crate 的 target）。
 /target/
 /protocol/target/
-/client/target/
+/armor/target/
 # 本机专属的 cargo 注册表缓存。
 #
 # 这个仓库所在的目录树在 DSH 的文件沙箱里可写，而 ~/.cargo 不可写，所以 desktop/ 的
 # 构建把 CARGO_HOME 指到了这里（里面是从 ~/.cargo 搬过来的 crates 缓存）。它是几 GB 的
 # 机器状态，不是项目的一部分。
 /.cargo-home/
 # WiFi 凭据，编译期由 env! 读取。不要提交。
 .env
 # pnpm 在本机把 store 落在了工作区里（沙箱下 HOME 里的 store 不可写）。
 /.pnpm-store/
 # macOS 的目录元数据。不锚定，子目录里的也一起忽略。
 .DS_Store
 # `docs/simba_docs`：工作区里另起的一个 Astro 文档站，与本仓库的目录结构无关，
 # 也不属于本项目的产物。留着不跟踪，免得以后 `git add -A` 顺手把它带进来。
 /docs/
@@ -1,402 +1,395 @@
 # ESP32-S3 摄像头图传（Rust / ESP-IDF / UDP）
-**ESP32-S3-WROOM-1-N16R8** + OV2640 / OV3660 / OV5640（DVP 接口）实时图传，
+两块 ESP32-S3-WROOM-1-N16R8 图传板（DVP 接口接 OV5640），向队伍客户端与裁判终端推
-客户端是 Rust + Slint 桌面程序。固件是跑在 ESP-IDF 上的 Rust，用官方
+UDP 图传。
 `esp32-camera` 组件做采集。
-```
+固件是跑在 ESP-IDF 上的 Rust，用官方 esp32-camera 组件采集；桌面端是 **Tauri v2 +
-protocol/   线路格式 + 帧重组    （有单元测试，为宿主架构编译）
+React**，用户端与裁判端两套页面（见 [`desktop/README.md`](desktop/README.md)）。同一套
-.           固件  -> ESP32-S3    （交叉编译，Xtensa）
+系统里还有一队一块的**装甲板**（ESP32-C3，一主三从），负责四路击打检测、灯带与整车血量，
-client/     桌面客户端           （Slint，macOS/Linux/Windows）
+并把血量广播给局域网里的两端。
 ```text
 protocol/   线路格式 + 帧重组    三端共用，无 ESP-IDF 依赖，14 个单元测试
 .           图传固件  -> ESP32-S3  交叉编译，Xtensa
 armor/      装甲板固件 -> ESP32-C3  独立 workspace，RISC-V；规则层 22 个单元测试
 desktop/    桌面端               Tauri v2 + React；用户端（双方血条 + 瞄准器）/ 裁判端（可改队名）
            core/               不含界面与 Tauri 的网络层、配置、密码（可单测）
            src-tauri/          Tauri 后端：推流、命令、录制
            src/                React 前端：两套页面 + HUD
 ```
-`protocol/` 被两端共用，所以线路格式不可能各自漂移。
+五份产物各自独立构建，各有自己的 `.cargo/config.toml`。
 ## 拓扑
 ```text
                    ┌──────────────────────────────┐
                    │  裁判终端（PC，仅显示）      │
                    │  队伍一 + 队伍二 + 双方血量   │
                    └───────────────┬──────────────┘
                                    │  同一个局域网，广播可用
               ┌────────────────────┼────────────────────┐
               │                    │                    │
       ┌───────┴───────┐    ┌───────┴───────┐    ┌───────┴───────┐
       │  图传板 A     │    │  图传板 B     │    │  装甲板主板   │
       │  (队伍一)     │    │  (队伍二)     │    │  ×2（每队一块）│
       └───────────────┘    └───────────────┘    └───────────────┘
 ```
 **图传板不区分队伍。** 它们只知道自己是谁（MAC 派生的 `sender_id`），"哪一边"由
 客户端决定。烧同一份固件即可，配置全在客户端一侧。
 **装甲板反过来：队伍是编译期定的**（`ARMOR_TEAM=0/1`，同时决定灯色红/蓝），因为血量
 上报里必须带 `team` 字段，而且灯色现场不该靠按键切错。见 `armor/README.md`。
 裁判终端同时收两块图传板，也收两块装甲板主板在 5601 上广播的血量。队伍客户端也收
 全部板子的视频，然后在**界面层**过滤到绑定的那一块；**血量相反，两边都显示**——用户端的
 画面左上角是自己、右上角是对手。血量本来就是明文广播的（裁判端与用户端收的是同一份），而
 "自己的血与对手的血一起看"是这项运动里最基本的对照，藏起来只会让操作手看不见对手的血。
 ## 实测性能
-VGA 640x480，JPEG 质量 12，板子与 2.4GHz AP 相距约一间房：
+VGA 640x480，传感器产出上限 22 fps（OV5640 在此配置下的实测值）。
-| | TCP（HTTP MJPEG） | UDP |
+| | TCP（HTTP MJPEG） | UDP（现在） |
 |---|---|---|
-| 帧率 | 1.9 fps | **20.8 fps** |
+| 传感器实际产出 | 22 fps | 22 fps |
-| 丢帧 | 大量超时 | **0.0%**（146 帧 / 1270 个数据报） |
+| 客户端实际收到 | **1.9 fps** | **22 fps** |
-| 帧间隔 | 测不出来 | 35 ms |
+| 实际吞吐 | 0.28 Mbit/s | 1.6 Mbit/s |
-| 实际吞吐 | 0.28 Mbit/s | 1.72 Mbit/s |
+| 丢帧 | — | 0% |
 | 传感器自身上限 | 22.2 fps | 22.2 fps |
-UDP 这条路已经跑到传感器的极限，网络不再是瓶颈——即便如此也只用掉链路的
+TCP 那一栏只用了链路能力的 1% 左右（ESP32-S3 在良好 2.4GHz 链路上 TCP 实测上限约
-6–9%，说明瓶颈从头到尾都不在带宽上。
+20–30 Mbit/s）。**链路是空的**，帧却堵在队头阻塞后面等一个实时画面等不起的重传计时
-（为什么用 UDP、以及 TCP 那组数字到底说明什么，见
+器。
 [`protocol/README.md`](protocol/README.md)。）
---
+UDP 没有重传与确认：缺了分片的帧整个丢弃，下一帧顶上。丢帧率实测 0%，因为带宽从来
 不是瓶颈——即便如此也只用掉 6–9%。
-# 固件
+其余数字：平均帧 22 kB，约 350 包/秒，每帧约 17 个分片，客户端观测的帧间隔 7 ms。
-## 环境要求
+## 为什么视频走 UDP 而不是 TCP
- **Rust 的 `esp` 工具链。** 仓库里有 `rust-toolchain.toml`，所以
+**延迟优先。** 丢失 5% 的画面远好于等待 500 ms 的重传。
  `rustup toolchain install esp` 就够；否则用 `espup install`。
 - **ESP-IDF。** `.cargo/config.toml` 通过 `IDF_PATH` 指向已有的安装。删掉那两行
  的话，`esp-idf-sys` 会自己 clone 并构建它固定的那个版本——能用，但要下载几百 MB。
 - **Python 3**（ESP-IDF 构建系统要用）。
 - **esptool** 或 **espflash**，用来烧录。
-先确认本机已具备：
+**没有队头阻塞。** 一帧的任一分片卡住，后面所有帧都跟着卡——对实时画面这正好是错
 的方向。
 **带宽不是约束。** 见上表，TCP 那栏证明了链路是空的，所以 TCP 的优势在这里换不来
 任何东西。
 代价是丢包丢整帧。这被接受了：**撕裂的画面比过期的画面更糟**，所以接收端不做补洞，
 只等下一张完整帧。
 ## 帧率必须按计数除以墙钟
 "22 fps" 这个数字不是对帧间隔取平均得来的，是每个窗口的**帧数增量除以窗口时长**。
 一次 UI 轮询（33ms）之间可能完成多帧，平均间隔量的是**显示**的刷新快慢而不是**相机**
 的出帧快慢——那会把上限 22fps 的传感器报成 36fps。**一个笃定的错误数字比没有数字更
 糟**，现场你会以为还有性能余量，然后花时间去找一个不存在的问题。
 这个错误在本项目里出现过两次（客户端的 `View::update_fps`、探测脚本的分窗打印），两
 次都是同一个形状：分子用累计值，分母用窗口值，于是报出随时间单调上升的假数字。
 ## 快速开始
 ### 1. 固件
 ```sh
-rustc --version          # 必须是 esp 工具链
+cp .env.example .env      # 填 WIFI_SSID / WIFI_PASS
-espflash --version
+./scripts/flash.sh --monitor 20
 python3 --version
 ```
-## 配置
+`flash.sh` 会编译、挑选避开坏字节的 app 偏移、烧录三段（bootloader / 分区表 /
 app）、打印串口日志。ESP-IDF 位置从 `.cargo/config.toml` 读，不用先 `activate`。
-WiFi 凭据在**编译期**由 `env!` 读取，所以放在 `.env` 里，不进源码。`.env` 已在
+`.env`：
 gitignore 中。
 ```sh
-cp .env.example .env
+WIFI_SSID=你的2.4G网络
-```
+WIFI_PASS=密码
-```sh
+# 装甲板（armor/）用这两个里的第一个；队伍号决定灯色与上报里的 team 字段：
-# .env
+#ARMOR_TEAM=0        # 0 = 队伍一（红），1 = 队伍二（蓝）
 WIFI_SSID=你的2.4G频段ssid
 WIFI_PASS=你的密码
 # 以下都有默认值：
 #CAM_RES=vga          # qqvga | qvga | cif | hvga | vga | svga | xga | sxga | uxga
 #CAM_QUALITY=12       # 0-63，数字越小画质越好、字节越少
 #CAM_VSYNC_INVERT=1   # 若板子在硬件上反相了 VSYNC，填 0
 #WIFI_AUTH=wpa2       # 固定认证方式，仅当扫描看不到 AP 时需要（如隐藏 SSID）
 ```
-SSID **必须是 2.4GHz**。ESP32-S3 的射频不支持 5GHz，5GHz 的 SSID 对它完全不可见，
+凭据由 `env!` 在**编译期**读取，所以没有运行时解析路径，也不会因为忘了读 `.env` 而
-板子只会一直超时等待。固件在关联前会先扫描并打印可见网络，正是为了让这个问题
+在板子上带着别人的密码。`ARMOR_TEAM` 同理：换队伍重刷装甲板固件即可，不用擦 NVS。
 能被一眼看出：
-```
+`WIFI_AUTH` 一般不用设：固件先扫描 AP，用它报告的真实认证方式去连，只有扫不到时才
-I esp32: scanning for 2.4 GHz networks...
+需要人工指定。指定之后**只**试这一种方式——不成功就直接报错，而不是挨个试 10 秒。
-I esp32:   SR-602-2G4    ch  6  -27 dBm  Some(WPAWPA2Personal)  <- target
+挨个试等于在猜一个本该已知的值。
 E esp32: "SR-602-5G" was not in the scan results
 ```
-## 编译
+### 2. 装甲板固件（ESP32-C3）
 ```sh
-./scripts/build.sh
+scripts/flash_armor.sh            # 编译 + 烧录 + 20 秒串口日志
 python3 scripts/armor_probe.py 15 # 不开界面，单看板子在广播什么血量
 ```
-这就是"读取 `.env` 后执行 `cargo build --release`"。产物在
+接线表、血量规则、C3 的 RMT/ADC 踩坑都在 [`armor/README.md`](armor/README.md)。
 `target/xtensa-esp32s3-espidf/release/esp32`（约 1.1 MB）。
-> **改了 C 文件？**
+### 3. 桌面端
 > `components/esp32-camera/**` 和 `components/cam_wrapper/**` 不在 `esp-idf-sys`
 > 的依赖追踪里，所以改它们**不会**触发重新编译，会静默地用旧代码。先清缓存：
 >
 > ```sh
 > rm -rf target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*
 > ./scripts/build.sh
 > ```
 ## 烧录并看日志
 ```sh
-./scripts/flash.sh --monitor 30
+cd desktop
 pnpm install
 pnpm app          # = tauri dev
 ```
-它会编译、烧录、打印串口日志。预期输出：
+没有板子也能把整条链路跑起来：`CAM_DEMO=1 pnpm app` 会合成**协议数据报**喂进真实的接收
 路径（分片、重组、发现、掉血派生、两道闸门全在跑真代码），界面上标着"演示模式"。
-```
+首次启动会问这台机器是哪一端：**用户端**要绑一块图传板与一块装甲板（改动需密码），
-I (2790) cam_wrapper: fps probe: 20 frames in 900 ms -> 22.2 fps, avg 9246 bytes
+**裁判端**不需要任何配置就能看两路。
 I (9817) esp32::udp: UDP sender listening on port 5600, streaming on request
 I (9817) esp32: ESP32 camera is live on 192.168.1.139
 I (9817) esp32: point the client at 192.168.1.139:5600 (UDP)
 ```
-`fps probe` 那一行是**传感器上限**，在 WiFi 启动之前测的。排查流速慢时要拿它做
+**`desktop/.cargo/config.toml` 里的 `target = "aarch64-apple-darwin"` 换机器必须改。**
-对照：如果 probe 说 22fps 而实际流不到，问题就在两者之间。
+desktop/ 嵌在固件的目录树里，会继承父目录那个 `xtensa-esp32s3-espidf` 的交叉编译配置，
 然后在依赖深处以 `libc` 找不到 `MAP_FAILED` 的形式失败。
-### 手动烧录
+界面、视频通道、密码模型、录制与排查都在 [`desktop/README.md`](desktop/README.md)。
-`scripts/flash.sh` 存在的原因之一是有一块坏 flash 字节（见
+## 发现是双向的
 [硬件相关](#硬件相关)）。它用 `esptool` 写三段：
-```sh
+单靠一个方向建立不了"谁要看我"：
 B=$(ls -d target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*/out/build)
 espflash save-image --chip esp32s3 --format esp-idf \
    target/xtensa-esp32s3-espidf/release/esp32 /tmp/app.bin
-~/.espressif/tools/python/*/venv/bin/python -m esptool \
+- 板子每 **2 秒**广播一次 Hello —— "我在线，我是谁"
-    --chip esp32s3 --port /dev/cu.usbmodemXXX --baud 460800 write-flash \
+- 客户端每 **800 ms**广播一次 Subscribe —— "我是这个角色，请给我画面"
    0x0     "$B/bootloader/bootloader.bin" \
    0x8000  "$B/partition_table/partition-table.bin" \
    0x10000 /tmp/app.bin
 ```
-注意 app 偏移必须和 `partitions.csv` 里的 `factory` 一致。这里不能用
+板子从订阅的**源地址**学到推流目标（所以客户端的 socket 必须固定绑 5600 端口，不能
-`cargo espflash flash`：它只写 app 段，而且会在没有 `.env` 的情况下重新编译，
+用临时端口）。
 导致 `main.rs` 里的 `env!` 失败。
-### 找串口
+对端靠**源地址**记忆，不发探测包。续订本来就每 800 ms 一次，所以"还活着吗"这个问题
 由续订本身回答了——超时即代表它离开了，多一份心跳状态就多一个能出错的地方。
-```sh
+两端各有自己的超时淘汰，阈值不同：
 ls /dev/cu.usbmodem*        # 这块板子显示为 /dev/cu.usbmodem111301
 ```
-`scripts/flash.sh` 会取第一个匹配项，也可以 `ESP_PORT=/dev/cu.usbmodemXXX` 指定。
+| | 超时 | 为什么是这个量级 |
 ---
 # 客户端
 ## 环境要求
 - Rust（普通 stable 或 nightly，**不要**用固件那个 `esp` 工具链）
 - 不需要额外的系统库：macOS 和 Linux 上 Slint 用 `femtovg` 渲染，也不需要 `skia`
 > `client/.cargo/config.toml` 把 `target` 钉成 `aarch64-apple-darwin`，因为这个
 > 目录位于固件源码树内部，否则会继承 Xtensa 交叉编译配置。**要按你的机器改**——
 > Intel Mac 用 `x86_64-apple-darwin`，Linux 用 `rustc -vV | grep host` 的输出。
 ## 编译与运行
 ```sh
 cd client
 cargo build --release
 ./target/aarch64-apple-darwin/release/cam-client          # 用下面的默认地址
 ./target/aarch64-apple-darwin/release/cam-client 192.168.1.139
 ```
 ```
 用法: cam-client [CAMERA_IP] [PORT]
  CAMERA_IP   ESP32 摄像头地址（默认 192.168.1.139）
  PORT        UDP 视频端口  （默认 5600）
 ```
 改 `ui/camera.slint` 时用一步到位的方式：
 ```sh
 cd client && cargo run --release -- 192.168.1.139
 ```
 ## 界面读数
 ```
 streaming            20.8 fps   10.1 kB per frame   35 ms between frames
 640x480              shown 146   dropped 0 (0.0%)   1270 datagrams
 ```
 **丢帧率和帧率同等重要**，这正是把统计放在界面上的原因。这条传输链路是**整帧丢弃
 而不重传**，所以单看帧率是有歧义的：
 | 帧率 | 丢帧 | 含义 |
 |---|---|---|
-| 达到传感器上限 | 0 | 链路没问题，瓶颈是传感器 |
+| 固件丢弃订阅者 | 6 s | 续订间隔 800 ms，7 倍余量，偶发丢包不会把人踢掉 |
-| 远低于上限 | 有 | 瓶颈是网络 |
+| 客户端移除板子 | 60 s | 只影响界面列表，不影响推流 |
 | 低 | 0，且显示 "no frames - camera?" | 板子没在推流 |
-状态文字的颜色是同一信息的粗略版本：推流中绿色，否则琥珀色。
+客户端的 60 s 刻意很长：界面列表里留着一块刚重启还没广播的板子，比它短暂消失更可接
 受。而它每 5 秒才扫一次，不值得为这个上一份状态。
-### 帧率是"计数"算出来的，不是"平均间隔"
+固件同时最多向 **4 个**订阅者推流（`MAX_PEERS`）。每个对端每帧要一次 `sendto`，这是帧
 CPU 成本的倍数；三台客户端（两队 + 裁判）够用，且不让一个陈旧的地址条目拖慢每一帧。
-不是对帧间隔取平均。一次 UI 轮询之间可能已完成好几帧，所以平均间隔量的是
+## 身份：为什么用 MAC 派生
 **显示**的刷新快慢，而不是**相机**的出帧快慢——那曾把上限 22fps 的传感器报成
 36fps。一个笃定的错误数字比没有数字更糟。
-## 诊断
+`protocol::id_from_mac()` 用 FNV-1a 从 MAC 派生 `sender_id`，避开 0（裁判终端的保留
 值）。
 **用 MAC 而不是 IP**，因为客户端要把绑定存进配置文件并在重启后继续有效——DHCP 换地
 址是常态，MAC 不会变。用 MAC 也意味着烧同一份固件即可，不需要任何"我是谁"的配置。
 ## 线路格式
 27 字节头 + 至多 1400 字节载荷，全部小端。细节在 `protocol/README.md`，那里有完整
 的字节图和每个拒收条件。
 三处关键决定：
 - **27 字节不凑整。** 头只占每个 1427 字节数据报的 1.9%，而为对齐在两端各写一段
  手写偏移常量，是引入静默错位的更划算的代价。
 - **每个数据报 1427 字节，低于 1500 MTU。** 超 MTU 的数据报要么被 AP 丢、要么被 IP
  分片，两种情况的丢包都记在应用账上而不是网络账上——后者本来更容易排查。
 - **`version` 不匹配就拒收**，而不是按错误布局继续解析。后者表现为随机崩溃或画面错
  乱，比拒绝连接难查得多。
 ## 硬件
 Freenove ESP32-S3-WROOM CAM，ESP32-S3-WROOM-1-N16R8（16 MB flash + 8 MB octal
 PSRAM），OV5640。
 ### 引脚
 `src/camera.rs` 的 `pins` 模块：
 | | GPIO |
 |---|---|
 | RESET | 0 |
 | XCLK | 15 |
 | PCLK | 13 |
 | VSYNC | 6 |
 | HREF | 7 |
 | SIOD (SDA) | 4 |
 | SIOC (SCL) | 5 |
 | DATA[0..8] | 11, 9, 8, 10, 12, 18, 17, 16 |
 ### 千万不要套用别的板子的引脚表
 这块板子的 GPIO 分配是死的：
 | 范围 | 占用 |
 |---|---|
 | 26–32 | SPI flash |
 | 33–37 | octal PSRAM |
 | 19 / 20 | USB |
 | 43 / 44 | console |
 | 45 / 46 | 模组内部 |
 直接套用 AI-Thinker ESP32-CAM 的引脚表会有 **7 根冲突**。冲突的表现不是"某根线不
 通"，而是 `PIN_FUNC_SELECT` 把某个外设接到了 flash 或 PSRAM 上，**CPU 在传输中途挂
 死**——没有报错、没有回溯、串口直接静默。
 改引脚前先对照上面这张表。
 ### 那块坏掉的 flash 字节
 测试用的这块模组在 `0xFADE7` 有个字节的 bit 5–7 **写不进去**。镜像放在哪里会决定哪
 个镜像字节落到这个地址，落上去就校验失败、bootloader 拒绝启动。
 镜像本身不因位置而变，所以移动 app 分区就够了。`scripts/flash.sh` 会挑最低的 64 KB
 对齐、且该地址处字节 flash 真的能存的偏移，写回 `partitions.csv`，然后重新编译
 （重编译会让镜像位移，所以编译后再验证一次）。
 **换到健康硬件**：把 `factory` 分区放回 `0x10000`，删掉 `flash.sh` 里的
 `BAD_FLASH_ADDR`，别的什么都不用改。
 Flash 跑 DIO @ 40 MHz 而不是这颗片子的标称 QIO/80 MHz：测试模组的坏字节在 quad 模式
 下会被推到 boot loop。QIO 对**代码执行**速度的提升是明显的（程序从 flash 跑，cache
 miss 直接打在这条总线上），健康硬件上值得换回去试。
 ### `PSRAM DMA` 是故意关掉的
 开着的话，esp32-camera 让 GDMA 直接把帧缓冲写进 PSRAM，然后**只在最后一个 DMA 节点
 （1 KB）里**找 JPEG 结束标记。标记落在窗口外就丢帧并报 `NO-EOI`——在这块板子上是大部
 分的帧，几帧之后驱动干脆不再交出任何帧，而且不恢复。
 关掉之后驱动 DMA 到内部 RAM 的中转缓冲，再 memcpy 进 PSRAM。每帧多一次约 23 KB 的
 memcpy，但搜索整个缓冲找标记。对一条能用的图传链路，这是对的取舍。
 ### CPU 频率
 **`CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y`** 是 `sdkconfig.defaults` 里最值钱的一行，
 而且免费。
 ESP-IDF v5.5 的 Kconfig 把 ESP32-S3 默认成 **160** MHz（见
 `components/esp_system/port/soc/esp32s3/Kconfig.cpu`），所以默认编译悄悄浪费了一半
 CPU。相机采集、esp32-camera 里的 JPEG 搜索、lwIP、发送路径全是 CPU 密集的，这一行一
 次性把它们全部搬上去。
 ### WiFi 缓冲留在内部 RAM
 `CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP=n`。
 这个值曾经按"PSRAM 很空闲"的直觉写成 `y`，方向恰好相反：WiFi 描述符和 TCP 段**每个
 包都要碰**，内部 SRAM 比隔着内存总线的 PSRAM 快一个数量级。把它们放进 PSRAM 的表现是
 高延迟和差吞吐，无论 PSRAM 还剩多少。
 帧缓冲相反——它大、相对少碰，留在 PSRAM。
 ### 相机任务钉在 CPU1
 `CONFIG_CAMERA_CORE0=n`（即跑在 CPU1）。WiFi 任务钉在 CPU0。esp32-camera 的采集任务
 时间是短促且延迟敏感的（DMA 完成、JPEG 标记搜索、拷进帧缓冲），在共享核上会被抢占，
 每一帧都被拉长。双核芯片上没有理由共享。
 ## vendored esp32-camera
 `components/esp32-camera/` 是上游 2.1.7 的副本，因为组件注册表的版本求解器找不到它。
 它打了一处补丁：`target/esp32s3/ll_cam.c` 里的 `CAM_IO_MUX_REG()`。这个宏负责把引脚
 接到 I2C（OV5640 的 SCCB 走 I2C），不接的话传感器根本不会被发现。
 **注意这个目录叫 `target/`，但它不是构建目录。** 它是上游组件的按芯片分目录
 （`esp32/`、`esp32s2/`、`esp32s3/`），里面是 `ll_cam.c` 等源码，包含上述补丁。所以
 `.gitignore` 里三条 `target/` 规则全部锚定在根目录——这是有意的。
 ## 改过 C 文件之后
 ```sh
-RUST_LOG=info ./target/aarch64-apple-darwin/release/cam-client 192.168.1.139
+rm -rf target/xtensa-esp32s3-espidf/release/build/esp-idf-sys-*
 ```
-```
+不删不会重新编译，你的补丁看起来像完全没生效。
 frames shown 146 | dropped 0 (0.0%) | datagrams 1270 | undecodable 0 | short 0
 ```
-| 计数器 | 含义 |
+## 摄像头端不编码，客户端不编码
 |---|---|
 | `frames shown` | 完整重组并交给界面的帧 |
 | `dropped` | 因分片缺失而被放弃的帧 |
 | `datagrams` | 能解析为分片的数据报 |
 | `undecodable` | 收到了但解析不了的数据报 |
-`undecodable` 非零意味着板子的数据报**到了但没看懂**——是协议或端口对不上，不是网络
+OV5640 的 JPEG 编码器**在传感器内部**。DVP 接口出来的一帧要么是 JPEG，要么是 YUV 裸
-问题。这两者很容易混淆，而这个计数器正是用来区分它们的。
+数据。
 不编码的话，单帧从约 21 KB 涨到 **450 KB**（21 倍），而 ESP32-S3 **没有硬件 JPEG
 编码器**（整个 ESP32 系列只有 P4 有，`esp_driver_jpeg` 里
 `CONFIG_IDF_TARGET_ESP32P4` 是写死的）。
 同理，客户端也不编码：板子出的就是传感器里的 JPEG，客户端只解码。ESP32-S3 也没有硬
 件 JPEG 解码器。
 ## 为什么收包和解码要分开线程
 一张 VGA 的 JPEG 解码要几毫秒。放在收包线程里会挤进数据报之间，造成**链路上本不存在
 的丢帧**——不是真的丢了网络包，是应用来不及取走 socket 缓冲。
 现在桌面端把 JPEG **原样**交给 WebView，由浏览器的原生解码器解——后端连解都不解，
 接收线程只做一次 16 字节头的拼接与一次广播。这一条比上面那条更彻底：省掉的不是几毫秒，
 而是一整个线程与一次内存拷贝。细节在 [`desktop/README.md`](desktop/README.md)。
 ## 排查
 | 现象 | 原因 |
 |---|---|
-| 一直显示 `connecting to …` | 板子不在网上，或防火墙拦了入站 UDP 5600 |
+| 板子无输出、串口静默 | GPIO 冲突。CPU 在传输中途挂了，见上面那张占用表 |
-| `no frames - camera?` | 板子停止推流：重启了，或掉线了 |
+| 几帧后停止出图，报 `NO-EOI` | `PSRAM DMA` 被打开了 |
-| 完全没有输出，也没有日志 | host triple 不对，见[目标架构](#目标架构) |
+| 板子在线但 `0 clients subscribed` | 订阅包格式不对。`Subscribe` 的 `role` 字节紧跟 27 字节头，在偏移 27 |
-| 只有第一帧然后卡住 | 另一个客户端连在别的端口上；板子只推给最后宣告的那个 |
+| 一直接到但画面偶尔解不出来 | 帧重组的问题。**先怀疑你的测量工具**：本项目的探测脚本就因为重组状态没按 `frame_id` 隔离，误报过 34 张坏帧 |
-| 颜色错乱 | 通道顺序。当前构建用 `Rgba8Pixel`，另一个选项是 `Bgra8Pixel` |
+| `libc` 找不到 `MAP_FAILED` | `desktop/.cargo/config.toml` 的 target 没改成宿主三元组 |
-| 编译在 `libc` / `memmap2` 报错 | 用的是 `esp` 工具链，或缺少 target triple 覆盖 |
+| 串口看不到任何输出 | 非 TTY 下 `espflash monitor` 不可用，用 `/tmp/rd2.py` 裸读 |
 | WiFi 连不上 | SSID 必须在 2.4GHz。5G 频段看不见 |
 | 裁判端两块画面宽窄不一 | 两格必须是 `flex: 1 1 0` 且 `min-width: 0`：按内容分宽度时，占位文字长的那一格会多占十几个像素 |
 | 裁判端两格显示同一块板子 | 旧版槽位分配的真 bug。现在候选里要排除另一个槽位占着的 id |
 | 有画面但状态栏说"离线" | 视频帧也必须算存活证据（`Discovery::touch`），不能只看 Hello |
 | 改了绑定却"没生效" | 改动需要先解锁；后端每个改动命令都会校验，界面上的入口只是入口 |
---
+独立核对线路格式：
 # 工作原理
 ## 采集 → UDP
 ```
 OV5640 ──DVP──> LCD_CAM/GDMA ──> PSRAM 帧缓冲
                                      │
                         frame::next_frame()  （阻塞）
                                      │
                  切成 1400 字节一个的数据报
                                      │
                          对每个 peer sendto()
 ```
 `esp_camera_fb_get` 会阻塞到传感器出帧，所以帧率跟随传感器，中间没有任何可能被
 积压 overrun 的队列。数据报一进内核，帧缓冲立刻还给驱动——多占着只会增加延迟。
 ## 对端
 板子是服务端，客户端是对等端。客户端绑定 UDP 5600 并发一个宣告数据报；板子随后
 就往它看到的源地址推流，当存活探测开始失败时移除该对端。没有握手、没有发现协议，
 而且客户端晚连（或板子重启）都能自恢复——因为宣告每 500ms 重发一次。
 最多并发 4 个对端。
 ## 为什么要 `cam_wrapper`
 `esp_camera.h` 里的 `camera_config_t` 对已废弃的 SCCB 引脚名用了匿名 union，bindgen
 会生成成 unsafe union 字段，从 Rust 构造很别扭。`components/cam_wrapper` 接收一个
 纯 int 结构体，在 C 侧填 union，于是 Rust 侧的绑定简单到可以安全构造。
 ## 客户端线程模型
 三个线程，且**没有任何 worker 线程碰 Slint 组件**：
 - `udp-reader` —— 收包与重组
 - `jpeg-decode` —— JPEG 解码成 RGBA
 - 主线程 / 事件循环 —— 转成 `slint::Image` 并更新属性，每 30ms 一次
 这是 Slint 的硬性约束而非风格偏好：组件只能在拥有它的线程上使用，
 `Weak<App>` 是 `!Send` 就是为了强制这一点。worker 线程去 upgrade 一个 weak handle
 会拿到 `None` 然后什么都不做——现象和"界面卡死"完全一样。
 ---
 # 硬件相关
 ## 引脚表
 默认匹配 **Freenove ESP32-S3-WROOM CAM** 的摄像头座（`src/camera.rs` 的 `pins`
 模块）：
 | 信号 | GPIO |  | 信号 | GPIO |
 |---|---|---|---|---|
 | RESET | 0 | | D0 (Y2) | 11 |
 | XCLK  | 15 | | D1 (Y3) | 9 |
 | PCLK  | 13 | | D2 (Y4) | 8 |
 | VSYNC | 6 | | D3 (Y5) | 10 |
 | HREF  | 7 | | D4 (Y6) | 12 |
 | SIOD  | 4 | | D5 (Y7) | 18 |
 | SIOC  | 5 | | D6 (Y8) | 17 |
 |       |    | | D7 (Y9) | 16 |
 数据总线是传感器的 **Y2..Y9**，即 10 位像素字的低字节，所以 Y2 是 D0、Y9 是 D7。
 ### 千万不要套用别的板子的引脚表
 上面每个引脚都是 ESP32-S3 空出来的。下面这些**不是**：
 | GPIO | 被什么占用 | 拿来用会怎样 |
 |---|---|---|
 | 26–32 | 模组的 SPI flash | `PIN_FUNC_SELECT` 改掉 flash 的复用，CPU **在传输中途挂死** |
 | 33–37 | octal PSRAM | 同上，对内存总线而言 |
 | 19, 20 | 原生 USB | 串口 console 断掉 |
 | 43, 44 | console UART | 日志断掉 |
 | 45, 46 | 模组内部 | 保留 |
 在 ESP32-S3 上套用 AI-Thinker ESP32-CAM 的引脚表是踩这个坑的经典方式：15 根信号里
 有 7 根落在 flash、PSRAM 或 USB 上。现象是板子能正常枚举、摄像头也能配置成功，
 然后在第一次 `PIN_FUNC_SELECT` 时锁死。
 ## Flash：DIO @ 40MHz
 `sdkconfig.defaults` 用 DIO/40MHz 而不是这个片子标称的 QIO/80MHz，因为测试用的模组
 有一块坏 flash 字节（见下），四线模式会把它推进启动循环。硬件正常的话可以换回
 QIO + 80MHz——程序是从 flash 运行的，这会明显加快**代码**执行。
 ## 坏的那块 flash 字节
 用于点亮的这块模组，其 SPI flash 在 **`0xFADE7`** 有一个字节的 bit5–7 写不进去。
 镜像放在该地址上的任何值都会被破坏，校验和失败，bootloader 拒绝启动。
 镜像内容不受它在 flash 中**位置**的影响，所以 `scripts/flash.sh` 会挑一个 64KB 对齐
 的 app 偏移，使该地址上的字节是这块 flash 存得下的，相应改写 `partitions.csv`，并在
 烧录前校验。
 **这是为坏硬件准备的绕行方案，不是设计选择。** 换到正常模组时：删掉
 `scripts/flash.sh` 里的 `BAD_FLASH_ADDR` 逻辑，把 `partitions.csv` 的 `factory` 改回
 `0x10000`，之后就可以用 `cargo espflash flash`。
 ## `PSRAM DMA` 是故意关掉的
 `sdkconfig.defaults` 里 `CONFIG_CAMERA_PSRAM_DMA=n`，原因就写在那个文件里。简要说：
 开着时 `esp32-camera` 只在最后 1KB 的 DMA 节点里找 JPEG 结束标记（EOI）。标记一旦
 落在窗口外，这一帧就被 `NO-EOI` 丢弃——在这块板子上是大部分帧，之后驱动彻底不再
 交出任何帧且不会恢复。关掉后每帧多一次约 20KB 的 `memcpy`，但搜索范围是整个缓冲。
 ## CPU 频率
 显式设置了 `CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ_240=y`，因为 **ESP-IDF v5.5 把 ESP32-S3
 的默认值设成 160MHz**（`components/esp_system/port/soc/esp32s3/Kconfig.cpu`）。默认
 构建会白白浪费一半 CPU，而采集、JPEG 搜索、lwIP、HTTP 全是 CPU 密集的。启动时确认：
 ```
 I (891) cpu_start: cpu freq: 240000000 Hz
 ```
 ## WiFi 缓冲留在内部 RAM
 `CONFIG_SPIRAM_TRY_ALLOCATE_WIFI_LWIP=n`。这里原本是 `y`，理由是"PSRAM 空间充足"——
 恰好搞反了。WiFi 描述符和 TCP 段每个包都要碰，而内部 SRAM 比隔着内存总线的 PSRAM
 快一个数量级。帧缓冲体积大、相对少碰，仍然留在 PSRAM。
 运行时也关掉了 WiFi 省电模式：开着时空闲的信标间隔要花几百毫秒，表现为卡顿和
 200–300ms 的 ping。
 ---
 # 可调项
 | 项目 | 位置 | 说明 |
 |---|---|---|
 | 分辨率 | `.env` 的 `CAM_RES` | QVGA..UXGA。CIF 以上需要 PSRAM。 |
 | JPEG 质量 | `.env` 的 `CAM_QUALITY` | 0–63，越小越好。VGA 下 12 约 10–20KB/帧。 |
 | 帧缓冲数 | `camera.rs` 的 `fb_count` | 3：一个在填、一个在发、一个备用。 |
 | 指定传感器 | `main.rs` 的 `SensorHint` | 除非探测失败，否则用 `Auto`。 |
 | XCLK | `camera.rs` 的 `xclk_freq_hz` | 20MHz；OV5640 的 PLL 只为此调校过。 |
 | VSYNC 极性 | `.env` 的 `CAM_VSYNC_INVERT` | 仅当板子在硬件上反相时需要改。 |
 | 采集核心 | `CONFIG_CAMERA_CORE0` | `n` 把采集放到 CPU1，避开 CPU0 上的 WiFi 任务。 |
 | 分片大小 | `protocol/` 的 `MAX_FRAGMENT_PAYLOAD` | 1400 保持在 1500 MTU 以内。再大就有 IP 分片风险。 |
 ## 继续提高帧率
 传感器在 VGA 下大约封顶 22fps，而链路现在已经跟得上，所以下一个杠杆在传感器侧：
 - **SVGA（800x600）** 牺牲的是分辨率而非帧率——OV5640 的帧率基本由像素时钟决定。
 - **调大 `CAM_QUALITY` 的数字** 会缩小帧体积、减少字节数，但瓶颈是每秒帧数而不是
  带宽。
 - 如果要的是低延迟而不是细节，用 **QQVGA/QVGA**：DVP 总线和 PSRAM 带宽都随像素数
  线性变化。
 ## 协议测试
 `protocol/` 是最容易出现细微错误、又无法在固件上验证的部分，所以它有真正的单元测试
 并且为宿主架构编译：
 ```sh
-cd protocol && cargo test
+python3 scripts/udp_probe.py 10
 ```
 它手写了每一个协议常量，**不依赖 `protocol` crate**——正因为如此，如果 crate 的编码
 有错，脚本会立刻报出不一致。
 ## 四份文档
 | | |
 |---|---|
 | 根 `README.md` | 你在这里。拓扑、性能、构建烧录、硬件坑 |
 | `protocol/README.md` | 线路格式、帧重组的取舍、每个拒收条件 |
 | `armor/README.md` | 装甲板接线表、血量规则、上报、C3 的 RMT/ADC 踩坑 |
 | `desktop/README.md` | 两套页面、视频通道路径、两道闸门、密码模型、录制与排查 |
 ## 装甲板（已实现）
 `armor/` 是一套独立的 Rust workspace（目标 **ESP32-C3**，RISC-V）：
 - `armor-protocol` —— 规则层：血量（100 起、每击 −3）、每板独立的 50 ms 受击冷却、
  受击后**只有那一路**灯带全黑 50 ms、按键 FSM、上报编码。纯计算，主机上 22 个测试。
 - `armor-firmware` —— 固件：四路压电片 40 kHz ADC 连续采样、四路 WS2812（C3 只有一个
  RMT 通道可用，靠 `rmt_tx_switch_gpio` 轮流驱动）、NVS、BOOT 键、WiFi + UDP。
 硬件是"一主三从"：三块从板里没有 MCU，各自只有一路灯带和一路压电片，直接接线到主板。
 接线表与实现细节见 [`armor/README.md`](armor/README.md)。
 ```sh
 scripts/build_armor.sh        # 编译（WIFI_SSID/WIFI_PASS/ARMOR_TEAM 取自 .env）
 scripts/flash_armor.sh        # 编译 + 烧录 + 串口日志
 python3 scripts/armor_probe.py 15   # 不开界面，单看板子在广播什么血量
 ```
-7 passed
+
-```
+桌面端侧：`desktop/core/src/armor.rs` 的 `ArmorHealthStore` 监听 5601，按 `(team, index)`
 存最后一次读数，四条都在 1.5 s 内收到才显示——**没有数据时显示占位符而不是 0**，
 0 看起来像真值，现场看到会以为对方已经没血了。界面上的血量画在画面角上（一条分 5 格的
 平行四边形，20 点血一格），归零不写"已击毁/损毁"，而是由图传中央的「胜利 / 击败」横幅表达
 （见 [`desktop/README.md`](desktop/README.md)）；数字变化也会打进客户端日志。
 同一块板子还会被单独记下来（帧头里的 MAC 派生 id），所以两端都能列出"场上有哪几块装甲板"
 并选一块绑定——命中反馈也是从这个 id 上归位的。**这不需要改固件**：主板一直在用
 `encode_from(sender_id)` 把自己的 id 打进帧头。
@@ -0,0 +1,31 @@
 # 装甲板的目标是 ESP32-C3（RISC-V），与外层 esp32/.cargo/config.toml 的
 # Xtensa 目标互不相干。这个文件离得近，所以会覆盖外层同名键（尤其是 MCU）。
 [build]
 target = "riscv32imc-esp-espidf"
 [target.riscv32imc-esp-espidf]
 linker = "ldproxy"
 runner = "espflash flash --monitor"
 rustflags = ["--cfg", "espidf_time64"]
 [unstable]
 # `esp` 工具链只带了 host 的预编译 std，没有 esp 目标（与图传板那套一样）。
 # 所以必须自己编 std：键名是 `build-std`（连字符），写成 `build_std` 会被 cargo
 # 当成未知键静默忽略，然后在链接阶段报找不到 `core`。
 build-std = ["std", "panic_abort"]
 [env]
 MCU = "esp32c3"
 # 本机装了两套 ESP-IDF：
 #
 #   /Users/peng/.espressif/v6.0.1/esp-idf   eim 装的，工具链齐全（含 RISC-V）
 #   /Users/peng/.espressif/esp-idf/v5.5.5   只有 Xtensa 工具链（图传板在用）
 #
 # C3 是 RISC-V，所以这里指向 v6.0.1。esp-idf-sys 0.38.1 支持 6.0–6.2。
 #
 # `ESP_IDF_TOOLS_INSTALL_DIR` 刻意 `force = false`：默认 `global`（即 ~/.espressif），
 # 但如果环境里已经给了 `custom:<可写目录>`（沙箱、CI），就用环境里的那个。
 # 形状必须与外层 esp32/.cargo/config.toml 一致（都是表），否则 cargo 合并配置会报错。
 IDF_PATH = { value = "/Users/peng/.espressif/v6.0.1/esp-idf", force = true }
 ESP_IDF_TOOLS_INSTALL_DIR = { value = "global", force = false }
@@ -0,0 +1,15 @@
 # 装甲板固件（ESP32-C3）：一主三从，主板一颗 MCU，四路压电片 + 四路 WS2812 都接在它上面。
 #
 # 独立 workspace，不参与外层 esp32/ crate 的构建：两者目标芯片不同
 # （外层是 Xtensa 的 ESP32-S3 图传，这里是 RISC-V 的 ESP32-C3），各自的
 # `.cargo/config.toml` 就是这条边界的体现。
 [workspace]
 resolver = "2"
 members = ["armor-firmware", "armor-protocol"]
 [profile.release]
 opt-level = "s"
 [profile.dev]
 debug = true
 opt-level = "z"
@@ -0,0 +1,352 @@
 # 装甲板（ESP32-C3 / Rust / ESP-IDF）—— 一主三从，与裁判终端联动
 一辆车四块装甲板（前/后/左/右），**只有主板一颗 MCU**：另外三块"从"板里没有单片机，
 各自只有一路 WS2812 和一路压电片，直接接线到主板上。主板负责四路击打检测、四路灯带、
 整车血量，并把血量广播给本项目裁判终端。
 固件是跑在 ESP-IDF 上的 Rust，目标芯片 **ESP32-C3（RISC-V）**。
 ```text
 armor/
 ├── Cargo.toml            workspace：两个 crate，各自独立构建
 ├── armor-protocol/       规则层 + 线路格式（纯计算，主机上 22 个单元测试）
 ├── armor-firmware/       固件：ADC / RMT / NVS / 按键 / WiFi+UDP
 │   ├── src/leds.rs       四路 WS2812（单 RMT 通道轮流切 GPIO）
 │   ├── src/piezo.rs      四路压电片（40 kHz ADC 连续采样）
 │   ├── src/net.rs        UDP 广播 ArmorHealth
 │   ├── src/settings.rs   NVS：队伍与颜色
 │   └── sdkconfig.defaults / partitions.csv
 └── .cargo/config.toml    riscv32imc-esp-espidf + MCU=esp32c3
 ```
 **为什么拆成两个 crate。** 规则层（算不算一次受击、扣几滴血、这一刻灯该显示什么、
 按一下键算短按还是长按）是最容易写错、又最不适合"烧上去看现象"的部分 —— 压电片的
 尖峰在硬件上根本没法按需复现。放在 `armor-protocol` 里就能喂 `Duration` 假时间来测。
 固件侧只做外设接线。
 ## 接线
 | 功能 | GPIO | 说明 |
 | --- | --- | --- |
 | WS2812 前 | **IO10** | 每条灯带 3 颗灯珠，GRB、MSB first |
 | WS2812 后 | **IO5** | |
 | WS2812 左 | **IO6** | |
 | WS2812 右 | **IO7** | |
 | 压电片 前 | GPIO0（ADC1_CH0） | 0 dB 衰减、12 bit |
 | 压电片 后 | GPIO4（ADC1_CH4） | |
 | 压电片 左 | GPIO3（ADC1_CH3） | |
 | 压电片 右 | GPIO1（ADC1_CH1） | |
 | BOOT 键 | GPIO9 | 低有效，内部上拉 |
 | 调试串口 UART0 TXD | GPIO21 | 115200 8N1，日志从这里出来（主控制台） |
 | 调试串口 UART0 RXD | GPIO20 | 目前空闲，留给以后的命令通道 |
 引脚与参考实现完全一致（灯：前 10 / 后 5 / 左 6 / 右 7；压电：前 0 / 后 4 / 左 3 /
 右 1）。调试口用 UART0 而不是 USB Serial/JTAG，是为了让"RXD/TXD"这对丝印就是日志口。
 **日志同时从板上原生 USB 口出来。** `sdkconfig.defaults` 里把 USB Serial/JTAG 配成了
 **次**控制台（`CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG=y`）：主控制台仍是 UART0，
 所以"RXD/TXD 就是调试口"这条成立；而只用原生 USB 线烧录、没接 USB-TTL 的人也能看到日志，
 否则那种接法下应用日志一个字符都看不到（只有 ROM 的启动信息）。
 ## 规则
 | | 值 | 在哪 |
 | --- | --- | --- |
 | 整车血量 | 100 | `Rules::max_hp` |
 | 每次受击扣血 | 3 | `Rules::damage_per_hit` |
 | 受击后变暗 | **只有被打的那一路**全黑 50 ms，其余三路不动 | `Rules::hit_blink` + `Armor::strip` |
 | 同一板位重复判定抑制 | 50 ms | `Rules::hit_cooldown` |
 | 受击阈值 | 原始 12 bit ADC > 2000（`ARMOR_THRESHOLD` 可改） | `Rules::threshold` |
 | 血量归零 | 四路全黑，直到复位 | `Armor::strip` |
 | 正常颜色 | 队伍一红（`0xFF0000`）、队伍二蓝（`0x0000FF`） | `Rgb::for_team` |
 | 复位（新一局） | 长按 BOOT ≥500 ms → 满血、清计数 | `Button` + `Armor::reset` |
 | 打印状态 | 短按 BOOT → 立刻打一行状态并重发上报 | `ButtonEvent::Click` |
 **整车一条血量，四格同值。** 板子算账、裁判端只显示：每条上报的 `hp` 相同，
 `index` 分别是 0..3，所以裁判端已经画好的四格血量界面不用改。
 **为什么要"每板独立冷却"。** 参考实现用全局 50 ms 冷却：一块板挨打后，别块板在这
 50 ms 内的击打会被吃掉。四路各自独立才是"每面各自挨打"的正确语义，这里有单元测试
 钉住（`cooldown_is_per_plate_not_global`）。
 ## 上报（UDP）
 主板每 200 ms 广播四条 `protocol::ArmorHealth` 到 `255.255.255.255:5601`：
 ```text
 magic "MVC1"(4) | type(1)=5 | version(2) | sender_id(4) | ... | team(1) | index(1) | hp(2)
 ```
 - **血量一变立刻发**，没变就按 200 ms 心跳重发。裁判端靠心跳判断板子还在线，一次
  丢包不该让界面退回"未接入"。
 - `sender_id` 用 MAC 派生的板子 id（`protocol::id_from_mac`），不是 0 —— 0 是裁判
  终端的保留 id，抓包时一块装甲板发的包不该长得像裁判端发的。
 - 四条 `index` 的 `hp` 相同（整车一条血），裁判端按 `(team, index)` 收齐四条才显示。
 - 广播而不是单播：裁判终端的 IP 是 DHCP 给的，会变。图传板用 Hello 广播绕开这件事，
  装甲板沿用同一个约定。
 ### 裁判端怎么收
 `client/src/armor.rs` 里的 `ArmorHealthStore`（裁判端角色才启动）：
 - 绑 `0.0.0.0:5601` 收广播，按 `(team, index)` 存最后一次读数。
 - **四条都在 1.5 s 内收到**才交给界面显示；否则回退占位符。心跳 200 ms，1.5 s 是连丢
  7 个包，偶发丢包不会让四个格子各自跳。
 - 队伍端不用它（界面不显示对手血量），所以那台机器不会去占 5601。
 - 血量变化会打日志（`armor: team 0 hp 100 -> 97`）：窗口是给别人看的，抓日志的人
  也得能看见掉血。
 **裁判端界面原本看不到血量。** 协议与 `ArmorSource` 早已就位，但 Slint 里那 4 格只是
 绿/灰方块 —— `hps` 的数值从没被渲染，于是"板子被打到 0"在界面上完全看不出来（现场
 表现就是"敲死了裁判系统没掉血"）。现在 `TeamHealth` 多了一个 `hp-text` 与 `critical`：
 队伍名旁边直接显示血量数字，低于 30 或归零时数字与血条转红。归零**不写"已击毁"**——那一刻
 图传中央会给出「胜利 / 击败」的结论（见 [`desktop/README.md`](../desktop/README.md)）。
 ## 构建
 凭据与队伍号走 `.env`（与图传固件共用同一个文件）：
 ```bash
 # .env
 WIFI_SSID=your-ssid
 WIFI_PASS=your-password
 ARMOR_TEAM=0            # 0 = 队伍一（红），1 = 队伍二（蓝）
 ARMOR_THRESHOLD=2000    # 受击阈值（原始 12 bit ADC），看日志里的 peak 来定
 scripts/build_armor.sh                          # 编译
 ARMOR_TEAM=1 scripts/build_armor.sh             # 临时当队伍二编译
 ARMOR_THRESHOLD=1200 scripts/build_armor.sh     # 换受击阈值（看日志里的 peak 来定）
 ```
 产物：`armor/target/riscv32imc-esp-espidf/release/armor`。
 `ARMOR_TEAM` 是**编译期**注入的：换队伍重刷固件即可，不用先擦 NVS。NVS 里另外记着
 `team` 与 `color`（命名空间 `armor`，与参考实现同名），两者不一致时以 `ARMOR_TEAM`
 为准并覆盖，日志里会说一声。
 本机已有的 ESP-IDF 与工具链通过 `armor/.cargo/config.toml` 指定（`IDF_PATH` /
 `ESP_IDF_TOOLS_INSTALL_DIR`），不需要先 `activate` ESP-IDF。删掉那两行就交给
 esp-idf-sys 自己下载它钉住的版本。
 ### 用的是 ESP-IDF v6.0.1，不是图传板那套 v5.5.5
 这台机器上有两套 ESP-IDF：
 | | 路径 | 工具链 |
 | --- | --- | --- |
 | v6.0.1（eim 装的） | `/Users/peng/.espressif/v6.0.1/esp-idf` | Xtensa + **RISC-V（`esp-15.2.0_20251204`）** |
 | v5.5.5（图传板在用） | `/Users/peng/.espressif/esp-idf/v5.5.5` | 只有 Xtensa |
 C3 是 **RISC-V**，而 v5.5.5 那套缺 `riscv32-esp-elf`（它要的是 `esp-14.2.0_20260121`，
 本机没有，而 GitHub release 又下不动）。所以装甲板固件指向 v6.0.1 —— 它的工具链齐全，
 且 `esp-idf-sys` 0.38.1 支持的版本范围是 4.4.4+、5.0–5.5、**6.0–6.2**。
 两套 IDF 共存没有冲突：各自 `.cargo/config.toml` 里的 `IDF_PATH` 是每套 crate 自己钉的。
 `ESP_IDF_TOOLS_INSTALL_DIR` 默认 `global`（即 `~/.espressif`，工具所在处），但**没有**加
 `force`：沙箱或 CI 里可以用 `ESP_IDF_TOOLS_INSTALL_DIR=custom:<可写目录>` 覆盖（工具目录
 不可写时把 `tools/` 软链到已装好的工具即可，Python venv 会建在那个可写目录里）。
 ### 主机侧测试
 规则层在 PC 上跑，不需要板子：
 ```bash
 cd armor/armor-protocol && cargo test    # 22 个测试
 cd protocol && cargo test                # 线路格式往返（含 ArmorHealth）
 ```
 （`armor-protocol/.cargo/config.toml` 把 target 覆盖回 host：它坐在 `armor/` 目录树
 里，否则会继承 RISC-V 目标，链接必然失败。这与 `protocol/`、`client/` 的做法一致。）
 ## 烧录与实测
 ```bash
 scripts/flash_armor.sh                    # 自动找串口，烧完看 20 秒日志
 ESP_PORT=/dev/cu.usbmodem1101 scripts/flash_armor.sh
 scripts/flash_armor.sh --monitor 60       # 看 60 秒
 scripts/flash_armor.sh --no-monitor       # 只烧不抓
 ```
 烧的是 ELF（`espflash` 自己从 ELF 里读分区表与 bootloader），芯片 `esp32c3`。
 不打开裁判端界面，也可以单独确认板子在广播、血量对不对：
 ```bash
 python3 scripts/armor_probe.py 15
 ```
 它手写协议常量（不依赖 Rust 侧代码），所以是线路格式的**独立**检查：如果固件编码写错，
 这个脚本会立刻报不一致。
 ### 串口日志长什么样（实机抓的）
 ```text
 I (321) armor: pins: ws2812 front=IO10 rear=IO5 left=IO6 right=IO7
 I (321) armor: pins: piezo  front=GPIO0 rear=GPIO4 left=GPIO3 right=GPIO1
 I (4864) esp_netif_handlers: sta ip: 192.168.1.117, mask: 255.255.255.0, gw: 192.168.1.1
 I (5034) armor: joined "SR-602-2G4" on 192.168.1.117
 I (5034) armor::net: reporting to 255.255.255.255:5601 over UDP
 I (5034) armor::net: this board's id is 0xA820D321, from MAC [98, A3, 16, 4C, 67, C8]
 I (6044) armor: status: hp=100 hits=0 dead=false plates[front=0 rear=0 left=0 right=0]
        peak[front=490 rear=395 left=456 right=475] thr=2000
        strips[front=#FF0000 rear=#FF0000 left=#FF0000 right=#FF0000]
        ap=SR-602-2G4 rssi=-36 ch=6 ip=192.168.1.117 reports=5 errs=0
 I (63104) armor: hit plate=front raw=4095 hp=1 (hits=33)
 I (63314) armor: hit plate=front raw=4095 hp=0 (hits=34)
 W (63314) armor: hp reached 0: all four strips stay dark until the next reset
 W (306504) armor: BOOT long press: hp reset to 100 (new round)
 ```
 （日志里的长行是这里折行显示的，实机是一行。）
 ## 实测（2026-10-14，ESP32-C3 devkit，MAC `98:a3:16:4c:67:c8`）
 | 项 | 结果 |
 | --- | --- |
 | 编译 | `cargo build --release` 通过；text 1,081,093 B，app 镜像 **1,082,848 B**，占 4 MB flash 的 26% |
 | 启动 | 无 panic/重启；状态行每秒一条 |
 | WiFi | 关联 `SR-602-2G4`（rssi −36，ch 6），DHCP 拿到 `192.168.1.117` |
 | 上报 | `scripts/armor_probe.py` 收到队伍一四条、约 5 包/秒、`sender_id 0xA820D321`、四格同值 |
 | 裁判端 | `cam-client --role referee` 日志 `team 0 plate 0..3 is online (hp 100) via 192.168.1.117`，界面显示血量数字 |
 | 受击 | 敲前装甲板：`hit plate=front raw=2663..4095`，每次 −3（100→97→94…），只有 front 计数 |
 | 变暗 | 敲击瞬间**只有前那一路**全黑 50 ms，其余不变（现场确认） |
 | 死亡 | 34 击到 0；状态行 `dead=true strips[front=off rear=off left=off right=off]`，四路全黑 |
 | 复位 | BOOT 长按 → 板子 `reset to 100`，裁判端日志 `armor: team 0 hp 0 -> 100` |
 | 底噪 | 未敲击时四路 peak 约 380–510，阈值 2000 有明显余量 |
 | 未接线 | 后/左/右三路压电片与灯带本次未接（用户说明），代码按四路齐全写 |
 ### 裁判端这边踩到的坑：界面根本不显示血量
 协议、`ArmorSource`、`ArmorHealthStore` 都对，但改之前 Slint 里那 4 格只是绿/灰方块，
 `hps` 的**数值从不渲染**——板子被打到 0，界面四格还是绿的，看起来像"没掉血"。现在
 队伍名旁边直接显示数字（低于 30 转红，归零不写"已击毁"，改由图传中央的胜负横幅表达），
 并且客户端日志会打 `armor: team 0 hp 100 -> 97`。
 ## 实现要点（都是踩过的坑）
 ### 1. ESP32-C3 的 RMT 只有 96 个 symbol 的通道内存
 C3 的 RMT 只有一个 block，总计 96 个 symbol，按 48 为单位分给两个 TX 通道。`mem_block_symbols = 64`
 会被向上取整到 96，也就是一个通道吃光全部内存，第二个 `rmt_new_tx_channel()` 就会失败：
 ```text
 E rmt: rmt_tx_register_to_group(168): no free tx channels
 ```
 四条灯带不可能各占一个通道（只有 2 个 TX 通道）。所以这里只建**一个**通道、让它独占
 96 个 symbol（一帧 = 3 珠 × 24 bit + reset = 73 个 symbol，装得下），再用
 `rmt_tx_switch_gpio()` 依次切到四个 GPIO 上发送；每路约 90 µs。
 **为什么不用 `esp-idf-hal` 的 `TxChannelDriver`。** 它把 `rmt_channel_handle_t` 藏在
 结构体里（`as_ptr()` 是 `pub(crate)`），拿不到句柄就调不了 `rmt_tx_switch_gpio()`。
 所以 `leds.rs` 直接用 sys 绑定：通道、官方 copy encoder、transmit 都是 IDF 原生的那
 几个函数，用法与参考实现的 `led_strip_encoder.c` 一一对应。
 **每路内容没变就不重发。** 参考实现里四条灯带永远同色，所以每 10 ms 无条件刷四遍；
 这里四路颜色独立（被打的那一路要单独变暗），于是只在内容变化时才走
 `disable → switch → enable → transmit`，另外每秒强制全刷一次（掉电、静电都可能让
 某条灯带丢帧，缓存不能当真相）。
 ### 2. 压电片必须连续（DMA）采样
 一次击打的波形只有几十微秒宽，oneshot 轮询几乎必然从尖峰旁边擦过去，表现就是"敲得响
 才算"。这里与参考实现一致：四通道合计 40 kHz（每通道 10 kHz），一帧 10 ms = 400 个
 采样点，一帧就是主循环的节拍。
 `esp-idf-hal` 0.47 的 `adc::continuous` 多通道入口 `EmptyAdcChannels::chain` 的约束是
 `A: Adc` 且 `O: AdcChannels<AdcUnit = A>`：`ADC1` 满足前者、`ADCU1` 满足后者，同一个
 类型参数凑不齐，四路 ADC1 通道拼不出来。所以 `piezo.rs` 同样直接用 sys 绑定，与参考
 实现逐行对应。
 采样点的通道号由硬件结果自带（`type2.channel()`），映射不依赖"结果按 pattern 顺序
 轮转"这个假设。
 ### 3. 一次击打会被算成几十次
 40 kHz 下，压电片一次击打会连续几十个采样点过阈值。**去抖不在采样层做**，而是
 `Armor::on_sample` 的冷却窗口把它收敛成一次受击 —— 这样"算不算受击"这条规则可以在
 主机上测（`repeat_samples_inside_the_cooldown_are_one_hit`）。
 ### 4. 控制台放在 UART0
 `sdkconfig.defaults` 里显式写了 `CONFIG_ESP_CONSOLE_UART_DEFAULT=y`：C3 的 ROM 默认
 控制台就是 UART0，引脚正好是 RXD=GPIO20 / TXD=GPIO21，与要求一致。换成 USB
 Serial/JTAG 输出只要把这一行换成 `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG`。
 ### 5. 应用分区给 2 MB
 默认的 1 MB 单 app 槽对带 WiFi 的 Rust 固件太紧，`partitions.csv` 按参考实现给
 factory 划了 2 MB。
 ### 6. WiFi 省电关掉
 省电模式下上报会晚一个信标间隔（上百毫秒），而"受击后 50 ms 变暗"本来就是要给人即时
 反馈的。板子是车载供电，这点电流不值得换不确定性。另外主循环里每 5 s 检查一次连接，
 断了就重连 —— 一块静默失联的装甲板在场上是最难查的故障。
 ### 7. 判断"连上没有"要问 IDF，不要信 esp-idf-svc 的事件缓存
 `BlockingWifi::is_connected()/is_up()/wait_netif_up()` 读的是 esp-idf-svc 自己维护的
 WiFi 事件状态。实测在 **IDF v6.0.1 + esp-idf-svc 0.53** 上它会停在"已连接"：日志说
 一切正常、`get_ip_info()` 却是 `0.0.0.0`，而 IDF 的 `esp_wifi_sta_get_ap_info()` 明明
 说没关联。后果是 `join()` 假装连上了、看门狗永远不会重试，板子静默失联。
 所以固件里一律用 IDF 的 API 判断：
 - 关联：`esp_wifi_sta_get_ap_info()`
 - 地址：`esp_netif_get_handle_from_ifkey("WIFI_STA_DEF")` + `esp_netif_get_ip_info()`
 而且 **WiFi 是尽力而为**：`join()` 失败只警告、不退出。一块因为没网就不亮灯的装甲板，
 比"裁判端看不到血量"糟糕得多。看门狗每 5 s 检查一次"关联 + 有 IP"，不满足就断开重连
 （重连时只等 3 s IP，别让主循环错过受击）。
 ### 8. 日志里"有没有连上"要说清楚
 状态行长这样：
 ```text
 status: hp=0 hits=37 dead=true plates[front=37 rear=0 left=0 right=0]
        peak[front=504 rear=379 left=459 right=486] thr=2000
        strips[front=off rear=off left=off right=off]
        ap=SR-602-2G4 rssi=-29 ch=6 ip=192.168.1.117 reports=1745 errs=0
 ```
 - `peak[...]` 是**这一秒内每路 ADC 的峰值**，用来校准阈值：没敲时的底噪要明显低于
  阈值，正常敲击要明显高于它（实测底噪 ~400–500，敲击 2000–4095）。只报"有没有过阈值"
  没法判断阈值该调到哪。
 - `thr=` 是当前阈值，`ARMOR_THRESHOLD=1200 scripts/build_armor.sh` 可以改。
 - `ap=` / `ip=` / `reports=` 一眼分清"板子没连上"和"包发出去了但对端没显示"。
 ### 9. USB 控制台看不到复位后的头两秒
 主控制台是 UART0，另外把 USB Serial/JTAG 配成了次控制台，所以插原生 USB 也能看日志。
 但复位时 USB 会重新枚举，**复位后最初约 1–2 秒的日志会丢**（我们实测错过过启动横幅）。
 要看完整启动过程就用 UART0 那对脚接 USB-TTL——那才是设计中的调试口。
 ## 与参考实现（`reference/armor`）的差异
 | | 参考实现 | 这里 | 为什么 |
 | --- | --- | --- | --- |
 | 主从链路 | ESP-NOW 配对，两块板对拷 | 无：三块从板只是直接接线的灯与传感器 | 按实际硬件（只有主板一颗 MCU） |
 | DBUS 透传 | UART0 收发 10 字节 DBUS，USB CDC 打 CSV | 不做 | 这套硬件没有 DBUS 需求；UART0 让给日志 |
 | 受击变暗 | 四条灯带一起全黑 50 ms | 只暗被打的那一路 | 每面独立灯带的意义就在这里 |
 | 冷却窗口 | 全局 50 ms | 每板独立 50 ms | 别块板的击打不该被吃掉 |
 | 灯带刷新 | 每 10 ms 无条件刷四遍 | 只在内容变化时刷 + 每秒强制全刷 | 四路独立控制后，省掉四轮 RMT 开销 |
 | 血量 | 只有击打计数，无血量 | 整车 100 血、每击 −3、0 血全黑，按 `ArmorHealth` 上报 | 与裁判端已画好的四格血量对齐 |
 | 颜色切换 | BOOT 短按切红/蓝，存 NVS | 颜色由 `ARMOR_TEAM` 决定（红/蓝），短按打状态 | 队别不该靠现场按键切错 |
 | 按键 | 移植 OneButton 状态机（短按配对，长按切色） | 本地 FSM：长按复位血量、短按打状态 | 只有两种动作，且要能在主机上测 |
 | 上报 sender_id | —（不走 UDP） | MAC 派生 id | 0 是裁判终端保留 id |
 ## 还没做的
 - **另外三路（后/左/右）的压电片与灯带还没接**（2026-10-14 实机只有前一路）。
  代码按四路齐全写，接线后无需改代码；但"四路同时受击"、"每路独立变暗"这两件事
  还没在实板上验证过。
 - **UART0 RX（GPIO20）上的命令通道**：日志方向已经能用；反向的 `status` / `reset`
  命令还没接（当前复位走 BOOT 长按）。
 - **从板加 MCU 的方案**：如果以后从板也装单片机（走 UART 或无线回传），
  `armor-protocol` 里已经预留了板位枚举与上报格式，加一个 `slave` bin 即可。
 - **双击 / 多击**：`Button` 只实现短按与长按，参考实现里未使用的 OneButton 功能没有移植。
 - **下发血量**：当前板子本地算账（裁判端只显示）。若以后要裁判端权威（下发血量/复位），
  需要新增一条下行消息并在 `client` 里发。
@@ -0,0 +1,26 @@
 [package]
 name = "armor-firmware"
 version = "0.1.0"
 edition = "2021"
 resolver = "2"
 rust-version = "1.82"
 # 一个 bin：主板固件。三块"从"装甲板里没有 MCU，只有一路 WS2812 + 一路压电片
 # 直接接在主板 GPIO 上，所以没有第二份固件可烧（见 armor/README.md）。
 [[bin]]
 name = "armor"
 path = "src/main.rs"
 harness = false # 不在固件里跑主机测试框架；规则层的测试在 armor-protocol
 [dependencies]
 log = "0.4"
 anyhow = "1"
 embedded-svc = "0.29"
 esp-idf-svc = "0.53"
 # 规则层 + 线路格式：血量、去抖、按键、灯带输出，以及上报给裁判终端的
 # `protocol::ArmorHealth`（armor-protocol 再导出）。规则层能在主机上单测。
 armor-protocol = { path = "../armor-protocol" }
 [build-dependencies]
 embuild = "0.33.5"
@@ -0,0 +1,3 @@
 fn main() {
    embuild::espidf::sysenv::output();
 }
@@ -0,0 +1,10 @@
 # 装甲板固件（4 MB flash）的自定义分区表。
 #
 # nvs      : 颜色 / 队伍等应用设置，外加 WiFi 校准数据
 # phy_init : 射频校准数据
 # factory  : 唯一的分区镜像（2 MB 余量；固件实测不到 1 MB，但默认的 1 MB 单 app
 #            槽对带 WiFi 的固件太紧）
 # Name,   Type, SubType, Offset,  Size,     Flags
 nvs,      data, nvs,     0x9000,  0x6000,
 phy_init, data, phy,     0xf000,  0x1000,
 factory,  app,  factory, 0x10000, 0x200000,
@@ -0,0 +1,29 @@
 # 装甲板固件（ESP32-C3）的默认配置。
 #
 # CONFIG_IDF_TARGET 必须显式写出来：本机装的是通用 ESP-IDF，默认目标是 ESP32，
 # 不写这一行会按 ESP32 去配 ADC/RMT 通道，编译期就报"没有这个外设"。
 #
 # 串口调试走 UART0（RXD = GPIO20 / TXD = GPIO21，115200 8N1）——这是 C3 的 ROM
 # 默认控制台引脚，和参考固件里给 DBUS 用的那两个脚是同一对。想改成 USB
 # Serial/JTAG 输出，把 CONFIG_ESP_CONSOLE_UART_DEFAULT 换成
 # CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG 即可。
 CONFIG_IDF_TARGET="esp32c3"
 # 4 MB flash；应用分区放到 2 MB（见 partitions.csv），默认的 1 MB 单 app 槽对
 # WiFi + 日志的 Rust 固件太紧。
 CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
 CONFIG_PARTITION_TABLE_CUSTOM=y
 # 调试口 = UART0（GPIO20 RX / GPIO21 TX）。
 #
 # 同时打开 USB Serial/JTAG 作为**次**控制台：日志会同时从板上那个原生 USB 口出来。
 # 这样现场两种接法都能看到日志 —— 接了 USB-TTL 到 RXD/TXD 的看 UART0，直接插板上
 # USB 口的看 USB。主控制台仍是 UART0，所以"RXD/TXD 就是调试口"这条成立。
 #
 # 只用原生 USB 口烧录（不接 USB-TTL）时，这一条是能看见日志的唯一办法。
 CONFIG_ESP_CONSOLE_UART_DEFAULT=y
 CONFIG_ESP_CONSOLE_SECONDARY_USB_SERIAL_JTAG=y
 # Rust 的 main 与规则层在同一个任务栈上跑，另外 log 会用到一些栈；默认 3.5 KB
 # 在带 WiFi 的固件里容易爆栈。
 CONFIG_ESP_MAIN_TASK_STACK_SIZE=8192
@@ -0,0 +1,27 @@
 //! 把 IDF 的 `esp_err_t` 返回值变成可读的 `anyhow::Error`。
 //!
 //! 固件里到处都要判 `ESP_OK` 并把错误码翻译成人能看懂的名字；不翻译的话现场只会
 //! 看到 `0x105`，而 IDF 的错误码表并不在脑子里。
 use anyhow::{anyhow, Result};
 use esp_idf_svc::sys as ffi;
 /// `ESP_OK` 之外的返回值转成 `Err`，`what` 是出错的那一步的名字。
 pub fn check(what: &str, rc: ffi::esp_err_t) -> Result<()> {
    if rc == ffi::ESP_OK {
        return Ok(());
    }
    Err(anyhow!("{what} failed: {} (0x{rc:x})", name(rc)))
 }
 /// 错误码的名字，例如 `ESP_ERR_INVALID_ARG`。
 #[must_use]
 pub fn name(rc: ffi::esp_err_t) -> String {
    // SAFETY: esp_err_to_name 对任意 esp_err_t 都返回一个静态 C 字符串。
    unsafe {
        core::ffi::CStr::from_ptr(ffi::esp_err_to_name(rc))
            .to_string_lossy()
            .into_owned()
    }
 }
@@ -0,0 +1,312 @@
 //! 四路 WS2812 灯带：一个 RMT TX 通道 + 官方 copy encoder，靠切 GPIO 轮流驱动。
 //!
 //! # 为什么不用 `esp-idf-hal` 的 `TxChannelDriver`
 //!
 //! 它把 `rmt_channel_handle_t` 藏在结构体里（`as_ptr()` 是 `pub(crate)`），而
 //! "一个通道依次驱动四路灯带"必须用 `rmt_tx_switch_gpio()` 换脚。ESP32-C3 的 RMT
 //! 只有 **2 个 TX 通道**，四路灯带不可能各占一个，所以这里直接用 `esp-idf-svc` 的
 //! sys 绑定：通道、encoder、transmit 都是 IDF 原生的那几个函数，用法与参考实现的
 //! `led_strip_encoder.c` 一一对应。
 //!
 //! # ESP32-C3 的 RMT 内存限制（照抄参考实现的踩坑记录）
 //!
 //! C3 的 RMT 只有一个 block，总计 **96 个 symbol 的通道内存**，按
 //! `SOC_RMT_MEM_WORDS_PER_CHANNEL = 48` 为单位分配。`mem_block_symbols = 64` 会被
 //! 向上取整到 96，也就是一个通道吃光全部内存，第二个 `rmt_new_tx_channel()` 会以
 //! `no free tx channels` 失败：
 //!
 //! ```text
 //! E rmt: rmt_tx_register_to_group(168): no free tx channels
 //! ```
 //!
 //! 所以这里只建**一个**通道、让它独占 96 个 symbol（一帧 = 3 珠 × 24 bit + reset
 //! = 73 个 symbol，装得下），再用 `rmt_tx_switch_gpio()` 依次切到四个 GPIO 上发送。
 //! 每路约 90 µs，10 ms 周期里的开销可以忽略。
 //!
 //! # 与参考实现的差异
 //!
 //! 参考实现里四条灯带永远同色，所以每 10 ms 无条件刷四遍。这里四路颜色各自独立
 //! （被打的那一路要单独变暗），于是：
 //!
 //! - 内容没变的路不发（`refresh` 里比较上一次的 [`Strip`]），省掉每次
 //!   `disable → switch → enable → transmit` 的四轮开销；
 //! - 每秒仍强制全刷一次：灯带可能因为上电次序、掉电、静电而丢帧，缓存不能当真相。
 use core::ffi::c_void;
 use core::time::Duration;
 use anyhow::Result;
 use esp_idf_svc::hal::rmt::{PinState, Pulse, Symbol};
 use esp_idf_svc::hal::units::Hertz;
 use esp_idf_svc::sys as ffi;
 use log::{info, warn};
 use armor_protocol::{Plate, Rgb, Strip};
 use crate::esp;
 /// RMT 计时分辨率：10 MHz，即 1 tick = 0.1 µs。
 const RMT_RESOLUTION_HZ: u32 = 10_000_000;
 /// 每条灯带 3 颗灯珠（与参考实现一致）。
 const LEDS_PER_STRIP: usize = 3;
 /// 一帧的符号数：24 bit/珠 × 3 珠 + 1 个 reset 符号。
 const FRAME_SYMBOLS: usize = LEDS_PER_STRIP * 24 + 1;
 /// 独占 C3 全部 RMT 通道内存，只建一个通道（见模块文档）。
 const MEM_BLOCK_SYMBOLS: usize = 96;
 /// WS2812 的位时序：T0H / T0L / T1H / T1L。
 const T0H_NS: u64 = 300;
 const T0L_NS: u64 = 900;
 const T1H_NS: u64 = 900;
 const T1L_NS: u64 = 300;
 /// 帧尾低电平时长；WS2812 要 >50 µs 才锁存。
 const RESET_US: u64 = 50;
 /// 灯带数据脚（GPIO 号，按 [`Plate`] 的 index 排列）：前 10 / 后 5 / 左 6 / 右 7。
 const STRIP_GPIO: [i32; 4] = [10, 5, 6, 7];
 /// `rmt_tx_wait_all_done` 的超时（毫秒）。一帧只要 ~90 µs，1 s 是"卡死就报错"的量级。
 const TX_TIMEOUT_MS: i32 = 1000;
 /// 强制全刷的周期：缓存不可信（掉电、静电都可能让灯带丢帧）。
 const FULL_REFRESH_MS: u64 = 1000;
 /// 四路 WS2812。
 pub struct Leds {
    channel: ffi::rmt_channel_handle_t,
    encoder: ffi::rmt_encoder_handle_t,
    /// 通道当前是否处于 enable 状态；切 GPIO 只能在 INIT 状态下做。
    enabled: bool,
    bit0: Symbol,
    bit1: Symbol,
    reset: Symbol,
    /// 每路的预编码帧。放在 `Box` 里：`rmt_transmit` 只借用指针，堆上的地址不会
    /// 因为结构体搬动而失效。
    frames: Box<[[ffi::rmt_symbol_word_t; FRAME_SYMBOLS]; 4]>,
    /// 上一次真正发出去的内容，用来跳过没变化的刷新。
    current: [Option<Strip>; 4],
    last_full_refresh_ms: u64,
 }
 impl Leds {
    /// 建通道与 encoder，把四路灯带全刷成黑色（上电先灭）。
    pub fn new() -> Result<Self> {
        let mut config = ffi::rmt_tx_channel_config_t::default();
        // 先落在前装甲板那一路；其余三路靠 switch_gpio 换过去。
        config.gpio_num = STRIP_GPIO[Plate::Front.index() as usize] as _;
        config.clk_src = ffi::soc_periph_rmt_clk_src_t_RMT_CLK_SRC_DEFAULT;
        config.resolution_hz = RMT_RESOLUTION_HZ;
        config.mem_block_symbols = MEM_BLOCK_SYMBOLS;
        config.trans_queue_depth = 4;
        let mut channel: ffi::rmt_channel_handle_t = core::ptr::null_mut();
        esp::check(
            "rmt_new_tx_channel",
            // SAFETY: config 与 channel 都是本函数的局部量，调用期间有效。
            unsafe { ffi::rmt_new_tx_channel(&config, &mut channel) },
        )?;
        let mut encoder: ffi::rmt_encoder_handle_t = core::ptr::null_mut();
        let copy_config = ffi::rmt_copy_encoder_config_t::default();
        if let Err(err) = esp::check(
            "rmt_new_copy_encoder",
            // SAFETY: 同上，copy encoder 只是把用户给的 symbol 原样搬进硬件。
            unsafe { ffi::rmt_new_copy_encoder(&copy_config, &mut encoder) },
        ) {
            // SAFETY: 通道刚建好且未使用，可以直接删。
            unsafe { ffi::rmt_del_channel(channel) };
            return Err(err);
        }
        let resolution = Hertz(RMT_RESOLUTION_HZ);
        let bit0 = Symbol::new_with(
            resolution,
            PinState::High,
            Duration::from_nanos(T0H_NS),
            PinState::Low,
            Duration::from_nanos(T0L_NS),
        )?;
        let bit1 = Symbol::new_with(
            resolution,
            PinState::High,
            Duration::from_nanos(T1H_NS),
            PinState::Low,
            Duration::from_nanos(T1L_NS),
        )?;
        let reset_low =
            Pulse::new_with_duration(resolution, PinState::Low, Duration::from_micros(RESET_US))?;
        // reset = 一整段（两半都是低电平）的符号。
        let reset = Symbol::new(reset_low, reset_low);
        // `rmt_symbol_word_t` 是 union，bindgen 不给它 `Default`，只能自己写一个全零符号。
        let blank = ffi::rmt_symbol_word_t { val: 0 };
        let mut leds = Self {
            channel,
            encoder,
            enabled: false,
            bit0,
            bit1,
            reset,
            frames: Box::new([[blank; FRAME_SYMBOLS]; 4]),
            current: [None; 4],
            last_full_refresh_ms: 0,
        };
        info!(
            "ws2812: 1 RMT channel x {MEM_BLOCK_SYMBOLS} symbols, {LEDS_PER_STRIP} leds/strip on GPIO {:?}",
            STRIP_GPIO
        );
        // 上电先灭：不知道灯带上一次显示的是什么。
        for plate in Plate::ALL {
            leds.write(plate, Strip::Black)?;
        }
        Ok(leds)
    }
    /// 把预编码的帧发到指定那一路。
    fn write(&mut self, plate: Plate, strip: Strip) -> Result<()> {
        let slot = plate.index() as usize;
        self.encode(slot, strip.color());
        // 切 GPIO 只能在 INIT 状态下做，所以先 disable。
        if self.enabled {
            esp::check("rmt_disable", unsafe { ffi::rmt_disable(self.channel) })?;
            self.enabled = false;
        }
        esp::check(
            "rmt_tx_switch_gpio",
            // SAFETY: 通道处于 INIT 状态；gpio 是 C3 上的合法输出脚。
            unsafe { ffi::rmt_tx_switch_gpio(self.channel, STRIP_GPIO[slot] as _, false) },
        )?;
        esp::check("rmt_enable", unsafe { ffi::rmt_enable(self.channel) })?;
        self.enabled = true;
        let tx_config = ffi::rmt_transmit_config_t {
            loop_count: 0, // 不循环
            ..Default::default()
        };
        esp::check(
            "rmt_transmit",
            // SAFETY: frames[slot] 在 Box 上，地址稳定；调用期间不会被移动。
            unsafe {
                ffi::rmt_transmit(
                    self.channel,
                    self.encoder,
                    self.frames[slot].as_ptr() as *const c_void,
                    core::mem::size_of_val(&self.frames[slot]),
                    &tx_config,
                )
            },
        )?;
        esp::check(
            "rmt_tx_wait_all_done",
            // SAFETY: 纯等待，超时给 1 s。
            unsafe { ffi::rmt_tx_wait_all_done(self.channel, TX_TIMEOUT_MS) },
        )?;
        self.current[slot] = Some(strip);
        Ok(())
    }
    /// 把 `rgb` 编成一条灯带的整帧（GRB、MSB first，3 珠同色）。
    fn encode(&mut self, slot: usize, rgb: Rgb) {
        let grb = rgb.to_grb();
        let frame = &mut self.frames[slot];
        // 一颗灯珠的 24 个符号只算一遍，再复制给另外两颗 —— 四条灯带都是 3 珠，
        // 中间那两步没必要重复算。
        let mut one_led = [ffi::rmt_symbol_word_t { val: 0 }; 24];
        for (byte_index, byte) in grb.iter().enumerate() {
            for bit in 0..8 {
                let symbol = if (byte >> (7 - bit)) & 1 == 1 {
                    self.bit1
                } else {
                    self.bit0
                };
                one_led[byte_index * 8 + bit] = symbol.into();
            }
        }
        for led in 0..LEDS_PER_STRIP {
            frame[led * 24..(led + 1) * 24].copy_from_slice(&one_led);
        }
        // 帧尾：>50 µs 低电平，灯带才会锁存这一帧。
        frame[FRAME_SYMBOLS - 1] = self.reset.into();
    }
    /// 按 [`Plate`] 的 index 刷四路灯带。
    ///
    /// 内容与上一次相同的路直接跳过（除非到了每秒一次的强制全刷），所以稳态下
    /// 这个函数几乎不花时间。
    pub fn refresh(&mut self, strips: [Strip; 4], now_ms: u64) -> Result<()> {
        let full = now_ms.saturating_sub(self.last_full_refresh_ms) >= FULL_REFRESH_MS;
        for plate in Plate::ALL {
            let strip = strips[plate.index() as usize];
            if !full && self.current[plate.index() as usize] == Some(strip) {
                continue;
            }
            self.write(plate, strip)?;
        }
        if full {
            self.last_full_refresh_ms = now_ms;
        }
        Ok(())
    }
 }
 impl Drop for Leds {
    fn drop(&mut self) {
        // 固件里 main 永不返回，这段只在异常路径（比如 new() 之后的早期返回）跑到。
        unsafe {
            if self.enabled {
                ffi::rmt_disable(self.channel);
            }
            if !self.encoder.is_null() {
                ffi::rmt_del_encoder(self.encoder);
            }
            if !self.channel.is_null() {
                ffi::rmt_del_channel(self.channel);
            }
        }
    }
 }
 /// 供 main 打印一次用：把四路输出拼成一行，便于对照。
 pub fn describe(strips: [Strip; 4]) -> String {
    Plate::ALL
        .iter()
        .map(|plate| {
            let strip = strips[plate.index() as usize];
            let text = if strip.is_black() {
                "off".to_string()
            } else {
                format!("#{:06X}", strip.color().to_u32())
            };
            format!("{}={text}", plate.name())
        })
        .collect::<Vec<_>>()
        .join(" ")
 }
 /// 记一次刷新失败：诊断信息比重启有用，现场灯带接错线也不该把固件打挂。
 pub fn log_failure(err: &anyhow::Error) {
    warn!("ws2812 refresh failed: {err:#}");
 }
@@ -0,0 +1,556 @@
 //! 装甲板主板固件（ESP32-C3）：一主三从，与裁判终端联动。
 //!
 //! # 这套硬件是什么
 //!
 //! 一辆车四块装甲板（前/后/左/右），但只有**主板一颗 MCU**：另外三块"从"板里没有
 //! 单片机，各自只有一路 WS2812 和一路压电片，直接接线到主板上。所以这份固件同时管
 //! 四路输入与四路输出：
 //!
 //! ```text
 //!   压电片 前/后/左/右 ──ADC──┐
 //!                            ├──► armor-protocol（血量 / 去抖 / 灯色）
 //!   BOOT 键 ──────── GPIO9 ──┘             │
 //!                                          ├──► WS2812 前/后/左/右
 //!                                          └──► UDP 广播 ──► 裁判终端 :5601
 //! ```
 //!
 //! # 规则（见 `armor-protocol`，那里有单元测试）
 //!
 //! - 整车一条血量：100 起，每次受击 −3，减到 0 不变负；0 血四路全黑。
 //! - 受击时**只有被打的那一路**灯带全黑 50 ms，其余三路不动。
 //! - 颜色由队伍决定：队伍一红、队伍二蓝；`ARMOR_TEAM` 编译期注入。
 //! - 血量账在板子上算，按 `protocol::ArmorHealth` 广播给本项目裁判终端。
 //!
 //! # 构建与烧录
 //!
 //! ```text
 //! scripts/build_armor.sh                 # 用 .env 里的 WIFI_SSID/WIFI_PASS/ARMOR_TEAM
 //! scripts/flash_armor.sh                 # 编译 + espflash + 串口日志
 //! ```
 //!
 //! 串口调试走 UART0：RXD = GPIO20 / TXD = GPIO21，115200 8N1（日志从 TX 出来，
 //! RX 目前空闲，留给以后加命令通道）。USB Serial/JTAG 配成了次控制台，所以插原生
 //! USB 口也能看到同一份日志。完整接线表、协议与踩坑见 `armor/README.md`。
 use std::time::Duration;
 use anyhow::{anyhow, Result};
 use embedded_svc::wifi::{AuthMethod, ClientConfiguration, Configuration, PmfConfiguration};
 use esp_idf_svc::eventloop::EspSystemEventLoop;
 use esp_idf_svc::hal::gpio::{PinDriver, Pull};
 use esp_idf_svc::hal::peripherals::Peripherals;
 use esp_idf_svc::nvs::EspDefaultNvsPartition;
 use esp_idf_svc::wifi::{BlockingWifi, EspWifi};
 use log::{error, info, warn};
 use armor_protocol::{Armor, Button, ButtonEvent, Plate, ReportSchedule, Rules, TEAM_2};
 mod esp;
 mod leds;
 mod net;
 mod piezo;
 mod settings;
 /// WiFi 账号来自 .env（构建期注入，固件里不留密码）。
 const SSID: &str = env!("WIFI_SSID");
 const PASSWORD: &str = env!("WIFI_PASS");
 /// 编译期注入的队伍号：`0` = 队伍一（红），`1` = 队伍二（蓝）。不写就是队伍一。
 const TEAM_ENV: &str = match option_env!("ARMOR_TEAM") {
    Some(value) => value,
    None => "0",
 };
 /// 受击阈值（原始 12 bit ADC）。参考实现用 2000，但压电片的幅度取决于贴装、线长
 /// 与有没有放大级，所以这里留一个编译期入口：`ARMOR_THRESHOLD=1200`。
 ///
 /// 怎么定这个值：看串口 status 行里的 `peak[...]`。没敲时的底噪要明显低于阈值，
 /// 正常敲击要明显高于它。
 const THRESHOLD_ENV: &str = match option_env!("ARMOR_THRESHOLD") {
    Some(value) => value,
    None => "2000",
 };
 /// 血量不变时的重发周期。裁判端靠它判断板子还在线 —— 一次丢包不该让界面变回
 /// "装甲板未接入"。
 const REPORT_HEARTBEAT_MS: u64 = 200;
 /// 状态行的打印周期（UART 调试口）。
 const STATUS_INTERVAL_MS: u64 = 1000;
 /// WiFi 断线检查周期。
 const WIFI_CHECK_MS: u64 = 5000;
 /// 毫秒时基。`esp_timer` 是微秒计数器，转毫秒后 u64 不会被绕回。
 fn now_ms() -> u64 {
    // SAFETY: 纯读计时器。
    (unsafe { esp_idf_svc::sys::esp_timer_get_time() } as u64) / 1000
 }
 fn main() -> Result<()> {
    // esp-idf-sys 的运行时补丁必须跑一次，日志系统也要先起来。
    esp_idf_svc::sys::link_patches();
    esp_idf_svc::log::EspLogger::initialize_default();
    let team = armor_protocol::parse_team(TEAM_ENV)
        .ok_or_else(|| anyhow!("ARMOR_TEAM must be 0 or 1, got {TEAM_ENV:?}"))?;
    let peripherals = Peripherals::take()?;
    let sys_loop = EspSystemEventLoop::take()?;
    let nvs = EspDefaultNvsPartition::take()?;
    // 队别与颜色：ARMOR_TEAM 是权威，NVS 只记住结果。
    let color = settings::Settings::new(nvs.clone())?.resolve_color(team)?;
    let threshold: u16 = THRESHOLD_ENV
        .parse()
        .map_err(|_| anyhow!("ARMOR_THRESHOLD must be a number, got {THRESHOLD_ENV:?}"))?;
    let rules = Rules {
        threshold,
        ..Rules::default()
    };
    let mut armor = Armor::new(rules, color);
    info!("pins: ws2812 front=IO10 rear=IO5 left=IO6 right=IO7");
    info!("pins: piezo  front=GPIO0 rear=GPIO4 left=GPIO3 right=GPIO1");
    info!("pins: boot=GPIO9  debug uart0 rxd=GPIO20 txd=GPIO21 115200 8N1");
    info!(
        "armor board: team={team} ({}), {} hp, -{} per hit, {} ms dark on the hit strip",
        if team == TEAM_2 { "blue" } else { "red" },
        armor.hp(),
        rules.damage_per_hit,
        rules.hit_blink.as_millis()
    );
    let mut leds = leds::Leds::new()?;
    let mut piezo = piezo::Piezo::new()?;
    // BOOT 键（GPIO9，低有效）：内部上拉，按下读低。
    let button = PinDriver::input(peripherals.pins.gpio9, Pull::Up)?;
    let mut button_fsm = Button::default();
    let mut wifi = BlockingWifi::wrap(
        EspWifi::new(peripherals.modem, sys_loop.clone(), Some(nvs))?,
        sys_loop,
    )?;
    // WiFi 是尽力而为：**连不上也绝不能挡住受击检测与灯效**。一块因为没网就不亮
    // 灯的装甲板，在场上比"裁判端看不到血量"糟糕得多。所以这里只报警，主循环照跑，
    // 由看门狗每 5 s 重试。
    if let Err(err) = join(&mut wifi, Duration::from_secs(10)) {
        warn!("no referee link yet ({err:#}); hits and LEDs still work, retrying every {WIFI_CHECK_MS} ms");
    }
    let reporter = net::Reporter::new()?;
    let sender_id = net::local_id();
    let mut hits: Vec<(Plate, u16)> = Vec::with_capacity(16);
    let mut reports = ReportSchedule::new(Duration::from_millis(REPORT_HEARTBEAT_MS));
    let mut last_status_ms = now_ms();
    let mut last_wifi_check_ms = now_ms();
    // 启动即发一次：裁判端不用等到第一次受击才知道板子在线。
    let mut force_report = true;
    // 上报统计，状态行里打出来：现场"裁判端没显示"时，第一件事是分清是链路问题
    // 还是对端问题。计数在涨就说明包已经出去了。
    let mut reports_sent: u64 = 0;
    let mut report_errors: u64 = 0;
    // 上一次状态行以来每路 ADC 的峰值（校准阈值用），打印后清零。
    let mut peak = [0u16; 4];
    info!("entering the main loop: long-press BOOT to reset hp, short-press to print status");
    loop {
        let now = Duration::from_millis(now_ms());
        // 采样：一次读一帧（约 10 ms），这一帧就是主循环的节拍。
        match piezo.read_frame(armor.rules().threshold, &mut hits) {
            Ok(stats) => {
                for (slot, value) in stats.peak.iter().enumerate() {
                    peak[slot] = peak[slot].max(*value);
                }
                for (plate, raw) in hits.iter().copied() {
                    if let Some(event) = armor.on_sample(plate, raw, now) {
                        info!(
                            "hit plate={} raw={} hp={} (hits={})",
                            event.plate.name(),
                            event.raw,
                            event.hp,
                            armor.hits()
                        );
                        if event.dead {
                            warn!("hp reached 0: all four strips stay dark until the next reset");
                        }
                    }
                }
            }
            Err(err) => {
                warn!("adc frame failed: {err:#}");
                // 读失败时别把循环变成没有节拍的忙等。
                std::thread::sleep(Duration::from_millis(10));
            }
        }
        // 灯带：只有内容变化的那一路才真的发 RMT（每秒另有一次强制全刷）。
        let strips = armor.strips(now);
        if let Err(err) = leds.refresh(strips, now_ms()) {
            leds::log_failure(&err);
        }
        // 按键。BOOT 低有效，所以"按下" = 读到低电平。
        match button_fsm.tick(button.is_low(), now) {
            ButtonEvent::LongPress => {
                armor.reset();
                warn!("BOOT long press: hp reset to {} (new round)", armor.hp());
                force_report = true;
            }
            ButtonEvent::Click => {
                info!(
                    "status: {}",
                    status_with_link(&armor, now, reports_sent, report_errors, peak)
                );
                force_report = true;
            }
            ButtonEvent::None => {}
        }
        // 上报：血量一变立刻发，其余按心跳重发。
        let current_ms = now_ms();
        if force_report || reports.due(armor.hp(), now) {
            match broadcast_health(&reporter, &armor, team, sender_id) {
                Ok(()) => {
                    reports.mark_sent(armor.hp(), now);
                    reports_sent = reports_sent.saturating_add(1);
                }
                Err(err) => {
                    report_errors = report_errors.saturating_add(1);
                    warn!("report failed: {err:#}");
                }
            }
            force_report = false;
        }
        // 状态行：现场不看串口也能从日志确认板子活着、血量是多少、链路通不通。
        if current_ms.saturating_sub(last_status_ms) >= STATUS_INTERVAL_MS {
            last_status_ms = current_ms;
            info!(
                "status: {}",
                status_with_link(&armor, now, reports_sent, report_errors, peak)
            );
            // 峰值是"上一秒"的量，打完就清零，这样现场能一眼看出没敲时的底噪。
            peak = [0u16; 4];
        }
        // WiFi 看门狗：**关联上 + 拿到 IP** 才算链路好。
        //
        // 判断不用 `BlockingWifi::is_connected()/is_up()`：那两个读的是 esp-idf-svc
        // 自己的事件缓存，实测在 IDF v6.0.1 上会停留在"已连接"，而 IDF 的 API 明明
        // 说没关联（现场表现就是日志说一切正常、裁判端一个包都收不到）。所以这里
        // 直接问 IDF：`esp_wifi_sta_get_ap_info()` 与 `esp_netif_get_ip_info()`。
        //
        // 重连时只给 3 s 等 IP（启动时给的 10 s）：这里是主循环，等太久会漏掉受击。
        if current_ms.saturating_sub(last_wifi_check_ms) >= WIFI_CHECK_MS {
            last_wifi_check_ms = current_ms;
            let link = link_state();
            let ip = sta_ip();
            let healthy = link.associated() && ip.is_some_and(|ip| !ip.is_unspecified());
            if !healthy {
                warn!("link is not usable ({}); reconnecting", describe_link(&link, ip));
                // 断开再连：关联掉了或 DHCP 没下来时，只有重新来一遍才会好。
                if let Err(err) = wifi.disconnect() {
                    warn!("disconnect failed: {err}");
                }
                if let Err(err) = join(&mut wifi, Duration::from_secs(3)) {
                    warn!("reconnect failed: {err:#}");
                }
            }
        }
    }
 }
 /// 广播四块装甲板的血量给裁判终端。
 ///
 /// 四条数据报的 `hp` 相同（整车一条血量），`index` 分别是 0..3 —— 裁判端已有的
 /// 四格血量界面无需改动。`sender_id` 用 MAC 派生的板子 id，方便抓包时分辨是谁发的。
 fn broadcast_health(
    reporter: &net::Reporter,
    armor: &Armor,
    team: u8,
    sender_id: u32,
 ) -> Result<()> {
    for datagram in armor.datagrams_from(team, sender_id) {
        reporter.broadcast(&datagram)?;
    }
    Ok(())
 }
 /// 状态行 + 当场问出来的链路状态。
 ///
 /// 每次都现算而不是缓存：现场排查时最怕看到的是过期的好消息。
 fn status_with_link(
    armor: &Armor,
    now: Duration,
    reports_sent: u64,
    report_errors: u64,
    peak: [u16; 4],
 ) -> String {
    status_line(
        armor,
        now,
        &link_line(&link_state(), sta_ip(), reports_sent, report_errors),
        peak,
    )
 }
 /// 一行状态，给 UART 调试口用。
 ///
 /// `peak` 是这一秒里每路 ADC 的峰值。它比"有没有受击"更有用：现场要判断阈值该调到
 /// 多少，靠的就是"没敲时的底噪"和"敲击时的幅度"这两个数字。
 fn status_line(armor: &Armor, now: Duration, link: &str, peak: [u16; 4]) -> String {
    let counts = armor.plate_hits_all();
    let per_plate = Plate::ALL
        .iter()
        .map(|plate| format!("{}={}", plate.name(), counts[plate.index() as usize]))
        .collect::<Vec<_>>()
        .join(" ");
    let peaks = Plate::ALL
        .iter()
        .map(|plate| format!("{}={}", plate.name(), peak[plate.index() as usize]))
        .collect::<Vec<_>>()
        .join(" ");
    format!(
        "hp={} hits={} dead={} plates[{}] peak[{}] thr={} strips[{}] {link}",
        armor.hp(),
        armor.hits(),
        armor.dead(),
        per_plate,
        peaks,
        armor.rules().threshold,
        leds::describe(armor.strips(now)),
    )
 }
 /// 链路那半截状态：连的是哪个 AP、信号多强、有没有 IP、上报发了多少包。
 ///
 /// 现场"裁判端没显示"时，第一件事是分清链路问题还是对端问题：`reports` 在涨就说明
 /// 包已经出去了，该去查裁判端；一直不动就是这块板子没连上。而"没连上"还要再分
 /// 关联与 DHCP —— 关联上但 IP 是 0.0.0.0 是最容易看错的一种。
 fn link_line(link: &Link, ip: Option<std::net::Ipv4Addr>, reports_sent: u64, report_errors: u64) -> String {
    format!(
        "{} reports={reports_sent} errs={report_errors}",
        describe_link(link, ip)
    )
 }
 /// 当前关联状态。**来源是 IDF 的 API**，不是 esp-idf-svc 的事件缓存（见看门狗注释）。
 #[derive(Debug, Clone)]
 enum Link {
    /// 关联上了：AP 名字、RSSI、信道。
    Associated {
        ssid: String,
        rssi: i8,
        channel: u8,
    },
    /// 没关联（或者 IDF 说 STA 没在跑）。
    Idle { rc: i32 },
 }
 impl Link {
    #[must_use]
    fn associated(&self) -> bool {
        matches!(self, Link::Associated { .. })
    }
 }
 /// 问一次 IDF：STA 关联到哪个 AP 了。
 fn link_state() -> Link {
    let mut record = esp_idf_svc::sys::wifi_ap_record_t::default();
    // SAFETY: record 是本函数的局部量，IDF 只往里写；未关联时返回非 OK 而不动它。
    let rc = unsafe { esp_idf_svc::sys::esp_wifi_sta_get_ap_info(&mut record) };
    if rc != esp_idf_svc::sys::ESP_OK {
        return Link::Idle { rc };
    }
    // ssid 是定长 33 字节、以 0 结尾的缓冲区。
    let ssid = unsafe {
        core::ffi::CStr::from_ptr(record.ssid.as_ptr() as *const core::ffi::c_char)
            .to_string_lossy()
            .into_owned()
    };
    Link::Associated {
        ssid,
        rssi: record.rssi,
        channel: record.primary,
    }
 }
 /// STA 网卡当前的 IPv4 地址（直接从 `esp_netif` 读，绕开 esp-idf-svc 的封装）。
 ///
 /// `None` 表示还没拿到 DHCP 地址。0.0.0.0 也按 `None` 处理 —— 那等于没有地址。
 fn sta_ip() -> Option<std::net::Ipv4Addr> {
    // 默认 STA 网卡的 interface key（`esp_netif_create_default_wifi_sta` 用的就是它）。
    let handle = unsafe {
        esp_idf_svc::sys::esp_netif_get_handle_from_ifkey(c"WIFI_STA_DEF".as_ptr())
    };
    if handle.is_null() {
        return None;
    }
    let mut info = esp_idf_svc::sys::esp_netif_ip_info_t::default();
    // SAFETY: info 是局部量，handle 来自上面的查询。
    if unsafe { esp_idf_svc::sys::esp_netif_get_ip_info(handle, &mut info) }
        != esp_idf_svc::sys::ESP_OK
    {
        return None;
    }
    // lwIP 的 `ip4_addr_t.addr` 是网络字节序，所以最低字节是点分表示的第一段。
    let raw = info.ip.addr;
    let ip = std::net::Ipv4Addr::new(
        (raw & 0xFF) as u8,
        ((raw >> 8) & 0xFF) as u8,
        ((raw >> 16) & 0xFF) as u8,
        ((raw >> 24) & 0xFF) as u8,
    );
    if ip.is_unspecified() {
        None
    } else {
        Some(ip)
    }
 }
 /// 链路状态的一行描述，日志与状态行共用。
 fn describe_link(link: &Link, ip: Option<std::net::Ipv4Addr>) -> String {
    let ip = match ip {
        Some(ip) => ip.to_string(),
        None => "none".to_string(),
    };
    match link {
        Link::Associated {
            ssid,
            rssi,
            channel,
        } => format!("ap={ssid} rssi={rssi} ch={channel} ip={ip}"),
        Link::Idle { rc } => format!("ap=none (rc=0x{rc:x}) ip={ip}"),
    }
 }
 /// 等到 STA 真的拿到 IP（权威来源），最多等 `timeout`。
 ///
 /// 不用 `BlockingWifi::wait_netif_up()`：它读的是 esp-idf-svc 的事件缓存，在
 /// IDF v6.0.1 上会"立刻成功"而实际没有地址 —— 那样 join() 会假装连上了，看门狗
 /// 也就永远不会重试。
 fn wait_for_ip(timeout: Duration) -> Option<std::net::Ipv4Addr> {
    let deadline = std::time::Instant::now() + timeout;
    loop {
        if let Some(ip) = sta_ip() {
            return Some(ip);
        }
        if std::time::Instant::now() >= deadline {
            return None;
        }
        std::thread::sleep(Duration::from_millis(200));
    }
 }
 /// 连上 WiFi 并等一个 IP（幂等：已启动就不再 start 一次）。
 ///
 /// 连不上时把扫到的网络打出来：这块模块只有 2.4 GHz，SSID 若在 5 GHz 上，现场看到
 /// 一张空列表比看一个关联超时有用得多。**调用方不应该因为这个错误就退出** —— 没有
 /// 网也要能打灯。
 fn join(wifi: &mut BlockingWifi<EspWifi<'static>>, ip_timeout: Duration) -> Result<()> {
    if !wifi.is_started()? {
        wifi.start()?;
    }
    if !link_state().associated() {
        let config = Configuration::Client(ClientConfiguration {
            ssid: SSID
                .try_into()
                .map_err(|_| anyhow!("WIFI_SSID too long (max 32 bytes)"))?,
            bssid: None,
            auth_method: default_auth_method(),
            password: PASSWORD
                .try_into()
                .map_err(|_| anyhow!("WIFI_PASS too long (max 64 bytes)"))?,
            channel: None,
            // 通告 PMF：WPA2/WPA3 混合模式的路由器否则会丢掉握手；`required: false`
            // 仍然允许纯 WPA2 的 AP。
            pmf_cfg: PmfConfiguration::Capable { required: false },
            ..Default::default()
        });
        wifi.set_configuration(&config)?;
        if let Err(err) = wifi.connect() {
            error!("could not join \"{SSID}\": {err}");
            report_scan(wifi);
            return Err(err.into());
        }
    }
    // 省电模式换来的电流不值得：它会让上报晚一个信标间隔（上百毫秒），而"受击后
    // 50 ms 变暗"这件事本来就是要给人即时反馈的。
    let rc = unsafe {
        esp_idf_svc::sys::esp_wifi_set_ps(esp_idf_svc::sys::wifi_ps_type_t_WIFI_PS_NONE)
    };
    if rc != esp_idf_svc::sys::ESP_OK {
        warn!("could not disable wifi power save ({})", esp::name(rc));
    }
    let link = link_state();
    let Some(ip) = wait_for_ip(ip_timeout) else {
        report_scan(wifi);
        return Err(anyhow!(
            "no DHCP address within {} ms ({})",
            ip_timeout.as_millis(),
            describe_link(&link, None)
        ));
    };
    info!("joined \"{SSID}\" on {ip}");
    Ok(())
 }
 /// 没写 `WIFI_PASS` 就是开放网络。
 fn default_auth_method() -> AuthMethod {
    if PASSWORD.is_empty() {
        AuthMethod::None
    } else {
        AuthMethod::WPA2Personal
    }
 }
 /// 把扫到的网络打出来，并标出我们要连的那个。连不上时的第一诊断信息。
 fn report_scan(wifi: &mut BlockingWifi<EspWifi<'static>>) {
    match wifi.scan() {
        Ok(aps) if aps.is_empty() => {
            error!("scan found no networks; check the antenna and that the AP is on 2.4 GHz");
        }
        Ok(aps) => {
            for ap in aps {
                info!(
                    "  {:<32} ch {:>2}  {:>4} dBm  {:?}{}",
                    ap.ssid,
                    ap.channel,
                    ap.signal_strength,
                    ap.auth_method,
                    if ap.ssid.as_str() == SSID { "  <- target" } else { "" }
                );
            }
        }
        Err(err) => warn!("scan failed: {err}"),
    }
 }
@@ -0,0 +1,142 @@
 //! 上报通道：把 [`ArmorHealth`](armor_protocol::ArmorHealth) 广播给本项目裁判终端。
 //!
 //! # 为什么直接写 lwIP 的 socket
 //!
 //! 与同仓库的图传固件（`src/udp.rs`）一样：`std::net` 在 lwIP 上的行为要靠一层
 //! VFS 转接，而这里只需要"建一个 UDP socket + 广播"这一件事，直接用 IDF 原生的
 //! `lwip_*` 就能与图传板跑在同一条被验证过的代码路径上。
 //!
 //! # 为什么不 bind
 //!
 //! 装甲板只发不收：血量是板子算出来的，裁判端只显示。所以 socket 不绑定端口，
 //! 由 lwIP 选一个临时端口即可 —— 绑定 5601 反而会和裁判端、以及同网段的另一块
 //! 装甲板抢同一个端口。裁判端监听 5601，板子往 5601 发，方向是单向的。
 //!
 //! # 广播而不是单播
 //!
 //! 裁判终端的地址是 DHCP 变的（图传板的 Hello 广播就是为了绕开这件事）。装甲板
 //! 沿用同一个约定：不知道也不关心裁判端在哪，反正同一个局域网里它会收到。
 use core::ffi::c_void;
 use std::net::SocketAddrV4;
 use anyhow::{anyhow, Result};
 use esp_idf_svc::sys as ffi;
 use log::{info, warn};
 use armor_protocol::{ARMOR_PORT, BROADCAST_ADDR};
 /// 把 Rust 的 socket 地址转成 lwIP 期望的 C 结构。
 ///
 /// 逐字段构造而不是 `transmute`：`SocketAddrV4` 是紧凑的 6 字节（端口在前、主机
 /// 字节序），C 的 `sockaddr_in` 是 16 字节且地址是网络字节序 —— 指针强转会发到一个
 /// 乱地址，而且不会报错。
 fn to_sockaddr(addr: SocketAddrV4) -> ffi::sockaddr_in {
    let octets = addr.ip().octets();
    ffi::sockaddr_in {
        sin_len: core::mem::size_of::<ffi::sockaddr_in>() as u8,
        sin_family: ffi::AF_INET as ffi::sa_family_t,
        // 用 lwIP 的 htons，字节序不必在 Rust 侧推理。
        sin_port: unsafe { ffi::lwip_htons(addr.port()) },
        sin_addr: ffi::in_addr {
            s_addr: u32::from_le_bytes(octets),
        },
        sin_zero: [0; 8],
    }
 }
 /// 本机 id：由 WiFi MAC 派生（FNV-1a），重启不变，且避开 0 —— 0 留给裁判终端。
 pub fn local_id() -> u32 {
    let mut mac = [0u8; 6];
    // SAFETY: `mac` 有 6 字节空间，函数会把 6 字节写满。
    let rc = unsafe { ffi::esp_read_mac(mac.as_mut_ptr(), ffi::esp_mac_type_t_ESP_MAC_WIFI_STA) };
    if rc != ffi::ESP_OK {
        warn!("could not read the WiFi MAC ({:#x}); using a fixed id", rc);
        return 0xF1F0_0001;
    }
    let id = armor_protocol::id_from_mac(&mac);
    info!("this board's id is 0x{id:08X}, from MAC {mac:02X?}");
    id
 }
 /// 广播上报器。
 pub struct Reporter {
    socket: i32,
 }
 impl Reporter {
    /// 建一个开了广播许可的 UDP socket。
    pub fn new() -> Result<Self> {
        // SAFETY: 建 socket 不涉及 Rust 内存。
        let socket = unsafe { ffi::lwip_socket(ffi::AF_INET as i32, ffi::SOCK_DGRAM as i32, 0) };
        if socket < 0 {
            // 用 std 的 errno 读取：`__errno` 不是每个目标的绑定里都有，而 lwIP 的
            // socket 错误码就是同一个 errno。
            return Err(anyhow!(
                "could not create UDP socket: {}",
                std::io::Error::last_os_error()
            ));
        }
        // 目标地址是 255.255.255.255，不开这个选项 sendto 会返回 EACCES。默认就是
        // 关的，而且失败不会自己冒出来 —— 只会表现为"裁判端一直显示未接入"。
        let enable: i32 = 1;
        // SAFETY: optval 指向栈上的 i32，optlen 与它一致。
        let rc = unsafe {
            ffi::lwip_setsockopt(
                socket,
                ffi::SOL_SOCKET as i32,
                ffi::SO_BROADCAST as i32,
                &enable as *const i32 as *const c_void,
                core::mem::size_of::<i32>() as u32,
            )
        };
        if rc != 0 {
            let err = std::io::Error::last_os_error();
            // SAFETY: 关闭本函数刚建的 socket。
            unsafe { ffi::lwip_close(socket) };
            return Err(anyhow!("could not enable SO_BROADCAST: {err}"));
        }
        info!("reporting to {BROADCAST_ADDR}:{ARMOR_PORT} over UDP");
        Ok(Self { socket })
    }
    /// 把一个数据报广播到裁判终端。
    pub fn broadcast(&self, payload: &[u8]) -> Result<()> {
        let addr = to_sockaddr(SocketAddrV4::new(BROADCAST_ADDR, ARMOR_PORT));
        // SAFETY: 缓冲区与地址在调用期间都有效；sendto 复制数据而不是持有指针。
        let rc = unsafe {
            ffi::lwip_sendto(
                self.socket,
                payload.as_ptr() as *const c_void,
                payload.len(),
                ffi::MSG_DONTWAIT as i32,
                &addr as *const ffi::sockaddr_in as *const ffi::sockaddr,
                core::mem::size_of::<ffi::sockaddr_in>() as ffi::socklen_t,
            )
        };
        if rc < 0 {
            return Err(anyhow!(
                "broadcast failed: {}",
                std::io::Error::last_os_error()
            ));
        }
        Ok(())
    }
 }
 impl Drop for Reporter {
    fn drop(&mut self) {
        // SAFETY: 关闭本结构体自己建的 socket。
        unsafe { ffi::lwip_close(self.socket) };
    }
 }
@@ -0,0 +1,213 @@
 //! 四路压电片的 ADC 连续采样（ESP32-C3）。
 //!
 //! # 为什么要连续（DMA）采样
 //!
 //! 压电片被敲一下的波形只有几十微秒宽。用 oneshot 轮询（每圈读一次）几乎必然从
 //! 尖峰旁边擦过去，表现就是"有时候敲得响才算"；参考实现因此用 40 kHz 的连续采样，
 //! 这里保持一致：四个通道合计 40 kHz（每通道 10 kHz），一帧 10 ms = 400 个采样点。
 //!
 //! # 为什么也走 sys 绑定
 //!
 //! `esp-idf-hal` 的 `adc::continuous` 要用 `AdcChannels` 组合通道，而多通道组合的
 //! 入口 `EmptyAdcChannels::chain` 在 0.47 里的约束是 `A: Adc` 且
 //! `O: AdcChannels<AdcUnit = A>` —— `ADC1` 满足前者、`ADCU1` 满足后者，同一个类型
 //! 参数凑不齐，四路 ADC1 通道拼不出来。直接照着 IDF 的 C API 建驱动反而更短，也
 //! 与参考实现逐行对应。
 //!
 //! 采样点的通道号由硬件结果自带（`type2.channel`），所以映射不依赖"结果按 pattern
 //! 顺序轮转"这个假设。
 use anyhow::Result;
 use esp_idf_svc::sys as ffi;
 use log::info;
 use armor_protocol::Plate;
 use crate::esp;
 /// 四个通道合计的采样率；每通道 10 kHz。
 const SAMPLE_FREQ_HZ: u32 = 40_000;
 /// 一帧的采样点数：10 ms × 40 kHz。
 pub const FRAME_MEASUREMENTS: usize = 400;
 /// 一帧的字节数（每个结果 4 字节）。
 const FRAME_BYTES: u32 = FRAME_MEASUREMENTS as u32 * ffi::SOC_ADC_DIGI_RESULT_BYTES;
 /// 连续读的超时：正常情况 10 ms 就凑满一帧，200 ms 只用来发现"驱动卡住了"。
 const READ_TIMEOUT_MS: u32 = 200;
 /// 每个板位对应的 ADC 通道号（ESP32-C3：GPIO0/4/3/1 = ADC1_CH0/CH4/CH3/CH1）。
 ///
 /// 顺序与 [`Plate`] 的 index 一致；硬件结果里的通道号就是这些值。
 const PLATE_CHANNEL: [u8; 4] = [0, 4, 3, 1];
 /// 一帧的统计：读到多少采样点，以及每个板位的峰值。
 ///
 /// 峰值是给**现场校准阈值**用的：压电片的输出幅度取决于贴装、线长和有没有放大，
 /// 只报"有没有过阈值"没法判断该把阈值调到哪里。status 行每秒打印一次。
 #[derive(Debug, Clone, Copy, Default)]
 pub struct FrameStats {
    /// 这一帧实际读到的采样点数。
    pub samples: usize,
    /// 每个板位的最大原始 ADC 值，按 [`Plate`] 的 index 排列。
    pub peak: [u16; 4],
 }
 /// 连续采样的压电片输入。
 pub struct Piezo {
    handle: ffi::adc_continuous_handle_t,
    /// 一帧的原始结果。`adc_digi_output_data_t` 里有 union，bindgen 不给 `Default`，
    /// 所以用零值显式初始化（这个类型是纯 POD，零值是合法状态）。
    frame: Box<[ffi::adc_digi_output_data_t; FRAME_MEASUREMENTS]>,
 }
 impl Piezo {
    /// 建驱动并开始采样。
    pub fn new() -> Result<Self> {
        let handle_config = ffi::adc_continuous_handle_cfg_t {
            // 两帧的余量：这一帧还没读完时，下一帧有地方落。
            max_store_buf_size: FRAME_BYTES * 2,
            conv_frame_size: FRAME_BYTES,
            ..Default::default()
        };
        let mut handle: ffi::adc_continuous_handle_t = core::ptr::null_mut();
        esp::check(
            "adc_continuous_new_handle",
            // SAFETY: 两个指针都指向本函数的局部量，调用期间有效。
            unsafe { ffi::adc_continuous_new_handle(&handle_config, &mut handle) },
        )?;
        // 四路通道的采样参数：0 dB 衰减、12 bit、都在 ADC1。
        let mut patterns = [ffi::adc_digi_pattern_config_t {
            atten: ffi::adc_atten_t_ADC_ATTEN_DB_0 as u8,
            channel: 0,
            unit: ffi::adc_unit_t_ADC_UNIT_1 as u8,
            bit_width: 12,
        }; 4];
        for (pattern, channel) in patterns.iter_mut().zip(PLATE_CHANNEL) {
            pattern.channel = channel;
        }
        let config = ffi::adc_continuous_config_t {
            pattern_num: patterns.len() as u32,
            adc_pattern: patterns.as_mut_ptr(),
            sample_freq_hz: SAMPLE_FREQ_HZ,
            conv_mode: ffi::adc_digi_convert_mode_t_ADC_CONV_SINGLE_UNIT_1,
            // C3 的连续采样只支持 12 bit 的 TYPE2 结果布局，也正好对应下面读的
            // `type2.data`（参考实现依赖了默认值 0，这里写明确）。
            format: ffi::adc_digi_output_format_t_ADC_DIGI_OUTPUT_FORMAT_TYPE2,
            ..Default::default()
        };
        if let Err(err) = esp::check(
            "adc_continuous_config",
            // SAFETY: IDF 会把 patterns 复制进驱动，调用后不再持有这个指针。
            unsafe { ffi::adc_continuous_config(handle, &config) },
        ) {
            // SAFETY: 句柄刚建好、还没 start，可以直接删。
            unsafe { ffi::adc_continuous_deinit(handle) };
            return Err(err);
        }
        esp::check("adc_continuous_start", unsafe {
            ffi::adc_continuous_start(handle)
        })?;
        let zero = ffi::adc_digi_output_data_t {
            __bindgen_anon_1: ffi::adc_digi_output_data_t__bindgen_ty_1 { val: 0 },
        };
        info!(
            "piezo: {SAMPLE_FREQ_HZ} Hz total over {} channels, {} measurements/frame (10 ms)",
            PLATE_CHANNEL.len(),
            FRAME_MEASUREMENTS
        );
        Ok(Self {
            handle,
            frame: Box::new([zero; FRAME_MEASUREMENTS]),
        })
    }
    /// 读一帧（约 10 ms），把过阈值的采样点收集进 `hits`。
    ///
    /// `hits` 会被清空后填充 `(板位, 原始值)`；返回值里带这一帧的采样点数与每路峰值。
    /// **去抖与扣血不在这里做** —— 那是
    /// [`armor_protocol::Armor::on_sample`] 的职责，一次击打的多个过阈值采样点由它
    /// 的冷却窗口收敛成一次受击。
    pub fn read_frame(
        &mut self,
        threshold: u16,
        hits: &mut Vec<(Plate, u16)>,
    ) -> Result<FrameStats> {
        hits.clear();
        let mut stats = FrameStats::default();
        let mut out_length: u32 = 0;
        let rc = unsafe {
            ffi::adc_continuous_read(
                self.handle,
                self.frame.as_mut_ptr() as *mut u8,
                FRAME_BYTES,
                &mut out_length,
                READ_TIMEOUT_MS,
            )
        };
        if rc == ffi::ESP_ERR_TIMEOUT {
            // 没有数据不算错误：上一帧还没凑满，下一圈再来。
            return Ok(stats);
        }
        esp::check("adc_continuous_read", rc)?;
        let count = (out_length as usize / ffi::SOC_ADC_DIGI_RESULT_BYTES as usize)
            .min(FRAME_MEASUREMENTS);
        stats.samples = count;
        for index in 0..count {
            // SAFETY: 配置的是 TYPE2（12 bit）格式，`type2` 是有效成员；每个结果
            // 4 字节且已 4 字节对齐。
            let result = unsafe { self.frame[index].__bindgen_anon_1.type2 };
            let raw = result.data() as u16;
            let Some(plate) = plate_of_channel(result.channel() as u8) else {
                continue;
            };
            // 峰值取自**所有**采样点，不只是过阈值的：阈值调得对不对，要靠没敲时
            // 的底噪和敲击时的幅度两个数字一起看。
            let slot = plate.index() as usize;
            if raw > stats.peak[slot] {
                stats.peak[slot] = raw;
            }
            if raw > threshold {
                hits.push((plate, raw));
            }
        }
        Ok(stats)
    }
 }
 impl Drop for Piezo {
    fn drop(&mut self) {
        // 固件里 main 永不返回；这段只在启动失败路径上跑到。
        unsafe {
            if !self.handle.is_null() {
                ffi::adc_continuous_stop(self.handle);
                ffi::adc_continuous_deinit(self.handle);
            }
        }
    }
 }
 /// 硬件结果里的通道号 → 板位。
 #[must_use]
 fn plate_of_channel(channel: u8) -> Option<Plate> {
    let slot = PLATE_CHANNEL.iter().position(|c| *c == channel)?;
    Plate::ALL.get(slot).copied()
 }
@@ -0,0 +1,65 @@
 //! 板子自己的持久化设置（NVS）：队别与颜色。
 //!
 //! 命名空间与键名都沿用参考实现（`armor` / `color`），所以从参考固件刷过来时，
 //! 之前存过的颜色还能被读到。新增一个 `team` 键用来记住这块板子是哪一队。
 use anyhow::Result;
 use esp_idf_svc::nvs::{EspDefaultNvsPartition, EspNvs, NvsDefault};
 use log::info;
 use armor_protocol::Rgb;
 /// NVS 命名空间（与参考实现一致）。
 const NAMESPACE: &str = "armor";
 /// 队别键名。
 const KEY_TEAM: &str = "team";
 /// 颜色键名，值是 `0x00RRGGBB`（与参考实现一致）。
 const KEY_COLOR: &str = "color";
 /// 打开着的 NVS 句柄。
 pub struct Settings {
    nvs: EspNvs<NvsDefault>,
 }
 impl Settings {
    /// 打开（必要时创建）命名空间。
    pub fn new(partition: EspDefaultNvsPartition) -> Result<Self> {
        Ok(Self {
            nvs: EspNvs::new(partition, NAMESPACE, true)?,
        })
    }
    /// 定出这次该用哪个颜色，并把它写回 NVS。
    ///
    /// 规则：**编译期注入的 `ARMOR_TEAM` 是权威**。换队伍只要重刷固件，不用先擦
    /// NVS；NVS 里的值只用来记住当前状态（也给以后加"手动换色"留位置）。两者
    /// 不一致时以 `ARMOR_TEAM` 为准并覆盖，日志里会说一声，免得现场纳闷为什么
    /// 灯色变了。
    pub fn resolve_color(&self, team: u8) -> Result<Rgb> {
        let expected = Rgb::for_team(team);
        let stored_team = self.nvs.get_u8(KEY_TEAM)?;
        let stored_color = self.nvs.get_u32(KEY_COLOR)?;
        let color = match (stored_team, stored_color) {
            (Some(stored), Some(raw)) if stored == team => Rgb::from_u32(raw),
            (Some(stored), Some(raw)) => {
                info!(
                    "ARMOR_TEAM={team} overrides the stored team {stored} (colour #{raw:06X}); rewriting NVS"
                );
                expected
            }
            _ => {
                info!(
                    "first boot as team {team}: storing colour #{:06X}",
                    expected.to_u32()
                );
                expected
            }
        };
        self.nvs.set_u8(KEY_TEAM, team)?;
        self.nvs.set_u32(KEY_COLOR, color.to_u32())?;
        Ok(color)
    }
 }
@@ -0,0 +1,7 @@
 # 这个 crate 在主机上跑单元测试，不交叉编译。
 #
 # 它坐在 armor/ 目录树里，cargo 会向上继承 armor/.cargo/config.toml 的 RISC-V
 # 目标与 ldproxy linker —— 把主机测试编译成 ESP32-C3 固件会直接失败在链接上。
 # 把 target 覆盖回 host triple 就够了，别的键对非 ESP 目标没有影响。
 [build]
 target = "aarch64-apple-darwin"
@@ -0,0 +1,9 @@
 [package]
 name = "armor-protocol"
 version = "0.1.0"
 edition = "2021"
 # 只依赖错误检查用的东西：规则层是纯计算（血量、去抖、按键状态机），
 # 这样它能在 PC 上跑单元测试，不需要 ESP32-C3 硬件。
 [dependencies]
 protocol = { path = "../../protocol" }
@@ -0,0 +1,872 @@
 //! 装甲板规则层：板位、整车血量、受击判定、按键状态机、上报帧。
 //!
 //! # 为什么和固件分开
 //!
 //! 这一层全是纯计算：一次采样算不算新受击、扣几滴血、灯带这一刻该显示什么颜色、
 //! 按一下键算短按还是长按。这些恰好是最容易写错、又最不适合"烧上去看现象"的部分
 //! —— 在 ESP32-C3 上，受击是几微秒的压电片尖峰，现场根本没法复现"冷却期内的第二次
 //! 采样被误判"这类 bug。放在这里就能用 `Duration` 喂假时间来测。
 //!
 //! 固件侧（`armor-firmware`）只负责把外设接到这层：ADC 采样值、GPIO 电平、毫秒
 //! 时基、UDP 发送。
 //!
 //! # 硬件形态（一主三从）
 //!
 //! **只有主板一颗 MCU**：三块"从"装甲板里没有单片机，只有一路 WS2812 和一路压电片，
 //! 直接接到主板上。所以这一层同时管四路：
 //!
 //! | 板位 | WS2812 | 压电片 ADC |
 //! | --- | --- | --- |
 //! | 前 front | GPIO10 | ADC1_CH0 (GPIO0) |
 //! | 后 rear  | GPIO5  | ADC1_CH4 (GPIO4) |
 //! | 左 left  | GPIO6  | ADC1_CH3 (GPIO3) |
 //! | 右 right | GPIO7  | ADC1_CH1 (GPIO1) |
 //!
 //! # 规则（已与本项目裁判端对齐）
 //!
 //! - 整车一条血量：初始 100，每次受击 −3，减到 0 为止**不变负**，血量 0 时四路灯带
 //!   全黑（"死了全黑"）。
 //! - 受击时**只有被打的那一路**灯带全黑 50 ms，其余三路不动；50 ms 同时是同一板位的
 //!   重复判定冷却。
 //! - 颜色由队伍决定：队伍一红、队伍二蓝（RoboMaster 惯例）。
 //! - 血量账在板子上算，按 [`protocol::ArmorHealth`] 上报给本项目裁判终端（UDP 5601）。
 //!   整车一条血量 → 四条上报的 `hp` 相同，`index` 分别是 0..3，裁判端已有的四格血量
 //!   界面无需改动。
 use std::time::Duration;
 pub use protocol::{id_from_mac, ArmorHealth, ARMOR_PORT, BROADCAST_ADDR, MsgType};
 /// 队伍一。
 pub const TEAM_1: u8 = 0;
 /// 队伍二。
 pub const TEAM_2: u8 = 1;
 /// 一块装甲板。
 ///
 /// 判别值就是上报里的 `index`（0..3），所以 `Plate::Front.index() == 0` 与裁判端
 /// 的四格顺序一一对应。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 #[repr(u8)]
 pub enum Plate {
    /// 前装甲板，WS2812 = GPIO10，压电片 = ADC1_CH0。
    Front = 0,
    /// 后装甲板，WS2812 = GPIO5，压电片 = ADC1_CH4。
    Rear = 1,
    /// 左装甲板，WS2812 = GPIO6，压电片 = ADC1_CH3。
    Left = 2,
    /// 右装甲板，WS2812 = GPIO7，压电片 = ADC1_CH1。
    Right = 3,
 }
 impl Plate {
    /// 按 index 顺序的四块板，也是灯带刷新和 ADC 通道表里用的顺序。
    pub const ALL: [Plate; 4] = [Plate::Front, Plate::Rear, Plate::Left, Plate::Right];
    /// 上报里的 `index`。
    #[must_use]
    pub const fn index(self) -> u8 {
        self as u8
    }
    /// 日志里用的短名（英文，和本仓库其余固件的日志一致）。
    #[must_use]
    pub const fn name(self) -> &'static str {
        match self {
            Plate::Front => "front",
            Plate::Rear => "rear",
            Plate::Left => "left",
            Plate::Right => "right",
        }
    }
    /// 从 `index` 还原，越界返回 `None`。
    #[must_use]
    pub const fn from_index(value: u8) -> Option<Plate> {
        match value {
            0 => Some(Plate::Front),
            1 => Some(Plate::Rear),
            2 => Some(Plate::Left),
            3 => Some(Plate::Right),
            _ => None,
        }
    }
    /// 数组下标。
    #[must_use]
    const fn slot(self) -> usize {
        self as usize
    }
 }
 /// 颜色，`0x00RRGGBB`（与参考实现里 `Adafruit_NeoPixel::Color(r, g, b)` 一致）。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Rgb(pub u8, pub u8, pub u8);
 impl Rgb {
    /// 队伍一的颜色。
    pub const RED: Rgb = Rgb(0xFF, 0x00, 0x00);
    /// 队伍二的颜色。
    pub const BLUE: Rgb = Rgb(0x00, 0x00, 0xFF);
    /// 全黑，也就是熄灭。
    pub const BLACK: Rgb = Rgb(0x00, 0x00, 0x00);
    /// 队伍对应的颜色：队伍二蓝，其余（含误配的值）红。
    #[must_use]
    pub const fn for_team(team: u8) -> Rgb {
        if team == TEAM_2 {
            Rgb::BLUE
        } else {
            Rgb::RED
        }
    }
    /// 打包成 `0x00RRGGBB`，用于写 NVS 或日志。
    #[must_use]
    pub const fn to_u32(self) -> u32 {
        ((self.0 as u32) << 16) | ((self.1 as u32) << 8) | (self.2 as u32)
    }
    /// 从 `0x00RRGGBB` 还原。
    #[must_use]
    pub const fn from_u32(value: u32) -> Rgb {
        Rgb(
            ((value >> 16) & 0xFF) as u8,
            ((value >> 8) & 0xFF) as u8,
            (value & 0xFF) as u8,
        )
    }
    /// WS2812 的线上字节序：GRB，MSB first。
    ///
    /// 交错顺序错了不会报错，只会显示成另一种颜色（红蓝互换），所以单独有测试钉住。
    #[must_use]
    pub const fn to_grb(self) -> [u8; 3] {
        [self.1, self.0, self.2]
    }
 }
 /// 一条灯带这一刻要显示的内容。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Strip {
    /// 正常颜色。
    Color(Rgb),
    /// 全黑：受击的 50 ms 窗口内，或者整车血量已经归零。
    Black,
 }
 impl Strip {
    /// 是否熄灭。
    #[must_use]
    pub const fn is_black(self) -> bool {
        matches!(self, Strip::Black)
    }
    /// 实际颜色，`Black` 就是 [`Rgb::BLACK`]。
    #[must_use]
    pub const fn color(self) -> Rgb {
        match self {
            Strip::Color(rgb) => rgb,
            Strip::Black => Rgb::BLACK,
        }
    }
 }
 /// 规则参数。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Rules {
    /// 整车初始血量。
    pub max_hp: u16,
    /// 每次受击扣多少血。
    pub damage_per_hit: u16,
    /// 受击后该路灯带全黑的时长。
    pub hit_blink: Duration,
    /// 同一块板重复受击的抑制窗口（压电片一次击打会在多个采样点上过阈值）。
    pub hit_cooldown: Duration,
    /// 原始 12 bit ADC 采样值超过它才算受击。
    pub threshold: u16,
 }
 impl Default for Rules {
    /// 现场取值：100 血、每击 −3、50 ms 变暗/冷却、阈值 2000（与参考实现一致）。
    fn default() -> Self {
        Self {
            max_hp: 100,
            damage_per_hit: 3,
            hit_blink: Duration::from_millis(50),
            hit_cooldown: Duration::from_millis(50),
            threshold: 2000,
        }
    }
 }
 /// 一次被计入的受击。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct HitEvent {
    /// 哪块装甲板。
    pub plate: Plate,
    /// 触发这次判定的原始 ADC 值，用来现场校准阈值。
    pub raw: u16,
    /// 扣血之后的整车血量。
    pub hp: u16,
    /// 这一击是否把血量打到 0。
    pub dead: bool,
    /// 判定时刻。
    pub at: Duration,
 }
 /// 装甲板状态机：血量、受击冷却、灯带输出。
 #[derive(Debug, Clone)]
 pub struct Armor {
    rules: Rules,
    color: Rgb,
    hp: u16,
    hits: u32,
    plate_hits: [u32; 4],
    last_hit: [Option<Duration>; 4],
 }
 impl Armor {
    /// 满血、`color` 为正常色。
    #[must_use]
    pub fn new(rules: Rules, color: Rgb) -> Self {
        Self {
            rules,
            color,
            hp: rules.max_hp,
            hits: 0,
            plate_hits: [0; 4],
            last_hit: [None; 4],
        }
    }
    /// 规则参数。
    #[must_use]
    pub fn rules(&self) -> Rules {
        self.rules
    }
    /// 当前整车血量。
    #[must_use]
    pub fn hp(&self) -> u16 {
        self.hp
    }
    /// 血量是否归零。
    #[must_use]
    pub fn dead(&self) -> bool {
        self.hp == 0
    }
    /// 累计计入的受击次数。
    #[must_use]
    pub fn hits(&self) -> u32 {
        self.hits
    }
    /// 某块装甲板各自被计中的次数。
    #[must_use]
    pub fn plate_hits(&self, plate: Plate) -> u32 {
        self.plate_hits[plate.slot()]
    }
    /// 四块板各自被计中的次数，按 index 排列。
    #[must_use]
    pub fn plate_hits_all(&self) -> [u32; 4] {
        self.plate_hits
    }
    /// 正常显示颜色。
    #[must_use]
    pub fn color(&self) -> Rgb {
        self.color
    }
    /// 换正常显示颜色（队伍变了、或从 NVS 读回）。
    pub fn set_color(&mut self, color: Rgb) {
        self.color = color;
    }
    /// 喂一个 ADC 采样值。
    ///
    /// 只有"过阈值 + 该板不在冷却期内"才计入受击并扣血；其余返回 `None`。
    /// 一次击打在 40 kHz 采样下会连续多个点过阈值，冷却窗口就是把这些点算成一次。
    pub fn on_sample(&mut self, plate: Plate, raw: u16, now: Duration) -> Option<HitEvent> {
        if raw <= self.rules.threshold {
            return None;
        }
        let slot = plate.slot();
        if let Some(last) = self.last_hit[slot] {
            if now.saturating_sub(last) < self.rules.hit_cooldown {
                return None;
            }
        }
        self.last_hit[slot] = Some(now);
        self.hits = self.hits.saturating_add(1);
        self.plate_hits[slot] = self.plate_hits[slot].saturating_add(1);
        let before = self.hp;
        self.hp = self.hp.saturating_sub(self.rules.damage_per_hit);
        Some(HitEvent {
            plate,
            raw,
            hp: self.hp,
            // 是"这一击打死了"，不是"打完之后已经死了"：已经 0 血以后继续挨打不该
            // 每次都报一次死亡，否则现场日志会被刷屏、上报也会抖。
            dead: self.hp == 0 && before > 0,
            at: now,
        })
    }
    /// 这块装甲板这一刻该显示什么。
    ///
    /// 整车死亡优先于一切：死了四路全黑。否则只有被打的那一路在 50 ms 窗口内全黑。
    #[must_use]
    pub fn strip(&self, plate: Plate, now: Duration) -> Strip {
        if self.dead() {
            return Strip::Black;
        }
        if let Some(last) = self.last_hit[plate.slot()] {
            if now.saturating_sub(last) < self.rules.hit_blink {
                return Strip::Black;
            }
        }
        Strip::Color(self.color)
    }
    /// 四路灯带这一刻的输出，按 index 排列 —— 固件照着它刷 RMT。
    #[must_use]
    pub fn strips(&self, now: Duration) -> [Strip; 4] {
        Plate::ALL.map(|plate| self.strip(plate, now))
    }
    /// 复位成"新一局"：满血、清计数、清冷却（颜色不动）。
    pub fn reset(&mut self) {
        self.hp = self.rules.max_hp;
        self.hits = 0;
        self.plate_hits = [0; 4];
        self.last_hit = [None; 4];
    }
    /// 要上报给裁判端的四条记录。
    ///
    /// 整车一条血量，所以四条 `hp` 相同、`index` 分别是 0..3；裁判端按
    /// [`protocol::ArmorHealth::team`] 把这里的数据归到对应队伍。
    #[must_use]
    pub fn reports(&self, team: u8) -> [ArmorHealth; 4] {
        Plate::ALL.map(|plate| ArmorHealth {
            team,
            index: plate.index(),
            hp: self.hp,
        })
    }
    /// 四条记录编码成可以直接 `sendto` 的字节串。
    #[must_use]
    pub fn datagrams(&self, team: u8) -> Vec<Vec<u8>> {
        self.datagrams_from(team, 0)
    }
    /// 同 [`datagrams`](Self::datagrams)，但帧头带上板子自己的 id（由 MAC 派生）。
    ///
    /// 用 `sender_id` 而不是默认的 0：0 是裁判终端的保留 id，抓包时一块装甲板发的
    /// 包不该长得像裁判端发的。
    #[must_use]
    pub fn datagrams_from(&self, team: u8, sender_id: u32) -> Vec<Vec<u8>> {
        self.reports(team)
            .iter()
            .map(|report| report.encode_from(sender_id))
            .collect()
    }
 }
 /// 上报节奏：血量一变立刻发，没变就按心跳周期重发。
 ///
 /// 裁判终端只看得到最后一条，"每 200 ms 重发"是它判断板子还在线的唯一依据 ——
 /// 没有心跳，一次丢包就会让界面显示成"装甲板未接入"。
 #[derive(Debug, Clone)]
 pub struct ReportSchedule {
    heartbeat: Duration,
    last: Option<(u16, Duration)>,
 }
 impl ReportSchedule {
    /// `heartbeat` 是血量不变时的重发周期。
    #[must_use]
    pub fn new(heartbeat: Duration) -> Self {
        Self {
            heartbeat,
            last: None,
        }
    }
    /// 这一刻该不该发。
    #[must_use]
    pub fn due(&self, hp: u16, now: Duration) -> bool {
        match self.last {
            None => true,
            Some((last_hp, last_at)) => {
                last_hp != hp || now.saturating_sub(last_at) >= self.heartbeat
            }
        }
    }
    /// 记下"这一刻用这个血量发过了"。
    pub fn mark_sent(&mut self, hp: u16, now: Duration) {
        self.last = Some((hp, now));
    }
 }
 /// 按键事件。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum ButtonEvent {
    /// 什么都没发生。
    None,
    /// 短按（按下后很快松开）：固件用它打印一次状态并立刻重发上报。
    Click,
    /// 长按（按住到阈值）：固件用它复位血量，也就是"新一局"。
    LongPress,
 }
 /// 按键状态机：去抖 + 短按 / 长按，事件只发一次。
 ///
 /// 参考实现移植了 OneButton 2.6.1 的整套状态机（它还带双击、多击、idle 回调）。
 /// 这里只有两种动作，所以按同样的语义重写了一个本地版本：电平去抖，长按在按住
 /// 到阈值时立刻产生一次且不重复，松开时若在短按窗口内则产生一次短按。
 #[derive(Debug, Clone)]
 pub struct Button {
    debounce: Duration,
    click_max: Duration,
    long_press: Duration,
    stable_pressed: bool,
    candidate: bool,
    candidate_since: Duration,
    pressed_since: Duration,
    long_fired: bool,
 }
 impl Default for Button {
    /// BOOT 键（GPIO9，低有效）的现场取值：去抖 20 ms、短按 <500 ms、长按 ≥500 ms。
    fn default() -> Self {
        Self::new(
            Duration::from_millis(20),
            Duration::from_millis(500),
            Duration::from_millis(500),
        )
    }
 }
 impl Button {
    /// 自定义时间参数，主要给测试用。
    #[must_use]
    pub fn new(debounce: Duration, click_max: Duration, long_press: Duration) -> Self {
        Self {
            debounce,
            click_max,
            long_press,
            stable_pressed: false,
            candidate: false,
            candidate_since: Duration::ZERO,
            pressed_since: Duration::ZERO,
            long_fired: false,
        }
    }
    /// 喂一次电平（已换算成"是否按下"）与当前时刻，最多产生一个事件。
    pub fn tick(&mut self, pressed: bool, now: Duration) -> ButtonEvent {
        let mut event = ButtonEvent::None;
        if pressed != self.stable_pressed {
            if self.candidate != pressed {
                // 抖动的新电平：重新开始计稳定时间。
                self.candidate = pressed;
                self.candidate_since = now;
            } else if now.saturating_sub(self.candidate_since) >= self.debounce {
                self.stable_pressed = pressed;
                if pressed {
                    self.pressed_since = now;
                    self.long_fired = false;
                } else if !self.long_fired
                    && now.saturating_sub(self.pressed_since) < self.click_max
                {
                    event = ButtonEvent::Click;
                }
            }
        } else {
            // 电平回到稳定值，候选作废。
            self.candidate = pressed;
        }
        if event == ButtonEvent::None
            && self.stable_pressed
            && !self.long_fired
            && now.saturating_sub(self.pressed_since) >= self.long_press
        {
            self.long_fired = true;
            event = ButtonEvent::LongPress;
        }
        event
    }
 }
 /// 解析编译期注入的 `ARMOR_TEAM`。
 ///
 /// 只接受 "0" 与 "1"：把队伍认错会让裁判端把血记到对手头上，现场很难发现，
 /// 所以宁可启动就报错。
 #[must_use]
 pub fn parse_team(value: &str) -> Option<u8> {
    match value.trim() {
        "0" => Some(TEAM_1),
        "1" => Some(TEAM_2),
        _ => None,
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    fn ms(v: u64) -> Duration {
        Duration::from_millis(v)
    }
    fn armor() -> Armor {
        Armor::new(Rules::default(), Rgb::for_team(TEAM_1))
    }
    // ---------------------------------------------------------------- 血量 --
    #[test]
    fn starts_at_full_hp_and_is_not_dead() {
        let a = armor();
        assert_eq!(a.hp(), 100);
        assert!(!a.dead());
        assert_eq!(a.hits(), 0);
    }
    #[test]
    fn each_hit_costs_three_and_floors_at_zero() {
        let mut a = armor();
        let mut hits = 0;
        // 100 / 3 = 33.33，所以第 34 击才归零。
        for i in 0..34 {
            let at = ms(i * 1000);
            a.on_sample(Plate::Front, 2500, at).expect("hit should count");
            hits += 1;
        }
        assert_eq!(hits, 34);
        assert_eq!(a.hp(), 0);
        assert!(a.dead());
        // 已经归零之后继续打，不会变负，也不算"新的一击导致死亡"。
        let event = a
            .on_sample(Plate::Rear, 2500, ms(40_000))
            .expect("still counts as a hit");
        assert_eq!(event.hp, 0);
        assert!(!event.dead, "0 -> 0 不是新的死亡事件");
        assert_eq!(a.hp(), 0);
    }
    #[test]
    fn sample_below_threshold_is_not_a_hit() {
        let mut a = armor();
        assert!(a.on_sample(Plate::Front, 2000, ms(0)).is_none(), "阈值是严格大于");
        assert!(a.on_sample(Plate::Front, 1999, ms(0)).is_none());
        assert!(a.on_sample(Plate::Front, 2001, ms(0)).is_some());
        assert_eq!(a.hp(), 97);
    }
    #[test]
    fn per_plate_hit_counts_are_separate() {
        let mut a = armor();
        a.on_sample(Plate::Front, 3000, ms(0));
        a.on_sample(Plate::Left, 3000, ms(1000));
        a.on_sample(Plate::Left, 3000, ms(2000));
        assert_eq!(a.plate_hits(Plate::Front), 1);
        assert_eq!(a.plate_hits(Plate::Left), 2);
        assert_eq!(a.plate_hits(Plate::Rear), 0);
        assert_eq!(a.plate_hits(Plate::Right), 0);
        assert_eq!(a.hits(), 3);
        // 整车一条血量：三击共扣 9。
        assert_eq!(a.hp(), 91);
    }
    // ------------------------------------------------------------ 受击去抖 --
    #[test]
    fn repeat_samples_inside_the_cooldown_are_one_hit() {
        let mut a = armor();
        // 40 kHz 采样下，一次击打会连续几十个点过阈值。
        for i in 0..49 {
            a.on_sample(Plate::Left, 2600, ms(i));
        }
        assert_eq!(a.plate_hits(Plate::Left), 1, "49 ms 内的连续采样算一次");
        assert_eq!(a.hp(), 97);
    }
    #[test]
    fn a_sample_after_the_cooldown_is_a_new_hit() {
        let mut a = armor();
        a.on_sample(Plate::Left, 2600, ms(0));
        assert!(a.on_sample(Plate::Left, 2600, ms(49)).is_none());
        assert!(a.on_sample(Plate::Left, 2600, ms(50)).is_some(), "50 ms 是边界，算新受击");
        assert_eq!(a.plate_hits(Plate::Left), 2);
        assert_eq!(a.hp(), 94);
    }
    #[test]
    fn cooldown_is_per_plate_not_global() {
        let mut a = armor();
        // 参考实现用全局冷却：一块板挨打后，别块板在这 50 ms 内的击打会被吃掉。
        // 每板独立冷却才是"每面各自挨打"的正确语义。
        a.on_sample(Plate::Front, 3000, ms(0));
        assert!(a.on_sample(Plate::Left, 3000, ms(1)).is_some());
        assert!(a.on_sample(Plate::Rear, 3000, ms(2)).is_some());
        assert_eq!(a.hits(), 3);
        assert_eq!(a.hp(), 91);
    }
    // ------------------------------------------------------------ 灯带输出 --
    #[test]
    fn hit_plate_goes_black_for_fifty_ms_only() {
        let mut a = armor();
        a.on_sample(Plate::Left, 3000, ms(1000));
        assert!(a.strip(Plate::Left, ms(1000)).is_black(), "受击瞬间");
        assert!(a.strip(Plate::Left, ms(1049)).is_black(), "窗口内");
        assert_eq!(
            a.strip(Plate::Left, ms(1050)),
            Strip::Color(Rgb::RED),
            "窗口结束恢复原色"
        );
        // 其余三路全程不受影响 —— 这正是每面独立灯带的意义。
        for plate in [Plate::Front, Plate::Rear, Plate::Right] {
            assert_eq!(a.strip(plate, ms(1000)), Strip::Color(Rgb::RED));
            assert_eq!(a.strip(plate, ms(1049)), Strip::Color(Rgb::RED));
        }
    }
    #[test]
    fn dead_blacks_out_every_strip() {
        let mut a = armor();
        let last = 34 * 1000;
        for i in 0..34 {
            a.on_sample(Plate::Front, 3000, ms(i * 1000));
        }
        assert!(a.dead());
        for plate in Plate::ALL {
            assert!(a.strip(plate, ms(last)).is_black(), "{plate:?} 死了要全黑");
        }
        // 冷却窗口早就过了，仍然全黑：死优先于一切。
        assert!(a.strip(Plate::Left, ms(last + 10_000)).is_black());
    }
    #[test]
    fn strips_returns_all_four_in_index_order() {
        let mut a = armor();
        a.on_sample(Plate::Rear, 3000, ms(0));
        let strips = a.strips(ms(0));
        assert_eq!(strips.len(), 4);
        assert!(strips[Plate::Rear.index() as usize].is_black());
        assert_eq!(strips[Plate::Front.index() as usize].color(), Rgb::RED);
    }
    // ---------------------------------------------------------------- 复位 --
    #[test]
    fn reset_restores_full_hp_and_keeps_the_colour() {
        let mut a = armor();
        a.on_sample(Plate::Front, 3000, ms(0));
        a.on_sample(Plate::Right, 3000, ms(100));
        a.set_color(Rgb::BLUE);
        a.reset();
        assert_eq!(a.hp(), 100);
        assert_eq!(a.hits(), 0);
        assert_eq!(a.plate_hits_all(), [0; 4]);
        assert_eq!(a.color(), Rgb::BLUE);
        assert_eq!(a.strip(Plate::Front, ms(100)), Strip::Color(Rgb::BLUE));
    }
    // ---------------------------------------------------------------- 上报 --
    #[test]
    fn reports_carry_the_shared_hp_on_all_four_indices() {
        let mut a = armor();
        a.on_sample(Plate::Front, 3000, ms(0));
        a.on_sample(Plate::Front, 3000, ms(1000));
        let reports = a.reports(TEAM_2);
        assert_eq!(reports.len(), 4);
        for (i, report) in reports.iter().enumerate() {
            assert_eq!(report.team, TEAM_2);
            assert_eq!(report.index, i as u8, "四格按 index 排列");
            assert_eq!(report.hp, 94, "整车一条血量，四格同值");
        }
    }
    #[test]
    fn datagrams_round_trip_through_the_shared_protocol() {
        let mut a = armor();
        a.on_sample(Plate::Left, 3000, ms(0));
        let datagrams = a.datagrams(TEAM_1);
        assert_eq!(datagrams.len(), 4);
        for (i, bytes) in datagrams.iter().enumerate() {
            // 裁判端就是用这个函数解回来的，编码错了这里立刻挂。
            let decoded = ArmorHealth::decode(bytes).expect("裁判端要能解出来");
            assert_eq!(decoded.team, TEAM_1);
            assert_eq!(decoded.index, i as u8);
            assert_eq!(decoded.hp, 97);
            assert_eq!(bytes.len(), protocol::HEADER_LEN + 4);
            assert_eq!(bytes[4], MsgType::ArmorHealth as u8);
        }
    }
    #[test]
    fn datagrams_can_carry_the_board_id() {
        let a = armor();
        let datagrams = a.datagrams_from(TEAM_2, 0xABCD_1234);
        for bytes in &datagrams {
            let header = protocol::decode_header(bytes).expect("帧头可解");
            assert_eq!(header.sender_id, 0xABCD_1234);
            assert_eq!(ArmorHealth::decode(bytes).map(|r| r.team), Some(TEAM_2));
        }
        // 默认入口仍然是裁判终端的保留 id 0。
        let plain = a.datagrams(TEAM_2);
        assert_eq!(
            protocol::decode_header(&plain[0]).map(|h| h.sender_id),
            Some(0)
        );
    }
    #[test]
    fn report_schedule_fires_immediately_then_heartbeats() {
        let mut s = ReportSchedule::new(ms(200));
        assert!(s.due(100, ms(0)), "第一次一定发");
        s.mark_sent(100, ms(0));
        assert!(!s.due(100, ms(199)));
        assert!(s.due(100, ms(200)), "心跳到期");
        // 血量变化不等心跳。
        assert!(s.due(97, ms(201)));
        s.mark_sent(97, ms(201));
        assert!(!s.due(97, ms(250)));
        assert!(s.due(94, ms(251)));
    }
    // ---------------------------------------------------------------- 按键 --
    #[test]
    fn button_needs_the_debounce_window() {
        let mut b = Button::new(ms(20), ms(500), ms(500));
        assert_eq!(b.tick(true, ms(0)), ButtonEvent::None);
        assert_eq!(b.tick(false, ms(5)), ButtonEvent::None, "5 ms 的毛刺不算按下");
        assert_eq!(b.tick(true, ms(10)), ButtonEvent::None);
        // 从 10 ms 起连续按下到 30 ms 才稳定。
        assert_eq!(b.tick(true, ms(29)), ButtonEvent::None);
        assert_eq!(b.tick(true, ms(30)), ButtonEvent::None, "按下本身不产生事件");
    }
    #[test]
    fn short_press_is_a_click() {
        let mut b = Button::new(ms(20), ms(500), ms(500));
        b.tick(true, ms(0));
        b.tick(true, ms(20)); // 稳定按下
        b.tick(false, ms(100));
        assert_eq!(b.tick(false, ms(120)), ButtonEvent::Click);
        // 只发一次。
        assert_eq!(b.tick(false, ms(200)), ButtonEvent::None);
    }
    #[test]
    fn holding_produces_one_long_press_and_no_click_on_release() {
        let mut b = Button::new(ms(20), ms(500), ms(500));
        b.tick(true, ms(0));
        b.tick(true, ms(20)); // 稳定按下
        assert_eq!(b.tick(true, ms(400)), ButtonEvent::None);
        assert_eq!(b.tick(true, ms(520)), ButtonEvent::LongPress, "按住到阈值");
        assert_eq!(b.tick(true, ms(900)), ButtonEvent::None, "不回弹重复长按");
        b.tick(false, ms(1000));
        assert_eq!(
            b.tick(false, ms(1020)),
            ButtonEvent::None,
            "长按过的这一下不该再算短按"
        );
    }
    // ---------------------------------------------------------------- 其它 --
    #[test]
    fn colours_match_the_robo_master_convention() {
        assert_eq!(Rgb::for_team(TEAM_1), Rgb::RED);
        assert_eq!(Rgb::for_team(TEAM_2), Rgb::BLUE);
        // 存 NVS / 打印与 Adafruit_NeoPixel::Color 的打包一致。
        assert_eq!(Rgb::RED.to_u32(), 0x00FF_0000);
        assert_eq!(Rgb::BLUE.to_u32(), 0x0000_00FF);
        assert_eq!(Rgb::from_u32(0x0012_3456), Rgb(0x12, 0x34, 0x56));
    }
    #[test]
    fn ws2812_byte_order_is_grb() {
        assert_eq!(Rgb::RED.to_grb(), [0x00, 0xFF, 0x00]);
        assert_eq!(Rgb::BLUE.to_grb(), [0x00, 0x00, 0xFF]);
        assert_eq!(Rgb(0x11, 0x22, 0x33).to_grb(), [0x22, 0x11, 0x33]);
    }
    #[test]
    fn plate_indices_are_stable() {
        assert_eq!(Plate::Front.index(), 0);
        assert_eq!(Plate::Rear.index(), 1);
        assert_eq!(Plate::Left.index(), 2);
        assert_eq!(Plate::Right.index(), 3);
        for plate in Plate::ALL {
            assert_eq!(Plate::from_index(plate.index()), Some(plate));
        }
        assert_eq!(Plate::from_index(4), None);
    }
    #[test]
    fn team_env_parsing_rejects_anything_but_zero_and_one() {
        assert_eq!(parse_team("0"), Some(TEAM_1));
        assert_eq!(parse_team("1"), Some(TEAM_2));
        assert_eq!(parse_team(" 1\n"), Some(TEAM_2));
        assert_eq!(parse_team("2"), None);
        assert_eq!(parse_team("team1"), None);
        assert_eq!(parse_team(""), None);
    }
 }
@@ -1,13 +0,0 @@
 # This crate builds for the host, not the ESP32.
 #
 # It sits inside the firmware's directory tree, so cargo walks up and inherits
 # ../.cargo/config.toml, which pins `target = "xtensa-esp32s3-espidf"` and an
 # ldproxy linker that only work inside the ESP-IDF cross build. Without this file
 # the desktop client is cross-compiled for Xtensa, which fails deep inside
 # dependencies (libc not finding MAP_FAILED and friends, because it was being
 # compiled for an embedded target that has no mmap).
 #
 # Overriding the target back to the host triple is the whole fix. Nothing else in
 # the parent config applies to a non-ESP target.
 [build]
 target = "aarch64-apple-darwin"
@@ -1,29 +0,0 @@
 [package]
 name = "cam-client"
 version = "0.1.0"
 edition = "2021"
 [build-dependencies]
 # Compiles ui/camera.slint into Rust before the crate itself builds. Kept separate
 # from [dependencies] because it only runs on the build host, never on the target.
 slint-build = "1"
 [dependencies]
 # Shared wire format with the firmware. Kept as a path dependency rather than
 # copied, so the two sides cannot drift apart silently.
 protocol = { path = "../protocol" }
 # Slint for the UI. The default renderer on macOS is femtovg, which needs no
 # extra system libraries; `backend-winit` provides the window integration.
 slint = "1"
 # JPEG decoding for display. Slint's Image can take raw RGBA, so the JPEG has to
 # be decoded somewhere - `image` does that, and nothing on this side re-encodes.
 image = { version = "0.25", default-features = false, features = ["jpeg"] }
 anyhow = "1"
 log = "0.4"
 env_logger = "0.11"
 [profile.release]
 opt-level = 2
@@ -1,158 +0,0 @@
 # cam-client
 [ESP32-S3 摄像头固件](../README.md) 的桌面查看器。接收 UDP 数据报形式的 JPEG 帧，
 解码后显示实时画面，并给出帧率与丢帧统计。
 Rust + [Slint](https://slint.dev)，不需要额外的系统库。
 ## 环境要求
 - Rust（普通工具链——**不要**用固件那个 `esp` 工具链）
 - 已在运行本固件的摄像头，且能在 2.4GHz WiFi 下访问到
 ## 目标架构
 **编译前先设好。** 本目录位于固件源码树内部，Cargo 否则会继承
 `../.cargo/config.toml` 去交叉编译 `xtensa-esp32s3-espidf`——报错会出现在依赖
 深处，而不是一眼可见的地方。
 `client/.cargo/config.toml` 因此把目标钉成宿主架构：
 ```toml
 [build]
 target = "aarch64-apple-darwin"    # Intel Mac：x86_64-apple-darwin
                                   # Linux：rustc -vV | grep host 的输出
 ```
 查看你的：
 ```sh
 rustc -vV | grep host
 ```
 ## 编译
 ```sh
 cargo build --release
 ```
 因为上面的 target 覆盖，二进制落在带架构名的目录里：
 ```sh
 ./target/aarch64-apple-darwin/release/cam-client
 ```
 ## 运行
 ```sh
 ./target/aarch64-apple-darwin/release/cam-client                    # 用下面的默认值
 ./target/aarch64-apple-darwin/release/cam-client 192.168.1.139
 ./target/aarch64-apple-darwin/release/cam-client 192.168.1.139 5600
 ```
 ```
 用法: cam-client [CAMERA_IP] [PORT]
  CAMERA_IP   ESP32 摄像头地址（默认 192.168.1.139）
  PORT        UDP 视频端口  （默认 5600）
 ```
 改 UI 时：
 ```sh
 cargo run --release -- 192.168.1.139
 ```
 ## 界面读数
 ```
 streaming            20.8 fps   10.1 kB per frame   35 ms between frames
 640x480              shown 146   dropped 0 (0.0%)   1270 datagrams
 ```
 丢帧率的存在是有理由的。这条链路**整帧丢弃而不重试**，所以单看帧率是有歧义的：
 | 帧率 | 丢帧 | 判断 |
 |---|---|---|
 | 达到传感器上限 | 0 | 链路正常，瓶颈是传感器 |
 | 远低于上限 | 有 | 瓶颈是网络 |
 | 低 | 0，且显示 "no frames - camera?" | 板子没在推流 |
 状态文字的颜色是同一信息的粗略版本：推流中绿色，否则琥珀色。
 ### 帧率是"计数"算出来的，不是"平均间隔"
 不是对帧间隔取平均。一次 UI 轮询之间可能已完成好几帧，所以平均间隔量的是
 **显示**的刷新快慢，而不是**相机**的出帧快慢——那曾把上限 22fps 的传感器报成
 36fps。一个笃定的错误数字比没有数字更糟。
 ## 诊断
 ```sh
 RUST_LOG=info ./target/aarch64-apple-darwin/release/cam-client 192.168.1.139
 ```
 ```
 frames shown 146 | dropped 0 (0.0%) | datagrams 1270 | undecodable 0 | short 0
 ```
 | 计数器 | 含义 |
 |---|---|
 | `frames shown` | 完整重组并交给界面的帧 |
 | `dropped` | 因分片缺失而被放弃的帧 |
 | `datagrams` | 能解析为分片的数据报 |
 | `undecodable` | 收到了但解析不了的数据报 |
 `undecodable` 非零意味着板子的数据报**到了但没看懂**——是协议或端口对不上，不是网络
 问题。这两者很容易混淆，而这个计数器正是用来区分它们的。
 ## 排查
 | 现象 | 原因 |
 |---|---|
 | 一直显示 `connecting to …` | 板子不在网上，或防火墙拦了入站 UDP 5600 |
 | `no frames - camera?` | 板子停止推流：重启了，或掉线了 |
 | 完全没有输出，也没有日志 | host triple 不对，见[目标架构](#目标架构) |
 | 只有第一帧然后卡住 | 另一个客户端连在别的端口上；板子只推给最后宣告的那个 |
 | 颜色错乱 | 通道顺序。当前构建用 `Rgba8Pixel`，另一个选项是 `Bgra8Pixel` |
 | 编译在 `libc` / `memmap2` 报错 | 用的是 `esp` 工具链，或缺少 target triple 覆盖 |
 ## 目录结构
 ```
 client/
 ├── Cargo.toml
 ├── build.rs                 编译 ui/camera.slint
 ├── ui/camera.slint          窗口定义
 └── src/
    ├── main.rs              命令行、线程编排、统计
    └── receiver.rs          socket、重组、JPEG 解码
 ```
 线路格式在 [`../protocol`](../protocol)，与固件共用，两端不会漂移。
 ## 线程模型
 三个线程，且**没有任何 worker 线程碰 Slint 组件**：
 | 线程 | 职责 |
 |---|---|
 | `udp-reader` | `recv_from`、解析、重组 |
 | `jpeg-decode` | JPEG → RGBA |
 | 主线程（事件循环） | RGBA → `slint::Image`、更新属性，每 30ms 一次 |
 这是 Slint 的硬性约束而非偏好：组件只能在拥有它的线程上使用，`Weak<App>` 是
 `!Send` 就是为了强制这一点。worker 线程去 upgrade 一个 weak handle 会拿到 `None`
 然后什么都不做——现象和"界面卡死"完全一样。
 解码单独一个线程，是因为一张 VGA 的 JPEG 要花几毫秒，放在收包线程里会挤进数据报
 之间，造成**链路上本不存在**的丢帧。
 ## 可调项
 | 项目 | 位置 | 说明 |
 |---|---|---|
 | 轮询间隔 | `src/main.rs` 的 `UI_POLL` | 30ms。更快只是白费 CPU，不会多出帧。 |
 | 帧率统计窗口 | `FPS_WINDOW` | 2 秒。在 ~22fps 下更短的窗口会量化失真。 |
 | 帧超时 | `receiver.rs` 的 `FRAME_TIMEOUT` | 500ms。一帧约 40ms，更慢的就是丢了。 |
 | 宣告间隔 | `ANNOUNCE_INTERVAL` | 500ms。同时兼作保活。 |
 | 主题 | `build.rs` | 默认 `fluent`；可试 `fluent-dark`、`material`、`native`。 |
@@ -1,10 +0,0 @@
 //! Compiles the Slint markup and writes the generated Rust.
 //!
 //! Without this, `slint::include_modules!` has nothing to expand to: it reads the
 //! path to the generated file from an environment variable that only this build
 //! script sets.
 fn main() {
    let config = slint_build::CompilerConfiguration::new().with_style("fluent".to_owned());
    slint_build::compile_with_config("ui/camera.slint", config).expect("compiling ui/camera.slint");
 }
@@ -1,310 +0,0 @@
 //! 绑定配置：这个客户端是什么身份，以及看哪块板子。
 //!
 //! 队伍的"选定后不可更改"落在 [`Config::camera_id`] 上：首次运行时从发现列表里选，
 //! 结果写进配置文件，之后直接读，不再询问。
 //!
 //! 用 TOML 而不是 JSON，因为这个文件是**给人看的**——现场排查时要能一眼看懂改了什么。
 //! 而它只有十来个字段，不值得为它引入整个序列化框架。
 use std::path::{Path, PathBuf};
 use anyhow::{Context, Result};
 /// 客户端身份。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Role {
    /// 队伍终端：一块画面 + 自己那一边的血量。
    Team,
    /// 裁判终端：两块画面 + 双方血量。
    Referee,
 }
 impl Role {
    pub fn as_str(self) -> &'static str {
        match self {
            Role::Team => "team",
            Role::Referee => "referee",
        }
    }
    pub fn parse(s: &str) -> Option<Self> {
        match s {
            "team" => Some(Role::Team),
            "referee" => Some(Role::Referee),
            _ => None,
        }
    }
    pub fn to_protocol(self) -> protocol::SubscribeRole {
        match self {
            Role::Team => protocol::SubscribeRole::Team,
            Role::Referee => protocol::SubscribeRole::Referee,
        }
    }
 }
 /// 磁盘上的配置。
 #[derive(Debug, Clone)]
 pub struct Config {
    /// 客户端身份。
    pub role: Role,
    /// 队伍端：自己属于哪一边，0 = 队伍一，1 = 队伍二。
    ///
    /// 决定血量栏显示哪一边。裁判端两个都要，所以忽略这个值。
    pub team: u8,
    /// 绑定的板子 id（MAC 派生，重启不变）。
    ///
    /// `None` 表示还没选过，首次运行会在界面上询问。
    pub camera_id: Option<u32>,
    /// 板子的 IP。DHCP 可能变，所以这只是发现阶段的一个提示。
    pub camera_addr: Option<std::net::Ipv4Addr>,
 }
 impl Default for Config {
    /// 默认当裁判机：它不需要任何配置就能用，是现场最省事的起点。
    fn default() -> Self {
        Self {
            role: Role::Referee,
            team: 0,
            camera_id: None,
            camera_addr: None,
        }
    }
 }
 impl Config {
    /// 从磁盘读取。
    ///
    /// 文件不存在时返回默认配置，这是正常路径——首次运行本来就没有配置。
    pub fn load(path: &Path) -> Result<Self> {
        if !path.exists() {
            log::info!("no config at {}; starting with defaults", path.display());
            return Ok(Self::default());
        }
        let text = std::fs::read_to_string(path)
            .with_context(|| format!("reading {}", path.display()))?;
        Self::parse(&text).with_context(|| format!("parsing {}", path.display()))
    }
    /// 写入磁盘。
    ///
    /// 手写序列化而不是引入 toml crate：这个文件只有十来个字段，且格式必须与
    /// [`Config::parse`] 严格对称——两份代码比一个依赖更容易在 review 时看出不匹配。
    pub fn save(&self, path: &Path) -> Result<()> {
        if let Some(dir) = path.parent() {
            std::fs::create_dir_all(dir)
                .with_context(|| format!("creating {}", dir.display()))?;
        }
        let mut out = String::new();
        out.push_str("# cam-client 配置。\n");
        out.push_str("#\n");
        out.push_str("# role  : team | referee\n");
        out.push_str("#         team    = 一路画面 + 自己那一边的血量，需要绑定一块板子\n");
        out.push_str("#         referee = 两路画面 + 双方血量，不需要绑定\n");
        out.push_str("# team  : 0 = 队伍一, 1 = 队伍二（仅 team 端用）\n");
        out.push_str("#\n");
        out.push_str("# 绑定之后不要再改 camera_id：队伍端按它选画面，改了就换了视角。\n");
        out.push_str("# camera_id 由板子的 MAC 派生，重启后不变，所以这个绑定是稳的。\n\n");
        out.push_str(&format!("role = \"{}\"\n", self.role.as_str()));
        out.push_str(&format!("team = {}\n", self.team));
        if let Some(id) = self.camera_id {
            out.push_str(&format!("camera_id = \"0x{id:08X}\"\n"));
        }
        if let Some(addr) = self.camera_addr {
            out.push_str(&format!("camera_addr = \"{addr}\"\n"));
        }
        std::fs::write(path, out).with_context(|| format!("writing {}", path.display()))?;
        log::info!("saved config to {}", path.display());
        Ok(())
    }
    /// 解析 TOML 的一个子集。
    ///
    /// 只支持 `key = value`、字符串、`整数`、十六进制字符串和注释——恰好是这个文件
    /// 需要的全部，遇到不认识的形式会明确报错而不是静默忽略，因为静默忽略会让一个
    /// 打错的配置看起来像是生效了。
    fn parse(text: &str) -> Result<Self> {
        let mut config = Config::default();
        let mut role_seen = false;
        for (lineno, raw) in text.lines().enumerate() {
            let line = strip_comment(raw).trim();
            if line.is_empty() {
                continue;
            }
            let Some((key, value)) = line.split_once('=') else {
                anyhow::bail!("line {}: expected `key = value`, got {line:?}", lineno + 1);
            };
            let key = key.trim();
            let value = value.trim().trim_matches('"');
            match key {
                "role" => {
                    config.role = Role::parse(value).ok_or_else(|| {
                        anyhow::anyhow!(
                            "line {}: role must be `team` or `referee`, got {value:?}",
                            lineno + 1
                        )
                    })?;
                    role_seen = true;
                }
                "team" => {
                    config.team = value
                        .parse::<u8>()
                        .with_context(|| format!("line {}: team must be 0 or 1", lineno + 1))?;
                }
                "camera_id" => {
                    config.camera_id = Some(parse_id(value).with_context(|| {
                        format!("line {}: camera_id must look like 0x1A2B3C4D", lineno + 1)
                    })?);
                }
                "camera_addr" => {
                    config.camera_addr = Some(value.parse().with_context(|| {
                        format!("line {}: camera_addr must be an IPv4 address", lineno + 1)
                    })?);
                }
                _ => {
                    anyhow::bail!(
                        "line {}: unknown key {key:?}; refusing to guess",
                        lineno + 1
                    );
                }
            }
        }
        if !role_seen {
            // 缺 role 时按裁判端处理：它是唯一无需配置就能工作的模式。
            config.role = Role::Referee;
        }
        Ok(config)
    }
 }
 /// 去掉 `#` 之后的内容。
 fn strip_comment(line: &str) -> &str {
    match line.find('#') {
        Some(at) => &line[..at],
        None => line,
    }
 }
 /// 解析 `0x1A2B3C4D` 或十进制形式的板子 id。
 fn parse_id(text: &str) -> Result<u32> {
    let text = text.trim();
    if let Some(hex) = text.strip_prefix("0x").or_else(|| text.strip_prefix("0X")) {
        u32::from_str_radix(hex, 16).with_context(|| format!("{text:?} is not hex"))
    } else {
        text.parse::<u32>()
            .with_context(|| format!("{text:?} is not a number"))
    }
 }
 /// 默认配置文件位置。
 ///
 /// 优先 `$XDG_CONFIG_HOME` 或 `~/.config`，与 Linux 上其它工具一致；macOS 上用同一个
 /// 路径而不是 `~/Library/Application Support`，是为了让两台机器（裁判机和队伍机可能
 /// 是不同系统）的配置结构一致。
 pub fn default_config_path() -> PathBuf {
    let base = std::env::var_os("XDG_CONFIG_HOME")
        .map(PathBuf::from)
        .filter(|p| !p.as_os_str().is_empty())
        .unwrap_or_else(|| {
            let home = std::env::var_os("HOME").map(PathBuf::from).unwrap_or_else(|| {
                PathBuf::from(".")
            });
            home.join(".config")
        });
    base.join("cam-client").join("config.toml")
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn parses_a_team_config() {
        let config = Config::parse(
            r#"
            # 队伍一的机器
            role = "team"
            team = 1
            camera_id = "0x3D4D8A9A"
            "#,
        )
        .expect("parses");
        assert_eq!(config.role, Role::Team);
        assert_eq!(config.team, 1);
        assert_eq!(config.camera_id, Some(0x3D4D_8A9A));
        assert!(config.is_bound());
    }
    #[test]
    fn referee_needs_no_binding() {
        let config = Config::parse("role = \"referee\"").expect("parses");
        assert_eq!(config.role, Role::Referee);
        assert!(config.is_bound(), "the referee watches everything");
    }
    #[test]
    fn a_team_without_a_camera_is_unbound() {
        let config = Config::parse("role = \"team\"\nteam = 0").expect("parses");
        assert_eq!(config.role, Role::Team);
        assert!(!config.is_bound(), "must ask which camera to watch");
    }
    #[test]
    fn roundtrips_through_save_and_load() {
        let mut dir = std::env::temp_dir();
        dir.push(format!("cam-client-test-{}", std::process::id()));
        let path = dir.join("nested").join("config.toml");
        let config = Config {
            role: Role::Team,
            team: 1,
            camera_id: Some(0x1234_5678),
            camera_addr: Some("192.168.1.50".parse().unwrap()),
        };
        config.save(&path).expect("saves");
        let loaded = Config::load(&path).expect("loads");
        assert_eq!(loaded.role, config.role);
        assert_eq!(loaded.team, config.team);
        assert_eq!(loaded.camera_id, config.camera_id);
        assert_eq!(loaded.camera_addr, config.camera_addr);
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn a_missing_file_is_the_default_not_an_error() {
        let config = Config::load(Path::new("/nonexistent/cam-client/config.toml"))
            .expect("a missing config is a normal first run");
        assert_eq!(config.role, Role::Referee);
    }
    #[test]
    fn refuses_garbage_instead_of_ignoring_it() {
        // 静默忽略一个打错的 key，会让配置看起来生效了。
        assert!(Config::parse("rol = \"team\"").is_err(), "unknown key");
        assert!(Config::parse("role = \"camera\"").is_err(), "bad role value");
        assert!(Config::parse("role = \"team\"\nteam = nine").is_err(), "bad team");
        assert!(Config::parse("just some text").is_err(), "not key = value");
    }
 }
@@ -1,628 +0,0 @@
 //! ESP32 图传查看器。
 //!
 //! 两种身份，由 [`Role`] 决定：
 //!
 //! - **队伍端** —— 一块画面 + 自己那一边的血量。需要绑定一块板子（选定后不可更改）。
 //! - **裁判端** —— 两块画面左右并排 + 双方血量。不需要绑定。
 //!
 //! 用法：
 //!
 //! ```text
 //! cam-client                      默认裁判端
 //! cam-client --role team --team 1  队伍一
 //! cam-client --camera-id 0x3D4D8A9A 绑定到某块板子
 //! ```
 //!
 //! 绑定与身份存在配置文件里（默认 `~/.config/cam-client/config.toml`）。首次运行
 //! 队伍端会列出发现的摄像头，选定后写入，之后不再询问。
 //!
 //! # 为什么血量是占位符
 //!
 //! 装甲板接口已经预留（[`receiver::ArmorSource`] 与 `protocol::ArmorHealth`），但
 //! 现在没有实现也没有数据源。界面显示占位符而不是 0——0 看起来像真值，现场看到会
 //! 以为对方已经没血了。
 mod config;
 mod receiver;
 use std::error::Error;
 use std::net::Ipv4Addr;
 use std::path::PathBuf;
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 use config::{Config, Role};
 use receiver::{
    decode_frame, ArmorSource, CameraInfo, DecodedFrame, NoArmorYet, Receiver,
    SourceStats, ARMOR_BOARDS,
 };
 slint::include_modules!();
 const USAGE: &str = "\
 用法: cam-client [选项]
  --role <team|referee>   身份。默认 referee（无需配置即可看两路）
  --team <0|1>             自己属于哪一边，仅 team 端用
  --camera-id <0xID>      绑定到某块板子（MAC 派生，重启不变）
  --camera <IP>            向哪块板子发订阅（默认 255.255.255.255 广播）
  --config <路径>          配置文件位置
  --list                   列出发现的摄像头后退出
  -h, --help               显示这段帮助
 ";
 /// 事件循环轮询新数据的间隔。
 ///
 /// 不是每帧一次：显示不需要每秒重绘 22 次，更快只是让事件循环和接收路径抢 CPU。
 const UI_POLL: Duration = Duration::from_millis(33);
 /// 帧率统计窗口。
 ///
 /// 按计数除以墙钟时间，而不是对帧间隔取平均。一次轮询之间可能完成多帧，所以平均间隔
 /// 量的是**显示**的刷新快慢而不是**相机**的出帧快慢——那会把上限 22fps 的传感器
 /// 报成 36fps。一个笃定的错误数字比没有数字更糟。
 const FPS_WINDOW: Duration = Duration::from_secs(2);
 /// 某一路的显示状态。
 struct View {
    /// 显示哪块板子（`None` = 还没有画面）。
    sender_id: Option<u32>,
    fps: f32,
    window_started: Instant,
    window_frames: u64,
    reported: bool,
 }
 impl View {
    fn new() -> Self {
        Self {
            sender_id: None,
            fps: 0.0,
            window_started: Instant::now(),
            window_frames: 0,
            reported: false,
        }
    }
    /// 累计窗口内的帧数，算出帧率。
    fn update_fps(&mut self, stats: &SourceStats) {
        let window = self.window_started.elapsed();
        if window < FPS_WINDOW {
            return;
        }
        self.fps = (stats.frames_shown - self.window_frames) as f32 / window.as_secs_f32();
        self.window_frames = stats.frames_shown;
        self.window_started = Instant::now();
    }
 }
 /// 解码后的画面缓存，供事件循环取用。
 ///
 /// 解码线程只处理纯数据（`Vec<u8>` + 尺寸），`slint::Image` 的构造留在事件循环，
 /// 因为 `slint::Image` 不是 `Send`。
 type DecodedSlots = Arc<Mutex<Vec<(u32, DecodedFrame)>>>;
 fn main() -> Result<(), Box<dyn Error>> {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
    let args = Args::parse(std::env::args().skip(1))?;
    if args.help {
        print!("{USAGE}");
        return Ok(());
    }
    let config_path = args.config.clone().unwrap_or_else(config::default_config_path);
    // 命令行覆盖配置文件，这样现场可以临时当另一台机器用而不用改文件。
    let mut config = Config::load(&config_path)?;
    if let Some(role) = args.role {
        config.role = role;
    }
    if let Some(team) = args.team {
        config.team = team;
    }
    if let Some(id) = args.camera_id {
        config.camera_id = Some(id);
    }
    log::info!(
        "role={} team={} camera_id={:?} config={}",
        config.role.as_str(),
        config.team,
        config.camera_id,
        config_path.display()
    );
    let rx = Arc::new(Receiver::start(
        args.camera,
        config.role.to_protocol(),
    )?);
    let discovery = rx.discovery();
    let frames = rx.frames();
    if args.list {
        // 等几个广播周期，让列表有内容。
        let socket = bind_socket()?;
        let for_list = Arc::clone(&rx);
        let handle = std::thread::spawn(move || for_list.run(socket));
        std::thread::sleep(Duration::from_secs(5));
        let cameras = discovery.online_cameras();
        if cameras.is_empty() {
            println!("没有发现摄像头。板子每 2 秒广播一次，再等等或检查网络。");
        } else {
            println!("发现 {} 块板子:", cameras.len());
            for c in cameras {
                println!("  0x{:08X}  {}  (id 与 MAC 派生，重启不变)", c.id, c.addr);
            }
        }
        rx.shutdown();
        let _ = handle.join();
        return Ok(());
    }
    // 血量目前没有数据源。接口已经就位，装甲板接上后换掉这一行即可。
    let armor: Arc<dyn ArmorSource> = Arc::new(NoArmorYet);
    let decoded: DecodedSlots = Arc::new(Mutex::new(Vec::new()));
    // 接收线程。
    {
        let rx = Arc::clone(&rx);
        std::thread::Builder::new()
            .name("udp-reader".into())
            .spawn(move || {
                let Ok(socket) = bind_socket() else {
                    log::error!("could not bind the socket for the receive loop");
                    return;
                };
                rx.run(socket);
            })?;
    }
    // 解码线程：一张 VGA 的 JPEG 要几毫秒，放在收包线程里会挤进数据报之间，造成
    // 链路上本不存在的丢帧。
    {
        let frames = Arc::clone(&frames);
        let decoded = Arc::clone(&decoded);
        std::thread::Builder::new()
            .name("jpeg-decode".into())
            .spawn(move || {
                loop {
                    if frames.pending_senders().is_empty() {
                        std::thread::sleep(Duration::from_millis(5));
                        continue;
                    }
                    for sender_id in frames.pending_senders() {
                        let Some(frame) = frames.take(sender_id) else {
                            continue;
                        };
                        match decode_frame(&frame.data) {
                            Some(pixels) => {
                                let mut slot = decoded.lock().expect("decoded mutex poisoned");
                                // 同一路只保留最新一张，避免解码已经过时的画面。
                                slot.retain(|(id, _)| *id != sender_id);
                                slot.push((sender_id, pixels));
                            }
                            None => log::warn!(
                                "frame {} from 0x{:08X} is not a decodable JPEG ({} bytes)",
                                frame.frame_id,
                                frame.sender_id,
                                frame.data.len()
                            ),
                        }
                    }
                }
            })?;
    }
    let timer = slint::Timer::default();
    // 每个身份一个闭包，而不是一个闭包里再 match 身份。
    //
    // 两种身份是两个不同的组件类型（TeamApp / RefereeApp），没有共同的超类可以
    // 在一个闭包里统一调用 set_frame/set_frame_a。写成两个分支后每边都拿到具体
    // 类型，属性赋值直接调用，不再需要 match 身份——那种 match 会让编译器在每个
    // 赋值点都检查一遍身份，而它本来就是编译期就定死的。
    match config.role {
        Role::Team => {
            let ui = TeamApp::new()?;
            ui.show()?;
            let weak = ui.as_weak();
            let discovery = Arc::clone(&discovery);
            let decoded = Arc::clone(&decoded);
            let armor = Arc::clone(&armor);
            let config_path = config_path.clone();
            let team = config.team;
            let bound = config.camera_id;
            let mut view = View::new();
            // 绑定回调与刷新定时器都要读这份列表，所以用锁共享，而不是让其中一个
            // 把 `choices` 移走。
            let choices: Arc<Mutex<Vec<CameraChoice>>> = Arc::new(Mutex::new(Vec::new()));
            // 绑定完成时写配置。"选定不可更改"就落在这里：此后配置里已有
            // camera_id，界面不再出现选择页。
            let choices_for_pick = Arc::clone(&choices);
            let pick_handle = ui.on_pick(move |index| {
                let Ok(index) = usize::try_from(index) else {
                    return;
                };
                let picked = choices_for_pick
                    .lock()
                    .expect("choices mutex poisoned")
                    .get(index)
                    .map(|c| c.id_text.to_string());
                let Some(id_text) = picked else {
                    return;
                };
                let Some(id) = parse_id(&id_text).ok() else {
                    log::error!("could not read back the selected id {id_text:?}");
                    return;
                };
                let saved = Config {
                    role: Role::Team,
                    team,
                    camera_id: Some(id),
                    camera_addr: None,
                };
                if let Err(err) = saved.save(&config_path) {
                    log::error!("could not save the binding: {err}");
                    log::error!("画面仍会显示，但下次启动要重新选择");
                } else {
                    log::info!("bound to camera 0x{id:08X}; saved in the config");
                }
            });
            let choices_for_poll = Arc::clone(&choices);
            timer.start(slint::TimerMode::Repeated, UI_POLL, move || {
                let Some(ui) = weak.upgrade() else {
                    return;
                };
                let cameras = discovery.online_cameras();
                // 未绑定：只显示选择界面。
                let Some(bound) = bound else {
                    let updated: Vec<CameraChoice> = cameras
                        .iter()
                        .map(|c| CameraChoice {
                            id_text: format!("0x{:08X}", c.id).into(),
                            addr_text: format!("{}  ({:?})", c.addr, c.silence()).into(),
                            online: c.is_online(),
                        })
                        .collect();
                    *choices_for_poll.lock().expect("choices mutex poisoned") = updated.clone();
                    ui.set_choices(std::rc::Rc::new(slint::VecModel::from(updated)).into());
                    ui.set_choosing(true);
                    return;
                };
                ui.set_choosing(false);
                if view.sender_id != Some(bound) {
                    view = View::new();
                    view.sender_id = Some(bound);
                }
                if let Some(image) = take_decoded(&decoded, bound) {
                    ui.set_frame(image);
                }
                let stats = discovery.stats(bound);
                view.update_fps(&stats);
                if !view.reported && stats.frames_shown > 0 {
                    log_diagnostics(&stats, bound);
                    view.reported = true;
                }
                ui.set_stats(render_camera_stats(&cameras, bound, &stats, view.fps));
                ui.set_health(render_health(team, armor.as_ref()));
            });
            // 绑定回调必须活到窗口关闭。CallbackHandle 是 Copy，但 Drop 会注销
            // 回调，所以必须真的把它泄漏掉——之前用 `mem::forget` 编译器提示它对
            // Copy 类型无效，那确实无效：第一次点击后回调就被注销了，第二次点击
            // 什么也不会发生。
            std::boxed::Box::leak(Box::new(pick_handle));
        }
        Role::Referee => {
            let ui = RefereeApp::new()?;
            ui.show()?;
            let weak = ui.as_weak();
            let discovery = Arc::clone(&discovery);
            let decoded = Arc::clone(&decoded);
            let armor = Arc::clone(&armor);
            let mut views: Vec<View> = (0..2).map(|_| View::new()).collect();
            timer.start(slint::TimerMode::Repeated, UI_POLL, move || {
                let Some(ui) = weak.upgrade() else {
                    return;
                };
                let cameras = discovery.online_cameras();
                // 两路按 id 顺序填槽。槽位保持稳定（不会因为某块板子临时离线就重新
                // 洗牌），否则画面会左右跳动。
                let ids: Vec<u32> = cameras.iter().map(|c| c.id).take(2).collect();
                for (i, view) in views.iter_mut().enumerate() {
                    let wanted = ids.get(i).copied();
                    if view.sender_id != wanted {
                        *view = View::new();
                        view.sender_id = wanted;
                    }
                }
                for (i, view) in views.iter_mut().enumerate() {
                    let Some(sender_id) = view.sender_id else {
                        continue;
                    };
                    if let Some(image) = take_decoded(&decoded, sender_id) {
                        if i == 0 {
                            ui.set_frame_a(image);
                        } else {
                            ui.set_frame_b(image);
                        }
                    }
                    let stats = discovery.stats(sender_id);
                    view.update_fps(&stats);
                    if !view.reported && stats.frames_shown > 0 {
                        log_diagnostics(&stats, sender_id);
                        view.reported = true;
                    }
                    let view_stats = render_camera_stats(&cameras, sender_id, &stats, view.fps);
                    if i == 0 {
                        ui.set_stats_a(view_stats);
                    } else {
                        ui.set_stats_b(view_stats);
                    }
                }
                ui.set_health_a(render_health(0, armor.as_ref()));
                ui.set_health_b(render_health(1, armor.as_ref()));
            });
        }
    }
    // Timer 一旦被 drop 就停止，所以要活到进程结束。
    let _timer = Box::leak(Box::new(timer));
    slint::run_event_loop()?;
    rx.shutdown();
    Ok(())
 }
 /// 从解码缓存里取出某一路的最新画面。
 ///
 /// 解码线程只处理纯数据，`slint::Image` 的构造留在这里——`slint::Image` 不是
 /// `Send`，跨不了线程。
 fn take_decoded(
    decoded: &DecodedSlots,
    sender_id: u32,
 ) -> Option<slint::Image> {
    let mut slot = decoded.lock().expect("decoded mutex poisoned");
    let pos = slot.iter().position(|(id, _)| *id == sender_id)?;
    let (_, pixels) = slot.remove(pos);
    let buffer = slint::SharedPixelBuffer::<slint::Rgba8Pixel>::clone_from_slice(
        &pixels.rgba,
        pixels.width,
        pixels.height,
    );
    Some(slint::Image::from_rgba8(buffer))
 }
 /// 命令行参数。
 struct Args {
    role: Option<Role>,
    team: Option<u8>,
    camera_id: Option<u32>,
    camera: Ipv4Addr,
    config: Option<PathBuf>,
    list: bool,
    help: bool,
 }
 impl Args {
    fn parse(argv: impl Iterator<Item = String>) -> Result<Self, Box<dyn Error>> {
        let mut args = Args {
            role: None,
            team: None,
            camera_id: None,
            camera: protocol::BROADCAST_ADDR,
            config: None,
            list: false,
            help: false,
        };
        let mut it = argv.peekable();
        while let Some(arg) = it.next() {
            match arg.as_str() {
                "-h" | "--help" => args.help = true,
                "--list" => args.list = true,
                "--role" => {
                    let v = it.next().ok_or("--role needs a value")?;
                    args.role =
                        Some(Role::parse(&v).ok_or("role must be `team` or `referee`")?);
                }
                "--team" => {
                    let v = it.next().ok_or("--team needs a value")?;
                    args.team = Some(v.parse().map_err(|_| "--team must be 0 or 1")?);
                }
                "--camera-id" => {
                    let v = it.next().ok_or("--camera-id needs a value")?;
                    args.camera_id = Some(parse_id(&v)?);
                }
                "--camera" => {
                    let v = it.next().ok_or("--camera needs a value")?;
                    args.camera = v
                        .parse()
                        .map_err(|_| "--camera must be an IPv4 address")?;
                }
                "--config" => {
                    args.config = Some(PathBuf::from(it.next().ok_or("--config needs a path")?));
                }
                other => {
                    return Err(format!("unknown argument {other:?}\n\n{USAGE}").into());
                }
            }
        }
        Ok(args)
    }
 }
 /// 绑定 UDP 接收 socket。
 ///
 /// 固定端口（而非临时端口）是必须的：板子从订阅的**源端口**学到推流目标，而这个
 /// socket 同时承担收包。
 fn bind_socket() -> std::io::Result<std::net::UdpSocket> {
    let socket = std::net::UdpSocket::bind(std::net::SocketAddrV4::new(
        Ipv4Addr::UNSPECIFIED,
        protocol::DEFAULT_PORT,
    ))?;
    socket.set_read_timeout(Some(Duration::from_millis(100)))?;
    // 广播是发现的前提：板子靠它宣告存在，客户端靠它发起订阅。
    let _ = socket.set_broadcast(true);
    Ok(socket)
 }
 /// 解析 `0x1A2B3C4D` 或十进制形式的板子 id。
 fn parse_id(text: &str) -> Result<u32, Box<dyn Error>> {
    let text = text.trim();
    if let Some(hex) = text.strip_prefix("0x").or_else(|| text.strip_prefix("0X")) {
        Ok(u32::from_str_radix(hex, 16)?)
    } else {
        Ok(text.parse()?)
    }
 }
 /// 一次性诊断，在某一路第一次出画面时记录。
 ///
 /// 不再单列"无法解码"计数：那是链路正常但内容坏了的情形，会在解码线程里逐帧告警，
 /// 汇总在这里反而会把它和普通的丢帧混在一起。
 fn log_diagnostics(stats: &SourceStats, sender_id: u32) {
    log::info!(
        "camera 0x{sender_id:08X}: {} frames shown | {} dropped ({:.1}%) | \
         {} datagrams | {}x{} {} bytes",
        stats.frames_shown,
        stats.frames_dropped,
        stats.loss_percent(),
        stats.datagrams,
        stats.width,
        stats.height,
        stats.last_frame_len,
    );
 }
 /// 把某一路的统计渲染成界面结构。
 fn render_camera_stats(
    cameras: &[CameraInfo],
    sender_id: u32,
    stats: &SourceStats,
    fps: f32,
 ) -> CameraStats {
    let online = cameras
        .iter()
        .find(|c| c.id == sender_id)
        .map(CameraInfo::is_online)
        .unwrap_or(false);
    // 从没出过画面时区分"在线但还没收到"和"离线"：前者只是刚连上，显示"等待画面"
    // 比让人以为板子挂了诚实。
    let status = if stats.frames_shown == 0 {
        if online {
            "已连接，等待画面…".to_string()
        } else {
            "离线".to_string()
        }
    } else {
        format!("0x{:08X}", sender_id)
    };
    CameraStats {
        online,
        status_text: status.into(),
        fps: format!("{fps:.1}").into(),
        resolution: format!("{}x{}", stats.width, stats.height).into(),
        frame_bytes: format!("{:.1} kB", stats.last_frame_len as f32 / 1024.0).into(),
        frames_shown: stats.frames_shown.to_string().into(),
        frames_dropped: stats.frames_dropped.to_string().into(),
        loss_percent: format!("{:.1}%", stats.loss_percent()).into(),
        datagrams: stats.datagrams.to_string().into(),
        gap_ms: stats
            .last_interval
            .map(|d| format!("{:.0} ms", d.as_secs_f32() * 1000.0))
            .unwrap_or_else(|| "-".to_string())
            .into(),
    }
 }
 /// 渲染一边的血量。
 ///
 /// 现在永远走 `available == false` 的分支，因为还没有数据源。装甲板接上后
 /// [`ArmorSource::health`] 返回 `Some`，界面自动显示真实数值，这里不用改。
 ///
 /// 没有数据时用占位符而不是 0：0 看起来像真值，现场看到会以为对方已经没血了。
 fn render_health(team: u8, armor: &dyn ArmorSource) -> TeamHealth {
    let name = match team {
        0 => "队伍一",
        _ => "队伍二",
    };
    match armor.health(team) {
        Some(hps) => TeamHealth {
            team_name: format!("{name} · 装甲板").into(),
            available: true,
            placeholder: String::new().into(),
            hps: std::rc::Rc::new(slint::VecModel::from(
                hps.iter().map(|hp| *hp as i32).collect::<Vec<i32>>(),
            ))
            .into(),
        },
        None => TeamHealth {
            team_name: name.into(),
            available: false,
            placeholder:
                "装甲板未接入：血量接口已预留（protocol::ArmorHealth），当前无数据源".into(),
            // 依然给出 4 个格子：界面用 `available` 决定颜色，所以空数组会让占位
            // 框整个消失，看起来像布局出错，而不是像"还没有数据"。
            hps: std::rc::Rc::new(slint::VecModel::from(vec![0i32; ARMOR_BOARDS])).into(),
        },
    }
 }
@@ -1,458 +0,0 @@
 //! UDP 接收、发现、多路帧重组。
 //!
 //! # 多路
 //!
 //! 裁判终端同时收两块图传板，队伍终端也会收到两块（只是界面上只显示一块）。
 //! 所以重组状态**必须按发送方分开**——把两块板的帧塞进同一个重组器，会让它们
 //! 的 `frame_id` 互相顶掉，两路都出不来。
 //!
 //! # 发现与订阅
 //!
 //! 两个方向各司其职：
 //!
 //! - 板子每 2 秒广播一次 [`protocol::MsgType::Hello`]，客户端被动收到就知道有谁在线。
 //! - 客户端广播 [`protocol::MsgType::Subscribe`]，板子收到后开始定向推流。
 //!
 //! 板子靠**源地址**记住客户端，所以客户端只要周期性续订就能维持推流，不存在
 //! 任何超时淘汰的竞态。
 //!
 //! # 丢帧策略
 //!
 //! 缺了分片的帧整个丢弃、下一帧顶上，不重传也不尝试补洞。对实时画面这是对的：
 //! 等重传补齐时，那一帧早就不新鲜了。这个取舍的代价是丢帧率必须摆在界面上，否则
 //! "画面卡"没法区分是链路问题还是传感器问题。
 use std::collections::HashMap;
 use std::io::ErrorKind;
 use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, UdpSocket};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::{Duration, Instant};
 use protocol::{Fragment, FrameAssembler, Subscribe, SubscribeRole, DEFAULT_PORT, HEADER_LEN};
 /// 接受的最大数据报。高于协议的理论上限（1427），留出余量，这样一个被截断的读只可能
 /// 来自网络，而不是来自过小的缓冲。
 const RECV_BUFFER: usize = 2048;
 /// 重新广播订阅的间隔。
 ///
 /// 比板子判定"客户端掉线"的超时（6 秒）短得多，所以偶发丢一两个包不会中断推流。
 const SUBSCRIBE_INTERVAL: Duration = Duration::from_millis(800);
 /// 一张帧没收齐就放弃的时限。
 ///
 /// 一帧在 22fps 下约 45ms 到，所以几百毫秒还没齐的永远不会齐了。
 const FRAME_TIMEOUT: Duration = Duration::from_millis(500);
 /// 一块已知的图传板。
 #[derive(Debug, Clone)]
 pub struct CameraInfo {
    pub id: u32,
    pub addr: SocketAddrV4,
    pub firmware: u16,
    /// 最近一次收到它广播的时刻。
    pub last_seen: Instant,
 }
 impl CameraInfo {
    /// 多久没有广播了。
    pub fn silence(&self) -> Duration {
        self.last_seen.elapsed()
    }
    /// 板子在线吗？
    ///
    /// 阈值是广播间隔的数倍，所以偶发丢包不会让界面上的在线状态闪��。
    pub fn is_online(&self) -> bool {
        self.silence() < Duration::from_secs(7)
    }
 }
 /// 一块板的运行时统计。
 #[derive(Debug, Clone, Copy, Default)]
 pub struct SourceStats {
    pub frames_shown: u64,
    /// 因分片缺失被放弃的帧。
    pub frames_dropped: u64,
    pub datagrams: u64,
    pub last_frame_len: usize,
    pub width: u16,
    pub height: u16,
    /// 上一帧到这一帧之间的间隔。
    pub last_interval: Option<Duration>,
    last_shown_at: Option<Instant>,
 }
 impl SourceStats {
    /// 丢弃的帧占已收到帧的比例。
    pub fn loss_percent(&self) -> f32 {
        let total = self.frames_shown + self.frames_dropped;
        if total == 0 {
            0.0
        } else {
            self.frames_dropped as f32 * 100.0 / total as f32
        }
    }
    fn on_frame(&mut self, width: u16, height: u16, len: usize) {
        self.last_interval = self.last_shown_at.map(|t| t.elapsed());
        self.last_shown_at = Some(Instant::now());
        self.frames_shown += 1;
        self.width = width;
        self.height = height;
        self.last_frame_len = len;
    }
 }
 /// 每一路的最新帧，等着被解码。
 ///
 /// 每路只保留最新的一张：在 22fps 下把每一帧都排队意味着内存里压着几十张 JPEG，
 /// 然后解码那些几毫秒后就被下一帧顶掉的画面——而这正是这条链路要消除的延迟。
 #[derive(Default)]
 pub struct LatestFrames {
    inner: Mutex<HashMap<u32, protocol::Frame>>,
 }
 impl LatestFrames {
    pub fn put(&self, frame: protocol::Frame) {
        self.inner
            .lock()
            .expect("latest-frames mutex poisoned")
            .insert(frame.sender_id, frame);
    }
    /// 取走某一路的待处理帧。
    pub fn take(&self, sender_id: u32) -> Option<protocol::Frame> {
        self.inner
            .lock()
            .expect("latest-frames mutex poisoned")
            .remove(&sender_id)
    }
    /// 列出所有有待处理帧的板子 id。
    pub fn pending_senders(&self) -> Vec<u32> {
        self.inner
            .lock()
            .expect("latest-frames mutex poisoned")
            .keys()
            .copied()
            .collect()
    }
 }
 /// 所有板子的共享状态，跨线程只读。
 pub struct Discovery {
    cameras: Mutex<HashMap<u32, CameraInfo>>,
    stats: Mutex<HashMap<u32, SourceStats>>,
 }
 impl Discovery {
    fn new() -> Self {
        Self {
            cameras: Mutex::new(HashMap::new()),
            stats: Mutex::new(HashMap::new()),
        }
    }
    /// 当前已知的板子，按 id 排序，让界面上���列表顺序稳定。
    pub fn cameras(&self) -> Vec<CameraInfo> {
        let mut list: Vec<CameraInfo> = self
            .cameras
            .lock()
            .expect("cameras mutex poisoned")
            .values()
            .cloned()
            .collect();
        list.sort_by_key(|c| c.id);
        list
    }
    /// 在线且刚刚广播过的板子。
    pub fn online_cameras(&self) -> Vec<CameraInfo> {
        self.cameras().into_iter().filter(CameraInfo::is_online).collect()
    }
    /// 某一路的统计。
    pub fn stats(&self, sender_id: u32) -> SourceStats {
        self.stats
            .lock()
            .expect("stats mutex poisoned")
            .get(&sender_id)
            .copied()
            .unwrap_or_default()
    }
    fn note_hello(&self, id: u32, addr: SocketAddrV4, firmware: u16) {
        let mut cameras = self.cameras.lock().expect("cameras mutex poisoned");
        cameras
            .entry(id)
            .and_modify(|c| {
                c.addr = addr;
                c.last_seen = Instant::now();
                c.firmware = firmware;
            })
            .or_insert(CameraInfo {
                id,
                addr,
                firmware,
                last_seen: Instant::now(),
            });
    }
    fn note_frame(&self, id: u32, width: u16, height: u16, len: usize) {
        let mut stats = self.stats.lock().expect("stats mutex poisoned");
        stats.entry(id).or_default().on_frame(width, height, len);
    }
    fn count(&self, id: u32, f: impl FnOnce(&mut SourceStats)) {
        let mut stats = self.stats.lock().expect("stats mutex poisoned");
        f(stats.entry(id).or_default());
    }
    /// 超过 `max_idle` 没有广播的板子从列表里移除。
    ///
    /// 界面上不会留下一堆永远离线的板子。
    pub fn forget_silent_cameras(&self, max_idle: Duration) {
        self.cameras
            .lock()
            .expect("cameras mutex poisoned")
            .retain(|_, c| c.silence() < max_idle);
    }
 }
 /// 客户端身份。
 ///
 /// 常量而非 MAC 派生：队伍客户端和裁判终端各自唯一，进程内也不需要区分自己，
 /// 而一个确定的常量让日志更好读。
 pub const CLIENT_ID: u32 = 0x0C11_0001;
 /// 接收器。
 ///
 /// socket 在这里创建而不是在接收线程里，这样"端口被占用"会立刻报错，而不是被线程
 /// 吞掉、表现为一个永远不出画面的空窗口。
 pub struct Receiver {
    discovery: Arc<Discovery>,
    frames: Arc<LatestFrames>,
    role: SubscribeRole,
    camera: Ipv4Addr,
    stop: Arc<AtomicBool>,
 }
 impl Receiver {
    /// 绑定视频端口并准备好发现。
    ///
    /// 绑定固定端口（而非临时端口）是必须的：板子是从订阅的**源端口**学到推流目标的，
    /// 临时端口也能工作，但固定端口让三台客户端行为一致，也方便抓包排查。
    pub fn start(camera: Ipv4Addr, role: SubscribeRole) -> std::io::Result<Self> {
        let socket =
            UdpSocket::bind(SocketAddrV4::new(Ipv4Addr::UNSPECIFIED, DEFAULT_PORT))?;
        socket.set_read_timeout(Some(Duration::from_millis(100)))?;
        let broadcast = socket.set_broadcast(true).is_ok();
        if !broadcast {
            log::warn!("could not enable broadcast on the socket");
        }
        Ok(Self {
            discovery: Arc::new(Discovery::new()),
            frames: Arc::new(LatestFrames::default()),
            role,
            camera,
            stop: Arc::new(AtomicBool::new(false)),
        })
    }
    pub fn discovery(&self) -> Arc<Discovery> {
        Arc::clone(&self.discovery)
    }
    pub fn frames(&self) -> Arc<LatestFrames> {
        Arc::clone(&self.frames)
    }
    /// 运行接收循环，直到 [`Receiver::shutdown`]。
    ///
    /// 阻塞，所以放在单独的线程上。
    pub fn run(&self, socket: UdpSocket) {
        let target = SocketAddrV4::new(self.camera, DEFAULT_PORT);
        let subscribe = Subscribe {
            role: self.role,
            client_id: CLIENT_ID,
        };
        let subscribe_bytes = subscribe.encode();
        // 每个发送方一个重组器：两块板的 frame_id 各自独立，混在一起会互相顶掉。
        let mut assemblers: HashMap<u32, FrameAssembler> = HashMap::new();
        let mut buf = [0u8; RECV_BUFFER];
        let mut last_subscribe = Instant::now() - SUBSCRIBE_INTERVAL;
        let mut last_sweep = Instant::now();
        log::info!(
            "listening on UDP {DEFAULT_PORT}, announcing {:?} to {target}",
            self.role
        );
        while !self.stop.load(Ordering::Relaxed) {
            // 周期性续订就是保活：板子在 6 秒收不到就认为我们走了。
            if last_subscribe.elapsed() >= SUBSCRIBE_INTERVAL {
                if let Err(err) = socket.send_to(&subscribe_bytes, target) {
                    log::warn!("could not subscribe at {target}: {err}");
                }
                last_subscribe = Instant::now();
            }
            match socket.recv_from(&mut buf) {
                Ok((n, from)) => {
                    self.handle_datagram(&buf[..n], from, &mut assemblers);
                }
                Err(err)
                    if err.kind() == ErrorKind::WouldBlock
                        || err.kind() == ErrorKind::TimedOut =>
                {
                    // 帧之间的常态。读超时正是让退出能及时响应的原因。
                }
                Err(err) => {
                    log::warn!("recv failed: {err}");
                    thread::sleep(Duration::from_millis(100));
                }
            }
            // 放弃等太久的半截帧。否则板子在帧中途死掉时，重组器会一直留着它。
            for (id, asm) in assemblers.iter_mut() {
                if asm.expire().is_some() {
                    self.discovery.count(*id, |s| s.frames_dropped += 1);
                }
            }
            if last_sweep.elapsed() >= Duration::from_secs(5) {
                self.discovery.forget_silent_cameras(Duration::from_secs(60));
                last_sweep = Instant::now();
            }
        }
        log::info!("receive loop stopped");
    }
    /// 处理一个数据报。
    fn handle_datagram(
        &self,
        bytes: &[u8],
        from: std::net::SocketAddr,
        assemblers: &mut HashMap<u32, FrameAssembler>,
    ) {
        if bytes.len() < HEADER_LEN {
            return;
        }
        // 板子的在线通告。注意这里不看来源端口：广播来的源端口没有意义，身份由
        // 头里的 sender_id 决定。
        if let Some(hello) = protocol::Hello::decode(bytes) {
            if let SocketAddr::V4(v4) = from {
                let is_new = !self.discovery.cameras().iter().any(|c| c.id == hello.sender_id);
                self.discovery.note_hello(hello.sender_id, v4, hello.firmware);
                if is_new {
                    log::info!(
                        "found camera 0x{:08X} at {v4}",
                        hello.sender_id
                    );
                }
            }
            return;
        }
        let Some(frag) = Fragment::decode(bytes) else {
            // 既不是 Hello 也不是合法分片：将来的其它消息，或一次损坏。
            return;
        };
        let id = frag.header.sender_id;
        match assemblers
            .entry(id)
            .or_insert_with(|| FrameAssembler::new(FRAME_TIMEOUT))
            .push(frag)
        {
            Ok(frame) => {
                self.discovery.count(id, |s| s.datagrams += 1);
                self.discovery
                    .note_frame(id, frame.width, frame.height, frame.data.len());
                self.frames.put(frame);
            }
            Err(protocol::DropReason::Superseded) => {
                // 被更新的帧追上了。这不是丢帧：半截的那张只是被超越，在健康链路上
                // 这是帧被放弃的**正常**方式。
                self.discovery.count(id, |s| s.datagrams += 1);
            }
            Err(protocol::DropReason::TimedOut) => {
                self.discovery.count(id, |s| {
                    s.datagrams += 1;
                    s.frames_dropped += 1;
                });
            }
        }
    }
    pub fn shutdown(&self) {
        self.stop.store(true, Ordering::Relaxed);
    }
 }
 /// 解码后的画面。
 pub struct DecodedFrame {
    pub rgba: Vec<u8>,
    pub width: u32,
    pub height: u32,
 }
 /// 解码一张 JPEG。
 ///
 /// 返回 `None` 表示字节不是可解码的图像——协议层挡不住这种：它只检查分片结构，
 /// 不检查 JPEG 本身是否有效。
 pub fn decode_frame(jpeg: &[u8]) -> Option<DecodedFrame> {
    let img = image::load_from_memory_with_format(jpeg, image::ImageFormat::Jpeg).ok()?;
    let rgba = img.to_rgba8();
    Some(DecodedFrame {
        width: rgba.width(),
        height: rgba.height(),
        rgba: rgba.into_raw(),
    })
 }
 /// 装甲板血量的来源。
 ///
 /// **预留，当前没有实现也没有数据源。** 血量显示为占位符。
 ///
 /// 接口和端口都已就位（[`protocol::ARMOR_PORT`]、[`protocol::ArmorHealth`]）：装甲板
 /// 接上以后往那个端口发消息即可，裁判界面与其它代码都不用改。
 pub trait ArmorSource: Send + Sync {
    /// 某一边的血量。
    ///
    /// 返回 4 个装甲板的当前血量，按 index 排列。没有数据时返回 `None`，界面据此
    /// 显示占位符而不是 0——0 是一个看起来像真值的假值。
    fn health(&self, team: u8) -> Option<[u16; 4]>;
 }
 /// 一边的装甲板数量。
 ///
 /// RoboMaster 规则是每队 4 块。界面按这个数量画格子，所以数据还没接上时也能看到
 /// 位置——空着比画 0 个格子更让人以为布局坏了。
 pub const ARMOR_BOARDS: usize = 4;
 /// 目前唯一的实现：什么都不提供。
 ///
 /// 存在的意义是让界面代码从一开始就对着一个真实接口开发，而不是等装甲板就绪后再改
 /// 一次结构。
 pub struct NoArmorYet;
 impl ArmorSource for NoArmorYet {
    fn health(&self, _team: u8) -> Option<[u16; 4]> {
        None
    }
 }
@@ -1,416 +0,0 @@
 // Rectangle、VerticalLayout、HorizontalLayout 是语言内置的，无需 import。
 /* 一块画面的读数。裁判端有两块，队伍端一块。 */
 export struct CameraStats {
    // 在线状态
    online: bool,
    status-text: string,
    // 实时测量
    fps: string,
    resolution: string,
    frame-bytes: string,
    // 累计
    frames-shown: string,
    frames-dropped: string,
    loss-percent: string,
    datagrams: string,
    // 帧间隔，用于把"卡"和"帧率低"区分开
    gap-ms: string,
 }
 /* 一边的血量（4 块装甲板）。
 *
 * `available` 为 false 时界面显示占位符而不是 0：0 是一个看起来像真值的假值，
 * 现场看到 0 会以为对方已经没血了。 */
 export struct TeamHealth {
    team-name: string,
    available: bool,
    // 占位符文案
    placeholder: string,
    // 每块装甲板的血量；available 时有效
    hps: [int],
 }
 /* 首次运行时的摄像头选择。
 *
 * 队伍端需要绑定一块板子（选定后不可更改），裁判端不需要。 */
 export struct CameraChoice {
    id-text: string,
    addr-text: string,
    online: bool,
 }
 // ---------------------------------------------------------------- 队伍端
 /*
 * 队伍终端：一块画面 + 自己那一边的血量。
 *
 * 与裁判端是两套独立布局而不是一套加条件显示：两种场景的布局诉求不同（一边要省
 * 画面空间给视频，一边要均分），共用一套再用 visible 切换会让每处改动都要考虑两种
 * 情况。 */
 export component TeamApp inherits Window {
    title: "cam-client — 队伍";
    preferred-width: 1000px;
    preferred-height: 720px;
    in property <image> frame;
    in property <CameraStats> stats;
    in property <TeamHealth> health;
    // 选择绑定时显示，其余时候隐藏
    in property <[CameraChoice]> choices;
    in property <bool> choosing;
    // 选中了列表里的第 N 项。
    //
    // 绑定在这里一次完成：Rust 侧收到回调就写配置文件，所以"选定"当场生效，而不是
    // "下次启动才生效"。索引而不是 id，是为了让 Rust 侧回到自己那份列表里取完整
    // 信息——.slint 里的模型只是给界面看的。
    callback pick(int);
    background: #101014;
    // 绑定完成前只显示选择界面：没有画面可显示，显示一个空窗口更让人困惑。
    if !root.choosing: VerticalLayout {
        spacing: 0;
        HorizontalLayout {
            padding: 0;
            spacing: 0;
            Rectangle {
                background: #0a0a0d;
                vertical-stretch: 1;
                frame := Image {
                    source: root.frame;
                    image-fit: contain;
                    width: parent.width;
                    height: parent.height;
                    horizontal-alignment: center;
                    vertical-alignment: center;
                }
            }
        }
        // 底部一条：左边自己这边的血量，右边这一路的统计。
        Rectangle {
            background: #1c1c22;
            height: 72px;
            HorizontalLayout {
                padding: 14px;
                spacing: 24px;
                VerticalLayout {
                    padding: 0;
                    spacing: 2px;
                    horizontal-stretch: 1;
                    Text {
                        text: root.health.team-name;
                        color: #e8e8ec;
                        font-size: 14px;
                        font-weight: 600;
                    }
                    // 装甲板还没接上，所以是一排占位而不是四个数字。
                    HorizontalLayout {
                        padding: 0;
                        spacing: 6px;
                        for hp in root.health.hps: Rectangle {
                            width: 34px;
                            height: 12px;
                            border-width: 1px;
                            border-color: root.health.available ? #4a4a55 : #33333c;
                            background: root.health.available ? #7ddc7d : #1a1a20;
                        }
                    }
                }
                VerticalLayout {
                    padding: 0;
                    spacing: 2px;
                    preferred-width: 320px;
                    Text {
                        text: root.stats.status-text + "    " + root.stats.fps + " fps    "
                            + root.stats.resolution + "    " + root.stats.frame-bytes;
                        color: root.stats.online ? #e8e8ec : #e0a060;
                        font-size: 13px;
                    }
                    Text {
                        text: "shown " + root.stats.frames-shown
                            + "    dropped " + root.stats.frames-dropped
                            + " (" + root.stats.loss-percent + ")"
                            + "    gap " + root.stats.gap-ms;
                        color: root.stats.frames-dropped == "0" ? #8a8a95 : #e0a060;
                        font-size: 12px;
                    }
                }
            }
        }
        // 血量还没有数据源：把这件事写出来，而不是让一排灰块让人猜。
        Rectangle {
            background: #14141a;
            height: 26px;
            Text {
                text: root.health.placeholder;
                color: #6a6a75;
                font-size: 12px;
                horizontal-alignment: center;
                vertical-alignment: center;
            }
        }
    }
    // 选择界面
    if root.choosing: VerticalLayout {
        padding: 32px;
        spacing: 16px;
        Text {
            text: "选择要观看的摄像头";
            color: #e8e8ec;
            font-size: 20px;
            font-weight: 600;
        }
        Text {
            text: "选定后不能更改。这里的选择会写入配置文件，重启后仍然生效。";
            color: #8a8a95;
            font-size: 13px;
            wrap: word-wrap;
        }
        Rectangle { height: 8px; background: transparent; }
        // TouchArea 而不是给 Rectangle 挂 callback：Rectangle 是基础元素，没有
        // 点击回调；TouchArea 才是带交互的元素。
        for choice[index] in root.choices: Rectangle {
            background: choice.online ? #1c1c22 : #16161b;
            border-width: 1px;
            border-color: #2a2a33;
            height: 56px;
            TouchArea {
                clicked => {
                    root.pick(index);
                }
            }
            HorizontalLayout {
                padding: 14px;
                spacing: 16px;
                Text {
                    text: choice.id-text;
                    color: #e8e8ec;
                    font-size: 14px;
                    font-weight: 600;
                    vertical-alignment: center;
                    horizontal-alignment: left;
                }
                Text {
                    text: choice.addr-text;
                    color: #8a8a95;
                    font-size: 12px;
                    vertical-alignment: center;
                    horizontal-alignment: left;
                    horizontal-stretch: 1;
                }
                Text {
                    text: choice.online ? "在线" : "离线";
                    color: choice.online ? #7ddc7d : #8a8a95;
                    font-size: 12px;
                    vertical-alignment: center;
                }
            }
        }
        // 一块都没发现时给出可操作的提示，而不是一个空列表。
        if root.choices.length == 0: Rectangle {
            background: #1a1418;
            border-width: 1px;
            border-color: #4a2a35;
            height: 64px;
            Text {
                text: "还没有发现任何摄像头。请确认板子已上电、已连上这个网络，\n然后稍候——板子每 2 秒广播一次在线状态。";
                color: #e0a060;
                font-size: 13px;
                wrap: word-wrap;
                vertical-alignment: center;
            }
        }
    }
 }
 // ---------------------------------------------------------------- 裁判端
 /* 裁判终端：两块画面左右并排 + 双方血量。
 *
 * 与队伍端分开：这里的核心诉求是"一眼比出两边的状态"，所以两块画面等宽、血量
 * 并排对称。 */
 export component RefereeApp inherits Window {
    title: "cam-client — 裁判系统";
    preferred-width: 1400px;
    preferred-height: 800px;
    in property <image> frame-a;
    in property <image> frame-b;
    in property <CameraStats> stats-a;
    in property <CameraStats> stats-b;
    in property <TeamHealth> health-a;
    in property <TeamHealth> health-b;
    background: #101014;
    VerticalLayout {
        spacing: 0;
        // 两路画面等宽并排，各占一半。
        HorizontalLayout {
            padding: 0;
            spacing: 2px;
            Rectangle {
                background: #0a0a0d;
                vertical-stretch: 1;
                horizontal-stretch: 1;
                frame-a := Image {
                    source: root.frame-a;
                    image-fit: contain;
                    width: parent.width;
                    height: parent.height;
                    horizontal-alignment: center;
                    vertical-alignment: center;
                }
            }
            Rectangle {
                background: #0a0a0d;
                vertical-stretch: 1;
                horizontal-stretch: 1;
                frame-b := Image {
                    source: root.frame-b;
                    image-fit: contain;
                    width: parent.width;
                    height: parent.height;
                    horizontal-alignment: center;
                    vertical-alignment: center;
                }
            }
        }
        // 每路画面下方的队伍条：名字、血量、统计。
        HorizontalLayout {
            padding: 0;
            spacing: 2px;
            Rectangle {
                background: #1c1c22;
                height: 78px;
                horizontal-stretch: 1;
                VerticalLayout {
                    padding: 10px;
                    spacing: 4px;
                    Text {
                        text: root.health-a.team-name + "    " + root.stats-a.status-text
                            + "    " + root.stats-a.fps + " fps    " + root.stats-a.resolution;
                        color: root.stats-a.online ? #e8e8ec : #e0a060;
                        font-size: 14px;
                        font-weight: 600;
                    }
                    HorizontalLayout {
                        padding: 0;
                        spacing: 6px;
                        for hp in root.health-a.hps: Rectangle {
                            width: 40px;
                            height: 14px;
                            border-width: 1px;
                            border-color: root.health-a.available ? #4a4a55 : #33333c;
                            background: root.health-a.available ? #7ddc7d : #1a1a20;
                        }
                    }
                    Text {
                        text: "shown " + root.stats-a.frames-shown
                            + "  dropped " + root.stats-a.frames-dropped
                            + " (" + root.stats-a.loss-percent + ")"
                            + "  gap " + root.stats-a.gap-ms;
                        color: root.stats-a.frames-dropped == "0" ? #8a8a95 : #e0a060;
                        font-size: 12px;
                    }
                }
            }
            Rectangle {
                background: #1c1c22;
                height: 78px;
                horizontal-stretch: 1;
                VerticalLayout {
                    padding: 10px;
                    spacing: 4px;
                    Text {
                        text: root.health-b.team-name + "    " + root.stats-b.status-text
                            + "    " + root.stats-b.fps + " fps    " + root.stats-b.resolution;
                        color: root.stats-b.online ? #e8e8ec : #e0a060;
                        font-size: 14px;
                        font-weight: 600;
                    }
                    HorizontalLayout {
                        padding: 0;
                        spacing: 6px;
                        for hp in root.health-b.hps: Rectangle {
                            width: 40px;
                            height: 14px;
                            border-width: 1px;
                            border-color: root.health-b.available ? #4a4a55 : #33333c;
                            background: root.health-b.available ? #7ddc7d : #1a1a20;
                        }
                    }
                    Text {
                        text: "shown " + root.stats-b.frames-shown
                            + "  dropped " + root.stats-b.frames-dropped
                            + " (" + root.stats-b.loss-percent + ")"
                            + "  gap " + root.stats-b.gap-ms;
                        color: root.stats-b.frames-dropped == "0" ? #8a8a95 : #e0a060;
                        font-size: 12px;
                    }
                }
            }
        }
        // 装甲板还没接上：说清楚，而不是留一排看不懂的灰块。
        Rectangle {
            background: #14141a;
            height: 26px;
            Text {
                text: root.health-a.placeholder;
                color: #6a6a75;
                font-size: 12px;
                horizontal-alignment: center;
                vertical-alignment: center;
            }
        }
    }
 }
@@ -0,0 +1,15 @@
 # 桌面端构建为宿主机目标，不是 ESP32。
 #
 # desktop/ 嵌在固件的目录树里，cargo 会向上找到 ../../.cargo/config.toml，那里面
 # `target = "xtensa-esp32s3-espidf"` 加一个 ldproxy linker，只有在 ESP-IDF 交叉编译
 # 里才成立。没有这个覆盖，桌面端会被交叉编译到 Xtensa，然后在依赖深处失败——
 # `libc` 找不到 `MAP_FAILED` 之类的东西，因为它正在为一个没有 `mmap` 的嵌入式目标
 # 编译。
 #
 # 覆盖 target 一项就够了：父配置里 `cfg(target_os = "espidf")` 那一段对 macOS 不
 # 生效，`[env]` 里两个 ESP-IDF 变量与宿主构建无关。
 #
 # 这一行是**换机器时必须改的**：换到 Intel Mac 是 x86_64-apple-darwin，换到 Linux
 # 是 x86_64-unknown-linux-gnu。
 [build]
 target = "aarch64-apple-darwin"
@@ -0,0 +1,17 @@
 # 前端依赖与产物。
 node_modules/
 dist/
 # Rust 构建产物。desktop/ 下面是三个各自独立的 crate（core / src-tauri / 以及构建时
 # 可能出现的根 crate），各有各的 target 目录，所以三个都要写。
 /target/
 /core/target/
 /src-tauri/target/
 # Tauri 生成的权限 schema（构建产物，随 tauri-build 版本变化）。
 /src-tauri/gen/schemas/
 # 本机开发用的状态：dev 配置（里面有密码哈希）、演示/录制的输出、界面截图。
 # 截图不是源码，它们随界面一起变；要看就去 `pnpm app` 跑起来，或者自己跑 .dev/shoot.js。
 /.dev/
 /screenshots/
@@ -0,0 +1,482 @@
 # desktop
 桌面端。**两种身份，两套页面，一个进程。**
 | 身份 | 画面 | 血量 | 装甲板 | 绑定 |
 |---|---|---|---|---|
 | 用户端（`team`） | 一路 | **双方**（左上角自己 / 右上角对手） | 自己那块 | **要，改动需密码** |
 | 裁判端（`referee`） | 两路并排 | 双方（各自贴画面角上，**队名可改**） | 发现列表 + 槽位 | 不需要 |
 界面是 WebView 里的 React（画面画在 canvas 上），后端是 Rust。**它不是把旧客户端套进
 一个窗口**：网络、重组、发现、配置、密码、录制全部重写成了可单测的模块。
 ```text
 desktop/
  core/           cam-core：不含任何界面与 Tauri 的东西（80 个测试）
  src-tauri/      Tauri 后端：推流、命令、录制（30 个测试）
  src/            React 前端：两套页面 + HUD
  src/lib/        IPC 封装、WebSocket 客户端、状态存储、格式化
  src/components/ 视频窗格、血条、胜负横幅、瞄准器、装甲板表、队名编辑、录制面板、设置抽屉
  src/pages/      用户端 / 裁判端
 ```
 ## 快速开始
 ```sh
 cd desktop
 pnpm install
 pnpm app          # = tauri dev：起 vite + 编 Rust + 开窗口
 pnpm build        # 只构建前端（tsc --noEmit && vite build）
 pnpm tauri build  # 出 .app 与 .dmg
 ```
 下面两条是 Rust 侧，用它验证不依赖窗口的部分：
 ```sh
 cd desktop/core      && cargo test    # 80
 cd desktop/src-tauri && cargo test    # 30，其中几条真的会起 ffmpeg
 ```
 ### 演示模式：没有板子也能把整条链路跑起来
 ```sh
 cd desktop
 CAM_DEMO=1 pnpm app
 ```
 它**不伪造数据给界面**，而是合成**协议数据报**，从 `Receiver::datagram` 与
 `ArmorHealthStore::datagram` 进去。也就是说演示模式跑的是同一条真实路径：
 ```text
 合成 JPEG ──分片──▶ Receiver::datagram ──重组──▶ 帧 sink ──▶ WebSocket ──▶ canvas
 合成血量 ─────────▶ ArmorHealthStore ──▶ HealthTracker ──▶ 命中反馈
 ```
 分片、重组、发现、统计、掉血派生、两道闸门全在跑真代码，截图与录制也不需要特殊分支。
 界面上会有一条 **演示模式** 标记，板子 id 也刻意取成 `0x0DE00001` 这种一眼能看出是人造
 的形状——**别把它当成现场数据**。
 ### 命令行与环境变量
 ```text
  --role <team|referee>   身份。默认看配置文件
  --config <路径>          配置文件位置
  --demo                  演示模式
  --list                  打印发现的摄像头与装甲板后退出
  -h, --help              帮助
 CAM_DEMO=1              等价于 --demo
 CAM_CONFIG=<路径>        等价于 --config <路径>
 ```
 两个环境变量存在的理由很实际：`tauri dev` 要用两个 `--` 才能把参数递给应用
 （`tauri dev -- -- --demo`），写在一行环境变量里不会有人记错。
 **未知参数只记一条 debug 日志，不报错。** macOS 从访达双击 .app 时系统会塞进来一个
 `-psn_0_123456`；把它当错误处理的表现是"双击图标什么都没发生"。
 ## 为什么换成 Tauri，代价是什么
 旧客户端是 Rust + Slint 单二进制，能用。换掉它的理由是**界面这一侧的生产力**：血条、
 瞄准器、可拖拽的偏移校准、下拉绑定、设置抽屉、录制列表与回放——这些用 CSS/HTML 写是
 几十分钟的事，用即时模式 UI 工具写要自己排版、自己画控件、自己处理焦点。这个项目的重心
 在链路（UDP、重组、发现、防作弊），界面应当越快改完越好。
 代价说清楚：
 - **多一层**。WebView + Node 工具链 + Tauri 的权限系统，比一个 Slint 二进制重得多。
 - **要联网装依赖**（前端 npm、Rust crates）。
 - **画面要过一条本地通道**才能到界面（见下一节）。Slint 那版是把 RGBA 直接交给渲染器，
  路径更短。
 换来的另一样东西是**可测性**：`core/` 不认识界面，所以重组、发现、帧率窗口、槽位分配、
 配置与密码全都能用单元测试盯住——而它们恰好是最容易错、错了又最难在现场看出来的部分。
 ## 视频怎么进 WebView
 **一个只监听回环地址的 WebSocket，推二进制 JPEG。** 界面从 `stream_info` 命令拿到
 `ws://127.0.0.1:<随机端口>/?token=...`。
 ### 为什么不是 Tauri 的 IPC
 两路 22fps、每帧约 22 kB，每秒约 1 MB 的裸 JPEG。走 IPC 要序列化成 JSON（base64 再涨
 1/3），前端再解回来——CPU 花在没人需要的编解码上，延迟白涨一截。二进制 WebSocket 帧把
 原始字节直接交给前端，浏览器用**原生解码器**解，**后端连 JPEG 都不用解**。
 ### 二进制帧的布局
 ```text
  0              4              8      10     12             16
  +--------------+--------------+------+------+--------------+---------+
  | sender_id u32| frame_id u32 | w u16| h u16| jpeg_len u32 | JPEG... |
  +--------------+--------------+------+------+--------------+---------+
 ```
 小端，16 字节头。前后端对这段布局的约定由一个测试盯着（`server.rs` 与 `stream.ts`
 两侧都有），长度不一致的帧宁可丢掉，也不要让前端拿到一段不完整的 JPEG。
 ### 前端侧的两个陷阱
 **解码是异步的，所以帧号要看着用。** `createImageBitmap` 返回 Promise，两个相邻帧的解码
 可能乱序完成。所以每路记住最后画过的帧号，只有更新的那帧才采用——没有这一步，画面会偶尔
 往回跳一帧，看起来像"卡了一下"，极难归因。
 **`ImageBitmap` 必须显式 `close()`。** 它持有解码后的像素，不吃 GC 的账。每收到新帧就
 替换旧的那张并不够，必须把旧的那张关掉，否则两路 22fps 跑几分钟就是几百 MB。
 ## 防作弊：两道闸门，不是一个
 对抗赛里两队都用这套系统看自己小车的图传，要防止对手开第二个窗口连到另一队的板子。
 **关键是这件事做在接收端，不是界面里。** 广播的 Hello 里就有 MAC 派生的 `sender_id` 与
 IP，藏起来毫无意义；数据也可能已经收下并解码了，`.slint`/CSS 只控制显示。
 | 闸门 | 管什么 | 什么时候开 |
 |---|---|---|
 | `only_sender` | 帧的重组与投递 | 用户端**始终**是绑定的那一块 |
 | `discovery_all` | 是否记录**其它**板子的 Hello | 只在密码解锁后的设置界面里打开 |
 旧客户端把两件事绑在同一道闸门上，于是只能在"能列出候选"和"挡住对手"之间二选一，改绑
 只能靠手改配置文件。现在分开了：设置界面能列出候选摄像头（否则无从选起），但**画面不进
 来**——对手的板子即使把流推到本机端口、即使被记进发现列表，它的帧也进不了重组器。
 四种情况不限制：裁判端（中立方）、debug 构建、用户端还没绑定、`--camera-id` 显式覆盖。
 ### 遥测按编译模式门控
 `TEAM_DIAGNOSTICS = cfg!(debug_assertions)`。用户端 release 下**不产出**帧率/丢帧这些
 数字——不是"界面藏起来"，是 DTO 里就不存在（`CameraStatsDto::build` 直接把它们置零）。
 由编译模式决定而不是命令行开关：开关意味着二进制里带着那套东西，忘开一次就泄露了。
 ### 这挡不住什么
 诚实地说：**IP 仍然通过 Hello 广播泄露。** 对手知道你的 IP 之后可以自己发一个
 `Subscribe` 过来——固件会向任何订阅者推流，那道闸门在他的客户端上，不在你的。真要挡住
 需要固件侧做配对 token（首次绑定发一个令牌，固件只接受带令牌的订阅），代价是固件重启就
 失配。
 回环通道上那个 token 也不是防对手的：它只让"本机另一个程序顺手连上来看画面"变成一件需要
 先读到那个 token 的事。
 ## 密码：它挡的是谁
 必须说清楚，否则会被当成一把它并不是的锁。
 - **挡得住**：现场随手改绑定。选手想把自己的画面换到对手那块板子上，得先知道密码；围观
  的人翻不到明文（只有 Argon2id 哈希），也不能靠改配置文件把绑定改掉——改了之后界面会
  要求先解锁。**退出/关闭程序**同样要密码，因为"随手关掉"也是一种要挡的误操作。
 - **挡不住**：一个愿意在自己机器上重编这个客户端的人。配置与二进制都在他手上，删掉哈希
  或者直接改源码都行。真要封住得回固件加配对 token。
 所以它的定位是**防误触与防随手改**，不是密码学意义上的对抗。
 实现上：
 - Argon2id（`argon2` crate，默认参数 19 MiB / t=2），存标准的 PHC 字符串，参数跟着哈希
  一起躺在配置里，以后调参不需要迁移。用快哈希（SHA-256 之类）对 4 位数字密码等于没有
  保护。
 - 首次启动**强制**设置密码（`Config::needs_password_setup`），最短 4 位。长度下限只要
  4 位是刻意的：一个 8 位强密码在这里换不来任何实际安全增益，却会让现场每次改绑都要掏
  手机查一遍。
 - 解锁一次管到进程结束（会话内）。用户端可以手动"上锁"。
 - **裁判端不要密码**：它没有"绑定到自己那块板子"的动作可被滥用，而现场裁判要能最快地改
  槽位、开录。
 - **离开用户端要密码**：否则切到裁判端就能看两路画面、还能随便改配置，闸门形同虚设。
 执行点在 Rust 侧：每个改变配置的命令都过 `AppState::require_unlocked`。界面上的解锁
 对话框只是入口——即使有人从控制台直接调 `invoke("bind_camera")`，一样要过这一关。
 **故意没有 `--camera-id` 这类命令行覆盖。** 旧客户端有一个，用来"临时把一台机器当另一台
 用"；在这里它等于一条不需要密码就能改绑的路，所以去掉。要临时换一块板子，就在设置里改
 （要密码），或者用 `--config` 指一份另外的配置文件。
 忘了密码：删掉配置文件里的 `password` 一行（或整个文件）。旧客户端的配置会在首次启动时
 导入并备份成 `.bak`。
 ## 用户端 HUD
 ### 血条：两个上角，平行四边形，一条分 5 格
 **画面左上角是自己，右上角是对手**——两条同时看得见。血量是这一屏上最需要对照的两个数，
 放在画面之外意味着视线要离开取景。条本身是斜的（平行四边形），里面分成 **5 格**，一格
 20 点血：格子少而大，隔着几米扫一眼也能数出"还剩几格"，比读一条连续的长度或一个百分比快。
 少了的那部分从**靠中心的一侧**开始灭，于是两条血一起减少时视觉上往两边退。
 （条挂在绝对定位的一层上，`pointer-events: none`——那一层盖着画面，而画面要能滚轮缩放、
 指针拖动。同理，倍率与复位徽标从画面**上**沿挪到了下沿，上沿两个角归血条。）
 宽度、是否显示数字/队名、低血阈值与脉动都可配；阈值以内的格子提前染上警示色，所以"危险区
 在哪"是一直看得见的，而不是等真的低血了才第一次出现。
 **未接入时显示占位说明而不是 0**：0 是一个看起来像真值的假值，现场看到 0 会以为对方已经
 没血了，然后开始找裁判理论。这一条在旧客户端上是踩过坑的。
 血量归零**不写"已击毁/损毁"这类话**：归零这件事由图传中央的胜负横幅表达（见下），条上只留
 一个 0 与灭掉的格子。
 ### 胜负横幅
 一方归零之后，**图传中央**显示结论：赢的一边是「胜利」，输的一边是「击败」，两边同时归零是
 「平局」（那时候任何一边显示"胜利"都是错的）。用词带上对手的名字，裁判端两格因此也能直接
 看出是哪一边赢了。
 - 结论由 Rust 侧算（`snapshot::resolve_outcomes`，有单测）：**输只需要看自己**——自己归零就是
  输，哪怕对手那块板子掉线；**赢要看两边**——对手归零且自己还有血，否则一块从没上报过血量的
  自家主板会让人"凭空胜利"。
 - 它一直显示到血量被重置（长按 BOOT / 下一局开始），不做几秒淡出：淡出之后屏幕上就再没有
  "这局结束了"的痕迹，截图、回放与现场的争议都无从对照。
 - 这是唯一放在画面正中的东西。命中反馈那一套刻意避开正中（见下），因为**胜负不是那种信息**：
  它是一局的结束，此刻不再需要瞄准。
 ### 瞄准器
 画在 canvas 上（不是叠一层 DOM），因为**它必须跟着画面走**：它标的是相机光轴上的一个点。
 用 DOM 摆一个 `<img>` 再叠一层 `transform` 的话，"图像落在哪、瞄准点落在哪"要算两遍，而
 两份实现迟早会不一致——表现是放大之后瞄准器偏了，恰恰发生在这件事最要紧的时候。所以变换
 只算一次，图像、网格、瞄准器、伤害数字全都用同一组数画出来。
 尺寸与缩放的关系也是刻意分开的：
 | | 跟着缩放走吗 | 为什么 |
 |---|---|---|
 | 位置 | **是** | 它指的是画面里的一个点 |
 | 大小 | 否 | 像真瞄具一样，放大之后准星覆盖画面里更小的一块 |
 | 网格 | 是 | 它标的是画面里的比例，用来估距离 |
 **偏移校准存的是画面比例，不是像素。** 摄像头与枪管不同轴时要把瞄点挪到弹着点上，而像素
 偏移在分辨率或窗口大小一变就全错了。校准可以拖着画面调，也可以直接填数值。
 ### 命中反馈
 主板**不报**"被打了一下"，只报"现在是多少血"。所以命中是靠相邻两次读数之差还原的
 （`HealthTracker`）：
 - 血量减少 ⇒ 一次命中，伤害是两个读数之差；
 - 血量增加 ⇒ 不是命中，是长按 BOOT 的重置；
 - 第一次见到一块板子不产生命中——没有基线，此时 `hp = 0` 只是"已经没血了"。
 按**板子**记基线而不是按 `(板子, index)`：主板一次广播四条、`hp` 相同，按四条各记一份
 基线会让一次掉血被报成四次命中。
 已知精度上限：两次读数之间发生两次伤害时只能看到净差。心跳 200 ms，所以这段窗口里的两次
 打击会被合并成一次——对"闪一下红"足够，对判定不够，判定看的是界面上的绝对血量。
 反馈有**两样**：整屏闪红、准星旁的伤害数字。**大号数字不放在画面正中**——第一版放了，
 结果它正好压在瞄准点上，而被打中的那一下恰恰是最需要看着准星的时候。
 **没有"画面抖动"了。** 原来有第三样：被打中时整幅图（连瞄准器一起）晃一下。它去掉了，
 理由有两条：
 - 抖动恰好发生在最需要看清画面的那一下；
 - 它把**画面**动了，而操作手看到画面动时的第一反应是"车在晃"，不是"我被打中了"——一个
  只有几百毫秒的信号，代价是让人怀疑一个不存在的问题。
 `HitFeedbackConfig::shake` 这个字段留着但不再生效：配置文件是 `deny_unknown_fields` 的，
 删字段会让所有写过 `shake = true` 的配置**解析失败**，而配置解析失败等于程序起不来。设置
 面板里也没有这个开关了。
 ## 裁判端
 ### 队名可以直接改
 两格画面各自下面有一个队名输入框（`TeamNameEditor`），回车或点到别处生效，Esc 取消。
 名字是**这一场比赛**的属性，所以它放在裁判盯着的地方，而不是设置面板深处的某一节；改完
 立刻反映到血条、装甲板表与"等待图传"的占位文字上。
 规范化的三件事统一在 Rust 侧做（`config::sanitize_team_name`，有单测）：合并空白、按**字符**
 截断到 12 个字（按字节截断会切出半个字）、留空回落到「队伍一 / 队伍二」。超过长度在输入框里
 就限制了，比提交后被悄悄截掉诚实。
 命令是 `set_team_name(team, name)`——**一次只改一边**。界面本来可以传一整个两条的数组，但那样
 每次改名都是"读两条、改一条、写两条"，而读来的那两条来自最多 200 ms 前的快照，紧接着改另一边
 就会把上一次的改动覆盖回去。**同样过密码闸门**：裁判端本来就没有密码（`Role::needs_password`
 为假），所以对现场没有影响；而给一个不设闸门的"写配置"入口，等于在闸门上开一条旁路——今天
 改的是名字，明天有人顺手把绑定也挪进来。
 名字在快照里以 `teamNames`（两条，下标就是队伍号）推给界面，两边各自的 `TeamHealthDto.name`
 也是从这里来的：界面各处自己拼 `team === 0 ? "队伍一" : "队伍二"` 会在改名之后留下一半旧名字，
 而且不会报错。
 ### 两格等宽
 `flex: 1 1 0` + `min-width: 0`，两格的宽度只由容器决定。
 旧客户端在这里翻过车：`HorizontalLayout` 先按内容的**最大**需求分配，剩下的才按 stretch
 分。一格写着"已连接，等待画面…"（8 字），另一格只有"未收到画面"（5 字），于是左边多要
 十几个像素——实测 55% / 45%。现在占位文字绝对定位、两格需求相同。
 ### 槽位分配：修掉了一个真 bug
 规则：
 1. 还在线的槽位不换人；
 2. **候选里排除已经被另一个槽位占着的 id**；
 3. 掉线的槽位保留它的 id（显示"离线"），这样它回来时还在原位；
 4. 没有候选就不动——只有一块板在场时另一个槽位空着，空着比显示一份复制品诚实。
 规则 2 是修 bug。旧实现只排除"这个槽位自己原来那个 id"，于是**队伍一的板子一离线，它的
 槽位就会去拿队伍二那块，两格显示同一块板子**——看起来像图传串了，现场的排查方向会是网线、
 AP、板子，而不是二十行分配代码。现在它有一个直接对着这个场景写的测试。
 有烧错固件的板子（`team` 字段是反的）时可以在设置里改成手动指定槽位。
 ### 装甲板发现列表
 场上连上了几块板子、各自自报哪一队、现在多少血、多久没广播、四条上报齐不齐、分到了哪个
 槽位——"裁判端没显示血量"时第一眼看的就是这张表。它能区分"板子根本没上线"、"上线了但队
 伍号烧反了"和"只有一条上报在发"。
 **这不需要改固件**：主板一直用 `encode_from(sender_id)` 把自己的 MAC 派生 id 打进帧头，
 只是旧的解码路径把它丢了。现在 `ArmorHealth::decode_from` 把它交出来。
 ### 截图与录制
 - 截图存 PNG（`shots/` 下），文件名带板子 id 与毫秒时间戳。
 - 录制存 mp4，走 ffmpeg 子进程：`-f image2pipe -c:v mjpeg -framerate <fps> -i pipe:0`
  喂帧，x264 编码，`+faststart`。
 - **帧率要显式告诉 ffmpeg**。`image2pipe` 里的 JPEG 序列没有时间戳，一串帧在 ffmpeg 看来
  就是"以固定帧率播放的图片"。所以这个数只能来自实测，它会写进日志与 DTO——回放快放/慢放
  时第一个要看的就是它。
 - 喂帧经由一条长度 64 的队列与一个写盘线程。**接收线程绝不能被写盘拖慢**：那一天的表现是
  链路上本不存在的丢帧。写不进去就丢帧并计数，丢帧数会出现在界面上。
 - 文件名会查重：同一秒停一次再开一次是很自然的操作（"这局重录"），而重名意味着 ffmpeg 的
  `-y` 把上一段**静默覆盖**掉。所以先收尾上一段再开新的，重名往后排 `-2`、`-3`。
 界面内回放走 Tauri 的资源协议，只对 `tauri.conf.json` 里 `assetProtocol.scope` 白名单的
 目录生效。默认录制目录在名单里；改到别处时 `<video>` 会加载失败，界面上给出"用系统播放器
 打开"的退路——而不是让人以为录下来的文件坏了。
 ## 配置
 `~/.config/cam-desktop/config.toml`，`--config` 可改。
 ```toml
 role = "team"
 roleChosen = true
 team = 0
 teamNames = ["队伍一", "队伍二"]
 cameraId = "0x0DE00001"
 armorId = "0x0A200001"
 mirror = false
 password = "$argon2id$v=19$m=19456,t=2,p=1$..."
 [recording]
 dir = "/Users/you/Movies/cam-desktop"
 ffmpeg = "ffmpeg"
 crf = 20
 preset = "veryfast"
 [hud.crosshair]
 style = "cross-dot"
 size = 0.05
 offsetX = 0.0
 ```
 几个决定：
 - **手写解析换成 serde + toml。** 旧客户端的配置只有四个标量字段，手写换来零依赖是划算
  的；现在有 HUD 的嵌套结构、密码哈希、录制参数，对称性成本超过了收益。
 - **未知键名仍然报错**（`deny_unknown_fields`）。打错一个键名却"看起来生效了"，在现场是
  要浪费时间的。
 - **字段名统一 camelCase**，磁盘、IPC、前端 TS 一个名字。TOML 里写 camelCase 不算最漂亮，
  但换来的是不需要任何一层做名字转换——而那种转换漏掉一个字段时不会报错，只会让某一项设置
  看起来"改了没生效"。
 - **原子写**：先写同目录临时文件再 `rename`。配置文件里有密码哈希，写一半崩掉留下的截断
  文件会让"解锁"永久失败。
 - **id 写成十六进制字符串**（`"0x3D4D8A9A"`），与界面、日志、抓包里看到的完全一致。
 - `teamNames` 在根上而不是 `[referee]` 里：用户端的血条同样要显示名字，而"这场比赛的两队
  叫什么"是比赛本身的属性，不是裁判端这个身份的属性。
 - `roleChosen` 单独一位：`role` 的默认值是裁判端，所以"role == referee"既可能是人选了裁判
  端，也可能只是还没人碰过这个文件。界面需要这个判据来决定首启要不要先问一句。
 旧客户端（Slint 版）的配置在首次启动时导入能对应的字段，然后改名成 `.bak`（不删：现场
 出问题时"旧的那份到底写了什么"是第一个要看的东西）。只有用**默认**路径时才做这件事——
 `--config` 指定了别的路径说明这次运行是有意分开的，那时去动常规配置是越界的。
 ## 浏览器预览（仅开发）
 Tauri 的界面跑在 WKWebView 里，改一行 CSS 要走一次 cargo 构建。所以 dev 模式下、且页面
 里没有 Tauri 注入时，同一套 React 组件可以在浏览器里跑起来：状态与画面由
 `src/lib/dev-preview.ts` 合成。
 ```sh
 pnpm dev                                          # 用户端
 open 'http://127.0.0.1:1420/?preview=referee'     # 裁判端（密码 1234）
 ```
 两重门保证它进不了正式构建：`import.meta.env.DEV` 为真**且**没有 `__TAURI_INTERNALS__`，
 并且调用点是 `await import(...)`——条件为假时整个模块不会被打进产物。
 ## 测试
 ```sh
 cd desktop/core      && cargo test    # 80：重组、发现、两道闸门、帧率窗口、槽位、配置、密码、胜负判定
 cd desktop/src-tauri && cargo test    # 30：帧头布局、录制、截图、演示画面、命令行
 cd protocol          && cargo test    # 15
 ```
 三条值得单独说的：
 - **录制**那条真的起 ffmpeg、喂 20 帧、停，然后用 `ffprobe` 读回帧数与分辨率。只断言"文件
  存在且非空"是不够的：ffmpeg 参数写错时也会留下一个空的容器，而那正是最难在现场发现的
  一种失败。
 - **截图**那条真写一个 PNG 再读回来对尺寸，另外验证坏输入会报错而不是留下一个空文件。
 - **帧率窗口**那条把"对帧间隔取平均会给出什么"也钉住了（约 30fps），防止有人"顺手修一下"
  改回错误算法。
 CSP 的验证不靠"看一眼没报错"，而是靠**前端能不能连上后端**：前端的第一步是先 `invoke`
 拿通道地址，再连 WebSocket。所以快照里的 `clients` 从 0 变成 1 同时证明了四件事——JS 加载
 成功、IPC 通、WebSocket 通、React 的 effect 跑到了。CSP 一旦挡住其中任何一环，它就会停在
 0。手动核对的办法：
 ```sh
 RUST_LOG=debug ./target/aarch64-apple-darwin/debug/cam-desktop | grep 'stream:'
 # 拿那条 ws://... 地址，用任何 WebSocket 客户端连上去，看 clients 是不是 1
 ```
 ## 线程与数据流
 | 线程 | 做什么 | 为什么单独 |
 |---|---|---|
 | `udp-reader` | 收包、解析、按发送方重组 | 不能让解码/写盘挤进数据报之间 |
 | `armor-reader` | 收 5601 上的血量广播 | 与视频是两个端口、两种节奏 |
 | `rec-writer-<id>` | 把队列里的帧写进 ffmpeg 的 stdin | 接收线程绝不能被写盘拖慢 |
 | `demo-*`（仅演示） | 合成协议数据报 | 走同一条真实路径 |
 | tokio 任务 | WebSocket 服务、5 Hz 快照 | 异步 IO |
 跨线程只有两样东西：`Arc` 与广播通道。帧在接收线程里编码一次（16 字节头 + JPEG），
 所有界面共用同一份 `Bytes`。
 ## 已知限制与没做的
 - **同一队有两块装甲板在广播时**，`health(team)` 是"最后写入者优先"，四个格子可能混着两块
  板子的数。真实比赛一队只有一块，所以这只在开发（演示 + 真板子）或烧错固件时才会遇到；
  日志里会警告一次，消歧办法是绑定具体的板子 id（`health_of_board`）。
 - **录制帧率**是固定值，不是可变帧率。源帧率变化大时回放速度会有偏差；这个数会写进日志与
  DTO，所以至少能解释清楚。
 - **`csp` 是一条收紧过的白名单**，但它是"够用"而不是"最小"：`style-src` 带
  `'unsafe-inline'`（React 的内联 `style` 属性需要它），`connect-src` 放开了整个
  `ws://127.0.0.1:*`（端口是启动时随机分配的，写不死）。验证方式是"前端能不能连上后端"
  ——见下面"测试"一节最后一条。
 - **证书与公证**没做，`.dmg` 只在本机可用。
 - 前端没有自动化测试。界面这一侧的验证手段是浏览器预览 + 真机运行；逻辑都在 `core/` 里
  有测试。
 ## 排查
 | 现象 | 原因 |
 |---|---|
 | 起不来，提示绑不上 UDP 5600 | 同一端口上已经跑着另一个客户端（旧的 Slint 版或另一份本程序）。看 `~/.config/cam-desktop/startup-error.txt` |
 | 窗口起来了但没画面 | 设置里看"摄像头"下拉：绑定的是哪一块、在不在线 |
 | 状态栏一直"已连接，等待画面…" | 板子在线但没推流。检查它有没有在向这个源端口订阅（客户端每 800ms 续订一次） |
 | 队伍端下拉里只有一块板子 | 正常：帧的闸门是绑定的那一块。设置界面解锁后会列出全部候选 |
 | 右上角那条血显示"装甲板未接入" | 对手那块主板没在 5601 上报血量（或不在线）。显示的是说明而不是 0——0 会被当成"对手已经没血" |
 | 改了队名，某一处还是旧名字 | 不该发生：名字只有一个来源（快照里的 `teamNames`，血条直接用 `name`）。看到的话说明有一处自己拼了"队伍一/队伍二"，那是个 bug |
 | 输了/赢了之后画面中央一直有字 | 刻意如此：它显示到血量被重置（长按 BOOT）为止，不做几秒淡出。想清掉就重置装甲板 |
 | 被打中时画面不动，只有闪红 | 刻意如此：抖动去掉了（见"命中反馈"）。旧配置里的 `shake = true` 读得进来但不生效 |
 | 画面不动 | 先看顶栏的"界面 N"：0 表示前端没接上，≥1 表示后端在推而前端没画。`RUST_LOG=debug` 会打印完整通道地址，可以用 `wscat` 连上去看 |
 | 回放失败 | 录制目录不在资源协议白名单里。用"用系统播放器打开" |
 | 录不了 | ffmpeg 不在 PATH 里。设置里可以指定路径；不起 ffmpeg 时会报错而不是假装在录 |
 | 两块画面串了 | 检查是不是手动指定了槽位，或者两块板子烧了同一个 `ARMOR_TEAM` |
 | macOS 上 WebKit 报 `could not create directory .../WebKit/...` | 运行环境禁止写 `~/Library/WebKit`（沙箱）。WebView 会退回无缓存的临时目录，功能不受影响 |
 | `libc` 找不到 `MAP_FAILED` | `desktop/.cargo/config.toml` 的 target 没改成宿主三元组 |
@@ -0,0 +1,436 @@
 # This file is automatically @generated by Cargo.
 # It is not intended for manual editing.
 version = 4
 [[package]]
 name = "anyhow"
 version = "1.0.104"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
 [[package]]
 name = "argon2"
 version = "0.5.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072"
 dependencies = [
 "base64ct",
 "blake2",
 "cpufeatures",
 "password-hash",
 ]
 [[package]]
 name = "base64ct"
 version = "1.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06"
 [[package]]
 name = "blake2"
 version = "0.10.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe"
 dependencies = [
 "digest",
 ]
 [[package]]
 name = "block-buffer"
 version = "0.10.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
 dependencies = [
 "generic-array",
 ]
 [[package]]
 name = "cam-core"
 version = "0.1.0"
 dependencies = [
 "anyhow",
 "argon2",
 "log",
 "protocol",
 "rand",
 "serde",
 "serde_json",
 "toml",
 ]
 [[package]]
 name = "cfg-if"
 version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
 [[package]]
 name = "cpufeatures"
 version = "0.2.17"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
 dependencies = [
 "libc",
 ]
 [[package]]
 name = "crypto-common"
 version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
 "generic-array",
 "typenum",
 ]
 [[package]]
 name = "digest"
 version = "0.10.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
 dependencies = [
 "block-buffer",
 "crypto-common",
 "subtle",
 ]
 [[package]]
 name = "equivalent"
 version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
 [[package]]
 name = "generic-array"
 version = "0.14.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
 dependencies = [
 "typenum",
 "version_check",
 ]
 [[package]]
 name = "getrandom"
 version = "0.3.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
 dependencies = [
 "cfg-if",
 "libc",
 "r-efi",
 "wasip2",
 ]
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 [[package]]
 name = "indexmap"
 version = "2.14.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855"
 dependencies = [
 "equivalent",
 "hashbrown",
 ]
 [[package]]
 name = "itoa"
 version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 [[package]]
 name = "libc"
 version = "0.2.190"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ce5d3ddc6d3fa000eb1536d85e147bfe31aacaba692ed6a876f95cb7c855be78"
 [[package]]
 name = "log"
 version = "0.4.34"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"
 [[package]]
 name = "memchr"
 version = "2.8.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
 [[package]]
 name = "password-hash"
 version = "0.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166"
 dependencies = [
 "base64ct",
 "rand_core 0.6.4",
 "subtle",
 ]
 [[package]]
 name = "ppv-lite86"
 version = "0.2.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
 dependencies = [
 "zerocopy",
 ]
 [[package]]
 name = "proc-macro2"
 version = "1.0.107"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
 dependencies = [
 "unicode-ident",
 ]
 [[package]]
 name = "protocol"
 version = "0.1.0"
 [[package]]
 name = "quote"
 version = "1.0.47"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
 dependencies = [
 "proc-macro2",
 ]
 [[package]]
 name = "r-efi"
 version = "5.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
 [[package]]
 name = "rand"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
 dependencies = [
 "rand_chacha",
 "rand_core 0.9.5",
 ]
 [[package]]
 name = "rand_chacha"
 version = "0.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
 dependencies = [
 "ppv-lite86",
 "rand_core 0.9.5",
 ]
 [[package]]
 name = "rand_core"
 version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
 [[package]]
 name = "rand_core"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
 dependencies = [
 "getrandom",
 ]
 [[package]]
 name = "serde"
 version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
 dependencies = [
 "serde_core",
 "serde_derive",
 ]
 [[package]]
 name = "serde_core"
 version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
 dependencies = [
 "serde_derive",
 ]
 [[package]]
 name = "serde_derive"
 version = "1.0.229"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn 3.0.9",
 ]
 [[package]]
 name = "serde_json"
 version = "1.0.154"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
 dependencies = [
 "itoa",
 "memchr",
 "serde",
 "serde_core",
 "zmij",
 ]
 [[package]]
 name = "serde_spanned"
 version = "1.1.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7523beb55eece201a2356bee0bbca0d1ab466c14c07703b2e0ee6d42cb0c2c"
 dependencies = [
 "serde_core",
 ]
 [[package]]
 name = "subtle"
 version = "2.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
 [[package]]
 name = "syn"
 version = "2.0.119"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
 dependencies = [
 "proc-macro2",
 "quote",
 "unicode-ident",
 ]
 [[package]]
 name = "syn"
 version = "3.0.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
 dependencies = [
 "proc-macro2",
 "quote",
 "unicode-ident",
 ]
 [[package]]
 name = "toml"
 version = "0.9.12+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cf92845e79fc2e2def6a5d828f0801e29a2f8acc037becc5ab08595c7d5e9863"
 dependencies = [
 "indexmap",
 "serde_core",
 "serde_spanned",
 "toml_datetime",
 "toml_parser",
 "toml_writer",
 "winnow 0.7.15",
 ]
 [[package]]
 name = "toml_datetime"
 version = "0.7.5+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "92e1cfed4a3038bc5a127e35a2d360f145e1f4b971b551a2ba5fd7aedf7e1347"
 dependencies = [
 "serde_core",
 ]
 [[package]]
 name = "toml_parser"
 version = "1.1.5+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c"
 dependencies = [
 "winnow 1.0.4",
 ]
 [[package]]
 name = "toml_writer"
 version = "1.1.3+spec-1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "06bdbd8cfc056b8d2e2e85f29b56a3bdbecb527cef81eb39e3e7b98af4652770"
 [[package]]
 name = "typenum"
 version = "1.20.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
 [[package]]
 name = "unicode-ident"
 version = "1.0.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
 [[package]]
 name = "version_check"
 version = "0.9.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
 [[package]]
 name = "wasip2"
 version = "1.0.4+wasi-0.2.12"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
 dependencies = [
 "wit-bindgen",
 ]
 [[package]]
 name = "winnow"
 version = "0.7.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
 [[package]]
 name = "winnow"
 version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "23b97319f7b8343df12cc98938e5c3eb436064524c8d2b4e30a1d3a36eecdf81"
 [[package]]
 name = "wit-bindgen"
 version = "0.57.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
 [[package]]
 name = "zerocopy"
 version = "0.8.63"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8"
 dependencies = [
 "zerocopy-derive",
 ]
 [[package]]
 name = "zerocopy-derive"
 version = "0.8.63"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f"
 dependencies = [
 "proc-macro2",
 "quote",
 "syn 2.0.119",
 ]
 [[package]]
 name = "zmij"
 version = "1.0.23"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
@@ -0,0 +1,27 @@
 [package]
 name = "cam-core"
 version = "0.1.0"
 edition = "2021"
 description = "桌面端的非界面部分：UDP 接收/重组、装甲板发现、配置与密码"
 [dependencies]
 # 与固件共享的线路格式。用 path 而不是复制，两边不可能悄悄分叉。
 protocol = { path = "../../protocol" }
 anyhow = "1"
 log = "0.4"
 # 配置的序列化。这里与旧客户端（client/）的做法相反：那一版的配置只有十来个标量
 # 字段，手写 TOML 换来零依赖是划算的。现在配置里有 HUD 的嵌套结构和密码哈希，手写
 # 解析器的对称性成本超过了它的收益，所以换成真正的 TOML。
 serde = { version = "1", features = ["derive"] }
 toml = "0.9"
 # 密码哈希。Argon2id 是目前的推荐选择（内存硬），而 SHA-256 之类的快哈希对
 # 一个 4 位数字密码来说等于没有保护。
 argon2 = "0.5"
 rand = "0.9"
 [dev-dependencies]
 # 只用来验证喂给界面的 JSON：断言"密码哈希不在里面"这件事只能对着序列化结果做。
 serde_json = "1"
@@ -0,0 +1,641 @@
 //! 装甲板：监听 5601，把主板广播的 `ArmorHealth` 变成界面要的东西。
 //!
 //! 两件事，各自服务一种需求：
 //!
 //! - **血量**（[`ArmorSource::health`]）：某一边四条上报都在新鲜期内才交给界面。
 //! - **发现**（[`ArmorHealthStore::boards`]）：场上有哪几块装甲板主板，各自的 id、IP、
 //!   自报的队伍、最后一次血量。
 //!
 //! 第二种以前没有，因为队伍端不能选装甲板。现在能选了（要密码），于是"列出候选"
 //! 成为必需。**这里不需要改固件**：主板一直用 `encode_from(sender_id)` 把自己的
 //! MAC 派生 id 打进帧头，只是旧的解码路径把它丢了。
 //!
 //! # 为什么按 `(team, index)` 存最后一次读数
 //!
 //! 主板每 200 ms 广播四条（`index` 0..3，整车一条血所以 `hp` 相同）。UDP 会丢包，
 //! 界面不能"收到哪条显示哪条"——那样四个格子会各自跳。所以**四条都在新鲜期内**才交给
 //! 界面；否则退回占位符：显示一个可能已经过期的血量，比显示"未接入"更危险（现场会以为
 //! 对方还有血）。
 //!
 //! # 为什么绑 0.0.0.0
 //!
 //! 板子往 `255.255.255.255:5601` 广播，只有绑到 `INADDR_ANY` 的 socket 才收得到。
 //! 绑具体网卡地址的话，换个网络就得改配置。
 //!
 //! # 两端都开
 //!
 //! 旧客户端只在裁判端绑 5601（队伍端不显示血量）。现在队伍端要显示自己的血条，所以
 //! 两端都要收。这反而去掉了同一台机器上"队伍端与裁判端抢 5601"的争用点——两套界面
 //! 现在在同一个进程里。
 //!
 //! # 命中检测
 //!
 //! 掉血事件（[`HealthTracker`]）由这里派生：主板只上报"现在是多少血"，不报"刚刚被
 //! 打了一下"。所以命中反馈是靠**相邻两次读数之差**还原的，见那个结构体的文档。
 use std::collections::HashMap;
 use std::io::ErrorKind;
 use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, UdpSocket};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::{Duration, Instant};
 use protocol::{ArmorHealth, ARMOR_PORT};
 use crate::receiver::ARMOR_BOARDS;
 /// 多久没收到就当作板子掉线。
 ///
 /// 心跳 200 ms，所以这是连续丢了 7 个包：偶发丢一两个不会让界面闪回占位符。
 pub const STALE_AFTER: Duration = Duration::from_millis(1500);
 /// 一边的装甲板数量（0/1 两支队伍）。
 const TEAMS: usize = 2;
 /// 某个 `(team, index)` 的最后一次读数。
 #[derive(Debug, Clone, Copy)]
 struct Reading {
    hp: u16,
    at: Instant,
 }
 /// 一块装甲板主板。
 #[derive(Debug, Clone)]
 pub struct ArmorBoard {
    /// MAC 派生的板子 id，重启不变，所以绑定它不会失效。
    pub id: u32,
    /// 最后一次收到它广播的来源地址。
    pub addr: SocketAddrV4,
    /// 板子自报的队伍（编译期定的 `ARMOR_TEAM`）。
    pub team: u8,
    /// 最后一次读数里的血量。整车一条血，所以取任意一条都一样。
    pub hp: u16,
    /// 见过的 `index` 位图：低 4 位分别对应 0..3。
    ///
    /// 用来区分"这块板子只报了第 0 条"和"四条都报了"——前者通常意味着配置或固件不对，
    /// 现场值得看一眼。
    pub plates_seen: u8,
    pub last_seen: Instant,
 }
 impl ArmorBoard {
    /// 多久没有广播了。
    pub fn silence(&self) -> Duration {
        self.last_seen.elapsed()
    }
    /// 板子在线吗？
    pub fn is_online(&self) -> bool {
        self.silence() < STALE_AFTER
    }
    /// 四条装甲板都上报过吗。
    pub fn reports_all_plates(&self) -> bool {
        self.plates_seen == 0b1111
    }
 }
 /// 收到的一条装甲板上报。
 ///
 /// 比 [`protocol::ArmorHealth`] 多一个"谁发的"——那正是能列出候选、能绑定、能把命中
 /// 归到具体某块板子上的前提。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ArmorReport {
    pub board: u32,
    pub addr: SocketAddrV4,
    pub team: u8,
    pub index: u8,
    pub hp: u16,
 }
 /// 每次收到上报就调一次。
 ///
 /// 在接收线程里被调用，所以必须是非阻塞的。Tauri 层在这里做掉血检测并把结果推给界面。
 pub type ArmorSink = Arc<dyn Fn(ArmorReport) + Send + Sync>;
 /// 已收到的最新血量。
 #[derive(Debug, Default)]
 struct Inner {
    /// `readings[team][index]`。
    readings: [[Option<Reading>; ARMOR_BOARDS]; TEAMS],
    /// 按板子 id 索引的发现状态。
    boards: HashMap<u32, ArmorBoard>,
    /// 已经打过"这块板子在线"的板子 id，避免刷屏。
    announced: Vec<u32>,
    /// 已经警告过"同一队有多块板子"的队伍，避免刷屏。
    warned_multi_board: Vec<u8>,
 }
 /// 相邻两次读数之差还原出来的掉血事件。
 ///
 /// 主板不报"被打了一下"，只报"现在是 97"。所以命中反馈只能是派生的：
 ///
 /// - 血量**减少** ⇒ 一次命中，伤害是两个读数之差。
 /// - 血量**增加** ⇒ 不是命中，是长按 BOOT 的重置。忽略，但值得记一条日志。
 /// - **第一次**见到一块板子不产生命中：没有基线，此时 `hp = 0` 只是"已经没血了"，
 ///   不是"刚刚被打死"。
 ///
 /// 已知的精度上限：两次读数之间发生两次伤害时只能看到净差。心跳 200 ms，所以这段
 /// 窗口里的两次打击会被合并成一次——对"闪一下红"的用途足够，对判定不够，判定看的是
 /// 界面上的绝对血量。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Hit {
    pub board: u32,
    pub team: u8,
    pub index: u8,
    pub from: u16,
    pub to: u16,
    pub damage: u16,
 }
 /// 从连续的读数里派生命中。
 ///
 /// 按**板子**而不是按 `(板子, index)` 记基线：主板一次广播四条、`hp` 相同，按四条各记
 /// 一份基线会让一次掉血被报成四次命中。
 #[derive(Debug, Default)]
 pub struct HealthTracker {
    last: HashMap<u32, u16>,
 }
 impl HealthTracker {
    pub fn new() -> Self {
        Self::default()
    }
    /// 喂进一条上报，返回派生的命中（如果有）。
    pub fn observe(&mut self, report: &ArmorReport) -> Option<Hit> {
        let previous = self.last.insert(report.board, report.hp);
        let Some(from) = previous else {
            // 第一次见到这块板子，没有基线。
            return None;
        };
        if report.hp >= from {
            // 持平（同一次广播的另外三条）或回升（重置）。
            return None;
        }
        Some(Hit {
            board: report.board,
            team: report.team,
            index: report.index,
            from,
            to: report.hp,
            damage: from - report.hp,
        })
    }
    /// 忘掉一块板子的基线（掉线重连后重新建）。
    pub fn forget(&mut self, board: u32) {
        self.last.remove(&board);
    }
 }
 /// 监听装甲板广播的血量源。
 pub struct ArmorHealthStore {
    inner: Mutex<Inner>,
    sink: Mutex<Option<ArmorSink>>,
 }
 impl Default for ArmorHealthStore {
    fn default() -> Self {
        Self::new()
    }
 }
 impl ArmorHealthStore {
    /// 建一个 store，但先不绑端口。测试从这里喂数据报。
    pub fn new() -> Self {
        Self {
            inner: Mutex::new(Inner::default()),
            sink: Mutex::new(None),
        }
    }
    /// 绑定 5601 并起一个接收线程。
    ///
    /// 绑定失败（端口被占、权限问题）返回 `Err`，调用方退回 [`crate::NoArmorYet`] 即可
    /// ——血量显示不了不该让整个客户端起不来。
    pub fn start() -> std::io::Result<(Arc<Self>, UdpSocket)> {
        let socket = UdpSocket::bind((Ipv4Addr::UNSPECIFIED, ARMOR_PORT))?;
        socket.set_read_timeout(Some(Duration::from_millis(200)))?;
        log::info!("armor: listening for health broadcasts on UDP {ARMOR_PORT}");
        Ok((Arc::new(Self::new()), socket))
    }
    /// 在单独的线程上跑接收循环。
    pub fn spawn(self: &Arc<Self>, socket: UdpSocket) {
        let store = Arc::clone(self);
        // 线程名带上前缀，日志里一眼能看出是装甲板那条链路。
        let _ = thread::Builder::new()
            .name("armor-reader".into())
            .spawn(move || store.run(socket));
    }
    /// 接收循环。这个线程活到进程结束，不需要退出条件。
    pub fn run(&self, socket: UdpSocket) {
        let mut buf = [0u8; 256];
        loop {
            let (len, from) = match socket.recv_from(&mut buf) {
                Ok(pair) => pair,
                Err(err)
                    if err.kind() == ErrorKind::WouldBlock
                        || err.kind() == ErrorKind::TimedOut =>
                {
                    continue;
                }
                Err(err) => {
                    log::warn!("armor: receive failed: {err}");
                    // 出错后别做没有间隔的忙等（比如网卡热插拔时的 ENOBUFS）。
                    thread::sleep(Duration::from_millis(200));
                    continue;
                }
            };
            self.datagram(&buf[..len], from);
        }
    }
    /// 处理一条上报。测试从这里喂字节。
    pub fn datagram(&self, bytes: &[u8], from: SocketAddr) {
        let SocketAddr::V4(addr) = from else {
            return;
        };
        // 同一个端口上可能有别的东西（图传板的心跳、别的协议），解不出来就当不是给
        // 我的，安静跳过。
        let Some((board, health)) = ArmorHealth::decode_from(bytes) else {
            return;
        };
        let (team, index) = (health.team as usize, health.index as usize);
        if team >= TEAMS || index >= ARMOR_BOARDS {
            log::warn!(
                "armor: ignoring out-of-range report team={} index={}",
                health.team,
                health.index
            );
            return;
        }
        let report = ArmorReport {
            board,
            addr,
            team: health.team,
            index: health.index,
            hp: health.hp,
        };
        {
            let mut inner = self.inner.lock().expect("armor mutex poisoned");
            // 第一次见到某块板子就报一声：现场判断"到底连上没有"最快的线索。
            if !inner.announced.contains(&board) {
                inner.announced.push(board);
                log::info!(
                    "armor: board 0x{board:08X} is online (team {}, hp {}) via {addr}",
                    health.team,
                    health.hp
                );
            }
            // 血量变化也要能看见：窗口是给别人看的，抓日志的人得知道掉血没有。整车一条
            // 血、四条同值，所以只对 index 0 报一次。
            //
            // 上一次的读数取自**这块板子自己**的记录，而不是 `readings[team][0]`：那个
            // 槽位是"这一队"的，同队有两块板子在广播时会被互相覆盖，于是日志会把另一块
            // 板子的血量当成"这块板子之前的血量"——一条读起来像真事的假线索。
            if index == 0 {
                if let Some(previous) = inner.boards.get(&board).map(|entry| entry.hp) {
                    if previous != health.hp {
                        log::info!(
                            "armor: board 0x{board:08X} team {team} hp {previous} -> {}",
                            health.hp
                        );
                    }
                }
            }
            // 同一队出现第二块板子：说清楚后果，并提醒用绑定/指定板子 id 来消歧。
            let same_team = inner
                .boards
                .values()
                .any(|other| other.id != board && other.team == health.team && other.is_online());
            if same_team && !inner.warned_multi_board.contains(&health.team) {
                inner.warned_multi_board.push(health.team);
                log::warn!(
                    "armor: 队伍 {team} 上有不止一块装甲板在广播（现在这是 0x{board:08X}）。\
                     `health(team)` 是**最后写入者优先**，四条上报可能来自不同的板子；\
                     要确定是谁的血，请在界面上绑定/指定具体的板子 id。"
                );
            }
            inner.readings[team][index] = Some(Reading {
                hp: health.hp,
                at: Instant::now(),
            });
            let entry = inner.boards.entry(board).or_insert(ArmorBoard {
                id: board,
                addr,
                team: health.team,
                hp: health.hp,
                plates_seen: 0,
                last_seen: Instant::now(),
            });
            // 队伍是编译期定的，但同队两块板子都自报同一个 team 是正常的；这里只在
            // 板子换了 team（重刷了固件）时跟着更新。
            entry.addr = addr;
            entry.team = health.team;
            entry.hp = health.hp;
            entry.plates_seen |= 1 << index;
            entry.last_seen = Instant::now();
        }
        let sink = self.sink.lock().expect("armor sink mutex poisoned").clone();
        if let Some(sink) = sink {
            sink(report);
        }
    }
    /// 注入上报的消费者。
    pub fn set_sink(&self, sink: ArmorSink) {
        *self.sink.lock().expect("armor sink mutex poisoned") = Some(sink);
    }
    /// 场上的装甲板主板，按 id 排序。
    ///
    /// 包含已经掉线的（界面要能把"掉线"显示出来），是否在线由 [`ArmorBoard::is_online`]
    /// 判断。
    pub fn boards(&self) -> Vec<ArmorBoard> {
        let inner = self.inner.lock().expect("armor mutex poisoned");
        let mut list: Vec<ArmorBoard> = inner.boards.values().cloned().collect();
        list.sort_by_key(|b| b.id);
        list
    }
    /// 某一块板子的最新血量，太旧就返回 `None`。
    pub fn health_of_board(&self, board: u32) -> Option<u16> {
        let inner = self.inner.lock().expect("armor mutex poisoned");
        let entry = inner.boards.get(&board)?;
        if entry.silence() > STALE_AFTER {
            return None;
        }
        Some(entry.hp)
    }
    /// 四个格子的当前血量；只要有一格不新鲜就返回 `None`。
    fn fresh_hp(&self, team: u8) -> Option<[u16; ARMOR_BOARDS]> {
        let team = usize::from(team);
        if team >= TEAMS {
            return None;
        }
        let now = Instant::now();
        let inner = self.inner.lock().expect("armor mutex poisoned");
        let mut out = [0u16; ARMOR_BOARDS];
        for (index, reading) in inner.readings[team].iter().enumerate() {
            let reading = reading.as_ref()?;
            if now.duration_since(reading.at) > STALE_AFTER {
                return None;
            }
            out[index] = reading.hp;
        }
        Some(out)
    }
 }
 impl crate::receiver::ArmorSource for ArmorHealthStore {
    fn health(&self, team: u8) -> Option<[u16; ARMOR_BOARDS]> {
        self.fresh_hp(team)
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::receiver::ArmorSource;
    fn from(ip: [u8; 4]) -> SocketAddr {
        SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::from(ip), 5601))
    }
    /// 主板一次广播四条，`hp` 相同。
    fn tick(store: &ArmorHealthStore, board: u32, team: u8, hp: u16, ip: [u8; 4]) {
        for index in 0..ARMOR_BOARDS as u8 {
            let health = ArmorHealth { team, index, hp };
            store.datagram(&health.encode_from(board), from(ip));
        }
    }
    #[test]
    fn one_broadcast_yields_four_plates_of_health() {
        let store = ArmorHealthStore::new();
        tick(&store, 0xAAAA_0001, 0, 100, [192, 168, 1, 50]);
        let health = store.health(0).expect("all four plates are fresh");
        assert_eq!(health, [100, 100, 100, 100]);
        assert_eq!(store.health(1), None, "the other team sent nothing");
    }
    #[test]
    fn a_single_missing_plate_falls_back_to_the_placeholder() {
        let store = ArmorHealthStore::new();
        // 只来三条：界面宁可说"未接入"，也不要显示一个可能过期的血量。
        for index in 0..3u8 {
            let health = ArmorHealth {
                team: 0,
                index,
                hp: 88,
            };
            store.datagram(&health.encode_from(0xAAAA_0001), from([192, 168, 1, 50]));
        }
        assert_eq!(store.health(0), None);
    }
    #[test]
    fn boards_are_listed_by_their_mac_derived_id() {
        let store = ArmorHealthStore::new();
        tick(&store, 0xBBBB_0002, 1, 100, [192, 168, 1, 60]);
        tick(&store, 0xAAAA_0001, 0, 100, [192, 168, 1, 50]);
        let boards = store.boards();
        let ids: Vec<u32> = boards.iter().map(|b| b.id).collect();
        assert_eq!(ids, vec![0xAAAA_0001, 0xBBBB_0002], "sorted, stable order");
        assert_eq!(boards[0].team, 0);
        assert_eq!(boards[1].team, 1);
        assert!(boards[0].reports_all_plates());
        assert!(boards[0].is_online());
    }
    #[test]
    fn health_of_board_ignores_out_of_range_and_garbage() {
        let store = ArmorHealthStore::new();
        // team/index 越界：丢掉并留一条警告，而不是写进 readings 把数组撑爆。
        let bad = ArmorHealth {
            team: 9,
            index: 0,
            hp: 100,
        };
        store.datagram(&bad.encode_from(1), from([192, 168, 1, 1]));
        assert!(store.boards().is_empty());
        // 不是装甲板上报的字节：安静跳过。
        store.datagram(&[0u8; 64], from([192, 168, 1, 1]));
        assert!(store.boards().is_empty());
    }
    #[test]
    fn the_sink_sees_every_report_with_its_board_id() {
        let store = ArmorHealthStore::new();
        let seen = Arc::new(Mutex::new(Vec::new()));
        let tap = Arc::clone(&seen);
        store.set_sink(Arc::new(move |report: ArmorReport| {
            tap.lock().unwrap().push((report.board, report.index, report.hp));
        }));
        tick(&store, 7, 0, 100, [192, 168, 1, 50]);
        assert_eq!(seen.lock().unwrap().len(), ARMOR_BOARDS);
    }
    #[test]
    fn two_boards_on_the_same_team_share_the_per_team_slot() {
        // 这是 `health(team)` 的已知限制，不是意外：一个队里同时有两块板子广播时，那
        // 四个格子是"最后写入者优先"，可能混着两块板子的数。真实比赛里一队只有一块，
        // 所以这条路径只在开发（演示 + 真板子）或烧错固件时才会走到。
        //
        // 消歧的办法是绑定具体的板子 id，走 `health_of_board`。
        let store = ArmorHealthStore::new();
        tick(&store, 0xAAAA_0001, 0, 100, [192, 168, 1, 50]);
        tick(&store, 0xBBBB_0002, 0, 40, [192, 168, 1, 60]);
        // 后写的那块板子赢了。
        assert_eq!(store.health(0), Some([40, 40, 40, 40]));
        // 按板子取就没这个歧义。
        assert_eq!(store.health_of_board(0xAAAA_0001), Some(100));
        assert_eq!(store.health_of_board(0xBBBB_0002), Some(40));
        // 两块板子都还在发现列表里，界面才能让人选。
        assert_eq!(store.boards().len(), 2);
    }
    #[test]
    fn a_falling_hp_is_exactly_one_hit() {
        let mut tracker = HealthTracker::new();
        let report = |hp: u16, index: u8| ArmorReport {
            board: 1,
            addr: "192.168.1.50:5601".parse().unwrap(),
            team: 0,
            index,
            hp,
        };
        // 第一次上报只是建立基线，不是"刚刚被打死"。
        for index in 0..4u8 {
            assert_eq!(tracker.observe(&report(100, index)), None);
        }
        // 掉血：四条同值的上报里只有第一条该产生命中。
        let hits: Vec<Option<Hit>> = (0..4u8).map(|i| tracker.observe(&report(97, i))).collect();
        assert_eq!(
            hits[0],
            Some(Hit {
                board: 1,
                team: 0,
                index: 0,
                from: 100,
                to: 97,
                damage: 3,
            })
        );
        assert!(
            hits[1..].iter().all(Option::is_none),
            "the other three datagrams carry the same hp and must not be hits"
        );
    }
    #[test]
    fn a_reset_is_not_a_hit() {
        let mut tracker = HealthTracker::new();
        let addr = "192.168.1.50:5601".parse().unwrap();
        let report = |hp: u16| ArmorReport {
            board: 1,
            addr,
            team: 0,
            index: 0,
            hp,
        };
        tracker.observe(&report(100));
        assert!(tracker.observe(&report(0)).is_some(), "death is a hit");
        assert_eq!(
            tracker.observe(&report(100)),
            None,
            "长按 BOOT 重置成满血不是一次命中"
        );
    }
    #[test]
    fn a_board_first_seen_at_zero_hp_produces_no_hit() {
        let mut tracker = HealthTracker::new();
        let report = ArmorReport {
            board: 1,
            addr: "192.168.1.50:5601".parse().unwrap(),
            team: 0,
            index: 0,
            hp: 0,
        };
        assert_eq!(tracker.observe(&report), None);
    }
    #[test]
    fn two_boards_keep_separate_baselines() {
        let mut tracker = HealthTracker::new();
        let addr = "192.168.1.50:5601".parse().unwrap();
        let report = |board: u32, hp: u16| ArmorReport {
            board,
            addr,
            team: 0,
            index: 0,
            hp,
        };
        tracker.observe(&report(1, 100));
        tracker.observe(&report(2, 100));
        let hit = tracker.observe(&report(2, 90)).expect("board 2 was hit");
        assert_eq!(hit.board, 2);
        assert_eq!(hit.damage, 10);
        assert_eq!(
            tracker.observe(&report(1, 100)),
            None,
            "board 1 is untouched, not a 10-point heal"
        );
    }
 }
@@ -0,0 +1,43 @@
 //! cam-core —— 桌面端的非界面部分。
 //!
 //! 这一层不认识 Tauri，也不认识任何界面：它只负责
 //!
 //! - [`receiver`]：收 UDP、发现摄像头、按发送方重组 JPEG 帧；
 //! - [`armor`]：收装甲板主板广播的血量，并列出场上有哪几块板子；
 //! - [`stats`]：帧率统计（按帧数除以墙钟，不是对帧间隔取平均）；
 //! - [`config`]：磁盘上的配置（身份、绑定、HUD、密码哈希）；
 //! - [`password`]：密码的哈希与校验。
 //!
 //! # 为什么单独一层
 //!
 //! 旧的 Slint 客户端把这几件事和界面耦合在一个 crate 里，于是**它们只能通过跑起
 //! 整个界面来验证**。抽出来之后，重组、发现、帧率窗口、血量新鲜度都能用单元测试
 //! 直接盯住——而它们恰好是最容易错、错了又最难在现场看出来的部分。
 //!
 //! # 界面怎么拿数据
 //!
 //! 两条路，都是**推**而不是轮询：
 //!
 //! - 视频帧走 [`receiver::Receiver::set_frame_sink`]：接收线程重组好一张 JPEG 就
 //!   交给 sink，由上层转成 WebSocket 的二进制消息。sink 必须是非阻塞的。
 //! - 血量走 [`armor::ArmorHealthStore::set_sink`]：每收到一条上报就交给 sink。
 //!
 //! 同时两边的**最新值**都留在内存里（[`receiver::LatestFrames`] 与
 //! [`armor::ArmorHealthStore::boards`]），给"截图"和"设置界面里的下拉列表"用——
 //! 那两处要的是当前状态，不是每一帧。
 pub mod armor;
 pub mod config;
 pub mod password;
 pub mod receiver;
 pub mod slots;
 pub mod snapshot;
 pub mod stats;
 pub use config::{Config, HudConfig, Role};
 pub use receiver::{
    ArmorSource, CameraInfo, FrameSink, LatestFrames, NoArmorYet, Receiver, SourceStats,
    ARMOR_BOARDS,
 };
 pub use slots::SlotAllocator;
 pub use stats::FpsWindow;
@@ -0,0 +1,161 @@
 //! 密码：哈希、校验、强度下限。
 //!
 //! # 这把锁挡的是谁
 //!
 //! 必须说清楚，否则会被当成一把它并不是的锁：
 //!
 //! - **挡得住**：现场随手改绑定。选手想把自己的画面换到对手那块板子上，得先知道密码；
 //!   围观的人翻不到明文密码（只有 Argon2id 哈希），也不能靠改配置文件把绑定改掉——
 //!   改了之后界面会要求先解锁。
 //! - **挡不住**：一个愿意在自己机器上重编这个客户端的人。配置文件与二进制都在他手上，
 //!   删掉哈希、或者直接改源码都行。真正封住这件事要靠固件侧的配对 token（见根 README
 //!   里"这挡不住什么"那一节）。
 //!
 //! 所以它的定位是**防误触与防随手改**，不是密码学意义上的对抗。这也是为什么强度下限
 //! 只要 4 位：一个 8 位强密码在这里换不来任何实际的安全增益，却会让现场每次改绑都要
 //! 掏手机查一遍。
 //!
 //! # 为什么是 Argon2 而不是 SHA-256
 //!
 //! 密码短（4 位数字只有 1 万种），任何**快**哈希都能在一秒内被穷举完。Argon2id 是
 //! 内存硬的，把每次尝试的代价抬到几十毫秒——即使密码很短，"改配置文件暴力试密码"
 //! 这条路也变得不划算。存的是标准的 PHC 字符串（`$argon2id$v=19$m=...`），参数跟着
 //! 哈希一起躺在配置里，所以以后调参数不需要做迁移。
 use anyhow::{anyhow, Result};
 use argon2::password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString};
 use argon2::Argon2;
 use rand::RngCore;
 /// 密码的最短长度。
 ///
 /// 见模块文档：这不是安全边界，长度下限只用来挡住"密码是 1 个字符"这种显然是随手打的
 /// 情况。
 pub const MIN_PASSWORD_LEN: usize = 4;
 /// 算一个密码的 PHC 字符串。
 ///
 /// 每次调用都用新的随机盐，所以同一个密码两次得到的结果不同——这样哈希不能当查找表用。
 pub fn hash_password(password: &str) -> Result<String> {
    check_strength(password)?;
    let mut salt = [0u8; 16];
    rand::rng().fill_bytes(&mut salt);
    let salt = SaltString::encode_b64(&salt)
        .map_err(|err| anyhow!("could not encode the salt: {err}"))?;
    // Argon2::default() 就是 Argon2id、v19、Params::DEFAULT（19 MiB，t=2）。
    let hash = Argon2::default()
        .hash_password(password.as_bytes(), &salt)
        .map_err(|err| anyhow!("could not hash the password: {err}"))?;
    Ok(hash.to_string())
 }
 /// 校验一个密码。
 ///
 /// 返回 `Ok(false)` 表示"密码不对"，返回 `Err` 表示"存下来的哈希本身坏了"——这两种
 /// 必须区分开：前者是用户输错了，后者是配置文件被改坏了，界面上要给完全不同的提示。
 pub fn verify_password(password: &str, phc: &str) -> Result<bool> {
    let parsed = PasswordHash::new(phc)
        .map_err(|err| anyhow!("the stored password hash is not a valid PHC string: {err}"))?;
    // `password-hash` 的解析器很宽松：`$argon2id$broken` 这种**截断**的字符串也能解析
    // 成功，只是解析出来的对象里没有盐、没有摘要。于是所有校验都失败，被 `is_ok()`
    // 读成"密码错了"——现场表现是"密码明明是对的，却一直说密码错"，然后所有人开始
    // 怀疑键盘。所以这里显式要求盐与摘要都在。
    if parsed.salt.is_none() || parsed.hash.is_none() {
        return Err(anyhow!(
            "the stored password hash is incomplete (no salt or no digest): {phc:?}"
        ));
    }
    Ok(Argon2::default()
        .verify_password(password.as_bytes(), &parsed)
        .is_ok())
 }
 /// 检查长度下限。
 pub fn check_strength(password: &str) -> Result<()> {
    if password.chars().count() < MIN_PASSWORD_LEN {
        return Err(anyhow!(
            "密码至少 {MIN_PASSWORD_LEN} 位（现在是 {} 位）",
            password.chars().count()
        ));
    }
    Ok(())
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn a_password_verifies_against_its_own_hash() {
        let phc = hash_password("1234").expect("hashes");
        assert!(verify_password("1234", &phc).expect("verifies"));
    }
    #[test]
    fn a_wrong_password_is_false_not_an_error() {
        let phc = hash_password("1234").expect("hashes");
        assert!(!verify_password("1235", &phc).expect("the hash itself is fine"));
        assert!(!verify_password("", &phc).expect("the hash itself is fine"));
    }
    #[test]
    fn the_same_password_hashes_differently_every_time() {
        // 随机盐：否则配置文件里的哈希就是一个可以拿去查表的指纹。
        let a = hash_password("1234").expect("hashes");
        let b = hash_password("1234").expect("hashes");
        assert_ne!(a, b, "a fresh salt each time");
        assert!(verify_password("1234", &a).unwrap());
        assert!(verify_password("1234", &b).unwrap());
    }
    #[test]
    fn the_hash_is_argon2id_and_carries_its_parameters() {
        // 参数写在 PHC 字符串里，所以以后调参数不需要迁移旧配置。
        let phc = hash_password("1234").expect("hashes");
        assert!(phc.starts_with("$argon2id$"), "got {phc}");
        assert!(phc.contains("$v=19$"), "got {phc}");
    }
    #[test]
    fn a_known_phc_string_still_verifies() {
        // 一条固定的 Argon2id PHC 串，密码是 1234。
        //
        // 作用是把"已经写进某个人的配置文件里的哈希，将来还能不能验证"钉下来：换库、
        // 换默认参数、或者手滑把 salt 的编码改成别的形式时，这条会立刻失败——而它失败的
        // 那一天，现场的表现会是"密码明明对，却一直说密码错"。
        const PHC: &str = "$argon2id$v=19$m=19456,t=2,p=1$rBxlGFBYgghR/PPmKlx++A$B7J4JeKgDzv4JdNycjf7rb+5UPgO9JY+KhURaZtn5R0";
        assert!(verify_password("1234", PHC).expect("verifies"));
        assert!(!verify_password("1235", PHC).expect("the hash itself is fine"));
    }
    #[test]
    fn a_corrupt_stored_hash_is_an_error_not_a_wrong_password() {
        // 这两种情况必须能分开：一个是输错了，一个是配置文件坏了。
        assert!(verify_password("1234", "not a phc string").is_err());
        assert!(verify_password("1234", "$argon2id$broken").is_err());
    }
    #[test]
    fn a_too_short_password_is_refused_at_set_time() {
        assert!(hash_password("123").is_err());
        assert!(hash_password("").is_err());
        assert!(hash_password("1234").is_ok());
    }
    #[test]
    fn a_non_ascii_password_works() {
        let phc = hash_password("口令甲乙").expect("hashes");
        assert!(verify_password("口令甲乙", &phc).unwrap());
        assert!(!verify_password("口令甲丙", &phc).unwrap());
    }
 }
@@ -0,0 +1,764 @@
 //! UDP 接收、发现、多路帧重组。
 //!
 //! # 多路
 //!
 //! 裁判终端同时收两块图传板，队伍终端也会收到两块（只是界面上只显示绑定的那一块）。
 //! 所以重组状态**必须按发送方分开**——把两块板的帧塞进同一个重组器，会让它们各自的
 //! `frame_id` 互相顶掉，两路都出不来。
 //!
 //! # 发现与订阅
 //!
 //! 两个方向各司其职：
 //!
 //! - 板子每 2 秒广播一次 [`protocol::MsgType::Hello`]，客户端被动收到就知道有谁在线。
 //! - 客户端广播 [`protocol::MsgType::Subscribe`]，板子收到后开始定向推流。
 //!
 //! 板子靠**源地址**记住客户端，所以客户端只要周期性续订就能维持推流，不存在任何
 //! 超时淘汰的竞态。
 //!
 //! # 丢帧策略
 //!
 //! 缺了分片的帧整个丢弃、下一帧顶上，不重传也不尝试补洞。对实时画面这是对的：等
 //! 重传补齐时，那一帧早就不新鲜了。代价是丢帧率必须摆在界面上，否则"画面卡"没法
 //! 区分是链路问题还是传感器问题。
 //!
 //! # 两道闸门，不是一个
 //!
 //! 旧客户端只有一道 `only_sender`：队伍端绑定了之后，连**发现**别人的板子都做不到，
 //! 于是"改绑"只能靠手改配置文件或删文件。
 //!
 //! 现在绑定可以在界面上改（需密码），所以闸门分成两道：
 //!
 //! | 闸门 | 管什么 | 什么时候开 |
 //! |---|---|---|
 //! | `only_sender` | 帧的重组与投递 | 队伍端始终是绑定的那一块 |
 //! | `discovery_all` | 是否记录**其它**板子的 Hello | 只在密码解锁后的设置界面里打开 |
 //!
 //! 这是有意的加强而不是放松：设置界面需要列出候选摄像头（否则无从选起），但**画面
 //! 不需要**——对手的板子即使把流推到本机端口、即使被记进发现列表，它的帧仍然进不了
 //! 重组器。旧版把两件事绑在一道闸门上，只能在"能列候选"和"挡住对手"之间二选一。
 //!
 //! # 可测性
 //!
 //! 数据报的处理（[`Receiver::datagram`]）与 socket 完全分开：测试直接喂字节进去，
 //! 不需要绑 5600 端口，也就不需要真实网络。
 use std::collections::HashMap;
 use std::io::ErrorKind;
 use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, UdpSocket};
 use std::sync::atomic::{AtomicBool, Ordering};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::{Duration, Instant};
 use protocol::{
    Fragment, FrameAssembler, Subscribe, SubscribeRole, DEFAULT_PORT, HEADER_LEN,
 };
 /// 接受的最大数据报。高于协议的理论上限（1427），留出余量，这样一个被截断的读只可能
 /// 来自网络，而不是来自过小的缓冲。
 const RECV_BUFFER: usize = 2048;
 /// 重新广播订阅的间隔。
 ///
 /// 比板子判定"客户端掉线"的超时（6 秒）短得多，所以偶发丢一两个包不会中断推流。
 const SUBSCRIBE_INTERVAL: Duration = Duration::from_millis(800);
 /// 一张帧没收齐就放弃的时限。
 ///
 /// 一帧在 22fps 下约 45ms 到，所以几百毫秒还没齐的永远不会齐了。
 const FRAME_TIMEOUT: Duration = Duration::from_millis(500);
 /// 一块已知的图传板。
 #[derive(Debug, Clone)]
 pub struct CameraInfo {
    pub id: u32,
    pub addr: SocketAddrV4,
    pub firmware: u16,
    /// 最近一次收到它广播的时刻。
    pub last_seen: Instant,
 }
 impl CameraInfo {
    /// 多久没有广播了。
    pub fn silence(&self) -> Duration {
        self.last_seen.elapsed()
    }
    /// 板子在线吗？
    ///
    /// 阈值是广播间隔的数倍，所以偶发丢包不会让界面上的在线状态闪烁。
    pub fn is_online(&self) -> bool {
        self.silence() < Duration::from_secs(7)
    }
 }
 /// 一块板的运行时统计。
 #[derive(Debug, Clone, Copy, Default)]
 pub struct SourceStats {
    pub frames_shown: u64,
    /// 因分片缺失被放弃的帧。
    pub frames_dropped: u64,
    pub datagrams: u64,
    pub last_frame_len: usize,
    pub width: u16,
    pub height: u16,
    /// 上一帧到这一帧之间的间隔。
    pub last_interval: Option<Duration>,
    last_shown_at: Option<Instant>,
 }
 impl SourceStats {
    /// 丢弃的帧占已收到帧的比例。
    pub fn loss_percent(&self) -> f32 {
        let total = self.frames_shown + self.frames_dropped;
        if total == 0 {
            0.0
        } else {
            self.frames_dropped as f32 * 100.0 / total as f32
        }
    }
    /// 上一帧到这一帧的间隔，毫秒。
    pub fn gap_ms(&self) -> Option<f32> {
        self.last_interval.map(|d| d.as_secs_f32() * 1000.0)
    }
    fn on_frame(&mut self, width: u16, height: u16, len: usize) {
        self.last_interval = self.last_shown_at.map(|t| t.elapsed());
        self.last_shown_at = Some(Instant::now());
        self.frames_shown += 1;
        self.width = width;
        self.height = height;
        self.last_frame_len = len;
    }
 }
 /// 每一路的**最新**一帧。
 ///
 /// 每路只保留最新的一张：这张图有两个用途，都不需要历史——截图（存盘的那一张应该
 /// 是按下按钮时看到的画面）和慢速客户端的补帧。真正的实时画面走
 /// [`Receiver::set_frame_sink`] 的推送路径，不从这里取。
 ///
 /// 用 `Arc` 而不是 `Vec<u8>`：同一张帧要同时给 sink 和这个缓存，克隆一个 22 kB 的
 /// 缓冲区是每秒 22 次不必要的分配。
 #[derive(Default)]
 pub struct LatestFrames {
    inner: Mutex<HashMap<u32, Arc<protocol::Frame>>>,
 }
 impl LatestFrames {
    pub fn put(&self, frame: Arc<protocol::Frame>) {
        self.inner
            .lock()
            .expect("latest-frames mutex poisoned")
            .insert(frame.sender_id, frame);
    }
    /// 取某一路的最新帧（克隆的是 `Arc`，不是 JPEG）。
    pub fn latest(&self, sender_id: u32) -> Option<Arc<protocol::Frame>> {
        self.inner
            .lock()
            .expect("latest-frames mutex poisoned")
            .get(&sender_id)
            .cloned()
    }
    /// 所有已知来源的最新帧，按 id 排序，让界面上的顺序稳定。
    pub fn latest_all(&self) -> Vec<Arc<protocol::Frame>> {
        let mut list: Vec<Arc<protocol::Frame>> = self
            .inner
            .lock()
            .expect("latest-frames mutex poisoned")
            .values()
            .cloned()
            .collect();
        list.sort_by_key(|f| f.sender_id);
        list
    }
 }
 /// 帧的消费者。
 ///
 /// 在接收线程里被调用，所以**必须是非阻塞的**：一次 `send` 到一个有界广播通道、
 /// 一次 `try_send`，都可以；写文件、等锁、发网络请求都不行——那会把接收循环拖慢，
 /// 表现为链路上本不存在的丢帧。
 pub type FrameSink = Arc<dyn Fn(Arc<protocol::Frame>) + Send + Sync>;
 /// 所有板子的共享状态，跨线程只读。
 pub struct Discovery {
    cameras: Mutex<HashMap<u32, CameraInfo>>,
    stats: Mutex<HashMap<u32, SourceStats>>,
 }
 impl Discovery {
    fn new() -> Self {
        Self {
            cameras: Mutex::new(HashMap::new()),
            stats: Mutex::new(HashMap::new()),
        }
    }
    /// 当前已知的板子，按 id 排序。
    pub fn cameras(&self) -> Vec<CameraInfo> {
        let mut list: Vec<CameraInfo> = self
            .cameras
            .lock()
            .expect("cameras mutex poisoned")
            .values()
            .cloned()
            .collect();
        list.sort_by_key(|c| c.id);
        list
    }
    /// 在线且刚刚广播过的板子。
    pub fn online_cameras(&self) -> Vec<CameraInfo> {
        self.cameras()
            .into_iter()
            .filter(CameraInfo::is_online)
            .collect()
    }
    /// 某一路的统计。
    pub fn stats(&self, sender_id: u32) -> SourceStats {
        self.stats
            .lock()
            .expect("stats mutex poisoned")
            .get(&sender_id)
            .copied()
            .unwrap_or_default()
    }
    /// 只刷新存活时间戳，不改地址或固件版本。
    ///
    /// 收到视频帧时调用：正在推流本身就是最可靠的存活证据。
    fn touch(&self, id: u32) {
        let mut cameras = self.cameras.lock().expect("cameras mutex poisoned");
        if let Some(info) = cameras.get_mut(&id) {
            info.last_seen = Instant::now();
        }
    }
    fn note_hello(&self, id: u32, addr: SocketAddrV4, firmware: u16) -> bool {
        let mut cameras = self.cameras.lock().expect("cameras mutex poisoned");
        match cameras.get_mut(&id) {
            Some(info) => {
                info.addr = addr;
                info.last_seen = Instant::now();
                info.firmware = firmware;
                false
            }
            None => {
                cameras.insert(
                    id,
                    CameraInfo {
                        id,
                        addr,
                        firmware,
                        last_seen: Instant::now(),
                    },
                );
                true
            }
        }
    }
    fn note_frame(&self, id: u32, width: u16, height: u16, len: usize) {
        let mut stats = self.stats.lock().expect("stats mutex poisoned");
        stats.entry(id).or_default().on_frame(width, height, len);
    }
    fn count(&self, id: u32, f: impl FnOnce(&mut SourceStats)) {
        let mut stats = self.stats.lock().expect("stats mutex poisoned");
        f(stats.entry(id).or_default());
    }
    /// 超过 `max_idle` 没有广播的板子从列表里移除。
    ///
    /// 界面上不会留下一堆永远离线的板子。
    pub fn forget_silent_cameras(&self, max_idle: Duration) {
        self.cameras
            .lock()
            .expect("cameras mutex poisoned")
            .retain(|_, c| c.silence() < max_idle);
    }
 }
 /// 客户端身份。
 ///
 /// 常量而非 MAC 派生：队伍客户端和裁判终端各自唯一，进程内也不需要区分自己，而一个
 /// 确定的常量让日志更好读。
 pub const CLIENT_ID: u32 = 0x0C11_0001;
 /// 接收循环的可变状态：只由接收线程在跑循环时访问。
 struct Ingest {
    /// 每个发送方一个重组器。
    assemblers: HashMap<u32, FrameAssembler>,
    /// 只处理这一块板子的**帧**，`None` 表示全都要（裁判端）。
    only_sender: Option<u32>,
    /// 是否记录**其它**板子的 Hello。
    discovery_all: bool,
 }
 /// 接收器。
 ///
 /// 构造（[`Receiver::new`]）不碰网络，`run` 才需要 socket。这样数据报处理的逻辑可以
 /// 在没有网络的情况下被单元测试直接喂字节。
 pub struct Receiver {
    discovery: Arc<Discovery>,
    latest: Arc<LatestFrames>,
    /// 帧的非阻塞消费者，由上层注入。
    sink: Mutex<Option<FrameSink>>,
    ingest: Mutex<Ingest>,
    /// 身份可以运行时切换（同一个进程里从裁判端切到用户端），所以订阅里声明的角色
    /// 也得能改——它决定板子要不要给这个客户端推流。
    role: Mutex<SubscribeRole>,
    camera: Ipv4Addr,
    stop: Arc<AtomicBool>,
 }
 impl Receiver {
    /// 建一个接收器，但先不绑端口。
    ///
    /// `only_sender` 为 `Some` 时只接受那一块板子的帧。
    pub fn new(camera: Ipv4Addr, role: SubscribeRole, only_sender: Option<u32>) -> Self {
        Self {
            discovery: Arc::new(Discovery::new()),
            latest: Arc::new(LatestFrames::default()),
            sink: Mutex::new(None),
            ingest: Mutex::new(Ingest {
                assemblers: HashMap::new(),
                only_sender,
                discovery_all: false,
            }),
            role: Mutex::new(role),
            camera,
            stop: Arc::new(AtomicBool::new(false)),
        }
    }
    /// 绑定视频端口并准备好发现。
    ///
    /// 绑定固定端口（而非临时端口）是必须的：板子是从订阅的**源端口**学到推流目标的。
    /// 绑定在这里而不是在接收线程里，这样"端口被占用"会立刻报错，而不是被线程吞掉、
    /// 表现为一个永远不出画面的空窗口。
    pub fn start(
        camera: Ipv4Addr,
        role: SubscribeRole,
        only_sender: Option<u32>,
    ) -> std::io::Result<(Self, UdpSocket)> {
        let socket =
            UdpSocket::bind(SocketAddrV4::new(Ipv4Addr::UNSPECIFIED, DEFAULT_PORT))?;
        socket.set_read_timeout(Some(Duration::from_millis(100)))?;
        let broadcast = socket.set_broadcast(true).is_ok();
        if !broadcast {
            log::warn!("could not enable broadcast on the socket");
        }
        Ok((Self::new(camera, role, only_sender), socket))
    }
    /// 绑定之后切换限制目标，或解除限制。
    ///
    /// 队伍端在设置界面里改绑一块板子时调用。
    pub fn restrict_to(&self, only_sender: Option<u32>) {
        self.ingest
            .lock()
            .expect("ingest mutex poisoned")
            .only_sender = only_sender;
    }
    /// 当前限制到哪一块板子。
    pub fn sender_limit(&self) -> Option<u32> {
        self.ingest.lock().expect("ingest mutex poisoned").only_sender
    }
    /// 切换身份，下一次续订就生效（800 ms 内）。
    pub fn set_role(&self, role: SubscribeRole) {
        *self.role.lock().expect("role mutex poisoned") = role;
    }
    /// 当前在订阅里声明的身份。
    pub fn role(&self) -> SubscribeRole {
        *self.role.lock().expect("role mutex poisoned")
    }
    /// 是否允许发现列表里出现**其它**板子。
    ///
    /// 只在密码解锁后的设置界面里打开，见本模块的文档。
    pub fn set_discovery_all(&self, all: bool) {
        self.ingest
            .lock()
            .expect("ingest mutex poisoned")
            .discovery_all = all;
    }
    /// 注入帧的消费者。重复调用会替换掉旧的。
    pub fn set_frame_sink(&self, sink: FrameSink) {
        *self.sink.lock().expect("sink mutex poisoned") = Some(sink);
    }
    pub fn discovery(&self) -> Arc<Discovery> {
        Arc::clone(&self.discovery)
    }
    pub fn latest_frames(&self) -> Arc<LatestFrames> {
        Arc::clone(&self.latest)
    }
    /// 处理一个数据报。测试从这里喂字节。
    pub fn datagram(&self, bytes: &[u8], from: SocketAddr) {
        if bytes.len() < HEADER_LEN {
            return;
        }
        let (limit, discovery_all) = {
            let ingest = self.ingest.lock().expect("ingest mutex poisoned");
            (ingest.only_sender, ingest.discovery_all)
        };
        // 板子的在线通告。注意这里不看来源端口：广播来的源端口没有意义，身份由头里
        // 的 sender_id 决定。
        if let Some(hello) = protocol::Hello::decode(bytes) {
            let SocketAddr::V4(v4) = from else {
                return;
            };
            // 限制生效且没开发现：别人的板子连记都不记。不记的理由不只是"不显示"——
            // 记进 discovery 之后，界面上任何一处遍历 cameras() 的地方都会间接泄露
            // 场上还有谁。
            if let Some(only) = limit {
                if !discovery_all && hello.sender_id != only {
                    return;
                }
            }
            if self.discovery.note_hello(hello.sender_id, v4, hello.firmware) {
                log::info!("found camera 0x{:08X} at {v4}", hello.sender_id);
            }
            return;
        }
        let Some(frag) = Fragment::decode(bytes) else {
            // 既不是 Hello 也不是合法分片：将来的其它消息，或一次损坏。
            return;
        };
        let id = frag.header.sender_id;
        // 帧的重组与投递过的是**另一道**闸门：发现列表里能看到对手的板子，不等于
        // 它的画面会进来。
        if let Some(only) = limit {
            if id != only {
                return;
            }
        }
        // 视频帧也算存活证据。
        //
        // `is_online` 看的是 `last_seen`，而它此前只由 Hello 更新。于是会出现一个
        // 荒唐的状态：画面在每秒刷 22 帧，状态栏却显示"离线"（橙色）。正在推流的板子
        // 比广播更可靠地证明自己活着。
        self.discovery.touch(id);
        let mut ingest = self.ingest.lock().expect("ingest mutex poisoned");
        let assembler = ingest
            .assemblers
            .entry(id)
            .or_insert_with(|| FrameAssembler::new(FRAME_TIMEOUT));
        match assembler.push(frag) {
            Ok(frame) => {
                drop(ingest);
                self.discovery.count(id, |s| s.datagrams += 1);
                self.discovery
                    .note_frame(id, frame.width, frame.height, frame.data.len());
                let frame = Arc::new(frame);
                self.latest.put(Arc::clone(&frame));
                let sink = self.sink.lock().expect("sink mutex poisoned").clone();
                if let Some(sink) = sink {
                    sink(frame);
                }
            }
            Err(protocol::DropReason::Superseded) => {
                // 被更新的帧追上了。这不是丢帧：半截的那张只是被超越，在健康链路上
                // 这是帧被放弃的**正常**方式。
                self.discovery.count(id, |s| s.datagrams += 1);
            }
            Err(protocol::DropReason::TimedOut) => {
                self.discovery.count(id, |s| {
                    s.datagrams += 1;
                    s.frames_dropped += 1;
                });
            }
        }
    }
    /// 放弃等太久的半截帧。接收循环周期性调用。
    pub fn expire_stalled_frames(&self) {
        let mut ingest = self.ingest.lock().expect("ingest mutex poisoned");
        let mut expired = Vec::new();
        for (id, assembler) in ingest.assemblers.iter_mut() {
            if assembler.expire().is_some() {
                expired.push(*id);
            }
        }
        drop(ingest);
        for id in expired {
            self.discovery.count(id, |s| s.frames_dropped += 1);
        }
    }
    /// 运行接收循环，直到 [`Receiver::shutdown`]。
    ///
    /// 阻塞，所以放在单独的线程上。
    pub fn run(&self, socket: UdpSocket) {
        let target = SocketAddrV4::new(self.camera, DEFAULT_PORT);
        let mut buf = [0u8; RECV_BUFFER];
        let mut last_subscribe = Instant::now() - SUBSCRIBE_INTERVAL;
        let mut last_sweep = Instant::now();
        log::info!(
            "listening on UDP {DEFAULT_PORT}, announcing {:?} to {target}",
            self.role()
        );
        while !self.stop.load(Ordering::Relaxed) {
            // 周期性续订就是保活：板子在 6 秒收不到就认为我们走了。
            //
            // 每次现编订阅包而不是循环外编一次：身份可以运行时切换，编一次的话切换后
            // 板子收到的还是旧角色。800 ms 一次，这点分配无所谓。
            if last_subscribe.elapsed() >= SUBSCRIBE_INTERVAL {
                let subscribe = Subscribe {
                    role: self.role(),
                    client_id: CLIENT_ID,
                };
                if let Err(err) = socket.send_to(&subscribe.encode(), target) {
                    log::warn!("could not subscribe at {target}: {err}");
                }
                last_subscribe = Instant::now();
            }
            match socket.recv_from(&mut buf) {
                Ok((n, from)) => self.datagram(&buf[..n], from),
                Err(err)
                    if err.kind() == ErrorKind::WouldBlock
                        || err.kind() == ErrorKind::TimedOut =>
                {
                    // 帧之间的常态。读超时正是让退出能及时响应的原因。
                }
                Err(err) => {
                    log::warn!("recv failed: {err}");
                    thread::sleep(Duration::from_millis(100));
                }
            }
            self.expire_stalled_frames();
            if last_sweep.elapsed() >= Duration::from_secs(5) {
                self.discovery
                    .forget_silent_cameras(Duration::from_secs(60));
                last_sweep = Instant::now();
            }
        }
        log::info!("receive loop stopped");
    }
    pub fn shutdown(&self) {
        self.stop.store(true, Ordering::Relaxed);
    }
 }
 /// 装甲板血量的来源。
 ///
 /// 真实实现是 [`crate::armor::ArmorHealthStore`]。这里只定接口，解码与新鲜度判断都在
 /// 那个模块里——也让"没有数据源"这件事有一个明确的替身（[`NoArmorYet`]），而不是
 /// 让界面去处理 `Option<Option<...>>`。
 pub trait ArmorSource: Send + Sync {
    /// 某一边的血量。
    ///
    /// 返回 4 个装甲板的当前血量，按 index 排列。没有数据时返回 `None`，界面据此显示
    /// 占位符而不是 0——0 是一个看起来像真值的假值。
    fn health(&self, team: u8) -> Option<[u16; 4]>;
 }
 /// 一边的装甲板数量。
 ///
 /// RoboMaster 规则是每队 4 块。界面按这个数量画格子，所以数据还没接上时也能看到位置
 /// ——空着比画 0 个格子更让人以为布局坏了。
 pub const ARMOR_BOARDS: usize = 4;
 /// 没有数据源时的替身：什么都不提供，界面显示占位符。
 pub struct NoArmorYet;
 impl ArmorSource for NoArmorYet {
    fn health(&self, _team: u8) -> Option<[u16; 4]> {
        None
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use protocol::{fragment_frame, Hello, MsgType};
    /// 一个完整的 JPEG 分片集合，足够让重组器交出一张帧。
    fn jpeg() -> Vec<u8> {
        (0..5000u32).map(|i| (i % 251) as u8).collect()
    }
    fn from(ip: [u8; 4]) -> SocketAddr {
        SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::from(ip), 5600))
    }
    fn feed_frame(rx: &Receiver, sender: u32, frame_id: u32, from_ip: [u8; 4]) {
        for frag in fragment_frame(sender, frame_id, &jpeg(), 640, 480) {
            rx.datagram(&frag.encode(), from(from_ip));
        }
    }
    fn feed_hello(rx: &Receiver, sender: u32, from_ip: [u8; 4]) {
        let hello = Hello {
            sender_id: sender,
            firmware: 7,
        };
        rx.datagram(&hello.encode(MsgType::Hello), from(from_ip));
    }
    #[test]
    fn delivers_the_latest_frame_of_the_bound_sender_only() {
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Team, Some(1));
        feed_frame(&rx, 1, 10, [192, 168, 1, 10]);
        feed_frame(&rx, 2, 20, [192, 168, 1, 20]);
        assert!(
            rx.latest_frames().latest(1).is_some(),
            "the bound camera must come through"
        );
        assert!(
            rx.latest_frames().latest(2).is_none(),
            "an opponent's board must not even be reassembled"
        );
    }
    #[test]
    fn the_sink_sees_exactly_the_frames_the_gate_allows() {
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Team, Some(1));
        let seen = Arc::new(Mutex::new(Vec::new()));
        let tap = Arc::clone(&seen);
        rx.set_frame_sink(Arc::new(move |frame: Arc<protocol::Frame>| {
            tap.lock().unwrap().push(frame.sender_id);
        }));
        feed_frame(&rx, 1, 1, [192, 168, 1, 10]);
        feed_frame(&rx, 2, 2, [192, 168, 1, 20]);
        assert_eq!(*seen.lock().unwrap(), vec![1]);
    }
    #[test]
    fn discovery_can_be_opened_without_opening_the_video_gate() {
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Team, Some(1));
        // 设置界面没开：别人的 Hello 不记。
        feed_hello(&rx, 2, [192, 168, 1, 20]);
        assert!(
            rx.discovery().cameras().is_empty(),
            "locked down: other boards are not even recorded"
        );
        // 设置界面解锁后列出候选。
        rx.set_discovery_all(true);
        feed_hello(&rx, 2, [192, 168, 1, 20]);
        let ids: Vec<u32> = rx.discovery().cameras().iter().map(|c| c.id).collect();
        assert_eq!(ids, vec![2], "the candidate list is what the dropdown needs");
        // 但画面仍然进不来。这正是把闸门分成两道的目的。
        feed_frame(&rx, 2, 5, [192, 168, 1, 20]);
        assert!(rx.latest_frames().latest(2).is_none());
    }
    #[test]
    fn rebinding_moves_the_gate() {
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Team, Some(1));
        feed_frame(&rx, 1, 1, [192, 168, 1, 10]);
        rx.restrict_to(Some(2));
        feed_frame(&rx, 1, 2, [192, 168, 1, 10]);
        feed_frame(&rx, 2, 3, [192, 168, 1, 20]);
        assert_eq!(rx.sender_limit(), Some(2));
        assert!(
            rx.latest_frames().latest(1).is_some(),
            "the old frame stays cached; nothing pretends it never arrived"
        );
        assert!(rx.latest_frames().latest(2).is_some());
    }
    #[test]
    fn an_unrestricted_receiver_takes_everything() {
        // 裁判端的形态。
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Referee, None);
        feed_hello(&rx, 1, [192, 168, 1, 10]);
        feed_hello(&rx, 2, [192, 168, 1, 20]);
        feed_frame(&rx, 1, 1, [192, 168, 1, 10]);
        feed_frame(&rx, 2, 1, [192, 168, 1, 20]);
        assert_eq!(rx.discovery().cameras().len(), 2);
        assert_eq!(rx.latest_frames().latest_all().len(), 2);
    }
    #[test]
    fn a_streaming_board_counts_as_online_without_a_hello() {
        // 曾经出现过"画面在刷新、状态栏却显示离线"的状态：is_online 只看 Hello。
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Referee, None);
        feed_hello(&rx, 1, [192, 168, 1, 10]);
        // 让发现列表先知道它，再把它的 last_seen 交给 touch。
        feed_frame(&rx, 1, 1, [192, 168, 1, 10]);
        let camera = rx.discovery().cameras().pop().expect("known");
        assert_eq!(camera.id, 1);
        assert!(camera.is_online());
    }
    #[test]
    fn the_same_frame_id_from_two_boards_does_not_collide() {
        // 两块板的 frame_id 各自从 0 开始，混用一个重组器会互相顶掉。
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Referee, None);
        feed_frame(&rx, 1, 3, [192, 168, 1, 10]);
        feed_frame(&rx, 2, 3, [192, 168, 1, 20]);
        assert_eq!(rx.latest_frames().latest(1).map(|f| f.frame_id), Some(3));
        assert_eq!(rx.latest_frames().latest(2).map(|f| f.frame_id), Some(3));
    }
    #[test]
    fn a_truncated_datagram_is_ignored_instead_of_panicking() {
        let rx = Receiver::new(Ipv4Addr::UNSPECIFIED, SubscribeRole::Referee, None);
        rx.datagram(&[0u8; 3], from([192, 168, 1, 10]));
        rx.datagram(&[], from([192, 168, 1, 10]));
        assert!(rx.discovery().cameras().is_empty());
    }
 }
@@ -0,0 +1,188 @@
 //! 裁判端两个槽位对应哪两块摄像头。
 //!
 //! # 规则
 //!
 //! 1. **还在线的槽位不换人。** 板子短暂掉线又回来时，画面留在原位。
 //! 2. **没人用的板子才拿来填。** 候选里排除已经被另一个槽位占着的 id——这一条是
 //!    修一个真 bug：以前的实现只排除"这个槽位自己原来那个 id"，于是队伍一那块板子
 //!    一离线，它的槽位就会去拿队伍二那块，**两格显示同一块板子**，看起来像图传串了。
 //! 3. **掉线的槽位保留它的 id。** 显示"离线"而不是变回空槽，这样它回来时还在原位，
 //!    也不会把画面顺序重排。
 //! 4. **没有候选就不动。** 只有一块板在场时，另一个槽位空着——空着比显示一份复制品
 //!    诚实。
 //!
 //! # 为什么值得单独一个模块加测试
 //!
 //! 这个逻辑出错的**表现**是"两路画面看起来串了"。现场的排查方向会是网线、AP、
 //! 板子，而不是二十行分配代码。旧客户端在 README 里为它写了整整一节，但仍然漏掉了
 //! 规则 2。所以现在它有了直接对着场景写的测试。
 /// 两个槽位。索引 0 是左（队伍一），1 是右（队伍二）。
 #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
 pub struct SlotAllocator {
    slots: [Option<u32>; 2],
 }
 impl SlotAllocator {
    pub fn new() -> Self {
        Self::default()
    }
    /// 当前分配。
    pub fn slots(&self) -> [Option<u32>; 2] {
        self.slots
    }
    pub fn slot(&self, index: usize) -> Option<u32> {
        self.slots.get(index).copied().flatten()
    }
    /// 手动指定一个槽位（裁判端的"允许手动覆盖"）。
    pub fn force(&mut self, index: usize, id: Option<u32>) {
        if let Some(slot) = self.slots.get_mut(index) {
            *slot = id;
        }
    }
    /// 按当前在线的摄像头更新分配，返回是否发生了变化。
    ///
    /// `online` 必须按 id 排序，调用方用 [`crate::receiver::Discovery::online_cameras`]
    /// 得到的就是排好序的——顺序稳定，分配才不会每轮抖动。
    pub fn assign(&mut self, online: &[u32]) -> bool {
        let before = self.slots;
        for index in 0..self.slots.len() {
            // 规则 1：还在场就不动。
            if self.slots[index].is_some_and(|id| online.contains(&id)) {
                continue;
            }
            // 规则 2：另一个槽位占着的 id 不能拿。
            let taken: Vec<u32> = (0..self.slots.len())
                .filter(|other| *other != index)
                .filter_map(|other| self.slots[other])
                .collect();
            let candidate = online
                .iter()
                .copied()
                .find(|id| !taken.contains(id) && self.slots[index] != Some(*id));
            // 规则 4：没有候选就保留原样（规则 3：掉线的 id 留着）。
            if let Some(id) = candidate {
                self.slots[index] = Some(id);
            }
        }
        self.slots != before
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn two_boards_fill_both_slots_left_to_right() {
        let mut slots = SlotAllocator::new();
        assert!(slots.assign(&[0xAAAA, 0xBBBB]));
        assert_eq!(slots.slots(), [Some(0xAAAA), Some(0xBBBB)]);
        assert!(!slots.assign(&[0xAAAA, 0xBBBB]), "nothing changed");
    }
    #[test]
    fn one_board_never_fills_both_slots() {
        // 旧实现会在两块都空时每轮取前两个，只有一块板在场时两格显示同一块画面。
        // 裁判看到两边一模一样，会以为两队的图传串了。
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA]);
        assert_eq!(slots.slots(), [Some(0xAAAA), None]);
    }
    #[test]
    fn an_online_slot_keeps_its_board_when_the_other_goes_offline() {
        // 这是本项目里真实出现过的 bug：队伍一的板子一离线，它的槽位去拿了队伍二
        // 那块，于是两格都显示队伍二——而 B 的槽位本身没动。
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA, 0xBBBB]);
        slots.assign(&[0xBBBB]);
        assert_eq!(
            slots.slots(),
            [Some(0xAAAA), Some(0xBBBB)],
            "A 掉线的槽位保留它的 id（显示离线），B 原地不动，绝不能出现两块 B"
        );
    }
    #[test]
    fn a_returning_board_lands_back_in_its_own_slot() {
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA, 0xBBBB]);
        slots.assign(&[0xBBBB]);
        slots.assign(&[0xAAAA, 0xBBBB]);
        assert_eq!(slots.slots(), [Some(0xAAAA), Some(0xBBBB)]);
    }
    #[test]
    fn a_spare_board_does_not_land_twice() {
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA, 0xBBBB]);
        // 两块都掉线，然后来了一块新的 C：只填一个槽位。
        slots.assign(&[0xCCCC]);
        assert_eq!(slots.slots(), [Some(0xCCCC), Some(0xBBBB)]);
        // C 填了左边，右边仍是掉线的 B；再来一块 D 才填右边。
        slots.assign(&[0xCCCC, 0xDDDD]);
        assert_eq!(slots.slots(), [Some(0xCCCC), Some(0xDDDD)]);
    }
    #[test]
    fn a_board_coming_back_does_not_thrash_the_slot_it_left() {
        // "板子短暂掉线又回来，槽位原地打转"：掉线的槽位不该立刻把自己换掉。
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA]);
        // A 掉线、B 上线：A 的槽位改拿 B。
        slots.assign(&[0xBBBB]);
        assert_eq!(slots.slots(), [Some(0xBBBB), None]);
        // A 回来，两块都在：B 已经在槽位里且在线，A 只能等另一个槽位——它空着，于是
        // A 落到右边。这是有意的：已经显示出来的画面不该因为一块板子回来就跳到别处。
        slots.assign(&[0xAAAA, 0xBBBB]);
        assert_eq!(slots.slots(), [Some(0xBBBB), Some(0xAAAA)]);
    }
    #[test]
    fn forcing_a_slot_overrides_the_automatic_choice() {
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA, 0xBBBB]);
        slots.force(0, Some(0xBBBB));
        slots.force(1, Some(0xAAAA));
        assert_eq!(slots.slots(), [Some(0xBBBB), Some(0xAAAA)]);
        // 手动模式下依然是手动值：assign 只对"不在线"的槽位动手。
        slots.assign(&[0xAAAA, 0xBBBB]);
        assert_eq!(slots.slots(), [Some(0xBBBB), Some(0xAAAA)]);
    }
    #[test]
    fn losing_everything_leaves_the_last_known_ids() {
        let mut slots = SlotAllocator::new();
        slots.assign(&[0xAAAA, 0xBBBB]);
        assert!(!slots.assign(&[]), "nothing to reassign");
        assert_eq!(
            slots.slots(),
            [Some(0xAAAA), Some(0xBBBB)],
            "掉线的槽位保留 id，界面才能说清在等谁"
        );
    }
 }
@@ -0,0 +1,701 @@
 //! 推给界面的快照类型。
 //!
 //! # 为什么单独一个模块
 //!
 //! 这些结构体的字段名就是**界面看到的 JSON 字段名**，所以它们是接口的一部分，值得
 //! 集中放、集中改。放在这里而不是 Tauri 层，是因为其中几个的构造规则（比如"关掉
 //! 诊断时不留数字"）需要单元测试。
 //!
 //! # 为什么 id 同时给数字和文本
 //!
 //! 界面显示、日志、配置文件里用的都是 `0x3D4D8A9A` 这种十六进制形式。让 Rust 侧拼好
 //! (`id_text`) 而不是让前端各处自己 `toString(16)`，可以避免"某处少补了前导零"这种
 //! 只能靠肉眼比对才发现的不一致。
 use serde::Serialize;
 use crate::armor::ArmorBoard;
 use crate::config::{Config, CrosshairConfig, GridConfig, HealthConfig, HitFeedbackConfig, Role};
 use crate::receiver::{CameraInfo, SourceStats};
 /// 把 id 写成界面上、配置文件里、抓包时都一致的形式。
 pub fn id_text(id: u32) -> String {
    format!("0x{id:08X}")
 }
 /// 一块图传板。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CameraDto {
    pub id: u32,
    pub id_text: String,
    pub addr: String,
    pub online: bool,
    pub silence_ms: u64,
    pub firmware: u16,
 }
 impl From<&CameraInfo> for CameraDto {
    fn from(camera: &CameraInfo) -> Self {
        Self {
            id: camera.id,
            id_text: id_text(camera.id),
            addr: camera.addr.ip().to_string(),
            online: camera.is_online(),
            silence_ms: camera.silence().as_millis() as u64,
            firmware: camera.firmware,
        }
    }
 }
 /// 一块装甲板主板。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ArmorBoardDto {
    pub id: u32,
    pub id_text: String,
    pub addr: String,
    pub online: bool,
    /// 板子自报的队伍（编译期定的 `ARMOR_TEAM`）。
    pub team: u8,
    /// 最后一次读数。整车一条血，所以这里一个数。
    pub hp: u16,
    pub plates_seen: u8,
    pub reports_all_plates: bool,
    pub silence_ms: u64,
 }
 impl From<&ArmorBoard> for ArmorBoardDto {
    fn from(board: &ArmorBoard) -> Self {
        Self {
            id: board.id,
            id_text: id_text(board.id),
            addr: board.addr.ip().to_string(),
            online: board.is_online(),
            team: board.team,
            hp: board.hp,
            plates_seen: board.plates_seen.count_ones() as u8,
            reports_all_plates: board.reports_all_plates(),
            silence_ms: board.silence().as_millis() as u64,
        }
    }
 }
 /// 一路画面的读数。
 ///
 /// # 关掉诊断时这些数字**不存在**，而不是被界面藏起来
 ///
 /// 旧客户端在队伍端 release 下把这些字段填成空字符串。现在换成数字，规则不变：非诊断
 /// 模式下它们被置零/置空。由编译模式决定而不是命令行参数——命令行开关意味着二进制里
 /// 带着那套东西，忘开一次就泄露了。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct CameraStatsDto {
    pub camera: u32,
    pub camera_text: String,
    pub online: bool,
    /// 界面直接显示这一行，所以"在线但还没画面"与"离线"的区别由这里给出，而不是让
    /// 前端从 online + hasFrames 猜。
    pub status: String,
    pub has_frames: bool,
    pub fps: f32,
    pub width: u16,
    pub height: u16,
    pub frames_shown: u64,
    pub frames_dropped: u64,
    pub loss_percent: f32,
    pub datagrams: u64,
    pub last_frame_bytes: usize,
    pub gap_ms: Option<f32>,
 }
 impl CameraStatsDto {
    /// `diagnostics` 为 false 时不产出技术数字（见类型文档）。
    pub fn build(
        diagnostics: bool,
        camera: u32,
        online: bool,
        stats: &SourceStats,
        fps: f32,
    ) -> Self {
        let has_frames = stats.frames_shown > 0;
        // 从没出过画面时区分"在线但还没收到"和"离线"：前者只是刚连上，显示"等待画面"
        // 比让人以为板子挂了诚实。
        //
        // 有画面时显示 id —— 这对调试有用。队伍端 release 下这一路只有自己绑定的板子，
        // 显示它不构成泄露（界面上根本没有别人的板子可选）。
        let status = if !has_frames {
            if online {
                "已连接，等待画面…".to_string()
            } else {
                "离线".to_string()
            }
        } else {
            id_text(camera)
        };
        if !diagnostics {
            return Self {
                camera,
                camera_text: id_text(camera),
                online,
                status,
                has_frames,
                fps: 0.0,
                width: 0,
                height: 0,
                frames_shown: 0,
                frames_dropped: 0,
                loss_percent: 0.0,
                datagrams: 0,
                last_frame_bytes: 0,
                gap_ms: None,
            };
        }
        // 没出过一个字节的源，`stats.width`/`height` 还是默认值 0，于是界面会显示成
        // "0x0"——一个看起来像分辨率的假分辨率。用 has_frames 把它挡掉。
        Self {
            camera,
            camera_text: id_text(camera),
            online,
            status,
            has_frames,
            fps: if has_frames { fps } else { 0.0 },
            width: if has_frames { stats.width } else { 0 },
            height: if has_frames { stats.height } else { 0 },
            frames_shown: stats.frames_shown,
            frames_dropped: stats.frames_dropped,
            loss_percent: stats.loss_percent(),
            datagrams: stats.datagrams,
            last_frame_bytes: stats.last_frame_len,
            gap_ms: stats.gap_ms(),
        }
    }
 }
 /// 一边的血量。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct TeamHealthDto {
    pub team: u8,
    pub name: String,
    /// 有没有可信的数据。false 时界面显示 `placeholder` 而不是 0——0 是一个看起来像
    /// 真值的假值，现场看到 0 会以为对方已经没血了。
    pub available: bool,
    pub placeholder: String,
    /// 整车血量（四条装甲板同值，所以取第一条）。
    pub hp: Option<u16>,
    /// 四条装甲板各自的读数；`available` 为 true 时有效。
    pub hps: Vec<u16>,
    /// 绑定的装甲板主板 id（用户端）/ 分配到的（裁判端）。
    pub board: Option<u32>,
    pub board_text: Option<String>,
    /// 血量偏低或已归零。
    pub critical: bool,
    /// 这一边的胜负结论，由 [`resolve_outcomes`] 从**双方**的血量算出来。
    ///
    /// 放在每一边的 DTO 上而不是单独一个全局字段：界面上一格画面就是一边，一个格子里
    /// 要放的就是"从我这边看，现在是什么结果"。裁判端两格因此各看各的那份。
    pub outcome: Option<MatchOutcome>,
 }
 /// 一边看到的比赛结果。
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
 #[serde(rename_all = "lowercase")]
 pub enum MatchOutcome {
    /// 对手归零，自己还活着。
    Victory,
    /// 自己归零，对手还活着。
    Defeat,
    /// 两边同时归零。不写成"平局"以外的任何一个字：同时打空时两边都看到"胜利"才是错的。
    Draw,
 }
 impl TeamHealthDto {
    /// 还没有数据源。
    pub fn absent(team: u8, board: Option<u32>, names: &[String; 2]) -> Self {
        Self {
            team,
            name: team_name(team, names),
            available: false,
            placeholder: format!(
                "装甲板未接入：等主板在 UDP {} 上广播血量",
                protocol::ARMOR_PORT
            ),
            hp: None,
            // 依然给出 4 个格子：界面用 `available` 决定颜色，空数组会让占位框整个消失，
            // 看起来像布局出错，而不是像"还没有数据"。
            hps: vec![0; crate::receiver::ARMOR_BOARDS],
            board,
            board_text: board.map(id_text),
            critical: false,
            outcome: None,
        }
    }
    /// 有数据。
    pub fn present(
        team: u8,
        board: Option<u32>,
        hps: [u16; crate::receiver::ARMOR_BOARDS],
        low: u16,
        names: &[String; 2],
    ) -> Self {
        let hp = hps.first().copied().unwrap_or(0);
        Self {
            team,
            name: team_name(team, names),
            available: true,
            placeholder: String::new(),
            hp: Some(hp),
            hps: hps.to_vec(),
            board,
            board_text: board.map(id_text),
            critical: hp == 0 || hp <= low,
            outcome: None,
        }
    }
 }
 /// 把双方的血量合起来算成各自看到的胜负结论，写回 `outcome`。
 ///
 /// # 规则是有意不对称的
 ///
 /// - **输只需要看自己**：自己归零就是输，哪怕对手那块板子的数据没收到。这一条要成立，
 ///   否则"我被打死了但对手的主板掉线"会显示成什么都没发生。
 /// - **赢要看两边**：必须看到对手归零**且**自己还有血。少了后一半，一块从没上报过血量的
 ///   自己方主板会让人"凭空胜利"。
 /// - 两边同时归零是平局：那种情况下任何一边显示"胜利"都是错的。
 ///
 /// 变量不足（对不上的队伍、只有一份 DTO）时什么都不写。
 pub fn resolve_outcomes(health: &mut [TeamHealthDto]) {
    if health.len() != 2 {
        return;
    }
    let dead = |index: usize| health[index].available && health[index].hp == Some(0);
    let alive = |index: usize| matches!(health[index].hp, Some(hp) if hp > 0) && health[index].available;
    let (a_dead, b_dead) = (dead(0), dead(1));
    let (a_alive, b_alive) = (alive(0), alive(1));
    health[0].outcome = if a_dead && b_dead {
        Some(MatchOutcome::Draw)
    } else if b_dead && a_alive {
        Some(MatchOutcome::Victory)
    } else if a_dead {
        Some(MatchOutcome::Defeat)
    } else {
        None
    };
    health[1].outcome = if a_dead && b_dead {
        Some(MatchOutcome::Draw)
    } else if a_dead && b_alive {
        Some(MatchOutcome::Victory)
    } else if b_dead {
        Some(MatchOutcome::Defeat)
    } else {
        None
    };
 }
 /// 队伍名的兜底值（与 `Config::default().team_names` 一致）。
 pub fn default_team_name(team: u8) -> String {
    crate::config::DEFAULT_TEAM_NAMES[usize::from(team.min(1))].to_string()
 }
 /// 这一边在界面上叫什么。
 ///
 /// 配置里的名字是裁判端可以改的，所以名字必须**从这里来**，不能让界面各处自己拼
 /// "队伍一"/"队伍二"——那种拼法会在改了名字之后留下一半旧名字。
 pub fn team_name(team: u8, names: &[String; 2]) -> String {
    let name = names[usize::from(team.min(1))].trim();
    if name.is_empty() {
        default_team_name(team)
    } else {
        name.to_string()
    }
 }
 /// 一次掉血（由 [`crate::armor::HealthTracker`] 派生）。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct HitDto {
    pub board: u32,
    pub team: u8,
    pub index: u8,
    pub from: u16,
    pub to: u16,
    pub damage: u16,
    /// Unix 毫秒。前端用它驱动闪红的动画，不需要自己计时。
    pub at_ms: u64,
 }
 /// 录制状态。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct RecordingDto {
    pub camera: u32,
    pub camera_text: String,
    pub active: bool,
    pub path: Option<String>,
    /// 告诉 ffmpeg 的输入帧率。回放快放/慢放时，第一个要看的就是这个数。
    pub input_fps: f32,
    pub frames_written: u64,
    /// 因为写入端跟不上而丢掉的帧。丢帧不报出来的话，回放里"少了半秒"会看起来像
    /// 相机的问题。
    pub frames_dropped: u64,
    pub started_ms: Option<u64>,
    pub error: Option<String>,
 }
 /// 裁判端两个槽位。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct SlotsDto {
    /// 左槽位 → 摄像头 id。
    pub camera_a: Option<u32>,
    pub camera_b: Option<u32>,
    /// 左槽位 → 装甲板主板 id。
    pub armor_a: Option<u32>,
    pub armor_b: Option<u32>,
    pub manual: bool,
 }
 /// 推给界面的完整状态。
 ///
 /// 一次性给全，而不是让界面按需多次查询：5 Hz 下这条消息只有几百字节，而"界面各处
 /// 分别拉数据"会引入一类难查的问题——两个面板显示的是不同时刻的状态（比如绑定改了
 /// 一半）。前端因此只需要一个 reducer。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Snapshot {
    pub role: Role,
    pub team: u8,
    pub mirrored: bool,
    /// 演示模式：画面与血量是本地合成的，不是场上的板子。界面必须把它显示出来，
    /// 否则截图与验收会被误读成真实链路。
    pub demo: bool,
    /// 是否产出技术读数（帧率/丢帧）。用户端 release 下为 false。
    pub diagnostics: bool,
    /// 密码闸门是否已经打开（会话内）。
    pub unlocked: bool,
    /// 发现列表是否放开（设置面板打开时）。开着才可能列出别人的板子。
    pub discovery_open: bool,
    pub uptime_ms: u64,
    /// 连着这个后端的界面数。
    pub clients: usize,
    pub config: ConfigView,
    pub cameras: Vec<CameraDto>,
    pub armor_boards: Vec<ArmorBoardDto>,
    /// 每块已知摄像头的读数。
    pub stats: Vec<CameraStatsDto>,
    /// 裁判端两个槽位。用户端的 `a` 就是它绑定的那一块。
    pub slots: SlotsDto,
    /// **两端都是两条，顺序是队伍号 0、1**：用户端也要显示对手的血量（画面右上角）。
    ///
    /// 界面按 `team` 取自己那一格，不靠数组下标——用户端绑的是队伍二时 `health[0]` 是别人。
    pub health: Vec<TeamHealthDto>,
    pub recordings: Vec<RecordingDto>,
    /// 启动时的说明（旧配置迁移、端口占用等）。
    pub notes: Vec<String>,
 }
 /// 配置里可以给界面看的那部分。
 ///
 /// **不含密码哈希**：界面只需要知道"设过没有"，把 PHC 字符串送进 WebView 没有任何用处，
 /// 只是多一个能被日志、崩溃报告带走的东西。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ConfigView {
    pub role: Role,
    /// 身份是否已由人选过。false 时界面先问一次（见 `Config::role_chosen`）。
    pub role_chosen: bool,
    pub team: u8,
    /// 两边在界面上显示的名字（裁判端可以改）。界面各处显示队伍名都要用它，
    /// 包括血条之外的地方（装甲板表、等待画面的占位文字）。
    pub team_names: [String; 2],
    pub camera_id: Option<u32>,
    pub camera_id_text: Option<String>,
    pub armor_id: Option<u32>,
    pub armor_id_text: Option<String>,
    pub mirror: bool,
    pub password_set: bool,
    pub hud: HudView,
    pub recording_dir: String,
    pub ffmpeg: String,
 }
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct HudView {
    pub health: HealthConfig,
    pub crosshair: CrosshairConfig,
    pub grid: GridConfig,
    pub hit_feedback: HitFeedbackConfig,
    pub show_zoom: bool,
    pub show_stats: bool,
 }
 impl From<&Config> for ConfigView {
    fn from(config: &Config) -> Self {
        Self {
            role: config.role,
            role_chosen: config.role_chosen,
            team: config.team,
            team_names: config.team_names.clone(),
            camera_id: config.camera_id,
            camera_id_text: config.camera_id.map(id_text),
            armor_id: config.armor_id,
            armor_id_text: config.armor_id.map(id_text),
            mirror: config.mirror,
            password_set: config.password.is_some(),
            hud: HudView {
                health: config.hud.health.clone(),
                crosshair: config.hud.crosshair.clone(),
                grid: config.hud.grid.clone(),
                hit_feedback: config.hud.hit_feedback.clone(),
                show_zoom: config.hud.show_zoom,
                show_stats: config.hud.show_stats,
            },
            recording_dir: config.recordings_dir().display().to_string(),
            ffmpeg: config.recording.ffmpeg.clone(),
        }
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use crate::receiver::SourceStats;
    fn stats() -> SourceStats {
        let mut stats = SourceStats::default();
        // 直接构造：SourceStats 的字段是 pub 的，只有 last_shown_at 是私有的。
        stats.frames_shown = 440;
        stats.frames_dropped = 10;
        stats.datagrams = 8000;
        stats.width = 640;
        stats.height = 480;
        stats.last_frame_len = 22_000;
        stats
    }
    #[test]
    fn diagnostics_off_leaves_no_numbers_behind() {
        // 不是"界面藏起来"，是**不存在**。
        let dto = CameraStatsDto::build(false, 0x3D4D_8A9A, true, &stats(), 22.0);
        assert_eq!(dto.frames_shown, 0);
        assert_eq!(dto.frames_dropped, 0);
        assert_eq!(dto.datagrams, 0);
        assert_eq!(dto.fps, 0.0);
        assert_eq!(dto.width, 0);
        assert_eq!(dto.gap_ms, None);
        assert_eq!(dto.last_frame_bytes, 0);
        // 但界面仍然需要知道画面来没来。
        assert!(dto.has_frames);
        assert!(dto.online);
    }
    #[test]
    fn diagnostics_on_reports_the_real_numbers() {
        let dto = CameraStatsDto::build(true, 0x3D4D_8A9A, true, &stats(), 22.0);
        assert_eq!(dto.frames_shown, 440);
        assert_eq!(dto.frames_dropped, 10);
        assert!((dto.loss_percent - 2.2222).abs() < 0.01);
        assert_eq!((dto.width, dto.height), (640, 480));
        assert_eq!(dto.fps, 22.0);
        assert_eq!(dto.status, "0x3D4D8A9A");
    }
    #[test]
    fn a_never_seen_camera_does_not_report_a_fake_resolution() {
        let dto = CameraStatsDto::build(true, 1, true, &SourceStats::default(), 0.0);
        assert_eq!(dto.status, "已连接，等待画面…");
        assert_eq!((dto.width, dto.height), (0, 0));
        assert!(!dto.has_frames, "0x0 would read like a real resolution");
    }
    #[test]
    fn an_offline_camera_says_offline() {
        let dto = CameraStatsDto::build(true, 1, false, &SourceStats::default(), 0.0);
        assert_eq!(dto.status, "离线");
    }
    /// 默认队名，测试里到处用。
    fn names() -> [String; 2] {
        ["队伍一".to_string(), "队伍二".to_string()]
    }
    #[test]
    fn absent_health_is_a_placeholder_with_four_cells() {
        let dto = TeamHealthDto::absent(0, None, &names());
        assert!(!dto.available);
        assert_eq!(dto.hp, None);
        assert_eq!(dto.hps.len(), crate::receiver::ARMOR_BOARDS);
        assert!(!dto.placeholder.is_empty());
        assert_eq!(dto.outcome, None, "没有数据时不下结论");
    }
    #[test]
    fn critical_health_is_flagged_at_zero_and_at_the_threshold() {
        let low = TeamHealthDto::present(0, Some(1), [30, 30, 30, 30], 30, &names());
        assert!(low.critical, "at the threshold");
        let ok = TeamHealthDto::present(0, Some(1), [31, 31, 31, 31], 30, &names());
        assert!(!ok.critical);
        let dead = TeamHealthDto::present(0, Some(1), [0, 0, 0, 0], 30, &names());
        assert!(dead.critical);
        assert_eq!(dead.hp, Some(0));
    }
    #[test]
    fn the_team_name_comes_from_the_config_not_from_a_hard_coded_string() {
        let custom = ["红队".to_string(), "蓝队".to_string()];
        assert_eq!(TeamHealthDto::absent(1, None, &custom).name, "蓝队");
        assert_eq!(
            TeamHealthDto::present(0, Some(1), [50; 4], 30, &custom).name,
            "红队"
        );
        // 空名字回落默认值，而不是显示一个没有名字的血条。
        let blank = ["".to_string(), "   ".to_string()];
        assert_eq!(team_name(0, &blank), "队伍一");
        assert_eq!(team_name(1, &blank), "队伍二");
        assert_eq!(team_name(9, &blank), "队伍二", "越界的队伍号按第二队处理");
    }
    #[test]
    fn killing_the_opponent_reads_as_a_victory_for_the_other_side() {
        let mut health = vec![
            TeamHealthDto::present(0, Some(1), [100; 4], 30, &names()),
            TeamHealthDto::present(1, Some(2), [0; 4], 30, &names()),
        ];
        resolve_outcomes(&mut health);
        assert_eq!(health[0].outcome, Some(MatchOutcome::Victory));
        assert_eq!(health[1].outcome, Some(MatchOutcome::Defeat));
    }
    #[test]
    fn nothing_is_announced_while_both_sides_are_alive() {
        let mut health = vec![
            TeamHealthDto::present(0, Some(1), [100; 4], 30, &names()),
            TeamHealthDto::present(1, Some(2), [40; 4], 30, &names()),
        ];
        resolve_outcomes(&mut health);
        assert_eq!(health[0].outcome, None);
        assert_eq!(health[1].outcome, None);
    }
    #[test]
    fn both_sides_at_zero_is_a_draw_rather_than_two_victories() {
        let mut health = vec![
            TeamHealthDto::present(0, Some(1), [0; 4], 30, &names()),
            TeamHealthDto::present(1, Some(2), [0; 4], 30, &names()),
        ];
        resolve_outcomes(&mut health);
        assert_eq!(health[0].outcome, Some(MatchOutcome::Draw));
        assert_eq!(health[1].outcome, Some(MatchOutcome::Draw));
    }
    #[test]
    fn a_dead_team_loses_even_when_the_other_board_is_missing() {
        // 输只看自己：对手的主板掉线不该让"我被击毁"变成什么都没发生。
        let mut health = vec![
            TeamHealthDto::present(0, Some(1), [0; 4], 30, &names()),
            TeamHealthDto::absent(1, None, &names()),
        ];
        resolve_outcomes(&mut health);
        assert_eq!(health[0].outcome, Some(MatchOutcome::Defeat));
        assert_eq!(health[1].outcome, None, "没有自己数据的这边不下结论");
    }
    #[test]
    fn a_missing_own_board_does_not_produce_a_victory() {
        // 赢要看两边：只看到对手归零、不知道自己还有没有血时不能宣布胜利。
        let mut health = vec![
            TeamHealthDto::absent(0, None, &names()),
            TeamHealthDto::present(1, Some(2), [0; 4], 30, &names()),
        ];
        resolve_outcomes(&mut health);
        assert_eq!(health[0].outcome, None);
        assert_eq!(health[1].outcome, Some(MatchOutcome::Defeat));
    }
    #[test]
    fn the_snapshot_serialises_the_outcome_as_a_plain_word() {
        let mut health = vec![
            TeamHealthDto::present(0, Some(1), [0; 4], 30, &names()),
            TeamHealthDto::present(1, Some(2), [50; 4], 30, &names()),
        ];
        resolve_outcomes(&mut health);
        let json = serde_json::to_string(&health[0]).unwrap();
        assert!(json.contains(r#""outcome":"defeat""#), "got {json}");
        let json = serde_json::to_string(&health[1]).unwrap();
        assert!(json.contains(r#""outcome":"victory""#), "got {json}");
    }
    #[test]
    fn a_recording_reports_the_framerate_it_told_ffmpeg() {
        // 回放速度不对时，这是唯一能解释原因的数字。
        let dto = RecordingDto {
            camera: 1,
            camera_text: id_text(1),
            active: true,
            path: None,
            input_fps: 21.5,
            frames_written: 0,
            frames_dropped: 0,
            started_ms: None,
            error: None,
        };
        let json = serde_json::to_string(&dto).unwrap();
        assert!(json.contains(r#""inputFps":21.5"#), "got {json}");
    }
    #[test]
    fn the_config_view_never_carries_the_password_hash() {
        let mut config = Config::default();
        config.role = Role::Team;
        config.password = Some("$argon2id$super$secret$hash".into());
        let view = ConfigView::from(&config);
        assert!(view.password_set);
        let json = serde_json::to_string(&view).unwrap();
        assert!(
            !json.contains("argon2id"),
            "the hash must not reach the webview: {json}"
        );
    }
    #[test]
    fn ids_are_formatted_like_everywhere_else() {
        assert_eq!(id_text(0x3D4D_8A9A), "0x3D4D8A9A");
        assert_eq!(id_text(1), "0x00000001", "leading zeros matter for eyeballing");
    }
 }
@@ -0,0 +1,228 @@
 //! 帧率统计。
 //!
 //! # 必须按"帧数除以墙钟"，不是"帧间隔的平均"
 //!
 //! 这两种算法在理想链路上给出同一个数，所以错误的那一版能一路跑到现场才暴露。
 //!
 //! 界面每 33ms 轮询一次，而相机出帧间隔是 45ms。也就是说**一次轮询之间可能完成零帧
 //! 或多帧**。对帧间隔取平均，量到的是**显示**的刷新节奏而不是**相机**的出帧节奏——
 //! 于是上限 22fps 的传感器被报成 36fps。**一个笃定的错误数字比没有数字更糟**：现场
 //! 会以为还有性能余量，然后花时间去查一个不存在的问题。
 //!
 //! 这个错误在本项目里出现过两次（旧客户端的 `View::update_fps`、探测脚本的分窗打印），
 //! 两次都是同一个形状：分子用累计值，分母用窗口值，于是报出随时间单调上升的假数字。
 //! 现在它的正确性由一个直接对着数字写的测试盯着。
 //!
 //! # 时钟是可注入的
 //!
 //! [`FpsWindow::observe`] 收 `now` 而不是自己取 `Instant::now()`，这样测试可以用
 //! 明确的时刻验证窗口边界——否则只能 sleep，而 sleep 出来的测试既慢又不稳。
 use std::time::{Duration, Instant};
 /// 帧率统计窗口。默认 2 秒。
 pub const DEFAULT_WINDOW: Duration = Duration::from_secs(2);
 /// 某一路的帧率窗口。
 #[derive(Debug, Clone)]
 pub struct FpsWindow {
    window: Duration,
    started: Instant,
    /// 上一次结算时的累计帧数。
    frames: u64,
    /// 已经结算过几个窗口。
    ///
    /// 不能拿"累计帧数非零"来代替它：窗口的基线是**播种**进去的（见 [`FpsWindow::seeded`]），
    /// 一块掉线又回来的板子一建立窗口就带着一个很大的累计值。用帧数判断的话，会在一个
    /// 窗口都还没走完时就宣称"有读数了"，界面于是先显示 0.0，再跳到真值。
    completed: u32,
    fps: f32,
 }
 impl Default for FpsWindow {
    fn default() -> Self {
        Self::new(DEFAULT_WINDOW)
    }
 }
 impl FpsWindow {
    pub fn new(window: Duration) -> Self {
        Self::starting_at(window, Instant::now())
    }
    /// 窗口从指定的时刻开始，并把累计帧数的基线设成给定值。
    ///
    /// 基线不能总是 0：`frames_shown` 是**自进程启动以来**的累计值，而一块掉线又回来的
    /// 板子会带着一个已经涨了很大的数字回来。基线设错（比如设成 0）时，下一个窗口会
    /// 报出几百 fps 的假数字。
    pub fn seeded(window: Duration, started: Instant, frames_shown: u64) -> Self {
        Self {
            window,
            started,
            frames: frames_shown,
            completed: 0,
            fps: 0.0,
        }
    }
    /// 窗口从指定的时刻开始，基线为 0。测试用。
    pub fn starting_at(window: Duration, started: Instant) -> Self {
        Self::seeded(window, started, 0)
    }
    /// 最近一次结算出的帧率。窗口还没满时是 0。
    pub fn fps(&self) -> f32 {
        self.fps
    }
    /// 窗口是否已经结算过至少一次。
    ///
    /// 界面用它在"还没收到帧"和"帧率真的是 0"之间区分——前者显示 0.0 会被读成"板子
    /// 卡死了"。
    pub fn has_reading(&self) -> bool {
        self.completed > 0
    }
    /// 喂进当前的累计帧数，返回本窗口的帧率（窗口未满时返回 `None`）。
    ///
    /// `frames_shown` 是**自进程启动以来**的累计值，不是窗口内的增量——这正是重点：
    /// 窗口内的增量由这里相减得到，调用方不需要（也就不会弄错）维护它。
    pub fn observe(&mut self, frames_shown: u64, now: Instant) -> Option<f32> {
        let elapsed = now.saturating_duration_since(self.started);
        if elapsed < self.window {
            return None;
        }
        self.fps = (frames_shown.saturating_sub(self.frames)) as f32 / elapsed.as_secs_f32();
        self.frames = frames_shown;
        self.started = now;
        self.completed += 1;
        Some(self.fps)
    }
    /// 换了一路画面：窗口重开。
    ///
    /// 不重开的话，新画面的第一段统计里带着上一块板子的累计帧数，会报出一个凭空多出来
    /// 的数字。旧客户端对此的处理是"`view.sender_id` 变了就整体重建 `View`"，那条
    /// 规则现在收在这里。
    pub fn reset(&mut self, now: Instant) {
        self.started = now;
        self.frames = 0;
        self.completed = 0;
        self.fps = 0.0;
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn rate_is_frames_over_wallclock() {
        let t0 = Instant::now();
        let mut window = FpsWindow::starting_at(Duration::from_secs(2), t0);
        // 2 秒里到了 44 帧 = 22 fps。
        let fps = window
            .observe(44, t0 + Duration::from_secs(2))
            .expect("the window is full");
        assert!((fps - 22.0).abs() < 0.001, "got {fps}");
    }
    #[test]
    fn a_half_full_window_reports_nothing() {
        let t0 = Instant::now();
        let mut window = FpsWindow::starting_at(Duration::from_secs(2), t0);
        assert_eq!(window.observe(10, t0 + Duration::from_millis(1999)), None);
        assert_eq!(window.fps(), 0.0);
        assert!(!window.has_reading());
    }
    #[test]
    fn a_stalled_stream_reports_zero_not_a_stale_number() {
        let t0 = Instant::now();
        let mut window = FpsWindow::starting_at(Duration::from_secs(2), t0);
        window.observe(44, t0 + Duration::from_secs(2));
        // 板子不出帧了：累计值不变，下一个窗口必须报 0。
        let fps = window
            .observe(44, t0 + Duration::from_secs(4))
            .expect("second window");
        assert_eq!(fps, 0.0);
    }
    #[test]
    fn averaging_frame_gaps_is_the_wrong_answer() {
        // 这条测试把"错误算法会给出什么"钉下来，避免有人"顺手修一下"。
        //
        // 场景：界面每 33ms 轮询一次，相机 45ms 出一帧。一次轮询里轮空、下一次里
        // 完成一帧，还有一次轮询之间完成两帧。对帧间隔取平均会算成约 33ms 一帧
        // （30fps 上下），而墙钟给出的才是真实的 22fps。
        let t0 = Instant::now();
        let mut window = FpsWindow::starting_at(Duration::from_secs(2), t0);
        // 2 秒内累计 44 帧，但最后一次轮询与上一帧之间只隔了 33ms。
        let fps = window
            .observe(44, t0 + Duration::from_secs(2))
            .expect("window full");
        assert!((fps - 22.0).abs() < 0.001, "wallclock rate: {fps}");
        assert!(
            fps < 25.0,
            "a frame-gap average would have reported ~30fps here"
        );
    }
    #[test]
    fn a_completed_window_is_not_a_reading_yet_until_it_is_full() {
        // 建立窗口的那一轮不该产出数字：它连一个完整窗口都还没过。
        let t0 = Instant::now();
        let mut window = FpsWindow::seeded(Duration::from_secs(2), t0, 9_000);
        assert_eq!(window.observe(9_010, t0 + Duration::from_millis(10)), None);
        assert!(!window.has_reading());
        // 2 秒后：这 2 秒里到了 44 帧。
        let fps = window
            .observe(9_044, t0 + Duration::from_secs(2))
            .expect("window full");
        assert!((fps - 22.0).abs() < 0.001, "got {fps}");
    }
    #[test]
    fn resetting_clears_the_cumulative_count() {
        let t0 = Instant::now();
        let mut window = FpsWindow::starting_at(Duration::from_secs(2), t0);
        window.observe(1000, t0 + Duration::from_secs(2));
        // 换了一路画面：累计值从 0 重新开始。
        window.reset(t0 + Duration::from_secs(2));
        let fps = window
            .observe(44, t0 + Duration::from_secs(4))
            .expect("window full");
        assert!((fps - 22.0).abs() < 0.001, "got {fps}");
    }
    #[test]
    fn a_counter_that_goes_backwards_does_not_underflow() {
        // 累计值只应该单调增。真出现回退（换了板子但没 reset），宁可报 0 也不要用
        // u64 回绕算出一个天文数字。
        let t0 = Instant::now();
        let mut window = FpsWindow::starting_at(Duration::from_secs(2), t0);
        window.observe(500, t0 + Duration::from_secs(2));
        let fps = window
            .observe(10, t0 + Duration::from_secs(4))
            .expect("window full");
        assert_eq!(fps, 0.0);
    }
 }
@@ -0,0 +1,12 @@
 <!doctype html>
 <html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>cam-desktop</title>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
 </html>
@@ -0,0 +1,28 @@
 {
  "name": "cam-desktop",
  "private": true,
  "version": "0.1.0",
  "type": "module",
  "description": "ESP32 图传与装甲板系统的桌面端：用户端（血条 + 瞄准器）与裁判端（双路 + 装甲板 + 录制）",
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "preview": "vite preview",
    "tauri": "tauri",
    "app": "tauri dev",
    "check": "tsc --noEmit"
  },
  "dependencies": {
    "@tauri-apps/api": "^2",
    "react": "^19",
    "react-dom": "^19"
  },
  "devDependencies": {
    "@tauri-apps/cli": "^2",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "@vitejs/plugin-react": "^5",
    "typescript": "^5.9",
    "vite": "^7"
  }
 }
@@ -0,0 +1,8 @@
 # pnpm 11 不再读取 package.json 里的 `pnpm` 字段，设置搬到了这里。
 # 这个文件是 pnpm 自己在遇到被忽略的构建脚本时生成的。
 #
 # esbuild 的 postinstall 是它把自己平台的二进制接好的那一步。不允许它跑，`pnpm exec`
 # 每次都会以 ERR_PNPM_IGNORED_BUILDS 退出 1 —— 即使 vite 本身还能跑，这个非零退出码
 # 也会让 `tauri dev` 的 beforeDevCommand 失败。所以这里显式放行。
 allowBuilds:
  esbuild: true
@@ -0,0 +1,8 @@
 # 这个目录里的一切都用宿主机的稳定版工具链构建。
 #
 # 仓库根目录的 rust-toolchain.toml 钉的是 `esp`（带 Xtensa 支持的定制工具链），
 # 那是给图传板与装甲板固件用的。桌面端不需要它，而且 Tauri 依赖里的若干 crate
 # 要求较新的稳定版。rustup 取**最近的**那一个 rust-toolchain.toml，所以这个文件
 # 就是 desktop/ 下面所有 cargo 调用的实际选择。
 [toolchain]
 channel = "stable"
@@ -0,0 +1,57 @@
 [package]
 name = "cam-desktop"
 version = "0.1.0"
 edition = "2021"
 description = "ESP32 图传与装甲板系统的桌面端"
 rust-version = "1.77"
 [build-dependencies]
 tauri-build = { version = "2", features = [] }
 [dependencies]
 # `protocol-asset` 打开自定义资源协议，录制出来的 mp4 才能在界面里直接回放
 # （前端用 convertFileSrc 把它变成一个 <video> 能播的 URL）。
 tauri = { version = "2", features = ["protocol-asset"] }
 # 只用来"在访达里显示"与"用系统播放器打开"。所有调用都走我们自己的 Rust 命令，
 # 所以前端不需要装 @tauri-apps/plugin-opener，也不需要给它开权限。
 tauri-plugin-opener = "2"
 # 非界面部分：UDP 接收/重组、装甲板、配置、密码、槽位分配。它自己带 64 个测试。
 cam-core = { path = "../core" }
 # 线路格式与固件共享。
 protocol = { path = "../../protocol" }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 log = "0.4"
 env_logger = "0.11"
 anyhow = "1"
 # 回环通道的随机 token。
 rand = "0.9"
 # 本地 WebSocket 视频通道。用 tokio-tungstenite 而不是 Tauri 的自定义协议：
 # 二进制消息不经 JSON/IPC 序列化，前端拿到的就是原始 JPEG 字节，可以直接交给
 # 浏览器的原生 JPEG 解码器（createImageBitmap）。
 tokio = { version = "1", features = [
    "rt-multi-thread",
    "net",
    "sync",
    "io-util",
    "macros",
    "time",
 ] }
 tokio-tungstenite = "0.30"
 futures-util = "0.3"
 # 截图要 PNG（相机出的 JPEG 不带 alpha、也可能被播放器当照片处理），所以要解码再编码。
 # demo 模式也用它合成假画面。
 image = { version = "0.25", default-features = false, features = ["jpeg", "png"] }
 # 文件名里的时间戳：现场看目录时要能一眼看出是哪一局录的。
 chrono = "0.4"
 [profile.release]
 opt-level = 2
@@ -0,0 +1,8 @@
 //! Tauri 的构建脚本。
 //!
 //! 它做两件事：把 `tauri.conf.json` 读进来生成上下文，以及（在 Windows 上）挂上清单。
 //! 桌面端不需要自定义资源编译，所以这里没有 `tauri_build::Attributes`。
 fn main() {
    tauri_build::build()
 }
@@ -0,0 +1,7 @@
 {
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "窗口与事件这些核心能力。业务命令（绑定、解锁、截图、录制）都是本应用自己的 #[tauri::command]，不在权限系统里，所以这里没有它们的条目。",
  "windows": ["main"],
  "permissions": ["core:default"]
 }
@@ -0,0 +1,551 @@
 //! 界面能调用的命令。
 //!
 //! # 每个会改东西的命令都过密码闸门
 //!
 //! 界面里有一个解锁对话框，但那只是入口：这些函数才是执行点。所以每个改变配置的命令
 //! 都显式调用 [`AppState::require_unlocked`]，而 `presented` 允许在同一次调用里带上
 //! 密码（前端在解锁后立刻改绑定时就是这样）。
 //!
 //! # 为什么错误是 `String`
 //!
 //! Tauri 把 `Err` 序列化给前端，而 `anyhow::Error` 不实现 `Serialize`。这些错误是给
 //! **现场的人**看的（"密码不对"、"还没有收到这一路的画面"），本来就该是给人读的句子，
 //! 所以直接传字符串，同时用 `log::warn!` 留下带上下文的版本。
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 use tauri::{AppHandle, State};
 use cam_core::config::Role;
 use cam_core::snapshot::{ConfigView, Snapshot};
 use cam_core::HudConfig;
 use crate::recording::{list_media, MediaFileDto};
 use crate::server::StreamInfo;
 use crate::state::AppState;
 /// 还没有测到帧率时，告诉 ffmpeg 的默认输入帧率。
 ///
 /// 传感器在这个配置下实测 22 fps，但写死 22 是在撒谎——真正的问题不是"猜得准不准"，
 /// 而是这个数会决定回放速度，所以它一律写进日志与 [`cam_core::snapshot::RecordingDto`]。
 const FALLBACK_INPUT_FPS: f32 = 20.0;
 type Shared<'a> = State<'a, Arc<AppState>>;
 // ---------------------------------------------------------------------------
 // 只读
 // ---------------------------------------------------------------------------
 /// 视频通道的地址与 token。前端启动时拉一次。
 #[tauri::command]
 pub fn stream_info(state: Shared<'_>) -> StreamInfo {
    state.stream_info()
 }
 /// 当前完整状态。
 #[tauri::command]
 pub fn get_snapshot(state: Shared<'_>) -> Snapshot {
    state.snapshot()
 }
 /// 配置里可以给界面看的那部分（不含密码哈希）。用户端第一次启动用它判断"要不要设密码"。
 #[tauri::command]
 pub fn get_config(state: Shared<'_>) -> ConfigView {
    ConfigView::from(&state.config())
 }
 /// 录制目录里的 mp4 与 png，新的在前。
 #[tauri::command]
 pub fn list_media_files(state: Shared<'_>) -> Vec<MediaFileDto> {
    list_media(&state.config().recordings_dir())
 }
 /// 配置文件的路径。现场排查时要能告诉人"去看这个文件"。
 #[tauri::command]
 pub fn config_path(state: Shared<'_>) -> String {
    state.config_path.display().to_string()
 }
 // ---------------------------------------------------------------------------
 // 密码
 // ---------------------------------------------------------------------------
 /// 校验密码并把本次运行标记为已解锁。
 #[tauri::command]
 pub fn unlock(password: String, state: Shared<'_>) -> Result<bool, String> {
    state
        .unlock(&password)
        .map_err(|err| format!("存下来的密码哈希读不出来：{err}"))
 }
 /// 手动重新上锁（并顺手把发现列表关掉）。
 #[tauri::command]
 pub fn lock(state: Shared<'_>) {
    state.lock();
 }
 /// 首次设置密码，或修改密码。
 #[tauri::command]
 pub fn set_password(
    current: Option<String>,
    fresh: String,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state
        .set_password(current.as_deref(), &fresh)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 设置面板打开/关闭带来的发现列表。打开需要已解锁。
 #[tauri::command]
 pub fn set_discovery_open(open: bool, state: Shared<'_>) -> Result<(), String> {
    state.set_discovery_open(open)
 }
 // ---------------------------------------------------------------------------
 // 绑定与身份
 // ---------------------------------------------------------------------------
 /// 绑定（或解除绑定）一块图传板。
 #[tauri::command]
 pub fn bind_camera(
    camera_id: Option<u32>,
    password: Option<String>,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state.require_unlocked(password.as_deref())?;
    state
        .update_config(move |config| config.camera_id = camera_id)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 绑定（或解除绑定）一块装甲板主板。
 #[tauri::command]
 pub fn bind_armor(
    armor_id: Option<u32>,
    password: Option<String>,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state.require_unlocked(password.as_deref())?;
    state
        .update_config(move |config| config.armor_id = armor_id)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 自己属于哪一边（0/1）。改错队号会把对手的血条放在左上角（当成自己的），所以也要密码。
 #[tauri::command]
 pub fn set_team(
    team: u8,
    password: Option<String>,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state.require_unlocked(password.as_deref())?;
    if team > 1 {
        return Err("队伍号只能是 0（队伍一）或 1（队伍二）".into());
    }
    state
        .update_config(move |config| config.team = team)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 切换身份。
 ///
 /// **离开用户端要密码**：否则解锁界面就形同虚设——切到裁判端就能看两路画面、还能随便
 /// 改配置。反过来（裁判端 → 用户端）不需要：裁判端本来就没有密码。
 #[tauri::command]
 pub fn set_role(
    role: Role,
    password: Option<String>,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    let current = state.config().role;
    if current.needs_password() && current != role {
        state.require_unlocked(password.as_deref())?;
    }
    state
        .update_config(move |config| {
            config.role = role;
            // 记下"人选过了"：下次启动直接进这个身份，不再问。
            config.role_chosen = true;
        })
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 左右镜像。摄像头装反了才需要，不是判罚相关的东西，所以不设密码。
 #[tauri::command]
 pub fn set_mirror(mirror: bool, state: Shared<'_>) -> Result<ConfigView, String> {
    state
        .update_config(move |config| config.mirror = mirror)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 保存 HUD 设置（血条、瞄准器、网格、命中反馈）。
 #[tauri::command]
 pub fn save_hud(hud: HudConfig, state: Shared<'_>) -> Result<ConfigView, String> {
    state
        .update_config(move |config| config.hud = hud)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 裁判端两个槽位的手动指定。
 #[tauri::command]
 #[allow(clippy::too_many_arguments)]
 pub fn set_referee_slots(
    camera_a: Option<u32>,
    camera_b: Option<u32>,
    armor_a: Option<u32>,
    armor_b: Option<u32>,
    manual: bool,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state
        .update_config(move |config| {
            config.referee.slot_a = camera_a;
            config.referee.slot_b = camera_b;
            config.referee.armor_a = armor_a;
            config.referee.armor_b = armor_b;
            config.referee.manual_slots = manual;
        })
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 改一边在界面上显示的名字（0 = 队伍一，1 = 队伍二）。
 ///
 /// # 为什么一次只改一边
 ///
 /// 界面本来可以传一整个 `[String; 2]`，但那意味着每次改名都是"读两条、改一条、写两条"，
 /// 而读来的那两条来自最多 200 ms 前的快照：紧接着改另一边就会把上一次的改动覆盖回去。
 /// 一次只改一边，这个窗口不存在。
 ///
 /// # 为什么这个命令也过密码闸门
 ///
 /// 名字本身不是判罚数据，但它写在**配置文件**里。给一个不设闸门的"改配置"入口，等于在
 /// 密码闸门上开一条旁路——今天改的是名字，明天有人顺手把绑定也挪进来。裁判端本来就没有
 /// 密码（`Role::needs_password` 为假），所以对裁判端这个闸门是空的，界面上的入口也在裁判端。
 ///
 /// 规范化（去空白、截断、留空回落默认名）由 [`cam_core::config::Config::normalized`] 统一
 /// 做，这里只管队伍号合不合法。
 #[tauri::command]
 pub fn set_team_name(
    team: u8,
    name: String,
    password: Option<String>,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state.require_unlocked(password.as_deref())?;
    if team > 1 {
        return Err("队伍号只能是 0（队伍一）或 1（队伍二）".into());
    }
    state
        .update_config(move |config| config.team_names[usize::from(team)] = name)
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 /// 录制目录与 ffmpeg 路径。
 #[tauri::command]
 pub fn set_recording_options(
    dir: Option<String>,
    ffmpeg: Option<String>,
    crf: Option<u8>,
    preset: Option<String>,
    state: Shared<'_>,
 ) -> Result<ConfigView, String> {
    state
        .update_config(move |config| {
            config.recording.dir = dir.filter(|d| !d.trim().is_empty());
            if let Some(ffmpeg) = ffmpeg.filter(|f| !f.trim().is_empty()) {
                config.recording.ffmpeg = ffmpeg;
            }
            if let Some(crf) = crf {
                config.recording.crf = crf;
            }
            if let Some(preset) = preset.filter(|p| !p.trim().is_empty()) {
                config.recording.preset = preset;
            }
        })
        .map_err(|err| format!("{err}"))?;
    Ok(ConfigView::from(&state.config()))
 }
 // ---------------------------------------------------------------------------
 // 截图与录制
 // ---------------------------------------------------------------------------
 /// 把某一路最新的一帧存成 PNG（存在录制目录的 `shots/` 下）。
 #[tauri::command]
 pub fn screenshot(camera: u32, state: Shared<'_>) -> Result<String, String> {
    let frame = state
        .latest_frames()
        .latest(camera)
        .ok_or_else(|| format!("还没有收到 0x{camera:08X} 的画面，暂时截不了"))?;
    let config = state.config();
    let dir = config.recordings_dir().join("shots");
    let path = crate::recording::save_screenshot(&frame.data, &dir, camera)
        .map_err(|err| format!("{err:#}"))?;
    log::info!(
        "screenshot of 0x{camera:08X} (frame {}) -> {}",
        frame.frame_id,
        path.display()
    );
    Ok(path.display().to_string())
 }
 /// 开始录制若干路。
 #[tauri::command]
 pub fn start_recording(
    cameras: Vec<u32>,
    state: Shared<'_>,
 ) -> Result<Vec<cam_core::snapshot::RecordingDto>, String> {
    if cameras.is_empty() {
        return Err("没有指定要录哪一路".into());
    }
    let config = state.config();
    let dir = config.recordings_dir();
    let mut started = Vec::new();
    for camera in cameras {
        // 帧率：配置里指定了就用它，否则用实测值。两者都没有时用保守默认值并记日志
        // ——猜错的表现是回放速度不对，而那个数会写进 DTO 与日志。
        let fps = if config.recording.fps > 0.0 {
            config.recording.fps
        } else {
            match state.fps_of(camera) {
                Some(measured) if measured > 1.0 => measured,
                _ => {
                    log::warn!(
                        "0x{camera:08X} 还没有测到帧率，录制先按 {FALLBACK_INPUT_FPS} fps 走；\
                         回放速度可能不准，可以改用 [recording] fps 明确指定"
                    );
                    FALLBACK_INPUT_FPS
                }
            }
        };
        let dto = state
            .recordings
            .start(
                camera,
                &dir,
                &config.recording.ffmpeg,
                fps,
                config.recording.crf,
                &config.recording.preset,
            )
            .map_err(|err| format!("起不了录制：{err:#}"))?;
        started.push(dto);
    }
    Ok(started)
 }
 /// 停止录制。`cameras` 为空表示全部停止。
 #[tauri::command]
 pub fn stop_recording(
    cameras: Vec<u32>,
    state: Shared<'_>,
 ) -> Result<Vec<cam_core::snapshot::RecordingDto>, String> {
    let stopped = if cameras.is_empty() {
        state.recordings.stop_all()
    } else {
        cameras
            .into_iter()
            .filter_map(|camera| state.recordings.stop(camera))
            .collect()
    };
    Ok(stopped)
 }
 /// 在访达/资源管理器里显示一个文件。
 ///
 /// 只允许指向录制目录里的东西：这是一个"用系统程序打开路径"的命令，把它做成任意路径
 /// 都能传的通用工具没有任何好处。
 #[tauri::command]
 pub fn reveal(path: String, state: Shared<'_>) -> Result<(), String> {
    let dir = state.config().recordings_dir();
    let target = PathBuf::from(&path);
    if !is_within(&dir, &target) {
        return Err(format!("只能打开录制目录（{}）里的文件", dir.display()));
    }
    if !target.exists() {
        return Err(format!("{} 不存在了", target.display()));
    }
    tauri_plugin_opener::reveal_item_in_dir(&target)
        .map_err(|err| format!("打开 {path} 失败：{err}"))
 }
 /// 用系统默认程序打开一个文件。
 ///
 /// 界面内回放走的是 Tauri 的资源协议，而那条协议只对白名单目录生效（见
 /// `tauri.conf.json` 里的 `assetProtocol.scope`）。录制目录被改到白名单之外时，`<video>`
 /// 会加载失败——那时这个命令是退路，而不是让现场以为"录下来的文件坏了"。
 #[tauri::command]
 pub fn open_file(path: String, state: Shared<'_>) -> Result<(), String> {
    let dir = state.config().recordings_dir();
    let target = PathBuf::from(&path);
    if !is_within(&dir, &target) {
        return Err(format!("只能打开录制目录（{}）里的文件", dir.display()));
    }
    if !target.exists() {
        return Err(format!("{} 不存在了", target.display()));
    }
    tauri_plugin_opener::open_path(&target, None::<&str>)
        .map_err(|err| format!("打开 {path} 失败：{err}"))
 }
 /// `child` 在 `parent` 里面吗。
 ///
 /// 逐段比较而不是字符串前缀：`/a/bc` 以 `/a/b` 为前缀，但它不在 `/a/b` 里面。
 fn is_within(parent: &Path, child: &Path) -> bool {
    let Ok(parent) = parent.canonicalize() else {
        return false;
    };
    match child.canonicalize() {
        Ok(child) => child.starts_with(parent),
        // 还不存在（比如刚被删掉）时退回文本比较，但仍然要求是父目录下的相对路径。
        Err(_) => child.parent().is_some_and(|p| {
            p.canonicalize()
                .map(|p| p.starts_with(&parent))
                .unwrap_or(false)
        }),
    }
 }
 // ---------------------------------------------------------------------------
 // 退出与清空
 // ---------------------------------------------------------------------------
 /// 清空配置：把文件挪到 `.bak`，然后回到"第一次启动"的状态。
 ///
 /// 不直接删的原因是现场排查：一个人说"我重置过了还是这样"时，能看一眼旧文件是最快的
 /// 结论。
 #[tauri::command]
 pub fn clear_config(password: Option<String>, state: Shared<'_>) -> Result<String, String> {
    state.require_unlocked(password.as_deref())?;
    let path = state.config_path.clone();
    if path.exists() {
        let backup = PathBuf::from(format!("{}.bak", path.display()));
        std::fs::rename(&path, &backup)
            .map_err(|err| format!("挪走 {} 失败：{err}", path.display()))?;
        log::warn!("配置已重置，旧文件留在 {}", backup.display());
    }
    state.lock();
    Ok(format!(
        "配置已重置（旧文件备份在 {}）。请重启程序。",
        path.display()
    ))
 }
 /// 退出程序。用户端要密码——现场"随手关掉"也是一种需要挡住的误操作。
 #[tauri::command]
 pub fn quit_app(
    password: Option<String>,
    app: AppHandle,
    state: Shared<'_>,
 ) -> Result<(), String> {
    state.require_unlocked(password.as_deref())?;
    // 先把录制收尾，否则 ffmpeg 会留下一个没有索引的 mp4。
    let stopped = state.recordings.stop_all();
    for dto in stopped {
        log::info!(
            "退出前收尾录制 0x{:08X}：{} 帧 -> {:?}",
            dto.camera,
            dto.frames_written,
            dto.path
        );
    }
    app.exit(0);
    Ok(())
 }
 /// 主动推一次快照。绑定改动之后前端不必等 200 ms。
 #[tauri::command]
 pub fn refresh(state: Shared<'_>) {
    state.push_snapshot();
 }
 #[cfg(test)]
 mod tests {
    use super::is_within;
    use std::path::PathBuf;
    #[test]
    fn a_sibling_directory_with_a_shared_prefix_is_not_inside() {
        let dir = std::env::temp_dir().join(format!("cam-reveal-{}", std::process::id()));
        std::fs::create_dir_all(dir.join("rec")).unwrap();
        std::fs::create_dir_all(dir.join("rec-evil")).unwrap();
        let inside = dir.join("rec").join("a.mp4");
        std::fs::write(&inside, b"x").unwrap();
        let outside = dir.join("rec-evil").join("b.mp4");
        std::fs::write(&outside, b"x").unwrap();
        assert!(is_within(&dir.join("rec"), &inside));
        assert!(
            !is_within(&dir.join("rec"), &outside),
            "`/a/rec-evil` 以 `/a/rec` 为前缀，但它不在里面"
        );
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn an_absolute_path_outside_is_refused() {
        let dir = std::env::temp_dir().join(format!("cam-reveal2-{}", std::process::id()));
        std::fs::create_dir_all(&dir).unwrap();
        assert!(!is_within(&dir, &PathBuf::from("/etc/hosts")));
        let _ = std::fs::remove_dir_all(&dir);
    }
 }
@@ -0,0 +1,376 @@
 //! 演示模式：本地合成画面与血量，喂进**真实的**接收路径。
 //!
 //! # 为什么不是"假界面"
 //!
 //! 演示模式不伪造数据给界面看，而是合成**协议数据报**，从
 //! [`cam_core::receiver::Receiver::datagram`] 与
 //! [`cam_core::armor::ArmorHealthStore::datagram`] 进去。也就是说它跑的是同一条真实链路：
 //!
 //! ```text
 //!   合成 JPEG ──分片──▶ Receiver::datagram ──重组──▶ 帧 sink ──▶ WebSocket ──▶ canvas
 //!   合成血量 ─────────▶ ArmorHealthStore ──▶ HealthTracker ──▶ 命中反馈
 //! ```
 //!
 //! 于是演示模式顺带成了这条链路的端到端验证：分片、重组、发现、统计、掉血派生、
 //! 两道闸门（用户端只收自己那一块）全都在跑真代码。截图、录制也因此**不需要特殊分支**。
 //!
 //! # 它绝不能被误读成真实链路
 //!
 //! 只在 `--demo` / `CAM_DEMO=1` 下启动，而且 [`cam_core::snapshot::Snapshot::demo`] 为
 //! true，界面必须显示"演示模式"标记。板子 id 也刻意取成 `0x0DE00001` 这种一眼能看出
 //! 是人造的形状。
 //!
 //! # 线程
 //!
 //! 三个：两路画面各一个（各 15fps 合成 JPEG），加一个广播装甲板血量的。它们活到进程
 //! 结束、不需要退出条件——和真实的接收线程一样。
 use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4};
 use std::sync::Arc;
 use std::time::Duration;
 use protocol::{fragment_frame, ArmorHealth, MsgType};
 use crate::state::{
    AppState, DEMO_ARMOR_A, DEMO_ARMOR_B, DEMO_CAMERA_A, DEMO_CAMERA_B,
 };
 /// 合成画面的尺寸。与实机一致（VGA），这样界面的缩放/比例在演示下也说得通。
 const WIDTH: u32 = 640;
 const HEIGHT: u32 = 480;
 /// 合成帧率。实机是 22fps；15 够看出流畅度，又把 CPU 留给真正要验证的界面。
 const FPS: u64 = 15;
 /// 装甲板广播周期，与固件一致（200 ms）。
 const ARMOR_PERIOD: Duration = Duration::from_millis(200);
 /// 演示里一次"命中"打掉多少血。故意取一组差异大的值，好看出闪红强度是不是跟着伤害走。
 const DAMAGE_CYCLE: [u16; 4] = [3, 7, 12, 25];
 pub fn spawn(state: Arc<AppState>) {
    log::warn!("演示模式：画面与血量都是本地合成的，不是场上的板子");
    for (camera, team) in [(DEMO_CAMERA_A, 0u8), (DEMO_CAMERA_B, 1u8)] {
        spawn_camera(Arc::clone(&state), camera, team);
    }
    spawn_armor(state);
 }
 /// 一路合成画面：周期广播 Hello（让发现列表有东西），并按 15fps 推分片。
 fn spawn_camera(state: Arc<AppState>, camera: u32, team: u8) {
    let _ = std::thread::Builder::new()
        .name(format!("demo-cam-{camera:08X}"))
        .spawn(move || {
            let from = SocketAddr::V4(SocketAddrV4::new(
                Ipv4Addr::new(127, 0, 0, 1),
                // 端口只是让日志/发现里的地址看起来像回事。
                41000 + team as u16,
            ));
            let hello = protocol::Hello {
                sender_id: camera,
                firmware: 0x0DE0,
            };
            let frame_interval = Duration::from_micros(1_000_000 / FPS);
            let mut frame_id: u32 = 0;
            let mut last_hello = std::time::Instant::now() - Duration::from_secs(10);
            loop {
                let started = std::time::Instant::now();
                // 板子每 2 秒广播一次在线状态，与固件一致。
                if last_hello.elapsed() >= Duration::from_secs(2) {
                    state
                        .receiver
                        .datagram(&hello.encode(MsgType::Hello), from);
                    last_hello = std::time::Instant::now();
                }
                let jpeg = render(camera, team, frame_id);
                for fragment in fragment_frame(camera, frame_id, &jpeg, WIDTH as u16, HEIGHT as u16)
                {
                    state.receiver.datagram(&fragment.encode(), from);
                }
                frame_id = frame_id.wrapping_add(1);
                // 按目标周期睡，而不是固定 sleep：合成一张 640x480 的 JPEG 要几毫秒，
                // 不扣掉这段时间的话实际帧率会明显低于 15，演示看起来像在卡。
                if let Some(rest) = frame_interval.checked_sub(started.elapsed()) {
                    std::thread::sleep(rest);
                }
            }
        });
 }
 /// 两块装甲板主板：各自按脚本掉血、打空、重置。
 fn spawn_armor(state: Arc<AppState>) {
    let _ = std::thread::Builder::new()
        .name("demo-armor".into())
        .spawn(move || {
            let boards = [(DEMO_ARMOR_A, 0u8, 41050u16), (DEMO_ARMOR_B, 1u8, 41051)];
            let mut hp = [100u16, 100u16];
            // 两块板子的掉血节奏错开，界面上两边的血量不会同时变。
            let mut ticks = [0u32, 7];
            let mut hits = [0usize, 1];
            let mut dead_for = [0u32, 0];
            loop {
                for (slot, (board, team, port)) in boards.iter().enumerate() {
                    ticks[slot] += 1;
                    if hp[slot] == 0 {
                        // 打空之后停一会儿再重置：让界面上的胜负横幅真的能被看到。
                        dead_for[slot] += 1;
                        if dead_for[slot] >= 10 {
                            hp[slot] = 100;
                            dead_for[slot] = 0;
                            ticks[slot] = 0;
                            log::info!("demo: 0x{board:08X} 重置为满血（长按 BOOT 的等价动作）");
                        }
                    } else if ticks[slot] % 15 == 0 {
                        // 约 3 秒一次。
                        let damage = DAMAGE_CYCLE[hits[slot] % DAMAGE_CYCLE.len()];
                        hits[slot] += 1;
                        hp[slot] = hp[slot].saturating_sub(damage);
                    }
                    let from = SocketAddr::V4(SocketAddrV4::new(
                        Ipv4Addr::new(127, 0, 0, 1),
                        *port,
                    ));
                    // 主板一次广播四条，整车一条血所以 hp 相同、index 0..3。
                    for index in 0..4u8 {
                        let health = ArmorHealth {
                            team: *team,
                            index,
                            hp: hp[slot],
                        };
                        state.armor.datagram(&health.encode_from(*board), from);
                    }
                }
                std::thread::sleep(ARMOR_PERIOD);
            }
        });
 }
 /// 合成一张 PNG/JPEG 用的画面。
 ///
 /// 内容刻意是为**验收**挑的：
 ///
 /// - 两路的底色不同（青 / 橙），一眼能分辨左右两格有没有串；
 /// - 正中有一组同心圆 + 十字，用来核对瞄准器的偏移校准（偏移为 0 时应该正好套住圆心）；
 /// - 每 40 px 一条淡网格，用来核对缩放与平移；
 /// - 左上角 16 个方块是二进制帧号，截图里能看出画面在推进；
 /// - 一个随时间走 Lissajous 的实心圆，用来判断两路是不是同一时刻的画面。
 fn render(camera: u32, team: u8, frame_id: u32) -> Vec<u8> {
    // 底色：竖直渐变。队伍一偏青、队伍二偏橙。
    //
    // 直接铺一块裸缓冲再交给 `from_raw`，而不是逐像素 `put_pixel`：一帧 30 万像素，
    // 每像素一次带边界检查的写入在 15fps 下是白白烧掉的 CPU。
    let tint: [i16; 3] = if team == 0 { [0, 46, 40] } else { [58, 30, 0] };
    let mut raw = vec![0u8; (WIDTH * HEIGHT * 3) as usize];
    for y in 0..HEIGHT {
        let shade = (y as i16 * 60 / HEIGHT as i16) as i16;
        let row = &mut raw[(y * WIDTH * 3) as usize..((y + 1) * WIDTH * 3) as usize];
        for pixel in row.chunks_exact_mut(3) {
            pixel[0] = (18 + tint[0] / 3 + shade) as u8;
            pixel[1] = (18 + tint[1] / 3 + shade) as u8;
            pixel[2] = (22 + tint[2] / 3 + shade) as u8;
        }
    }
    let mut img = image::RgbImage::from_raw(WIDTH, HEIGHT, raw)
        .expect("the buffer is exactly WIDTH * HEIGHT * 3 bytes");
    let (cx, cy) = (WIDTH as i32 / 2, HEIGHT as i32 / 2);
    let t = frame_id as f32 / FPS as f32;
    // 淡网格：每 40 px。缩放/平移时这组线是最直观的参照。
    for x in (0..WIDTH as i32).step_by(40) {
        for y in 0..HEIGHT as i32 {
            if let Some(pixel) = img.get_pixel_mut_checked(x as u32, y as u32) {
                *pixel = brighten(*pixel, 12);
            }
        }
    }
    for y in (0..HEIGHT as i32).step_by(40) {
        for x in 0..WIDTH as i32 {
            if let Some(pixel) = img.get_pixel_mut_checked(x as u32, y as u32) {
                *pixel = brighten(*pixel, 12);
            }
        }
    }
    // 中心的靶心：两个同心圆 + 四臂。瞄准器偏移校准时对着它看。
    ring(&mut img, cx, cy, 60, image::Rgb([200, 200, 210]));
    ring(&mut img, cx, cy, 28, image::Rgb([150, 150, 160]));
    arm(&mut img, cx - 90, cy, cx - 40, cy, image::Rgb([120, 120, 130]));
    arm(&mut img, cx + 40, cy, cx + 90, cy, image::Rgb([120, 120, 130]));
    arm(&mut img, cx, cy - 90, cx, cy - 40, image::Rgb([120, 120, 130]));
    arm(&mut img, cx, cy + 40, cx, cy + 90, image::Rgb([120, 120, 130]));
    // 二进制帧号：16 个方块，最左边是低位。
    for bit in 0..16i32 {
        let on = (frame_id >> bit) & 1 == 1;
        let x = 12 + bit * 14;
        let color = if on {
            image::Rgb([120, 255, 160])
        } else {
            image::Rgb([52, 52, 60])
        };
        fill_rect(&mut img, x, 12, 10, 10, color);
    }
    // Lissajous 圆点：两路同一个 t 下位置不同，用来分辨"这两格是不是同一块板子"。
    let phase = if team == 0 { 0.0 } else { 1.7 };
    let dot_x = cx + (250.0 * (t * 0.9 + phase).sin()) as i32;
    let dot_y = cy + (150.0 * (t * 1.3 + phase).cos()) as i32;
    disc(&mut img, dot_x, dot_y, 26, image::Rgb([255, 210, 90]));
    // 底部随时间右移的指示条：截图里能判断这一帧是不是较新的。
    let bar = ((t * 60.0) as i32).rem_euclid(WIDTH as i32 - 80);
    fill_rect(&mut img, bar, HEIGHT as i32 - 24, 60, 8, image::Rgb([90, 200, 255]));
    // 摄像头 id 的最低位用一个角标表示，进一步区分两路。
    let corner = if camera == DEMO_CAMERA_A { 0 } else { 1 };
    fill_rect(
        &mut img,
        WIDTH as i32 - 40 - corner * 24,
        12,
        18,
        18,
        if corner == 0 {
            image::Rgb([120, 255, 160])
        } else {
            image::Rgb([255, 140, 120])
        },
    );
    let mut out = Vec::new();
    let mut encoder = image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, 78);
    encoder
        .encode_image(&img)
        .expect("a synthetic RGB image always encodes");
    out
 }
 fn brighten(pixel: image::Rgb<u8>, by: u8) -> image::Rgb<u8> {
    image::Rgb([
        pixel[0].saturating_add(by),
        pixel[1].saturating_add(by),
        pixel[2].saturating_add(by),
    ])
 }
 fn put(img: &mut image::RgbImage, x: i32, y: i32, color: image::Rgb<u8>) {
    if x < 0 || y < 0 || x >= WIDTH as i32 || y >= HEIGHT as i32 {
        return;
    }
    img.put_pixel(x as u32, y as u32, color);
 }
 fn fill_rect(img: &mut image::RgbImage, x: i32, y: i32, w: i32, h: i32, color: image::Rgb<u8>) {
    for dy in 0..h {
        for dx in 0..w {
            put(img, x + dx, y + dy, color);
        }
    }
 }
 fn disc(img: &mut image::RgbImage, cx: i32, cy: i32, radius: i32, color: image::Rgb<u8>) {
    for dy in -radius..=radius {
        for dx in -radius..=radius {
            if dx * dx + dy * dy <= radius * radius {
                put(img, cx + dx, cy + dy, color);
            }
        }
    }
 }
 /// 细圆环（只画一圈，不填充）。
 fn ring(img: &mut image::RgbImage, cx: i32, cy: i32, radius: i32, color: image::Rgb<u8>) {
    let steps = 720;
    for step in 0..steps {
        let angle = step as f32 * std::f32::consts::TAU / steps as f32;
        put(
            img,
            cx + (radius as f32 * angle.cos()) as i32,
            cy + (radius as f32 * angle.sin()) as i32,
            color,
        );
    }
 }
 /// 一像素宽的线段（只用来画靶心的四臂，够用就行）。
 fn arm(img: &mut image::RgbImage, x0: i32, y0: i32, x1: i32, y1: i32, color: image::Rgb<u8>) {
    let steps = (x1 - x0).abs().max((y1 - y0).abs()).max(1);
    for step in 0..=steps {
        let f = step as f32 / steps as f32;
        put(
            img,
            x0 + ((x1 - x0) as f32 * f) as i32,
            y0 + ((y1 - y0) as f32 * f) as i32,
            color,
        );
    }
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    #[test]
    fn a_synthetic_frame_is_a_decodable_jpeg_of_the_right_size() {
        let jpeg = render(DEMO_CAMERA_A, 0, 42);
        assert!(jpeg.starts_with(&[0xFF, 0xD8]), "JPEG SOI");
        assert!(jpeg.ends_with(&[0xFF, 0xD9]), "JPEG EOI");
        let decoded = image::load_from_memory_with_format(&jpeg, image::ImageFormat::Jpeg)
            .expect("decodes");
        assert_eq!((decoded.width(), decoded.height()), (WIDTH, HEIGHT));
    }
    #[test]
    fn the_two_cameras_look_different() {
        // 两路画面必须能被一眼分辨，否则"左右两格是不是同一块板子"就看不出来。
        let a = render(DEMO_CAMERA_A, 0, 10);
        let b = render(DEMO_CAMERA_B, 1, 10);
        assert_ne!(a, b);
    }
    #[test]
    fn consecutive_frames_differ() {
        // 画面必须真的在动，否则截图看不出链路是活的。
        assert_ne!(render(DEMO_CAMERA_A, 0, 1), render(DEMO_CAMERA_A, 0, 2));
    }
    #[test]
    fn a_frame_is_big_enough_to_be_a_realistic_load() {
        // 太小说明画的内容退化了（比如全是纯色），那分片/带宽的验证就失去意义。
        let jpeg = render(DEMO_CAMERA_A, 0, 1);
        assert!(jpeg.len() > 3_000, "suspiciously small: {} bytes", jpeg.len());
        assert!(
            jpeg.len() < 200_000,
            "suspiciously large: {} bytes",
            jpeg.len()
        );
    }
 }
@@ -0,0 +1,357 @@
 //! cam-desktop —— ESP32 图传与装甲板系统的桌面端。
 //!
 //! 一个进程、两套页面：
 //!
 //! - **用户端**（`--role team`）：一路画面 + 血条 + 瞄准器，绑定一块图传板与一块装甲板。
 //! - **裁判端**（`--role referee`，默认）：两路画面 + 双方血量 + 装甲板发现列表 + 截图与录制。
 //!
 //! 界面是 WebView（React 渲染到 canvas），后端是这里的 Rust：UDP 收流、发现、装甲板、
 //! 配置与密码、录制。视频不经 IPC，而是走一个只监听回环的 WebSocket（见 [`server`]）。
 //!
 //! # 命令行
 //!
 //! ```text
 //!   --role <team|referee>   身份。默认看配置文件，没有配置文件时是 referee
 //!   --config <路径>          配置文件位置
 //!   --demo                  演示模式：本地合成画面与血量（标了"演示模式"）
 //!   --list                  打印发现的摄像头与装甲板后退出
 //!   -h, --help              显示这段帮助
 //! ```
 //!
 //! **未知参数只记一条日志，不报错**：macOS 从访达启动 .app 时会塞进来一个
 //! `-psn_0_123456`，把它当错误处理的表现是"双击图标什么都没发生"。
 mod commands;
 mod demo;
 mod recording;
 mod server;
 mod state;
 use std::error::Error;
 use std::path::PathBuf;
 use std::sync::Arc;
 use std::time::Duration;
 use cam_core::config::{self, Config, Role};
 use tauri::{Manager, RunEvent, WindowEvent};
 use state::AppState;
 const USAGE: &str = "\
 用法: cam-desktop [选项]
  --role <team|referee>   身份。默认看配置文件；没有配置文件时是 referee
  --config <路径>          配置文件位置
  --demo                  演示模式：画面与血量都是本地合成的
  --list                  打印发现的摄像头与装甲板后退出
  -h, --help               显示这段帮助
 身份由配置文件记住（~/.config/cam-desktop/config.toml），首次启动会在界面上问。
 用户端的绑定改动需要密码；裁判端不需要。
 环境变量：
  CAM_DEMO=1              等价于 --demo
  CAM_CONFIG=<路径>        等价于 --config <路径>
 两个环境变量存在的理由很实际：`tauri dev` 要用两个 `--` 才能把参数递给应用
 （`tauri dev -- -- --demo`），而写在一行环境变量里不会有人记错。
 ";
 fn main() {
    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
    if let Err(err) = run() {
        log::error!("{err}");
        // 走到这里说明连窗口都没起来（配置坏了、回环端口绑不上）。GUI 程序从访达启动时
        // 没有终端可看，所以把原因也写进一个旁边的文件——现场排查时这是唯一线索。
        let path = config::default_config_path().with_extension("startup-error.txt");
        let _ = std::fs::write(&path, format!("{err}\n"));
        eprintln!("{USAGE}");
        std::process::exit(1);
    }
 }
 /// 命令行参数。全部可选——什么都不给时按配置文件走。
 #[derive(Debug, Default)]
 struct Args {
    role: Option<Role>,
    config: Option<PathBuf>,
    demo: bool,
    list: bool,
    help: bool,
 }
 impl Args {
    fn parse(argv: impl Iterator<Item = String>) -> Self {
        let mut args = Args {
            demo: std::env::var("CAM_DEMO").is_ok_and(|v| v == "1" || v == "true"),
            config: std::env::var_os("CAM_CONFIG").map(PathBuf::from),
            ..Default::default()
        };
        let mut it = argv.peekable();
        while let Some(arg) = it.next() {
            match arg.as_str() {
                "-h" | "--help" => args.help = true,
                "--demo" => args.demo = true,
                "--list" => args.list = true,
                "--role" => {
                    args.role = it.next().and_then(|v| Role::parse(&v));
                }
                "--config" => {
                    args.config = it.next().map(PathBuf::from);
                }
                other => {
                    // 见模块文档：macOS 的 .app 启动参数与 shell 里的笔误都可能出现在这里，
                    // 但报错的代价（窗口起不来）远大于收益。
                    log::debug!("ignoring unknown argument {other:?}");
                }
            }
        }
        args
    }
 }
 fn run() -> Result<(), Box<dyn Error>> {
    let args = Args::parse(std::env::args().skip(1));
    if args.help {
        print!("{USAGE}");
        return Ok(());
    }
    let config_path = args.config.clone().unwrap_or_else(config::default_config_path);
    // 首次启动时导入旧客户端的配置，并把旧文件改名成 .bak。
    let (mut config, notes) = config::load_with_migration(&config_path)?;
    // 命令行覆盖配置文件，反过来不成立（只在内存里改）。这样现场可以把一台机器临时当
    // 另一台用，而不动文件。
    if let Some(role) = args.role {
        config.role = role;
    }
    for note in &notes {
        log::info!("{note}");
    }
    log::info!(
        "role={} team={} camera={:?} armor={:?} mirror={} demo={} config={}",
        config.role.as_str(),
        config.team,
        config.camera_id,
        config.armor_id,
        config.mirror,
        args.demo,
        config_path.display()
    );
    let (state, video_socket, armor_socket) =
        AppState::new(config_path, config, notes, args.demo)?;
    // 视频端口绑不上时没有 socket，接收线程也就没有意义——界面会显示那条说明。
    if let Some(socket) = video_socket {
        let receiver = Arc::clone(&state.receiver);
        std::thread::Builder::new()
            .name("udp-reader".into())
            .spawn(move || receiver.run(socket))?;
    }
    if let Some(socket) = armor_socket {
        state.armor.spawn(socket);
    }
    // 顺序有讲究：sink 必须先装好，后台任务才开始推——否则头几帧会掉在空处。
    state.install_sinks();
    // 视频通道的地址。
    //
    // 带 token 的那一版只在 debug 级：它是给本机开发者用 `wscat` 连上去看这条通道用的
    // （"画面不动"时能立刻分清是后端没推还是前端没接）。info 级只报端口。
    log::info!("stream: listening on ws://127.0.0.1:{}", state.port);
    log::debug!("stream: {}", state.stream_info().url);
    if args.demo {
        state.note("演示模式已打开：画面与血量由本机合成，不是场上的板子。");
        demo::spawn(Arc::clone(&state));
    }
    // --list：等一个广播周期，把发现到的东西打出来。
    //
    // 旧的 Slint 客户端在 release 的用户端直接拒绝这个选项（它会列出场上所有板子的 id
    // 与 IP）。现在这条限制落在别处：用户端的发现列表只在**解锁后的设置面板**里放开，
    // 而这里的输出只进日志，不进界面。
    if args.list {
        std::thread::sleep(Duration::from_secs(5));
        println!("摄像头：");
        for camera in state.snapshot().cameras {
            println!(
                "  {}  {}  {}",
                camera.id_text,
                camera.addr,
                if camera.online { "在线" } else { "离线" }
            );
        }
        println!("装甲板：");
        for board in state.snapshot().armor_boards {
            println!(
                "  {}  {}  队伍{}  {} 血",
                board.id_text,
                board.addr,
                board.team + 1,
                board.hp
            );
        }
        state.recordings.stop_all();
        _ = state;
        return Ok(());
    }
    let listener_state = Arc::clone(&state);
    let app = tauri::Builder::default()
        .plugin(tauri_plugin_opener::init())
        .manage(Arc::clone(&state))
        .invoke_handler(tauri::generate_handler![
            commands::stream_info,
            commands::get_snapshot,
            commands::get_config,
            commands::list_media_files,
            commands::config_path,
            commands::unlock,
            commands::lock,
            commands::set_password,
            commands::set_discovery_open,
            commands::bind_camera,
            commands::bind_armor,
            commands::set_team,
            commands::set_role,
            commands::set_mirror,
            commands::save_hud,
            commands::set_team_name,
            commands::set_referee_slots,
            commands::set_recording_options,
            commands::screenshot,
            commands::start_recording,
            commands::stop_recording,
            commands::reveal,
            commands::open_file,
            commands::clear_config,
            commands::quit_app,
            commands::refresh,
        ])
        .setup(move |_app| {
            listener_state.spawn_background();
            Ok(())
        })
        // 用户端未解锁时拦住"关窗口"与"退出"。
        //
        // 这是需求里明确要的（退出/关闭也要密码），所以这里把 close 拦下来并让前端弹
        // 解锁框。拦不住的路径仍然存在——`kill -9`、强退、拔电源——所以它同样是"防
        // 随手误操作"，不是安全边界。
        .on_window_event(|window, event| {
            if let WindowEvent::CloseRequested { api, .. } = event {
                let state = window.state::<Arc<AppState>>();
                if state.config().role.needs_password() && !state.is_unlocked() {
                    api.prevent_close();
                    state.push(server::WireMsg::ConfirmQuit);
                }
            }
        })
        .build(tauri::generate_context!())?;
    app.run(|app, event| {
        if let RunEvent::ExitRequested { api, .. } = &event {
            let state = app.state::<Arc<AppState>>();
            if state.config().role.needs_password() && !state.is_unlocked() {
                api.prevent_exit();
                state.push(server::WireMsg::ConfirmQuit);
                return;
            }
        }
        if let RunEvent::Exit = event {
            // 收尾录制：ffmpeg 需要把索引写完，否则留下一个放不了的 mp4。
            let state = app.state::<Arc<AppState>>();
            let stopped = state.recordings.stop_all();
            for dto in stopped {
                log::info!(
                    "退出：0x{:08X} 收了 {} 帧 -> {:?}",
                    dto.camera,
                    dto.frames_written,
                    dto.path
                );
            }
        }
    });
    Ok(())
 }
 /// 让 [`Config`] 在日志里可读。
 ///
 /// 实现成自由函数而不是给 `Config` 加 `Display`：那是 cam-core 的公共类型，而"日志里长
 /// 什么样"是这个二进制自己的事。
 #[allow(dead_code)]
 fn describe(config: &Config) -> String {
    format!(
        "role={} team={} camera={:?} armor={:?}",
        config.role.as_str(),
        config.team,
        config.camera_id,
        config.armor_id
    )
 }
 #[cfg(test)]
 mod tests {
    use super::Args;
    fn args(list: &[&str]) -> Args {
        Args::parse(list.iter().map(|s| s.to_string()))
    }
    #[test]
    fn defaults_are_all_optional() {
        let parsed = args(&[]);
        assert!(parsed.role.is_none(), "the config file decides");
        assert!(!parsed.demo);
        assert!(!parsed.help);
    }
    #[test]
    fn role_and_config_are_read() {
        let parsed = args(&["--role", "team", "--config", "/tmp/x.toml"]);
        assert_eq!(parsed.role, Some(cam_core::Role::Team));
        assert_eq!(parsed.config.unwrap().to_string_lossy(), "/tmp/x.toml");
    }
    #[test]
    fn a_mac_app_launch_argument_does_not_break_startup() {
        // 从访达双击 .app 时系统会塞进来这个。把它当错误处理的表现是"双击没反应"。
        let parsed = args(&["-psn_0_123456"]);
        assert!(parsed.role.is_none());
        assert!(!parsed.help);
    }
    #[test]
    fn a_bad_role_value_falls_back_to_the_config_rather_than_dying() {
        let parsed = args(&["--role", "teem"]);
        assert!(parsed.role.is_none(), "typo must not kill the window");
    }
    #[test]
    fn demo_can_be_turned_on_from_the_command_line() {
        assert!(args(&["--demo"]).demo);
    }
 }
@@ -0,0 +1,826 @@
 //! 录制为 mp4，以及录制文件的清点。
 //!
 //! # 为什么用 ffmpeg 子进程而不是 Rust 编码器
 //!
 //! 两路 640x480@22fps 的 H.264 编码在 Rust 侧要引一个大而重的编码器绑定；而现场机器上
 //! 已经有 ffmpeg（`/opt/homebrew/bin/ffmpeg`），它是硬编码/多线程都调好的。代价是多一个
 //! **外部依赖**——所以 [Recorder::start] 在 ffmpeg 起不来时返回一个明确的错误，而不是
 //! 让界面看起来"在录"，其实什么都没写。
 //!
 //! # 为什么帧率要显式告诉 ffmpeg
 //!
 //! `image2pipe` 里的 JPEG 序列**没有时间戳**：一串帧在 ffmpeg 看来就是"以固定帧率播放
 //! 的图片"。所以必须由我们给出这个数，而它只能来自实测（[`crate::state`] 里的帧率窗口）。
 //! 猜错的表现是回放快放或慢放——而且看不出来是哪里错了，所以在 DTO 与文档里都写明了。
 //!
 //! # 为什么经由一个线程和一条有界队列
 //!
 //! 喂帧发生在 UDP 接收线程里，而**接收线程绝不能被写盘拖慢**：那一天的表现是链路上
 //! 本不存在的丢帧。所以中间隔一条长度 64 的队列：写不进去就把帧丢掉并计数，丢帧数会
 //! 出现在界面上——少了半秒却不说，会看起来像相机的问题。
 use std::collections::HashMap;
 use std::io::{ErrorKind, Write};
 use std::path::{Path, PathBuf};
 use std::process::{Child, ChildStdin, Command, Stdio};
 use std::sync::atomic::{AtomicU64, Ordering};
 use std::sync::mpsc::{sync_channel, SyncSender, TrySendError};
 use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::{SystemTime, UNIX_EPOCH};
 use anyhow::{anyhow, Context, Result};
 use cam_core::snapshot::{id_text, RecordingDto};
 use protocol::Frame;
 /// 写入线程的队列长度。
 ///
 /// 22fps 下这是约 3 秒的缓冲：够吸收一次写盘的抖动，又不至于在 ffmpeg 卡死时把内存
 /// 堆起来。
 const QUEUE: usize = 64;
 /// Unix 毫秒。
 pub fn now_ms() -> u64 {
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_millis() as u64)
        .unwrap_or(0)
 }
 /// 一次录制。
 pub struct Recorder {
    camera: u32,
    path: PathBuf,
    started_ms: u64,
    input_fps: f32,
    /// `None` 表示已经停止喂帧（队列那头的线程会随之收尾）。
    tx: Option<SyncSender<Arc<Frame>>>,
    frames_written: Arc<AtomicU64>,
    frames_dropped: Arc<AtomicU64>,
    error: Arc<Mutex<Option<String>>>,
    finish: Option<thread::JoinHandle<()>>,
 }
 impl Recorder {
    /// 启动一路录制。
    ///
    /// `fps` 是喂给 ffmpeg 的输入帧率，调用方负责给出实测值。
    pub fn start(
        camera: u32,
        dir: &Path,
        ffmpeg: &str,
        fps: f32,
        crf: u8,
        preset: &str,
    ) -> Result<Self> {
        std::fs::create_dir_all(dir)
            .with_context(|| format!("creating the recording directory {}", dir.display()))?;
        // 文件名里带秒级时间戳，但**必须**再查一次有没有同名——同一秒里停一次再开一次
        // 是很自然的操作（"这局重录"），而重名意味着 ffmpeg 的 `-y` 会把上一段直接覆盖掉，
        // 没有任何提示。现场丢掉的那段往往正好是要复盘的那一段。
        let path = unique_take_path(dir, camera);
        let mut child = Command::new(ffmpeg)
            .args(["-hide_banner", "-loglevel", "error", "-y"])
            // 输入：一串 JPEG。-framerate 必须在 -i 之前，它是 image2 解复用器的选项。
            .args(["-f", "image2pipe", "-c:v", "mjpeg"])
            .args(["-framerate", &format!("{fps:.4}")])
            .args(["-i", "pipe:0"])
            .args(["-an"])
            .args(["-c:v", "libx264", "-preset", preset])
            .args(["-crf", &crf.to_string()])
            // yuv420p + faststart：前者让文件在任何播放器里都能放，后者把索引挪到文件头，
            // 于是分享出去的 mp4 可以边下边播。
            .args(["-pix_fmt", "yuv420p", "-movflags", "+faststart"])
            .arg(&path)
            .stdin(Stdio::piped())
            .stdout(Stdio::null())
            .stderr(Stdio::piped())
            .spawn()
            .with_context(|| {
                format!(
                    "could not start ffmpeg ({ffmpeg}); 用 [recording] ffmpeg 指定它的路径"
                )
            })?;
        let stdin = child
            .stdin
            .take()
            .ok_or_else(|| anyhow!("ffmpeg was started without a stdin pipe"))?;
        let (tx, rx) = sync_channel::<Arc<Frame>>(QUEUE);
        let frames_written = Arc::new(AtomicU64::new(0));
        let frames_dropped = Arc::new(AtomicU64::new(0));
        let error = Arc::new(Mutex::new(None));
        let finish = {
            let frames_written = Arc::clone(&frames_written);
            let error = Arc::clone(&error);
            let path = path.clone();
            thread::Builder::new()
                .name(format!("rec-writer-{}", id_text(camera)))
                .spawn(move || {
                    if let Err(err) = pump(&rx, stdin, &mut child, &frames_written) {
                        log::error!("recording {} stopped: {err:#}", path.display());
                        *error.lock().expect("rec error mutex poisoned") =
                            Some(format!("{err:#}"));
                    }
                })?
        };
        log::info!(
            "recording 0x{camera:08X} -> {} ({fps:.1} fps in, crf {crf}, {preset})",
            path.display()
        );
        Ok(Self {
            camera,
            path,
            started_ms: now_ms(),
            input_fps: fps,
            tx: Some(tx),
            frames_written,
            frames_dropped,
            error,
            finish: Some(finish),
        })
    }
    /// 喂一帧。写不进去就计一次丢帧，不阻塞。
    pub fn feed(&self, frame: &Arc<Frame>) {
        let Some(tx) = self.tx.as_ref() else {
            return;
        };
        match tx.try_send(Arc::clone(frame)) {
            Ok(()) => {}
            Err(TrySendError::Full(_)) => {
                self.frames_dropped.fetch_add(1, Ordering::Relaxed);
            }
            // 写入线程已经结束（ffmpeg 退出）：由 `error` 记录原因，这里不再重复报。
            Err(TrySendError::Disconnected(_)) => {}
        }
    }
    pub fn frames_written(&self) -> u64 {
        self.frames_written.load(Ordering::Relaxed)
    }
    pub fn frames_dropped(&self) -> u64 {
        self.frames_dropped.load(Ordering::Relaxed)
    }
    pub fn error(&self) -> Option<String> {
        self.error.lock().expect("rec error mutex poisoned").clone()
    }
    /// 停止并等 ffmpeg 把文件收尾（`+faststart` 要重写一遍索引，所以这一步不是瞬时的）。
    pub fn stop(mut self) -> RecordingDto {
        // 丢掉发送端 ⇒ 写入线程的 recv 返回 Err ⇒ 它关掉 stdin 并 wait 子进程。
        drop(self.tx.take());
        if let Some(handle) = self.finish.take() {
            if handle.join().is_err() {
                log::warn!("the recording writer thread panicked");
            }
        }
        let mut dto = self.dto();
        dto.active = false;
        if let Some(error) = dto.error.as_deref() {
            log::warn!("recording 0x{:08X} finished with an error: {error}", self.camera);
        } else {
            log::info!(
                "recording 0x{:08X} stopped: {} frames -> {}",
                self.camera,
                dto.frames_written,
                self.path.display()
            );
        }
        dto
    }
    pub fn dto(&self) -> RecordingDto {
        RecordingDto {
            camera: self.camera,
            camera_text: id_text(self.camera),
            active: self.tx.is_some(),
            path: Some(self.path.display().to_string()),
            input_fps: self.input_fps,
            frames_written: self.frames_written(),
            frames_dropped: self.frames_dropped(),
            started_ms: Some(self.started_ms),
            error: self.error(),
        }
    }
 }
 /// 给一段新录制挑一个不会被占用的文件名。
 ///
 /// `rec-00000001-2026-10-14_19-12-05.mp4`，同秒重名时往后排 `-2`、`-3`。
 fn unique_take_path(dir: &Path, camera: u32) -> PathBuf {
    let base = format!(
        "rec-{}-{}",
        id_text(camera).trim_start_matches("0x"),
        chrono::Local::now().format("%Y-%m-%d_%H-%M-%S")
    );
    unique_path(dir, &base, "mp4")
 }
 /// 挑一个还没被占用的路径：`<base>.<ext>` → `<base>-2.<ext>` → `<base>-3.<ext>`。
 ///
 /// 录制与截图共用它。时间戳只到秒（截图到毫秒），所以"同一秒停一次再开一次"这种事
 /// 会挑到同一个名字——而 ffmpeg 的 `-y` 与图片写入都会**静默覆盖**。现场丢掉的那一段
 /// 往往正好是要复盘的那一段。
 fn unique_path(dir: &Path, base: &str, ext: &str) -> PathBuf {
    let mut candidate = dir.join(format!("{base}.{ext}"));
    for n in 2..1000 {
        if !candidate.exists() {
            break;
        }
        candidate = dir.join(format!("{base}-{n}.{ext}"));
    }
    candidate
 }
 /// 把一张 JPEG 存成 PNG。
 ///
 /// 从命令里抽出来是为了能测：这条路径里唯一可能出错的是"JPEG 解不开"与"PNG 写不出去"，
 /// 两者都值得有一个直接对着它们写的测试——现场截图失败却不报错，等于证据没留下来。
 pub fn save_screenshot(jpeg: &[u8], dir: &Path, camera: u32) -> Result<PathBuf> {
    std::fs::create_dir_all(dir)
        .with_context(|| format!("creating the screenshot directory {}", dir.display()))?;
    let path = unique_path(
        dir,
        &format!(
            "shot-{camera:08X}-{}",
            chrono::Local::now().format("%Y-%m-%d_%H-%M-%S-%3f")
        ),
        "png",
    );
    let image = image::load_from_memory_with_format(jpeg, image::ImageFormat::Jpeg)
        .map_err(|err| anyhow!("这一帧不是能解码的 JPEG：{err}"))?;
    image
        .save_with_format(&path, image::ImageFormat::Png)
        .map_err(|err| anyhow!("写不了 {}：{err}", path.display()))?;
    Ok(path)
 }
 /// 写入线程的主体：把队列里的帧写进 ffmpeg 的 stdin，队列关闭后收尾。
 fn pump(
    rx: &std::sync::mpsc::Receiver<Arc<Frame>>,
    mut stdin: ChildStdin,
    child: &mut Child,
    frames_written: &AtomicU64,
 ) -> Result<()> {
    while let Ok(frame) = rx.recv() {
        if let Err(err) = stdin.write_all(&frame.data) {
            // 管道断了通常意味着 ffmpeg 已经退出（参数不对、磁盘满）。把它的 stderr
            // 读出来拼进错误里：只说"Broken pipe"对现场毫无帮助。
            let reason = child_stderr(child);
            return Err(anyhow!(
                "writing to ffmpeg failed: {err}{}",
                reason.map(|r| format!("；ffmpeg 说：{r}")).unwrap_or_default()
            ));
        }
        frames_written.fetch_add(1, Ordering::Relaxed);
    }
    // 关掉 stdin 是让 ffmpeg 知道"没有更多帧了"的唯一方式。
    drop(stdin);
    match child.wait() {
        Ok(status) if status.success() => Ok(()),
        Ok(status) => {
            let reason = child_stderr(child);
            Err(anyhow!(
                "ffmpeg exited with {status}{}",
                reason.map(|r| format!("：{r}")).unwrap_or_default()
            ))
        }
        Err(err) => Err(anyhow!("could not wait for ffmpeg: {err}")),
    }
 }
 /// 读一下子进程的 stderr（已经读完则返回 `None`）。
 fn child_stderr(child: &mut Child) -> Option<String> {
    use std::io::Read;
    let mut buf = String::new();
    let stderr = child.stderr.as_mut()?;
    // 管道是非阻塞读的话这里会直接返回；否则 ffmpeg 已经退出，读得到 EOF。
    match stderr.read_to_string(&mut buf) {
        Ok(0) => None,
        Ok(_) => Some(buf.trim().to_string()),
        Err(err) if err.kind() == ErrorKind::WouldBlock => None,
        Err(_) => None,
    }
 }
 /// 所有正在进行的录制。
 #[derive(Default)]
 pub struct RecordingSet {
    inner: Mutex<HashMap<u32, Recorder>>,
 }
 impl RecordingSet {
    pub fn new() -> Arc<Self> {
        Arc::new(Self::default())
    }
    pub fn start(
        &self,
        camera: u32,
        dir: &Path,
        ffmpeg: &str,
        fps: f32,
        crf: u8,
        preset: &str,
    ) -> Result<RecordingDto> {
        // **先停掉同一路已有的那次录制，再开新的。**
        //
        // 顺序不是随便定的：文件名唯一性靠"这个路径已经被占用了"来判断，而 ffmpeg 的输出
        // 文件是它启动之后才创建的。先开新的话，新的一段会挑到与上一段相同的名字，然后被
        // 它的 `-y` 覆盖掉——而上一段刚要收尾。先停就能保证上一个文件已经落地，`exists()`
        // 于是是可信的。
        let previous = self.inner.lock().expect("recording mutex poisoned").remove(&camera);
        if let Some(previous) = previous {
            log::warn!("0x{camera:08X} was already recording; the previous take is being closed");
            drop(previous.stop());
        }
        let recorder = Recorder::start(camera, dir, ffmpeg, fps, crf, preset)?;
        let dto = recorder.dto();
        self.inner
            .lock()
            .expect("recording mutex poisoned")
            .insert(camera, recorder);
        Ok(dto)
    }
    pub fn stop(&self, camera: u32) -> Option<RecordingDto> {
        let recorder = self
            .inner
            .lock()
            .expect("recording mutex poisoned")
            .remove(&camera)?;
        Some(recorder.stop())
    }
    pub fn stop_all(&self) -> Vec<RecordingDto> {
        let recorders: Vec<Recorder> = self
            .inner
            .lock()
            .expect("recording mutex poisoned")
            .drain()
            .map(|(_, recorder)| recorder)
            .collect();
        recorders.into_iter().map(Recorder::stop).collect()
    }
    /// 把一帧喂给对应那一路的录制器。在 UDP 接收线程里被调用，所以必须快。
    pub fn feed(&self, frame: &Arc<Frame>) {
        // 先快速判断有没有在录，避免每帧都抢锁。
        if self.inner.lock().expect("recording mutex poisoned").is_empty() {
            return;
        }
        let inner = self.inner.lock().expect("recording mutex poisoned");
        if let Some(recorder) = inner.get(&frame.sender_id) {
            recorder.feed(frame);
        }
    }
    pub fn active(&self) -> Vec<RecordingDto> {
        let inner = self.inner.lock().expect("recording mutex poisoned");
        let mut list: Vec<RecordingDto> = inner.values().map(Recorder::dto).collect();
        list.sort_by_key(|dto| dto.camera);
        list
    }
 }
 /// 一段已经录好的文件或截图。
 #[derive(Debug, Clone, serde::Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct MediaFileDto {
    pub name: String,
    pub path: String,
    pub kind: String,
    pub bytes: u64,
    pub modified_ms: u64,
 }
 /// 列出目录里的 mp4 与 png，新的在前。
 ///
 /// 只认这两种后缀：目录是给人看的，不该因为里面放了个 `.DS_Store` 就报错或显示出来。
 pub fn list_media(dir: &Path) -> Vec<MediaFileDto> {
    let Ok(entries) = std::fs::read_dir(dir) else {
        return Vec::new();
    };
    let mut out = Vec::new();
    for entry in entries.flatten() {
        let path = entry.path();
        if !path.is_file() {
            continue;
        }
        let Some(ext) = path.extension().and_then(|e| e.to_str()) else {
            continue;
        };
        let kind = match ext.to_ascii_lowercase().as_str() {
            "mp4" => "video",
            "png" => "image",
            _ => continue,
        };
        let Ok(meta) = entry.metadata() else {
            continue;
        };
        out.push(MediaFileDto {
            name: path
                .file_name()
                .map(|n| n.to_string_lossy().to_string())
                .unwrap_or_default(),
            path: path.display().to_string(),
            kind: kind.to_string(),
            bytes: meta.len(),
            modified_ms: meta
                .modified()
                .ok()
                .and_then(|t| t.duration_since(UNIX_EPOCH).ok())
                .map(|d| d.as_millis() as u64)
                .unwrap_or(0),
        });
    }
    out.sort_by(|a, b| b.modified_ms.cmp(&a.modified_ms));
    out
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    use protocol::fragment_frame;
    use std::time::Duration;
    /// 合成一张能被 ffmpeg 解出来的 JPEG。
    fn jpeg(width: u32, height: u32, seed: u8) -> Vec<u8> {
        let mut img = image::RgbImage::new(width, height);
        for (x, y, pixel) in img.enumerate_pixels_mut() {
            *pixel = image::Rgb([
                (x as u8).wrapping_add(seed),
                (y as u8).wrapping_add(seed),
                seed,
            ]);
        }
        let mut out = Vec::new();
        let mut encoder =
            image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, 80);
        encoder.encode_image(&img).expect("encodes");
        out
    }
    fn frame(camera: u32, id: u32) -> Arc<Frame> {
        Arc::new(Frame {
            sender_id: camera,
            frame_id: id,
            width: 64,
            height: 48,
            data: jpeg(64, 48, id as u8),
        })
    }
    fn has_ffmpeg() -> bool {
        Command::new("ffmpeg")
            .arg("-version")
            .stdout(Stdio::null())
            .stderr(Stdio::null())
            .status()
            .map(|s| s.success())
            .unwrap_or(false)
    }
    fn temp_dir(tag: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!(
            "cam-desktop-rec-{tag}-{}",
            std::process::id()
        ));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).expect("creates the temp dir");
        dir
    }
    #[test]
    fn a_missing_ffmpeg_is_an_error_not_a_silent_no_op() {
        let dir = temp_dir("no-ffmpeg");
        // 不用 expect_err：那要求 Ok 那一侧实现 Debug，而 Recorder 持有着管道与线程，
        // 给它加 Debug 只是为了写测试，不划算。
        let err = match Recorder::start(1, &dir, "definitely-not-ffmpeg", 20.0, 20, "veryfast") {
            Ok(_) => panic!("must refuse to pretend it is recording"),
            Err(err) => err,
        };
        assert!(
            err.to_string().contains("ffmpeg"),
            "the message must name the missing tool: {err}"
        );
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn recording_produces_a_playable_mp4() {
        // 这一条真的会起 ffmpeg 并写出一个文件，然后用 ffprobe 读回它的帧数与分辨率。
        // 只用"文件存在且非空"来断言是不够的：ffmpeg 参数写错时也会留下一个空的
        // 容器，而那正是最难在现场发现的一种失败。
        if !has_ffmpeg() {
            eprintln!("skipping: no ffmpeg on this machine");
            return;
        }
        let dir = temp_dir("mp4");
        let set = RecordingSet::new();
        set.start(0xAAAA, &dir, "ffmpeg", 20.0, 23, "veryfast")
            .expect("starts");
        for i in 0..20 {
            set.feed(&frame(0xAAAA, i));
        }
        // 让写入线程把队列排空再停。
        for _ in 0..50 {
            thread::sleep(Duration::from_millis(10));
            if set.active()[0].frames_written >= 20 {
                break;
            }
        }
        let dto = set.stop(0xAAAA).expect("was recording");
        assert_eq!(dto.frames_written, 20, "all 20 frames reached ffmpeg");
        assert_eq!(dto.frames_dropped, 0);
        assert!(dto.error.is_none(), "ffmpeg said: {:?}", dto.error);
        let path = dto.path.expect("has a path");
        let meta = std::fs::metadata(&path).expect("the file exists");
        assert!(meta.len() > 0, "an empty container is a failure, not a take");
        if let Some((frames, width, height)) = ffprobe_frames(&path) {
            assert_eq!(frames, 20, "ffmpeg wrote every frame we fed it");
            assert_eq!((width, height), (64, 48));
        }
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn feeding_after_stop_does_not_panic() {
        if !has_ffmpeg() {
            return;
        }
        let dir = temp_dir("after-stop");
        let set = RecordingSet::new();
        set.start(0xBBBB, &dir, "ffmpeg", 20.0, 23, "veryfast")
            .unwrap();
        let held = frame(0xBBBB, 0);
        set.stop(0xBBBB);
        // 停止之后接收线程可能还有一帧在手。
        set.feed(&held);
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn starting_twice_closes_the_first_take_instead_of_leaking_it() {
        if !has_ffmpeg() {
            return;
        }
        let dir = temp_dir("twice");
        let set = RecordingSet::new();
        // 第一段：喂几帧并等它们真的落到 ffmpeg。写盘是异步的，不等到位的话这次录制会是
        // 零帧，而零帧时 ffmpeg 连输出文件都不会创建——那测的就不是同一件事了。
        set.start(1, &dir, "ffmpeg", 20.0, 23, "veryfast").unwrap();
        for i in 0..8 {
            set.feed(&frame(1, i));
        }
        wait_for_frames(&set, 1, 8);
        // 第二段：这里会把第一段收尾，并另取一个文件名。
        let second = set.start(1, &dir, "ffmpeg", 20.0, 23, "veryfast").unwrap();
        for i in 10..18 {
            set.feed(&frame(1, i));
        }
        wait_for_frames(&set, 1, 8);
        assert_eq!(set.active().len(), 1, "只有一路在录");
        assert_eq!(set.stop_all().len(), 1);
        let files = list_media(&dir);
        assert_eq!(files.len(), 2, "两段各自留下一个文件：{files:?}");
        assert!(
            files.iter().all(|file| file.bytes > 0),
            "两段都得有内容，空容器不算一次录制：{files:?}"
        );
        assert!(second.path.is_some(), "第二段也应该有自己的路径");
        let _ = std::fs::remove_dir_all(&dir);
    }
    /// 等到某一路写进了至少 `want` 帧，或者超时。
    fn wait_for_frames(set: &RecordingSet, camera: u32, want: u64) {
        for _ in 0..100 {
            let written = set
                .active()
                .iter()
                .find(|dto| dto.camera == camera)
                .map(|dto| dto.frames_written)
                .unwrap_or(0);
            if written >= want {
                return;
            }
            thread::sleep(Duration::from_millis(10));
        }
        panic!("0x{camera:08X} 没有把 {want} 帧写进 ffmpeg");
    }
    #[test]
    fn two_takes_in_the_same_second_do_not_overwrite_each_other() {
        // 同一秒里停一次再开一次是现场很自然的操作（"这局重录"）。重名的后果是 ffmpeg 的
        // `-y` 静默覆盖上一段——而丢掉的那段往往正好是要复盘的那段。
        let dir = temp_dir("unique");
        let first = unique_take_path(&dir, 0xAAAA);
        std::fs::write(&first, b"").unwrap();
        let second = unique_take_path(&dir, 0xAAAA);
        assert_ne!(first, second);
        assert!(
            second.to_string_lossy().ends_with("-2.mp4"),
            "got {}",
            second.display()
        );
        std::fs::write(&second, b"").unwrap();
        let third = unique_take_path(&dir, 0xAAAA);
        assert!(third.to_string_lossy().ends_with("-3.mp4"));
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn a_screenshot_is_a_readable_png_of_the_same_size() {
        let dir = temp_dir("shots");
        let path = save_screenshot(&jpeg(64, 48, 7), &dir, 0x3D4D_8A9A).expect("saves");
        let decoded = image::open(&path).expect("the PNG is readable");
        assert_eq!((decoded.width(), decoded.height()), (64, 48));
        assert!(
            path.file_name().unwrap().to_string_lossy().starts_with("shot-3D4D8A9A-"),
            "文件名要能看出是哪一路截的：{path:?}"
        );
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn two_screenshots_never_land_on_the_same_file() {
        let dir = temp_dir("shots-twice");
        let first = save_screenshot(&jpeg(32, 32, 1), &dir, 1).unwrap();
        let second = save_screenshot(&jpeg(32, 32, 2), &dir, 1).unwrap();
        assert_ne!(first, second, "两次截图不能落在同一个文件上");
        assert!(first.to_string_lossy().contains("shot-00000001-"));
        assert!(second.to_string_lossy().contains("shot-00000001-"));
        // 时间戳到毫秒，所以这两次通常落在不同的毫秒上，各自拿到自己的名字。真正要挡的
        // 是**同一毫秒**内连按两次，那由 `unique_path` 的后缀兜住——下面直接验证它。
        let forced = unique_path(&dir, "shot-00000001-fixed", "png");
        std::fs::write(&forced, b"").unwrap();
        let forced2 = unique_path(&dir, "shot-00000001-fixed", "png");
        assert!(forced2.to_string_lossy().ends_with("-2.png"), "got {forced2:?}");
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn a_broken_frame_is_an_error_not_an_empty_png() {
        let dir = temp_dir("shots-bad");
        let err = save_screenshot(b"not a jpeg at all", &dir, 1).unwrap_err();
        assert!(err.to_string().contains("JPEG"), "got {err}");
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn media_listing_ignores_anything_that_is_not_a_take() {
        let dir = temp_dir("listing");
        std::fs::write(dir.join("a.mp4"), b"x").unwrap();
        std::fs::write(dir.join("b.PNG"), b"x").unwrap();
        std::fs::write(dir.join("notes.txt"), b"x").unwrap();
        std::fs::write(dir.join(".DS_Store"), b"x").unwrap();
        let files = list_media(&dir);
        let names: Vec<&str> = files.iter().map(|f| f.name.as_str()).collect();
        assert_eq!(names.len(), 2, "got {names:?}");
        assert!(names.contains(&"a.mp4"));
        assert!(names.contains(&"b.PNG"), "后缀大小写不该决定它是不是一张截图");
        assert_eq!(files[0].kind, "video");
        let _ = std::fs::remove_dir_all(&dir);
    }
    #[test]
    fn listing_a_missing_directory_is_empty_not_an_error() {
        assert!(list_media(Path::new("/nonexistent/recordings")).is_empty());
    }
    #[test]
    fn the_file_name_says_which_camera_and_when() {
        // 现场翻目录时要能一眼看出是哪一路、哪一局。
        assert!(id_text(0x3D4D_8A9A).ends_with("3D4D8A9A"));
    }
    /// 用 ffprobe 读回帧数与分辨率。ffprobe 不在就返回 `None`（跳过那几条断言）。
    fn ffprobe_frames(path: &str) -> Option<(i64, u32, u32)> {
        let out = Command::new("ffprobe")
            .args([
                "-v",
                "error",
                "-select_streams",
                "v:0",
                "-count_frames",
                "-show_entries",
                "stream=nb_read_frames,width,height",
                "-of",
                "default=noprint_wrappers=1",
                path,
            ])
            .output()
            .ok()?;
        if !out.status.success() {
            return None;
        }
        let text = String::from_utf8_lossy(&out.stdout);
        let mut frames = None;
        let mut width = None;
        let mut height = None;
        for line in text.lines() {
            if let Some((key, value)) = line.split_once('=') {
                match key {
                    "nb_read_frames" => frames = value.parse().ok(),
                    "width" => width = value.parse().ok(),
                    "height" => height = value.parse().ok(),
                    _ => {}
                }
            }
        }
        Some((frames?, width?, height?))
    }
    #[test]
    fn fragmented_frames_are_not_what_the_recorder_wants() {
        // 录制器收的是**重组之后**的整帧（sink 传进来的就是），不是分片。这里把这个
        // 约定钉下来：如果哪天有人在接收路径上提前喂分片，测试会立刻说明原因。
        let frags = fragment_frame(1, 1, &jpeg(64, 48, 1), 64, 48);
        assert!(frags.len() == 1, "one small JPEG is one fragment");
        let whole = frame(1, 1);
        assert!(whole.data.len() > 2, "a real JPEG, not a fragment header");
    }
 }
@@ -0,0 +1,369 @@
 //! 界面与后端之间的视频通道：一个只监听回环地址的 WebSocket。
 //!
 //! # 为什么不是 Tauri 的 IPC
 //!
 //! 两路 22fps、每帧约 22 kB，也就是每秒约 1 MB 的裸 JPEG。走 IPC 的话它要被序列化成
 //! JSON（base64 再涨 1/3），再在 JS 侧解回来——CPU 花在没人需要的编解码上，延迟也白
 //! 涨一截。WebSocket 的二进制帧把原始 JPEG 字节直接交给前端，浏览器用原生解码器
 //! （`createImageBitmap`）解，**后端连 JPEG 都不用解**。
 //!
 //! # 为什么要有 token
 //!
 //! 端口是随机分配的，但同机器上任何进程都能连回环地址。这条通道里有实时画面，给它一
 //! 个每次启动随机生成的 token（前端从 `stream_info` 命令拿到），至少让"另一个本地程序
 //! 顺手连上来看画面"变成一件需要先读到那个 token 的事。
 //!
 //! 说清楚它的边界：这**不是**防对手的措施——对手要看画面得先在自己的机器上跑这套客户
 //! 端，那道闸门在 [`cam_core::receiver::Receiver`] 里。这里的 token 只防止本机上的顺手
 //! 连接。
 //!
 //! # 二进制帧的布局
 //!
 //! ```text
 //!   0              4              8      10     12             16
 //!   +--------------+--------------+------+------+--------------+---------+
 //!   | sender_id u32| frame_id u32 | w u16| h u16| jpeg_len u32 | JPEG... |
 //!   +--------------+--------------+------+------+--------------+---------+
 //! ```
 //!
 //! 小端。16 字节头，前端切掉它就能拿到一段完整的 JPEG。`sender_id` 让前端知道这一帧是
 //! 哪块板子的——用户端只画绑定的那一路，裁判端按槽位分配画两路。
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Arc;
 use std::time::Duration;
 use futures_util::{SinkExt, StreamExt};
 use serde::Serialize;
 use tokio::net::{TcpListener, TcpStream};
 use tokio::sync::broadcast;
 use tokio_tungstenite::tungstenite::handshake::server::{ErrorResponse, Request, Response};
 use tokio_tungstenite::tungstenite::http::StatusCode;
 use tokio_tungstenite::tungstenite::{Bytes, Message};
 use cam_core::snapshot::{HitDto, Snapshot};
 /// 二进制帧头长度。
 pub const FRAME_HEADER_LEN: usize = 16;
 /// 广播通道的容量。
 ///
 /// 满了之后 `send` 会挤掉最老的（接收慢的连接会拿到 `Lagged`）——对实时画面这正是想要
 /// 的：落后 200 帧的客户端需要的是最新的那一帧，不是补齐历史。按每帧 16+22 kB 算，
 /// 256 个槽位约 5.6 MB 上限。
 pub const CHANNEL_CAPACITY: usize = 256;
 /// 向界面推送的消息。
 pub enum ServerMsg {
    /// 一帧原始 JPEG（已经拼好 16 字节头）。
    ///
    /// 载荷用 `Bytes` 而不是 `Arc<Vec<u8>>`：它本身就是引用计数的缓冲，克隆是加一次
    /// 引用计数，而且正好是 tungstenite 要的类型——每个连接一次多余的拷贝就此消失。
    Binary(Bytes),
    /// JSON 文本。
    Text(String),
 }
 /// JSON 文本消息的信封。
 ///
 /// 用内部标签 `t` 而不是两个字段：前端一个 `switch (msg.t)` 就能分发，且不需要为每种
 /// 消息各写一次 `JSON.parse` 的错误处理。
 #[derive(Debug, Clone, Serialize)]
 #[serde(tag = "t", rename_all = "camelCase")]
 pub enum WireMsg {
    /// 完整状态快照，5 Hz。
    Snapshot(Box<Snapshot>),
    /// 一次掉血，立即推。
    Hit(HitDto),
    /// 后端拦截了一次"关闭/退出"（用户端还没解锁）。前端据此弹出解锁对话框。
    ConfirmQuit,
    /// 一条说明（迁移、录制报错等），前端显示成一行提示。
    ///
    /// 写成带字段的结构体而不是 `Note(String)`：serde 的**内部标签**（`#[serde(tag)]`）
    /// 只支持载荷是 map 的变体，newtype 里放一个字符串会在运行时报错，而不是编译期。
    Note { message: String },
 }
 /// 前端连接这条通道需要的信息。
 #[derive(Debug, Clone, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct StreamInfo {
    /// `ws://127.0.0.1:<port>/?token=...`
    pub url: String,
    pub port: u16,
    /// 当前连着的界面数。用于诊断"画面不动"到底是后端没推还是前端没连。
    pub clients: usize,
 }
 /// 把一张帧编码成二进制消息。
 pub fn encode_frame(frame: &protocol::Frame) -> Vec<u8> {
    let mut out = Vec::with_capacity(FRAME_HEADER_LEN + frame.data.len());
    out.extend_from_slice(&frame.sender_id.to_le_bytes());
    out.extend_from_slice(&frame.frame_id.to_le_bytes());
    out.extend_from_slice(&frame.width.to_le_bytes());
    out.extend_from_slice(&frame.height.to_le_bytes());
    out.extend_from_slice(&(frame.data.len() as u32).to_le_bytes());
    out.extend_from_slice(&frame.data);
    out
 }
 /// 从二进制消息里解出帧头。前后端对这段字节布局的约定由测试盯着。
 #[cfg(test)]
 pub fn decode_frame_header(message: &[u8]) -> Option<(u32, u32, u16, u16, usize)> {
    if message.len() < FRAME_HEADER_LEN {
        return None;
    }
    let sender_id = u32::from_le_bytes(message[0..4].try_into().ok()?);
    let frame_id = u32::from_le_bytes(message[4..8].try_into().ok()?);
    let width = u16::from_le_bytes(message[8..10].try_into().ok()?);
    let height = u16::from_le_bytes(message[10..12].try_into().ok()?);
    let len = u32::from_le_bytes(message[12..16].try_into().ok()?) as usize;
    if message.len() < FRAME_HEADER_LEN + len {
        return None;
    }
    Some((sender_id, frame_id, width, height, len))
 }
 /// 绑一个随机端口的回环 listener。
 ///
 /// 随机端口而不是固定端口：同一台机器上同时开用户端和裁判端时不会撞车。
 pub async fn bind() -> std::io::Result<(TcpListener, u16)> {
    let listener = TcpListener::bind(("127.0.0.1", 0)).await?;
    let port = listener.local_addr()?.port();
    Ok((listener, port))
 }
 /// 接受循环。每个连接一个任务，活到连接断开。
 pub async fn serve(
    listener: TcpListener,
    token: String,
    tx: broadcast::Sender<Arc<ServerMsg>>,
    clients: Arc<AtomicUsize>,
 ) {
    loop {
        let (stream, peer) = match listener.accept().await {
            Ok(pair) => pair,
            Err(err) => {
                log::warn!("stream: accept failed: {err}");
                tokio::time::sleep(Duration::from_millis(200)).await;
                continue;
            }
        };
        let tx = tx.clone();
        let token = token.clone();
        let clients = Arc::clone(&clients);
        tauri::async_runtime::spawn(async move {
            if let Err(err) = handle_client(stream, peer, &token, tx, clients).await {
                log::debug!("stream: client {peer} ended: {err}");
            }
        });
    }
 }
 async fn handle_client(
    stream: TcpStream,
    peer: std::net::SocketAddr,
    token: &str,
    tx: broadcast::Sender<Arc<ServerMsg>>,
    clients: Arc<AtomicUsize>,
 ) -> anyhow::Result<()> {
    stream.set_nodelay(true).ok();
    let expected = token.to_string();
    let callback = move |req: &Request, res: Response| -> Result<Response, ErrorResponse> {
        let query = req.uri().query().unwrap_or("");
        let presented = query
            .split('&')
            .filter_map(|pair| pair.split_once('='))
            .find(|(key, _)| *key == "token")
            .map(|(_, value)| value.to_string());
        match presented {
            Some(value) if constant_time_eq(&value, &expected) => Ok(res),
            _ => {
                log::warn!("stream: refusing {peer}: wrong or missing token");
                let mut response = ErrorResponse::new(Some("bad token".into()));
                *response.status_mut() = StatusCode::FORBIDDEN;
                Err(response)
            }
        }
    };
    let ws = tokio_tungstenite::accept_hdr_async(stream, callback).await?;
    let (mut sink, mut incoming) = ws.split();
    let mut rx = tx.subscribe();
    let mut keepalive = tokio::time::interval(Duration::from_secs(20));
    let count = clients.fetch_add(1, Ordering::Relaxed) + 1;
    log::info!("stream: interface connected from {peer} ({count} connected)");
    // 连上就先推一条提示，前端能据此在界面上显示"通道已接通"。
    let hello = serde_json::to_string(&WireMsg::Note {
        message: "video channel ready".into(),
    })
    .unwrap_or_else(|_| "{}".into());
    let _ = sink.send(Message::text(hello)).await;
    let result = loop {
        tokio::select! {
            message = rx.recv() => match message {
                Ok(msg) => {
                    let out = match &*msg {
                        ServerMsg::Binary(bytes) => Message::Binary(bytes.clone()),
                        ServerMsg::Text(text) => Message::text(text.clone()),
                    };
                    if let Err(err) = sink.send(out).await {
                        break Err(anyhow::anyhow!("send failed: {err}"));
                    }
                }
                // 接收慢，积压被挤掉了。对视频这是正常且期望的：跳过旧帧，继续送新的。
                Err(broadcast::error::RecvError::Lagged(skipped)) => {
                    log::debug!("stream: {peer} lagged {skipped} messages; skipping ahead");
                }
                Err(broadcast::error::RecvError::Closed) => {
                    break Ok(());
                }
            },
            _ = keepalive.tick() => {
                // WKWebView 侧的连接可能在休眠后静默失效。ping 让这种情况变成一次明确的
                // 发送失败，而不是一个永远不刷新的窗口。
                if let Err(err) = sink.send(Message::Ping(Bytes::new())).await {
                    break Err(anyhow::anyhow!("keepalive failed: {err}"));
                }
            }
            incoming_msg = incoming.next() => match incoming_msg {
                None => break Ok(()),
                Some(Err(err)) => break Err(anyhow::anyhow!("receive failed: {err}")),
                // 这条通道是单向的：前端发来的东西（pong 除外）一律忽略。
                Some(Ok(_)) => {}
            },
        }
    };
    let count = clients.fetch_sub(1, Ordering::Relaxed) - 1;
    log::info!("stream: interface disconnected ({count} connected)");
    result
 }
 /// 定长比较，避免 token 校验泄露时间信息。
 fn constant_time_eq(a: &str, b: &str) -> bool {
    let (a, b) = (a.as_bytes(), b.as_bytes());
    if a.len() != b.len() {
        return false;
    }
    let mut diff = 0u8;
    for (x, y) in a.iter().zip(b) {
        diff |= x ^ y;
    }
    diff == 0
 }
 /// 生成一个随机 token。
 pub fn random_token() -> String {
    use rand::RngCore;
    let mut bytes = [0u8; 24];
    rand::rng().fill_bytes(&mut bytes);
    bytes.iter().map(|b| format!("{b:02x}")).collect()
 }
 #[cfg(test)]
 mod tests {
    use super::*;
    fn frame(sender: u32, id: u32, len: usize) -> protocol::Frame {
        protocol::Frame {
            sender_id: sender,
            frame_id: id,
            width: 640,
            height: 480,
            data: vec![0xAB; len],
        }
    }
    #[test]
    fn the_binary_header_roundtrips() {
        let encoded = encode_frame(&frame(0x3D4D_8A9A, 4242, 22_000));
        assert_eq!(encoded.len(), FRAME_HEADER_LEN + 22_000);
        assert_eq!(
            decode_frame_header(&encoded),
            Some((0x3D4D_8A9A, 4242, 640, 480, 22_000))
        );
    }
    #[test]
    fn a_truncated_message_is_refused_rather_than_read_past_the_end() {
        let mut encoded = encode_frame(&frame(1, 1, 100));
        encoded.truncate(FRAME_HEADER_LEN + 40);
        // 头里声明 100 字节，实际只有 40：宁可返回 None，也不要让前端拿到一段不完整的
        // JPEG（那会解码失败，或者更糟——解出一张半截的图）。
        assert_eq!(decode_frame_header(&encoded), None);
        assert_eq!(decode_frame_header(&[0u8; 4]), None);
    }
    #[test]
    fn the_token_comparison_is_exact() {
        assert!(constant_time_eq("abc", "abc"));
        assert!(!constant_time_eq("abc", "abd"));
        assert!(!constant_time_eq("abc", "abcd"));
        assert!(!constant_time_eq("", "a"));
        assert!(constant_time_eq("", ""));
    }
    #[test]
    fn tokens_differ_between_runs() {
        assert_ne!(random_token(), random_token());
        assert_eq!(random_token().len(), 48);
    }
    #[test]
    fn the_wire_envelope_carries_the_message_kind() {
        let json = serde_json::to_string(&WireMsg::Hit(HitDto {
            board: 1,
            team: 0,
            index: 2,
            from: 100,
            to: 97,
            damage: 3,
            at_ms: 1,
        }))
        .unwrap();
        assert!(json.contains(r#""t":"hit""#), "got {json}");
        assert!(json.contains(r#""damage":3"#), "got {json}");
    }
    #[test]
    fn a_unit_variant_is_just_a_tag() {
        let json = serde_json::to_string(&WireMsg::ConfirmQuit).unwrap();
        assert_eq!(json, r#"{"t":"confirmQuit"}"#);
    }
    #[test]
    fn a_note_is_tagged_too() {
        let json = serde_json::to_string(&WireMsg::Note {
            message: "hi".into(),
        })
        .unwrap();
        assert_eq!(json, r#"{"t":"note","message":"hi"}"#);
    }
 }
@@ -0,0 +1,648 @@
 //! 进程内的共享状态。
 //!
 //! 这里是"网络层的推"与"界面的拉"交汇的地方：
 //!
 //! - **推**：接收线程拿到帧就交给 sink，sink 直接发进广播通道（不阻塞、不排队）；
 //!   装甲板上报推进一个 [`HealthTracker`]，派生出掉血事件就立刻推一条。
 //! - **拉**：一个 5 Hz 的循环把当前状态拼成一份 [`Snapshot`] 推出去。界面不需要任何
 //!   轮询命令，它只是渲染收到的那份状态。
 //!
 //! # 密码闸门的执行点在这里，不在界面里
 //!
 //! 所有会改绑定的命令都过 [`AppState::require_unlocked`]。界面上有一个解锁对话框，但那
 //! **只是入口**：即使有人从控制台直接调 `invoke("bind_camera")`，一样要过这一关。这和
 //! 旧客户端把防作弊放在**接收端**而不是界面里是同一条原则。
 use std::collections::{HashMap, HashSet};
 use std::path::PathBuf;
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::{Arc, Mutex};
 use std::time::{Duration, Instant};
 use anyhow::{Context, Result};
 use cam_core::armor::{ArmorHealthStore, HealthTracker};
 use cam_core::config::{Config, Role};
 use cam_core::password;
 use cam_core::receiver::{Discovery, LatestFrames, Receiver};
 use cam_core::ArmorSource;
 use cam_core::slots::SlotAllocator;
 use cam_core::snapshot::{
    resolve_outcomes, ArmorBoardDto, CameraDto, CameraStatsDto, ConfigView, HitDto, Snapshot,
    SlotsDto, TeamHealthDto,
 };
 use cam_core::stats::{FpsWindow, DEFAULT_WINDOW};
 use tokio::sync::broadcast;
 use crate::recording::{now_ms, RecordingSet};
 use crate::server::{self, ServerMsg, WireMsg};
 /// 状态快照的推送频率。
 ///
 /// 5 Hz：血量心跳是 200 ms，所以这个频率刚好不漏掉一次掉血；而再快也只是让界面做
 /// 无意义的重绘。
 pub const SNAPSHOT_INTERVAL: Duration = Duration::from_millis(200);
 /// 界面端是否产出技术读数。
 ///
 /// 由**编译模式**决定而不是命令行参数：命令行开关意味着二进制里带着那套东西，忘开
 /// 一次就泄露了。裁判端不受影响——它是中立方，双方遥测对判罚有用。
 pub const TEAM_DIAGNOSTICS: bool = cfg!(debug_assertions);
 pub struct AppState {
    pub config_path: PathBuf,
    config: Mutex<Config>,
    /// 会话内解锁（见模块文档）。
    unlocked: AtomicBool,
    /// 设置面板是否打开，决定发现列表放不放开。
    discovery_open: AtomicBool,
    pub receiver: Arc<Receiver>,
    pub armor: Arc<ArmorHealthStore>,
    discovery: Arc<Discovery>,
    latest: Arc<LatestFrames>,
    /// 每一路的帧率窗口。掉线的摄像头会被清掉，回来时重新建。
    fps: Mutex<HashMap<u32, FpsWindow>>,
    slots: Mutex<SlotAllocator>,
    pub recordings: Arc<RecordingSet>,
    tx: broadcast::Sender<Arc<ServerMsg>>,
    /// 回环上已经绑好的 WebSocket listener，等 `spawn_background` 取走。
    ///
    /// 先绑再交给后台任务，是为了让"端口绑不上"在启动阶段就报错，而不是变成一个永远
    /// 连不上的界面。
    listener: Mutex<Option<tokio::net::TcpListener>>,
    pub port: u16,
    token: String,
    clients: Arc<AtomicUsize>,
    pub demo: bool,
    notes: Mutex<Vec<String>>,
    started: Instant,
 }
 impl AppState {
    /// 建好状态，并绑好两个 UDP 端口。
    ///
    /// 视频端口（5600）绑不上是**致命**的：整个程序的存在意义就是收画面，绑不上应该
    /// 立刻报错，而不是开一个永远不出画面的窗口。装甲板端口（5601）绑不上只是没有
    /// 血量，退回占位符即可——血量显示不了不该让整个客户端起不来。
    pub fn new(
        config_path: PathBuf,
        config: Config,
        mut notes: Vec<String>,
        demo: bool,
    ) -> Result<(Arc<Self>, Option<std::net::UdpSocket>, Option<std::net::UdpSocket>)> {
        let role = config.role;
        let bound = if role == Role::Team { config.camera_id } else { None };
        // 视频端口绑不上**不**致命：界面照常起来，并把原因写在最显眼的地方。
        //
        // 一开始这里是 `?`（直接退出）。但那样一来，现场看到的是一次闪退加上一句只出现
        // 在 stderr 的话——从访达双击启动时连 stderr 都没有。让窗口起来并说明原因，比
        // 静默退出有用得多；而且"另一个客户端已经在跑"恰好是最常见的原因。
        let (receiver, video_socket) = match Receiver::start(
            protocol::BROADCAST_ADDR,
            role.to_protocol(),
            bound,
        ) {
            Ok((receiver, socket)) => (Arc::new(receiver), Some(socket)),
            Err(err) => {
                log::error!("could not bind UDP {}: {err}", protocol::DEFAULT_PORT);
                notes.push(format!(
                    "绑不上 UDP {}：{err}。多半是同一个端口上已经跑着另一个客户端 \
                     （旧的 Slint 版或另一份本程序）。画面收不到，其它功能照常。",
                    protocol::DEFAULT_PORT
                ));
                (
                    Arc::new(Receiver::new(
                        protocol::BROADCAST_ADDR,
                        role.to_protocol(),
                        bound,
                    )),
                    None,
                )
            }
        };
        let discovery = receiver.discovery();
        let latest = receiver.latest_frames();
        // 装甲板：两端都要收。用户端要显示**双方**的血条（左上自己、右上对手），裁判端也是双方。
        let (armor, armor_socket) = match ArmorHealthStore::start() {
            Ok((store, socket)) => (store, Some(socket)),
            Err(err) => {
                log::warn!(
                    "armor: could not listen on UDP {}: {err}; health stays a placeholder",
                    protocol::ARMOR_PORT
                );
                (Arc::new(ArmorHealthStore::new()), None)
            }
        };
        let (tx, _) = broadcast::channel(server::CHANNEL_CAPACITY);
        let (listener, port) = tauri::async_runtime::block_on(server::bind())
            .context("绑不上本地 WebSocket 端口（回环地址）")?;
        let state = Arc::new(Self {
            config_path,
            config: Mutex::new(config),
            unlocked: AtomicBool::new(false),
            discovery_open: AtomicBool::new(false),
            receiver,
            armor,
            discovery,
            latest,
            fps: Mutex::new(HashMap::new()),
            slots: Mutex::new(SlotAllocator::new()),
            recordings: RecordingSet::new(),
            tx,
            listener: Mutex::new(Some(listener)),
            port,
            token: server::random_token(),
            clients: Arc::new(AtomicUsize::new(0)),
            demo,
            notes: Mutex::new(notes),
            started: Instant::now(),
        });
        state.apply_gates();
        Ok((state, video_socket, armor_socket))
    }
    /// 让视频通道开始工作：把帧与装甲板上报接到广播通道上。
    ///
    /// 必须在 `Arc<AppState>` 建好之后调用（sink 里要持有 state 的通道）。
    pub fn install_sinks(self: &Arc<Self>) {
        let tx = self.tx.clone();
        let recordings = Arc::clone(&self.recordings);
        // 帧的 sink：在接收线程里跑，只做"编码一次 + 广播"。这一份字节所有界面共用。
        self.receiver
            .set_frame_sink(Arc::new(move |frame: Arc<protocol::Frame>| {
                recordings.feed(&frame);
                let bytes = server::encode_frame(&frame);
                let _ = tx.send(Arc::new(ServerMsg::Binary(bytes.into())));
            }));
        let tx = self.tx.clone();
        let tracker = Arc::new(Mutex::new(HealthTracker::new()));
        // 装甲板的 sink：把"现在多少血"派生为"刚刚掉了几点"，立刻推给界面。
        self.armor.set_sink(Arc::new(move |report| {
            let hit = tracker
                .lock()
                .expect("health tracker mutex poisoned")
                .observe(&report);
            let Some(hit) = hit else {
                return;
            };
            log::info!(
                "armor: board 0x{:08X} took {} damage ({} -> {})",
                hit.board,
                hit.damage,
                hit.from,
                hit.to
            );
            let dto = HitDto {
                board: hit.board,
                team: hit.team,
                index: hit.index,
                from: hit.from,
                to: hit.to,
                damage: hit.damage,
                at_ms: now_ms(),
            };
            let _ = tx.send(Arc::new(ServerMsg::Text(
                serde_json::to_string(&WireMsg::Hit(dto)).unwrap_or_default(),
            )));
        }));
    }
    /// 起 WebSocket 服务与快照循环。
    pub fn spawn_background(self: &Arc<Self>) {
        let Some(listener) = self
            .listener
            .lock()
            .expect("listener mutex poisoned")
            .take()
        else {
            log::warn!("spawn_background called twice; the stream server is already running");
            return;
        };
        let state = Arc::clone(self);
        let token = self.token.clone();
        let tx = self.tx.clone();
        let clients = Arc::clone(&self.clients);
        tauri::async_runtime::spawn(async move {
            server::serve(listener, token, tx, clients).await;
        });
        let state_for_loop = Arc::clone(&state);
        tauri::async_runtime::spawn(async move {
            let mut ticker = tokio::time::interval(SNAPSHOT_INTERVAL);
            loop {
                ticker.tick().await;
                state_for_loop.tick();
                state_for_loop.push_snapshot();
            }
        });
    }
    // -----------------------------------------------------------------------
    // 配置
    // -----------------------------------------------------------------------
    pub fn config(&self) -> Config {
        self.config.lock().expect("config mutex poisoned").clone()
    }
    /// 改配置、落盘、重新套用闸门。
    pub fn update_config(&self, change: impl FnOnce(&mut Config)) -> Result<Config> {
        let updated = {
            let mut config = self.config.lock().expect("config mutex poisoned");
            change(&mut config);
            // Guard 上不能直接调 `normalized()`（它取走 self）。克隆一份再归一化：配置
            // 只有几百字节，而这里每次都是人点一下才发生。
            config.clone().normalized()
        };
        updated
            .save(&self.config_path)
            .context("写入配置文件失败；改动只在本次运行内有效")?;
        *self.config.lock().expect("config mutex poisoned") = updated.clone();
        self.apply_gates();
        Ok(updated)
    }
    /// 按当前配置重新设置两道闸门。
    ///
    /// 每一次可能改变身份、绑定或发现开合的改动之后都要调用它——把这件事收在一个函数
    /// 里，是为了不让"某个命令忘了重新套用闸门"这种漏洞有时间长出来。
    pub fn apply_gates(&self) {
        let config = self.config();
        let role = config.role;
        self.receiver.set_role(role.to_protocol());
        // 第一道闸门：帧。用户端只看绑定的那一块；裁判端看全部。
        let limit = match role {
            Role::Team => config.camera_id,
            Role::Referee => None,
        };
        self.receiver.restrict_to(limit);
        // 第二道闸门：发现列表。只有用户端在**解锁后**打开设置面板时才放开；裁判端
        // 本来就要看到全场。
        let open = match role {
            Role::Referee => true,
            Role::Team => self.discovery_open.load(Ordering::Relaxed) && self.unlocked.load(Ordering::Relaxed),
        };
        self.receiver.set_discovery_all(open);
        if !open {
            self.discovery_open.store(false, Ordering::Relaxed);
        }
    }
    // -----------------------------------------------------------------------
    // 密码闸门
    // -----------------------------------------------------------------------
    pub fn is_unlocked(&self) -> bool {
        // 裁判端没有密码（见 Role::needs_password），所以它永远是"已解锁"。
        !self.config().role.needs_password() || self.unlocked.load(Ordering::Relaxed)
    }
    /// 校验一次密码，成功就把会话标记为已解锁。
    pub fn unlock(&self, presented: &str) -> Result<bool> {
        let stored = self.config().password;
        let Some(stored) = stored else {
            // 还没设过密码：任何输入都不该被当成"通过"。
            return Ok(false);
        };
        let ok = password::verify_password(presented, &stored)?;
        if ok {
            self.unlocked.store(true, Ordering::Relaxed);
            log::info!("密码校验通过；本次运行内不再询问");
        } else {
            log::warn!("密码校验失败");
        }
        Ok(ok)
    }
    /// 手动重新上锁。
    pub fn lock(&self) {
        self.unlocked.store(false, Ordering::Relaxed);
        self.discovery_open.store(false, Ordering::Relaxed);
        self.apply_gates();
    }
    /// 改绑之前的守门人。
    ///
    /// `presented` 允许调用方在同一次调用里带上密码（界面上就是这样：解锁对话框收起后
    /// 用户立刻做改动），但会话已经解锁时不需要它。
    pub fn require_unlocked(&self, presented: Option<&str>) -> Result<(), String> {
        if self.is_unlocked() {
            return Ok(());
        }
        if let Some(presented) = presented {
            match self.unlock(presented) {
                Ok(true) => return Ok(()),
                Ok(false) => {
                    return Err("密码不对。改摄像头/装甲板绑定、切换队伍都需要密码。".into())
                }
                Err(err) => return Err(format!("存下来的密码哈希读不出来：{err}")),
            }
        }
        Err("这个改动需要密码。先解锁（密码只是防止现场随手改绑，见 README 的说明）。".into())
    }
    /// 打开/关闭设置面板带来的发现列表。
    pub fn set_discovery_open(&self, open: bool) -> Result<(), String> {
        if open {
            self.require_unlocked(None)?;
        }
        self.discovery_open.store(open, Ordering::Relaxed);
        self.apply_gates();
        Ok(())
    }
    /// 设置或修改密码。用户端第一次启动必须设。
    pub fn set_password(&self, current: Option<&str>, fresh: &str) -> Result<()> {
        let existing = self.config().password;
        if let Some(existing) = existing {
            // 已有密码：必须能证明知道旧的（或者在本次运行里已经解锁过）。
            let trusted = self.unlocked.load(Ordering::Relaxed)
                || current
                    .map(|current| password::verify_password(current, &existing).unwrap_or(false))
                    .unwrap_or(false);
            if !trusted {
                anyhow::bail!("修改密码需要先输入当前密码");
            }
        }
        let hash = password::hash_password(fresh)?;
        self.update_config(move |config| config.password = Some(hash))?;
        self.unlocked.store(true, Ordering::Relaxed);
        Ok(())
    }
    // -----------------------------------------------------------------------
    // 推送
    // -----------------------------------------------------------------------
    pub fn push(&self, msg: WireMsg) {
        let text = match serde_json::to_string(&msg) {
            Ok(text) => text,
            Err(err) => {
                log::error!("could not serialise a message for the interface: {err}");
                return;
            }
        };
        // 没有连接时发送会失败，这是正常情况（界面还没起来，或者刚刷新）。
        let _ = self.tx.send(Arc::new(ServerMsg::Text(text)));
    }
    pub fn push_snapshot(&self) {
        self.push(WireMsg::Snapshot(Box::new(self.snapshot())));
    }
    pub fn note(&self, message: impl Into<String>) {
        let message = message.into();
        log::info!("{message}");
        self.notes
            .lock()
            .expect("notes mutex poisoned")
            .push(message.clone());
        self.push(WireMsg::Note { message });
    }
    pub fn stream_info(&self) -> server::StreamInfo {
        server::StreamInfo {
            url: format!("ws://127.0.0.1:{}/?token={}", self.port, self.token),
            port: self.port,
            clients: self.clients.load(Ordering::Relaxed),
        }
    }
    pub fn latest_frames(&self) -> Arc<LatestFrames> {
        Arc::clone(&self.latest)
    }
    // -----------------------------------------------------------------------
    // 每 200ms 推进一次
    // -----------------------------------------------------------------------
    /// 推进帧率窗口与槽位分配。
    pub fn tick(&self) {
        let online: Vec<u32> = self.discovery.online_cameras().iter().map(|c| c.id).collect();
        let online_set: HashSet<u32> = online.iter().copied().collect();
        {
            let mut fps = self.fps.lock().expect("fps mutex poisoned");
            let now = Instant::now();
            // 掉线的摄像头把窗口丢掉。留着的话，它回来时累计帧数已经涨了一大截，下一
            // 次结算会报出一个几百 fps 的假数字。
            fps.retain(|id, _| online_set.contains(id));
            for id in &online {
                let stats = self.discovery.stats(*id);
                fps.entry(*id)
                    .or_insert_with(|| FpsWindow::seeded(DEFAULT_WINDOW, now, stats.frames_shown))
                    .observe(stats.frames_shown, now);
            }
        }
        let config = self.config();
        let mut slots = self.slots.lock().expect("slots mutex poisoned");
        match config.role {
            Role::Referee => {
                if config.referee.manual_slots {
                    // 手动：以配置为准。现场有烧错固件的板子时，人需要能压过自动分配。
                    slots.force(0, config.referee.slot_a);
                    slots.force(1, config.referee.slot_b);
                } else {
                    slots.assign(&online);
                }
            }
            // 用户端只有一个"槽位"：它绑定的那一块。
            Role::Team => {
                slots.force(0, config.camera_id);
                slots.force(1, None);
            }
        }
    }
    fn diagnostics(&self) -> bool {
        self.config().role == Role::Referee || TEAM_DIAGNOSTICS
    }
    /// 某块摄像头的帧率（用于录制时告诉 ffmpeg 输入帧率）。
    pub fn fps_of(&self, camera: u32) -> Option<f32> {
        let fps = self.fps.lock().expect("fps mutex poisoned");
        let window = fps.get(&camera)?;
        if window.has_reading() {
            Some(window.fps())
        } else {
            None
        }
    }
    // -----------------------------------------------------------------------
    // 快照
    // -----------------------------------------------------------------------
    pub fn snapshot(&self) -> Snapshot {
        let config = self.config();
        let diagnostics = self.diagnostics();
        let cameras: Vec<CameraDto> = self
            .discovery
            .cameras()
            .iter()
            .map(CameraDto::from)
            .collect();
        let stats: Vec<CameraStatsDto> = self
            .discovery
            .cameras()
            .iter()
            .map(|camera| {
                let stats = self.discovery.stats(camera.id);
                let fps = self.fps_of(camera.id).unwrap_or(0.0);
                CameraStatsDto::build(diagnostics, camera.id, camera.is_online(), &stats, fps)
            })
            .collect();
        let armor_boards: Vec<ArmorBoardDto> =
            self.armor.boards().iter().map(ArmorBoardDto::from).collect();
        let slots = self.slots.lock().expect("slots mutex poisoned").slots();
        // 两边都给：用户端的画面右上角要显示对手的血量，裁判端本来就要双方。
        //
        // 顺序固定为队伍号 0、1，界面按 `team` 取那一格——**不靠数组下标**判断"哪个是我"，
        // 因为下标在"用户端绑的是队伍二"时就不再等于自己的队伍号了。
        let mut health = vec![self.health_for(0), self.health_for(1)];
        // 胜负是**两边合起来**才能算出来的东西，所以在这里补一步。
        resolve_outcomes(&mut health);
        Snapshot {
            role: config.role,
            team: config.team,
            mirrored: config.mirror,
            demo: self.demo,
            diagnostics,
            unlocked: self.is_unlocked(),
            discovery_open: self.discovery_open.load(Ordering::Relaxed),
            uptime_ms: self.started.elapsed().as_millis() as u64,
            clients: self.clients.load(Ordering::Relaxed),
            config: ConfigView::from(&config),
            cameras,
            armor_boards,
            stats,
            slots: SlotsDto {
                camera_a: slots[0],
                camera_b: slots[1],
                armor_a: self.assigned_armor(&config, 0),
                armor_b: self.assigned_armor(&config, 1),
                manual: config.referee.manual_slots,
            },
            health,
            recordings: self.recordings.active(),
            notes: self.notes.lock().expect("notes mutex poisoned").clone(),
        }
    }
    /// 一边的装甲板主板：手动指定优先，否则按板子自报的 `team` 自动找。
    ///
    /// 槽位指定只有**裁判端**有：`referee.armor_a/b` 是裁判端界面上的"左格/右格"，用户端
    /// 拿它当自己的板子会让绑定被一份不相干的配置盖掉。
    fn assigned_armor(&self, config: &Config, team: u8) -> Option<u32> {
        let explicit = if config.role == Role::Referee {
            if team == 0 {
                config.referee.armor_a
            } else {
                config.referee.armor_b
            }
        } else {
            None
        };
        if config.role == Role::Referee && config.referee.manual_slots {
            return explicit;
        }
        explicit.or_else(|| {
            self.armor
                .boards()
                .iter()
                .find(|board| board.team == team && board.is_online())
                .map(|board| board.id)
        })
    }
    /// 一边的血量。
    ///
    /// 顺序是有意的：先看绑定的那块板子，再看"这一边有没有人报血量"。绑定了却在掉线
    /// 状态时要显示**未接入**而不是拿别人的数据顶上——现场会以为对手还有血。
    ///
    /// # 对手那一块绝不能用 `armor_id`
    ///
    /// `armor_id` 是**我自己**绑定的主板。拿它去填对手那一格，右上角显示的就是自己的血——
    /// 比不显示更糟：现场会照着一个假的对手血量做决策。
    fn health_for(&self, team: u8) -> TeamHealthDto {
        let config = self.config();
        let low = config.hud.health.low_threshold;
        let own = config.role == Role::Team && team == config.team;
        let bound = if own { config.armor_id } else { None };
        let board = bound.or_else(|| self.assigned_armor(&config, team));
        if let Some(board) = board {
            return match self.armor.health_of_board(board) {
                Some(hp) => TeamHealthDto::present(team, Some(board), [hp; 4], low, &config.team_names),
                None => TeamHealthDto::absent(team, Some(board), &config.team_names),
            };
        }
        match self.armor.health(team) {
            Some(hps) => TeamHealthDto::present(team, None, hps, low, &config.team_names),
            None => TeamHealthDto::absent(team, None, &config.team_names),
        }
    }
 }
 /// 演示模式下合成的板子 id。
 ///
 /// 取成合法十六进制、又不与真实 MAC 派生值相像的形状：截图里一眼能看出这是演示。
 pub const DEMO_CAMERA_A: u32 = 0x0DE0_0001;
 pub const DEMO_CAMERA_B: u32 = 0x0DE0_0002;
 pub const DEMO_ARMOR_A: u32 = 0x0A20_0001;
 pub const DEMO_ARMOR_B: u32 = 0x0A20_0002;
@@ -0,0 +1,53 @@
 {
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "cam-desktop",
  "version": "0.1.0",
  "identifier": "org.camdesktop.client",
  "build": {
    "beforeDevCommand": "pnpm dev",
    "devUrl": "http://127.0.0.1:1420",
    "beforeBuildCommand": "pnpm build",
    "frontendDist": "../dist"
  },
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "cam-desktop",
        "width": 1440,
        "height": 900,
        "minWidth": 900,
        "minHeight": 600,
        "maximized": true,
        "resizable": true,
        "fullscreen": false
      }
    ],
    "security": {
      "csp": "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob: asset: http://asset.localhost; media-src 'self' asset: http://asset.localhost blob:; connect-src 'self' ipc: http://ipc.localhost ws://127.0.0.1:*; object-src 'none'; base-uri 'self'; form-action 'none'",
      "assetProtocol": {
        "enable": true,
        "scope": [
          "$HOME/Movies/cam-desktop/**",
          "$HOME/Videos/cam-desktop/**",
          "$APPDATA/**",
          "$TEMP/**"
        ]
      }
    }
  },
  "bundle": {
    "active": true,
    "targets": ["app", "dmg"],
    "category": "Utility",
    "shortDescription": "ESP32 图传与装甲板桌面端",
    "longDescription": "用户端：一路画面 + 血条与瞄准器。裁判端：两路画面 + 双方血量 + 装甲板发现列表 + 截图与录制。",
    "icon": [
      "icons/32x32.png",
      "icons/128x128.png",
      "icons/128x128@2x.png",
      "icons/icon.icns",
      "icons/icon.ico"
    ]
  }
 }
@@ -0,0 +1,299 @@
 /**
 * 应用外壳：连通道、拿状态、按身份分流、管住解锁流程。
 *
 * # 状态来自哪里
 *
 * 后端每 200 ms 推一份完整快照，前端不轮询。唯一在本地维护的是 **HUD 草稿**：滑杆要即时
 * 反馈，等 300 ms 的后端往返会很黏手。草稿改动后节流保存，保存的结果就是后端的配置。
 *
 * # 解锁流程
 *
 * 需要密码的动作有三处入口：打开设置面板、点关闭窗口（后端会推 `confirmQuit`）、以及
 * 任何一次被后端拒绝的改动。三条路径都汇到同一个 `UnlockDialog`，解锁成功后执行挂起的
 * 那个动作。后端才是真正的闸门，这里只负责把话说清楚。
 */
 import { useCallback, useEffect, useRef, useState } from "react";
 import { SettingsPanel } from "./components/SettingsPanel";
 import { SetupPassword, RolePicker } from "./components/Gate";
 import { Toast } from "./components/TopBar";
 import { UnlockDialog } from "./components/UnlockDialog";
 import { api } from "./lib/ipc";
 import { startStream, streamClient, useAppStore } from "./lib/store";
 import type { ConfigView, HudView, Snapshot } from "./lib/types";
 import { RefereePage } from "./pages/RefereePage";
 import { TeamPage } from "./pages/TeamPage";
 /** 解锁之后要做的那件事。 */
 type Pending = { kind: "settings" } | { kind: "quit" } | { kind: "retry"; run: () => void };
 export default function App() {
  const { snapshot, connected, confirmQuit } = useAppStore();
  const [url, setUrl] = useState<string | null>(null);
  const [fatal, setFatal] = useState<string | null>(null);
  const [hud, setHud] = useState<HudView | null>(null);
  const [drawer, setDrawer] = useState(false);
  const [calibrating, setCalibrating] = useState(false);
  const [unlockReason, setUnlockReason] = useState<string | null>(null);
  const [pending, setPending] = useState<Pending | null>(null);
  const [error, setError] = useState<string | null>(null);
  const [info, setInfo] = useState<string | null>(null);
  const hudInitialised = useRef(false);
  // ---- 通道 ----
  useEffect(() => {
    void api.streamInfo().then(
      (stream) => setUrl(stream.url),
      (err) => setFatal(err instanceof Error ? err.message : String(err)),
    );
  }, []);
  useEffect(() => {
    if (!url) return;
    const client = startStream(url);
    return () => client.close();
  }, [url]);
  // ---- HUD 草稿 ----
  useEffect(() => {
    if (!snapshot || hudInitialised.current) return;
    hudInitialised.current = true;
    setHud(snapshot.config.hud);
  }, [snapshot]);
  const onConfig = useCallback((config: ConfigView) => {
    // 绑定/身份改了：HUD 之外的东西都由快照带回来，这里只需要让 HUD 跟上（例如换了身份）。
    setHud((current) => current ?? config.hud);
  }, []);
  /** 校准时拖动画面：偏移是按比例的，直接累加。 */
  const onCalibrate = useCallback(
    (dx: number, dy: number) => {
      setHud((current) => {
        if (!current) return current;
        const clamp = (value: number) => Math.max(-0.5, Math.min(0.5, value));
        const next: HudView = {
          ...current,
          crosshair: {
            ...current.crosshair,
            offsetX: clamp(current.crosshair.offsetX + dx),
            offsetY: clamp(current.crosshair.offsetY + dy),
          },
        };
        return next;
      });
    },
    [],
  );
  // 校准改动也要落盘。和设置面板里的滑杆共用同一条节流路径。
  useEffect(() => {
    if (!hud || !calibrating) return;
    const timer = window.setTimeout(() => {
      void api.saveHud(hud).catch(() => undefined);
    }, 600);
    return () => window.clearTimeout(timer);
  }, [hud, calibrating]);
  // ---- 解锁 ----
  const needsUnlock = useCallback(
    (reason: string, next: Pending) => {
      setUnlockReason(reason);
      setPending(next);
    },
    [],
  );
  const openSettings = useCallback(() => {
    if (!snapshot) return;
    if (snapshot.role !== "referee" && !snapshot.unlocked) {
      needsUnlock("改摄像头/装甲板绑定、切换队伍号都要密码。", { kind: "settings" });
      return;
    }
    setDrawer(true);
  }, [snapshot, needsUnlock]);
  // 后端拦下了一次"关窗口/退出"。
  useEffect(() => {
    if (confirmQuit === 0) return;
    needsUnlock("退出程序需要密码。", { kind: "quit" });
  }, [confirmQuit, needsUnlock]);
  const finishUnlock = useCallback(() => {
    setUnlockReason(null);
    const action = pending;
    setPending(null);
    switch (action?.kind) {
      case "settings":
        setDrawer(true);
        break;
      case "quit":
        void api.quit().catch((err) =>
          setError(err instanceof Error ? err.message : String(err)),
        );
        break;
      case "retry":
        action.run();
        break;
      default:
        break;
    }
    void api.refresh();
  }, [pending]);
  // ---- 窗口标题 ----
  useEffect(() => {
    if (!snapshot) return;
    const suffix =
      snapshot.role === "team" ? "用户端" : "裁判端";
    const extra = snapshot.demo ? "（演示模式）" : "";
    void import("@tauri-apps/api/window")
      .then(({ getCurrentWindow }) => getCurrentWindow().setTitle(`cam-desktop — ${suffix}${extra}`))
      .catch(() => undefined);
  }, [snapshot?.role, snapshot?.demo]);
  // ---- 分支 ----
  if (fatal) {
    return (
      <div className="gate">
        <h1 className="gate__title">起不来</h1>
        <p className="gate__error">{fatal}</p>
        <p className="gate__note">
          端口可能被另一个客户端占着（旧的 Slint 版或另一份本程序）。关掉那一份再试。
        </p>
      </div>
    );
  }
  if (!snapshot) {
    return (
      <div className="gate">
        <h1 className="gate__title">cam-desktop</h1>
        <p className="gate__hint">
          {connected ? "正在等待后端的第一份状态…" : "正在连接后端…"}
        </p>
      </div>
    );
  }
  if (!snapshot.config.roleChosen) {
    return <RolePicker />;
  }
  if (snapshot.role === "team" && !snapshot.config.passwordSet) {
    return <SetupPassword />;
  }
  return (
    <div className="app">
      {snapshot.role === "team" ? (
        <TeamPage
          snapshot={snapshot}
          hud={hud ?? snapshot.config.hud}
          onOpenSettings={openSettings}
          calibrating={calibrating}
          onCalibrate={onCalibrate}
        />
      ) : (
        <RefereePage
          snapshot={snapshot}
          hud={hud ?? snapshot.config.hud}
          onOpenSettings={openSettings}
          onError={setError}
          onInfo={setInfo}
        />
      )}
      {drawer && (
        <SettingsPanel
          snapshot={snapshot}
          hud={hud ?? snapshot.config.hud}
          onHud={setHud}
          calibrating={calibrating}
          onCalibrating={(active) => {
            setCalibrating(active);
            if (active) setDrawer(false);
          }}
          onClose={() => {
            setCalibrating(false);
            setDrawer(false);
          }}
          onNeedsUnlock={(reason) => needsUnlock(reason, { kind: "settings" })}
          onError={setError}
          onInfo={setInfo}
          onConfig={onConfig}
        />
      )}
      {unlockReason && (
        <UnlockDialog
          reason={unlockReason}
          onUnlocked={finishUnlock}
          onCancel={() => {
            setUnlockReason(null);
            setPending(null);
          }}
        />
      )}
      {error && <Toast kind="error" message={error} onClose={() => setError(null)} />}
      {info && !error && <Toast kind="info" message={info} onClose={() => setInfo(null)} />}
      {/* 校准提示：视频区域在页面里，离开设置面板之后还能看到它。 */}
      {calibrating && (
        <div className="calibrate-banner">
          校准中：拖动画面挪动瞄准点，调好后回到设置里关掉这个开关。
          <button onClick={() => setCalibrating(false)}>结束校准</button>
        </div>
      )}
      <ChannelWatchdog snapshot={snapshot} />
    </div>
  );
 }
 /**
 * 通道看门狗：后端在推、前端没连上时给一句明确的话。
 *
 * 这一条存在的理由很实际：画面不动时，第一件要分清的事是"后端没推"还是"前端没接上"。
 * 后端快照里有 `clients`，所以这两件事可以分开说。
 */
 function ChannelWatchdog({ snapshot }: { snapshot: Snapshot }) {
  const { connected } = useAppStore();
  if (connected) return null;
  let detail = "正在重连后端的视频通道…";
  try {
    detail += `（已收到 ${streamClient().counters.frames} 帧，重连 ${streamClient().counters.reconnects} 次）`;
  } catch {
    // 通道还没建起来。
  }
  if (snapshot.clients === 0 && snapshot.uptimeMs > 5000) {
    detail += " 后端报告没有任何界面连着，这一条是前端侧的问题。";
  }
  return <div className="channel-warning">{detail}</div>;
 }
@@ -0,0 +1,115 @@
 /**
 * 裁判端的装甲板发现列表。
 *
 * 场上到底连上了几块板子、分别自报哪一队、现在多少血、多久没广播了——现场"裁判端没显示
 * 血量"时，这一张表就是第一眼看的地方：它能区分"板子根本没上线"、"上线了但队伍号烧反了"
 * 和"只有一条上报在发"。
 */
 import { elapsed, teamColor, teamName } from "../lib/format";
 import type { ArmorBoardDto, SlotsDto } from "../lib/types";
 interface Props {
  boards: ArmorBoardDto[];
  slots: SlotsDto;
  /** 两边显示的名字（裁判端可改）。缺省时回落到「队伍一 / 队伍二」。 */
  names?: [string, string];
 }
 export function ArmorTable({ boards, slots, names }: Props) {
  return (
    <div className="armor-table">
      <div className="armor-table__head">
        <span>装甲板</span>
        <span>地址</span>
        <span>自报队伍</span>
        <span>血量</span>
        <span>四条</span>
        <span>静默</span>
        <span>槽位</span>
      </div>
      {boards.length === 0 && (
        <div className="armor-table__empty">
          还没有收到任何装甲板上报。主板每 200 ms 广播一次，确认它已上电、和这台机器在同一个
          网络里。
        </div>
      )}
      {boards.map((board) => {
        const assigned =
          slots.armorA === board.id
            ? `左（${teamName(0, names)}）`
            : slots.armorB === board.id
              ? `右（${teamName(1, names)}）`
              : "—";
        return (
          <div
            key={board.id}
            className={`armor-table__row${board.online ? "" : " armor-table__row--offline"}`}
          >
            <span className="mono">{board.idText}</span>
            <span className="mono dim">{board.addr}</span>
            <span style={{ color: teamColor(board.team) }}>{teamName(board.team, names)}</span>
            <span className={`mono${board.hp === 0 ? " danger" : ""}`}>{board.hp}</span>
            <span className={board.reportsAllPlates ? "dim" : "warn"}>
              {board.platesSeen}/4
              {!board.reportsAllPlates && " ⚠"}
            </span>
            <span className="dim">{board.online ? `${elapsed(board.silenceMs)}前` : "离线"}</span>
            <span className="dim">{assigned}</span>
          </div>
        );
      })}
    </div>
  );
 }
 /** 一行只读读数，裁判端每格下面用。 */
 export function StatsLine({
  stats,
  diagnostics,
 }: {
  stats:
    | {
        status: string;
        online: boolean;
        hasFrames: boolean;
        fps: number;
        width: number;
        height: number;
        framesShown: number;
        framesDropped: number;
        lossPercent: number;
        datagrams: number;
        lastFrameBytes: number;
        gapMs: number | null;
      }
    | undefined;
  diagnostics: boolean;
 }) {
  if (!stats) {
    return <div className="stats-line stats-line--empty">还没有这一路的数据</div>;
  }
  const parts: string[] = [];
  if (diagnostics) {
    if (stats.hasFrames) {
      parts.push(`${stats.fps.toFixed(1)} fps`);
      parts.push(`${stats.width}×${stats.height}`);
      parts.push(`${(stats.lastFrameBytes / 1024).toFixed(1)} kB/帧`);
      parts.push(`丢 ${stats.framesDropped}（${stats.lossPercent.toFixed(1)}%）`);
    }
  }
  return (
    <div className="stats-line">
      <span className={stats.online ? "stats-line__status" : "stats-line__status warn"}>
        {stats.status}
      </span>
      {parts.length > 0 && <span className="dim">{parts.join(" · ")}</span>}
    </div>
  );
 }
@@ -0,0 +1,136 @@
 /**
 * 首次启动的两道门：先选身份，再设密码。
 *
 * 身份必须问一次，因为 `role` 的默认值（裁判端）既可能是人选了裁判端，也可能只是还没人
 * 碰过这个文件——后者让用户端的人第一次打开会直接进裁判端，然后以为这个程序只有那一种
 * 界面。所以后端单独记了一个 `roleChosen`。
 */
 import { useEffect, useRef, useState } from "react";
 import { api } from "../lib/ipc";
 import { pushNote } from "../lib/store";
 import type { Role } from "../lib/types";
 export function RolePicker() {
  const [busy, setBusy] = useState<Role | null>(null);
  const [error, setError] = useState<string | null>(null);
  const choose = async (role: Role) => {
    setBusy(role);
    setError(null);
    try {
      await api.setRole(role);
      await api.refresh();
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    } finally {
      setBusy(null);
    }
  };
  return (
    <div className="gate">
      <h1 className="gate__title">这台机器是哪一端？</h1>
      <p className="gate__hint">选定之后记进配置，下次启动直接进这一端。之后可以在设置里改。</p>
      <div className="gate__choices">
        <button className="choice" disabled={busy !== null} onClick={() => void choose("team")}>
          <span className="choice__name">用户端</span>
          <span className="choice__desc">
            一路画面 + 血条 + 瞄准器。需要绑定一块图传板与一块装甲板，绑定改动要密码。
          </span>
          {busy === "team" && <span className="choice__busy">正在切换…</span>}
        </button>
        <button className="choice" disabled={busy !== null} onClick={() => void choose("referee")}>
          <span className="choice__name">裁判端</span>
          <span className="choice__desc">
            两路画面 + 双方血量 + 装甲板发现列表 + 截图与录制。不需要绑定，也不需要密码。
          </span>
          {busy === "referee" && <span className="choice__busy">正在切换…</span>}
        </button>
      </div>
      {error && <p className="gate__error">{error}</p>}
    </div>
  );
 }
 export function SetupPassword() {
  const [first, setFirst] = useState("");
  const [again, setAgain] = useState("");
  const [error, setError] = useState<string | null>(null);
  const [busy, setBusy] = useState(false);
  const input = useRef<HTMLInputElement | null>(null);
  useEffect(() => {
    input.current?.focus();
  }, []);
  const submit = async () => {
    if (busy) return;
    if (first !== again) {
      setError("两次输入不一致");
      setAgain("");
      return;
    }
    setBusy(true);
    setError(null);
    try {
      await api.setPassword(first);
      await api.refresh();
      pushNote("密码已设置。改摄像头/装甲板绑定、切换队伍号、退出都需要它。");
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    } finally {
      setBusy(false);
    }
  };
  return (
    <div className="gate">
      <h1 className="gate__title">先设一个密码</h1>
      <p className="gate__hint">
        用户端改摄像头与装甲板绑定、切换队伍号、退出都要用它。至少 4 位，本机存的是
        Argon2id 哈希，不是明文。
      </p>
      <div className="gate__form">
        <input
          ref={input}
          className="input"
          type="password"
          placeholder="密码"
          autoComplete="new-password"
          value={first}
          onChange={(event) => setFirst(event.target.value)}
        />
        <input
          className="input"
          type="password"
          placeholder="再输一次"
          autoComplete="new-password"
          value={again}
          onChange={(event) => setAgain(event.target.value)}
          onKeyDown={(event) => {
            if (event.key === "Enter") void submit();
          }}
        />
        {error && <p className="gate__error">{error}</p>}
        <button className="button button--primary" onClick={() => void submit()} disabled={busy}>
          {busy ? "保存中…" : "设置密码并继续"}
        </button>
      </div>
      <p className="gate__note">
        忘了密码的处理：删掉配置文件里的 password 一行，或者删掉整个配置文件。旧客户端
        （Slint 版）的配置会在首次启动时自动导入并备份成 .bak。
      </p>
    </div>
  );
 }
@@ -0,0 +1,161 @@
 /**
 * 画面角上的分段血条（平行四边形，一条分 5 格）。
 *
 * # 为什么改到角上、改成斜的
 *
 * 原来它在画面**下面**一条窄带里。改成画面左上角/右上角之后：
 *
 * - 画面不再是"被一条横带压住的一块"，整块视频区域给到取景；
 * - 两边各占一角，**同时**看到自己与对手的血量，视线不用离开画面；
 * - 斜切的形状不会在第一时间被误认成字幕条或进度条，扫一眼就知道是血量。
 *
 * 左上角给自己、右上角给对手（见 `TeamPage`）。裁判端两格各自一个角，与用户端同一套
 * 视觉语言。
 *
 * # 一条分 5 格 = 一格 20 点
 *
 * 整条是一条，里面分成 **5 格**：格子少而大，隔着几米扫一眼就能数出"还剩三格"，
 * 比读一条连续的长度或一个百分比快。血量归零就是 0 格，那时图传中央会给出胜负。
 *
 * 血少了，亮着的格子从**中心那一侧**开始灭（左条从右往左灭，右条从左往右灭），所以两条
 * 血一起减少时，视觉上是往两侧退——不会看成"条变长了"。
 *
 * # 未接入时不显示 0
 *
 * `available` 为 false 时显示占位说明而不是 0：0 是一个看起来像真值的假值，现场看到 0
 * 会以为对方已经没血了，然后开始找裁判理论。这一条在旧客户端上是踩过坑的。
 */
 import { useEffect, useState } from "react";
 import { teamColor, withAlpha } from "../lib/format";
 import type { HealthConfig, TeamHealthDto } from "../lib/types";
 interface Props {
  health: TeamHealthDto;
  config: HealthConfig;
  /** 挂在画面哪一角。`right` 会把条整个镜像过来（含缺血的退向）。 */
  align: "left" | "right";
  /** 这一格是谁：用户端用「我方 / 对手」把两条同色的血区分开。 */
  tag?: string;
 }
 /** 整条分成几格。 */
 const CELLS = 5;
 /** 一格多少血。整车一条血 100 点。 */
 const CELL_HP = 100 / CELLS;
 /** 脉动的周期。与 CSS 动画保持一致。 */
 const PULSE_MS = 900;
 interface Cell {
  /** 这一格是不是亮着（这一格的血还在）。 */
  on: boolean;
  /** 落在低血阈值以内：这是"危险区"，即使还亮着也提前给个警示色。 */
  danger: boolean;
 }
 export function HealthBar({ health, config, align, tag }: Props) {
  const [pulseOn, setPulseOn] = useState(true);
  // 低血脉动：只有真的低血时才起定时器，否则一个空转的 setInterval 会让整个界面
  // 每秒重渲染一次。
  const pulsing = config.pulse && health.available && health.critical;
  useEffect(() => {
    if (!pulsing) {
      setPulseOn(true);
      return;
    }
    const timer = window.setInterval(() => setPulseOn((on) => !on), PULSE_MS / 2);
    return () => window.clearInterval(timer);
  }, [pulsing]);
  const color = health.critical ? "#ff5f5f" : teamColor(health.team);
  const hp = health.available ? Math.max(0, Math.min(100, health.hp ?? 0)) : 0;
  // 向上取整：还剩 1 点血的时候必须还剩一格亮着。向下取整会让"还有 10 点血"显示成空条，
  // 而那正是最需要它准确的时候。
  const lit = Math.ceil(hp / CELL_HP);
  const dangerCells =
    config.lowThreshold > 0 && config.lowThreshold < 100
      ? Math.ceil(config.lowThreshold / CELL_HP)
      : 0;
  // 逻辑顺序：0 号格是"满血时最靠外的那一格"。
  //
  // **不要在这里按 `align` 反转数组**：右角那条的翻转让 CSS 的 `scaleX(-1)` 做
  // （`segbars--right .segbars__track`），两边都做等于翻两次、又翻回来了——表现是右条
  // 从外侧开始灭，与左条相反。
  const cells: Cell[] = Array.from({ length: CELLS }, (_, index) => ({
    on: index < lit,
    danger: index >= CELLS - dangerCells,
  }));
  // 宽度按配置收窄。它挂在画面角上，太宽会盖住画面本身。
  const width = `${Math.round(config.width * 100)}%`;
  return (
    <div
      className={`segbars segbars--${align}`}
      style={{ width }}
      title={health.available ? undefined : health.placeholder}
    >
      <div className="segbars__labels">
        {tag && <span className="segbars__tag">{tag}</span>}
        {config.showTeamName && (
          <span className="segbars__team" style={{ color }}>
            {health.name}
          </span>
        )}
        {health.available ? (
          config.showNumbers && (
            <span className="segbars__value" style={{ color }}>
              {hp}
            </span>
          )
        ) : (
          <span className="segbars__missing">装甲板未接入</span>
        )}
      </div>
      <div
        className="segbars__track"
        style={{ opacity: pulsing && !pulseOn ? 0.35 : 1 }}
        aria-hidden="true"
      >
        {cells.map((cell, index) => (
          <span
            key={index}
            className={[
              "segbars__cell",
              cell.on ? "segbars__cell--on" : "",
              cell.danger ? "segbars__cell--danger" : "",
            ]
              .filter(Boolean)
              .join(" ")}
            style={
              cell.on
                ? {
                    background: color,
                    boxShadow: `0 0 8px ${withAlpha(color, 0.45)}`,
                  }
                : undefined
            }
          />
        ))}
      </div>
    </div>
  );
 }
 /**
 * 这一格是谁。
 *
 * 用户端两条血分别属于两边，而形状是对称的——没有这个标签，"左边这条是我的"要靠位置猜。
 */
 export function healthTag(health: TeamHealthDto, myTeam: number): string {
  return health.team === myTeam ? "我方" : "对手";
 }
@@ -0,0 +1,41 @@
 /**
 * 命中反馈的整屏层：闪红 + 顶部一条文字。
 *
 * # 大号数字刻意不放在画面正中
 *
 * 第一版把 `-7 / 100 → 93` 放在正中，结果它正好压在瞄准点上——被打中的那一下恰恰是最
 * 需要看着准星的时候。现在数字由 `VideoSurface` 画在**准星旁边**（跟着瞄准点走，不挡
 * 目标），这里只留闪红与顶部一条信息。
 *
 * `key={hit.seq}` 是让 CSS 动画每次都从头开始的关键：同一个元素上换属性不会重启动画，
 * 于是第二下命中就再也闪不出来了——一个"第一次有效"的 bug。
 */
 import type { HitPulseRecord } from "../lib/store";
 import type { HitFeedbackConfig } from "../lib/types";
 interface Props {
  hit: HitPulseRecord | null;
  config: HitFeedbackConfig;
  /** 这一下是不是打在我这一边（裁判端两边都显示，但只有相关那一路闪）。 */
  relevant: boolean;
  label?: string;
 }
 export function HitFlash({ hit, config, relevant, label }: Props) {
  if (!hit || !relevant || !config.flash) return null;
  const strength = Math.min(0.55, 0.16 * config.intensity);
  return (
    <div key={hit.seq} className="hit-flash" style={{ ["--flash" as string]: strength }}>
      <div className="hit-flash__banner">
        {label && <span className="hit-flash__label">{label}</span>}
        <span className="hit-flash__value">-{hit.damage}</span>
        <span className="hit-flash__sub">
          {hit.from} → {hit.to}
        </span>
      </div>
    </div>
  );
 }
@@ -0,0 +1,56 @@
 /**
 * 图传中央的胜负横幅：一边归零之后，画面正中显示「胜利」或「击败」。
 *
 * # 为什么这次放在正中
 *
 * 命中反馈那一套刻意避开正中（伤害数字放在准星旁），因为被打中的那一下恰恰最需要看着
 * 准星。**胜负不是那种信息**：它是一局的结束，此刻不再需要瞄准；反过来说，它是这一屏
 * 上唯一还重要的事，放在角上会让人错过整场比赛的结论。
 *
 * # 它一直显示到血量被重置
 *
 * 不做 3 秒淡出：淡出之后屏幕上就再没有"这局结束了"的痕迹，截图、回放、现场的争议都
 * 无从对照。血量被重置（长按 BOOT / 下一局开始）时它自己消失——那个动作本来就是
 * "这局翻篇了"。
 *
 * 用词是两边各说各的：赢的一边看到「胜利」，输的一边看到「击败」。同时归零显示「平局」，
 * 因为那时候任何一边显示"胜利"都是错的。
 */
 import type { MatchOutcome } from "../lib/types";
 interface Props {
  /** 从这一边看的结论。两边都活着时是 null，什么都不显示。 */
  outcome: MatchOutcome | null;
  /** 我这一边的名字。 */
  mine: string;
  /** 对手的名字。 */
  theirs: string;
 }
 const WORD: Record<MatchOutcome, string> = {
  victory: "胜利",
  defeat: "击败",
  draw: "平局",
 };
 export function MatchBanner({ outcome, mine, theirs }: Props) {
  if (!outcome) return null;
  const caption =
    outcome === "victory"
      ? `击败 ${theirs}`
      : outcome === "defeat"
        ? `被 ${theirs} 击败`
        : "双方装甲板同时归零";
  return (
    <div className={`match-banner match-banner--${outcome}`} role="status">
      <div className="match-banner__card">
        <span className="match-banner__team">{mine}</span>
        <span className="match-banner__word">{WORD[outcome]}</span>
        <span className="match-banner__caption">{caption}</span>
      </div>
    </div>
  );
 }
@@ -0,0 +1,201 @@
 /**
 * 录制、截图与录下来的东西。
 *
 * # 回放为什么可能失败
 *
 * 界面内回放走 Tauri 的资源协议，而那条协议只对 `tauri.conf.json` 里
 * `assetProtocol.scope` 白名单的目录生效。默认录制目录在白名单里；如果现场把输出目录
 * 改到别处，`<video>` 会加载失败——那时退回到"用系统播放器打开"，而不是让人以为文件坏了。
 */
 import { useCallback, useEffect, useState } from "react";
 import { convertFileSrc } from "@tauri-apps/api/core";
 import { api } from "../lib/ipc";
 import { bytes, since } from "../lib/format";
 import type { MediaFileDto, Snapshot } from "../lib/types";
 import { Button } from "./controls";
 interface Props {
  snapshot: Snapshot;
  onError: (message: string) => void;
  onInfo: (message: string) => void;
 }
 export function MediaPanel({ snapshot, onError, onInfo }: Props) {
  const [files, setFiles] = useState<MediaFileDto[]>([]);
  const [playing, setPlaying] = useState<MediaFileDto | null>(null);
  const [playbackFailed, setPlaybackFailed] = useState(false);
  const [busy, setBusy] = useState(false);
  const refresh = useCallback(() => {
    void api.mediaFiles().then(setFiles, () => undefined);
  }, []);
  useEffect(() => {
    refresh();
    // 录制中每 2 秒刷一次列表：刚录完的那一段应该自己出现。
    const timer = window.setInterval(refresh, 2000);
    return () => window.clearInterval(timer);
  }, [refresh]);
  const active = snapshot.recordings.filter((recording) => recording.active);
  const cameras = snapshot.cameras.filter((camera) => camera.online).map((camera) => camera.id);
  const guard = (action: Promise<unknown>) => {
    setBusy(true);
    void action
      .then(() => api.refresh())
      .catch((err) => onError(err instanceof Error ? err.message : String(err)))
      .finally(() => setBusy(false));
  };
  return (
    <div className="media-panel">
      <div className="media-panel__actions">
        <Button
          variant="primary"
          disabled={busy || cameras.length === 0}
          title={cameras.length === 0 ? "还没有在线的摄像头" : undefined}
          onClick={() => {
            guard(api.startRecording(cameras));
            onInfo("开始录制。停止之前请留在这台机器上——退出会先收尾再走。");
          }}
        >
          录制全部在线画面
        </Button>
        <Button
          disabled={busy || active.length === 0}
          onClick={() => {
            guard(api.stopRecording([]));
            refresh();
          }}
        >
          停止全部录制
        </Button>
        {[snapshot.slots.cameraA, snapshot.slots.cameraB]
          .filter((id): id is number => id !== null)
          .map((camera) => (
            <Button
              key={camera}
              variant="ghost"
              disabled={busy}
              onClick={() => {
                guard(api.screenshot(camera));
                onInfo(`已截图 0x${camera.toString(16).toUpperCase().padStart(8, "0")}（存在录制目录的 shots/ 下）。`);
                refresh();
              }}
            >
              截图 {`0x${camera.toString(16).toUpperCase().padStart(8, "0")}`}
            </Button>
          ))}
        <Button
          variant="ghost"
          onClick={() => {
            void api
              .reveal(snapshot.config.recordingDir)
              .catch((err) => onError(err instanceof Error ? err.message : String(err)));
          }}
        >
          打开录制目录
        </Button>
      </div>
      {active.length > 0 && (
        <div className="media-panel__active">
          {active.map((recording) => (
            <div key={recording.camera} className="recording">
              <span className="recording__dot" />
              <span className="mono">{recording.cameraText}</span>
              <span>
                {recording.framesWritten} 帧 · {since(recording.startedMs)} · {recording.inputFps.toFixed(1)} fps
                输入
              </span>
              {recording.framesDropped > 0 && (
                <span className="warn" title="写盘跟不上时丢的帧。丢帧不报出来，回放里少半秒会被当成相机的问题。">
                  丢 {recording.framesDropped} 帧
                </span>
              )}
              {recording.error && <span className="danger">ffmpeg：{recording.error}</span>}
              <Button variant="ghost" onClick={() => { guard(api.stopRecording([recording.camera])); refresh(); }}>
                停止
              </Button>
            </div>
          ))}
        </div>
      )}
      <div className="media-panel__list">
        {files.length === 0 && <p className="dim">录制目录里还没有文件。</p>}
        {files.map((file) => (
          <div key={file.path} className="media-row">
            <span className={`media-row__kind media-row__kind--${file.kind}`}>
              {file.kind === "video" ? "MP4" : "PNG"}
            </span>
            <span className="media-row__name" title={file.path}>
              {file.name}
            </span>
            <span className="dim">{bytes(file.bytes)}</span>
            <Button
              variant="ghost"
              onClick={() => {
                setPlaybackFailed(false);
                setPlaying(file.kind === "video" ? file : null);
                if (file.kind === "image") {
                  void api.openFile(file.path).catch(() => undefined);
                }
              }}
            >
              {file.kind === "video" ? "播放" : "打开"}
            </Button>
            <Button
              variant="ghost"
              onClick={() => {
                void api
                  .reveal(file.path)
                  .catch((err) => onError(err instanceof Error ? err.message : String(err)));
              }}
            >
              在访达里显示
            </Button>
          </div>
        ))}
      </div>
      {playing && (
        <div className="playback">
          <div className="playback__head">
            <span className="mono">{playing.name}</span>
            <Button variant="ghost" onClick={() => setPlaying(null)}>
              关闭
            </Button>
          </div>
          {playbackFailed ? (
            <div className="playback__fallback">
              <p className="warn">
                界面内回放失败——多半是这个目录不在资源协议的白名单里（改成默认的录制目录，或者
                直接看下面这一条）。
              </p>
              <Button variant="primary" onClick={() => void api.openFile(playing.path).catch(() => undefined)}>
                用系统播放器打开
              </Button>
            </div>
          ) : (
            <video
              className="playback__video"
              src={convertFileSrc(playing.path)}
              controls
              autoPlay
              onError={() => setPlaybackFailed(true)}
            />
          )}
        </div>
      )}
    </div>
  );
 }
@@ -0,0 +1,763 @@
 /**
 * 设置抽屉。两端的"改东西"都收在这里，所以密码闸门也只有一个入口。
 *
 * # 打开面板 ≠ 解锁
 *
 * 面板本身由 `App` 在**解锁之后**才挂载，但面板里的每个改动仍然各自过一次后端闸门
 * （`bind_camera` 等都会校验）。所以即使有人把这里改成"不需要密码"，配置也改不动。
 *
 * # 发现列表按需放开
 *
 * 挂载时调 `set_discovery_open(true)`，卸载时关掉。这是用户端唯一会列出别的图传板的
 * 时候——**画面不会**因此进来，接收端那道闸门只管帧，不管发现（见 `cam_core::receiver`）。
 */
 import { useCallback, useEffect, useMemo, useState } from "react";
 import { api } from "../lib/ipc";
 import { teamName } from "../lib/format";
 import type {
  ConfigView,
  CrosshairConfig,
  HudView,
  Snapshot,
 } from "../lib/types";
 import { Button, Field, Section, Select, Slider, Switch } from "./controls";
 interface Props {
  snapshot: Snapshot;
  hud: HudView;
  onHud: (hud: HudView) => void;
  calibrating: boolean;
  onCalibrating: (active: boolean) => void;
  onClose: () => void;
  onNeedsUnlock: (reason: string) => void;
  onError: (message: string) => void;
  onInfo: (message: string) => void;
  /** 配置变了（身份/绑定）。App 用它立刻刷新顶层状态。 */
  onConfig: (config: ConfigView) => void;
 }
 /** HUD 的滑杆每动一下都会触发保存，节流一下，免得写盘几十次。 */
 const SAVE_DEBOUNCE_MS = 350;
 export function SettingsPanel({
  snapshot,
  hud,
  onHud,
  calibrating,
  onCalibrating,
  onClose,
  onNeedsUnlock,
  onError,
  onInfo,
  onConfig,
 }: Props) {
  const config = snapshot.config;
  const locked = !snapshot.unlocked && config.role !== "referee";
  // 打开面板时放开发现列表（后端会校验是否已解锁）。
  useEffect(() => {
    if (locked) return;
    void api.setDiscoveryOpen(true).catch((err) => {
      onNeedsUnlock(err instanceof Error ? err.message : String(err));
    });
    return () => {
      void api.setDiscoveryOpen(false).catch(() => undefined);
    };
  }, [locked, onNeedsUnlock]);
  // HUD 的保存节流。滑杆一停就写。
  const [pending, setPending] = useState<HudView | null>(null);
  useEffect(() => {
    if (!pending) return;
    const timer = window.setTimeout(() => {
      setPending(null);
      void api.saveHud(pending).then(onConfig).catch((err) => {
        onError(err instanceof Error ? err.message : String(err));
      });
    }, SAVE_DEBOUNCE_MS);
    return () => window.clearTimeout(timer);
  }, [pending, onConfig, onError]);
  const update = useCallback(
    (change: (draft: HudView) => void) => {
      const next = structuredClone(hud);
      change(next);
      onHud(next);
      setPending(next);
    },
    [hud, onHud],
  );
  const run = async (action: () => Promise<ConfigView>) => {
    try {
      onConfig(await action());
      await api.refresh();
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      if (message.includes("密码")) {
        onNeedsUnlock(message);
        return;
      }
      onError(message);
    }
  };
  const cameraOptions = useMemo(
    () =>
      snapshot.cameras.map((camera) => ({
        value: camera.id,
        label: camera.idText,
        hint: `${camera.addr} · ${camera.online ? "在线" : "离线"}${
          snapshot.stats.find((s) => s.camera === camera.id)?.hasFrames ? "" : " · 无画面"
        }`,
      })),
    [snapshot.cameras, snapshot.stats],
  );
  const armorOptions = useMemo(
    () =>
      snapshot.armorBoards.map((board) => ({
        value: board.id,
        label: board.idText,
        hint: `${board.addr} · ${teamName(board.team, snapshot.config.teamNames)} · ${board.hp} 血 · ${
          board.online ? "在线" : "离线"
        }`,
      })),
    [snapshot.armorBoards, snapshot.config.teamNames],
  );
  return (
    <aside className="drawer">
      <header className="drawer__head">
        <h2 className="drawer__title">设置</h2>
        <div className="drawer__head-actions">
          {config.role === "team" && (
            <Button
              variant="ghost"
              onClick={() => {
                void api.lock().then(() => {
                  onInfo("已重新上锁。");
                  onClose();
                });
              }}
            >
              上锁
            </Button>
          )}
          <Button variant="ghost" onClick={onClose}>
            关闭
          </Button>
        </div>
      </header>
      {locked && (
        <p className="drawer__locked">
          这个面板的改动需要密码。<button onClick={() => onNeedsUnlock("改动设置需要密码")}>立即解锁</button>
        </p>
      )}
      <div className="drawer__body">
        <Section title="身份">
          <Field label="这台机器是哪一端">
            <Select
              value={config.role}
              options={[
                { value: "team", label: "用户端", hint: "一路画面 + 血条 + 瞄准器" },
                { value: "referee", label: "裁判端", hint: "两路 + 双方血量 + 录制" },
              ]}
              onChange={(role) => void run(() => api.setRole(role))}
            />
          </Field>
          <p className="section__note">
            离开用户端要密码：否则切到裁判端就能看两路画面、也能随便改配置。
          </p>
        </Section>
        {config.role === "team" && (
          <>
            <Section
              title="绑定"
              hint="图传板与装甲板都用 MAC 派生的 id 标识，重启不变，所以绑定是稳的。改动需要密码。"
            >
              <Field label="摄像头（图传板）">
                <Select
                  value={config.cameraId}
                  options={cameraOptions}
                  onChange={(id) => void run(() => api.bindCamera(id))}
                />
              </Field>
              <Field label="装甲板主板" hint="决定血条读谁的血量。下拉里是场上正在广播的板子。">
                <Select
                  value={config.armorId}
                  options={armorOptions}
                  onChange={(id) => void run(() => api.bindArmor(id))}
                />
              </Field>
              <Field
                label="自己属于哪一边"
                hint="改错队号会把对手的血条当成自己的：画面左上角那一条就会是对手的血。"
              >
                <Select
                  value={config.team}
                  options={[
                    { value: 0, label: `${teamName(0, config.teamNames)}（红）` },
                    { value: 1, label: `${teamName(1, config.teamNames)}（蓝）` },
                  ]}
                  onChange={(team) => void run(() => api.setTeam(team))}
                />
              </Field>
              <Switch
                checked={config.mirror}
                label="左右镜像画面（摄像头装反了）"
                onChange={(mirror) => void run(() => api.setMirror(mirror))}
              />
              {cameraOptions.length === 0 && (
                <p className="section__note section__note--warn">
                  现在没有发现任何图传板。板子每 2 秒广播一次，确认它已上电、和这台机器在同一个
                  网络里，然后稍等。
                </p>
              )}
            </Section>
            <Section title="瞄准器" hint="位置跟着画面走，大小不跟着缩放走——放大后准星更精确。">
              <Switch
                checked={hud.crosshair.visible}
                label="显示瞄准器"
                onChange={(visible) =>
                  update((draft) => {
                    draft.crosshair.visible = visible;
                  })
                }
              />
              <Field label="样式">
                <Select
                  value={hud.crosshair.style}
                  options={[
                    { value: "cross", label: "四臂十字" },
                    { value: "cross-dot", label: "十字 + 中心点" },
                    { value: "circle-dot", label: "圆环 + 中心点" },
                    { value: "dot", label: "只有点" },
                  ]}
                  onChange={(style) =>
                    update((draft) => {
                      draft.crosshair.style = style;
                    })
                  }
                />
              </Field>
              <Field label="大小" hint="画面短边的比例">
                <Slider
                  value={hud.crosshair.size}
                  min={0.01}
                  max={0.2}
                  step={0.005}
                  format={(value) => `${(value * 100).toFixed(1)}%`}
                  onChange={(size) =>
                    update((draft) => {
                      draft.crosshair.size = size;
                    })
                  }
                />
              </Field>
              <Field label="线宽">
                <Slider
                  value={hud.crosshair.thickness}
                  min={0.001}
                  max={0.02}
                  step={0.0005}
                  format={(value) => value.toFixed(4)}
                  onChange={(thickness) =>
                    update((draft) => {
                      draft.crosshair.thickness = thickness;
                    })
                  }
                />
              </Field>
              <Field label="中心空隙">
                <Slider
                  value={hud.crosshair.gap}
                  min={0}
                  max={0.1}
                  step={0.002}
                  format={(value) => `${(value * 100).toFixed(1)}%`}
                  onChange={(gap) =>
                    update((draft) => {
                      draft.crosshair.gap = gap;
                    })
                  }
                />
              </Field>
              <Field label="颜色">
                <input
                  className="color"
                  type="color"
                  value={hud.crosshair.color}
                  onChange={(event) =>
                    update((draft) => {
                      draft.crosshair.color = event.target.value;
                    })
                  }
                />
              </Field>
              <Calibration
                crosshair={hud.crosshair}
                calibrating={calibrating}
                onCalibrating={onCalibrating}
                onChange={(offsetX, offsetY) =>
                  update((draft) => {
                    draft.crosshair.offsetX = offsetX;
                    draft.crosshair.offsetY = offsetY;
                  })
                }
              />
            </Section>
            <Section title="叠加与提示">
              <Switch
                checked={hud.grid.visible}
                label="显示网格"
                onChange={(visible) =>
                  update((draft) => {
                    draft.grid.visible = visible;
                  })
                }
              />
              {hud.grid.visible && (
                <>
                  <Field label="网格样式">
                    <Select
                      value={hud.grid.style}
                      options={[
                        { value: "thirds", label: "三分线" },
                        { value: "squares", label: "等分方格" },
                        { value: "cross", label: "中心十字" },
                      ]}
                      onChange={(style) =>
                        update((draft) => {
                          draft.grid.style = style;
                        })
                      }
                    />
                  </Field>
                  {hud.grid.style === "squares" && (
                    <Field label="等分数">
                      <Slider
                        value={hud.grid.divisions}
                        min={2}
                        max={16}
                        step={1}
                        format={(value) => `${value} 格`}
                        onChange={(divisions) =>
                          update((draft) => {
                            draft.grid.divisions = divisions;
                          })
                        }
                      />
                    </Field>
                  )}
                  <Field label="网格明显程度">
                    <Slider
                      value={hud.grid.opacity}
                      min={0.05}
                      max={1}
                      step={0.01}
                      format={(value) => value.toFixed(2)}
                      onChange={(opacity) =>
                        update((draft) => {
                          draft.grid.opacity = opacity;
                        })
                      }
                    />
                  </Field>
                </>
              )}
              <Switch
                checked={hud.showZoom}
                label="显示放大倍率"
                onChange={(showZoom) =>
                  update((draft) => {
                    draft.showZoom = showZoom;
                  })
                }
              />
              <Switch
                checked={hud.hitFeedback.flash}
                label="被打中时闪红"
                onChange={(flash) =>
                  update((draft) => {
                    draft.hitFeedback.flash = flash;
                  })
                }
              />
              <Switch
                checked={hud.hitFeedback.marker}
                label="在瞄点旁显示伤害数字"
                onChange={(marker) =>
                  update((draft) => {
                    draft.hitFeedback.marker = marker;
                  })
                }
              />
              <Field label="闪红强度">
                <Slider
                  value={hud.hitFeedback.intensity}
                  min={0.2}
                  max={2}
                  step={0.1}
                  format={(value) => `${value.toFixed(1)}×`}
                  onChange={(intensity) =>
                    update((draft) => {
                      draft.hitFeedback.intensity = intensity;
                    })
                  }
                />
              </Field>
            </Section>
            <Section
              title="血条"
              hint="条挂在画面两个上角：左上角是自己、右上角是对手。一条分 5 格，一格 20 点血。"
            >
              <Switch
                checked={hud.health.visible}
                label="显示血条"
                onChange={(visible) =>
                  update((draft) => {
                    draft.health.visible = visible;
                  })
                }
              />
              <Switch
                checked={hud.health.showNumbers}
                label="显示血量数字"
                onChange={(showNumbers) =>
                  update((draft) => {
                    draft.health.showNumbers = showNumbers;
                  })
                }
              />
              <Switch
                checked={hud.health.showTeamName}
                label="显示队伍名"
                onChange={(showTeamName) =>
                  update((draft) => {
                    draft.health.showTeamName = showTeamName;
                  })
                }
              />
              <Switch
                checked={hud.health.pulse}
                label="低血时脉动"
                onChange={(pulse) =>
                  update((draft) => {
                    draft.health.pulse = pulse;
                  })
                }
              />
              <Field label="低血阈值">
                <Slider
                  value={hud.health.lowThreshold}
                  min={5}
                  max={100}
                  step={5}
                  format={(value) => `${value} 血`}
                  onChange={(lowThreshold) =>
                    update((draft) => {
                      draft.health.lowThreshold = lowThreshold;
                    })
                  }
                />
              </Field>
              <Field label="血条宽度" hint="占画面宽度的比例">
                <Slider
                  value={hud.health.width}
                  min={0.15}
                  max={0.9}
                  step={0.01}
                  format={(value) => `${(value * 100).toFixed(0)}%`}
                  onChange={(width) =>
                    update((draft) => {
                      draft.health.width = width;
                    })
                  }
                />
              </Field>
            </Section>
          </>
        )}
        {config.role === "referee" && (
          <Section
            title="裁判端槽位"
            hint="默认按装甲板自报的队伍自动分左右。有烧错固件的板子时打开手动指定。"
          >
            <Switch
              checked={snapshot.slots.manual}
              label="手动指定槽位"
              onChange={(manual) =>
                void run(() =>
                  api.setRefereeSlots({
                    cameraA: snapshot.slots.cameraA,
                    cameraB: snapshot.slots.cameraB,
                    armorA: snapshot.slots.armorA,
                    armorB: snapshot.slots.armorB,
                    manual,
                  }),
                )
              }
            />
            {snapshot.slots.manual && (
              <>
                <Field label={`左格：${teamName(0, config.teamNames)}摄像头`}>
                  <Select
                    value={snapshot.slots.cameraA}
                    options={cameraOptions}
                    onChange={(cameraA) =>
                      void run(() =>
                        api.setRefereeSlots({ ...snapshot.slots, cameraA, manual: true }),
                      )
                    }
                  />
                </Field>
                <Field label={`左格：${teamName(0, config.teamNames)}装甲板`}>
                  <Select
                    value={snapshot.slots.armorA}
                    options={armorOptions}
                    onChange={(armorA) =>
                      void run(() =>
                        api.setRefereeSlots({ ...snapshot.slots, armorA, manual: true }),
                      )
                    }
                  />
                </Field>
                <Field label={`右格：${teamName(1, config.teamNames)}摄像头`}>
                  <Select
                    value={snapshot.slots.cameraB}
                    options={cameraOptions}
                    onChange={(cameraB) =>
                      void run(() =>
                        api.setRefereeSlots({ ...snapshot.slots, cameraB, manual: true }),
                      )
                    }
                  />
                </Field>
                <Field label={`右格：${teamName(1, config.teamNames)}装甲板`}>
                  <Select
                    value={snapshot.slots.armorB}
                    options={armorOptions}
                    onChange={(armorB) =>
                      void run(() =>
                        api.setRefereeSlots({ ...snapshot.slots, armorB, manual: true }),
                      )
                    }
                  />
                </Field>
              </>
            )}
          </Section>
        )}
        <Section title="录制与截图" hint="截图存 PNG，录制存 mp4（需要 ffmpeg）。">
          <Field label="输出目录">
            <input
              className="input"
              type="text"
              defaultValue={config.recordingDir}
              onBlur={(event) => {
                const value = event.target.value.trim();
                if (value !== config.recordingDir) {
                  void run(() => api.setRecordingOptions({ dir: value, ffmpeg: null, crf: null, preset: null }));
                }
              }}
            />
          </Field>
          <Field label="ffmpeg 路径" hint="默认从 PATH 找。找不到就录不了，但界面照常用。">
            <input
              className="input"
              type="text"
              defaultValue={config.ffmpeg}
              onBlur={(event) => {
                const value = event.target.value.trim();
                if (value && value !== config.ffmpeg) {
                  void run(() => api.setRecordingOptions({ dir: null, ffmpeg: value, crf: null, preset: null }));
                }
              }}
            />
          </Field>
          <p className="section__note">
            界面内回放要目录在资源协议的白名单里（默认的 ~/Movies/cam-desktop 就在）。
            改到别处时回放会失败，界面上会给出"用系统播放器打开"的退路。
          </p>
        </Section>
        <Section title="安全" hint="密码只挡现场随手改绑；配置文件与程序都在本机，愿意改的人绕得过去。">
          <ChangePassword onDone={onInfo} onError={onError} />
          <div className="row">
            <Button
              variant="danger"
              onClick={() => {
                if (!window.confirm("清空配置？旧文件会被改名成 .bak，然后需要重启程序。")) return;
                void api.clearConfig().then(
                  (message) => onInfo(message),
                  (err) => {
                    const text = err instanceof Error ? err.message : String(err);
                    if (text.includes("密码")) onNeedsUnlock(text);
                    else onError(text);
                  },
                );
              }}
            >
              清空配置
            </Button>
            <Button
              variant="danger"
              onClick={() => {
                if (!window.confirm("退出程序？正在进行的录制会先收尾。")) return;
                void api.quit().catch((err) => {
                  const text = err instanceof Error ? err.message : String(err);
                  if (text.includes("密码")) onNeedsUnlock(text);
                  else onError(text);
                });
              }}
            >
              退出程序
            </Button>
          </div>
        </Section>
      </div>
    </aside>
  );
 }
 /** 瞄准器偏移：拖画面校准 + 数值微调 + 归零。 */
 function Calibration({
  crosshair,
  calibrating,
  onCalibrating,
  onChange,
 }: {
  crosshair: CrosshairConfig;
  calibrating: boolean;
  onCalibrating: (active: boolean) => void;
  onChange: (offsetX: number, offsetY: number) => void;
 }) {
  return (
    <div className="calibration">
      <Switch
        checked={calibrating}
        label="拖动画面校准瞄准点"
        onChange={onCalibrating}
      />
      <p className="section__note">
        摄像头与枪管不同轴时用这里把瞄点挪到弹着点上。偏移存的是<span className="em">画面比例</span>
        ，所以换分辨率、换窗口大小都不影响它。
      </p>
      <Field label="水平偏移" hint={`${(crosshair.offsetX * 100).toFixed(2)}%`}>
        <Slider
          value={crosshair.offsetX}
          min={-0.3}
          max={0.3}
          step={0.001}
          format={(value) => `${(value * 100).toFixed(2)}%`}
          onChange={(value) => onChange(value, crosshair.offsetY)}
        />
      </Field>
      <Field label="垂直偏移" hint={`${(crosshair.offsetY * 100).toFixed(2)}%`}>
        <Slider
          value={crosshair.offsetY}
          min={-0.3}
          max={0.3}
          step={0.001}
          format={(value) => `${(value * 100).toFixed(2)}%`}
          onChange={(value) => onChange(crosshair.offsetX, value)}
        />
      </Field>
      <Button variant="ghost" onClick={() => onChange(0, 0)}>
        偏移归零
      </Button>
    </div>
  );
 }
 /** 改密码。 */
 function ChangePassword({
  onDone,
  onError,
 }: {
  onDone: (message: string) => void;
  onError: (message: string) => void;
 }) {
  const [current, setCurrent] = useState("");
  const [fresh, setFresh] = useState("");
  const [busy, setBusy] = useState(false);
  return (
    <div className="password-change">
      <input
        className="input"
        type="password"
        placeholder="当前密码"
        autoComplete="off"
        value={current}
        onChange={(event) => setCurrent(event.target.value)}
      />
      <input
        className="input"
        type="password"
        placeholder="新密码（≥4 位）"
        autoComplete="new-password"
        value={fresh}
        onChange={(event) => setFresh(event.target.value)}
      />
      <Button
        disabled={busy || fresh.length < 4}
        onClick={() => {
          setBusy(true);
          void api
            .setPassword(fresh, current)
            .then(() => {
              onDone("密码已更新。");
              setCurrent("");
              setFresh("");
            })
            .catch((err) => onError(err instanceof Error ? err.message : String(err)))
            .finally(() => setBusy(false));
        }}
      >
        {busy ? "保存中…" : "修改密码"}
      </Button>
    </div>
  );
 }
@@ -0,0 +1,95 @@
 /**
 * 裁判端就地改队伍名。
 *
 * # 为什么是输入框而不是设置面板里的两项
 *
 * 现场改名字的时机是"比赛开始前，两队报上名来"。那时候裁判盯着的是两格画面，让他在
 * 设置面板的某一节里找到对应项、改完再关掉，是一次没有必要的往返。名字就放在两格画面
 * 各自下面，改完直接看到血条上的名字变了。
 *
 * # 回车/失焦才提交
 *
 * 逐字提交会在每次按键后写一次配置文件（还带一次 Argon2 无关的原子替换），而且中间态
 * （"红"、"红队"）会被后端截断/回落规则改写一次，光标跟着跳。失焦提交是唯一不会跟
 * 打字打架的时机。
 *
 * 超过上限的字数由后端统一截断（`TEAM_NAME_MAX_CHARS`），这里也限一下长度——输入框
 * 里就能看到"打不进去了"，比提交后被悄悄截掉诚实。
 */
 import { useEffect, useRef, useState } from "react";
 import { DEFAULT_TEAM_NAMES } from "../lib/format";
 /** 与 Rust 侧的 `config::TEAM_NAME_MAX_CHARS` 一致。 */
 const MAX_CHARS = 12;
 interface Props {
  team: number;
  /** 当前生效的名字（来自快照，可能已经被后端规范化过）。 */
  name: string;
  /** 提交。后端会规范化，成功之后快照会带新名字回来。 */
  onSave: (name: string) => void;
  disabled?: boolean;
 }
 export function TeamNameEditor({ team, name, onSave, disabled }: Props) {
  const [draft, setDraft] = useState(name);
  const focused = useRef(false);
  /** Esc 已经改回去了，紧接着的那次失焦不该再提交。 */
  const reverted = useRef(false);
  // 焦点不在输入框里时跟着快照走：改完之后后端返回的规范名要能显示出来，而正在打字时
  // 不能被一份恰好到达的快照顶掉。
  useEffect(() => {
    if (!focused.current) setDraft(name);
  }, [name]);
  const commit = () => {
    focused.current = false;
    if (reverted.current) {
      reverted.current = false;
      return;
    }
    if (draft === name) return;
    const trimmed = draft.trim();
    setDraft(trimmed);
    onSave(trimmed);
  };
  return (
    <label className="team-name">
      <span className="team-name__label" style={{ color: team === 0 ? "#ff5f5f" : "#5aa9ff" }}>
        队名
      </span>
      <input
        className="input team-name__input"
        value={draft}
        maxLength={MAX_CHARS}
        disabled={disabled}
        placeholder={DEFAULT_TEAM_NAMES[team] ?? "队伍"}
        title="改完按回车或点到别处生效；留空回落到默认名"
        onChange={(event) => setDraft(event.target.value)}
        onFocus={() => {
          focused.current = true;
        }}
        onBlur={commit}
        onKeyDown={(event) => {
          if (event.key === "Enter") {
            // 只走失焦这一条提交路径，避免回车与失焦各提交一次。
            event.currentTarget.blur();
          } else if (event.key === "Escape") {
            // 注意：不能只 `setDraft(name)` 再 blur——blur 是同一次事件里同步发生的，
            // `commit` 读到的还是这一帧的旧 draft，于是"取消"反而把改动存了下去。
            reverted.current = true;
            setDraft(name);
            event.currentTarget.blur();
          }
        }}
      />
    </label>
  );
 }
@@ -0,0 +1,96 @@
 /**
 * 顶部状态条：身份、连接、演示模式、说明、以及进入设置的入口。
 *
 * 演示模式的标记**必须显眼**：那一整屏画面与血量都是本机合成的，截图或验收时把它当成
 * 真实链路会得出完全错误的结论。
 */
 import type { ReactNode } from "react";
 import { pushNote, useAppStore } from "../lib/store";
 import type { Snapshot } from "../lib/types";
 import { Button } from "./controls";
 interface Props {
  snapshot: Snapshot;
  onOpenSettings: () => void;
  onOpenMedia?: () => void;
  extra?: ReactNode;
 }
 export function TopBar({ snapshot, onOpenSettings, onOpenMedia, extra }: Props) {
  const { connected, notes } = useAppStore();
  return (
    <header className="topbar">
      <div className="topbar__left">
        <span className="topbar__brand">cam-desktop</span>
        <span className={`tag tag--${snapshot.role}`}>
          {snapshot.role === "team" ? "用户端" : "裁判端"}
        </span>
        {snapshot.demo && (
          <button
            className="tag tag--demo tag--button"
            title="所有画面与血量都是本机合成的假数据，不代表场上的任何一块板子。"
            onClick={() =>
              pushNote("演示模式：画面与血量由本机合成，不是真实链路。截图或验收时别把它当成现场数据。")
            }
          >
            演示模式 · 合成画面
          </button>
        )}
        {!connected && <span className="tag tag--warn">通道断开，重连中</span>}
        {snapshot.recordings.length > 0 && (
          <span className="tag tag--recording">
            <span className="recording__dot" /> 录制中 ×{snapshot.recordings.length}
          </span>
        )}
        {extra}
      </div>
      <div className="topbar__right">
        {notes.slice(-1).map((note, index) => (
          <span key={index} className="topbar__note">
            {note}
          </span>
        ))}
        <span className="dim mono" title="连着这个后端的界面数">
          界面 {snapshot.clients}
        </span>
        {onOpenMedia && (
          <Button variant="ghost" onClick={onOpenMedia}>
            录制与回放
          </Button>
        )}
        <Button variant="ghost" onClick={onOpenSettings}>
          设置
        </Button>
      </div>
    </header>
  );
 }
 /** 浮动提示（错误/信息）。 */
 export function Toast({
  message,
  kind,
  onClose,
 }: {
  message: string;
  kind: "info" | "error";
  onClose: () => void;
 }) {
  return (
    <div className={`toast toast--${kind}`} onClick={onClose} role="alert">
      <span>{message}</span>
      <span className="toast__close">✕</span>
    </div>
  );
 }
@@ -0,0 +1,89 @@
 /**
 * 解锁对话框。
 *
 * 它只是**入口**，不是闸门：真正拦住改绑的是后端的 `require_unlocked`。所以这里即使
 * 被人绕过、甚至被改成永远返回成功，配置也改不动。
 */
 import { useEffect, useRef, useState } from "react";
 import { api } from "../lib/ipc";
 interface Props {
  /** 为什么需要密码：显示在标题下。 */
  reason: string;
  onUnlocked: () => void;
  onCancel: () => void;
 }
 export function UnlockDialog({ reason, onUnlocked, onCancel }: Props) {
  const [password, setPassword] = useState("");
  const [error, setError] = useState<string | null>(null);
  const [busy, setBusy] = useState(false);
  const input = useRef<HTMLInputElement | null>(null);
  useEffect(() => {
    input.current?.focus();
  }, []);
  const submit = async () => {
    if (busy) return;
    setBusy(true);
    setError(null);
    try {
      const ok = await api.unlock(password);
      if (ok) {
        onUnlocked();
      } else {
        setError("密码不对");
        setPassword("");
        input.current?.focus();
      }
    } catch (err) {
      setError(err instanceof Error ? err.message : String(err));
    } finally {
      setBusy(false);
    }
  };
  return (
    <div className="overlay" role="dialog" aria-modal="true">
      <div className="dialog">
        <h2 className="dialog__title">需要密码</h2>
        <p className="dialog__hint">{reason}</p>
        <input
          ref={input}
          className="input"
          type="password"
          value={password}
          placeholder="密码"
          autoComplete="off"
          onChange={(event) => setPassword(event.target.value)}
          onKeyDown={(event) => {
            if (event.key === "Enter") void submit();
            if (event.key === "Escape") onCancel();
          }}
        />
        {error && <p className="dialog__error">{error}</p>}
        <p className="dialog__note">
          密码只挡现场随手改绑，不是安全边界：配置文件与程序都在本机，愿意改的人绕得过去。
          忘了密码就删掉配置里的 password 一行。
        </p>
        <div className="dialog__actions">
          <button className="button button--ghost" onClick={onCancel}>
            取消
          </button>
          <button className="button button--primary" onClick={() => void submit()} disabled={busy}>
            {busy ? "校验中…" : "解锁"}
          </button>
        </div>
      </div>
    </div>
  );
 }
@@ -0,0 +1,457 @@
 /**
 * 一路画面：canvas 绘制 + 缩放/平移 + 网格 + 瞄准器 + 命中反馈。
 *
 * # 为什么画在 canvas 上而不是用 CSS 变换 `<img>`
 *
 * 瞄准器必须跟着**画面**走：它标的是相机光轴上的一个点。用 DOM 摆一个 `<img>` 再叠一层
 * `transform` 的话，"图像落在哪、瞄准点落在哪"要算两遍，而两份实现迟早会不一致——表现
 * 是放大之后瞄准器偏了，恰恰发生在这件事最要紧的时候。
 *
 * 所以变换只算一次（`layout()`），图像、网格、瞄准器、伤害数字全都用同一组数画出来。
 *
 * # 尺寸与缩放的关系
 *
 * - 图像按 `contain` 放进窗格，再乘 `zoom`。
 * - **网格**画在图像矩形里，跟着缩放走：它标的是画面里的比例，用来估距离。
 * - **瞄准器**的**位置**跟着图像走，**大小**不跟着：像真瞄具一样，放大之后准星不会
 *   跟着变粗，而是覆盖画面里更小的一块——那正是放大有用武之地的原因。
 * - 镜像靠 `scale(-1, 1)`，同时把拖动方向也翻过来，否则向右拖画面会往左走。
 */
 import { useEffect, useRef, type ReactNode } from "react";
 import { streamClient } from "../lib/store";
 import { withAlpha } from "../lib/format";
 import type { CrosshairConfig, GridConfig, HitFeedbackConfig } from "../lib/types";
 export interface ViewTransform {
  zoom: number;
  x: number;
  y: number;
 }
 export const IDENTITY_VIEW: ViewTransform = { zoom: 1, x: 0, y: 0 };
 /** 缩放上下限。再多只是把像素拉大。 */
 export const MIN_ZOOM = 1;
 export const MAX_ZOOM = 8;
 export const ZOOM_STEP = 1.25;
 export interface HitPulse {
  /** 每次命中都不同，用来重启动画。 */
  seq: number;
  damage: number;
  /** `performance.now()` 时刻。 */
  at: number;
 }
 interface Props {
  camera: number | null;
  emptyText: string;
  mirrored: boolean;
  crosshair: CrosshairConfig | null;
  grid: GridConfig | null;
  view: ViewTransform;
  onView: (view: ViewTransform) => void;
  /** 校准模式：拖动画面来挪瞄准点。 */
  calibrating?: boolean;
  onCalibrate?: (dxFraction: number, dyFraction: number) => void;
  /** 命中脉冲。只有属于这一路的命中才该传进来。 */
  hit?: HitPulse | null;
  hitFeedback: HitFeedbackConfig;
  showZoom: boolean;
  children?: ReactNode;
 }
 export function VideoSurface({
  camera,
  emptyText,
  mirrored,
  crosshair,
  grid,
  view,
  onView,
  calibrating = false,
  onCalibrate,
  hit = null,
  hitFeedback,
  showZoom,
  children,
 }: Props) {
  const canvasRef = useRef<HTMLCanvasElement | null>(null);
  // 绘制循环不随 props 重建，所以最新一份 props 放在 ref 里给它读。
  const props = useRef({ camera, mirrored, crosshair, grid, view, hit, hitFeedback });
  props.current = { camera, mirrored, crosshair, grid, view, hit, hitFeedback };
  const drag = useRef<{ x: number; y: number; originX: number; originY: number } | null>(null);
  const dirty = useRef(true);
  const lastFrameId = useRef<number | null>(null);
  useEffect(() => {
    dirty.current = true;
  }, [camera, mirrored, crosshair, grid, view, hit, hitFeedback]);
  // canvas 的像素尺寸跟着 CSS 尺寸与 DPR 走。不这么做的话在 Retina 上会糊。
  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    const resize = () => {
      const dpr = window.devicePixelRatio || 1;
      const width = Math.max(1, Math.round(canvas.clientWidth * dpr));
      const height = Math.max(1, Math.round(canvas.clientHeight * dpr));
      if (canvas.width !== width || canvas.height !== height) {
        canvas.width = width;
        canvas.height = height;
        dirty.current = true;
      }
    };
    resize();
    const observer = new ResizeObserver(resize);
    observer.observe(canvas);
    return () => observer.disconnect();
  }, []);
  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    let raf = 0;
    const loop = (timestamp: number) => {
      raf = requestAnimationFrame(loop);
      const current = props.current;
      const frame = streamClient().latest(current.camera);
      if (frame && frame.frameId !== lastFrameId.current) {
        lastFrameId.current = frame.frameId;
        dirty.current = true;
      }
      // 命中动画期间必须持续重绘，否则闪红/伤害数字只画了一帧就停住。
      //
      // **抖动没有了**（见 `HitFeedbackConfig::shake` 的文档）：不再有"整幅图跟着晃"的
      // 那一路，所以这里也不再需要因为抖动而复绘。
      const pulseAge = current.hit ? timestamp - current.hit.at : Number.POSITIVE_INFINITY;
      const animating =
        pulseAge < 700 && (current.hitFeedback.marker || current.hitFeedback.flash);
      if (!dirty.current && !animating) return;
      dirty.current = false;
      draw(canvas, current, frame, timestamp);
    };
    raf = requestAnimationFrame(loop);
    return () => cancelAnimationFrame(raf);
  }, []);
  // ---- 输入 ----
  const onWheel = (event: React.WheelEvent<HTMLDivElement>) => {
    const factor = event.deltaY > 0 ? 1 / ZOOM_STEP : ZOOM_STEP;
    const zoom = clamp(view.zoom * factor, MIN_ZOOM, MAX_ZOOM);
    // 缩回 1 时顺便归位：此时画面完整可见，平移没有意义，留着会让下一次放大从偏移位置
    // 开始，看起来像"跳了一下"。
    onView(zoom <= MIN_ZOOM ? IDENTITY_VIEW : { ...view, zoom });
  };
  const onPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
    event.currentTarget.setPointerCapture(event.pointerId);
    drag.current = { x: event.clientX, y: event.clientY, originX: view.x, originY: view.y };
  };
  const onPointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
    const start = drag.current;
    if (!start) return;
    const dx = event.clientX - start.x;
    const dy = event.clientY - start.y;
    if (calibrating) {
      // 校准：把屏幕上的位移换算成画面里的比例位移。用当前显示出来的图像尺寸做分母，
      // 所以放大之后校准更精细——这正是需要的。
      const box = canvasRef.current;
      if (!box || !onCalibrate) return;
      const frame = streamClient().latest(camera);
      if (!frame) return;
      const { drawWidth, drawHeight } = layout(box, frame.width, frame.height, view);
      if (drawWidth <= 0 || drawHeight <= 0) return;
      // 一次移动一小步，然后把起点挪过来。
      drag.current = { ...start, x: event.clientX, y: event.clientY };
      const sign = mirrored ? -1 : 1;
      onCalibrate((sign * dx) / drawWidth, dy / drawHeight);
      return;
    }
    if (view.zoom <= MIN_ZOOM) return;
    // 镜像时把横向拖动也翻过来：否则向右拖，画面往左走，看起来像拖动坏了。
    const sign = mirrored ? -1 : 1;
    onView({ ...view, x: start.originX + sign * dx, y: start.originY + dy });
  };
  const endDrag = () => {
    drag.current = null;
  };
  const cursor = calibrating ? "crosshair" : view.zoom > MIN_ZOOM ? "grab" : "default";
  return (
    <div
      className="video-surface"
      style={{ cursor }}
      onWheel={onWheel}
      onPointerDown={onPointerDown}
      onPointerMove={onPointerMove}
      onPointerUp={endDrag}
      onPointerCancel={endDrag}
      onDoubleClick={() => onView(IDENTITY_VIEW)}
    >
      <canvas ref={canvasRef} className="video-canvas" />
      {emptyText !== "" && <div className="video-empty">{emptyText}</div>}
      {showZoom && view.zoom > MIN_ZOOM + 0.05 && (
        <div className="video-badge video-badge--zoom">×{view.zoom.toFixed(2)}</div>
      )}
      {(view.zoom > MIN_ZOOM + 0.05 || view.x !== 0 || view.y !== 0) && (
        <button className="video-badge video-badge--reset" onClick={() => onView(IDENTITY_VIEW)}>
          复位
        </button>
      )}
      {calibrating && <div className="video-calibrating">校准中：拖动画面挪动瞄准点</div>}
      {children}
    </div>
  );
 }
 // ---------------------------------------------------------------------------
 // 绘制
 // ---------------------------------------------------------------------------
 interface CanvasProps {
  camera: number | null;
  mirrored: boolean;
  crosshair: CrosshairConfig | null;
  grid: GridConfig | null;
  view: ViewTransform;
  hit: HitPulse | null;
  hitFeedback: HitFeedbackConfig;
 }
 interface Box {
  clientWidth: number;
  clientHeight: number;
 }
 /** 图像在窗格里的落点与大小（CSS 像素）。 */
 function layout(box: Box, frameWidth: number, frameHeight: number, view: ViewTransform) {
  const width = box.clientWidth;
  const height = box.clientHeight;
  if (frameWidth <= 0 || frameHeight <= 0) {
    return { left: 0, top: 0, drawWidth: 0, drawHeight: 0 };
  }
  const fit = Math.min(width / frameWidth, height / frameHeight);
  const drawWidth = frameWidth * fit * view.zoom;
  const drawHeight = frameHeight * fit * view.zoom;
  return {
    left: (width - drawWidth) / 2 + view.x,
    top: (height - drawHeight) / 2 + view.y,
    drawWidth,
    drawHeight,
  };
 }
 function draw(
  canvas: HTMLCanvasElement,
  current: CanvasProps,
  frame: { bitmap: ImageBitmap; width: number; height: number } | undefined,
  timestamp: number,
 ) {
  const dpr = window.devicePixelRatio || 1;
  const width = canvas.clientWidth;
  const height = canvas.clientHeight;
  const ctx = canvas.getContext("2d");
  if (!ctx) return;
  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
  ctx.clearRect(0, 0, width, height);
  const box = { clientWidth: width, clientHeight: height };
  // 没有画面时把瞄准器留在窗格中心：录像断了，准星不该跟着消失。
  const fallback = { left: 0, top: 0, drawWidth: 0, drawHeight: 0 };
  const geometry = frame
    ? layout(box, frame.width, frame.height, current.view)
    : fallback;
  if (frame) {
    ctx.save();
    if (current.mirrored) {
      ctx.translate(width, 0);
      ctx.scale(-1, 1);
    }
    // 放大超过 3 倍时关掉插值：这时候要看的是像素本身，双线性插值只会把它糊掉。
    ctx.imageSmoothingEnabled = current.view.zoom < 3;
    ctx.drawImage(frame.bitmap, geometry.left, geometry.top, geometry.drawWidth, geometry.drawHeight);
    ctx.restore();
    if (current.grid?.visible) {
      drawGrid(ctx, geometry, current.grid);
    }
  }
  // 瞄准点的屏幕位置：图像坐标系里的 (0.5 + offsetX, 0.5 + offsetY)。
  const crosshair = current.crosshair;
  let aimX = width / 2;
  let aimY = height / 2;
  if (crosshair && frame && geometry.drawWidth > 0) {
    const rawX = geometry.left + (0.5 + crosshair.offsetX) * geometry.drawWidth;
    aimX = current.mirrored ? width - rawX : rawX;
    aimY = geometry.top + (0.5 + crosshair.offsetY) * geometry.drawHeight;
  }
  if (crosshair?.visible) {
    drawCrosshair(ctx, aimX, aimY, Math.min(width, height), crosshair);
  }
  // 伤害数字：画在屏幕坐标里，不跟着缩放走。
  if (current.hit && current.hitFeedback.marker) {
    const age = timestamp - current.hit.at;
    if (age >= 0 && age < 700) {
      const progress = age / 700;
      ctx.save();
      ctx.globalAlpha = 1 - progress;
      ctx.fillStyle = "#ff8a8a";
      ctx.font = `600 ${Math.round(Math.max(14, Math.min(width, height) * 0.05))}px ui-sans-serif, system-ui, sans-serif`;
      ctx.textAlign = "left";
      ctx.textBaseline = "middle";
      ctx.fillText(`-${current.hit.damage}`, aimX + 24, aimY - 26 - progress * 26);
      ctx.restore();
    }
  }
 }
 function drawGrid(
  ctx: CanvasRenderingContext2D,
  geometry: { left: number; top: number; drawWidth: number; drawHeight: number },
  grid: GridConfig,
 ) {
  if (geometry.drawWidth <= 0 || geometry.drawHeight <= 0) return;
  ctx.save();
  ctx.strokeStyle = `rgba(255, 255, 255, ${grid.opacity})`;
  ctx.lineWidth = 1;
  const x0 = geometry.left;
  const y0 = geometry.top;
  const x1 = x0 + geometry.drawWidth;
  const y1 = y0 + geometry.drawHeight;
  if (grid.style === "thirds") {
    for (const fraction of [1 / 3, 2 / 3]) {
      line(ctx, x0 + geometry.drawWidth * fraction, y0, x0 + geometry.drawWidth * fraction, y1);
      line(ctx, x0, y0 + geometry.drawHeight * fraction, x1, y0 + geometry.drawHeight * fraction);
    }
  } else if (grid.style === "squares") {
    const divisions = Math.max(2, grid.divisions);
    for (let i = 1; i < divisions; i += 1) {
      const fraction = i / divisions;
      line(ctx, x0 + geometry.drawWidth * fraction, y0, x0 + geometry.drawWidth * fraction, y1);
      line(ctx, x0, y0 + geometry.drawHeight * fraction, x1, y0 + geometry.drawHeight * fraction);
    }
  } else {
    // 中心十字。
    line(ctx, x0 + geometry.drawWidth / 2, y0, x0 + geometry.drawWidth / 2, y1);
    line(ctx, x0, y0 + geometry.drawHeight / 2, x1, y0 + geometry.drawHeight / 2);
  }
  ctx.restore();
 }
 function line(ctx: CanvasRenderingContext2D, x0: number, y0: number, x1: number, y1: number) {
  // 半像素偏移，让 1px 的线落在像素中心而不是跨两个像素发虚。
  ctx.beginPath();
  ctx.moveTo(Math.round(x0) + 0.5, Math.round(y0) + 0.5);
  ctx.lineTo(Math.round(x1) + 0.5, Math.round(y1) + 0.5);
  ctx.stroke();
 }
 function drawCrosshair(
  ctx: CanvasRenderingContext2D,
  cx: number,
  cy: number,
  shortSide: number,
  config: CrosshairConfig,
 ) {
  const arm = Math.max(3, config.size * shortSide);
  const gap = config.gap * shortSide;
  const thickness = Math.max(1, config.thickness * shortSide);
  // 外描一圈深色：浅色背景下亮绿准星会消失，这一圈让它始终看得见。
  const halo = withAlpha("#000000", 0.55);
  const stroke = (color: string, width: number, radius: number) => {
    ctx.strokeStyle = color;
    ctx.lineWidth = width;
    ctx.beginPath();
    if (config.style === "circle-dot") {
      ctx.arc(cx, cy, radius, 0, Math.PI * 2);
    } else {
      // 四臂，中心留 gap 的空隙。
      ctx.moveTo(cx - radius, cy);
      ctx.lineTo(cx - gap, cy);
      ctx.moveTo(cx + gap, cy);
      ctx.lineTo(cx + radius, cy);
      ctx.moveTo(cx, cy - radius);
      ctx.lineTo(cx, cy - gap);
      ctx.moveTo(cx, cy + gap);
      ctx.lineTo(cx, cy + radius);
    }
    ctx.stroke();
  };
  stroke(halo, thickness + 2, arm + 1);
  stroke(config.color, thickness, arm);
  // 中心点：`cross` 之外都画。
  if (config.style !== "cross") {
    const dot = Math.max(1.2, thickness * 0.9);
    ctx.fillStyle = halo;
    ctx.beginPath();
    ctx.arc(cx, cy, dot + 1, 0, Math.PI * 2);
    ctx.fill();
    ctx.fillStyle = config.color;
    ctx.beginPath();
    ctx.arc(cx, cy, dot, 0, Math.PI * 2);
    ctx.fill();
  }
 }
 function clamp(value: number, min: number, max: number): number {
  return Math.min(max, Math.max(min, value));
 }
@@ -0,0 +1,153 @@
 /** 设置面板里复用的几个小控件。分成单独文件只是为了不把面板本身撑成一千行。 */
 import type { ChangeEvent, ReactNode } from "react";
 export function Section({ title, hint, children }: { title: string; hint?: string; children: ReactNode }) {
  return (
    <section className="section">
      <h3 className="section__title">{title}</h3>
      {hint && <p className="section__hint">{hint}</p>}
      <div className="section__body">{children}</div>
    </section>
  );
 }
 export function Field({
  label,
  hint,
  children,
 }: {
  label: string;
  hint?: string;
  children: ReactNode;
 }) {
  return (
    <label className="field">
      <span className="field__label">{label}</span>
      <span className="field__control">{children}</span>
      {hint && <span className="field__hint">{hint}</span>}
    </label>
  );
 }
 export function Switch({
  checked,
  onChange,
  label,
  disabled = false,
 }: {
  checked: boolean;
  onChange: (value: boolean) => void;
  label: string;
  disabled?: boolean;
 }) {
  return (
    <label className={`switch${disabled ? " switch--disabled" : ""}`}>
      <input
        type="checkbox"
        checked={checked}
        disabled={disabled}
        onChange={(event: ChangeEvent<HTMLInputElement>) => onChange(event.target.checked)}
      />
      <span className="switch__track">
        <span className="switch__knob" />
      </span>
      <span className="switch__label">{label}</span>
    </label>
  );
 }
 export function Slider({
  value,
  min,
  max,
  step,
  onChange,
  format,
  disabled = false,
 }: {
  value: number;
  min: number;
  max: number;
  step: number;
  onChange: (value: number) => void;
  format?: (value: number) => string;
  disabled?: boolean;
 }) {
  return (
    <span className="slider">
      <input
        type="range"
        min={min}
        max={max}
        step={step}
        value={value}
        disabled={disabled}
        onChange={(event) => onChange(Number(event.target.value))}
      />
      <span className="slider__value">{format ? format(value) : value.toFixed(2)}</span>
    </span>
  );
 }
 export function Select<T extends string | number>({
  value,
  options,
  onChange,
  disabled = false,
 }: {
  value: T | null;
  options: { value: T; label: string; hint?: string }[];
  onChange: (value: T) => void;
  disabled?: boolean;
 }) {
  return (
    <select
      className="select"
      value={value === null ? "" : String(value)}
      disabled={disabled}
      onChange={(event) => {
        const raw = event.target.value;
        const match = options.find((option) => String(option.value) === raw);
        if (match) onChange(match.value);
      }}
    >
      {value === null && <option value="">（未选择）</option>}
      {options.map((option) => (
        <option key={String(option.value)} value={String(option.value)}>
          {option.hint ? `${option.label} — ${option.hint}` : option.label}
        </option>
      ))}
    </select>
  );
 }
 export function Button({
  children,
  onClick,
  variant = "default",
  disabled = false,
  title,
 }: {
  children: ReactNode;
  onClick: () => void;
  variant?: "default" | "primary" | "danger" | "ghost";
  disabled?: boolean;
  title?: string;
 }) {
  return (
    <button className={`button button--${variant}`} onClick={onClick} disabled={disabled} title={title}>
      {children}
    </button>
  );
 }
 /** 一行只读信息：左边标题、右边值。 */
 export function Readout({ label, value }: { label: string; value: ReactNode }) {
  return (
    <div className="readout">
      <span className="readout__label">{label}</span>
      <span className="readout__value">{value}</span>
    </div>
  );
 }
@@ -0,0 +1,538 @@
 /**
 * 仅开发用的浏览器预览。
 *
 * # 它解决什么问题
 *
 * Tauri 的界面跑在 WKWebView 里，改一行 CSS 要走一次 cargo 构建；而且截图要靠 macOS 的
 * 屏幕录制权限。预览模式让同一套 React 组件在浏览器里跑起来：状态由本文件合成，画面用
 * `createImageBitmap` 从一块 canvas 上取——`VideoSurface`、血条、瞄准器、命中反馈全都是
 * 真代码，只有"后端"是假的。
 *
 * # 它绝不可能进到正式构建里
 *
 * 两重门：
 *
 * 1. `import.meta.env.DEV` —— 只在 `vite dev` 下为真；`vite build` 时是 false，
 * 2. 并且页面里没有 Tauri 注入的 `__TAURI_INTERNALS__`。
 *
 * 调用点还用 `await import(...)`：条件为假时整个模块不会被打进产物，而不是打进去再靠
 * 运行时不走。
 *
 * # 用法
 *
 * ```sh
 * pnpm dev                          # 用户端
 * open 'http://127.0.0.1:1420/?preview=referee'   # 裁判端
 * ```
 */
 import { DEFAULT_TEAM_NAMES } from "./format";
 import type { StreamClient } from "./stream";
 import type {
  ConfigView,
  HudView,
  Snapshot,
  WireMsg,
 } from "./types";
 /** 页面里有没有 Tauri 注入。 */
 function hasTauri(): boolean {
  return typeof window !== "undefined" && "__TAURI_INTERNALS__" in window;
 }
 /** 现在是不是在预览模式。 */
 export function isPreview(): boolean {
  return import.meta.env.DEV && !hasTauri();
 }
 const params = new URLSearchParams(typeof location === "undefined" ? "" : location.search);
 const startAsReferee = params.get("preview") === "referee";
 // ---------------------------------------------------------------------------
 // 可变状态：设置面板里的改动会落到这里，界面因此是可交互的
 // ---------------------------------------------------------------------------
 const DEFAULT_HUD: HudView = {
  health: {
    visible: true,
    showNumbers: true,
    showTeamName: true,
    lowThreshold: 30,
    pulse: true,
    width: 0.42,
  },
  crosshair: {
    visible: true,
    style: "cross-dot",
    size: 0.045,
    thickness: 0.004,
    gap: 0.012,
    color: "#3dff88",
    offsetX: 0,
    offsetY: 0,
  },
  grid: { visible: false, style: "thirds", divisions: 6, opacity: 0.22 },
  hitFeedback: { flash: true, shake: false, marker: true, intensity: 1 },
  showZoom: true,
  showStats: true,
 };
 const CAMERA_A = 0x0de0_0001;
 const CAMERA_B = 0x0de0_0002;
 const ARMOR_A = 0x0a20_0001;
 const ARMOR_B = 0x0a20_0002;
 interface PreviewState {
  role: "team" | "referee";
  hud: HudView;
  cameraId: number | null;
  armorId: number | null;
  team: number;
  /** 两边显示的名字，与后端配置里的 `teamNames` 对应。 */
  teamNames: [string, string];
  mirror: boolean;
  unlocked: boolean;
  password: string | null;
  calibrating: boolean;
  recordings: { camera: number; frames: number; startedMs: number }[];
  hp: [number, number];
 }
 const state: PreviewState = {
  role: startAsReferee ? "referee" : "team",
  hud: structuredClone(DEFAULT_HUD),
  cameraId: startAsReferee ? null : CAMERA_A,
  armorId: startAsReferee ? null : ARMOR_A,
  team: 0,
  teamNames: ["队伍一", "队伍二"],
  mirror: true,
  // 预览里直接是已解锁状态，免得每次刷新都要输密码。
  unlocked: false,
  password: "1234",
  calibrating: false,
  recordings: [],
  hp: [100, 100],
 };
 // ---------------------------------------------------------------------------
 // 假的命令实现
 // ---------------------------------------------------------------------------
 /** 供 `ipc.ts` 在有 Tauri 时不会走到的分支上用。 */
 export async function previewInvoke<T>(command: string, args?: Record<string, unknown>): Promise<T> {
  const value = handle(command, args ?? {});
  return value as T;
 }
 function handle(command: string, args: Record<string, unknown>): unknown {
  switch (command) {
    case "stream_info":
      return { url: "preview://", port: 0, clients: 1 };
    case "get_snapshot":
      return snapshot();
    case "get_config":
      return configView();
    case "list_media_files":
      return [];
    case "config_path":
      return "/预览模式/没有真实配置文件";
    case "unlock":
      state.unlocked = String(args.password) === state.password;
      return state.unlocked;
    case "lock":
      state.unlocked = false;
      return undefined;
    case "set_password":
      state.password = String(args.fresh);
      state.unlocked = true;
      return configView();
    case "set_discovery_open":
      return undefined;
    case "bind_camera":
      guard();
      state.cameraId = (args.cameraId as number | null) ?? null;
      return configView();
    case "bind_armor":
      guard();
      state.armorId = (args.armorId as number | null) ?? null;
      return configView();
    case "set_team":
      guard();
      state.team = Number(args.team);
      return configView();
    case "set_team_name": {
      guard();
      const team = Number(args.team);
      if (team !== 0 && team !== 1) throw new Error("队伍号只能是 0 或 1");
      // 与后端一样：合并空白、按字符截断、留空回落默认名。
      state.teamNames[team] = sanitizeName(String(args.name ?? ""), team);
      return configView();
    }
    case "set_role":
      state.role = args.role as "team" | "referee";
      return configView();
    case "set_mirror":
      state.mirror = Boolean(args.mirror);
      return configView();
    case "save_hud":
      state.hud = args.hud as HudView;
      return configView();
    case "set_referee_slots":
      return configView();
    case "set_recording_options":
      return configView();
    case "screenshot":
      return "/预览模式/没有截图";
    case "start_recording": {
      const cameras = (args.cameras as number[]) ?? [];
      const startedMs = Date.now();
      for (const camera of cameras) {
        if (!state.recordings.some((r) => r.camera === camera)) {
          state.recordings.push({ camera, frames: 0, startedMs });
        }
      }
      return recordings();
    }
    case "stop_recording": {
      const cameras = (args.cameras as number[]) ?? [];
      state.recordings = cameras.length
        ? state.recordings.filter((r) => !cameras.includes(r.camera))
        : [];
      return recordings();
    }
    case "refresh":
    case "reveal":
    case "open_file":
      return undefined;
    case "clear_config":
      return "预览模式：没有真实配置可清空";
    case "quit":
      return undefined;
    default:
      throw new Error(`预览模式没有实现命令 ${command}`);
  }
 }
 /** 预览里模拟后端的密码闸门，好让解锁流程也能被看到。 */
 function guard() {
  if (state.role === "team" && state.password !== null && !state.unlocked) {
    throw new Error("这个改动需要密码。先解锁（预览模式里密码是 1234）。");
  }
 }
 function configView(): ConfigView {
  return {
    role: state.role,
    roleChosen: true,
    team: state.team,
    teamNames: [...state.teamNames] as [string, string],
    cameraId: state.cameraId,
    cameraIdText: state.cameraId === null ? null : hex(state.cameraId),
    armorId: state.armorId,
    armorIdText: state.armorId === null ? null : hex(state.armorId),
    mirror: state.mirror,
    passwordSet: state.password !== null,
    hud: structuredClone(state.hud),
    recordingDir: "/预览模式/recordings",
    ffmpeg: "ffmpeg",
  };
 }
 function recordings() {
  return state.recordings.map((recording) => ({
    camera: recording.camera,
    cameraText: hex(recording.camera),
    active: true,
    path: `/预览模式/rec-${recording.camera.toString(16)}.mp4`,
    inputFps: 20,
    framesWritten: recording.frames,
    framesDropped: 0,
    startedMs: recording.startedMs,
    error: null,
  }));
 }
 /** 与后端 `config::sanitize_team_name` 一致：合并空白、按字符截断、留空回落默认名。 */
 function sanitizeName(name: string | undefined, team: number): string {
  const collapsed = (name ?? "").split(/\s+/).filter(Boolean).join(" ");
  const text = collapsed.length > 0 ? collapsed : DEFAULT_TEAM_NAMES[team];
  return [...text].slice(0, 12).join("");
 }
 function hex(id: number): string {
  return `0x${id.toString(16).toUpperCase().padStart(8, "0")}`;
 }
 function snapshot(): Snapshot {
  const cameras = [
    { id: CAMERA_A, team: 0 },
    { id: CAMERA_B, team: 1 },
  ].map(({ id, team }) => ({
    id,
    idText: hex(id),
    addr: team === 0 ? "192.168.1.41" : "192.168.1.42",
    online: true,
    silenceMs: 120,
    firmware: 3,
  }));
  const boards = [
    { id: ARMOR_A, team: 0 },
    { id: ARMOR_B, team: 1 },
  ].map(({ id, team }, index) => ({
    id,
    idText: hex(id),
    addr: team === 0 ? "192.168.1.51" : "192.168.1.52",
    online: true,
    team,
    hp: state.hp[index],
    platesSeen: 4,
    reportsAllPlates: true,
    silenceMs: 90,
  }));
  const stats = cameras.map((camera) => ({
    camera: camera.id,
    cameraText: camera.idText,
    online: true,
    status: camera.idText,
    hasFrames: true,
    fps: 20,
    width: 640,
    height: 480,
    framesShown: 1000,
    framesDropped: 3,
    lossPercent: 0.3,
    datagrams: 17000,
    lastFrameBytes: 22000,
    gapMs: 50,
  }));
  // 与后端 `cam_core::snapshot::resolve_outcomes` 同一套规则，包括那条不对称：
  // 输只看自己，赢要看对手归零**且**自己还活着。
  const outcomeFor = (team: number) => {
    const mine = state.hp[team];
    const theirs = state.hp[team === 0 ? 1 : 0];
    if (mine === 0 && theirs === 0) return "draw" as const;
    if (theirs === 0 && mine > 0) return "victory" as const;
    if (mine === 0) return "defeat" as const;
    return null;
  };
  const healthFor = (team: number) => {
    const hp = state.hp[team];
    const board = team === 0 ? ARMOR_A : ARMOR_B;
    return {
      team,
      name: state.teamNames[team],
      available: true,
      placeholder: "",
      hp,
      hps: [hp, hp, hp, hp],
      board,
      boardText: hex(board),
      critical: hp === 0 || hp <= state.hud.health.lowThreshold,
      outcome: outcomeFor(team),
    };
  };
  return {
    role: state.role,
    team: state.team,
    mirrored: state.mirror,
    demo: true,
    diagnostics: true,
    unlocked: state.unlocked || state.role === "referee",
    discoveryOpen: true,
    uptimeMs: performance.now(),
    clients: 1,
    config: configView(),
    cameras,
    armorBoards: boards,
    stats,
    slots: {
      cameraA: state.role === "referee" ? CAMERA_A : state.cameraId,
      cameraB: state.role === "referee" ? CAMERA_B : null,
      armorA: state.role === "referee" ? ARMOR_A : state.armorId,
      armorB: state.role === "referee" ? ARMOR_B : null,
      manual: false,
    },
    // 两边都给：用户端也要显示对手的血量（画面右上角那一条）。
    health: [healthFor(0), healthFor(1)],
    recordings: recordings(),
    notes: ["这是浏览器预览：状态与画面都是本文件合成的，不是真实链路。"],
  };
 }
 // ---------------------------------------------------------------------------
 // 假的画面与心跳
 // ---------------------------------------------------------------------------
 /** 启动预览的数据源：每 200ms 一份快照，每 50ms 一帧画面。 */
 export function startPreview(client: StreamClient, emit: (msg: WireMsg) => void) {
  let frameId = 0;
  const started = performance.now();
  // 快照。
  const snapshotTimer = window.setInterval(() => {
    emit({ t: "snapshot", ...snapshot() } as WireMsg);
  }, 200);
  // 两路画面，各 20fps。
  const canvases = new Map<number, HTMLCanvasElement>();
  const render = async (camera: number, team: number) => {
    const canvas = canvases.get(camera) ?? makeCanvas();
    canvases.set(camera, canvas);
    draw(canvas, team, frameId);
    const bitmap = await createImageBitmap(canvas);
    client.injectFrame(camera, frameId, canvas.width, canvas.height, bitmap);
  };
  const frameTimer = window.setInterval(() => {
    frameId += 1;
    const cameras =
      state.role === "referee"
        ? [
            [CAMERA_A, 0],
            [CAMERA_B, 1],
          ]
        : [[state.cameraId ?? CAMERA_A, state.team]];
    for (const [camera, team] of cameras as [number, number][]) {
      void render(camera, team);
    }
    for (const recording of state.recordings) recording.frames += 1;
  }, 50);
  // 掉血：每 3 秒一次，轮流打两块板子，顺便把命中反馈也验证了。
  //
  // 打空的那一拍只做重置、不出命中（胜负横幅要真的能看到），其余每一拍都出一次
  // 命中。早先的写法是 `to = from === 0 ? 100 : ...` 然后按 `to >= from` 判断——那样一旦
  // 两块都打空，之后每次都是重置，命中就再也不会出现，盯着界面等闪红会等到超时。
  let tick = 0;
  const hitTimer = window.setInterval(() => {
    tick += 1;
    const team = tick % 2;
    if (state.hp[team] === 0) {
      state.hp[team] = 100;
      return;
    }
    const from = state.hp[team];
    const damage = 3 + ((tick * 7) % 20);
    const to = Math.max(0, from - damage);
    state.hp[team] = to;
    emit({
      t: "hit",
      board: team === 0 ? ARMOR_A : ARMOR_B,
      team,
      index: 0,
      from,
      to,
      damage: from - to,
      atMs: Date.now(),
    } as WireMsg);
  }, 3000);
  // 第一帧不必等 200ms。
  emit({ t: "snapshot", ...snapshot() } as WireMsg);
  return () => {
    window.clearInterval(snapshotTimer);
    window.clearInterval(frameTimer);
    window.clearInterval(hitTimer);
    void started;
  };
 }
 function makeCanvas(): HTMLCanvasElement {
  const canvas = document.createElement("canvas");
  canvas.width = 640;
  canvas.height = 480;
  return canvas;
 }
 /** 与 `src-tauri/src/demo.rs` 画的是同一类东西：底色区分两路、中心靶心、二进制帧号。 */
 function draw(canvas: HTMLCanvasElement, team: number, frameId: number) {
  const ctx = canvas.getContext("2d");
  if (!ctx) return;
  const { width, height } = canvas;
  const tint = team === 0 ? [0, 46, 40] : [58, 30, 0];
  const gradient = ctx.createLinearGradient(0, 0, 0, height);
  gradient.addColorStop(0, `rgb(${18 + tint[0] / 3}, ${18 + tint[1] / 3}, ${22 + tint[2] / 3})`);
  gradient.addColorStop(1, `rgb(${78 + tint[0] / 3}, ${78 + tint[1] / 3}, ${82 + tint[2] / 3})`);
  ctx.fillStyle = gradient;
  ctx.fillRect(0, 0, width, height);
  ctx.strokeStyle = "rgba(255,255,255,0.07)";
  ctx.lineWidth = 1;
  for (let x = 0; x < width; x += 40) {
    ctx.beginPath();
    ctx.moveTo(x + 0.5, 0);
    ctx.lineTo(x + 0.5, height);
    ctx.stroke();
  }
  for (let y = 0; y < height; y += 40) {
    ctx.beginPath();
    ctx.moveTo(0, y + 0.5);
    ctx.lineTo(width, y + 0.5);
    ctx.stroke();
  }
  const cx = width / 2;
  const cy = height / 2;
  ctx.strokeStyle = "#c8c8d2";
  ctx.lineWidth = 2;
  ctx.beginPath();
  ctx.arc(cx, cy, 60, 0, Math.PI * 2);
  ctx.stroke();
  ctx.strokeStyle = "#96969f";
  ctx.beginPath();
  ctx.arc(cx, cy, 28, 0, Math.PI * 2);
  ctx.stroke();
  ctx.strokeStyle = "#78788a";
  for (const [dx, dy] of [
    [1, 0],
    [-1, 0],
    [0, 1],
    [0, -1],
  ]) {
    ctx.beginPath();
    ctx.moveTo(cx + dx * 40, cy + dy * 40);
    ctx.lineTo(cx + dx * 90, cy + dy * 90);
    ctx.stroke();
  }
  for (let bit = 0; bit < 16; bit += 1) {
    const on = ((frameId >> bit) & 1) === 1;
    ctx.fillStyle = on ? "#78ffa0" : "#34343c";
    ctx.fillRect(12 + bit * 14, 12, 10, 10);
  }
  const t = frameId / 20;
  const phase = team === 0 ? 0 : 1.7;
  ctx.fillStyle = "#ffd25a";
  ctx.beginPath();
  ctx.arc(cx + 250 * Math.sin(t * 0.9 + phase), cy + 150 * Math.cos(t * 1.3 + phase), 26, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = "#5ac8ff";
  ctx.fillRect(((t * 60) % (width - 80)) | 0, height - 24, 60, 8);
  ctx.font = "600 20px ui-monospace, monospace";
  ctx.fillStyle = "#e8e8ec";
  ctx.fillText(team === 0 ? "PREVIEW · TEAM 1" : "PREVIEW · TEAM 2", 14, height - 40);
  ctx.font = "500 16px ui-monospace, monospace";
  ctx.fillStyle = "#8a8a95";
  ctx.fillText(`frame ${frameId}`, 14, height - 16);
 }
@@ -0,0 +1,88 @@
 /** 纯格式化函数。界面里所有"给人看的数字"都从这里过一遍。 */
 /** `0x3D4D8A9A`。与 Rust 侧的 `snapshot::id_text` 输出一致。 */
 export function idText(id: number | null | undefined): string {
  if (id === null || id === undefined) return "—";
  return `0x${id.toString(16).toUpperCase().padStart(8, "0")}`;
 }
 /** 22000 → `21.5 kB`。 */
 export function bytes(value: number): string {
  if (value <= 0) return "—";
  if (value < 1024) return `${value} B`;
  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} kB`;
  return `${(value / 1024 / 1024).toFixed(2)} MB`;
 }
 /** 毫秒 → 人话。 */
 export function elapsed(ms: number | null | undefined): string {
  if (ms === null || ms === undefined) return "—";
  if (ms < 1000) return `${Math.round(ms)} ms`;
  if (ms < 60_000) return `${(ms / 1000).toFixed(1)} s`;
  const totalSeconds = Math.round(ms / 1000);
  const minutes = Math.floor(totalSeconds / 60);
  const seconds = totalSeconds % 60;
  if (minutes < 60) return `${minutes} 分 ${seconds} 秒`;
  const hours = Math.floor(minutes / 60);
  return `${hours} 小时 ${minutes % 60} 分`;
 }
 /** 录制时长：从开始到现在的墙钟。 */
 export function since(ms: number | null | undefined, now = Date.now()): string {
  if (!ms) return "—";
  return elapsed(now - ms);
 }
 /** Unix 毫秒 → `14:03:22`。 */
 export function clockTime(ms: number | null | undefined): string {
  if (!ms) return "—";
  const date = new Date(ms);
  const pad = (value: number) => value.toString().padStart(2, "0");
  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
 }
 /** 小数位固定的帧率。0 表示"还没读数"，显示成 `—` 而不是 `0.0`。 */
 export function fps(value: number): string {
  if (!Number.isFinite(value) || value <= 0) return "—";
  return value.toFixed(1);
 }
 /** 队伍名的兜底值。与 Rust 侧的 `config::DEFAULT_TEAM_NAMES` 一致。 */
 export const DEFAULT_TEAM_NAMES = ["队伍一", "队伍二"];
 /**
 * 队伍名。
 *
 * 名字是**配置里可以改的**（裁判端能直接编辑），所以显示的地方一律从这里取：散在各处的
 * `team === 0 ? "队伍一" : "队伍二"` 会在改名之后留下一半旧名字，而且不会报错。
 *
 * `names` 传配置里的两条；缺省或留空时回落到默认名。
 */
 export function teamName(team: number, names?: readonly string[] | null): string {
  const custom = names?.[team]?.trim();
  if (custom) return custom;
  return DEFAULT_TEAM_NAMES[team] ?? "队伍";
 }
 /** 队伍配色：与装甲板灯色一致（队伍一红、队伍二蓝）。 */
 export function teamColor(team: number): string {
  return team === 0 ? "#ff5f5f" : "#5aa9ff";
 }
 /** 把 `#RRGGBB` 变成 `rgba(...)`。瞄准器颜色要带透明度时用。 */
 export function withAlpha(hex: string, alpha: number): string {
  const match = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
  if (!match) return hex;
  const value = parseInt(match[1], 16);
  const r = (value >> 16) & 0xff;
  const g = (value >> 8) & 0xff;
  const b = value & 0xff;
  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
 }
@@ -0,0 +1,101 @@
 /**
 * 后端命令的封装。
 *
 * 每个函数对应 `desktop/src-tauri/src/commands.rs` 里的一个 `#[tauri::command]`。
 * Tauri 会把 JS 侧的 camelCase 参数名转成 Rust 侧的 snake_case，所以这里的参数名写成
 * 前端习惯的样子即可。
 *
 * # 错误
 *
 * 后端的 `Err(String)` 会以 rejected promise 的形式回来，字符串就是给现场的人看的那句
 * 话。`call()` 把 `unknown` 归一成 `Error`，调用方只管 `catch (err) { err.message }`。
 */
 import { invoke } from "@tauri-apps/api/core";
 import type {
  ConfigView,
  HudView,
  MediaFileDto,
  RecordingDto,
  Role,
  Snapshot,
  StreamInfo,
 } from "./types";
 /**
 * 把后端的字符串错误变成真正的 `Error`。
 *
 * 在没有 Tauri 的 `vite dev` 会话里（`?preview=` 那种），这条走预览实现——它用
 * `await import()` 引入，所以正式构建里那段代码根本不会被打进产物（见 `dev-preview.ts`）。
 */
 async function call<T>(command: string, args?: Record<string, unknown>): Promise<T> {
  if (import.meta.env.DEV && !("__TAURI_INTERNALS__" in window)) {
    const preview = await import("./dev-preview");
    return preview.previewInvoke<T>(command, args);
  }
  try {
    return await invoke<T>(command, args);
  } catch (raw) {
    throw new Error(typeof raw === "string" ? raw : String(raw));
  }
 }
 export const api = {
  // ---- 只读 ----
  streamInfo: () => call<StreamInfo>("stream_info"),
  snapshot: () => call<Snapshot>("get_snapshot"),
  config: () => call<ConfigView>("get_config"),
  mediaFiles: () => call<MediaFileDto[]>("list_media_files"),
  configPath: () => call<string>("config_path"),
  // ---- 密码 ----
  unlock: (password: string) => call<boolean>("unlock", { password }),
  lock: () => call<void>("lock"),
  setPassword: (fresh: string, current?: string) =>
    call<ConfigView>("set_password", { current: current ?? null, fresh }),
  setDiscoveryOpen: (open: boolean) => call<void>("set_discovery_open", { open }),
  // ---- 绑定与身份 ----
  bindCamera: (cameraId: number | null, password?: string) =>
    call<ConfigView>("bind_camera", { cameraId, password: password ?? null }),
  bindArmor: (armorId: number | null, password?: string) =>
    call<ConfigView>("bind_armor", { armorId, password: password ?? null }),
  setTeam: (team: number, password?: string) =>
    call<ConfigView>("set_team", { team, password: password ?? null }),
  setRole: (role: Role, password?: string) =>
    call<ConfigView>("set_role", { role, password: password ?? null }),
  setMirror: (mirror: boolean) => call<ConfigView>("set_mirror", { mirror }),
  saveHud: (hud: HudView) => call<ConfigView>("save_hud", { hud }),
  /** 改一边的队名（0 = 队伍一，1 = 队伍二）。一次只改一边，避免覆盖另一边的改动。 */
  setTeamName: (team: number, name: string, password?: string) =>
    call<ConfigView>("set_team_name", { team, name, password: password ?? null }),
  setRefereeSlots: (slots: {
    cameraA: number | null;
    cameraB: number | null;
    armorA: number | null;
    armorB: number | null;
    manual: boolean;
  }) => call<ConfigView>("set_referee_slots", slots),
  setRecordingOptions: (options: {
    dir: string | null;
    ffmpeg: string | null;
    crf: number | null;
    preset: string | null;
  }) => call<ConfigView>("set_recording_options", options),
  // ---- 截图与录制 ----
  screenshot: (camera: number) => call<string>("screenshot", { camera }),
  startRecording: (cameras: number[]) => call<RecordingDto[]>("start_recording", { cameras }),
  stopRecording: (cameras: number[]) => call<RecordingDto[]>("stop_recording", { cameras }),
  reveal: (path: string) => call<void>("reveal", { path }),
  openFile: (path: string) => call<void>("open_file", { path }),
  // ---- 退出与重置 ----
  clearConfig: (password?: string) =>
    call<string>("clear_config", { password: password ?? null }),
  quit: (password?: string) => call<void>("quit_app", { password: password ?? null }),
  refresh: () => call<void>("refresh"),
 };
@@ -0,0 +1,141 @@
 /**
 * 后端状态的订阅式存储。
 *
 * 后端每 200 ms 推一份完整快照，前端只做渲染——没有轮询、没有"各处分别拉数据"带来的
 * 两种时刻的状态混在一起。实现用一个模块级单例 + `useSyncExternalStore`。
 *
 * 快照对象**每次整体替换**：`useSyncExternalStore` 靠引用比较判断要不要重渲染，就地
 * 修改字段不会触发更新。
 */
 import { useSyncExternalStore } from "react";
 import { StreamClient } from "./stream";
 import type { HitEvent, Snapshot, WireMsg } from "./types";
 /**
 * 一次掉血在界面上的记录。
 *
 * `receivedAt` 用 `performance.now()` 而不是后端给的 `atMs`（Unix 毫秒）：动画的时钟必须
 * 与 `requestAnimationFrame` 的时间戳同源，把两个时钟相减会得到一个荒唐的年龄，动画也
 * 就不会出现。
 */
 export interface HitPulseRecord extends HitEvent {
  seq: number;
  receivedAt: number;
 }
 export interface AppStore {
  /** 还没收到第一份快照时为 null。 */
  snapshot: Snapshot | null;
  /** 与后端的视频通道是否连着。 */
  connected: boolean;
  /** 最近一次掉血，界面用它做闪红与伤害数字。 */
  lastHit: HitPulseRecord | null;
  /** 后端要求弹出解锁框（用户端点关闭窗口时）。 */
  confirmQuit: number;
  /** 一条条要显示的说明。 */
  notes: string[];
  /** 通道本身的问题（连不上、丢帧）。 */
  channelError: string | null;
 }
 const initial: AppStore = {
  snapshot: null,
  connected: false,
  lastHit: null,
  confirmQuit: 0,
  notes: [],
  channelError: null,
 };
 let store: AppStore = initial;
 let hitSeq = 0;
 const listeners = new Set<() => void>();
 function emit(next: Partial<AppStore>) {
  store = { ...store, ...next };
  for (const listener of listeners) listener();
 }
 function subscribe(listener: () => void) {
  listeners.add(listener);
  return () => listeners.delete(listener);
 }
 /** 组件里读状态。 */
 export function useAppStore(): AppStore {
  return useSyncExternalStore(subscribe, () => store);
 }
 /** 组件外读状态（事件处理、命令回调里用）。 */
 export function currentStore(): AppStore {
  return store;
 }
 function handleMessage(msg: WireMsg) {
  switch (msg.t) {
    case "snapshot": {
      const { t: _tag, ...snapshot } = msg;
      emit({ snapshot: snapshot as Snapshot });
      return;
    }
    case "hit":
      hitSeq += 1;
      emit({ lastHit: { ...msg, seq: hitSeq, receivedAt: performance.now() } });
      return;
    case "note":
      emit({ notes: [...store.notes, msg.message].slice(-6) });
      return;
    case "confirmQuit":
      emit({ confirmQuit: store.confirmQuit + 1 });
      return;
  }
 }
 let client: StreamClient | null = null;
 /**
 * 建立与后端的通道。整个界面只调一次（在 `App` 里）。
 */
 export function startStream(url: string): StreamClient {
  client?.close();
  client = new StreamClient({
    onMessage: handleMessage,
    onConnection: (connected) =>
      emit({
        connected,
        channelError: connected ? null : "与后端的视频通道断开，正在重连…",
      }),
  });
  // 浏览器预览：没有 WebSocket，状态与画面由 dev-preview.ts 合成。
  // 动态引入让这段代码在正式构建里被完全剔掉。
  if (import.meta.env.DEV && !("__TAURI_INTERNALS__" in window)) {
    emit({ connected: true });
    const current = client;
    void import("./dev-preview").then((preview) => preview.startPreview(current, handleMessage));
    return client;
  }
  client.connect(url);
  return client;
 }
 export function streamClient(): StreamClient {
  if (!client) throw new Error("startStream 还没有被调用");
  return client;
 }
 /** 手动塞一条说明（本地校验失败之类）。 */
 export function pushNote(message: string) {
  emit({ notes: [...store.notes, message].slice(-6) });
 }
 /** 关掉一条说明。 */
 export function dismissNote(index: number) {
  emit({ notes: store.notes.filter((_, i) => i !== index) });
 }
@@ -0,0 +1,212 @@
 /**
 * 视频与状态通道的客户端。
 *
 * # 为什么是 WebSocket 而不是 invoke
 *
 * 两路 22fps、每帧约 22 kB，也就是每秒约 1 MB 的裸 JPEG。走 IPC 的话它要变成 base64
 * 再涨 1/3，然后在 JS 里解回来——CPU 花在没人需要的编解码上。二进制 WebSocket 帧把
 * 原始 JPEG 字节直接交给我们，交给 `createImageBitmap` 解码。
 *
 * # 解码是异步的，所以帧号要看着用
 *
 * `createImageBitmap` 返回 Promise，两个相邻帧的解码**可能**乱序完成。所以每路记住最后
 * 画过的帧号，只有更新的那帧才会被采用。没有这一步，画面会偶发地往回跳一帧——看起来
 * 像"卡了一下"，极难归因。
 *
 * # `ImageBitmap` 必须显式 close
 *
 * 它持有解码后的像素（不吃 GC 的账）。每收到新帧就替换旧的那张并不够，必须把旧的那张
 * `close()` 掉，否则两路 22fps 跑上几分钟就是几百 MB 的显存/内存。
 */
 import { FRAME_HEADER_LEN, type WireMsg } from "./types";
 /** 每路最新一张画面。 */
 export interface FrameInfo {
  camera: number;
  frameId: number;
  width: number;
  height: number;
  bitmap: ImageBitmap;
  /** 收到的时刻（`performance.now()`），界面用来显示端到端延迟。 */
  receivedAt: number;
 }
 interface Handlers {
  onMessage: (msg: WireMsg) => void;
  onConnection: (connected: boolean) => void;
 }
 /** 断线重连的退避上限。 */
 const MAX_BACKOFF_MS = 3000;
 export class StreamClient {
  private ws: WebSocket | null = null;
  private url: string | null = null;
  private readonly frames = new Map<number, FrameInfo>();
  private readonly handlers: Handlers;
  private retryTimer: number | null = null;
  private backoff = 250;
  private closed = false;
  /** 统计：收到多少帧、解码失败多少张。界面用它区分"链路没数据"和"数据坏了"。 */
  readonly counters = { frames: 0, decodeFailures: 0, reconnects: 0 };
  constructor(handlers: Handlers) {
    this.handlers = handlers;
  }
  connect(url: string) {
    this.url = url;
    this.closed = false;
    this.open();
  }
  private open() {
    if (!this.url || this.closed) return;
    let socket: WebSocket;
    try {
      socket = new WebSocket(this.url);
    } catch {
      this.scheduleReconnect();
      return;
    }
    socket.binaryType = "arraybuffer";
    this.ws = socket;
    socket.onopen = () => {
      this.backoff = 250;
      this.handlers.onConnection(true);
    };
    socket.onclose = () => {
      this.handlers.onConnection(false);
      this.scheduleReconnect();
    };
    socket.onerror = () => {
      // onerror 之后一定会有 onclose，重连交给那一条路径。
    };
    socket.onmessage = (event) => {
      if (typeof event.data === "string") {
        try {
          this.handlers.onMessage(JSON.parse(event.data) as WireMsg);
        } catch {
          // 前端解析不了的消息只可能是版本不匹配，忽略比崩掉好。
        }
        return;
      }
      void this.onBinary(event.data as ArrayBuffer);
    };
  }
  private async onBinary(buffer: ArrayBuffer) {
    if (buffer.byteLength < FRAME_HEADER_LEN) return;
    const view = new DataView(buffer);
    const camera = view.getUint32(0, true);
    const frameId = view.getUint32(4, true);
    const width = view.getUint16(8, true);
    const height = view.getUint16(10, true);
    const length = view.getUint32(12, true);
    if (buffer.byteLength < FRAME_HEADER_LEN + length) return;
    this.counters.frames += 1;
    const jpeg = new Uint8Array(buffer, FRAME_HEADER_LEN, length);
    let bitmap: ImageBitmap;
    try {
      bitmap = await createImageBitmap(new Blob([jpeg], { type: "image/jpeg" }));
    } catch {
      this.counters.decodeFailures += 1;
      return;
    }
    this.store(camera, frameId, width, height, bitmap);
  }
  /**
   * 放进一帧。
   *
   * 解码是异步的，所以这里要再判一次"更新的一帧有没有先到"：`createImageBitmap` 的
   * 完成顺序不保证与发起顺序一致，不判的话画面会偶发地往回跳一帧。
   *
   * 预览模式（`dev-preview.ts`）直接调它，绕过 WebSocket——两条路径共用同一套存储逻辑，
   * 所以预览里看到的画面行为与真机一致。
   */
  private store(
    camera: number,
    frameId: number,
    width: number,
    height: number,
    bitmap: ImageBitmap,
  ) {
    const current = this.frames.get(camera);
    // 带符号差处理 u32 回绕。
    if (current && ((frameId - current.frameId) | 0) <= 0) {
      bitmap.close();
      return;
    }
    current?.bitmap.close();
    this.frames.set(camera, {
      camera,
      frameId,
      width,
      height,
      bitmap,
      receivedAt: performance.now(),
    });
  }
  /** 给预览模式用的入口：直接塞一帧。 */
  injectFrame(
    camera: number,
    frameId: number,
    width: number,
    height: number,
    bitmap: ImageBitmap,
  ) {
    this.counters.frames += 1;
    this.store(camera, frameId, width, height, bitmap);
  }
  private scheduleReconnect() {
    if (this.closed || this.retryTimer !== null) return;
    this.retryTimer = window.setTimeout(() => {
      this.retryTimer = null;
      this.counters.reconnects += 1;
      this.backoff = Math.min(this.backoff * 2, MAX_BACKOFF_MS);
      this.open();
    }, this.backoff);
  }
  /** 某一路最新的一帧。 */
  latest(camera: number | null | undefined): FrameInfo | undefined {
    if (camera === null || camera === undefined) return undefined;
    return this.frames.get(camera);
  }
  close() {
    this.closed = true;
    if (this.retryTimer !== null) {
      window.clearTimeout(this.retryTimer);
      this.retryTimer = null;
    }
    this.ws?.close();
    this.ws = null;
    for (const frame of this.frames.values()) frame.bitmap.close();
    this.frames.clear();
  }
 }
@@ -0,0 +1,239 @@
 /**
 * 与 Rust 侧 DTO 一一对应的类型。
 *
 * 这些名字不是随手起的：Rust 那边的结构体带 `#[serde(rename_all = "camelCase")]`，
 * 字段名就是这里写的这样。改任何一边都要同时改另一边——**编译器不会帮你发现这件事**，
 * 所以两边都留了指向对方的注释。
 *
 * 对应的 Rust 定义在 `desktop/core/src/snapshot.rs` 与 `desktop/src-tauri/src/recording.rs`。
 */
 export type Role = "team" | "referee";
 /** `cam_core::config::CrosshairStyle` */
 export type CrosshairStyle = "cross" | "cross-dot" | "circle-dot" | "dot";
 /** `cam_core::config::GridStyle` */
 export type GridStyle = "thirds" | "squares" | "cross";
 /** `cam_core::config::HealthConfig` */
 export interface HealthConfig {
  visible: boolean;
  showNumbers: boolean;
  showTeamName: boolean;
  lowThreshold: number;
  pulse: boolean;
  /** 血条宽度占画面宽度的比例。 */
  width: number;
 }
 /** `cam_core::config::CrosshairConfig` */
 export interface CrosshairConfig {
  visible: boolean;
  style: CrosshairStyle;
  /** 臂长 / 半径，画面短边的比例。 */
  size: number;
  /** 线宽，画面短边的比例。 */
  thickness: number;
  /** 中心空隙，画面短边的比例。 */
  gap: number;
  /** `#RRGGBB` */
  color: string;
  /** 校准偏移，画面宽度的比例，正数向右。 */
  offsetX: number;
  /** 校准偏移，画面高度的比例，正数向下。 */
  offsetY: number;
 }
 /** `cam_core::config::GridConfig` */
 export interface GridConfig {
  visible: boolean;
  style: GridStyle;
  divisions: number;
  opacity: number;
 }
 /** `cam_core::config::HitFeedbackConfig` */
 export interface HitFeedbackConfig {
  flash: boolean;
  /**
   * 已废弃：命中时不再抖动画面。
   *
   * 字段留着只是为了读得进旧配置文件（Rust 侧 `deny_unknown_fields`，删字段会让写过
   * `shake = true` 的配置直接解析失败）。界面不读它。
   */
  shake: boolean;
  marker: boolean;
  intensity: number;
 }
 /** `cam_core::snapshot::HudView` */
 export interface HudView {
  health: HealthConfig;
  crosshair: CrosshairConfig;
  grid: GridConfig;
  hitFeedback: HitFeedbackConfig;
  showZoom: boolean;
  showStats: boolean;
 }
 /** `cam_core::snapshot::ConfigView`（不含密码哈希） */
 export interface ConfigView {
  role: Role;
  roleChosen: boolean;
  team: number;
  /** 两边在界面上显示的名字，下标就是队伍号。裁判端可以直接改。 */
  teamNames: [string, string];
  cameraId: number | null;
  cameraIdText: string | null;
  armorId: number | null;
  armorIdText: string | null;
  mirror: boolean;
  passwordSet: boolean;
  hud: HudView;
  recordingDir: string;
  ffmpeg: string;
 }
 /** `cam_core::snapshot::CameraDto` */
 export interface CameraDto {
  id: number;
  idText: string;
  addr: string;
  online: boolean;
  silenceMs: number;
  firmware: number;
 }
 /** `cam_core::snapshot::ArmorBoardDto` */
 export interface ArmorBoardDto {
  id: number;
  idText: string;
  addr: string;
  online: boolean;
  team: number;
  hp: number;
  platesSeen: number;
  reportsAllPlates: boolean;
  silenceMs: number;
 }
 /** `cam_core::snapshot::CameraStatsDto` */
 export interface CameraStatsDto {
  camera: number;
  cameraText: string;
  online: boolean;
  status: string;
  hasFrames: boolean;
  fps: number;
  width: number;
  height: number;
  framesShown: number;
  framesDropped: number;
  lossPercent: number;
  datagrams: number;
  lastFrameBytes: number;
  gapMs: number | null;
 }
 /** `cam_core::snapshot::SlotsDto` */
 export interface SlotsDto {
  cameraA: number | null;
  cameraB: number | null;
  armorA: number | null;
  armorB: number | null;
  manual: boolean;
 }
 /**
 * `cam_core::snapshot::MatchOutcome`。
 *
 * 是**从这一边看**的结论，不是"谁赢了"这个全局判断：同一场对局里两边的 DTO 各带一份。
 */
 export type MatchOutcome = "victory" | "defeat" | "draw";
 /** `cam_core::snapshot::TeamHealthDto` */
 export interface TeamHealthDto {
  team: number;
  name: string;
  available: boolean;
  placeholder: string;
  hp: number | null;
  hps: number[];
  board: number | null;
  boardText: string | null;
  critical: boolean;
  /** 有结论时（有人归零）才有值；两边都活着时是 null。 */
  outcome: MatchOutcome | null;
 }
 /** `cam_core::snapshot::RecordingDto` */
 export interface RecordingDto {
  camera: number;
  cameraText: string;
  active: boolean;
  path: string | null;
  inputFps: number;
  framesWritten: number;
  framesDropped: number;
  startedMs: number | null;
  error: string | null;
 }
 /** `desktop/src-tauri/src/recording.rs` 的 `MediaFileDto` */
 export interface MediaFileDto {
  name: string;
  path: string;
  kind: "video" | "image";
  bytes: number;
  modifiedMs: number;
 }
 /** `cam_core::snapshot::Snapshot` */
 export interface Snapshot {
  role: Role;
  team: number;
  mirrored: boolean;
  demo: boolean;
  diagnostics: boolean;
  unlocked: boolean;
  discoveryOpen: boolean;
  uptimeMs: number;
  clients: number;
  config: ConfigView;
  cameras: CameraDto[];
  armorBoards: ArmorBoardDto[];
  stats: CameraStatsDto[];
  slots: SlotsDto;
  health: TeamHealthDto[];
  recordings: RecordingDto[];
  notes: string[];
 }
 /** `desktop/src-tauri/src/server.rs` 的 `StreamInfo` */
 export interface StreamInfo {
  url: string;
  port: number;
  clients: number;
 }
 /** `server::WireMsg` 的 `Hit`。 */
 export interface HitEvent {
  board: number;
  team: number;
  index: number;
  from: number;
  to: number;
  damage: number;
  atMs: number;
 }
 /** `server::WireMsg` 的文本信封。`t` 是 serde 的内部标签。 */
 export type WireMsg =
  | ({ t: "snapshot" } & Snapshot)
  | ({ t: "hit" } & HitEvent)
  | { t: "note"; message: string }
  | { t: "confirmQuit" };
 /** 二进制视频帧的头部长度，与 `server::FRAME_HEADER_LEN` 一致。 */
 export const FRAME_HEADER_LEN = 16;
@@ -0,0 +1,15 @@
 import { createRoot } from "react-dom/client";
 import App from "./App";
 import "./styles/global.css";
 const container = document.getElementById("root");
 if (!container) {
  throw new Error("index.html 里没有 #root");
 }
 // 不用 StrictMode：这个界面的关键路径是命令式的（WebSocket、requestAnimationFrame 绘制
 // 循环、canvas 尺寸）。StrictMode 在开发下会把每个 effect 跑两遍，于是连接与绘制循环会
 // 短暂地建两份——排查起来的噪音大于它带来的收益。生产构建的行为与这里一致。
 createRoot(container).render(<App />);
@@ -0,0 +1,215 @@
 /**
 * 裁判端：两路画面 + 双方血量 + 装甲板发现列表 + 截图与录制。
 *
 * 布局的诉求与用户端不同：这里要**一眼比出两边的状态**，所以两格等宽、血量各自贴在画面的
 * 上角（左格左上、右格右上，与用户端的"自己在左上、对手在右上"是同一套读法）、缩放置互相
 * 独立（滚轮只作用于鼠标所在的那一路）。
 *
 * 两格等宽这件事在旧客户端上是踩过坑的：`HorizontalLayout` 先按内容的**最大**需求分配，
 * 剩下的才按 stretch 分。一格写着"已连接，等待画面…"（8 字），另一格只有"未收到画面"
 * （5 字），于是左边多要十几个像素——实测 55% / 45%。解法是让两格的需求只由画面决定：
 * 统一的 `preferred-width` 加 `min-width`，文字用绝对定位不参与布局。CSS 的 flex 里
 * 用 `flex: 1 1 0` + `min-width: 0` 达到同一件事。
 *
 * # 队名可以直接改
 *
 * 名字属于这一场比赛，所以它放在两格画面各自下面（见 `TeamNameEditor`），改完立刻反映到
 * 血条、装甲板表与等待画面的文字上。命令在 Rust 侧，规范化也在那边统一做。
 */
 import { useMemo, useState } from "react";
 import { ArmorTable, StatsLine } from "../components/ArmorTable";
 import { HealthBar } from "../components/HealthBar";
 import { HitFlash } from "../components/HitFlash";
 import { MatchBanner } from "../components/MatchBanner";
 import { MediaPanel } from "../components/MediaPanel";
 import { TeamNameEditor } from "../components/TeamNameEditor";
 import { TopBar } from "../components/TopBar";
 import { IDENTITY_VIEW, VideoSurface, type ViewTransform } from "../components/VideoSurface";
 import { Button } from "../components/controls";
 import { teamName } from "../lib/format";
 import { api } from "../lib/ipc";
 import { useAppStore } from "../lib/store";
 import type { HudView, Snapshot } from "../lib/types";
 interface Props {
  snapshot: Snapshot;
  hud: HudView;
  onOpenSettings: () => void;
  onError: (message: string) => void;
  onInfo: (message: string) => void;
 }
 /** 底部区域的两个页签。 */
 type Tab = "armor" | "media";
 export function RefereePage({ snapshot, hud, onOpenSettings, onError, onInfo }: Props) {
  const { lastHit } = useAppStore();
  const [tab, setTab] = useState<Tab>("armor");
  // 两路各自独立的缩放与平移。
  const [viewA, setViewA] = useState<ViewTransform>(IDENTITY_VIEW);
  const [viewB, setViewB] = useState<ViewTransform>(IDENTITY_VIEW);
  // 队名以快照为准（后端会规范化）。
  const names = snapshot.config.teamNames;
  const panes = useMemo(
    () =>
      [
        {
          key: "a",
          camera: snapshot.slots.cameraA,
          armor: snapshot.slots.armorA,
          team: 0,
          // 左格的血条贴左上角，右格贴右上角：与用户端"自己在左上、对手在右上"一致。
          align: "left" as const,
          view: viewA,
          onView: setViewA,
        },
        {
          key: "b",
          camera: snapshot.slots.cameraB,
          armor: snapshot.slots.armorB,
          team: 1,
          align: "right" as const,
          view: viewB,
          onView: setViewB,
        },
      ].map((pane) => ({
        ...pane,
        stats: snapshot.stats.find((entry) => entry.camera === pane.camera),
        health: snapshot.health.find((entry) => entry.team === pane.team) ?? snapshot.health[0],
        opponent: snapshot.health.find((entry) => entry.team !== pane.team) ?? null,
      })),
    [snapshot.slots, snapshot.stats, snapshot.health, viewA, viewB],
  );
  /**
   * 改一边的队名。
   *
   * 命令一次只改一边，所以这里**不**把另一边的名字一起带上：那是"读两条、写两条"，
   * 而读来的值来自最多 200 ms 前的快照——紧接着改另一边就会把它覆盖回去。
   */
  const saveName = (team: number, value: string) => {
    void api.setTeamName(team, value).catch((err) => {
      onError(err instanceof Error ? err.message : String(err));
    });
  };
  return (
    <div className="page">
      <TopBar snapshot={snapshot} onOpenSettings={onOpenSettings} />
      <div className="referee-stage">
        {panes.map((pane) => {
          // 这一下落在哪一格：指定了装甲板就比板子 id，否则退回比队伍号。
          const hitRelevant = Boolean(
            lastHit &&
              (pane.armor !== null ? lastHit.board === pane.armor : lastHit.team === pane.team),
          );
          const label = teamName(pane.team, names);
          return (
            <section key={pane.key} className="pane">
              <VideoSurface
                camera={pane.camera}
                emptyText={
                  pane.stats?.hasFrames
                    ? ""
                    : pane.stats?.online
                      ? "已连接，等待画面…"
                      : `等待${label}的图传`
                }
                mirrored={snapshot.mirrored}
                // 裁判端不给瞄准器：这里没有人在瞄。网格留着，用来比对两路的取景。
                crosshair={null}
                grid={hud.grid}
                view={pane.view}
                onView={pane.onView}
                hit={
                  hitRelevant && lastHit
                    ? { seq: lastHit.seq, damage: lastHit.damage, at: lastHit.receivedAt }
                    : null
                }
                hitFeedback={hud.hitFeedback}
                showZoom
              >
                {hud.health.visible && (
                  <div className={`video-hud video-hud--${pane.align}`}>
                    <HealthBar health={pane.health} config={hud.health} align={pane.align} />
                  </div>
                )}
                <MatchBanner
                  outcome={pane.health.outcome}
                  mine={pane.health.name}
                  theirs={
                    pane.opponent?.name ?? teamName(pane.team === 0 ? 1 : 0, names)
                  }
                />
                <HitFlash
                  hit={lastHit}
                  config={hud.hitFeedback}
                  relevant={hitRelevant}
                  label={`${label}被打中`}
                />
              </VideoSurface>
              <div className="pane__foot">
                <TeamNameEditor
                  team={pane.team}
                  name={pane.health.name}
                  onSave={(value) => saveName(pane.team, value)}
                />
                <StatsLine stats={pane.stats} diagnostics={snapshot.diagnostics} />
              </div>
            </section>
          );
        })}
      </div>
      <div className="referee-bottom">
        <div className="tabs">
          <button
            className={`tab${tab === "armor" ? " tab--active" : ""}`}
            onClick={() => setTab("armor")}
          >
            装甲板（{snapshot.armorBoards.length}）
          </button>
          <button className={`tab${tab === "media" ? " tab--active" : ""}`} onClick={() => setTab("media")}>
            录制与回放{snapshot.recordings.length > 0 ? ` · 进行中 ${snapshot.recordings.length}` : ""}
          </button>
          <span className="tabs__spacer" />
          <Button
            variant="ghost"
            onClick={() =>
              void api
                .refresh()
                .catch((err) => onError(err instanceof Error ? err.message : String(err)))
            }
          >
            刷新
          </Button>
        </div>
        <div className="referee-bottom__body">
          {tab === "armor" ? (
            <ArmorTable
              boards={snapshot.armorBoards}
              slots={snapshot.slots}
              names={names}
            />
          ) : (
            <MediaPanel snapshot={snapshot} onError={onError} onInfo={onInfo} />
          )}
        </div>
      </div>
    </div>
  );
 }
@@ -0,0 +1,147 @@
 /**
 * 用户端：一路画面 + 双方血条 + 瞄准器 + 胜负横幅。
 *
 * 界面上的东西按"操作手需要什么"排：
 *
 * - 画面占满除底部状态行以外的全部空间（一个像素都不浪费在装饰上）；
 * - **血条叠在画面两个上角**：左上角是自己，右上角是对手。血量是这一屏上最需要"同时看到"
 *   的两个数，放在画面之外意味着视线要离开取景；
 * - 瞄准器画在画面里（`VideoSurface` 负责），位置跟着图像走；
 * - 被打中时整屏闪一下红、瞄点旁跳一个伤害数字——**画面不抖**（见 `HitFeedbackConfig`）；
 * - 一方归零之后，画面正中给出「胜利 / 击败」。
 */
 import { useMemo, useState } from "react";
 import { IDENTITY_VIEW, VideoSurface, type ViewTransform } from "../components/VideoSurface";
 import { HealthBar, healthTag } from "../components/HealthBar";
 import { HitFlash } from "../components/HitFlash";
 import { MatchBanner } from "../components/MatchBanner";
 import { StatsLine } from "../components/ArmorTable";
 import { TopBar } from "../components/TopBar";
 import { Button } from "../components/controls";
 import { teamName } from "../lib/format";
 import { useAppStore } from "../lib/store";
 import type { HudView, Snapshot, TeamHealthDto } from "../lib/types";
 interface Props {
  snapshot: Snapshot;
  hud: HudView;
  onOpenSettings: () => void;
  /** 是否在瞄准器校准模式（开关在设置面板里）。 */
  calibrating: boolean;
  /** 校准模式下拖动画面：把屏幕位移换算成画面比例位移。 */
  onCalibrate: (dxFraction: number, dyFraction: number) => void;
 }
 export function TeamPage({
  snapshot,
  hud,
  onOpenSettings,
  calibrating,
  onCalibrate,
 }: Props) {
  const [view, setView] = useState<ViewTransform>(IDENTITY_VIEW);
  const { lastHit } = useAppStore();
  const camera = snapshot.config.cameraId;
  const stats = useMemo(
    () => snapshot.stats.find((entry) => entry.camera === camera),
    [snapshot.stats, camera],
  );
  // 快照里两边都有一份，**按队伍号取**而不是按下标：绑的是队伍二时 `health[0]` 是别人。
  const mine: TeamHealthDto =
    snapshot.health.find((entry) => entry.team === snapshot.team) ?? snapshot.health[0];
  const theirs: TeamHealthDto | null =
    snapshot.health.find((entry) => entry.team !== snapshot.team) ?? null;
  const theirTeam = snapshot.team === 0 ? 1 : 0;
  const myName = mine?.name ?? teamName(snapshot.team, snapshot.config.teamNames);
  const theirName = theirs?.name ?? teamName(theirTeam, snapshot.config.teamNames);
  // 这一下是不是打在我身上：绑定了装甲板就比板子 id，没绑定就退回比队伍号。
  const hitIsMine = Boolean(
    lastHit &&
      (mine?.board != null ? lastHit.board === mine.board : lastHit.team === snapshot.team),
  );
  const pulse = hitIsMine && lastHit ? { seq: lastHit.seq, damage: lastHit.damage, at: lastHit.receivedAt } : null;
  if (camera === null) {
    return (
      <div className="page">
        <TopBar snapshot={snapshot} onOpenSettings={onOpenSettings} />
        <div className="page__center">
          <h2>还没有绑定摄像头</h2>
          <p className="dim">
            用户端要先选一块图传板（就是装在这台车上的那一块）。绑定会写进配置文件，重启后
            仍然生效；以后要改需要密码。
          </p>
          <Button variant="primary" onClick={onOpenSettings}>
            选择摄像头
          </Button>
        </div>
      </div>
    );
  }
  return (
    <div className="page">
      <TopBar snapshot={snapshot} onOpenSettings={onOpenSettings} />
      <div className="team-stage">
        <VideoSurface
          camera={camera}
          emptyText={stats?.hasFrames ? "" : stats?.online ? "已连接，等待画面…" : "离线：这块板子还没广播"}
          mirrored={snapshot.mirrored}
          crosshair={hud.crosshair}
          grid={hud.grid}
          view={view}
          onView={setView}
          calibrating={calibrating}
          onCalibrate={calibrating ? onCalibrate : undefined}
          hit={pulse}
          hitFeedback={hud.hitFeedback}
          showZoom={hud.showZoom}
        >
          {hud.health.visible && (
            <>
              <div className="video-hud video-hud--left">
                <HealthBar
                  health={mine}
                  config={hud.health}
                  align="left"
                  tag={healthTag(mine, snapshot.team)}
                />
              </div>
              <div className="video-hud video-hud--right">
                {theirs && (
                  <HealthBar
                    health={theirs}
                    config={hud.health}
                    align="right"
                    tag={healthTag(theirs, snapshot.team)}
                  />
                )}
              </div>
            </>
          )}
          {/* 结论只看自己这一份：后端的 outcome 就是"从这一边看"的。 */}
          <MatchBanner outcome={mine?.outcome ?? null} mine={myName} theirs={theirName} />
          <HitFlash hit={lastHit} config={hud.hitFeedback} relevant={hitIsMine} />
        </VideoSurface>
      </div>
      <footer className="statusbar">
        <StatsLine stats={stats} diagnostics={snapshot.diagnostics} />
        <span className="dim">
          滚轮缩放 · 拖动平移（放大后） · 双击复位
          {calibrating && " · 校准中：拖动画面挪动瞄准点"}
        </span>
      </footer>
    </div>
  );
 }
@@ -0,0 +1,25 @@
 {
  "compilerOptions": {
    "target": "ES2022",
    "useDefineForClassFields": true,
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": false,
    "types": ["vite/client"]
  },
  "include": ["src"],
  "references": [{ "path": "./tsconfig.node.json" }]
 }
@@ -0,0 +1,15 @@
 {
  "compilerOptions": {
    // 被引用的工程（project reference）不能关掉 emit：tsc 需要它来产出 .tsbuildinfo，
    // 否则会报 TS6310。构建产物落到 node_modules/.tmp，不进仓库。
    "composite": true,
    "skipLibCheck": true,
    "module": "ESNext",
    "moduleResolution": "bundler",
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "emitDeclarationOnly": true,
    "outDir": "node_modules/.tmp/tsconfig.node"
  },
  "include": ["vite.config.ts"]
 }
@@ -0,0 +1,28 @@
 import { defineConfig } from "vite";
 import react from "@vitejs/plugin-react";
 // Tauri 在开发模式下把 devUrl 指向这个端口，所以它必须固定——换成随机端口的话
 // tauri.conf.json 里的 devUrl 就对不上了。
 //
 // `clearScreen: false` 让 vite 不要清掉终端：外面是 tauri-cli 在跑，cargo 的编译
 // 输出与 vite 的输出共用这一个终端，清屏会把编译错误冲掉。
 export default defineConfig({
  plugins: [react()],
  clearScreen: false,
  server: {
    port: 1420,
    strictPort: true,
    host: "127.0.0.1",
    // src-tauri 与 core 的改动由 cargo 负责重建，让 vite 不要跟着刷新两遍。
    watch: {
      ignored: ["**/src-tauri/**", "**/core/**", "**/target/**"],
    },
  },
  build: {
    // macOS 上跑的是 WKWebView，不是需要兼容老浏览器的页面。
    target: "safari15",
    sourcemap: false,
    outDir: "dist",
    emptyOutDir: true,
  },
 });
@@ -1,14 +1,17 @@
 # Name,     Type, SubType,  Offset,   Size,     Flags
 #
-# The app partition starts at 0x40000 rather than the usual 0x10000 on purpose:
+# The app partition offset here is chosen by scripts/flash.sh, not by hand. It
-# the module this firmware was first brought up on has a defective byte in its
+# sits well above the usual 0x10000 because the module this firmware was first
-# SPI flash at 0xFADE7 (bits 5..7 cannot be programmed). The app image is
+# brought up on has a defective byte in its SPI flash at 0xFADE7 (bits 5..7
-# unchanged by where it is placed, so moving the partition moves which image byte
+# cannot be programmed). The app image is unchanged by where it is placed, so
-# lands on that address - and at 0x40000 the byte there is 0x1A, which the flash
+# moving the partition moves which image byte lands on that address - and
-# accepts.
+# because a rebuild can shift the image again, re-deriving the offset by hand
 # would break on the next build. flash.sh picks the lowest 64 KB-aligned offset
 # whose byte at that address the flash can actually store, writes it back here,
 # and rebuilds.
 #
-# If you move to healthy hardware, put `factory` back at 0x10000 and delete the
+# If you move to healthy hardware, put `factory` back at 0x10000 and delete
-# note in sdkconfig.defaults; nothing else depends on this.
+# BAD_FLASH_ADDR from scripts/flash.sh; nothing else depends on this.
 nvs,        data, nvs,      0x9000,   0x6000,
 phy_init,   data, phy,      0xf000,   0x1000,
 factory,    app,  factory,  0x060000,  0x120000,
@@ -1,49 +1,95 @@
 # protocol
-摄像头 UDP 图传的线路格式，**固件与客户端共用**。
+摄像头 UDP 图传的线路格式，**固件与两端客户端共用**。
 ```
 protocol/   线路格式 + 帧重组    （13 个单元测试，无 ESP-IDF 依赖）
 .           固件  -> ESP32-S3    （交叉编译，Xtensa）
 client/     桌面客户端           （Slint，两种身份）
 ```
 这是本仓库里最该被测试的部分：帧重组和编码都极易出微妙错误，而这两件事都无法
 在固件上验证——你只会看到"不出画面"。
-因此它没有 ESP-IDF 依赖，会为宿主架构编译：
+因此它为宿主架构编译，与 ESP-IDF 完全无关：
 ```sh
-cargo test
+cd protocol && cargo test
 ```
 ```
-7 passed
+13 passed
 ```
 ## 拓扑
 ```text
                    ┌──────────────────────────────┐
                    │  裁判终端（PC，仅显示）      │
                    │  队伍一 + 队伍二 + 双方血量   │
                    └───────────────┬──────────────┘
                                    │  同一个局域网，广播可用
               ┌────────────────────┼────────────────────┐
               │                    │                    │
       ┌───────┴───────┐    ┌───────┴───────┐    ┌───────┴───────┐
       │  图传板 A     │    │  图传板 B     │    │  装甲板 ×4    │
       │  (队伍一)     │    │  (队伍二)     │    │  (预留，未实现) │
       └───────────────┘    └───────────────┘    └───────────────┘
 ```
 两块板子不区分队伍——它们只知道自己是谁（MAC 派生的 id），"哪一边"由客户端决定。
 烧同一份固件即可，配置在客户端一侧。
 ## 线路格式
-每个数据报 = 20 字节头 + 至多 1400 字节 JPEG 数据：
+每个数据报 = **27 字节头** + 至多 **1400 字节**载荷：
-```
+```text
 0                   1                   2                   3
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
-+-------------------------------+-------------------------------+
+-------------------------------+-------+-----------------------+
-|          magic (u32)          |        frame_id (u32)         |
+|          magic (u32)          | type  |      version (u16)    |
-+-------------------------------+-------------------------------+
+-------------------------------+-------+-----------------------+
 |         sender_id (u32)       |          frame_id (u32)     |
 +-------------------------------+-------+-----------------------+
 |     frag_index (u16)         |      frag_count (u16)      |
-+-------------------------------+-------------------------------+
+-------------------------------+-------+-----------------------+
 |          total_len (u32)      |  width (u16) | height (u16)   |
 +-------------------------------+---------------+---------------+
 |                     payload (0..=1400)                        |
 +---------------------------------------------------------------+
 ```
-全部整数为**小端**——ESP32-S3（Xtensa）和所有桌面架构都原生如此，编解码就是
+全部整数**小端**——ESP32-S3（Xtensa）和所有桌面架构都原生如此，编解码就是
 `to_le_bytes` / `from_le_bytes`，没有字节序转换步骤。
- `magic` 固定值，用于把同端口上的无关 UDP 包挡掉。
+`msg_type` 决定同一端口上的字节如何解释，这是视频、发现、装甲板能共用一个端口的
- `total_len` 是整张 JPEG 的长度，接收端据此预分配缓冲并判断帧是否完整。
+前提：
- `width`/`height` 每个分片都重复携带（不只是第 0 个），这样每个数据报都能独立
+
 | type | 方向 | 用途 |
 |---|---|---|
 | 1 `Video` | 板子 → 客户端 | 一帧 JPEG 的第 N 个分片 |
 | 2 `Subscribe` | 客户端 → 板子 | "我是这个角色，请给我画面" |
 | 3 `Hello` | 板子 → 客户端 | "我在线，我是谁" |
 | 4 `Heartbeat` | 板子 → 客户端 | 同上，心跳形式 |
 | 5 `ArmorHealth` | 装甲板 → 客户端 | 血量（**预留，当前无实现**） |
 ### 三个设计决定
 **27 字节不凑整。** 头只占每个 1427 字节数据报的 1.9%，而为对齐在固件和客户端两侧
 各写一段手写偏移常量，是引入静默错位的更划算的代价。
 **`sender_id` 是多路的前提。** 裁判终端同时收两块板子，靠它在同一端口上区分来源。
 **`width`/`height` 每个分片都重复携带**（不只是第 0 个），这样每个数据报都能独立
 解析，中途加入的接收端也能立刻知道分辨率。
-## 为什么是 UDP 而不是 TCP
+**`version` 不匹配就拒收**，而不是按错误布局继续解析——后者会表现为随机崩溃或画面
 错乱，比拒绝连接难查得多。
-这是本 crate 存在的原因，也是实测数据：
+## 为什么视频走 UDP 而不是 TCP
 实测（VGA 640x480，传感器产出 22 fps）：
 | | TCP（HTTP MJPEG） | UDP |
 |---|---|---|
@@ -51,45 +97,114 @@ cargo test
 | 客户端实际收到 | **1.9 fps** | **20.8 fps** |
 | 实际吞吐 | 0.28 Mbit/s | 1.72 Mbit/s |
-关键在于**链路是空的**：TCP 那一栏只用了链路能力的 1% 左右（ESP32-S3 在良好的
+TCP 那一栏只用了链路能力的 1% 左右（ESP32-S3 在良好 2.4GHz 链路上 TCP 实测上限
-2.4GHz 链路上，TCP 实测上限约 20–30 Mbit/s），帧却堵在队头阻塞后面等一个实时画面
+约 20–30 Mbit/s）。**链路是空的**，帧却堵在队头阻塞后面等一个实时画面等不起的
-等不起的重传计时器。
+重传计时器。
-UDP 没有任何重传与确认：缺了分片的帧被整个丢弃，下一帧顶上。这换来低延迟，也把
+UDP 没有重传与确认：缺了分片的帧整个丢弃，下一帧顶上。这换来低延迟，也把本来就
-本来就有的带宽真正用起来了——但即便如此也只用掉 6–9%，说明瓶颈从头到尾都不在
+有的带宽真正用起来了——但即便如此也只用掉 6–9%，说明瓶颈从头到尾都不在带宽上。
 带宽上。
 ## 接收端的取舍
-`FrameAssembler` 的策略就是全部要点：**只有分片全部到齐才显示该帧，且最新的帧永远
+`FrameAssembler` 的策略就是全部要点：**一张帧只有所有分片都到齐才交付，且最新的
-优先。**
+帧永远优先。**
-UDP 不保证跨数据报的顺序或到达，所以试图"补洞"的接收端做的功比"等下一张完整帧"
+UDP 不保证跨数据报的顺序与到达，所以试图"补洞"的接收端做的功比"等下一张完整帧"
 更多——而且补的过程中会显示撕裂的画面。
-另外有一个有界超时，用来堵住另一种失败模式：发送方在帧中途死掉时，半截缓冲会
+### 按发送方分开
 永远留在这里。
-| 字段 | 含义 |
+**每个发送方必须有自己的重组器。** 两块板子的 `frame_id` 各自独立计数，塞进同一个
-|---|---|
+重组器会让它们互相顶掉，两路都出不来。
 | `frag_count == 0` | 非法，立即拒绝 |
 | `frag_index >= frag_count` | 自相矛盾，立即拒绝 |
 | `payload_len > total_len` | 损坏，立即拒绝（在造成大额分配之前就挡住） |
-## 发送端
+### 重复分片必须去重
-`fragment_frame()` 从 JPEG 长度推出分片数，因此调用方不可能产出与自身矛盾的
+`FrameAssembler` 按分片下标记录是否收到，重复的直接跳过且不计数，并显式确认最后一个
-分片集合。
+分片确实到过。
 用单一计数 `seen >= expected` 判断收齐不够健壮：一个丢失的分片若能被某个分片的副本
 凑数，计数就达标了，而缓冲区里留着空洞，交出去一张尾部是 0 的 JPEG。两个测试专门覆盖
 它（`a_duplicate_cannot_complete_a_frame_with_a_hole`、
 `a_gap_that_is_never_filled_never_yields_a_frame`）。
 **不过要说清楚：在实测链路上一次重复投递都没出现过。** 一到两个订阅者、20 秒 2000+
 个分片，重复数为 0（固定端口与临时端口两种订阅方式都试过）。所以这层防护是为了正确
 性，不是为了修一个正在发生的故障。
 它防的是"哪天真的重复了"——那时症状是**帧率完全正常、没有任何报错线索**，只有偶尔
 几张图解不出来，比一次崩溃难查得多。
 ### 按 frame_id 隔离，换帧即放弃
 每个 `FrameAssembler` **按 `frame_id` 隔离**状态：`frame_id` 一变就重置，之前那帧的半
 成品直接丢掉。
 不隔离的后果很具体——某帧丢了分片之后，下一帧的分片会接着往同一个计数器里凑，凑够
 了就交出去一张**混着两帧**的 JPEG。
 这个坑我踩过：`scripts/udp_probe.py` 最初只按 `sender_id` 存重组状态，于是 10 秒里报出
 34 张"JPEG 不完整"。那个数字看起来像丢包或重复分片的证据，我据此给 `protocol` 写了一
 个"修复重复分片"的提交和一段因果说明——**结论是错的**，那段归因比它揭示的 bug 更值得
 记下来。修掉之后同样 14 秒内是 0 张。
 探到坏帧时，先怀疑测量工具。
 ### 有界超时
 发送方在帧中途死掉时，半截缓冲会永远留在重组器里。`expire()` 堵住这个。
 ### 发送端的复用
 `Fragment::encode_into()` 追加写入而不分配：发送端对每帧的每个分片复用同一个缓冲，
-在 22fps 下这是每秒约 250 次分配与不分配的区别——在 WiFi 栈也要抢内部 RAM 的芯片
+在 22fps 下这是每秒约 250 次分配与不节省别的差别——在这块同时要抢内部 RAM 的芯片
-上，这个差别很实在。
+上很实在。
 `fragment_frame()` 从 JPEG 长度推出分片数，因此调用方不可能产出与自身矛盾的集合。
 ## 拒收条件
 `Fragment::decode` 会挡掉这些，`FrameAssembler` 不必再操心：
 | 条件 | 为什么 |
 |---|---|
 | `magic` 不符 | 同端口上可能有别的协议 |
 | `version` 不符 | 按错误布局解析比拒收难查 |
 | 长度不足 27 字节 | 可能是存活探测包（1 字节） |
 | `frag_count == 0` | 自相矛盾 |
 | `frag_index >= frag_count` | 自相矛盾 |
 | 载荷比 `total_len` 还长 | 损坏，且在造成大额分配之前就该挡住 |
 ## 不变量
- 一个数据报不超过 `HEADER_LEN + MAX_FRAGMENT_PAYLOAD` = 1420 字节，低于典型以太网
+- 一个数据报不超过 `HEADER_LEN + MAX_FRAGMENT_PAYLOAD` = **1427 字节**，低于典型
-  的 1500 MTU。
+  以太网的 1500 MTU。
-  这一点比看起来重要：超过 MTU 的数据报要么被 AP 丢掉，要么被 IP 分片，而两种情况
+  这一点比看起来重要：超 MTU 的数据报要么被 AP 丢弃，要么被 IP 分片，两种情况的
-  的丢包都会**记在应用账上**而不是网络账上——后者本来更容易排查。
+  丢包都**记在应用账上**而不是网络账上——后者本来更容易排查。
- VGA 下 `MAX_FRAGMENT_PAYLOAD` 对应每帧 8–10 个数据报。
+- VGA 下每帧约 17 个分片。
 - `DEFAULT_PORT` = 5600，两端共用同一个常量。
 - `ARMOR_PORT` = 5601，装甲板预留，当前无实现。
 ## 身份
 `id_from_mac()` 用固定长度输入的 FNV-1a 从 MAC 派生 `sender_id`。
 **用 MAC 而不是 IP**，因为客户端要把绑定存进配置文件并在重启后继续有效——DHCP 换
 地址是常态，MAC 不会变。用 MAC 也意味着烧同一份固件即可，不需要任何"我是谁"的配置。
 返回值避开 0，那是裁判终端的保留值。哈希有测试保证稳定性与不撞车。
 ## 独立核对
 `scripts/udp_probe.py` 手写了这里的每一个常量，**不依赖本 crate**。
 这正是它的价值：如果本 crate 的编码有错，脚本仍按文档解析，会立刻报出不一致。反面
 例子也有——它的 `role` 字节曾多填 12 个零字节，固件按偏移严格读取因而拒收，表现为
 "板子在线但 0 clients subscribed"。改协议时记得同步它。
 ## 装甲板（预留）
 `ArmorHealth` 与 `ARMOR_PORT` 已就位，`MsgType` 也留了 5 号。现在没有实现也没有
 数据源，裁判界面显示占位符而不是 0——**0 看起来像真值，现场看到会以为对方已经没
 血了**。
 接上以后板子向 `ARMOR_PORT` 发这个结构，客户端监听即可，界面与其它代码都不用改。
@@ -453,14 +453,14 @@ impl Hello {
 }
 // ---------------------------------------------------------------------------
-// 装甲板（预留）
+// 装甲板
 // ---------------------------------------------------------------------------
 /// 一块装甲板的上报。
 ///
-/// 现在没有实现也没有数据源，但格式在这里定下来，并且 [`MsgType::ArmorHealth`]
+/// 由 `armor/armor-firmware` 里的主板（ESP32-C3）广播到 [`ARMOR_PORT`]，裁判终端监听
-/// 与 [`ARMOR_PORT`] 已经就位：板子接上以后向 `ARMOR_PORT` 发这个结构，裁判终端
+/// 该端口并把它显示成四格血量。整车一条血量，所以四条上报的 `hp` 相同、`index`
-/// 监听即可，界面与其它代码都不用改。
+/// 分别是 0..3。
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct ArmorHealth {
    /// 哪一边：0 = 队伍一，1 = 队伍二。
@@ -472,10 +472,20 @@ pub struct ArmorHealth {
 }
 impl ArmorHealth {
    /// 编码成线上字节，帧头的 `sender_id` 留 0。
    ///
    /// 0 是 [`REFEREE_ID`]，所以板子发的时候应该用 [`encode_from`](Self::encode_from)
    /// 填上自己的 id（由 MAC 派生），抓包时才能分辨是哪块板子。
    pub fn encode(&self) -> Vec<u8> {
        self.encode_from(0)
    }
    /// 与 [`encode`](Self::encode) 相同，但帧头带上发送方自己的 id。
    pub fn encode_from(&self, sender_id: u32) -> Vec<u8> {
        let header = Header {
            msg_type: MsgType::ArmorHealth,
            version: PROTOCOL_VERSION,
            sender_id,
            ..Default::default()
        };
@@ -488,17 +498,32 @@ impl ArmorHealth {
    }
    pub fn decode(bytes: &[u8]) -> Option<Self> {
        Self::decode_from(bytes).map(|(_, health)| health)
    }
    /// 与 [`decode`](Self::decode) 相同，但把帧头里的 `sender_id` 一起返回。
    ///
    /// 板子用 [`encode_from`](Self::encode_from) 把自己的 MAC 派生 id 填进去，所以
    /// 这一个 u32 就是**哪块装甲板主板在说话**。裁判端与队伍端要列出"场上有哪几块
    /// 装甲板"并让用户选中其中一块，靠的就是它——没有它就只剩 `team` 字段，
    /// 同队的两块板子无从区分。
    ///
    /// 保持 [`decode`](Self::decode) 不变是有意的：`team`/`index`/`hp` 是上报的语义，
    /// 而 `sender_id` 是链路层的信封，不需要它的人不该被迫处理它。
    pub fn decode_from(bytes: &[u8]) -> Option<(u32, Self)> {
        let header = decode_header(bytes)?;
        if header.msg_type != MsgType::ArmorHealth || bytes.len() < HEADER_LEN + 4 {
            return None;
        }
-        Some(ArmorHealth {
+        let health = ArmorHealth {
            team: bytes[HEADER_LEN],
            index: bytes[HEADER_LEN + 1],
            hp: u16::from_le_bytes(bytes[HEADER_LEN + 2..HEADER_LEN + 4].try_into().ok()?),
-        })
+        };
        Some((header.sender_id, health))
    }
 }
@@ -540,8 +565,13 @@ pub struct FrameAssembler {
    height: u16,
    since: Option<std::time::Instant>,
    timeout: std::time::Duration,
-    /// 已收到的分片数，含重复。用来统计网络丢了多少。
+    /// 已收到的分片数（不含重复）。用来统计网络丢了多少。
    seen: usize,
    /// 每个分片是否已收到。
    ///
    /// 存在的原因是 `seen` 会被重复包灌水：UDP 会重复投递，一个丢失的分片可以
    /// 被另一个包的副本凑数，于是"收够了"却留着空洞，交出去一张尾部是 0 的坏图。
    have: Vec<bool>,
 }
 impl FrameAssembler {
@@ -557,6 +587,7 @@ impl FrameAssembler {
            since: None,
            timeout,
            seen: 0,
            have: Vec::new(),
        }
    }
@@ -602,12 +633,32 @@ impl FrameAssembler {
                self.height = frag.header.height;
                self.since = Some(std::time::Instant::now());
                self.seen = 0;
                self.have.clear();
                self.have.resize(self.expected, false);
            }
            Some(id) if id == frame_id => {}
            _ => unreachable!("current_id was just reconciled with frame_id"),
        }
-        let start = frag.header.frag_index as usize * MAX_FRAGMENT_PAYLOAD;
+        let index = frag.header.frag_index as usize;
        // 重复分片直接跳过，且**不**增加计数。
        //
        // 用 `seen` 一个计数判断收齐是不够健壮的：一个丢失的分片若能被某个分片的
        // 副本凑数，计数就达标了，而缓冲区里留着空洞，交出去一张尾部是 0 的 JPEG。
        // 位图让"收到过"这件事是显式的，不用靠计数的算术去推断。
        //
        // 要说明的是：在本项目实测的链路上（2.4GHz AP，一到两个订阅者，20 秒 2000+
        // 个分片）**一次重复投递都没出现过**，所以这层防护是为了正确性而不是为了
        // 修一个正在发生的故障。之前观察到的 34 张坏 JPEG 另有原因：探测脚本自己
        // 的重组状态只按 sender_id 存、不按 frame_id 存，于是丢片之后下一帧的分片
        // 会接着凑上一帧的计数。那个脚本已修，见 scripts/udp_probe.py。
        if self.have[index] {
            return Err(DropReason::Superseded);
        }
        self.have[index] = true;
        let start = index * MAX_FRAGMENT_PAYLOAD;
        let end = start + frag.payload.len();
        if end > self.buffer.len() {
@@ -616,7 +667,12 @@ impl FrameAssembler {
        self.buffer[start..end].copy_from_slice(&frag.payload);
        self.seen += 1;
-        if self.seen >= self.expected {
+        // 计数达标还不够：最后一个分片必须真的到过，否则中间可能缺一块。
        // 显式检查尾块，比依赖计数的算术更直接，也更容易看出意图。
        let tail_index =
            (frag.header.total_len as usize).saturating_sub(1) / MAX_FRAGMENT_PAYLOAD;
        if self.seen >= self.expected && self.have[tail_index] {
            let total = frag.header.total_len as usize;
            self.buffer.truncate(total.min(self.buffer.len()));
@@ -660,6 +716,7 @@ impl FrameAssembler {
        self.buffer.shrink_to_fit();
        self.since = None;
        self.seen = 0;
        self.have = Vec::new();
    }
 }
@@ -827,8 +884,7 @@ mod tests {
    #[test]
    fn armor_health_roundtrips() {
-        // 现在没有实现，但格式必须先定下来并且可往返，否则接上板子时才发现布局
+        // 现在有实现了（armor/ 里的 ESP32-C3 固件在发它），布局必须保持可往返。
        // 不兼容就晚了。
        let hp = ArmorHealth {
            team: 1,
            index: 2,
@@ -839,6 +895,52 @@ mod tests {
        assert_eq!(ArmorHealth::decode(&encoded), Some(hp));
    }
    #[test]
    fn armor_health_can_carry_the_sending_board_id() {
        let hp = ArmorHealth {
            team: 0,
            index: 3,
            hp: 97,
        };
        let encoded = hp.encode_from(0x1234_5678);
        assert_eq!(
            decode_header(&encoded).map(|h| h.sender_id),
            Some(0x1234_5678),
            "抓包时要能分辨是哪块装甲板发的"
        );
        assert_eq!(ArmorHealth::decode(&encoded), Some(hp));
        // 帧头 id 不影响帧体，也不该影响旧调用方的行为。
        assert_eq!(ArmorHealth::decode(&hp.encode()), Some(hp));
        assert_eq!(decode_header(&hp.encode()).map(|h| h.sender_id), Some(0));
    }
    #[test]
    fn armor_health_decode_from_returns_the_board_id() {
        // 客户端要列出"场上有哪几块装甲板"，只能靠帧头里这个 id：team 只有 0/1，
        // 同队的两块板子在 team 上无法区分。
        let hp = ArmorHealth {
            team: 1,
            index: 1,
            hp: 100,
        };
        assert_eq!(
            ArmorHealth::decode_from(&hp.encode_from(0xABCD_1234)),
            Some((0xABCD_1234, hp))
        );
        // decode 是 decode_from 丢掉信封的那一半，两者必须一致。
        assert_eq!(
            ArmorHealth::decode(&hp.encode_from(0xABCD_1234)),
            ArmorHealth::decode_from(&hp.encode_from(0xABCD_1234)).map(|(_, h)| h)
        );
        // 不是装甲板上报就不该解出来。
        assert!(ArmorHealth::decode_from(&[0u8; 8]).is_none());
    }
    #[test]
    fn ids_are_stable_and_never_zero() {
        let mac = [0x90, 0x70, 0x69, 0xF8, 0xF2, 0x14];
@@ -852,6 +954,50 @@ mod tests {
        assert_ne!(a, id_from_mac(&[1, 2, 3, 4, 5, 6]));
    }
    #[test]
    fn a_duplicate_cannot_complete_a_frame_with_a_hole() {
        // UDP 会重复投递。一个丢失的分片若能被另一片的副本凑数，接收端就会以为
        // 收齐了，交出一张中间是 0 的坏 JPEG——而且帧率正常、没有任何报错线索。
        let jpeg: Vec<u8> = (0..5000u32).map(|i| (i % 251) as u8).collect();
        let frags = fragment_frame(1, 1, &jpeg, 640, 480);
        let mut asm = FrameAssembler::new(std::time::Duration::from_secs(2));
        // 丢掉第 2 片，然后把第 0 片连送三次来灌 seen。
        for f in frags.iter().filter(|f| f.header.frag_index != 2) {
            let _ = asm.push(f.clone());
        }
        for _ in 0..3 {
            assert!(
                asm.push(frags[0].clone()).is_err(),
                "a duplicate must not be allowed to complete the frame"
            );
        }
        assert!(asm.is_in_progress(), "the hole must keep it incomplete");
        // 补上真正的第 2 片，才在这一片上收齐——所以结果要从这一次的返回值拿。
        let completed = asm.push(frags[2].clone());
        assert_eq!(
            completed.expect("completes once the hole is filled").data,
            jpeg,
        );
    }
    #[test]
    fn a_gap_that_is_never_filled_never_yields_a_frame() {
        let jpeg = vec![0xAAu8; 5000];
        let frags = fragment_frame(1, 1, &jpeg, 640, 480);
        let mut asm = FrameAssembler::new(std::time::Duration::from_secs(2));
        // 反复送同一片，永远凑不齐——接收端必须一直等着，而不是交出半张图。
        for _ in 0..50 {
            assert!(asm.push(frags[0].clone()).is_err());
        }
        assert!(asm.is_in_progress(), "50 duplicates must not complete a frame");
        assert_eq!(asm.sender_id(), 1, "and it must still be the same camera");
    }
    #[test]
    fn empty_jpeg_still_produces_one_fragment() {
        let frags = fragment_frame(1, 1, &[], 64, 48);
@@ -0,0 +1,2 @@
 CompileFlags:
    Remove: [-f*, -m*]
@@ -0,0 +1,106 @@
 # =============================================================================
 #  armor — 文本/二进制归属与行尾（CRLF/LF）策略
 # -----------------------------------------------------------------------------
 #  规则：仓库里一律存 LF；工作区只在 Windows 原生脚本上使用 CRLF。
 #  目的：
 #    * 避免不同机器（core.autocrlf 开着/关着）之间产生"整文件假改动"；
 #    * 让 diff / blame / 合并只在真正改动的行上出现；
 #    * .ps1/.bat/.cmd 保持 CRLF，兼容 cmd.exe 与习惯 Windows 的工具链。
 #
 #  注意：.gitattributes 的 text/eol 属性优先级高于 core.autocrlf。
 #        本文件用 "* text=auto eol=lf" 覆盖了所有路径，所以无论别人本机
 #        core.autocrlf 是 true / false / 未设置，入库结果都完全一致（已实测）。
 #        若想改成"工作区也全用 LF"（含 .ps1），只需把第 1 节的
 #        eol=crlf 全部改成 eol=lf，其余规则不用动。
 #
 #  核对命令：
 #    git check-attr -a -- <路径>     查看某路径最终生效的属性
 #    git ls-files --eol              查看已入库文件的 i/(索引) w/(工作区) 行尾
 # =============================================================================
 # 默认：内容自动判定是否为文本；文本一律在索引与工作区使用 LF
 * text=auto eol=lf
 # =============================================================================
 # 1. Windows 原生脚本 —— 工作区保持 CRLF
 # =============================================================================
 # cmd.exe 对纯 LF 的 .bat/.cmd 处理有坑（尤其是带 label/goto 的脚本），
 # 必须 CRLF；.ps1/.psm1 按 Windows 惯例也保持 CRLF。
 *.ps1   text eol=crlf
 *.psm1  text eol=crlf
 *.bat   text eol=crlf
 *.cmd   text eol=crlf
 # =============================================================================
 # 2. 源码与文本配置 —— 显式声明为文本，工作区 LF
 # =============================================================================
 # 固件源码（main/ 下的 C/C++ 与官方 RMT 编码器）
 *.c     text eol=lf
 *.h     text eol=lf
 *.cpp   text eol=lf
 *.hpp   text eol=lf
 *.cc    text eol=lf
 *.hh    text eol=lf
 # 构建系统
 CMakeLists.txt     text eol=lf
 *.cmake            text eol=lf
 Kconfig            text eol=lf
 Kconfig.projbuild  text eol=lf
 # ESP-IDF 配置：sdkconfig 由工具生成（已忽略），defaults 是入库的那份
 sdkconfig           text eol=lf
 sdkconfig.old       text eol=lf
 sdkconfig.defaults  text eol=lf
 sdkconfig.ci*       text eol=lf
 # 文档与数据
 *.md    text eol=lf
 *.rst   text eol=lf
 *.txt   text eol=lf
 *.csv   text eol=lf
 *.json  text eol=lf
 *.yml   text eol=lf
 *.yaml  text eol=lf
 # 本仓库自身的元文件与工程级工具配置
 .gitignore      text eol=lf
 .gitattributes  text eol=lf
 .clangd         text eol=lf
 # =============================================================================
 # 3. 二进制 —— 禁止任何行尾转换与文本合并
 # =============================================================================
 # 固件/构建产物（已被 .gitignore 排除，这里再兜一层，防止被强制入库时被破坏）
 *.bin   binary
 *.elf   binary
 *.hex   binary
 *.a     binary
 *.o     binary
 # 图片与压缩包
 *.png   binary
 *.jpg   binary
 *.jpeg  binary
 *.gif   binary
 *.ico   binary
 *.bmp   binary
 *.svg   binary
 *.zip   binary
 *.gz    binary
 *.tar   binary
 *.7z    binary
 # 密钥与证书：绝不能因为行尾转换而改变字节
 *.pem   binary
 *.key   binary
 *.der   binary
 *.crt   binary
 *.p12   binary
 *.pfx   binary
@@ -0,0 +1,209 @@
 # =============================================================================
 #  armor — ESP32-C3 / ESP-IDF v6.1 工程专用 .gitignore
 # -----------------------------------------------------------------------------
 #  取舍原则
 #    1) 只忽略「本机生成物 + 本机专有配置 + 编辑器/系统杂物」；
 #       源码、构建脚本、分区表、可复现配置一律入库。
 #    2) 能用 "/" 锚定就用锚定模式，避免将来新增同名目录时被误伤。
 #    3) 每段都写明理由，后人可据此判断能否删改。
 #    4) 语法提醒：.gitignore 的 "#" 注释必须独占一行，不能写在模式后面；
 #       行尾空格会被静默丢弃（或被当成模式的一部分），也不要加。
 #
 #  自检
 #    git status --short             # 期望只列出应该入库的源文件
 #    git check-ignore -v <路径>     # 查看某路径被哪条规则命中
 # =============================================================================
 # =============================================================================
 # 1. ESP-IDF 构建输出（体积最大，本工作区约 17 MB，必须忽略）
 # =============================================================================
 # idf.py 默认在工程根目录生成 build/：CMake/Ninja 缓存、.o、静态库、固件
 # 镜像、flasher_args.json、compile_commands.json 全在里面。
 # 本工程路径是纯 ASCII，不会触发 idf.ps1 的「非 ASCII 路径 -> 外置构建目录」
 # 逻辑，所以 build/ 就落在工程内。
 /build/
 # 其它常见构建目录命名：多配置构建、CMake 预设、CLion
 /build-*/
 /cmake-build-*/
 # 仅当 IDF_BUILD_DIR 被指向工程内部时才会出现
 # （idf.ps1 的默认兜底是 <盘符>:\esp-idf-build\armor，位于仓库之外）
 /esp-idf-build/
 # clangd --background-index 的索引缓存（.vscode 里启用了该选项）
 /.cache/
 # 根目录下零散的 CMake/Ninja 缓存（正常应在 build/ 内，保险起见）
 /.ninja_deps
 /.ninja_log
 /CMakeCache.txt
 /CMakeFiles/
 # =============================================================================
 # 2. ESP-IDF 生成的本机配置
 # =============================================================================
 # sdkconfig     : menuconfig/构建时自动写出，代表「本机当前状态」，每台机器都可能不同
 # sdkconfig.old : 上一次配置的备份
 # 可复现的那份是 sdkconfig.defaults（已生成，见第 9 节），所以这两个都忽略。
 /sdkconfig
 /sdkconfig.old
 # 提示：ESP-IDF 工具在 Windows 上写 sdkconfig / sdkconfig.defaults 用的是 CRLF，
 # 这是工具行为、无需干预 —— 入库行尾由 .gitattributes 统一成 LF，
 # 本地暂时出现 CRLF 不会让 git status 变脏（已实测）。
 # =============================================================================
 # 3. IDF Component Manager（引入 idf_component.yml 后才会出现）
 # =============================================================================
 # managed_components/ 是下载到本地的第三方组件副本，官方文档明确说它
 # 「通常不纳入版本控制」；dependencies.lock 由工具自动求解生成、禁止手改。
 # 若团队要锁定依赖版本，可注释掉 dependencies.lock 并把它提交入库。
 /managed_components/
 /dependencies.lock
 # 工具导出的编译数据库副本（真正那份在 build/ 里，已随 build/ 忽略）
 /compile_commands.json
 # =============================================================================
 # 4. 固件产物与运行日志
 # =============================================================================
 # 只锚定根目录，避免误伤将来放进 assets/ 之类的素材
 /*.bin
 /*.elf
 /*.map
 /*.hex
 # README 里 monitor 打印的 CSV，属于采集到的运行数据，不入库
 /logs/
 *.log
 # =============================================================================
 # 5. 密钥类文件 —— 提交即泄密，且很难从历史里挽回
 # =============================================================================
 # 安全启动签名私钥 / Flash 加密密钥 / 证书私钥。
 # 若仓库确实需要存放公开证书，请把下面的通配收窄成具体文件名。
 *.pem
 *.key
 *.p12
 *.pfx
 # =============================================================================
 # 6. 编辑器 / IDE（本机专有，往往含绝对路径）
 # =============================================================================
 # VS Code + ESP-IDF 扩展自动生成。当前 .vscode/settings.json 里是
 # C:\esp\v6.1\esp-idf、d:\宣筹\...\build、COM10 这类本机绝对路径，
 # 提交上去只会误导别人。
 /.vscode/*
 # 想共享「推荐扩展列表」时，取消下一行注释（上一行的 /.vscode/* 必须保留）
 !/.vscode/extensions.json
 /.idea/
 /.vs/
 *.code-workspace
 *.sublime-project
 *.sublime-workspace
 # 编辑器临时/交换文件
 *.swp
 *.swo
 *~
 .#*
 \#*#
 # =============================================================================
 # 7. Python 与测试/覆盖率工具缓存（ESP-IDF 工具链脚本产物）
 # =============================================================================
 __pycache__/
 *.py[cod]
 .venv/
 venv/
 /.mypy_cache/
 /.pytest_cache/
 /.ruff_cache/
 # pytest-embedded、单元测试与尺寸报告（ESP-IDF 自身仓库也忽略这些）
 pytest-embedded/
 pytest_embedded_log/
 TEST_LOGS/
 XUNIT_RESULT*.xml
 build_summary_*.xml
 app_info_*.txt
 size_info*.txt
 .manifest_sha
 # 覆盖率
 *.gcda
 *.gcno
 *.gcov
 coverage.info
 coverage_report/
 # =============================================================================
 # 8. 操作系统杂物
 # =============================================================================
 Thumbs.db
 ehthumbs.db
 desktop.ini
 $RECYCLE.BIN/
 .DS_Store
 .AppleDouble
 ._*
 *.lnk
 # =============================================================================
 # 9. 必须入库的文件（切勿加入忽略列表）
 # =============================================================================
 #   CMakeLists.txt / main/CMakeLists.txt
 #   main/*.cpp main/*.hpp main/*.c main/*.h
 #   idf.ps1              构建入口（含非 ASCII 路径 workaround）
 #   partitions.csv       自定义分区表
 #   README.md            工程文档（移植要点与踩坑记录）
 #   .clangd              工程级 clangd 配置
 #   sdkconfig.defaults   可复现配置来源（由 idf.py save-defconfig 生成）
 #   .gitattributes       行尾(CRLF/LF)与文本/二进制归属策略
 #
 # 提醒：ESP-IDF 自身仓库的 .gitignore 会忽略 .clangd 和 .vscode/；
 # 本工程故意保留 .clangd（它是为 clangd 去掉 -f*/-m* 的项目配置），
 # 不要照抄 IDF 仓库的规则。
 # =============================================================================
 # 10. sdkconfig.defaults 与 sdkconfig 的关系（2026-10-14 核对并修复）
 # =============================================================================
 #  忽略 sdkconfig 的前提是 sdkconfig.defaults 存在且正确。核对时发现：
 #   * README「目录结构」里列的 sdkconfig.defaults 当时并不存在；
 #   * 当时的 sdkconfig（以及 build/config/sdkconfig.h）是
 #     CONFIG_PARTITION_TABLE_SINGLE_APP=y、CONFIG_ESPTOOLPY_FLASHSIZE_2MB=y，
 #     即用的是默认 single-app 分区表，partitions.csv 根本没有生效；
 #   * 而 README「实测验证结果」的 boot log 却是 4 MB flash + 2 MB factory 分区。
 #  已按文档修正（4 MB flash + CONFIG_PARTITION_TABLE_CUSTOM=y）重新配置，
 #  并用 `idf.py save-defconfig` 生成 sdkconfig.defaults，内容就是最小差异：
 #     CONFIG_IDF_TARGET="esp32c3"
 #     CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
 #     CONFIG_PARTITION_TABLE_CUSTOM=y
 #  （CONFIG_PARTITION_TABLE_CUSTOM_FILENAME 的 Kconfig 默认值本来就是
 #    "partitions.csv"，所以 save-defconfig 不会重复写入。）
 #
 #  维护规则：
 #   * 改配置请改 sdkconfig.defaults（或 menuconfig 后重跑 save-defconfig），
 #     不要把 sdkconfig 提交进来；
 #   * 想确认「相对 IDF 默认值改了什么」：重跑 idf.py save-defconfig 再看 diff；
 #   * 构建日志里分区表应为 nvs 0x9000 / phy_init 0xf000 / factory 0x10000 2M，
 #     否则说明 defaults 没生效或 partitions.csv 没被采用。
 # =============================================================================
@@ -0,0 +1,8 @@
 # ESP-IDF project for the "armor" hit-detection node (ESP32-C3).
 #
 # Converted from a PlatformIO / Arduino project; see README.md for the mapping
 # between the original Arduino APIs and the ESP-IDF ones used here.
 cmake_minimum_required(VERSION 3.16)
 include($ENV{IDF_PATH}/tools/cmake/project.cmake)
 project(armor)
@@ -0,0 +1,205 @@
 # armor (ESP32-C3) — ESP-IDF 工程
 本目录原为一个 PlatformIO / Arduino 工程，现已改造为 ESP-IDF 工程。
 原始 PlatformIO 工程曾备份在同级的 `../armor-platformio-backup/`——**那份备份没有进仓库**，
 这里的 `reference/armor/` 只保留改造后的 ESP-IDF 工程。
 - 目标芯片：**ESP32-C3**（实测设备 `ESP32-C3 (QFN32) rev v0.4`，USB-Serial/JTAG，MAC `98:a3:16:4c:67:c8`）
 - ESP-IDF 版本：**v6.1.0**
 - 状态：**已构建并烧录成功，实测稳定运行**
 ## 目录结构
 ```
 armor/
 ├── CMakeLists.txt          # ESP-IDF 顶层工程文件
 ├── sdkconfig.defaults      # 默认配置（替代 platformio.ini 的 board/build_flags）
 │                           # 由 idf.py save-defconfig 生成：IDF_TARGET / 4MB flash / 自定义分区表
 ├── partitions.csv          # 自定义分区表（2 MB factory 应用分区）
 ├── idf.ps1                 # 便捷脚本：自动激活 ESP-IDF 后转发给 idf.py
 ├── .gitignore              # 忽略 build/、sdkconfig、IDE 与本机生成物
 ├── .gitattributes          # 行尾策略：仓库统一 LF，.ps1/.bat/.cmd 在工作区用 CRLF
 └── main/
    ├── CMakeLists.txt
    ├── armor_main.cpp      # app_main：NVS / 串口 / 按键 / 业务任务（原 main.cpp）
    ├── air.hpp / air.cpp   # ESP-NOW 对拷链路
    ├── hit.hpp / hit.cpp   # 压电片击打检测 + WS2812
    ├── button.hpp/.cpp     # OneButton 2.6.1 状态机移植
    ├── storage.hpp/.cpp    # NVS 封装（替代 Arduino Preferences）
    ├── armor_time.hpp      # millis()
    └── led_strip_encoder.* # 官方 WS2812 RMT 编码器（取自 IDF 示例）
 ```
 ## 与 PlatformIO 工程的对应关系
 | PlatformIO / Arduino | ESP-IDF |
 | --- | --- |
 | `platform = espressif32`, `framework = arduino` | ESP-IDF v6.1 原生工程 |
 | `board = esp32-c3-devkitm-1` | `CONFIG_IDF_TARGET="esp32c3"` |
 | `lib_deps = Adafruit NeoPixel` | `led_strip_encoder.c` + RMT TX 驱动 |
 | `lib_deps = OneButton` | `main/button.cpp`（逐行移植其状态机） |
 | `Preferences` | `storage.cpp`（NVS） |
 | `ARDUINO_USB_CDC_ON_BOOT=1`（`Serial`） | USB Serial/JTAG 控制台 + `usb_serial_jtag_read_bytes()` |
 | `Serial0`（GPIO20/21） | `uart_driver_install(UART_NUM_0)`，TX=21 / RX=20 |
 | `setup()` / `loop()` / `loop2()` | `app_main()` / `hit_task` / `loop2_task` |
 | `gen_build.cmd`, `upload.cmd` | `idf.ps1`（见下） |
 ## 移植要点
 ### 1. ADC：旧驱动在新版 IDF 中已被移除
 原代码使用 `driver/adc.h` 的 legacy DMA 接口（`adc_digi_initialize` /
 `adc_digi_controller_configure` / `adc_digi_read_bytes`），该驱动在 ESP-IDF v6
 中已删除。现改用 `esp_adc/adc_continuous.h`，采样参数保持一致：
 总采样率 40 kHz、4 通道、12 bit、`ADC_ATTEN_DB_0`，每帧 10 ms（1600 字节）。
 解析方式仍是直接读取 `adc_digi_output_data_t::type2`（C3 的 12 bit 布局），
 因此击打判定阈值 `HIT_THRESHOLD = 2000` 的语义不变。
 ### 2. WS2812：软件位翻转 → RMT 硬件驱动
 Adafruit_NeoPixel 是软件位翻转驱动，这里换成 RMT + 官方 `led_strip_encoder`。
 字节序保持 Adafruit 的 `NEO_GRB`（GRB + MSB first）。
 **ESP32-C3 的 RMT 资源限制（踩坑记录）**：C3 的 RMT 只有一个 block，总计
 **96 个 symbol 的通道内存**，按 `SOC_RMT_MEM_WORDS_PER_CHANNEL = 48` 为单位分配给
 两个 TX 通道。因此：
 - `mem_block_symbols = 64` 会被向上取整到 96，即**一个通道吃光全部内存**，
  导致第二个 `rmt_new_tx_channel()` 失败：
  `E rmt: rmt_tx_register_to_group(168): no free tx channels` →
  `ESP_ERROR_CHECK` 触发 `abort()` → 芯片反复重启。
 - 4 条灯带在固件中始终显示同一颜色，所以这里只用**一个** RMT TX 通道，
  令其独占全部 96 symbol（足够一次装下 3 颗灯珠的整帧：3×24 bit + reset = 73
  symbol），再用 `rmt_tx_switch_gpio()` 依次把该通道切到 4 个 GPIO 上发送。
  每条灯带约 140 µs，10 ms 周期内开销可忽略。
 ### 3. 按键
 按 OneButton 2.6.1 的 `_fsm()` / `debounce()` 逐行移植，默认值与调用方式
 （`attachClick` / `attachLongPressStart` / `setClickMs(50)` / `setPressMs(500)` /
 每 10 ms `tick()`）完全一致。未使用的双击、多击、idle 等功能没有移植。
 ### 4. 控制台
 控制台走 USB Serial/JTAG，等价于原来的 `ARDUINO_USB_CDC_ON_BOOT=1`，
 同时让 UART0（GPIO20/21）腾出来给 DBUS 数据，与原 `Serial0` 一致。
 USB CDC 的 10 字节 DBUS 帧由独立的 `cdc_task` 接收。
 ### 5. NVS
 命名空间仍是 `armor`，键名 `color`、`peer_mac` 保持原样。
 ### 与原始固件的差异（有意为之）
 - `Air::onRecv()` 现在直接用 `esp_now_recv_info_t::rx_ctrl->rssi` 记录信号强度。
  原代码依赖混杂模式回调“恰好先于” ESP-NOW 回调执行，存在竞态；新写法在配对
  比较时能拿到当前包的准确 RSSI。
 - `my_packet.dbus` 的写入/清零加了临界区保护（原代码在 CDC 回调与业务线程之间
  无保护）。
 - ESP-NOW 负载长度由 `alignas(1)` 改为 `__attribute__((packed))`，
  两者都让 `sizeof(packet_t) == 19`，但后者是可移植写法（C++ 标准不允许
  `alignas` 比成员自然对齐更宽松）。
 - `hit_cnt++` 改为 `hit_cnt = hit_cnt + 1`：C++20 起对 `volatile` 使用 `++` 已废弃，
  而 IDF 默认开启 `-Werror`。
 - 分区表使用 2 MB 的 factory 分区（默认的 1 MB 对 WiFi + ESP-NOW 固件偏紧；
  当前固件 0xcfbc0 ≈ 852 KB）。
 其余业务逻辑（颜色切换、配对流程、串口协议、超时清零）与原实现逐条对应。
 ## ⚠️ 非 ASCII 路径问题（本工程必须注意）
 本工程所在路径包含中文（`D:\宣筹\校内赛\...`）。**ESP-IDF v6.1 在 Windows 上无法
 在非 ASCII 路径下编译**，原因是 `components/esp_libc/project_include.cmake` 会把
 编译器的 `-specs=<build>/specs/picolibc.specs` 参数写进
 `build/toolchain/cflags`，而读写该文件用的 `tools/cmake/toolchain_flags.cmake`
 走的是 CMake `file(STRINGS)`；未指定 `ENCODING` 时它按 ASCII 解析，会**静默丢弃
 所有非 ASCII 字节**，于是 `-specs=` 指向的文件名被破坏，每个编译单元都报：
 ```
 riscv32-esp-elf-gcc.exe: fatal error: cannot read spec file
  'D:/\x0a/\x0a/2026/SmallMaster-master/code/armor/build/specs/picolibc.specs': Invalid argument
 ```
 实测字节级证据（`file(STRINGS)` 往返）：
 | | 字节 |
 | --- | --- |
 | 输入 `D:/宣筹/校内赛/...` | `... 2F, E5,AE,A3, E7,AD,B9, 2F, E6,A0,A1, E5,86,85, E8,B5,9B, 2F ...` |
 | `file(READ)` 直读（正常） | 同上 |
 | `file(STRINGS)` 往返后 | `... 2F, 0D,0A, 2F, 0D,0A, 2F ...` |
 **解决办法**：把 build 目录放到纯 ASCII 路径下（源码可以留在中文路径），
 即 `idf.py -B <ASCII 目录>`。本仓库的 `idf.ps1` 已自动处理：
 ```
 检测到工程路径含非 ASCII 字符时，自动改用 <盘符>:\esp-idf-build\armor 作为 build 目录
 ```
 可用环境变量 `IDF_BUILD_DIR` 覆盖该位置；若想改回在工程内构建，
 把工程移到纯 ASCII 路径即可（此时脚本不会加 `-B`）。
 > 注意：用目录联接（junction）指向中文路径**无效**——PowerShell 的
 > `Set-Location` 会把联接解析回真实路径，CMake 仍然看到中文路径。
 ## 构建与烧录
 ```powershell
 # 构建（自动处理非 ASCII 路径）
 .\idf.ps1 build
 # 烧录
 .\idf.ps1 -p COM9 flash
 # 烧录并监视（Ctrl+] 退出）
 .\idf.ps1 -p COM9 flash monitor
 # 擦除整片 flash
 .\idf.ps1 erase-flash
 ```
 `idf.ps1` 会在需要时通过 `eim_idf.json` 自动找到并激活本机的 ESP-IDF。
 如果你已经激活过 ESP-IDF（`idf.py` 可用），也可以直接：
 ```powershell
 idf.py -B <ASCII 路径> build
 idf.py -B <ASCII 路径> -p COM9 flash monitor
 ```
 串口参数与原先一致：UART0 = 115200 8N1（DBUS），USB CDC 输出
 `color,hit_cnt,peer_rssi,my_rssi,latency_ms` 的 CSV 行。
 ## 实测验证结果（COM9，ESP32-C3 rev v0.4）
 烧录后 boot log：
 ```
 I (24)  boot: ESP-IDF v6.1 2nd stage bootloader
 I (25)  boot.esp32c3: SPI Speed : 80MHz / Mode : DIO / Flash Size : 4MB
 I (26)  boot:  2 factory          factory app      00 00 00010000 00200000
 I (175) boot: Loaded app from partition at offset 0x10000
 I (185) app_init: Project name:     armor
 I (185) app_init: ESP-IDF:          v6.1
 I (190) main_task: Calling app_main()
 I (245) wifi:mode : sta (98:a3:16:4c:67:c8)
 I (247) wifi:(2.4G)set country: cc=JP  schan=1 nchan=14 policy=1
 I (250) wifi:ic_enable_sniffer          <- 混杂模式
 I (250) ESPNOW: espnow [version: 2.0] init
 I (251) armor: armor node started
 I (252) main_task: Returned from app_main()
 16711680,0,0,0,65
 16711680,0,0,0,75
 ...
 ```
 - 无重启、无 panic、无 abort；连续 6 秒稳定输出 555 行 CSV（约 11 ms 一条，符合 10 ms 循环）。
 - `color = 16711680 = 0xFF0000`，即 NVS 为空时的默认红色，与 `Hit::RED` 一致。
 - WiFi 国家码 `JP`、信道 1–14、混杂模式、ESP-NOW v2.0 全部按原逻辑生效。
 ## 硬件引脚（未改动）
 | 功能 | GPIO |
 | --- | --- |
 | 按键（BOOT，低有效） | 9 |
 | WS2812 前 / 后 / 左 / 右 | 10 / 5 / 6 / 7 |
 | 压电片 ADC 前 / 后 / 左 / 右（ADC1_CH0/4/3/1） | 0 / 4 / 3 / 1 |
 | DBUS UART0 TX / RX | 21 / 20 |
@@ -0,0 +1,83 @@
 <#
 .SYNOPSIS
    Run idf.py for this project with a local ESP-IDF environment activated.
 .DESCRIPTION
    Activates ESP-IDF (located through the Espressif Installation Manager's
    eim_idf.json, unless IDF_PATH is already set) and forwards every remaining
    argument to idf.py.
    Non-ASCII project path workaround
    ---------------------------------
    ESP-IDF v6.1 rewrites the compiler's "-specs=..." flag from
    components/esp_libc/project_include.cmake through CMake's file(STRINGS),
    which silently drops every non-ASCII byte. When this project lives under a
    path containing non-ASCII characters (e.g. "D:\宣筹\..."), the rewritten
    flag points at a nonexistent file and every compile fails with:
        riscv32-esp-elf-gcc.exe: fatal error: cannot read spec file ...
    This script detects that case and builds out-of-tree into an ASCII build
    directory instead, which keeps the flag (and every generated path) ASCII.
    Override the location with the IDF_BUILD_DIR environment variable.
 .EXAMPLE
    .\idf.ps1 build
    .\idf.ps1 menuconfig
    .\idf.ps1 -p COM9 flash monitor
    .\idf.ps1 erase-flash
 #>
 # NOTE: deliberately no param() block. An advanced/declared parameter list makes
 # PowerShell try to bind idf.py's own short options to its common parameters
 # ("-p" is ambiguous with -ProgressAction / -PipelineVariable). A simple script
 # passes every unbound token through $args verbatim.
 $IdfArgs = @($args)
 $ErrorActionPreference = 'Stop'
 function Find-IdfActivation {
    $candidates = @(
        (Join-Path $env:USERPROFILE '.espressif\eim_idf.json'),
        'C:\Espressif\tools\eim_idf.json',
        (Join-Path $env:LOCALAPPDATA 'Espressif\eim_idf.json')
    )
    foreach ($path in $candidates) {
        if (-not (Test-Path $path)) { continue }
        $cfg = Get-Content $path -Raw | ConvertFrom-Json
        $installed = $cfg.idfInstalled | Where-Object { $_.id -eq $cfg.idfSelectedId } | Select-Object -First 1
        if (-not $installed) { $installed = $cfg.idfInstalled | Select-Object -First 1 }
        if ($installed -and (Test-Path $installed.activationScript)) {
            return $installed.activationScript
        }
    }
    return $null
 }
 if (-not $env:IDF_PATH) {
    $activation = Find-IdfActivation
    if (-not $activation) {
        throw 'ESP-IDF not found. Activate your ESP-IDF environment first (export.ps1 / eim).'
    }
    . $activation *> $null
 }
 if (-not $IdfArgs -or $IdfArgs.Count -eq 0) { $IdfArgs = @('build') }
 # --- non-ASCII project path workaround -------------------------------------
 $projectDir = if ($PSScriptRoot) { $PSScriptRoot } else { (Get-Location).Path }
 $userPickedBuildDir = $IdfArgs -contains '-B' -or $IdfArgs -contains '--build-dir'
 if ($projectDir -notmatch '^[\x20-\x7E]+$' -and -not $userPickedBuildDir) {
    if ($env:IDF_BUILD_DIR) {
        $buildDir = $env:IDF_BUILD_DIR
    } else {
        $qualifier = Split-Path -Qualifier $projectDir   # e.g. "D:"
        $buildDir = Join-Path $qualifier 'esp-idf-build\armor'
    }
    Write-Host "Non-ASCII project path detected; building out-of-tree in '$buildDir'." -ForegroundColor Yellow
    Write-Host 'Set IDF_BUILD_DIR to use a different build directory.' -ForegroundColor Yellow
    $IdfArgs = @('-B', $buildDir) + $IdfArgs
 }
 & idf.py @IdfArgs
 exit $LASTEXITCODE
--- a/Show More
+++ b/Show More