simba-rmic-2026/docs/design/match-and-broadcast.md

比赛控制与直播提案

状态：待确认，尚未实现。保留自 2026-10-19 的界面重构草案；以下布局、状态、命令、快捷键与验收数字均为提议，不是当前能力或测试结果。 比赛判负、技术暂停、计时比分、直播页和双路同步回放仍需确认。当前客户端说明见桌面端，已实现的 USB 维护与固件包格式见固件维护。 原草案中的旧色板、字体方案、单文件 CSS 基线、烧录实现计划和排期已被当前实现取代，不再作为开发依据。 规则依据：2026 校内赛参赛手册、对抗赛与奖项、裁判系统。规则摘录沿用原稿，实施前需核对手册。

页面方案

应用外壳（新增 AppShell）

┌──────────────────────────────────────────────────────────────────────┐
│ TopBar 44px   cam-desktop · 裁判端 · 链路●   │ 比赛条（裁判/直播） │ 工具 │
├──────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   Stage：视频 + 画面内 HUD + 覆盖层（暂停/判定/校准）                  │
│                                                                      │
├──────────────────────────────────────────────────────────────────────┤
│ StatusBar 28px  链路 / 帧率 / 丢帧 / 提示                             │
└──────────────────────────────────────────────────────────────────────┘

三种外壳状态（data-shell）：

状态	触发	行为
normal	默认	全部 chrome 可见
immersive	F11	chrome 隐藏；指针移到上沿 8px 时 TopBar 150ms 淡入，3 s 后淡出；指针静止 2 s 隐藏光标
broadcast	视图切换 Ctrl+Shift+B	只渲染 BroadcastStage；禁用设置/维护/发现列表；不渲染任何 IP/token

结构落点：App.tsx 里现有的门禁分支（致命错误 / 等待快照 / 身份选择 / 设密码）不动，只在最后一段把 TeamPage | RefereePage 包进 AppShell，并新增 BroadcastPage 分支。

用户端 TeamPage（操作手视角）

使用场景：操作手位于布帘后，单手操作、不看键盘，单局 3 分钟。

┌──────────────────────────────────────────────┐
│              02:41                  （计时）  │  ← 仅比赛进行中出现
│ ┌────────────┐                  ┌────────────┐│
│ │我方 ████ 76│                  │100 ████ 对手││  ← 血条贴角，宽 36%
│ └────────────┘                  └────────────┘│
│                                              │
│                    +                    （准星）│
│                                              │
│  （命中时：上中"命中 -3" + 全屏淡红 620ms）    │
└──────────────────────────────────────────────┘
│ 链路 · 28.6 fps · 丢 0.4%                     │ ← release 下只留"链路"

改动点：

1. 顶部加计时条（仅 match.phase ∈ {running, paused} 且本队已绑定）；不显示比分细节，局间才显示"第 2 局 · 1:1"。
2. 底部状态行从"滚轮缩放 · 拖动平移…"改成首次提示：进入页面 5 s 后自动淡出，鼠标移动再出现（作为新交互提议，时长仍需确认）。
3. 新增 PausedOverlay：技术暂停时整屏 86% 遮罩 + "技术暂停 03:12 · 由裁判发起"，血条/计时保留可见。
4. 新增 JudgedOverlay：判负/结束时显示"本局判负（设备故障）"或"胜利"，与 MatchBanner 合并成一个组件（避免两套结论 UI 同时出现）。
5. 设置入口、录制入口不进主界面（现在 TopBar 里有"设置/固件维护"，用户端误触风险高）：改为 Ctrl+K 命令面板或长按品牌名 2 s。
6. 校准模式（现有 calibrating）保留，但提示从底部横幅改到画面内角标，避免遮挡。

裁判端 RefereePage

三区 + 一条比赛条：

┌ TopBar ────────────────────────────────────────────────────────────────┐
│ cam-desktop · 裁判端 · 链路● · 录制×2                    [直播] [设置]    │
├ MatchBar 52px ─────────────────────────────────────────────────────────┤
│ BO3 第2局 │ 02:41 │ 红 76 ╍╍╍╍ 100 蓝 │ ⏸ 技术暂停 │ ⚑ 判负 │ ⋯ 更多 │
├────────────────────────────────────────────────────────────────────────┤
│  ┌─ 红方（左）──────────────┐   ┌─ 蓝方（右）──────────────┐          │
│  │  video + HUD            │   │  video + HUD             │          │
│  │  [队名 可编辑] [fps]     │   │  [队名 可编辑] [fps]      │          │
│  └─────────────────────────┘   └──────────────────────────┘          │
├ Dock ─────────────────────────────────────────────────────────────────┤
│ [装甲板 8] [录制与回放 3] [事件 27] [连接诊断]              [刷新] [⟳]  │
│  …内容（表格/列表/日志）…                                              │
└────────────────────────────────────────────────────────────────────────┘

