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 例。

web/src/admin/tests/lan-display-card.test.ts

@@ -0,0 +1,123 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+/**
+ * 「局域网大屏」卡片的接线与文案。
+ *
+ * 组件本身没有 DOM 测试环境（仓库里只有「纯函数 + 源码断言」这一套），所以这里钉两件事：
+ * 卡片必须出现的那几句原文，以及它只从 `adminApi.systemNetwork()` 拿地址——
+ * 现场端口/路径改过时，页面里任何写死的 `19540` / `http://…/display` 都会生成一条假链接。
+ */
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+let reply: () => Response = () => jsonResponse({ ok: true, data: null })
+
+// 必须在导入被测模块之前装好：ApiClient 构造时就把当时的 fetch 绑进实例。
+globalThis.fetch = (async () => reply()) as typeof fetch
+
+function respondWith(response: () => Response): void {
+  reply = response
+}
+
+const { ApiError, adminApi } = await import('../api/client')
+
+const PAGE = readFileSync(new URL('../pages/DisplayPage.vue', import.meta.url), 'utf8')
+
+test('卡片文案齐全：标题、一句话说明、复制反馈、扫码说明、空态', () => {
+  assert.match(PAGE, /局域网大屏/)
+  assert.match(PAGE, /在别的设备浏览器打开下面的地址，就是一块大屏/)
+  assert.match(PAGE, /手机扫码直接打开/)
+  assert.match(PAGE, /已复制/)
+  assert.match(PAGE, /未检测到局域网地址（可能是没插网线 \/ 只有回环）/)
+})
+
+test('链接本身就是可点的新窗口链接', () => {
+  assert.match(PAGE, /<a class="lan-link" :href="item\.url" target="_blank" rel="noopener">/)
+})
+
+test('页面的地址只来自 lanDisplayLinks()，不写死端口或路径', () => {
+  assert.match(PAGE, /import \{ copyText, lanDisplayLinks \} from '\.\/lanDisplay'/)
+  assert.match(PAGE, /lanDisplayLinks\(lanInfo\.value\)/)
+  // 19540 一旦出现在页面里，就说明有人在拼地址时替服务端做了决定。
+  assert.doesNotMatch(PAGE, /19540/)
+})
+
+test('二维码只给第一个地址，且用的是矢量 SVG', () => {
+  assert.match(PAGE, /v-if="index === 0 && lanQrSvg !== null"/)
+  assert.match(PAGE, /import \{ encodeQr, qrToSvg \} from '@\/shared\/qrcode'/)
+  assert.match(PAGE, /qrToSvg\(first\.url, \{ scale, margin: QR_MARGIN, ecc: 'M' \}\)/)
+})
+
+test('复制按钮走 copyText（含非安全上下文回退），失败有提示', () => {
+  assert.match(PAGE, /await copyText\(url\)/)
+  assert.match(PAGE, /toast\.error\('复制失败'/)
+})
+
+test('访客按只读说明拦住，不整页报错', () => {
+  assert.match(PAGE, /只有登录后的录入员 \/ 管理员能查看局域网地址，当前为只读访客。/)
+  // 提示必须由 computed 直接渲染：写成「挂载时把它复制进一个 ref」会在身份就绪后永远不清
+  // （2026-09-12 真浏览器复现：管理员登录后卡片仍停在访客态，接口一次都没请求）。
+  assert.match(PAGE, /<p v-if="lanGateReason !== null" class="notice">/)
+})
+
+test('接口不可用时卡片给说明，页面照常渲染其它卡片', () => {
+  assert.match(PAGE, /读不到局域网地址：/)
+  // 读失败不能清空其它区域；卡片自己的提示条与在线大屏的提示条是两条独立通路。
+  assert.match(PAGE, /lanProblem\.value =/)
+})
+
+test('systemNetwork：403 不降级成示例地址', async () => {
+  respondWith(() =>
+    jsonResponse({ ok: false, error: { code: 'FORBIDDEN', message: '需要录入员及以上权限' } }, 403),
+  )
+
+  await assert.rejects(
+    () => adminApi.systemNetwork(),
+    (error: unknown) => {
+      assert.ok(error instanceof ApiError)
+      assert.equal(error.code, 'FORBIDDEN')
+      return true
+    },
+  )
+})
+
+test('systemNetwork：后端连不上时给示例地址，让示例模式也能看到卡片', async () => {
+  respondWith(() => {
+    throw new TypeError('fetch failed')
+  })
+
+  const info = await adminApi.systemNetwork()
+
+  assert.equal(info.port, 19540)
+  assert.equal(info.displayPath, '/display')
+  assert.ok(info.addresses.length > 0)
+  // 示例地址必须是私有段，不能是回环或公网地址。
+  for (const address of info.addresses) {
+    assert.match(address.ip, /^(10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.)/)
+  }
+})
+
+test('systemNetwork：接口存在时按服务端下发的端口与路径透传', async () => {
+  respondWith(() =>
+    jsonResponse({
+      ok: true,
+      data: {
+        port: 8080,
+        displayPath: '/screen',
+        adminPath: '/admin',
+        addresses: [{ ip: '192.168.1.23', interface: 'eth0', family: 'ipv4' }],
+      },
+    }),
+  )
+
+  const info = await adminApi.systemNetwork()
+  assert.equal(info.port, 8080)
+  assert.equal(info.displayPath, '/screen')
+})

web/src/admin/tests/lan-display-refresh.test.ts

@@ -0,0 +1,38 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+
+/**
+ * 「局域网大屏」卡片的加载时机回归钉子。
+ *
+ * 真事故（2026-09-12 用真 Chromium + 真服务端复现）：`refreshLan()` 在挂载时跑，
+ * 而 `auth` 是**异步**加载的 —— 那一刻 `auth.readOnly` 必然为 true，于是卡片把
+ * 「当前为只读访客」写进 `lanProblem` 这个**普通 ref** 就返回了；等身份落定后
+ * 没有任何东西再触发它，结果：
+ *   - 卡片永远停在访客态（管理员登录后也一样）；
+ *   - `/api/system/network` **一次都没被请求**。
+ * 页面级测试在仓库里跑不起来（没有 jsdom / @vue/test-utils），所以这里退化成源码断言：
+ * 钉住「gate 由 computed 直接渲染」+「gate 变 null 时会重跑加载」这两件事，
+ * 防止以后重构又把它改回「写死进 ref 就完事」。
+ */
+const SOURCE = readFileSync(new URL('../pages/DisplayPage.vue', import.meta.url), 'utf8')
+
+test('访客提示直接由 computed 渲染，不从 ref 里读（否则身份就绪后不会消失）', () => {
+  assert.match(SOURCE, /<p v-if="lanGateReason !== null" class="notice">/, 'gate 必须直接绑 computed')
+  assert.match(SOURCE, /const lanGateReason = computed\(/, 'gate 必须是 computed')
+  // 反面：把 gate 写进 lanProblem 后就 return，是本事故的写法
+  assert.doesNotMatch(
+    SOURCE,
+    /lanProblem\.value = lanGateReason\.value/,
+    '不允许把 gate 写进 lanProblem：那是个普通 ref，身份就绪后不会自己清掉',
+  )
+})
+
+test('身份就绪（gate 变 null）时必须重跑一次加载', () => {
+  assert.match(SOURCE, /watch\(lanGateReason,/, '必须 watch gate')
+  assert.match(
+    SOURCE,
+    /watch\(lanGateReason,[\s\S]{0,200}?refreshLan\(\)/,
+    'watch 的回调里必须调用 refreshLan()，否则接口永远不会被请求',
+  )
+})

web/src/admin/tests/lan-display.test.ts

@@ -0,0 +1,133 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import type { NetworkInfo } from '@/shared'
+import { copyText, displayUrl, lanDisplayLinks } from '../pages/lanDisplay'
+
+/**
+ * 「局域网大屏」卡片的两条硬要求：
+ *  1. 地址完全由服务端下发的 port / displayPath 拼出来——现场端口或路径改过时，
+ *     前端写死的那个数会安静地生成一条打不开的链接；
+ *  2. 复制在非安全上下文里也得成功。面板就是从 `http://192.168.x.x:19540` 打开的，
+ *     那里 `navigator.clipboard` 是 undefined，必须退到 execCommand + 临时 textarea。
+ */
+
+const NETWORK: NetworkInfo = {
+  port: 19540,
+  displayPath: '/display',
+  adminPath: '/admin',
+  addresses: [
+    { ip: '192.168.1.23', interface: 'eth0', family: 'ipv4' },
+    { ip: '10.0.8.7', interface: 'wlan0', family: 'ipv4' },
+  ],
+}
+
+test('地址用服务端下发的端口与路径拼，不写死 19540 / /display', () => {
+  assert.equal(displayUrl(NETWORK.addresses[0]!, NETWORK), 'http://192.168.1.23:19540/display')
+
+  // 换个端口与路径，拼出来必须跟着变。
+  const custom: NetworkInfo = { ...NETWORK, port: 8080, displayPath: '/screen' }
+  assert.equal(displayUrl(custom.addresses[0]!, custom), 'http://192.168.1.23:8080/screen')
+  assert.deepEqual(
+    lanDisplayLinks(custom).map((link) => link.url),
+    ['http://192.168.1.23:8080/screen', 'http://10.0.8.7:8080/screen'],
+  )
+})
+
+test('IPv6 地址加方括号，否则端口会被当成地址的一部分', () => {
+  const info: NetworkInfo = { ...NETWORK, addresses: [{ ip: 'fe80::1', interface: 'eth0', family: 'ipv6' }] }
+  assert.equal(displayUrl(info.addresses[0]!, info), 'http://[fe80::1]:19540/display')
+})
+
+test('每个地址都摊成一条链接，顺序与服务端一致', () => {
+  const links = lanDisplayLinks(NETWORK)
+  assert.deepEqual(
+    links.map((link) => link.ip),
+    ['192.168.1.23', '10.0.8.7'],
+  )
+})
+
+test('没地址时给空数组（页面据此显示空态）', () => {
+  assert.deepEqual(lanDisplayLinks({ ...NETWORK, addresses: [] }), [])
+})
+
+test('端口为 0 时给空数组，不拼 http://ip:0/display 这种点不开的链接', () => {
+  assert.deepEqual(lanDisplayLinks({ ...NETWORK, port: 0 }), [])
+})
+
+test('复制：navigator.clipboard 不存在时走到 execCommand 回退', async () => {
+  const seen: string[] = []
+  const ok = await copyText('http://192.168.1.23:19540/display', {
+    clipboard: null, // 非安全上下文里就是这个值
+    legacyCopy: (text) => {
+      seen.push(text)
+      return true
+    },
+  })
+
+  assert.equal(ok, true)
+  assert.deepEqual(seen, ['http://192.168.1.23:19540/display'])
+})
+
+test('复制：clipboard 存在但被拒绝（writeText reject）时也走到回退', async () => {
+  let legacyCalls = 0
+  const ok = await copyText('addr', {
+    clipboard: {
+      writeText: () => Promise.reject(new Error('NotAllowedError')),
+    },
+    legacyCopy: () => {
+      legacyCalls++
+      return true
+    },
+  })
+
+  assert.equal(ok, true)
+  assert.equal(legacyCalls, 1)
+})
+
+test('复制：clipboard 成功时不该再走回退', async () => {
+  const written: string[] = []
+  let legacyCalls = 0
+  const ok = await copyText('addr', {
+    clipboard: {
+      writeText: async (text) => {
+        written.push(text)
+      },
+    },
+    legacyCopy: () => {
+      legacyCalls++
+      return true
+    },
+  })
+
+  assert.equal(ok, true)
+  assert.deepEqual(written, ['addr'])
+  assert.equal(legacyCalls, 0)
+})
+
+test('复制：两条路都不通时返回 false，不谎报成功', async () => {
+  assert.equal(await copyText('addr', { clipboard: null, legacyCopy: () => false }), false)
+  assert.equal(
+    await copyText('addr', {
+      clipboard: null,
+      legacyCopy: () => {
+        throw new Error('document.execCommand is not a function')
+      },
+    }),
+    false,
+  )
+  // node 里既没有 navigator.clipboard 也没有 document：不能抛异常。
+  assert.equal(await copyText('addr', { clipboard: null }), false)
+})
+
+const SOURCE = readFileSync(new URL('../pages/lanDisplay.ts', import.meta.url), 'utf8')
+
+test('回退实现真的用临时 textarea + execCommand，并且会把 DOM 清理干净', () => {
+  assert.match(SOURCE, /doc\.execCommand\('copy'\)/)
+  assert.match(SOURCE, /doc\.createElement\('textarea'\)/)
+  assert.match(SOURCE, /doc\.body\.appendChild\(area\)/)
+  // 不摘掉临时节点，每点一次复制就在 body 里留一个隐身 textarea。
+  assert.match(SOURCE, /finally \{[\s\S]*area\.remove\(\)/)
+  // 先 clipboard 后回退的顺序不能反：优先走异步剪贴板，失败才退。
+  assert.match(SOURCE, /await clipboard\.writeText\(text\)/)
+})