feat(console,admin): kiosk 不再点击穿透 + 压住任务栏；大屏控制页新增「局域网大屏」（链接/复制/二维码）dev_0.4.0

## ① 现场问题：kiosk 窗口点击穿透（原设计方向反了） `displays.js` 原来对多屏 kiosk 调 `setIgnoreMouseEvents(true)`，注释写的是「防止现场误触」——但该 API 的语义是「本窗口忽略鼠标」，点击会**落到它后面的窗口或桌面**，现场想防的误触正好变成误点别的东西；被忽略鼠标的窗口也点不活。现在窗口**默认吞掉鼠标、不穿透**。配置项**改名**为 `display.allowClickThrough`（缺省 false；显式 true 才穿透）。 **旧键 `display.ignoreMouse` 完全不读**——老机器的配置文件里还写着旧版模板留下的 `ignoreMouse: true`，而配置策略是「已存在不覆盖」，只改默认值等于老机器升级后照样穿透；改名才能让默认值真正生效。启动时若发现旧键会记一条中文提示（只记一次），并在合并后的配置里把它剥掉，防止将来有人再读到那个陈年 true。（不是自动改写用户配置文件：无法区分「操作员刻意写的 true」与「旧模板留下的 true」。） ## ② 现场问题：任务栏盖住 kiosk 窗口、被盖住后抢不回前台原顺序是 `setKiosk(true)` 之后又 `setBounds(...)`，在 Windows 上会把窗口从真正的全屏态拽回「恰好铺满该屏的无边框窗口」→ 不是 topmost，任务栏与拖过去的窗口都盖得住。现在固定为 **先 `setBounds` 定位 → 再 `setKiosk(true)` → 最后 `setAlwaysOnTop(true, 'screen-saver')`**（默认层级 `floating` 在 Windows 上仍画在任务栏下面），并加了「已达标就不重复进出 kiosk」的守卫避免重排白闪；非 kiosk 分支会摘掉置顶。 Win 真机行为需现场复核，代码/桩级已验（含顺序与层级的断言）。 ## ③ 新功能：大屏控制页「局域网大屏」卡片 - 服务端新增 `GET /api/system/network`（recorder 及以上）：回本机可用局域网 IPv4 （排除回环/link-local/IPv6，去重，按 192.168/10/172.16-31 优先排序）+ 真实监听端口 + 路径；无地址回 `[]` 不报错。 - 卡片：每个地址一条可点击链接 + 复制按钮，第一个地址配二维码（148px）。 - **二维码是离线自实现的纯 TS 编码器**（版本 1–40 自动、ECC L/M/Q/H、8 种掩码择优），正确性用 **Python OpenCV 真解码**验收：29/29 条解出原文（含中文与边界）， SVG 渲染后再解码 4/4，并把验证过的矩阵冻结成仓库参照用例。 - 复制按**非安全上下文**处理：面板常从 `http://192.168.x.x` 打开，那里 `navigator.clipboard` 是 undefined，自动回退 `execCommand('copy')`。 ## ④ 真机联调抓出并修掉一个时序缺陷（真浏览器 + 真服务端） `DisplayPage` 的 `refreshLan()` 在挂载时跑，而 `auth` 是异步加载的——那一刻 `auth.readOnly` 必然为 true，卡片把「当前为只读访客」写进一个**普通 ref** 就返回了，身份落定后没有任何东西再触发它：**管理员登录后卡片永远停在访客态， `/api/system/network` 一次都没被请求**。改为「gate 由 computed 直接渲染 + watch gate 变 null 时重跑加载」，并补回归钉子。（同时修正了一条把该错误结构当成正确行为的源码断言用例。）端到端证据：真服务 + 局域网 IP（真非安全上下文）→ 卡片列出两个地址、点击复制变「已复制」（走 execCommand 回退）→ 浏览器渲染的二维码截图经 cv2 解出 `http://10.50.101.85:19861/display`。 ## 文档部署指南配置表与多屏行为、使用手册「大屏控制」与局域网设备段、devdocs 05/07/10/13、升级说明新增 dev_0.4.0（含旧键废弃与启动提示）。**无数据迁移**，旧赛事包照常导入。自检：服务端 13 包 ×2；前端 vue-tsc + 645 例 ×2 + build；Console 20 文件 + 68 例。
2026-09-12 16:25:04 +08:00
1 parent ed2c0b3f3c
commit 9ef68c2589
@@ -426,6 +426,15 @@

 **逐屏 / 逐设备切页**：在线大屏列表里每一行都在「当前页」旁带一个页面下拉和「切到此页」按钮，只把**这一块屏 / 这一台设备**切过去，其他屏不受影响；上方「切页」卡片里的「立即跳转」则是**所有大屏一起切**。离线实例的下拉与按钮是灰的，发不到它；点名的大屏一台都没收到指令时会明确提示「目标大屏已离线，请刷新在线列表」，不会谎报成功。列表读取失败时页面会提示「读取在线大屏失败」，并保留上一次的结果，不会把列表清空。