改动点：

1. MatchBar（新，常驻，高 52px）：局次、计时、比分、暂停、判负、更多菜单。这是裁判端最重要的新增组件；判定后整条切成"结果态"（红/蓝底 + 理由 + 撤销入口）。
2. referee-stage 保持 flex: 1，新增的 MatchBar 占固定高度；下方控制台采用可拖拽高度（提议默认 240px，最小 120，最大 45vh）；加一行比赛条后，900px 高的窗口约剩 560px 用于画面。
3. ArmorTable 改为两队并列（左红右蓝），每行左侧加 5 格迷你血条（与 HUD 同源，便于核对）；主装甲板加 主 徽标；离线行 opacity .55（保留）；reportsAllPlates=false 时显示"仅报 2 块"——规则允许 2 或 4 块装甲板。
4. 新增 EventPanel（Dock 第 3 个页签）：命中/暂停/判负/录制开始/结束的时间轴列表，可导出。
5. MediaPanel 保留全部功能，新增两个东西：按局分组（matchId 目录）与 "回放本局"（双路同步 + 事件定位）。
6. 队名编辑保留（现在是内联输入），但改成"点击铅笔 → 行内编辑 → Enter 保存 / Esc 取消"，避免一直占一行高。

直播 BroadcastPage（新）

见下文直播方案。要点：一个 1920×1080 虚拟画布 + 4 个模板 + 安全区参考线 + 只读数据。

状态与交互

状态模型（前端）

interface AppStore {
  snapshot: Snapshot | null;
  connected: boolean;
  lastHit: HitPulseRecord | null;
  confirmQuit: number;
  notes: string[];
  channelError: string | null;
  // 新增
  ui: { shell: "normal" | "immersive" | "broadcast"; guides: boolean; idle: boolean };
  events: MatchEventView[];      // 由 WireMsg::MatchEvent 累积（本地最多 500 条）
  clockSkewMs: number;           // serverNow - localNow，用于计时插值
}

事件传输：比赛事件走独立推送，与现有的 hit 同一条路（server::WireMsg 新增 MatchEvent），前端累积；Snapshot.match 只带最近 12 条用于重连后补齐。理由：快照 5 Hz × 200 条事件会让每份快照增加到几十 KB，事件单独推送可避免重复传输。

计时以后端为准：Snapshot 增加 nowMs: u64（后端 Unix 毫秒），前端用 useServerClock 每帧算 serverNow = localNow + clockSkewMs，再用 match.remainingMs - (serverNow - snapshotAt) 插值。setInterval 在窗口失焦时会被节流，不能作为比赛计时依据。

一键判负

入口：MatchBar 右侧 ⚑ 判负，或 Ctrl/Cmd+Shift+F。只在裁判端、phase ∈ {running, paused} 时可用。

三步，不可合并

① 点按 → ForfeitDialog
   ┌─────────────────────────────────────────┐
   │ 判定本局结果                             │
   │ 当前：红 76 · 蓝 100 ｜ 剩余 02:41 ｜ 第2局│
   │ 败方： (●) 红方  ( ) 蓝方                 │
   │ 理由： [设备故障 ▾]                       │
   │   设备故障 / 违规 / 弃权 / 未到场 / 其他   │
   │ 备注： [________________________]         │
   │ ⚠ 本操作只改变比赛判定与记录，不改变硬件血量 │
   │            [取消]  [长按 1 秒确认判负]     │
   └─────────────────────────────────────────┘
② 长按 1000ms（HoldButton，松手即取消，Esc 取消）
③ 5s 内 toast 提供「撤销」

执行语义

match_end { reason: Forfeit { loser: 0|1, kind: ForfeitKind, note: Option<String> } }

• 状态 → Ended { by: Referee, reason, at, actor }，比分按规则 +1 给胜方。
• 用户端若已同步（见 R2）：显示 JudgedOverlay「本局判负」；未同步则只影响裁判端与直播。
• 不改硬件血量：ArmorHealthStore 只接收上报，没有任何写入口（见 R1）。界面必须显式写明这一点，否则现场会以为"判负之后对方血量归零了"。
• 审计：事件 { at, actor, action:"forfeit", loser, reason, note, hp:[76,100], remainingMs:161000 }，追加到 matches/<yyyy-mm-dd>/<matchId>/events.ndjson，同时进 snapshot.match.events。
• 撤销：match_undo { eventId }，5 s 内可直接撤销；之后只能 match_reopen_round { reason }，在历史里留下"更正"两条记录（不删除原记录）。

与自动判定共存：resolve_outcomes 已经能在血量归零时给出 Victory/Defeat/Draw。两者必须用同一字段建模：

end: { by: "auto" | "referee"; reason: "knockout" | "timeout" | "forfeit" | "equipment" | "tiebreak"; loser?: 0|1 }

回放和统计据此区分结束原因。

技术暂停

规则对齐：手册写"任意一方…可向场边裁判申请发起时长为 5 分钟 的技术暂停并说明理由，待主裁判批准后技术暂停开始。技术暂停期间，双方均可在该段时间内检修机器人。"

四步流程

申请方(红/蓝) → 理由 → ✅ 主裁判已批准 → 开始计时(05:00) → 恢复

• 入口：MatchBar 的 ⏸ 技术暂停。对话框必填：申请方、理由（枚举+备注）、"主裁判已批准"复选框（不勾不能开始——把规则写进交互里）。
• 开始后：phase = Paused { kind: Tech, endsAt, applicant }，比赛计时冻结，技术暂停独立倒计时 5:00。
• 用户端/直播：PausedOverlay 显示"技术暂停 · 剩余 04:12"，不遮挡血条与计时。
• 结束：
  • 手动「恢复比赛」→ 3-2-1 倒数 3 s（Resuming 过渡态）→ Running。
  • 05:00 到点 → 状态 PausedTimeout，提示"技术暂停已超时"，按钮变成「恢复」/「判负」二选一，不自动判负（规则没写超时即判负）。
• 录制不停（证据链需要），但写入 bookmark 事件；视频文件里保留暂停期间的画面。
• 暂停期间的命中：硬件照常上报，客户端如实显示并把事件标红（不隐藏、不改血量）。理由见 R1/Q3——客户端没有写硬件的能力，做"冻结基线"只会制造两份互相矛盾的血量。

计时 / 比分

两个不同的 3 分钟，界面必须分开写

阶段	时长	文案
赛前准备	3:00	准备 02:41（浅色，不计入比赛）
单局比赛	3:00	比赛 02:41（主色，进入最后 30 s 变红）
技术暂停	5:00	技术暂停 04:12（青色）

状态机

Idle ──start_round──▶ Running ──pause──▶ Paused ──resume──▶ Running
  ▲                      │                  │
  │                      ├──hp=0 / timeout──▶ Ended(by=auto)
  │                      └──forfeit─────────▶ Ended(by=referee)
  └──reset/next_round─────┴──────────────────┘

Ended(timeout 且血量相等) ──▶ AwaitingTiebreak ──set_tiebreak──▶ Ended(by=referee, reason=tiebreak)

到点判定（严格照手册四条）：

1. 血量先减为 0 的一方落败 → 已有 resolve_outcomes，直接复用。
2. 3 分钟耗尽且无人归零 → 血量多者胜。
3. 双方血量均等 → 不以"平局"结束，进入 AwaitingTiebreak，由裁判选择"本局最快开始移动的一队"。
   • 客户端没有运动遥测（协议里没有位置/速度），所以只能人工录入：set_tiebreak { winner: 0|1 }。
   • 这条必须显眼提示裁判"需要人工判定"，不能默认算平局，否则会静默改变比赛结果。
4. 两边同时归零 → Draw（现有 MatchOutcome::Draw 逻辑保留，仅用于显示）。

比分：bestOf ∈ {1,3,5}（对应手册 BO1/BO3/BO5），score: [u8;2]，history: Vec<RoundResult>。先到 ceil(bestOf/2) 局的一方赢下系列赛，界面显示 2:0 · 系列赛结束。

计时实现（后端为准）：