+**局域网大屏**：这张卡片是给「用别的设备当大屏」准备的——把主机在局域网里可用的地址拼成完整链接，手机 / 平板 / 电视浏览器打开就是一块只读大屏（卡片上就写着「在别的设备浏览器打开下面的地址，就是一块大屏。」）。
+
+- 卡片右上角徽标显示「N 个可用地址」；每个地址一行，**点链接**直接在新标签页打开，点旁边的**复制**按钮把完整地址（形如 `http://192.168.1.5:19540/display`）复制到剪贴板，按钮会短暂变成「已复制」；
+- **第一个地址带一个二维码**（下方注明「手机扫码直接打开」），手机相机一扫即可打开，省去手敲长地址；
+- **空态**：显示「未检测到局域网地址（可能是没插网线 / 只有回环）。」——意思是主机当前没有别的设备能用上的地址（网线没插、网卡没起来，或只剩本机回环地址），先在 Windows 网络设置里确认主机已连上局域网；如果显示的是「服务端没有下发大屏端口，暂时拼不出能在别的设备打开的地址。」，那是服务端异常，重启 Console / 服务端后再看；
+- 卡片底部注明「地址由服务端下发的端口与路径拼成；平板上打开后不必登录，大屏本身是只读的」——**平板 / 电视那边不用登录**，只有看这张卡片（也就是本管理面板）才需要身份；
+- **权限**：这张卡片需要**录入员（recorder）及以上**登录才看得到，只读访客（guest）看到的是「只有登录后的录入员 / 管理员能查看局域网地址，当前为只读访客。」；账号权限不足时提示「当前账号没有查看权限，请先登录（该接口需要录入员及以上）。」；
+- 复制失败（浏览器不允许自动复制）时会提示「复制失败 / 浏览器不允许自动复制，请手动选中地址复制」，手动选中地址复制即可。
+
 ### 9.1 显示器菜单（重建被关掉的大屏窗口）

 扩展屏上的大屏窗口平时由服务管理程序（Console）按配置自动开出来，只有在**有人手动关掉了某块屏的大屏窗口**时才需要这一节。
@@ -439,7 +448,7 @@
   - 该屏已经有窗口 → **聚焦窗口**：把窗口提到最前，不重建、不打断正在展示的比分；
   - 该屏还没有窗口，且允许多屏全屏 → **创建全屏窗口**；
   - 该屏还没有窗口，但不允许全屏 → **创建窗口（窗口化）**，行内会注明「单显示器 / 主显示器只能窗口化」；