pub struct MatchClock {
    started: Option<Instant>,
    frozen_elapsed: Duration, // 暂停累计
    limit: Duration,
}
impl MatchClock {
    fn remaining(&self) -> Duration;
    fn pause(&mut self); fn resume(&mut self);
}

在 AppState::tick()（5 Hz）里推进；Snapshot.match.remaining_ms 为权威值；Snapshot.now_ms 用于前端插值。不允许前端 setInterval 自己减。

回放

入口：Ended 后结果卡 →「回放本局」；或 Dock 的「录制与回放 → 按局分组」。

布局

┌ 回放 · 2026-11-01 第2局 红 vs 蓝 ─────────────── [导出] [返回] ┐
│ ┌──────────────────────┐ ┌──────────────────────┐              │
│ │ 红方录屏             │ │ 蓝方录屏             │              │
│ └──────────────────────┘ └──────────────────────┘              │
│ ▶ ━━━━━●━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 01:12/03:00  │
│   ⚑ 00:00 开始 · ● 00:41 命中 · ⏸ 01:12 技术暂停 · ⚑ 02:33 判负 │
└────────────────────────────────────────────────────────────────┘

• 两个 <video> 共用主时钟（以 A 为主，B 每秒校正一次，偏差 > 120 ms 才 seek，避免抖动）。
• 事件时间轴可点击跳转：currentTime = (event.atMs - roundStartAtMs) / 1000。
• 快捷键：空格 播放/暂停、←/→ ±1 s、Shift+←/→ ±5 s、M 打标记。
• 截图：现有 api.screenshot(camera) 只能截最新一帧，不能截回放帧。需要新增 save_png { data: Vec<u8>, name: String }（限制写入 recordings_dir/shots），前端用 canvas.drawImage(video) + toBlob 取帧。
• 录制文件命名建议：<date>_<round>_<红队>_vs_<蓝队>_<cameraText>.mp4；若比赛开始时自动开启录制，需要给 Recorder::start 增加一个 label: Option<&str>。
• 录制起停由 match_start/end 发出事件，是否自动则看用户配置（默认自动开、自动停；退出程序仍走现有 stop_all 收尾）。

---

直播 UI：安全区与包装层

基准画布与安全区

基准 1920×1080（16:9）。相机是 640×480（4:3），所以直播层必须自己决定是加信箱还是裁切，不能指望画面填满。

区域	距边距	1080p 像素	内容
画布	—	0	1920×1080
Action safe（93%）	3.5%	左右 67px / 上下 38px	视频、装饰边框
Title safe（90%）	5%	左右 96px / 上下 54px	比分、计时、队名、判定卡
可牺牲区（平台遮挡）	—	底部 120px（y ≥ 960）、右侧 60px	只放赞助条/次要字幕；比分、计时、判定卡一律不得进入
视频安全区（画面内 HUD）	3.5%	640×480 上约 22px 横 / 17px 纵	血条与命中提示条

若输出 720p，以上像素值 ×2/3；若必须 4:3 输出（1440×1080），安全区按宽高比各算一次，不要简单套 16:9 的数字。

分区与坐标（模板 A：双路对称，默认）

y=0    ┌──────────────────────────────────────────────────────────┐
       │  [赛事名/校徽]                          ● LIVE   BO3 第2局 │ 0–108     标题区
y=108  ├──────────────────────────────────────────────────────────┤
       │         ┌────────────────┐  ┌────────────────┐            │
y=150  │  红方   │  视频 800×600  │  │  视频 800×600  │   蓝方     │ 150–750   媒体区
       │  队名   │  (640×480 放大)│  │                │   队名     │ x:140–940 / 980–1780
y=750  ├──────────────────────────────────────────────────────────┤
       │            红 76 ━━━━━━ 02:41 ━━━━━━ 100 蓝                │ 770–930   比分/计时
y=930  ├──────────────────────────────────────────────────────────┤
       │  [事件字幕]                                    [赞助条]    │ 940–1080  可牺牲区
y=960  │ - - - - - - - - - 平台遮挡区上沿（不放关键信息） - - - - - │
y=1080 └──────────────────────────────────────────────────────────┘