-   - 已开窗口的行还有一个 **关闭窗口**：全屏大屏窗口是锁定鼠标的，万一开到了错误的屏上，从大屏本身退不出来，用这个按钮收掉；
+   - 已开窗口的行还有一个 **关闭窗口**：全屏大屏窗口画面上没有任何可操作的按钮（也不响应键盘），万一开到了错误的屏上，从大屏本身退不出来，用这个按钮收掉；
 4. **重新排布（按设置重建全部窗口）**：按服务管理程序里的选屏配置重建所有大屏窗口。不在该配置范围内的窗口会被关掉，所以日常只想恢复某一块屏时，请优先用上面的「创建」按钮。

 **为什么单显示器 / 主显示器只能创建窗口化窗口**：全屏窗口会盖住整块屏，而且没有标题栏和关闭按钮。单显示器上开全屏，等于把操作人员的桌面整个盖住；主显示器上开全屏，会把服务管理窗口、管理面板这些工作窗口全部遮住——现场又没有键盘可以退出来。所以这两种情况下按钮只提供窗口化：窗口约占屏幕 80%、居中显示、带标题栏，随时可关。只有「本机有多于一块显示器，且目标不是主显示器」时才放行全屏。
@@ -948,7 +957,7 @@

 > 大屏的标题字体与正文字体取自「系统设置 → 赛事信息 → 字体」（见 14.3）：可选四款内置字体，也可以上传自己的字体；上传字体加载失败时自动回落到默认字体，画面不会出现方块或空白。

-> 除了 Console 开出来的本机大屏窗口，**局域网设备（另一台电脑、电视浏览器）打开 `http://<主机IP>:19540/display` 也能当大屏用**。这类设备会出现在管理端「大屏控制 → 在线大屏」列表里（标记为「局域网浏览器」），也能被单独切页，用法见第 9 节；它们不受 Console 的 kiosk、防熄屏控制（另见常见问题 Q29）。
+> 除了 Console 开出来的本机大屏窗口，**局域网设备（另一台电脑、电视浏览器）打开 `http://<主机IP>:19540/display` 也能当大屏用**。这个地址不用手敲：管理端「大屏控制 → 局域网大屏」卡片里有**可复制的完整链接与二维码**（见第 9 节）。这类设备会出现在管理端「大屏控制 → 在线大屏」列表里（标记为「局域网浏览器」），也能被单独切页，用法见第 9 节；它们不受 Console 的 kiosk、防熄屏控制（另见常见问题 Q29）。

 ### 17.2 轮播与锁定

@@ -6,7 +6,63 @@

 ---