• 媒体区左右各留 140px：其中 100px 给队名，剩余给队伍色条（--team-0/1 4px 竖条）。
• 比分/计时带固定 y 770–930，底边 930 < 960，永远不进平台遮挡区；判定卡必须在 title safe 内（x 96–1824，y 54–1026）。
• 计时居中，字号 --fs-clock；比分 --fs-score。
• 4:3 → 800×600 是 1.25× 放大，VGA 源放大后仍可读；不要裁切（裁切会切掉装甲板或场地边线，判罚举证时没有依据）。

模板 B：主视角 + PIP（一方图传丢失时自动建议）

┌──────────────────────────────────────────────┐
│ 标题条                                        │
│  ┌────────────────────────────────────────┐  │
│  │        主画面 1600×900（居中偏上）      │  │
│  └────────────────────────────────────────┘  │
│                    ┌──────────┐               │
│                    │ PIP 480×360│  ← 右下，避开平台遮挡区
│  比分板            └──────────┘               │
└──────────────────────────────────────────────┘

模板 C：待机/准备（Idle/Ready，或信号中断）

• 中央：赛事名 + 双方队名 + 准备 03:00（大号）+ "信号恢复中"（画面缺失时显示）。
• 背景：--bg-void + 2% 噪点 + 细网格（background-image: repeating-linear-gradient，静态，不滚）。
• 永不显示纯黑屏（黑屏会被平台判为离线）。

模板 D：判定（Ended）

• 中央判定卡：红方胜 / 本局判负（--fs-display）+ 理由（设备故障/超出时间/血量归零）+ 比分。
• 卡背景 rgba(8,8,12,.72) + 1px 亮边 + 切角，不做全屏红闪。

包装层结构（z 序）

z0  BackgroundLayer    底色 + 静态网格 + 噪点
z1  MediaLayer         双路 VideoSurface（复用现有组件，crosshair=null）
z2  HudLayer           画面内血条（可选显示，直播默认显示）
z3  LowerLayer         比分板 / 计时 / 队名 / 事件字幕
z4  AlertLayer         暂停 / 判负 / 判定卡
z5  BrandLayer         赛事名、校徽、赞助、LIVE 徽标
z6  GuideLayer         安全区参考线（仅预览，输出时 display:none）

实现要点：

• BroadcastStage 用 1920×1080 的绝对坐标系 + transform: scale(min(vw/1920, vh/1080))，transform-origin: top left。这样所有设计稿坐标直接写进 CSS，无需换算为百分比。
• 参考线由 GuideLayer 画（outline: 1px dashed），受 props.guides 控制；全屏/输出时自动关闭。
• 视频源仍用 VideoSurface（ViewTransform 固定 IDENTITY_VIEW），只是容器换成 800×600 的固定框——不要为直播再写一套 canvas 绘制。

输出方式

方案	做法	评价
A（推荐）	同一窗口切 broadcast 视图 + F11 全屏；OBS「窗口采集」+ 裁到 16:9	无需新增权限或进程，作为首选方案
B	第二个 WebviewWindow（label: broadcast，无边框、置顶）	需要 core:webview:allow-create-webview-window；双窗口抢 GPU，留待后续实现
C	NDI / 虚拟摄像头	明确不做（依赖重、跨平台成本高）

实施时需检查：

1. WebView 背景：transparent: true 在 Windows WebView2 与 macOS WKWebView 行为不一致，直播场景下透明边缘会出黑边。结论：用不透明底色 --bg-void 铺满，不做透明。
2. 低帧画面 + 高帧包装：视频是 JPEG 序列，帧率取决于固件配置（commands.rs 的注释里记着"The sensor 实测 22 fps"，target/firmware/BUILD-INFO.json 里 vga30 档实测 29.7 fps）；无论哪个值都远低于包装层的 60 fps，动效会"飘"在画面上。所以包装层只做状态迁移动画，不做连续动画。
3. 纯黑编码：#000 在 H.264 里容易 banding，用 #07080a + 2% 噪点。
4. OBS 窗口采集会采到鼠标：全屏时 cursor: none（immersive 状态负责）。
5. 窗口标题：直播窗口标题里不要出现队名/端口等内部信息（setTitle 现在会写身份；broadcast 视图下改成 cam-desktop — 直播）。
6. 分辨率自适应：transform: scale() 后文字仍清晰（矢量），但如果 OBS 缩放窗口，字号会变成非整数像素 → 建议 OBS 采集时窗口保持 1920×1080 或 1280×720。

直播视图的安全边界（必须做）

• broadcast 视图不渲染：设置按钮、维护入口、cameras[].addr（IP）、stream_info.url（token）、密码相关 UI、装甲板 id 全文（只显示队名）。
• 所有管理命令在广播态禁用（不是隐藏，是 disabled + aria-hidden，防止误触与 Tab 聚焦）。
• 演示模式（demo）在直播里显示红色角标"演示画面"，与现有 tag--demo 同一语义（现在只在 TopBar，直播态必须另有一处）。
• 断流时 StandbyCard 明确写"信号中断 · 正在重连"，不显示上一帧冻结画面冒充直播（冻结画面会被观众当成"画面卡住"）。

---

校内赛规则要点与判罚流程

规则事实（来自官方手册，不改写）

条目	规定	来源
队伍	每队严格 3 人，每人限一队；16 队取得比赛资格	赛事概览
赛制	BO1 / BO3 / BO5；16→8 双败 BO3，8→4 双败 BO3，总决赛 BO5	对抗赛与奖项
红蓝方	每场编号小者为红方，编号大者为蓝方	同上
检录	尺寸 / 遥控运动 / 发射 / 裁判系统安装 / 裁判系统（含图传）运作；通过后不得再烧录或改硬件直至准备阶段	同上
赛前准备	3 分钟；双方把机器人放到与装甲板颜色相同的部署点；确认裁判系统与操作位图传客户端连接、遥控连接正常	同上
技术暂停	5 分钟；任意一方遇突发问题向场边裁判申请并说明理由，主裁判批准后开始；期间双方均可检修	同上
血量	初始 100；每发有效攻击扣 3 点	同上
单局时长	3 分钟	同上
胜负	①血量先归零者负 ②时间耗尽血量多者胜 ③双方血量均等则以本局最快开始移动的一队获胜	同上
装甲板	每车 2 或 4 块，其中一块为主装甲板；检测周期 100 ms；任一触发后全车 100 ms 静默期；供电 5 V ± 1 V；UART 可向主控发键鼠指令	裁判系统
图传	1 个模块，回传第一人称画面到裁判系统客户端屏幕；供电 3.3 V（与装甲板 5 V 不同）	同上
日程	10-25 适应性训练；11-01 决赛（9:00–11:00 / 14:00–18:00）	赛事概览

对客户端的影响

1. 血量必须同时有数字和格子。100 点 / 5 格 = 20 点/格，而单发只扣 3 点——一格的粒度相当于 6.7 发。只给格子，操作手无法判断"再中两发就死"。→ 保留 showNumbers 默认开启，且数字 ≥ 18px。
2. 100 点 = 34 发（33 发后剩 1 点）。裁判端可以显示"已中 33 发"这类辅助读数（100 - hp) / 3），但不要把它当成权威值——静默期内的连击会被合并。
3. 100 ms 静默期决定命中动效下限：同一次攻击可能在 4 块板上各上报一次，HealthTracker 按血量差派生，已经能合并；UI 侧不要为每个 board 事件各弹一次伤害数字（否则一次命中会闪 4 下）。
4. 装甲板 2 块也要能显示：ArmorBoardDto.reportsAllPlates / platesSeen 已存在，界面在 platesSeen < 4 时显示"仅报 N 块"，不要显示 4 个空槽让人以为板子坏了。
5. "最快开始移动"没有数据源。图传只给画面，协议里没有位移/速度；因此这条规则只能人工判定（见“计时 / 比分”）。不要试图从画面里推算。
6. 赛前 3 分钟是"确认客户端连上了"的窗口，所以用户端需要一个准备检查卡：图传在线、装甲板在线、帧率、最近一帧年龄、镜像是否正确。这张卡在 Ready 阶段自动出现，Running 后消失。
7. 红蓝配色固定：队号 0 = 红、1 = 蓝，与部署点/装甲板灯色一致（现有 teamColor 已是这个语义，只改色值）。

判罚流程（客户端可执行的部分）

                     ┌──────────────────────────────┐
                     │ 单局结束条件                  │
                     └──────────────┬───────────────┘
        ┌───────────────────────────┼───────────────────────────┐
        │                           │                           │
   血量归零                     时间耗尽                    人工裁定
   （自动，双方一致）           （自动比血量）              （裁判操作）
        │                           │                           │
        │                    ┌──────┴──────┐          ┌─────────┼─────────┐
        │                 血量不等      血量相等      设备故障   违规/弃权  平血仲裁
        │                    │              │             │         │         │
        ▼                    ▼              ▼             ▼         ▼         ▼
   Ended(by=auto,      Ended(by=auto,  AwaitingTiebreak  ForfeitDialog（长按 1s + 理由）
   reason=knockout)    reason=timeout) → set_tiebreak      → Ended(by=referee)
                                            │
                                            ▼
                                   Ended(by=referee, reason=tiebreak)