-## dev_0.3.0（当前版本）
+## dev_0.4.0（当前版本）
+
+### 一句话
+
+**没有数据迁移，旧赛事项目包照常导入**：本版修了两个现场问题（kiosk 窗口误点穿、kiosk 窗口被任务栏盖住）并新增一个功能（大屏控制页的「局域网大屏」卡片）。⚠️ 唯一要留意的：**老机器配置文件里的 `display.ignoreMouse: true` 已废弃、不再生效**——升级后大屏窗口自动变成「不穿透」，想恢复穿透要改用新键名。
+
+### ① kiosk 窗口不再点击穿透，旧键 `display.ignoreMouse` 已废弃
+
+- **以前**：多屏 kiosk 窗口默认开启 `setIgnoreMouseEvents(true)`，本意是「不接收误触」，但它的真实语义是「**本窗口完全忽略鼠标**」——点击会落到大屏**后面**的窗口或桌面上，现场想防的误触反而变成误点别的东西；被忽略鼠标的窗口也点不活、被别的窗口盖住后抢不回前台。
+- **现在**：大屏窗口**默认吞掉鼠标点击、不穿透**，点击不会漏到后面的窗口或桌面，被盖住后点一下就能回到最前。
+- **开关改名**：`display.ignoreMouse` → **`display.allowClickThrough`**（默认 `false`）。旧键现在**完全不读**——老机器配置文件里那个 `ignoreMouse: true` 不会再让大屏穿透。
+  - **为什么换键名而不是只改默认值**：旧版默认就是穿透，而且旧版模板已经把 `ignoreMouse: true` 写进了现场机器的配置文件（`%LOCALAPPDATA%\ScoreboardConsole\console\config.json`），而 Console 的规矩是**已存在的用户配置绝不覆盖**——光改默认值救不了老机器，配置文件里那个显式 `true` 会一直压着默认值；也没法区分「操作员刻意要穿透」和「旧模板留下的 true」。换个新键名，旧文件里的旧键自然失效，现场不动配置文件就回到「不穿透」。
+- **升级后第一次启动**，如果配置文件里还留着旧键，Console 会在 `logs\console.log` 里记一条**中文警告（只记一次，不随大屏重排重复刷）**，原文是：
+
+  > 警告：配置项 display.ignoreMouse 已废弃、不再生效：本机配置文件里写的 ignoreMouse: true 会被忽略。大屏窗口现在默认「不穿透」，点击不会再漏到大屏后面的窗口或桌面；要让大屏恢复点击穿透，请改用 display.allowClickThrough: true
+
+  （`ignoreMouse` 后面跟的值会原样照抄你配置文件里写的内容。）**旧键的值一律忽略，也不会被自动改写进你的配置文件。**
+- **确实需要穿透**（把大屏当纯展示层、同一块屏上还要操作别的窗口）才显式写 `display.allowClickThrough: true`，代价是：点击会漏到大屏后面的窗口 / 桌面（误触会点到别的东西），大屏也点不活。
+
+### ② kiosk 窗口现在压得住任务栏
+
+- **以前**：先 `setKiosk(true)` 再 `setBounds(...)`，在 Windows 上会把窗口从真正的全屏态拽回「恰好铺满该屏的无边框窗口」——它不是置顶层，**任务栏与任何拖到这块屏上的窗口都能盖在它上面**；再叠加上一条的穿透，大屏被盖住后还点不活。
+- **现在**：多屏 kiosk 窗口固定置顶在 **`screen-saver` 层级**（Windows 上 `setAlwaysOnTop(true)` 的默认层级 `floating` 仍画在任务栏**下面**，只有 pop-up-menu 及以上才压得住任务栏）。效果：**任务栏盖不住它，别的窗口拖到这块屏上也盖不住它，被盖住后点一下就能回到最前**。
+- 调用顺序固定为「**先 `setBounds` 定位 → 再 `setKiosk(true)` → 最后 `setAlwaysOnTop(true, 'screen-saver')`**」，并加了「已经是对的状态就直接返回」的守卫，避免重排时反复进出 kiosk 导致大屏白闪。窗口化（单屏调试态）会把置顶摘掉。
+
+### ③ 大屏控制页新增「局域网大屏」卡片
+
+- 卡片列出主机在局域网里**可用的地址**，拼成完整链接（形如 `http://192.168.1.5:19540/display`）：链接可点开，旁边有**复制**按钮（复制成功短暂显示「已复制」），**第一个地址还带二维码**，手机扫码即可打开；
+- 地址与端口由服务端 `GET /api/system/network` 下发（真实监听端口与路径，不是写死的），按现场最可能用到的顺序排（`192.168.*` → `10.*` → `172.16–31.*` → 其它）；
+- 没有可用地址时显示「未检测到局域网地址（可能是没插网线 / 只有回环）。」——这不是故障，表示主机当前没有别的设备能连上的地址；
+- 这张卡片**需要录入员（recorder）及以上**登录才看得到，只读访客会被提前拦住。
+
+### ④ 没有数据迁移
+
+- 本版**没有任何数据库迁移**，也没有设置项迁移；旧赛事项目包照常导入、切换、导出，已有榜单数字与升级前一致。
+- 配置文件里那份旧键我们**不会**替你删改（现场那份原样留着，人自己决定），它只是不再生效。
+
+### ⑤ 升级后 3 分钟核对
+
+1. 启动 Console，打开 `logs\console.log`：确认没有意外的报错；
+2. 看多屏大屏：窗口应当压住任务栏、点一下能回到最前，且**点击不会再点到桌面或后面的窗口**（即不穿透）；
+3. 若有老机器配置文件里写着 `ignoreMouse: true`，日志里应能看到上面那条「已废弃」警告——这是正常的，行为已是「不穿透」；
+4. （可选）确实要穿透的机器：在 `%LOCALAPPDATA%\ScoreboardConsole\console\config.json` 里写 `"allowClickThrough": true`，重启 Console；
+5. 用录入员及以上账号进「大屏控制」页，确认右侧有「局域网大屏」卡片，点「复制」能复制链接、手机能扫第一个地址的二维码打开大屏；
+6. 用《上线检查清单》过一遍。
+
+### ⑥ 详细说明在哪
+
+| 想了解 | 看 |
+| --- | --- |
+| 多屏 kiosk 的鼠标 / 置顶行为 | 《部署指南》6.2 配置表、7.4 |
+| 「局域网大屏」卡片怎么用 | 《使用手册》第 9 节 |
+| 接口与字段 | `devdocs/05` 大屏控制与运维 |
+
+---
+
+## dev_0.3.0

 ### 一句话