操作记录

{
  "id": "evt-0007",
  "atMs": 1761998400000,
  "actor": "referee",
  "action": "forfeit",
  "loser": 0,
  "reason": "equipment",
  "note": "图传模块断电",
  "hp": [76, 100],
  "remainingMs": 161000,
  "round": 2,
  "score": [1, 0]
}

• 落盘：<app_data>/matches/<yyyy-mm-dd>/<matchId>/events.ndjson（追加写，不覆盖），另有 match.json 存最终结果。
• 导出：match_export 把 result.csv 与 events.ndjson 放到录制目录，供组委会归档。
• 更正：match_undo（5 s 内）或 match_reopen_round（带理由）；任何更正都新增记录，不删除原记录。

规则缺口（手册未定义，客户端不臆造）

缺口	客户端默认行为	需要谁定
警告/红黄牌累计	不实现累计逻辑，只有"理由 + 备注"	组委会
判负后是否重赛	只记录 reason，不自动重开	主裁判
平血"最快开始移动"的判定依据	人工选择，必填备注	主裁判
设备故障（图传中断）导致无法比赛	人工裁定：技术暂停 / 判负 / 重赛	主裁判
技术暂停超时（>5 分钟）	提示超时，不自动判负	主裁判

手册 1.0.0 的更新日志提到"添加了详细的扣血、判罚规则与单局时间"，但当前公开页面只给出了 上方规则表列出的内容（扣血 3 点、技术暂停 5 分钟、四条胜负条件）。如果组委会另有一份判罚细则（红黄牌、犯规等级），需要提供原文，否则界面不写死任何罚则。

---

风险与待确认事项

风险

#	风险	概率/影响	缓解
R1	客户端判负 ≠ 硬件血量：协议只有上行（MsgType 1–5），没有下行控制，判负后对方装甲板仍报 100	高 / 高	界面明确写"只改变判定与记录，不改变硬件血量"；不伪造 HP；若要硬件生效必须另做固件+协议（Q2）
R2	跨端不同步：裁判端判负/暂停，操作位用户端看不到	高 / 高	v1 只作用于裁判端与直播；v2 用 5601 广播新 MsgType（见下）并加共享码签名；现场先用对讲机兜底
R6	动效拖慢低配裁判机（双路 canvas + CSS 动画）	中 / 中	只用 transform/opacity；禁连续动画；低动效开关；实测 30 min 不掉帧
R7	录制与比赛状态机耦合（自动起停误伤手动录制）	中 / 中	状态机只发事件；"随比赛自动录制"做成开关，默认开
R8	直播泄密（IP/token/密码入口出现在画面里）	中 / 高	broadcast 视图白名单渲染；不渲染 addr/url；只读态；截图核对清单
R9	规则变更/规则缺口（平血、超时、罚则）	中 / 中	规则参数可配置（MatchConfig）；缺省行为全部"人工裁定 + 记录"
R10	中文排版回归（字距、字重、字号）	中 / 低	沿用"中文不加字距"；只换 token 不动排版规则；逐页截图对比
R11	光敏/无障碍（红闪、脉动）	低 / 中	≤ 3 Hz、面积 < 25%、prefers-reduced-motion 降级、低动效开关

R2 的可选技术方案（若用户要跨端同步）

// protocol/src/lib.rs 新增（不改动已有枚举值）
pub enum MsgType { Video = 1, Subscribe = 2, Hello = 3, Heartbeat = 4, ArmorHealth = 5, MatchControl = 6 }

// 载荷：version(1) op(1) team(1) seq(4) issued_unix_ms(8) mac(16)
// op: 1=pause 2=resume 3=forfeit 4=reset 5=state-sync

• 裁判端以 REFEREE_ID 广播到 5601；用户端在装甲板监听里增加一个 MsgType::MatchControl 分支（不改相机订阅逻辑）。
• 安全：局域网里任何人都能发 UDP，所以必须带共享码派生 MAC（检录时裁判端生成 6 位码，双方在客户端输入），否则队伍可以伪造"对方判负"。
• 固件兼容性待验证：装甲板固件只认 MsgType::ArmorHealth，未知类型按现有 decode_header 逻辑返回 None 被忽略；但上线前必须在实机上验证"未知 MsgType 不会让板子异常"。

需要用户确认的问题

比赛语义

1. Q1 客户端"一键判负"要不要让用户端（操作位）也看到？如果需要，是否接受"局域网广播 + 共享码"的方案（R2）？
2. Q2 判负/技术暂停是否需要改变装甲板硬件血量（例如判负后立即把对方 HP 打到 0）？这需要改固件 + 协议，属于另一个工程。
3. Q3 技术暂停期间的命中：如实显示并标红（当前建议），还是冻结/忽略？谁来确定"暂停开始"的时间点——客户端按钮，还是场边裁判口头通知后由裁判端按下？
4. Q4 平血时"本局最快开始移动的一队"由谁录入？是否接受"裁判端手动点选一方 + 必填备注"？
5. Q5 是否需要 BO3/BO5 的系列赛比分与"第 N 局"编排？队伍名/编号从哪来（手工输入 vs 导入名单）？

直播

6. Q6 输出分辨率与帧率（1080p30 / 720p60？）、推流平台（B 站 / 抖音 / 校内大屏 / 录播）？安全区按哪个标准？
7. Q7 是否用 OBS 窗口采集（推荐，方案 A）？还是需要独立输出窗口 / 透明背景（方案 B）？
8. Q8 包装层需要哪些固定素材：赛事名、校徽、赞助商 LOGO、选手照片/队徽？由谁提供、什么格式？

录制与部署

• 录制是否随比赛状态自动起停？文件名是否包含双方队名与局次？
• 现场优先支持哪个平台？当前默认 Rust target 为 aarch64-apple-darwin；Windows 构建需要显式指定宿主 target。

附录 A：热键总表

键	范围	动作	备注
F11 / ⌃⌘F / Alt+Enter	全局	全屏切换	400 ms 去抖
Esc	全局	关最上层（对话框 → 抽屉 → 全屏）	逐层关闭
Ctrl/Cmd+K	全局	命令面板（设置/维护/直播/回放）	替代主界面按钮
Ctrl/Cmd+Shift+B	全局	切换直播视图	仅裁判端
Ctrl/Cmd+Enter	裁判端	开始本局	phase ∈ {Idle, Ready}
Ctrl/Cmd+Shift+P	裁判端	技术暂停	弹对话框
Ctrl/Cmd+Shift+F	裁判端	判负	仍需长按确认
Ctrl/Cmd+1 / +2	裁判端	选中红/蓝（对话框内）	—
Space	仅回放	播放/暂停	比赛中禁止
←/→、Shift+←/→	仅回放	±1 s / ±5 s	—
M	仅回放	打标记	写入事件
Tab（按住）	全局	显示当前视图快捷键	半透明面板
Ctrl/Cmd+R	全局	刷新快照（现有 refresh）	—

附录 B：验收标准（提议）

项	标准	验证方法
全屏	F11 切换 < 350 ms；切 10 次不卡死、不丢键	手工
计时	3 分钟误差 < 200 ms；切窗口/最小化不失速	与手机秒表对比 3 次
判负	必须长按 ≥ 1000 ms；< 1000 ms 不生效；撤销窗口 5 s	自动化 + 手工
技术暂停	申请表单不勾"已批准"无法开始；5:00 倒计时准确	手工
直播	安全区内无越界元素；不出现 IP/token/设置入口	截图核对清单
动效	30 min 双路运行，主线程不掉帧（≥ 25 fps）	性能面板
无障碍	关键文字对比 ≥ 4.5:1；prefers-reduced-motion 下无位移动画	对比度工具 + 开关
回归	视频/血量/装甲板/录制/维护五项原功能全部可用	回归清单

附录 C：范围

1. 不做网络 OTA / 设备自升级（与固件维护 的边界一致）。
2. 不做修改固件源码；打包只组装已有产物。
3. 不做从画面推算"移动先后"、命中位置、弹道等规则数据。
4. 不做直播的透明背景/虚拟摄像头/NDI。
5. 不做多语言（中文界面为唯一语言，符合约束）。
6. 不做用户账号/云端同步。