@@ -114,7 +114,7 @@
 检查 HDMI、扩展显示模式、Console「大屏窗口」状态，点「重新排布」；服务端未就绪时最多等 20 秒才开屏；单屏窗口化时按 `F11` 切全屏。详见 [部署指南 · 故障排查](./部署指南.md#9-故障排查)。

 **Q22：单屏和多屏的显示方式有什么不同？**
-单屏时大屏以窗口化方式打开，按 `F11` 切全屏；多屏时除内置屏外每块屏一个 kiosk 全屏窗口，各锁一页，不响应 F11，也不接收鼠标。
+单屏时大屏以窗口化方式打开，按 `F11` 切全屏；多屏时除内置屏外每块屏一个 kiosk 全屏窗口，各锁一页，不响应 F11，**默认吞掉鼠标点击、不穿透**（点击不会漏到后面的窗口或桌面，被别的窗口盖住后点一下就能回到最前）；确实要穿透时在配置里显式写 `display.allowClickThrough: true`（旧键 `display.ignoreMouse` 已废弃、不再生效），详见 [部署指南 6.2](./部署指南.md)。

 **Q23：大屏为什么不自动轮播？**
 Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点「解锁」后开始轮播，每 20 秒一页；公告页不参与轮播。
@@ -317,7 +317,7 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
 | `display.pages` | `["standings","medals","individual","results"]` | 多屏时按屏序轮转锁定的页面；可加入 `live`（实时赛况）等页面值，见 7.4 |
 | `display.pageParam` | `page` | 页面 URL 参数名 |
 | `display.kiosk` | `true` | 多屏时是否 kiosk 全屏（单屏恒为窗口化） |
-| `display.ignoreMouse` | `true` | 多屏窗口是否忽略鼠标 |
+| `display.allowClickThrough` | `false` | 多屏 kiosk 窗口是否**允许点击穿透**。默认 `false` = 窗口吞掉鼠标点击：点击不会漏到大屏后面的窗口 / 桌面，被别的窗口盖住后点一下就能回到最前。显式写 `true` 才穿透，代价是**误触会点到后面别的东西**、大屏也点不活。本键是 `display.ignoreMouse` **改名**来的 |
 | `display.reloadEveryHours` | `24` | 定时重载兜底，`0` = 关闭 |
 | `display.waitForServerMs` | `20000` | 服务端未就绪时，最多等这么久也先把大屏开出来 |
 | `display.backgroundColor` | `#0b0f1a` | 大屏窗口底色，减少加载白闪 |
@@ -328,6 +328,8 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
 | `log.maxFileBytes` | `4194304` | 单个日志文件上限，超出后轮转为 `.1` |

 > 配置缺项会自动使用内置默认值；JSON 语法错误时回落到全默认值，并在窗口顶部提示。
+>
+> 配置文件里若还留着**已废弃的** `display.ignoreMouse`（旧版模板会写 `ignoreMouse: true`），这个键现在**完全不读**，启动时会在 `logs\console.log` 里记一条中文警告（只在启动记一次，不随大屏重排重复刷）：旧键已废弃、现在默认不穿透、想穿透改用 `display.allowClickThrough: true`。旧键的值一律忽略，也**不会**被自动改写进你的配置文件。

 ### 6.3 修改端口

@@ -369,7 +371,7 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da

 - 除内置屏外的每块屏各开一个 kiosk 全屏窗口；
 - 每块屏**锁定一个页面**，按 `display.pages` 的顺序轮转分配；
- 多屏 kiosk 不响应 F11，也不接收鼠标（`ignoreMouse`），也不显示任何调试标识；
+- 多屏 kiosk 不响应 F11，也不显示任何调试标识；窗口**默认吞掉鼠标点击、不穿透**——点击不会漏到大屏后面的窗口或桌面，被别的窗口盖住后点一下就能回到最前，只有显式配 `display.allowClickThrough: true` 才会让点击穿透（代价是误触会点到后面的东西、大屏也点不活）；kiosk 窗口固定置顶在 `screen-saver` 层级，**压得住任务栏**，别的窗口拖到这块屏上也盖不住它；
 - 可用的页面值：`standings`（总积分榜）、`medals`（单位奖牌榜）、`individual`（个人积分奖牌榜）、`results`（分项成绩）、`live`（实时赛况）、`announcement`（公告）；管理端切页用的是同一批页面的规范名 `team-medals` / `athlete-standings` / `event-results`，两种写法大屏都认。把 `live` 加进 `display.pages`，就能把某块屏固定成「实时赛况」（`live` 也认 `live-results` / `实时赛况` / `实时` / `赛况` 这些别名，与其它页一样）。
 - 这一页现在叫 **「单位奖牌榜」**（旧称「团体奖牌榜」容易和「团体项目的奖牌」混淆，已改名）；**旧名 `团体奖牌榜` 仍作为别名被接受**，老配置里的 `display.pages`、大屏地址里 `page=团体奖牌榜` 这类老链接都照常生效，不需要改。

@@ -377,6 +379,8 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da

 管理端「大屏控制」页有**显示器**卡片，可以给指定显示器单独开窗或收窗。这张卡片只在**从服务管理窗口点「打开服务端管理面板」打开的那个窗口**里可用；用浏览器直接打开管理面板时，卡片会提示此功能不可用。

+同一页右侧还有「**局域网大屏**」卡片：把本机可用的局域网地址拼成完整链接（可点开、可一键复制），第一个地址还带二维码，别的设备扫码即可当大屏用。卡片需**录入员及以上**登录才看得到，用法见《使用手册》第 9 节。
+
 - 列出本机每块显示器（名称、分辨率、缩放、是否主显示器、当前有没有大屏窗口、是全屏还是窗口化）；
 - 先在「窗口页面」里选页面，再对某块屏点「创建全屏窗口」或「创建窗口（窗口化）」；已经开着窗口的屏显示「聚焦窗口」与「关闭窗口」；
 - **全屏只对「多显示器 + 非主显示器」开放**：只接一块屏、或选中的是主显示器时只能创建窗口化窗口（全屏会把桌面整个盖住又退不出来）。请求被降级时窗口照开，提示里会写明原因；
@@ -415,6 +419,7 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
 http://<主机IP>:19540/display
 ```

+- 这个地址不用手敲：管理端「大屏控制 → 局域网大屏」卡片里有**可复制的完整链接**与**二维码**（第一个地址），别的设备扫码或在浏览器里粘贴即可打开（该卡片需录入员及以上登录才看得到）；
 - 需要主机设置固定 IP，且设备与主机在同一局域网；
 - 安卓电视一般常亮，无需额外防熄屏；
 - 浏览器方案**不受** Console 的 kiosk、防熄屏、选屏控制，字体与动画表现以实际设备为准；