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 例。
This commit is contained in:
AskaEth committed
1 parent
ed2c0b3f3c
commit
9ef68c2589
33 files changed
+2923
-95
No files matched your search
+6
-4
@@ -121,9 +121,9 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
|
||||
|
||||
| 场景 | 行为 |
|
||||
| --- | --- |
|
||||
| 只有一块屏 | 窗口化（屏幕 80% 大小、居中），不做多屏编排，**不跟随** `display-metrics-changed`（分辨率/缩放变化不重排，行为冻结）；`display-added` / `display-removed` 一直听着，电视插回来会自动排布回 kiosk。监听常驻、只有 `closeAll()`（服务停止 / 应用退出）才摘（回归测试见 `main/displays.test.js`）；`F11` 手动切换全屏，窗口级全屏状态经 `display-preload.js` 下发给页面，页面据此收起自绘标题栏 |
|
||||
| 只有一块屏 | 窗口化（屏幕 80% 大小、居中），不做多屏编排，**不跟随** `display-metrics-changed`（分辨率/缩放变化不重排，行为冻结）；`display-added` / `display-removed` 一直听着，电视插回来会自动排布回 kiosk。监听常驻、只有 `closeAll()`（服务停止 / 应用退出）才摘（回归测试见 `main/displays.test.js`）；`F11` 手动切换全屏，窗口级全屏状态经 `display-preload.js` 下发给页面，页面据此收起自绘标题栏。窗口化窗口**不置顶、不穿透**：F11 全屏完全由用户控制，置顶会把它变成一块收不掉、盖住一切的覆盖层 |
|
||||
| 模式与 URL | **必须永远一致**：模式（窗口化 / kiosk）记在窗口的 entry 上，谁改模式谁按新模式重载 URL。`layout()` 只对排布自己开的窗口套用全局 `single`，管理面板手动开的窗口保持自己的模式——否则会出现「窗口化窗口被改成 kiosk 全屏、URL 里还留着 `windowed=1`」这种页面认知与窗口真实模式脱钩、标题栏画反的问题（回归测试见 `main/displays.test.js`）|
|
||||
| 多块屏 | 除内置屏外的每块屏一个 kiosk 窗口，按 `display.bounds`（DIP）定位，窗口 `setIgnoreMouseEvents(true)`，光标由页面 CSS 隐藏 |
|
||||
| 多块屏 | 除内置屏外的每块屏一个 kiosk 窗口，按 `display.bounds`（DIP）定位，光标由页面 CSS 隐藏。窗口**默认吞掉鼠标、不穿透**：`setIgnoreMouseEvents(true)` 的语义是「本窗口忽略鼠标」，点击会落到它后面的窗口或桌面上（现场想防的误触反而变成误点别的东西），被忽略鼠标的窗口也点不活、抢不回前台；只有确实要把大屏当纯展示层、同一块屏上还要操作别的窗口时才显式配 `display.allowClickThrough: true`。这个开关是从 `display.ignoreMouse` **改名**来的：旧版默认穿透，而且旧版模板已经把 `ignoreMouse: true` 写进了现场机器的用户配置（`userpaths.js` 不覆盖用户文件），只改默认值救不了老机器——换个新键名，旧键自然失效；启动时若发现配置里还留着旧键，会在 `logs/console.log` 里记一条提示（只记一次），说明它已废弃、现在默认不穿透、想穿透该写哪个键。窗口**置顶在 `screen-saver` 层级**（Windows 上 `setAlwaysOnTop(true)` 的默认层级 `floating` 仍画在任务栏下面，只有 pop-up-menu 及以上才压得住任务栏），所以别的窗口拖到这块屏上盖不住它、任务栏也盖不住它，被盖住后点一下就能回到最前。调用顺序**必须**是「先 `setBounds` 定位 → 再 `setKiosk(true)` → 最后置顶」：反过来会把窗口从真正的全屏态拽回「恰好铺满该屏的无边框窗口」，既不是 topmost、也压不住任务栏（回归测试见 `main/displays.test.js`）|
|
||||
| 选屏 | 运行时枚举，不写死坐标；`selection` 可选 `all-secondary`（默认，用 `display.internal` 排除内置屏）/ `all` / `specified` |
|
||||
| 页面锁定 | 每块屏各锁一页，URL 形如 `http://127.0.0.1:19540/display?page=standings&lock=1&screen=<id>&instance=<host>-<id>`，页序按 `display.pages` 轮转 |
|
||||
| 防熄屏 | Console 启动即生效，退出时释放；前台后台都算 |
|
||||
@@ -163,7 +163,8 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
|
||||
| `display.pages` | `["standings","medals","individual","results"]` | 按屏序轮转锁定；只填大屏支持的页名 |
|
||||
| `display.pageParam` | `page` | 页面 URL 参数名 |
|
||||
| `display.kiosk` | `true` | 多屏时是否 kiosk（单屏恒窗口化） |
|
||||
| `display.ignoreMouse` | `true` | 多屏窗口是否忽略鼠标 |
|
||||
| `display.allowClickThrough` | `false` | 多屏 kiosk 窗口是否**允许点击穿透**（`setIgnoreMouseEvents(true)`）。写 `true` 后该窗口忽略所有鼠标事件：点击落到它后面的窗口/桌面（现场误触会点到别的东西），大屏也点不活、被盖住后抢不回前台。只把大屏当纯展示层、且要在同一块屏上操作别的窗口时才开 |
|
||||
| `display.ignoreMouse` | — | **已废弃 → 见 `display.allowClickThrough`**。旧版默认 `true` 且被旧模板写进现场机器的用户配置，只改默认值救不了老机器，所以换了键名；本键现在**完全不读**，配置文件里留着它只会让启动日志多一条提示，不影响行为 |
|
||||
| `display.reloadEveryHours` | `24` | 定时重载兜底，0 = 关闭 |
|
||||
| `display.waitForServerMs` | `20000` | 服务端未就绪时开大屏的兜底等待 |
|
||||
| `display.backgroundColor` | `#0b0f1a` | 窗口底色，减少加载白闪 |
|
||||
@@ -171,7 +172,7 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
|
||||
| `admin.width` / `admin.height` | `1280` / `860` | 管理窗口初始尺寸（服务端管理面板窗口按 `width` 不小于 1100 取用） |
|
||||
| `log.maxLines` / `log.file` / `log.maxFileBytes` | `2000` / `logs/console.log` / `4194304` | 日志缓冲与文件；`log.file` 相对部署包根目录解析（不随配置搬到用户数据目录） |
|
||||
|
||||
配置缺项自动用内置默认值，文件不存在或 JSON 语法错误时回落到全默认值，并在管理窗口顶部给出提示。
|
||||
配置缺项自动用内置默认值，文件不存在或 JSON 语法错误时回落到全默认值，并在管理窗口顶部给出提示。配置里如果还留着已改名的旧键（目前是 `display.ignoreMouse`），启动时会在 `logs/console.log` 里记一条中文提示（只在启动记一次，不随大屏重排重复刷），说明该键已废弃、现在默认不穿透、要穿透该写哪个键；旧键的值一律忽略，**不会**被自动改写进用户的配置文件。
|
||||
|
||||
## 打包（electron-builder）
|
||||
|
||||
@@ -198,6 +199,7 @@ pnpm pack # 只出目录，不生成安装包，便于现场调试
|
||||
以下内容只做了静态语法检查，需要在 Windows + 真实多显示器环境跑一遍：
|
||||
|
||||
- 多屏 kiosk 定位与 `display-metrics-changed` 重排（改分辨率 / 缩放 / 插拔 HDMI）。
|
||||
- kiosk 窗口的置顶（`setAlwaysOnTop(true, 'screen-saver')`）与任务栏覆盖：能否稳定压住任务栏、别的窗口拖到该屏上会不会盖住它、点击后能否回到最前——`screen-saver` 层级在 Windows 上的实际效果只能在真机上验；`setKiosk` / `setBounds` 的先后顺序同理（Linux 开发机没有 Electron 运行时）。
|
||||
- 管理面板显示器菜单：真正的 kiosk 全屏 / 窗口化结果、`screen.getAllDisplays()` 的 `label` 与主屏判定、`display:list` 返回的 scaleFactor 是否与现场一致。
|
||||
- `powerSaveBlocker` 在长时间后台下的实际效果。
|
||||
- 托盘图标在 Windows 任务栏的显示效果（16px 缩放）。
|
||||
|
||||
+1
-1
@@ -19,7 +19,7 @@
|
||||
"pages": ["standings", "medals", "individual", "results"],
|
||||
"pageParam": "page",
|
||||
"kiosk": true,
|
||||
"ignoreMouse": true,
|
||||
"allowClickThrough": false,
|
||||
"reloadEveryHours": 24,
|
||||
"waitForServerMs": 20000,
|
||||
"backgroundColor": "#0b0f1a"
|
||||
|
||||
+54
-4
@@ -38,7 +38,16 @@ const DEFAULTS = {
|
||||
pages: ['standings', 'medals', 'individual', 'results'],
|
||||
pageParam: 'page',
|
||||
kiosk: true,
|
||||
ignoreMouse: true,
|
||||
// 多屏 kiosk 窗口是否**允许点击穿透**（写 true 才穿透）。默认 false = 窗口吞掉点击，
|
||||
// 可以点活、被盖住后能抢回前台。
|
||||
// 这个键是 display.ignoreMouse 改名来的，**为什么换键名而不是只改默认值**：
|
||||
// 旧版默认 true，而且旧版模板已经把 ignoreMouse: true 写进了现场机器的
|
||||
// <用户根>\console\config.json，userpaths.js 的策略是「已存在就绝不覆盖」——
|
||||
// 光把默认值改成 false 救不了老机器（文件里那个显式 true 会一直压着默认值），
|
||||
// 我们也没法区分「操作员刻意要穿透」和「旧模板留下的 true」（去改用户文件就是猜）。
|
||||
// 换个新键名，老文件里的旧键自然失效，现场不动配置文件就回到不穿透；
|
||||
// 确实要穿透的再显式写 allowClickThrough: true（旧键会触发一条启动提示，见 loadConfig）
|
||||
allowClickThrough: false,
|
||||
reloadEveryHours: 24,
|
||||
// 服务端迟迟没就绪时的兜底：超时后也把大屏开出来，避免现场一片黑
|
||||
waitForServerMs: 20000,
|
||||
@@ -83,12 +92,51 @@ function readJson(file) {
|
||||
}
|
||||
}
|
||||
|
||||
// 改名过的配置键：旧键 → 新键。只提示、**不自动迁移**——改现场机器上的配置文件不是
|
||||
// Console 该做的事，而且「操作员刻意写的」和「旧模板留下的」在文件里长得一模一样，猜错就改了人家的意图。
|
||||
const RENAMED_KEYS = {
|
||||
'display.ignoreMouse': 'display.allowClickThrough'
|
||||
}
|
||||
|
||||
// 看看持久化的配置文件里还留着哪些废弃键。读的是**文件里真实写了什么**（readJson 的原始值），
|
||||
// 不是 merge 之后的结果：merge 出来的值一律带 DEFAULTS，拿它判断会把每个键都当成「用户写过」。
|
||||
// 只在这里算一次、由 index.js 在启动时记一次，绝不在 layout/重排路径里判断，否则日志会被刷爆。
|
||||
function deprecatedKeyNotices(values) {
|
||||
const notices = []
|
||||
// 配置文件内容可能是 null / 数组 / 字符串（JSON 语法合法但不是对象），一律当作「没有旧键」
|
||||
if (!isPlainObject(values)) return notices
|
||||
for (const [oldKey, newKey] of Object.entries(RENAMED_KEYS)) {
|
||||
const [section, key] = oldKey.split('.')
|
||||
if (!isPlainObject(values[section]) || !(key in values[section])) continue
|
||||
notices.push(
|
||||
`配置项 ${oldKey} 已废弃、不再生效：本机配置文件里写的 ${key}: ${JSON.stringify(values[section][key])} 会被忽略。` +
|
||||
`大屏窗口现在默认「不穿透」，点击不会再漏到大屏后面的窗口或桌面；` +
|
||||
`要让大屏恢复点击穿透，请改用 ${newKey}: true`
|
||||
)
|
||||
}
|
||||
return notices
|
||||
}
|
||||
|
||||
// 把改名前的旧键从**合并后的配置**里删掉：要让「旧键失效」彻底一点，
|
||||
// 不能只做到「没人读它」——merge 是通用深合并，旧键会原样留在 cfg.values.display 里，
|
||||
// 以后谁再加一行读旧键的代码，就会读到老机器配置文件里那个陈年 true。
|
||||
// 只动这份内存里的配置，绝不写回用户文件（现场那份要原样留着，人自己决定怎么改）。
|
||||
function stripRenamedKeys(values) {
|
||||
for (const oldKey of Object.keys(RENAMED_KEYS)) {
|
||||
const [section, key] = oldKey.split('.')
|
||||
if (isPlainObject(values[section])) delete values[section][key]
|
||||
}
|
||||
return values
|
||||
}
|
||||
|
||||
function loadConfig(configPath) {
|
||||
const { values, warning } = readJson(configPath)
|
||||
return {
|
||||
path: configPath,
|
||||
values: merge(DEFAULTS, values),
|
||||
warning
|
||||
values: stripRenamedKeys(merge(DEFAULTS, values)),
|
||||
warning,
|
||||
// 提示按**文件里真实写了什么**算，所以传的是 readJson 的原始值，不是上面那份合并结果
|
||||
notices: deprecatedKeyNotices(values)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -123,4 +171,6 @@ function resolveExecutable(exe, configPath, baseDir) {
|
||||
return { path: found || candidates[0], candidates: [...new Set(candidates)] }
|
||||
}
|
||||
|
||||
module.exports = { loadConfig, updateConfig, resolveExecutable }
|
||||
// DEFAULTS 一并导出：displays.test.js 用它断言「随包发布的默认值」本身
|
||||
// （例如 display.allowClickThrough 必须是不穿透），测试里自己写死一份就验不到默认值被改回去
|
||||
module.exports = { DEFAULTS, loadConfig, updateConfig, resolveExecutable }
|
||||
@@ -0,0 +1,87 @@
|
||||
'use strict'
|
||||
|
||||
const assert = require('node:assert/strict')
|
||||
const fs = require('node:fs')
|
||||
const os = require('node:os')
|
||||
const path = require('node:path')
|
||||
const test = require('node:test')
|
||||
|
||||
const { DEFAULTS, loadConfig } = require('./config')
|
||||
|
||||
function makeDir(t) {
|
||||
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scoreboard-config-'))
|
||||
t.after(() => fs.rmSync(dir, { recursive: true, force: true }))
|
||||
return dir
|
||||
}
|
||||
|
||||
// 现场机器上那份用户配置：内容原样写进文件，读的也必须是文件里真实写了什么
|
||||
function loadWith(t, raw) {
|
||||
const dir = makeDir(t)
|
||||
const file = path.join(dir, 'config.json')
|
||||
fs.writeFileSync(file, typeof raw === 'string' ? raw : JSON.stringify(raw, null, 2), 'utf8')
|
||||
return loadConfig(file)
|
||||
}
|
||||
|
||||
test('缺省的 allowClickThrough 不穿透（默认值就是 false）', (t) => {
|
||||
assert.equal(DEFAULTS.display.allowClickThrough, false)
|
||||
const cfg = loadWith(t, { display: {} })
|
||||
assert.equal(cfg.values.display.allowClickThrough, false)
|
||||
assert.deepEqual(cfg.notices, [])
|
||||
})
|
||||
|
||||
test('显式写 allowClickThrough: true 才穿透，且不产生废弃提示', (t) => {
|
||||
const cfg = loadWith(t, { display: { allowClickThrough: true } })
|
||||
assert.equal(cfg.values.display.allowClickThrough, true)
|
||||
assert.deepEqual(cfg.notices, [])
|
||||
})
|
||||
|
||||
// 本次修复的核心回归钉子：老机器升级后，用户配置文件里那个旧版模板写下的
|
||||
// ignoreMouse: true 必须彻底失效（userpaths.js 不会覆盖用户文件，只能靠不读旧键）
|
||||
test('老配置里的旧键 ignoreMouse 已失效：既不生效、也不再是穿透开关', (t) => {
|
||||
const cfg = loadWith(t, { display: { ignoreMouse: true } })
|
||||
|
||||
assert.equal('ignoreMouse' in DEFAULTS.display, false, 'DEFAULTS 里不能再有旧键')
|
||||
assert.equal(cfg.values.display.allowClickThrough, false, '旧键 true 不能把穿透带回来')
|
||||
assert.equal(cfg.values.display.ignoreMouse, undefined, '旧键不该被 merge 进最终配置')
|
||||
|
||||
// 但必须留下一条一次性提示，让现场知道该改哪个键
|
||||
assert.equal(cfg.notices.length, 1)
|
||||
const [notice] = cfg.notices
|
||||
assert.match(notice, /display\.ignoreMouse/)
|
||||
assert.match(notice, /display\.allowClickThrough/)
|
||||
assert.match(notice, /废弃/, '要明说这个键已经不用了')
|
||||
assert.match(notice, /不穿透/, '要明说现在的默认是不穿透')
|
||||
assert.match(notice, /true/, '要给出「确实想穿透」的写法')
|
||||
})
|
||||
|
||||
test('旧键提示只跟着「文件里写了旧键」出现，缺省或新键都不提示', (t) => {
|
||||
// 旧版模板整份配置（现场最常见的形态）：只提示一次，不会按重排/每帧刷
|
||||
const legacyTemplate = loadWith(t, {
|
||||
display: { selection: 'all-secondary', kiosk: true, ignoreMouse: true }
|
||||
})
|
||||
assert.equal(legacyTemplate.notices.length, 1)
|
||||
|
||||
// 新模板（已去掉旧键、写上 new key）不再提示
|
||||
const currentTemplate = loadWith(t, {
|
||||
display: { selection: 'all-secondary', kiosk: true, allowClickThrough: false }
|
||||
})
|
||||
assert.deepEqual(currentTemplate.notices, [])
|
||||
|
||||
// 两个键都在：仍然按「有旧键」提示一次（提示说的是旧键不生效，与新键无关）
|
||||
const both = loadWith(t, { display: { ignoreMouse: true, allowClickThrough: true } })
|
||||
assert.equal(both.notices.length, 1)
|
||||
assert.equal(both.values.display.allowClickThrough, true, '新键显式 true 仍然算数')
|
||||
})
|
||||
|
||||
test('配置文件读不出来/内容不是对象时不报废弃键、也不炸', (t) => {
|
||||
const missing = loadConfig(path.join(makeDir(t), 'nope.json'))
|
||||
assert.deepEqual(missing.notices, [])
|
||||
assert.equal(missing.warning !== null, true)
|
||||
assert.equal(missing.values.display.allowClickThrough, false)
|
||||
|
||||
const broken = loadWith(t, '{ 这不是 JSON')
|
||||
assert.deepEqual(broken.notices, [])
|
||||
|
||||
assert.deepEqual(loadWith(t, 'null').notices, [])
|
||||
assert.deepEqual(loadWith(t, '[1,2,3]').notices, [])
|
||||
})
|
||||
@@ -11,6 +11,11 @@ const SELECTION = {
|
||||
SPECIFIED: 'specified'
|
||||
}
|
||||
|
||||
// 只比窗口矩形本身：getBounds() 在真实 Electron 里会多带几个键，比整对象会永远判不等
|
||||
function sameBounds(a, b) {
|
||||
return Boolean(a) && a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height
|
||||
}
|
||||
|
||||
// 大屏窗口管理：按显示器枚举结果开窗，绝不写死坐标。
|
||||
// 坐标一律用 DIP（display.bounds），页面内部再用 CSS 缩放适配，两边互不干扰。
|
||||
class DisplayManager {
|
||||
@@ -137,7 +142,9 @@ class DisplayManager {
|
||||
frame: false,
|
||||
// 与 Console 主窗口同一套兜底：个别平台会忽略 frame:false
|
||||
titleBarStyle: 'hidden',
|
||||
kiosk: !single && this.display.kiosk !== false,
|
||||
// 这里刻意不给 kiosk：进 kiosk 必须发生在 setBounds 之后，而 setBounds 与 kiosk
|
||||
// 的先后顺序是「压不压得住任务栏」的关键，只留 applyGeometry 一处去管，
|
||||
// 免得构造函数和 applyGeometry 各设一遍、顺序互相打架
|
||||
autoHideMenuBar: true,
|
||||
backgroundColor: this.display.backgroundColor || '#000000',
|
||||
title: `大屏 · ${page}`,
|
||||
@@ -152,8 +159,17 @@ class DisplayManager {
|
||||
}
|
||||
})
|
||||
|
||||
// 大屏页零交互控件；窗口层再兜一道，防止现场误触鼠标
|
||||
if (!single && this.display.ignoreMouse !== false) {
|
||||
// 大屏页没有可点的控件，但窗口**默认仍然吞掉鼠标**（不穿透）。
|
||||
// 这里原来是「默认 setIgnoreMouseEvents(true)」，方向恰好反了：
|
||||
// setIgnoreMouseEvents(true) 的语义不是「本窗口不吃误触」，而是「本窗口完全忽略鼠标」，
|
||||
// 点击会落到它后面的窗口或桌面上——现场想防的误触反而变成了误点别的东西；
|
||||
// 而且被忽略鼠标的窗口点不活、被盖住后也抢不回前台。
|
||||
// 只有确实要穿透（把大屏当纯展示层、同一块屏上还要操作别的窗口）才显式配
|
||||
// display.allowClickThrough: true，代价见 README。
|
||||
// 旧键 display.ignoreMouse 在这里**完全不读**：老机器的配置文件里还被旧版模板写着
|
||||
// ignoreMouse: true，读它就等于老机器升级后继续穿透（详见 config.js 的 DEFAULTS 注释）；
|
||||
// 旧键的存在与否由 config.js 在启动时提示一次，这里不掺和。
|
||||
if (!single && this.display.allowClickThrough === true) {
|
||||
win.setIgnoreMouseEvents(true)
|
||||
}
|
||||
|
||||
@@ -233,15 +249,46 @@ class DisplayManager {
|
||||
}
|
||||
}
|
||||
|
||||
// 把窗口摆到目标屏、并把窗口态调到目标模式。**这里的调用顺序是「大屏能不能压住任务栏」
|
||||
// 的全部理由**，动它之前先读下面 kiosk 分支的注释。
|
||||
applyGeometry(win, display, single) {
|
||||
if (!win || win.isDestroyed()) return
|
||||
if (single) {
|
||||
const bounds = this.geometryFor(display, single)
|
||||
const wantKiosk = !single && this.display.kiosk !== false
|
||||
|
||||
if (!wantKiosk) {
|
||||
// 窗口化（单屏调试态）与「多屏但 display.kiosk=false」：一律不置顶。
|
||||
// 单屏窗口化的 F11 全屏由用户自己控制，置顶会把它变成一块收不掉、盖住一切的覆盖层；
|
||||
// 从 kiosk 退回来的窗口也必须在这里把置顶摘掉，否则会带着 WS_EX_TOPMOST 留在窗口化态
|
||||
if (win.isKiosk()) win.setKiosk(false)
|
||||
if (win.isFullScreen()) win.setFullScreen(false)
|
||||
} else if (this.display.kiosk !== false) {
|
||||
win.setKiosk(true)
|
||||
win.setBounds(bounds)
|
||||
win.setAlwaysOnTop(false)
|
||||
return
|
||||
}
|
||||
win.setBounds(this.geometryFor(display, single))
|
||||
|
||||
// layout() 会因为插拔屏幕/改分辨率/改缩放在运行期反复调用；已经是对的状态就直接返回，
|
||||
// 否则每次重排都要退出再进入一次 kiosk，现场大屏会白闪一下
|
||||
if (win.isKiosk() && win.isAlwaysOnTop() && sameBounds(win.getBounds(), bounds)) return
|
||||
|
||||
// 顺序不能反，三条各自都是一次现场事故：
|
||||
// ① 已经在 kiosk 里就先退出。Windows 上对全屏窗口调 setBounds 会把它从真正的全屏态
|
||||
// 拽回「恰好铺满该屏的无边框窗口」；此时再 setKiosk(true)，Electron 侧会因为内部
|
||||
// 仍认为是 kiosk 而直接返回、什么都不做，窗口就永远停在那个假全屏态——它不是
|
||||
// topmost，任务栏（topmost）和任何拖到这块屏上的窗口都能画在它上面；
|
||||
// ② 先 setBounds 定位，后 setKiosk(true) 进全屏。这样窗口进 kiosk 时已经在正确的屏上，
|
||||
// 真正处于全屏态的窗口既压住任务栏，也不会被拖过来的窗口盖住；
|
||||
// ③ 置顶放最后，之后不许再有任何改动窗口几何/窗口态的调用，否则 topmost 可能又丢。
|
||||
if (win.isKiosk()) win.setKiosk(false)
|
||||
if (win.isFullScreen()) win.setFullScreen(false)
|
||||
win.setBounds(bounds)
|
||||
win.setKiosk(true)
|
||||
// 层级必须给 'screen-saver'：Windows 上只有 pop-up-menu 及以上才画在任务栏之上，
|
||||
// setAlwaysOnTop(true) 的默认层级 'floating' 仍然在任务栏下面。置顶之后别的窗口
|
||||
// 拖到这块屏上也盖不住它，点一下就能回到最前——大屏没有键盘，这是唯一的抢回前台手段。
|
||||
// 这里不需要再监听 blur 或起定时器补偿：topmost 是 z 序属性、与焦点无关，
|
||||
// 定时重设只会白白抢焦点，属于无因之果
|
||||
win.setAlwaysOnTop(true, 'screen-saver')
|
||||
}
|
||||
|
||||
loadPage(entry, display, page, single) {
|
||||
@@ -357,7 +404,7 @@ class DisplayManager {
|
||||
return { created: true, mode: this.modeOf(entry) }
|
||||
}
|
||||
|
||||
// 关掉某块屏上的大屏窗口：kiosk 窗口刻意忽略鼠标，误开后只能从这里收
|
||||
// 关掉某块屏上的大屏窗口：窗口默认置顶且压住任务栏，误开/要收场时只能从这里收
|
||||
closeDisplay(displayId) {
|
||||
const entry = this.windows.get(displayId)
|
||||
if (!entry) return false
|
||||
|
||||
@@ -47,6 +47,13 @@ class FakeBrowserWindow extends EventEmitter {
|
||||
this.destroyed = false
|
||||
this.kiosk = options.kiosk === true
|
||||
this.fullScreen = false
|
||||
// Electron 里 setIgnoreMouseEvents / setAlwaysOnTop 的默认态：不穿透、不置顶
|
||||
this.ignoreMouse = false
|
||||
this.alwaysOnTop = false
|
||||
this.alwaysOnTopLevel = null
|
||||
// 调用流水。坐标与窗口态的**先后顺序**本身就是被测行为（见 assertKioskOrder）：
|
||||
// 只看最终状态会漏掉「先进 kiosk 再 setBounds」这种被改回去的回归
|
||||
this.calls = []
|
||||
// 模拟真实 Electron 在切换瞬间回读到的旧值：设了它 isFullScreen() 就返回这个
|
||||
this.staleFullScreen = undefined
|
||||
this.bounds = { x: options.x, y: options.y, width: options.width, height: options.height }
|
||||
@@ -74,14 +81,19 @@ class FakeBrowserWindow extends EventEmitter {
|
||||
|
||||
setFullScreen(value) {
|
||||
this.fullScreen = value
|
||||
this.calls.push(['setFullScreen', value])
|
||||
}
|
||||
|
||||
isKiosk() {
|
||||
return this.kiosk
|
||||
}
|
||||
|
||||
// 真实 Electron 里 kiosk 就是窗口级全屏，两者同进同退，桩也照这个来，
|
||||
// 否则「kiosk 窗口其实是全屏」这层关系测不出来
|
||||
setKiosk(value) {
|
||||
this.kiosk = value
|
||||
this.fullScreen = value
|
||||
this.calls.push(['setKiosk', value])
|
||||
}
|
||||
|
||||
getBounds() {
|
||||
@@ -90,10 +102,22 @@ class FakeBrowserWindow extends EventEmitter {
|
||||
|
||||
setBounds(bounds) {
|
||||
this.bounds = bounds
|
||||
this.calls.push(['setBounds', { ...bounds }])
|
||||
}
|
||||
|
||||
isAlwaysOnTop() {
|
||||
return this.alwaysOnTop
|
||||
}
|
||||
|
||||
setAlwaysOnTop(value, level) {
|
||||
this.alwaysOnTop = value
|
||||
this.alwaysOnTopLevel = value ? level || 'floating' : null
|
||||
this.calls.push(['setAlwaysOnTop', value, level])
|
||||
}
|
||||
|
||||
setIgnoreMouseEvents(value) {
|
||||
this.ignoreMouse = value
|
||||
this.calls.push(['setIgnoreMouseEvents', value])
|
||||
}
|
||||
|
||||
show() {
|
||||
@@ -137,6 +161,12 @@ Module._load = function (request, parent, isMain) {
|
||||
}
|
||||
const { DisplayManager } = require('./displays')
|
||||
Module._load = originalLoad
|
||||
// 随包发布的内置默认值：用例要验「多屏 kiosk 默认不穿透」，就得拿**真的默认值**去跑，
|
||||
// 在测试里自己写死一份 false 是验不到 DEFAULTS/config.json 被改回 true 的
|
||||
const { DEFAULTS } = require('./config')
|
||||
// 随包的 config.json 模板（打包态首次启动复制到用户数据目录）是现场真正的默认值，
|
||||
// 只改代码里的 DEFAULTS 而漏了它，现场升级后仍然是穿透
|
||||
const shippedConfig = require('../config.json')
|
||||
|
||||
const WIDTH = 1920
|
||||
const HEIGHT = 1080
|
||||
@@ -145,7 +175,15 @@ function fakeDisplay(id, { internal = false } = {}) {
|
||||
return { id, label: `显示器 ${id}`, internal, bounds: { x: 0, y: 0, width: WIDTH, height: HEIGHT }, scaleFactor: 1 }
|
||||
}
|
||||
|
||||
function makeManager(t, { selection = 'all', kiosk = true } = {}) {
|
||||
// allowClickThrough 默认直接取 config.js 里的内置默认值（false = 不穿透），
|
||||
// 这样「默认值被改回 true」这件事本身会被用例抓住；要穿透的用例显式传 { allowClickThrough: true }。
|
||||
// legacy 用来注入旧机器配置文件里留下的老键（如 ignoreMouse: true），验「老键已失效」
|
||||
function makeManager(t, {
|
||||
selection = 'all',
|
||||
kiosk = true,
|
||||
allowClickThrough = DEFAULTS.display.allowClickThrough,
|
||||
legacy = {}
|
||||
} = {}) {
|
||||
fakeScreen.displays = []
|
||||
fakeScreen.primaryId = 1
|
||||
// 上一个用例若忘了收摊，残留的监听会串到这一个用例里
|
||||
@@ -160,9 +198,10 @@ function makeManager(t, { selection = 'all', kiosk = true } = {}) {
|
||||
pages: ['standings', 'medals'],
|
||||
pageParam: 'page',
|
||||
kiosk,
|
||||
ignoreMouse: true,
|
||||
allowClickThrough,
|
||||
reloadEveryHours: 0,
|
||||
backgroundColor: '#000000'
|
||||
backgroundColor: '#000000',
|
||||
...legacy
|
||||
}
|
||||
},
|
||||
server: { host: '0.0.0.0', port: 19540 },
|
||||
@@ -343,6 +382,181 @@ test('kiosk 窗口不挂 F11 处理', (t) => {
|
||||
assert.equal(manager.windows.get(2).win.webContents.listeners('before-input-event').length, 0)
|
||||
})
|
||||
|
||||
// —— 窗口层行为：能不能点穿、压不压得住任务栏 ——
|
||||
// 现场回归：① 大屏窗口默认 setIgnoreMouseEvents(true)，点击穿透到后面的窗口/桌面，
|
||||
// 「防误触」变成了「误点别的东西」，被穿透的窗口还点不活；
|
||||
// ② kiosk 窗口先 setKiosk(true) 再 setBounds，被 Windows 从真正的全屏态拽回
|
||||
// 「恰好铺满该屏的无边框窗口」，不是 topmost，任务栏与拖过来的窗口都能盖住它。
|
||||
// ①的开关键从 ignoreMouse 改名成了 allowClickThrough：旧键在老机器的用户配置里被写死着，
|
||||
// 只改默认值救不了它们，用例里的「老机器」就是带 ignoreMouse: true 进来的那份配置。
|
||||
|
||||
// 窗口调用流水里「最后一次」满足条件的调用下标；找不到返回 -1
|
||||
function lastCallIndex(win, name, match = () => true) {
|
||||
return win.calls.reduce((found, [called, ...args], index) => (
|
||||
called === name && match(...args) ? index : found
|
||||
), -1)
|
||||
}
|
||||
|
||||
// kiosk 窗口必须：先 setBounds 定位 → 再 setKiosk(true) → 最后置顶到 screen-saver。
|
||||
// 顺序反了就是上面 ② 那个事故；这里断言的是顺序而不是最终状态，正为此。
|
||||
function assertKioskOrder(win) {
|
||||
const boundsAt = lastCallIndex(win, 'setBounds')
|
||||
const kioskAt = lastCallIndex(win, 'setKiosk', (value) => value === true)
|
||||
assert.notEqual(kioskAt, -1, 'kiosk 窗口必须真的进过 kiosk')
|
||||
assert.ok(
|
||||
boundsAt !== -1 && boundsAt < kioskAt,
|
||||
`setBounds(#${boundsAt}) 必须在 setKiosk(true)(#${kioskAt}) 之前，实际调用流水：${JSON.stringify(win.calls)}`
|
||||
)
|
||||
|
||||
const topAt = lastCallIndex(win, 'setAlwaysOnTop', (value) => value === true)
|
||||
assert.ok(topAt > kioskAt, `进 kiosk 之后必须置顶，实际调用流水：${JSON.stringify(win.calls)}`)
|
||||
assert.equal(win.alwaysOnTopLevel, 'screen-saver', 'Windows 上只有 pop-up-menu 及以上才画在任务栏之上')
|
||||
}
|
||||
|
||||
test('新键缺省 = 不穿透：多屏 kiosk 不调 setIgnoreMouseEvents(true)', (t) => {
|
||||
// 先把「默认值本身」钉住：这份默认值改成 true，就等于把点击穿透又放回现场
|
||||
assert.equal(DEFAULTS.display.allowClickThrough, false, '内置默认值必须是「不穿透」')
|
||||
assert.equal(shippedConfig.display.allowClickThrough, false, '随包的 config.json 模板也必须是「不穿透」')
|
||||
assert.equal('ignoreMouse' in DEFAULTS.display, false, '旧键必须从 DEFAULTS 里消失，否则等于还在读它')
|
||||
|
||||
const manager = makeManager(t)
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true }), fakeDisplay(2)]
|
||||
|
||||
manager.enable()
|
||||
|
||||
for (const id of [1, 2]) {
|
||||
const win = manager.windows.get(id).win
|
||||
assert.equal(win.ignoreMouse, false, `display=${id} 默认必须吞掉鼠标：穿透会把点击送给后面的窗口/桌面`)
|
||||
assert.equal(lastCallIndex(win, 'setIgnoreMouseEvents', (value) => value === true), -1)
|
||||
}
|
||||
})
|
||||
|
||||
test('只有显式配 display.allowClickThrough=true 才穿透', (t) => {
|
||||
const manager = makeManager(t, { allowClickThrough: true })
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true }), fakeDisplay(2)]
|
||||
|
||||
manager.enable()
|
||||
|
||||
assert.deepEqual(
|
||||
manager.windows.get(2).win.calls.filter(([name]) => name === 'setIgnoreMouseEvents'),
|
||||
[['setIgnoreMouseEvents', true]]
|
||||
)
|
||||
})
|
||||
|
||||
test('回归钉子：老机器配置里留着 ignoreMouse: true 也不穿透（旧键已失效）', (t) => {
|
||||
// 这就是本次修复的核心：旧版模板把 ignoreMouse: true 写进了现场机器的用户配置，
|
||||
// 而 userpaths.js 不会覆盖用户文件——只要还读旧键，那台机器升级后照样穿透
|
||||
const manager = makeManager(t, { legacy: { ignoreMouse: true } })
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true }), fakeDisplay(2)]
|
||||
|
||||
manager.enable()
|
||||
|
||||
for (const id of [1, 2]) {
|
||||
const win = manager.windows.get(id).win
|
||||
assert.equal(win.ignoreMouse, false, `display=${id}：旧键 ignoreMouse 已废弃，不能让它把穿透带回来`)
|
||||
assert.equal(lastCallIndex(win, 'setIgnoreMouseEvents', (value) => value === true), -1)
|
||||
}
|
||||
|
||||
// 用例本身要确保旧键真的塞进了配置里，否则这条测试等于没测
|
||||
assert.equal('ignoreMouse' in manager.display, true)
|
||||
assert.equal(manager.display.allowClickThrough, false, '新键没被显式写成 true')
|
||||
})
|
||||
|
||||
test('单屏窗口化不受穿透开关影响：配了穿透也不穿透、也不置顶', (t) => {
|
||||
const manager = makeManager(t, { allowClickThrough: true })
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true })]
|
||||
|
||||
manager.enable()
|
||||
|
||||
const win = manager.windows.get(1).win
|
||||
assert.equal(win.ignoreMouse, false, '穿透这一行从来只管多屏 kiosk')
|
||||
assert.equal(lastCallIndex(win, 'setAlwaysOnTop', (value) => value === true), -1, '窗口化的 F11 全屏归用户管，不能置顶')
|
||||
assert.equal(win.isKiosk(), false)
|
||||
})
|
||||
|
||||
test('kiosk 窗口：先 setBounds 再 setKiosk(true)，最后置顶 screen-saver', (t) => {
|
||||
const manager = makeManager(t)
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true }), fakeDisplay(2)]
|
||||
|
||||
manager.enable()
|
||||
|
||||
for (const id of [1, 2]) {
|
||||
const win = manager.windows.get(id).win
|
||||
assertKioskOrder(win)
|
||||
assert.equal(win.isKiosk(), true)
|
||||
assert.equal(win.alwaysOnTop, true, '被别的窗口盖住后要能点回最前')
|
||||
}
|
||||
})
|
||||
|
||||
test('面板手动开的 kiosk 窗口同样置顶、不穿透', (t) => {
|
||||
const manager = makeManager(t)
|
||||
const primary = fakeDisplay(1, { internal: true })
|
||||
const external = fakeDisplay(2)
|
||||
fakeScreen.displays = [primary, external]
|
||||
|
||||
assert.deepEqual(manager.openOn(external, { page: 'medals', single: false }), { created: true, mode: 'kiosk' })
|
||||
|
||||
const win = manager.windows.get(2).win
|
||||
assertKioskOrder(win)
|
||||
assert.equal(win.ignoreMouse, false)
|
||||
})
|
||||
|
||||
test('kiosk 已是目标态时不重复进出 kiosk（重排不该让大屏白闪）', (t) => {
|
||||
const manager = makeManager(t)
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true }), fakeDisplay(2)]
|
||||
manager.enable()
|
||||
|
||||
const win = manager.windows.get(2).win
|
||||
const callsBefore = JSON.stringify(win.calls)
|
||||
|
||||
// 一次「屏幕没变」的重排：窗口态已经是目标态，就一个窗口调用都不该发生
|
||||
manager.layout()
|
||||
|
||||
assert.equal(JSON.stringify(win.calls), callsBefore)
|
||||
assertKioskOrder(win)
|
||||
})
|
||||
|
||||
test('插拔屏幕就地换模式：置顶跟着 kiosk 来回，顺序不变', (t) => {
|
||||
const manager = makeManager(t)
|
||||
const primary = fakeDisplay(1, { internal: true })
|
||||
fakeScreen.displays = [primary]
|
||||
manager.enable()
|
||||
|
||||
const win = manager.windows.get(1).win
|
||||
assert.equal(win.alwaysOnTop, false, '单屏窗口化不置顶')
|
||||
|
||||
// 插上电视：同一块屏上的窗口就地转 kiosk，必须补上置顶
|
||||
fakeScreen.displays = [primary, fakeDisplay(2)]
|
||||
manager.layout()
|
||||
assertModeConsistent(manager, 1, false)
|
||||
assertKioskOrder(win)
|
||||
|
||||
// 电视拔了：转回窗口化，置顶必须摘掉，否则窗口化态会继续盖住一切
|
||||
fakeScreen.displays = [primary]
|
||||
manager.layout()
|
||||
assertModeConsistent(manager, 1, true)
|
||||
assert.equal(win.alwaysOnTop, false)
|
||||
assert.equal(win.alwaysOnTopLevel, null)
|
||||
})
|
||||
|
||||
test('收窗路径不被置顶破坏：closeDisplay / closeAll 仍收得掉 kiosk 窗口', (t) => {
|
||||
const manager = makeManager(t)
|
||||
fakeScreen.displays = [fakeDisplay(1, { internal: true }), fakeDisplay(2)]
|
||||
manager.enable()
|
||||
|
||||
const external = manager.windows.get(2).win
|
||||
const primary = manager.windows.get(1).win
|
||||
assert.equal(manager.closeDisplay(2), true)
|
||||
assert.equal(external.isDestroyed(), true)
|
||||
assert.equal(manager.windows.has(2), false)
|
||||
assert.equal(manager.closeDisplay(2), false, '已经收掉的窗口不能再报成功')
|
||||
|
||||
manager.closeAll()
|
||||
assert.equal(primary.isDestroyed(), true)
|
||||
assert.equal(manager.windows.size, 0)
|
||||
assert.equal(manager.enabled, false)
|
||||
})
|
||||
|
||||
// 屏幕监听的三条不变式，对应审查日志模块13 [1] P1：
|
||||
// ① 任何一次「屏幕数量变化」都不能把监听永久摘掉（只有 closeAll 摘）
|
||||
// ② 事件到达后 600ms 防抖重排，从 1 块恢复 2 块要自动回到 kiosk，从 2 块变 1 块要收回窗口化
|
||||
|
||||
@@ -609,6 +609,10 @@ function main() {
|
||||
log.push('console', `用户数据目录：${userPaths.root}（Console 配置、服务端 config.yaml、rules 都在这里，覆盖安装不会丢）`)
|
||||
}
|
||||
if (cfg.warning) log.push('console', cfg.warning)
|
||||
// 配置里还留着改名前的旧键（如 display.ignoreMouse）：只在启动这里提示一次。
|
||||
// 判断与文案都在 config.js 的 loadConfig 里算好，这里只负责落日志——
|
||||
// 大屏重排路径（displays.js）绝不碰这件事，否则每次插拔屏幕都要刷一行
|
||||
for (const notice of cfg.notices) log.push('console', `警告：${notice}`)
|
||||
|
||||
const resolved = resolveExecutable(cfg.values.server.exe, cfg.path, bundleDir)
|
||||
exePath = resolved.path
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "scoreboard-console",
|
||||
"productName": "Scoreboard Console",
|
||||
"version": "0.3.0",
|
||||
"version": "0.4.0",
|
||||
"private": true,
|
||||
"author": "AskaEth",
|
||||
"description": "赛事积分榜 · 桌面宿主：守护 Go 服务端并把大屏投到扩展屏",
|
||||
|
||||
+11
-2
@@ -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 轮播与锁定
|
||||
|
||||
|
||||
+57
-1
@@ -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
|
||||
|
||||
### 一句话
|
||||
|
||||
|
||||
+1
-1
@@ -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 秒一页；公告页不参与轮播。
|
||||
|
||||
+7
-2
@@ -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、防熄屏、选屏控制，字体与动画表现以实际设备为准；
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"net"
|
||||
"net/http"
|
||||
"sort"
|
||||
)
|
||||
|
||||
// 大屏控制页要把「当前设备的局域网地址」显示成可点链接 + 二维码：面板自己往往是从
|
||||
// 127.0.0.1 打开的，浏览器里的 location.host 对平板毫无用处，所以地址只能由服务端枚举网卡得到。
|
||||
//
|
||||
// 路径也随响应一起下发：/ → index.html、/display → display.html、/admin → admin.html 的映射
|
||||
// 写在 server.go 的 staticHandler 里。前端各自硬编码一份，改前端产物名时就会有两处要跟着动。
|
||||
const (
|
||||
displayPagePath = "/display"
|
||||
adminPagePath = "/admin"
|
||||
)
|
||||
|
||||
// lanAddress 是一个「局域网里其他设备能连上这台机器」的候选地址。
|
||||
//
|
||||
// family 目前恒为 ipv4：IPv6 要写成 http://[fe80::1%eth0]:port/display，方括号与 %zone
|
||||
// 粘到平板浏览器里出错率高，而现场本来就是 IPv4 内网。留着这个字段是为了以后真要补 IPv6 时
|
||||
// 前端不必改结构（见 06/07 文档里的前端约定）。
|
||||
type lanAddress struct {
|
||||
IP string `json:"ip"`
|
||||
Interface string `json:"interface"`
|
||||
Family string `json:"family"`
|
||||
}
|
||||
|
||||
// networkInfo 是 GET /api/system/network 的响应体。
|
||||
type networkInfo struct {
|
||||
Port int `json:"port"`
|
||||
DisplayPath string `json:"displayPath"`
|
||||
AdminPath string `json:"adminPath"`
|
||||
Addresses []lanAddress `json:"addresses"`
|
||||
}
|
||||
|
||||
// ifaceSnapshot 是 net.Interface 里本接口用得上的那部分。
|
||||
//
|
||||
// 单独抽出来是为了让筛选与排序成为纯函数：net.Interface 的 Addrs() 直接问操作系统，
|
||||
// 拿真网卡根本造不出「网线 + WiFi 双网卡」「两张网卡配同一个地址」这类现场，
|
||||
// 而这正是最需要钉住的行为。测试构造快照即可，真网卡一行都不用碰。
|
||||
type ifaceSnapshot struct {
|
||||
Name string
|
||||
Flags net.Flags
|
||||
Addrs []net.Addr
|
||||
}
|
||||
|
||||
// snapshotInterfaces 读一次本机网卡。读不到（极罕见）时返回空切片：
|
||||
// 前端据此显示「未检测到局域网地址」，比报错更接近事实——服务本身是好的。
|
||||
func (s *server) snapshotInterfaces() []ifaceSnapshot {
|
||||
list, err := net.Interfaces()
|
||||
if err != nil {
|
||||
s.logger.Warn("枚举网卡失败，大屏控制页将显示「未检测到局域网地址」", "err", err)
|
||||
return nil
|
||||
}
|
||||
out := make([]ifaceSnapshot, 0, len(list))
|
||||
for _, iface := range list {
|
||||
addrs, err := iface.Addrs()
|
||||
if err != nil {
|
||||
// 单张网卡读不到地址不影响别的网卡：现场常见的是一张 down 掉的虚拟网卡报错。
|
||||
continue
|
||||
}
|
||||
out = append(out, ifaceSnapshot{Name: iface.Name, Flags: iface.Flags, Addrs: addrs})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// lanAddresses 从网卡快照里挑出可用的局域网 IPv4 地址，按「现场最可能用的那个」排在最前。
|
||||
// 结果永远非 nil：没有任何可用地址时返回空切片，前端才知道这是「没有」而不是「没拿到字段」。
|
||||
func lanAddresses(ifaces []ifaceSnapshot) []lanAddress {
|
||||
// 候选先带上 4 字节形式：去重、排序用得到，且避免在比较器里反复做 To4。
|
||||
type candidate struct {
|
||||
entry lanAddress
|
||||
ip4 net.IP
|
||||
}
|
||||
seen := make(map[string]struct{})
|
||||
cands := make([]candidate, 0, len(ifaces))
|
||||
for _, iface := range ifaces {
|
||||
if !usableInterface(iface.Flags) {
|
||||
continue
|
||||
}
|
||||
for _, raw := range iface.Addrs {
|
||||
ip4 := addrIP(raw).To4()
|
||||
if ip4 == nil || !usableLanIPv4(ip4) {
|
||||
continue
|
||||
}
|
||||
key := ip4.String()
|
||||
// 同一地址配在多个接口上（桥接、双网卡同网段）时只留先出现的一条：
|
||||
// 列表里两条一模一样的链接，现场会以为是两个不同的东西。
|
||||
if _, dup := seen[key]; dup {
|
||||
continue
|
||||
}
|
||||
seen[key] = struct{}{}
|
||||
cands = append(cands, candidate{
|
||||
entry: lanAddress{IP: key, Interface: iface.Name, Family: "ipv4"},
|
||||
ip4: ip4,
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
sort.Slice(cands, func(i, j int) bool {
|
||||
a, b := cands[i], cands[j]
|
||||
if ra, rb := lanRank(a.ip4), lanRank(b.ip4); ra != rb {
|
||||
return ra < rb
|
||||
}
|
||||
// 同档按地址数值排序：同一台机器每次刷新都要给出同样的顺序，
|
||||
// 否则列表第一个地址会跳来跳去，现场刚记住的链接下次就变了。
|
||||
if c := bytes.Compare(a.ip4, b.ip4); c != 0 {
|
||||
return c < 0
|
||||
}
|
||||
return a.entry.Interface < b.entry.Interface
|
||||
})
|
||||
|
||||
out := make([]lanAddress, 0, len(cands))
|
||||
for _, c := range cands {
|
||||
out = append(out, c.entry)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// usableInterface 判断一张网卡能不能贡献地址：
|
||||
// - 必须 UP —— 网线没插、接口被 down 掉时，配置还在但包根本发不出去；
|
||||
// - 排除回环接口 —— lo 上的 127.x 对别的设备毫无意义（面板自己就是从 127.0.0.1 打开的，
|
||||
// 真把它显示出来会误导现场照抄一个只有本机能打开的地址）。
|
||||
func usableInterface(flags net.Flags) bool {
|
||||
return flags&net.FlagUp != 0 && flags&net.FlagLoopback == 0
|
||||
}
|
||||
|
||||
// usableLanIPv4 判断一个 IPv4 地址能不能给局域网其他设备用。
|
||||
// 逐条排除的都是「拿得到、连不上」的地址：
|
||||
// - 127.0.0.0/8 回环：只有本机能访问；
|
||||
// - 169.254.0.0/16 link-local：DHCP 没拿到地址时系统自配的，同网段设备通常也到不了；
|
||||
// - 0.0.0.0：未指定地址，拼不成 URL；
|
||||
// - 224.0.0.0/4 组播：不是单播目的地址。
|
||||
func usableLanIPv4(ip4 net.IP) bool {
|
||||
switch {
|
||||
case ip4.IsLoopback(), ip4.IsUnspecified(), ip4.IsLinkLocalUnicast(), ip4.IsMulticast():
|
||||
return false
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// lanRank 是排序档位（越小越靠前）：现场「网线 + WiFi 双网卡」时，排第一的应该是他们真正在用的那个。
|
||||
//
|
||||
// 分档依据是各私有段在实际现场的常见程度：
|
||||
// - 0：192.168.0.0/16 —— 家用与小型办公路由器的出厂段，现场路由器 / 无线热点几乎都在这里；
|
||||
// - 1：10.0.0.0/8 —— 稍大的内网、企业路由器与手机热点（部分机型）常用的段；
|
||||
// - 2：172.16.0.0/12 —— RFC1918 三段里最少见的，多是虚拟化 / 容器网桥（docker 默认就用它），
|
||||
// 真要拿它给平板用也得排在直连网段之后；
|
||||
// - 3：其余（公网地址、运营商专线地址等）—— 能用就留着，但不给第一顺位：
|
||||
// 现场多半是靠某个中间设备才通的，未必是平板能直连的那个。
|
||||
func lanRank(ip4 net.IP) int {
|
||||
switch {
|
||||
case ip4[0] == 192 && ip4[1] == 168:
|
||||
return 0
|
||||
case ip4[0] == 10:
|
||||
return 1
|
||||
case ip4[0] == 172 && ip4[1] >= 16 && ip4[1] <= 31:
|
||||
return 2
|
||||
default:
|
||||
return 3
|
||||
}
|
||||
}
|
||||
|
||||
// addrIP 从 net.Addr 里取出 IP。网卡地址实际都是 *net.IPNet，*net.IPAddr 只是兜底。
|
||||
func addrIP(addr net.Addr) net.IP {
|
||||
switch a := addr.(type) {
|
||||
case *net.IPNet:
|
||||
return a.IP
|
||||
case *net.IPAddr:
|
||||
return a.IP
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// systemNetwork 是 GET /api/system/network：大屏控制页用它拼出平板能直接打开的链接。
|
||||
// 端口取服务端实际监听的那个（见 server.port），不在这里另写一个数字。
|
||||
func (s *server) systemNetwork(w http.ResponseWriter, r *http.Request) (any, error) {
|
||||
return networkInfo{
|
||||
Port: s.port,
|
||||
DisplayPath: displayPagePath,
|
||||
AdminPath: adminPagePath,
|
||||
Addresses: lanAddresses(s.snapshotInterfaces()),
|
||||
}, nil
|
||||
}
|
||||
@@ -0,0 +1,145 @@
|
||||
package httpapi
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net"
|
||||
"reflect"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// lanIf 造一张网卡快照：测试里要的是「现场双网卡」这类布局，不能去动真网卡。
|
||||
func lanIf(name string, flags net.Flags, cidrs ...string) ifaceSnapshot {
|
||||
addrs := make([]net.Addr, 0, len(cidrs))
|
||||
for _, cidr := range cidrs {
|
||||
ip, ipnet, err := net.ParseCIDR(cidr)
|
||||
if err != nil {
|
||||
panic("测试地址非法: " + cidr)
|
||||
}
|
||||
addrs = append(addrs, &net.IPNet{IP: ip, Mask: ipnet.Mask})
|
||||
}
|
||||
return ifaceSnapshot{Name: name, Flags: flags, Addrs: addrs}
|
||||
}
|
||||
|
||||
func lanIPs(got []lanAddress) []string {
|
||||
out := make([]string, 0, len(got))
|
||||
for _, a := range got {
|
||||
out = append(out, a.IP)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// 只回「平板真的连得上」的 IPv4：回环、link-local、未指定、组播、IPv6、down 掉的接口全要滤掉。
|
||||
// 这条用例钉住的是现场最容易踩的坑——面板从 127.0.0.1 打开，顺手把回环地址显示出去，
|
||||
// 现场照着抄到平板上就是打不开。
|
||||
func TestLanAddressesFiltersUnusable(t *testing.T) {
|
||||
ifaces := []ifaceSnapshot{
|
||||
lanIf("lo", net.FlagUp|net.FlagLoopback, "127.0.0.1/8", "::1/128"),
|
||||
// 网线插着但 DHCP 没拿到地址：系统自配 169.254.x，同网段设备通常也到不了。
|
||||
lanIf("eth0", net.FlagUp, "169.254.10.5/16", "fe80::a00:27ff:fe4e:66a1/64"),
|
||||
// 接口 down 掉：配置还在，包发不出去。
|
||||
lanIf("eth1", 0, "192.168.5.5/24"),
|
||||
// 非回环接口上被误配了回环地址（别名地址写错段）：按地址本身也得滤掉，
|
||||
// 光看接口标志漏得掉这一条。
|
||||
lanIf("eth2", net.FlagUp, "127.0.0.5/8"),
|
||||
lanIf("docker0", net.FlagUp, "0.0.0.0/32", "224.0.0.1/4", "172.20.0.1/16"),
|
||||
// 双栈内网里网卡还会带全局 IPv6：拼 URL 要写方括号且常带 %zone，平板粘过去容易出错，
|
||||
// 所以一律不往下发（family 字段留着，将来真要用才补）。
|
||||
lanIf("wlan0", net.FlagUp, "2400:3200::1/64", "10.1.2.3/8"),
|
||||
}
|
||||
|
||||
want := []string{"10.1.2.3", "172.20.0.1"}
|
||||
got := lanAddresses(ifaces)
|
||||
if !reflect.DeepEqual(lanIPs(got), want) {
|
||||
t.Fatalf("可用地址应为 %v，得到 %v", want, lanIPs(got))
|
||||
}
|
||||
// family 是给前端拼 URL 用的：目前只回 IPv4，字段也必须存在。
|
||||
for _, a := range got {
|
||||
if a.Family != "ipv4" {
|
||||
t.Fatalf("family 应为 ipv4，得到 %q（%s）", a.Family, a.IP)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 一个地址都挑不出来时必须回空切片而不是 nil：JSON 里要是 null，前端分不清
|
||||
// 「没有局域网地址」和「服务端没给这个字段」。
|
||||
func TestLanAddressesEmptyResultIsNonNil(t *testing.T) {
|
||||
cases := map[string][]ifaceSnapshot{
|
||||
"没有网卡": nil,
|
||||
"只有回环": {lanIf("lo", net.FlagUp|net.FlagLoopback, "127.0.0.1/8")},
|
||||
"只有 IPv6": {lanIf("eth0", net.FlagUp, "fe80::1/64")},
|
||||
"接口全 down": {lanIf("eth0", 0, "192.168.1.23/24")},
|
||||
}
|
||||
for name, ifaces := range cases {
|
||||
got := lanAddresses(ifaces)
|
||||
if got == nil {
|
||||
t.Fatalf("%s：应回空切片而不是 nil", name)
|
||||
}
|
||||
if len(got) != 0 {
|
||||
t.Fatalf("%s：不该有地址，得到 %v", name, lanIPs(got))
|
||||
}
|
||||
raw, err := json.Marshal(networkInfo{Port: 1, Addresses: got})
|
||||
if err != nil {
|
||||
t.Fatalf("%s：序列化失败 %v", name, err)
|
||||
}
|
||||
if !strings.Contains(string(raw), `"addresses":[]`) {
|
||||
t.Fatalf("%s：addresses 应序列化为 []，得到 %s", name, raw)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 同一地址配在多张网卡上（桥接、双网卡同网段）时只留一条，且保留先出现的那张网卡名；
|
||||
// 顺序按「像不像常见内网段」分档，同档再按地址数值升序——否则列表每次刷新都在跳，
|
||||
// 现场刚记住的链接下次就不是第一条了。
|
||||
func TestLanAddressesDedupAndOrder(t *testing.T) {
|
||||
ifaces := []ifaceSnapshot{
|
||||
// 常见的「网线 eth0 + WiFi wlan0」现场：WiFi 落在路由器出厂段 192.168.x。
|
||||
lanIf("eth0", net.FlagUp, "172.20.1.5/16", "192.168.1.23/24", "8.8.8.8/32"),
|
||||
lanIf("wlan0", net.FlagUp, "192.168.1.9/24", "10.0.0.4/8", "192.168.1.100/24"),
|
||||
lanIf("br0", net.FlagUp, "192.168.1.23/24"),
|
||||
}
|
||||
|
||||
want := []string{"192.168.1.9", "192.168.1.23", "192.168.1.100", "10.0.0.4", "172.20.1.5", "8.8.8.8"}
|
||||
got := lanAddresses(ifaces)
|
||||
if !reflect.DeepEqual(lanIPs(got), want) {
|
||||
t.Fatalf("地址顺序应为 %v，得到 %v", want, lanIPs(got))
|
||||
}
|
||||
// 192.168.1.23 先出现在 eth0 上，br0 上的同一地址要被丢掉、也不能改写 interface。
|
||||
if got[1].Interface != "eth0" {
|
||||
t.Fatalf("去重后应保留先出现的接口名 eth0，得到 %q", got[1].Interface)
|
||||
}
|
||||
}
|
||||
|
||||
// 排序档位本身：192.168/16 → 10/8 → 172.16-31/12 → 其余，越靠前越是现场真在用的那条。
|
||||
func TestLanRankPrefersCommonLanSegments(t *testing.T) {
|
||||
order := []string{
|
||||
"192.168.0.1", "192.168.255.254", // 路由器出厂段
|
||||
"10.0.0.1", "10.255.255.254", // 企业内网 / 热点
|
||||
"172.16.0.1", "172.31.255.254", // 最少见，多是虚拟网桥
|
||||
"172.15.0.1", "172.32.0.1", "203.0.113.9", // 172.16/12 之外
|
||||
}
|
||||
for i := 1; i < len(order); i++ {
|
||||
prev, curr := net.ParseIP(order[i-1]).To4(), net.ParseIP(order[i]).To4()
|
||||
if lanRank(prev) > lanRank(curr) {
|
||||
t.Fatalf("%s 不该排在 %s 之后（%d > %d）", order[i-1], order[i], lanRank(prev), lanRank(curr))
|
||||
}
|
||||
}
|
||||
if lanRank(net.ParseIP("172.15.0.1").To4()) != 3 || lanRank(net.ParseIP("172.32.0.1").To4()) != 3 {
|
||||
t.Fatal("172.16/12 的两侧边界不该被当成常见内网段")
|
||||
}
|
||||
}
|
||||
|
||||
// 网卡地址实际都是 *net.IPNet，但兜底分支也要能取到 IP，否则换平台（如某些 BSD/虚拟网卡）
|
||||
// 会静默把地址全滤掉，现场表现为「明明有网却显示未检测到」。
|
||||
func TestAddrIPHandlesBothAddrTypes(t *testing.T) {
|
||||
if got := addrIP(&net.IPAddr{IP: net.ParseIP("192.168.1.23")}); got.String() != "192.168.1.23" {
|
||||
t.Fatalf("*net.IPAddr 应取到 IP，得到 %v", got)
|
||||
}
|
||||
if got := addrIP(&net.IPNet{IP: net.ParseIP("10.0.0.4"), Mask: net.CIDRMask(8, 32)}); got.String() != "10.0.0.4" {
|
||||
t.Fatalf("*net.IPNet 应取到 IP，得到 %v", got)
|
||||
}
|
||||
// 认不出的地址类型不能让整条链路 panic。
|
||||
if got := addrIP(nil); got != nil {
|
||||
t.Fatalf("未知地址类型应返回 nil，得到 %v", got)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,109 @@
|
||||
package httpapi_test
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net"
|
||||
"net/http"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/config"
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/httpapi"
|
||||
)
|
||||
|
||||
// GET /api/system/network 是给大屏控制页拼「平板能直接打开的链接」用的：
|
||||
// recorder 起可读，guest 与未登录一律 403（与 /api/system/about 同档——机器级信息不给匿名访客）。
|
||||
func TestSystemNetworkPermission(t *testing.T) {
|
||||
env := newTestEnvWith(t, func(o *httpapi.Options) { o.Port = 18080 })
|
||||
|
||||
guest, _ := env.client()
|
||||
if status, env2 := env.do(guest, http.MethodGet, "/api/system/network", nil, false); status != http.StatusForbidden ||
|
||||
env2.Error == nil || env2.Error.Code != "FORBIDDEN" {
|
||||
t.Fatalf("guest 读 network 应 403 FORBIDDEN，得到 %d %+v", status, env2.Error)
|
||||
}
|
||||
|
||||
env.createUser("recorder", "recorder-pass", "recorder")
|
||||
client, _ := env.client()
|
||||
env.login(client, "recorder", "recorder-pass")
|
||||
status, env2 := env.do(client, http.MethodGet, "/api/system/network", nil, false)
|
||||
if status != http.StatusOK || !env2.OK {
|
||||
t.Fatalf("recorder 读 network 应 200，得到 %d %+v", status, env2.Error)
|
||||
}
|
||||
}
|
||||
|
||||
// 响应形状是对前端契约：字段一个不多一个不少，port 必须是实际监听端口（测试注入 18080），
|
||||
// 路径字段则要与服务端真的托管着的页面一致——前端是照它拼链接的，写错了就是死链。
|
||||
func TestSystemNetworkShape(t *testing.T) {
|
||||
env := newTestEnvWith(t, func(o *httpapi.Options) { o.Port = 18080 })
|
||||
env.createUser("recorder", "recorder-pass", "recorder")
|
||||
client, _ := env.client()
|
||||
env.login(client, "recorder", "recorder-pass")
|
||||
|
||||
status, env2 := env.do(client, http.MethodGet, "/api/system/network", nil, false)
|
||||
if status != http.StatusOK {
|
||||
t.Fatalf("读 network 应 200，得到 %d", status)
|
||||
}
|
||||
var body map[string]any
|
||||
if err := json.Unmarshal(env2.Data, &body); err != nil {
|
||||
t.Fatalf("解析 network: %v (%s)", err, env2.Data)
|
||||
}
|
||||
assertKeys(t, "network", body, []string{"port", "displayPath", "adminPath", "addresses"})
|
||||
|
||||
if got, ok := body["port"].(float64); !ok || int(got) != 18080 {
|
||||
t.Fatalf("port 应回注入的实际监听端口 18080，得到 %#v", body["port"])
|
||||
}
|
||||
if body["displayPath"] != "/display" || body["adminPath"] != "/admin" {
|
||||
t.Fatalf("路径字段不符: displayPath=%#v adminPath=%#v", body["displayPath"], body["adminPath"])
|
||||
}
|
||||
|
||||
// 路径字段指向的页面必须真的存在：改了前端产物名就会在这里红灯，而不是等到现场打开是 404。
|
||||
for _, path := range []string{body["displayPath"].(string), body["adminPath"].(string)} {
|
||||
code, raw := env.doRaw(client, http.MethodGet, path, nil, "", false)
|
||||
if code != http.StatusOK || !strings.Contains(string(raw), "<html") {
|
||||
t.Fatalf("路径 %s 应返回页面，得到 %d %.80s", path, code, raw)
|
||||
}
|
||||
}
|
||||
|
||||
// addresses 必须是数组（没有地址时是 [] 而不是 null），每条都带 ip/interface/family 且是 IPv4。
|
||||
raw, ok := body["addresses"].([]any)
|
||||
if !ok {
|
||||
t.Fatalf("addresses 应是数组，得到 %#v", body["addresses"])
|
||||
}
|
||||
for _, item := range raw {
|
||||
entry, ok := item.(map[string]any)
|
||||
if !ok {
|
||||
t.Fatalf("地址项应是对象，得到 %#v", item)
|
||||
}
|
||||
assertKeys(t, "addresses[]", entry, []string{"ip", "interface", "family"})
|
||||
if entry["family"] != "ipv4" {
|
||||
t.Fatalf("family 应为 ipv4，得到 %#v", entry["family"])
|
||||
}
|
||||
ip := net.ParseIP(entry["ip"].(string))
|
||||
if ip == nil || ip.To4() == nil {
|
||||
t.Fatalf("ip 应是 IPv4 文本，得到 %#v", entry["ip"])
|
||||
}
|
||||
// 回环与 link-local 是「拿得到、连不上」的地址，绝不能出现在给平板用的列表里。
|
||||
if ip.IsLoopback() || ip.IsLinkLocalUnicast() {
|
||||
t.Fatalf("不该出现回环 / link-local 地址: %#v", entry)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 调用方忘了注入 Port 时也要给出一个真端口（config 的默认端口），不能是 :0 —— 那会拼出
|
||||
// 一条根本打不开的链接。默认值的唯一来源是 config 包，本用例直接对比它，防止两处漂移。
|
||||
func TestSystemNetworkPortFallsBackToConfigDefault(t *testing.T) {
|
||||
env := newTestEnv(t)
|
||||
env.createUser("recorder", "recorder-pass", "recorder")
|
||||
client, _ := env.client()
|
||||
env.login(client, "recorder", "recorder-pass")
|
||||
|
||||
_, env2 := env.do(client, http.MethodGet, "/api/system/network", nil, false)
|
||||
var body map[string]any
|
||||
if err := json.Unmarshal(env2.Data, &body); err != nil {
|
||||
t.Fatalf("解析 network: %v (%s)", err, env2.Data)
|
||||
}
|
||||
want := config.Default().Server.Port
|
||||
if got, ok := body["port"].(float64); !ok || int(got) != want {
|
||||
t.Fatalf("未注入端口时应回 config 默认端口 %d，得到 %#v", want, body["port"])
|
||||
}
|
||||
}
|
||||
@@ -14,6 +14,7 @@ import (
|
||||
"time"
|
||||
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/auth"
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/config"
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/export"
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/middleware"
|
||||
"git.yeij.top/AskaEth/Scoreboard/server/internal/webui"
|
||||
@@ -51,6 +52,10 @@ type Options struct {
|
||||
WS http.Handler
|
||||
// ProjectDir 可选，当前赛事项目目录（含 uploads/），用于赛事包导出。
|
||||
ProjectDir string
|
||||
// Port 是服务端**实际监听**的端口，由 main 从 config 传入；GET /api/system/network
|
||||
// 用它拼出「平板能直接打开的链接」。<=0（调用方没传）时按 config 的默认端口兜底，
|
||||
// 不让响应里出现 :0 —— 详见 New。
|
||||
Port int
|
||||
// WebFS 可选，默认使用内嵌前端资源。
|
||||
WebFS fs.FS
|
||||
}
|
||||
@@ -63,11 +68,13 @@ type server struct {
|
||||
auth *auth.Service
|
||||
dataDir string
|
||||
projectDir string
|
||||
backups *export.Service
|
||||
shutdown func()
|
||||
display DisplaySender
|
||||
realtime Realtime
|
||||
idem *idempotencyStore
|
||||
// port 是实际监听端口，只读地传给 GET /api/system/network（见 Options.Port）。
|
||||
port int
|
||||
backups *export.Service
|
||||
shutdown func()
|
||||
display DisplaySender
|
||||
realtime Realtime
|
||||
idem *idempotencyStore
|
||||
}
|
||||
|
||||
// New 组装并返回服务端的 HTTP 处理器。
|
||||
@@ -88,6 +95,12 @@ func New(opts Options) http.Handler {
|
||||
}
|
||||
backups = export.NewService(opts.System, opts.Event, dir, 0, logger)
|
||||
}
|
||||
// 端口取实际监听值。调用方漏传时用 config 的默认端口兜底，而不是在这里另抄一个数字：
|
||||
// 响应里出现 19540 至少是个真端口，出现 :0 会让前端拼出一条根本打不开的链接。
|
||||
port := opts.Port
|
||||
if port <= 0 {
|
||||
port = config.Default().Server.Port
|
||||
}
|
||||
|
||||
s := &server{
|
||||
logger: logger,
|
||||
@@ -97,6 +110,7 @@ func New(opts Options) http.Handler {
|
||||
auth: svc,
|
||||
dataDir: opts.DataDir,
|
||||
projectDir: opts.ProjectDir,
|
||||
port: port,
|
||||
backups: backups,
|
||||
shutdown: opts.Shutdown,
|
||||
display: opts.Display,
|
||||
@@ -202,6 +216,11 @@ func (s *server) routes(mux *http.ServeMux) {
|
||||
mux.HandleFunc("GET /api/system/session", s.read(auth.RoleAdmin, s.getSessionSettingsHandler))
|
||||
mux.HandleFunc("PUT /api/system/session", s.write(auth.RoleAdmin, s.updateSessionSettingsHandler))
|
||||
|
||||
// 大屏控制页要用「当前设备的局域网地址」拼出平板能直接打开的链接（可点 + 复制 + 二维码）。
|
||||
// 面板自己常常是从 127.0.0.1 打开的，浏览器端点算不出本机局域网 IP，只能由服务端枚举网卡。
|
||||
// 与 /api/system/about 同档：都是机器级信息，guest 一律 403。
|
||||
mux.HandleFunc("GET /api/system/network", s.read(auth.RoleRecorder, s.systemNetwork))
|
||||
|
||||
// 基础配置
|
||||
mux.HandleFunc("GET /api/teams", s.public(s.listTeamsHandler))
|
||||
mux.HandleFunc("POST /api/teams", s.write(auth.RoleRecorder, s.createTeamHandler))
|
||||
|
||||
@@ -162,6 +162,9 @@ func main() {
|
||||
Auth: authSvc,
|
||||
DataDir: cfg.DataDir,
|
||||
Backup: backupSvc,
|
||||
// 实际监听端口：GET /api/system/network 用它拼大屏控制页上的局域网链接，
|
||||
// 必须与下面 srv.Addr 用的是同一个值。
|
||||
Port: cfg.Server.Port,
|
||||
// POST /api/shutdown 复用同一个关闭信号：取消 ctx 后走下面的 Shutdown + 关库。
|
||||
Shutdown: stop,
|
||||
ProjectDir: filepath.Join(cfg.DataDir, "event_projs", projectName),
|
||||
|
||||
@@ -13,6 +13,7 @@ import type {
|
||||
EventSettings,
|
||||
HealthInfo,
|
||||
LiveEvents,
|
||||
NetworkInfo,
|
||||
Page,
|
||||
PageQuery,
|
||||
PointAdjustment,
|
||||
@@ -328,6 +329,19 @@ export const adminApi = {
|
||||
() => ({ source: 'auto', eventIds: [], events: [] }),
|
||||
),
|
||||
|
||||
/**
|
||||
* 本机局域网地址（`GET /api/system/network`，recorder 及以上）。
|
||||
*
|
||||
* 这句是给「大屏控制」页的局域网卡片用的：连不上后端时退回示例地址，
|
||||
* 让示例模式也能看到卡片长什么样；**403 不降级**——访客必须看到「没权限」而不是
|
||||
* 一条看着能用的假地址（那会让人拿着错的链接去别的设备上试）。
|
||||
*/
|
||||
systemNetwork: (): Promise<NetworkInfo> =>
|
||||
call(
|
||||
() => client.system.network(),
|
||||
() => mockDb.network(),
|
||||
),
|
||||
|
||||
login: (username: string, password: string): Promise<CurrentUser> =>
|
||||
callWrite(() => client.auth.login(username, password)),
|
||||
|
||||
|
||||
@@ -11,6 +11,7 @@ import type {
|
||||
EventCategory,
|
||||
EventSettings,
|
||||
HealthInfo,
|
||||
NetworkInfo,
|
||||
Page,
|
||||
PointAdjustment,
|
||||
PublishPayload,
|
||||
@@ -834,6 +835,22 @@ class MockDb {
|
||||
health(): HealthInfo {
|
||||
return { version: 'mock' }
|
||||
}
|
||||
|
||||
/**
|
||||
* 示例模式下的本机网络信息：字段形状与 `GET /api/system/network` 完全一致，
|
||||
* IP 用私有段里的一条假地址，绝不能让示例数据里出现真机或公网地址。
|
||||
*/
|
||||
network(): NetworkInfo {
|
||||
return {
|
||||
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' },
|
||||
],
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
function round(value: number): number {
|
||||
|
||||
@@ -24,6 +24,7 @@ export const ICON_PATHS = {
|
||||
maximize: 'M5 5h14v14H5z',
|
||||
restore: 'M8 8h11v11H8zM5 16V5h11',
|
||||
check: 'M5 12.5 10 17l9-10',
|
||||
copy: 'M9 9h11v11H9zM15 9V4H4v11h4',
|
||||
warning: 'M12 4l9 16H3l9-16Zm0 6v4m0 3v.5',
|
||||
search: 'M11 19a8 8 0 1 0 0-16 8 8 0 0 0 0 16Zm10 2-4.3-4.3',
|
||||
chevron: 'M8 10l4 4 4-4',
|
||||
|
||||
@@ -1,15 +1,18 @@
|
||||
<script setup lang="ts">
|
||||
import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
|
||||
import { formatDateTime, type EventSettings, type LiveEvents } from '@/shared'
|
||||
import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
|
||||
import { formatDateTime, type EventSettings, type LiveEvents, type NetworkInfo } from '@/shared'
|
||||
import type { DisplayInstance } from '@/shared/api'
|
||||
import { DISPLAY_PAGES, type DisplayPageKey } from '@/display/types'
|
||||
import { encodeQr, qrToSvg } from '@/shared/qrcode'
|
||||
import MxIcon from '../components/MxIcon.vue'
|
||||
import PageHeader from '../components/PageHeader.vue'
|
||||
import { adminApi } from '../api/client'
|
||||
import MockBadge from '../components/system/MockBadge.vue'
|
||||
import { adminApi, ApiError } from '../api/client'
|
||||
import { settingsApi } from '../components/system/systemApi'
|
||||
import { useAuthStore } from '../stores/auth'
|
||||
import { useEventStore } from '../stores/event'
|
||||
import { useToastStore } from '../stores/toast'
|
||||
import { copyText, lanDisplayLinks } from './lanDisplay'
|
||||
|
||||
/**
|
||||
* 页面选项直接取大屏那份清单（`@/display/types`）：规范页名与中文标签只维护一处，
|
||||
@@ -317,17 +320,114 @@ function onVisibilityChange(): void {
|
||||
if (document.visibilityState === 'visible') void refreshInstances()
|
||||
}
|
||||
|
||||
// ── 局域网大屏（别的设备用浏览器打开就是一块大屏） ────────────────────────────
|
||||
|
||||
const lanInfo = ref<NetworkInfo | null>(null)
|
||||
/**
|
||||
* 非 null 表示卡片只能给说明、给不出地址：权限不足或接口读不到。
|
||||
*
|
||||
* 用 `lanInfo === null` 兼作「还没读到答案」——请求只有「拿到数据」和「拿到一句话」
|
||||
* 两种结局，所以首帧不会先闪一下「未检测到局域网地址」那个空态。
|
||||
*/
|
||||
const lanProblem = ref<string | null>(null)
|
||||
/** 刚复制成功的地址，1.5 秒后清掉，用来把按钮文案切成「已复制」。 */
|
||||
const copiedUrl = ref<string | null>(null)
|
||||
let copiedTimer: ReturnType<typeof setTimeout> | null = null
|
||||
|
||||
/** 二维码目标边长（像素）：卡片里放得下，也够手机在正常距离扫出来。 */
|
||||
const QR_PIXELS = 140
|
||||
const QR_MARGIN = 4
|
||||
|
||||
/**
|
||||
* 访客提前拦住，不去吃那个必然的 403。
|
||||
*
|
||||
* `/api/system/network` 是 recorder 及以上，与系统设置各面板同一口径；
|
||||
* 示例数据模式例外——那时本来就没有会话，但界面要能看到卡片长什么样。
|
||||
*/
|
||||
const lanGateReason = computed(() =>
|
||||
auth.readOnly && !data.isMock ? '只有登录后的录入员 / 管理员能查看局域网地址，当前为只读访客。' : null,
|
||||
)
|
||||
|
||||
const lanLinks = computed(() => (lanInfo.value === null ? [] : lanDisplayLinks(lanInfo.value)))
|
||||
|
||||
/** 有地址但服务端没给端口：拼不出链接，这句话要和「没插网线」分开说。 */
|
||||
const lanPortMissing = computed(() => lanInfo.value !== null && lanInfo.value.port <= 0)
|
||||
|
||||
/**
|
||||
* 第一个地址的小二维码。
|
||||
*
|
||||
* 只给第一条地址出码：卡片上摆一排二维码没有意义，现场也只需要一个能随手扫的入口。
|
||||
* scale 由模块数反推，让不同版本（21–177 模块）渲染出来都落在接近的像素尺寸上。
|
||||
*/
|
||||
const lanQrSvg = computed(() => {
|
||||
const first = lanLinks.value[0]
|
||||
if (first === undefined) return null
|
||||
const size = encodeQr(first.url).size
|
||||
const scale = Math.max(1, Math.round(QR_PIXELS / (size + QR_MARGIN * 2)))
|
||||
return qrToSvg(first.url, { scale, margin: QR_MARGIN, ecc: 'M' })
|
||||
})
|
||||
|
||||
async function refreshLan(): Promise<void> {
|
||||
// 身份还没就绪时不要「把访客理由写进 lanProblem 就完事」：auth 是异步加载的，
|
||||
// 挂载那一刻 readOnly 必然为 true，写死之后即使随后拿到管理员身份也没有东西再触发本函数
|
||||
// —— 卡片会永远停在「只读访客」，接口一次都不会被请求（真机深链进本页必现）。
|
||||
// 这里的职责只有「能不能读」；读不了就清空状态，等 watch 在身份就绪后重跑。
|
||||
if (lanGateReason.value !== null) {
|
||||
lanInfo.value = null
|
||||
lanProblem.value = null
|
||||
return
|
||||
}
|
||||
try {
|
||||
lanInfo.value = await adminApi.systemNetwork()
|
||||
lanProblem.value = null
|
||||
} catch (caught) {
|
||||
// 403 是权限边界，其余是服务端没给答案；两者在现场要做的事完全不同，不能合成一句。
|
||||
lanInfo.value = null
|
||||
lanProblem.value =
|
||||
caught instanceof ApiError && caught.code === 'FORBIDDEN'
|
||||
? '当前账号没有查看权限，请先登录（该接口需要录入员及以上）。'
|
||||
: `读不到局域网地址：${caught instanceof Error ? caught.message : '未知错误'}`
|
||||
}
|
||||
}
|
||||
|
||||
async function copyLanUrl(url: string): Promise<void> {
|
||||
// 面板多半是从 http://192.168.x.x 打开的，那里 navigator.clipboard 是 undefined，
|
||||
// copyText 会自己退到 execCommand，这里只负责把结果反馈给操作员。
|
||||
const copied = await copyText(url)
|
||||
if (!copied) {
|
||||
toast.error('复制失败', '浏览器不允许自动复制，请手动选中地址复制')
|
||||
return
|
||||
}
|
||||
copiedUrl.value = url
|
||||
if (copiedTimer !== null) clearTimeout(copiedTimer)
|
||||
copiedTimer = setTimeout(() => {
|
||||
copiedUrl.value = null
|
||||
copiedTimer = null
|
||||
}, 1500)
|
||||
}
|
||||
|
||||
onMounted(() => {
|
||||
void loadDisplays()
|
||||
void refreshSettings()
|
||||
void refreshLive()
|
||||
void refreshInstances()
|
||||
void refreshLan()
|
||||
// 身份是异步加载的：挂载那一刻 readOnly 必然为 true，卡片只能先显示「只读访客」。
|
||||
// 等身份落定（gate 变成 null）必须**主动重跑一次**，否则这张卡会永远停在访客态、
|
||||
// 接口一次都不请求 —— 真机深链进本页必现（2026-09-12 用真 Chromium 复现）。
|
||||
watch(lanGateReason, (reason) => {
|
||||
if (reason === null) void refreshLan()
|
||||
})
|
||||
startPolling()
|
||||
document.addEventListener('visibilitychange', onVisibilityChange)
|
||||
})
|
||||
|
||||
onBeforeUnmount(() => {
|
||||
stopPolling()
|
||||
if (copiedTimer !== null) {
|
||||
clearTimeout(copiedTimer)
|
||||
copiedTimer = null
|
||||
}
|
||||
document.removeEventListener('visibilitychange', onVisibilityChange)
|
||||
})
|
||||
|
||||
@@ -804,69 +904,117 @@ async function send(
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<section class="mx-card">
|
||||
<div class="mx-card-head">
|
||||
<span class="mx-card-title">在线大屏</span>
|
||||
<span class="mx-badge" :class="onlineCount > 0 ? 'mx-badge-success' : 'mx-badge-neutral'">
|
||||
{{ onlineCount }} / {{ instances.length }} 在线
|
||||
</span>
|
||||
</div>
|
||||
<div class="mx-card-body">
|
||||
<div v-if="instancesError !== null" class="board-note">
|
||||
<MxIcon name="warning" :size="14" />
|
||||
<span>读取在线大屏失败：{{ instancesError }}</span>
|
||||
<div class="col">
|
||||
<section class="mx-card">
|
||||
<div class="mx-card-head">
|
||||
<span class="mx-card-title">局域网大屏</span>
|
||||
<MockBadge v-if="data.isMock" />
|
||||
<span v-else-if="lanLinks.length > 0" class="mx-badge mx-badge-neutral">
|
||||
{{ lanLinks.length }} 个可用地址
|
||||
</span>
|
||||
</div>
|
||||
<div class="mx-card-body">
|
||||
<p class="lan-intro">在别的设备浏览器打开下面的地址，就是一块大屏。</p>
|
||||
|
||||
<p v-if="instances.length === 0" class="display-note">
|
||||
还没有大屏上报。本机用 Console 打开的大屏窗口、以及局域网设备打开 /display 后，都会在这里出现（每 5 秒刷新一次）。
|
||||
</p>
|
||||
<p v-if="lanGateReason !== null" class="notice">{{ lanGateReason }}</p>
|
||||
<p v-else-if="lanProblem !== null" class="notice">{{ lanProblem }}</p>
|
||||
<p v-else-if="lanInfo === null" class="display-note">读取中…</p>
|
||||
<p v-else-if="lanPortMissing" class="display-note">
|
||||
服务端没有下发大屏端口，暂时拼不出能在别的设备打开的地址。
|
||||
</p>
|
||||
|
||||
<div v-for="instance in instances" :key="instance.id" class="display-row">
|
||||
<div class="display-meta">
|
||||
<div class="display-name">
|
||||
<span class="instance-id">{{ instance.id }}</span>
|
||||
<span class="mx-badge" :class="instance.online ? 'mx-badge-success' : 'mx-badge-error'">
|
||||
{{ instance.online ? '在线' : '离线' }}
|
||||
</span>
|
||||
<span v-if="instance.slow" class="mx-badge mx-badge-warning">落后</span>
|
||||
<span class="mx-badge mx-badge-neutral">
|
||||
{{ instance.screen === '' ? '局域网浏览器' : `屏 ${instance.screen}` }}
|
||||
</span>
|
||||
<template v-else-if="lanLinks.length > 0">
|
||||
<div v-for="(item, index) in lanLinks" :key="item.ip" class="lan-row">
|
||||
<div class="lan-line">
|
||||
<a class="lan-link" :href="item.url" target="_blank" rel="noopener">{{ item.url }}</a>
|
||||
<button class="mx-btn mx-btn-secondary mx-btn-sm" type="button" @click="copyLanUrl(item.url)">
|
||||
<MxIcon :name="copiedUrl === item.url ? 'check' : 'copy'" :size="14" />
|
||||
{{ copiedUrl === item.url ? '已复制' : '复制' }}
|
||||
</button>
|
||||
</div>
|
||||
<div v-if="index === 0 && lanQrSvg !== null" class="lan-qr">
|
||||
<!--
|
||||
内容是自家编码器产出的 SVG 字符串（路径全是数字坐标、aria 里的文本已转义），
|
||||
不是用户输入；用它换掉几百个 <rect>，卡片首屏才不会被二维码拖慢。
|
||||
-->
|
||||
<div class="lan-qr-code" v-html="lanQrSvg"></div>
|
||||
<div class="lan-qr-note">手机扫码直接打开</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="display-sub">
|
||||
当前页：{{ instance.page === '' ? '未上报' : pageLabel(instance.page) }} · 来源：{{ instance.remoteAddr === '' ? '未知' : instance.remoteAddr }}
|
||||
</div>
|
||||
<div class="display-sub">最后心跳：{{ formatDateTime(instance.lastHeartbeat) }}</div>
|
||||
<div v-if="!instance.online" class="display-sub">已离线：指令发不到它，等大屏重新连上再切页。</div>
|
||||
</template>
|
||||
|
||||
<p v-else class="display-note">未检测到局域网地址（可能是没插网线 / 只有回环）。</p>
|
||||
|
||||
<p class="hint">
|
||||
地址由服务端下发的端口与路径拼成；平板上打开后不必登录，大屏本身是只读的。
|
||||
</p>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="mx-card">
|
||||
<div class="mx-card-head">
|
||||
<span class="mx-card-title">在线大屏</span>
|
||||
<span class="mx-badge" :class="onlineCount > 0 ? 'mx-badge-success' : 'mx-badge-neutral'">
|
||||
{{ onlineCount }} / {{ instances.length }} 在线
|
||||
</span>
|
||||
</div>
|
||||
<div class="mx-card-body">
|
||||
<div v-if="instancesError !== null" class="board-note">
|
||||
<MxIcon name="warning" :size="14" />
|
||||
<span>读取在线大屏失败：{{ instancesError }}</span>
|
||||
</div>
|
||||
<div class="display-actions">
|
||||
<select
|
||||
class="mx-cell-input instance-page-select"
|
||||
:value="draftFor(`instance:${instance.id}`, instance.page)"
|
||||
:disabled="!canWrite || !instance.online || targetPending !== null"
|
||||
@change="pickPage(`instance:${instance.id}`, $event)"
|
||||
>
|
||||
<option v-for="page in DISPLAY_PAGES" :key="page.key" :value="page.key">{{ page.title }}</option>
|
||||
</select>
|
||||
<button
|
||||
class="mx-btn mx-btn-primary mx-btn-sm"
|
||||
type="button"
|
||||
:disabled="!canWrite || !instance.online || targetPending !== null"
|
||||
@click="gotoInstance(instance)"
|
||||
>
|
||||
{{ targetPending === `instance:${instance.id}` ? '下发中…' : '切到此页' }}
|
||||
</button>
|
||||
|
||||
<p v-if="instances.length === 0" class="display-note">
|
||||
还没有大屏上报。本机用 Console 打开的大屏窗口、以及局域网设备打开 /display 后，都会在这里出现（每 5 秒刷新一次）。
|
||||
</p>
|
||||
|
||||
<div v-for="instance in instances" :key="instance.id" class="display-row">
|
||||
<div class="display-meta">
|
||||
<div class="display-name">
|
||||
<span class="instance-id">{{ instance.id }}</span>
|
||||
<span class="mx-badge" :class="instance.online ? 'mx-badge-success' : 'mx-badge-error'">
|
||||
{{ instance.online ? '在线' : '离线' }}
|
||||
</span>
|
||||
<span v-if="instance.slow" class="mx-badge mx-badge-warning">落后</span>
|
||||
<span class="mx-badge mx-badge-neutral">
|
||||
{{ instance.screen === '' ? '局域网浏览器' : `屏 ${instance.screen}` }}
|
||||
</span>
|
||||
</div>
|
||||
<div class="display-sub">
|
||||
当前页：{{ instance.page === '' ? '未上报' : pageLabel(instance.page) }} · 来源：{{ instance.remoteAddr === '' ? '未知' : instance.remoteAddr }}
|
||||
</div>
|
||||
<div class="display-sub">最后心跳：{{ formatDateTime(instance.lastHeartbeat) }}</div>
|
||||
<div v-if="!instance.online" class="display-sub">已离线：指令发不到它，等大屏重新连上再切页。</div>
|
||||
</div>
|
||||
<div class="display-actions">
|
||||
<select
|
||||
class="mx-cell-input instance-page-select"
|
||||
:value="draftFor(`instance:${instance.id}`, instance.page)"
|
||||
:disabled="!canWrite || !instance.online || targetPending !== null"
|
||||
@change="pickPage(`instance:${instance.id}`, $event)"
|
||||
>
|
||||
<option v-for="page in DISPLAY_PAGES" :key="page.key" :value="page.key">{{ page.title }}</option>
|
||||
</select>
|
||||
<button
|
||||
class="mx-btn mx-btn-primary mx-btn-sm"
|
||||
type="button"
|
||||
:disabled="!canWrite || !instance.online || targetPending !== null"
|
||||
@click="gotoInstance(instance)"
|
||||
>
|
||||
{{ targetPending === `instance:${instance.id}` ? '下发中…' : '切到此页' }}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="board-hint">
|
||||
<p>当前状态：{{ locked ? '已锁定' : '自动轮播' }} · 全部大屏页面 {{ pageLabel(currentPage) }}</p>
|
||||
<p v-if="instancesUpdatedAt !== null" class="muted">最近一次刷新：{{ formatDateTime(instancesUpdatedAt) }}</p>
|
||||
<p class="muted">「落后」= 该实例确认的版本落后（大屏可能在卡或网络差）；离线实例会在服务端保留一段时间，便于排查。</p>
|
||||
<p v-if="data.isMock" class="mock">示例数据模式下指令不会真正下发到大屏。</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="board-hint">
|
||||
<p>当前状态：{{ locked ? '已锁定' : '自动轮播' }} · 全部大屏页面 {{ pageLabel(currentPage) }}</p>
|
||||
<p v-if="instancesUpdatedAt !== null" class="muted">最近一次刷新：{{ formatDateTime(instancesUpdatedAt) }}</p>
|
||||
<p class="muted">「落后」= 该实例确认的版本落后（大屏可能在卡或网络差）；离线实例会在服务端保留一段时间，便于排查。</p>
|
||||
<p v-if="data.isMock" class="mock">示例数据模式下指令不会真正下发到大屏。</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
@@ -943,6 +1091,53 @@ async function send(
|
||||
background: var(--mx-s3);
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
.lan-intro {
|
||||
font-size: 12px;
|
||||
color: var(--mx-t3);
|
||||
line-height: 1.6;
|
||||
margin-bottom: 12px;
|
||||
}
|
||||
.lan-row {
|
||||
padding: 10px 12px;
|
||||
border-radius: var(--mx-r-sm);
|
||||
background: var(--mx-s3);
|
||||
}
|
||||
.lan-row + .lan-row {
|
||||
margin-top: 8px;
|
||||
}
|
||||
.lan-line {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: 10px;
|
||||
}
|
||||
.lan-link {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
font-family: var(--mx-mono);
|
||||
font-size: 13px;
|
||||
color: var(--mx-primary);
|
||||
/* 地址是机器串出来的，窄栏里要能折行，不能把「复制」按钮顶出卡片。 */
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
.lan-qr {
|
||||
margin-top: 10px;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
align-items: flex-start;
|
||||
gap: 6px;
|
||||
}
|
||||
.lan-qr-code {
|
||||
/* 二维码自带白底留出静区，和卡片底色隔开，避免深色主题下扫不出来。 */
|
||||
line-height: 0;
|
||||
padding: 6px;
|
||||
border-radius: var(--mx-r-xs);
|
||||
background: #fff;
|
||||
}
|
||||
.lan-qr-note {
|
||||
font-size: 12px;
|
||||
color: var(--mx-t3);
|
||||
}
|
||||
.textarea-wrap {
|
||||
height: auto;
|
||||
align-items: flex-start;
|
||||
|
||||
@@ -0,0 +1,102 @@
|
||||
import type { NetworkAddress, NetworkInfo } from '@/shared'
|
||||
|
||||
/**
|
||||
* 「局域网大屏」卡片的纯逻辑。
|
||||
*
|
||||
* 抽出来是因为这两件事都没法在组件里测：地址要靠服务端下发的 port / displayPath 拼
|
||||
* （不能写死），复制要在 `navigator.clipboard` 不存在的老式上下文里退回 execCommand。
|
||||
* 现场面板正是从 `http://192.168.x.x:<端口>` 这种裸 HTTP 地址打开的——**非安全上下文里
|
||||
* clipboard 是 undefined**，所以回退不是兼容性洁癖，而是这条路径的常态。
|
||||
*/
|
||||
|
||||
export interface LanDisplayLink {
|
||||
ip: string
|
||||
/** 完整地址：`http://<ip>:<port><displayPath>`。 */
|
||||
url: string
|
||||
}
|
||||
|
||||
/** 拼一条局域网大屏地址；IPv6 要加方括号，否则端口那一段会被当成地址的一部分。 */
|
||||
export function displayUrl(address: NetworkAddress, network: NetworkInfo): string {
|
||||
const host = address.ip.includes(':') ? `[${address.ip}]` : address.ip
|
||||
return `http://${host}:${network.port}${network.displayPath}`
|
||||
}
|
||||
|
||||
/**
|
||||
* 把服务端返回的网络信息摊平成可点的链接。
|
||||
*
|
||||
* 端口缺失（服务端异常 / 老版本接口）时给空数组：拼 `http://ip:0/display` 这种
|
||||
* 「看着像链接、点开连不上」的东西比空态更糟。
|
||||
*/
|
||||
export function lanDisplayLinks(network: NetworkInfo): LanDisplayLink[] {
|
||||
if (!Number.isFinite(network.port) || network.port <= 0) return []
|
||||
return network.addresses.map((address) => ({ ip: address.ip, url: displayUrl(address, network) }))
|
||||
}
|
||||
|
||||
/** 复制用到的宿主能力；全部可注入，这样在 node 里也能把回退路径走一遍。 */
|
||||
export interface CopyDeps {
|
||||
/** 默认取 `navigator.clipboard`；非安全上下文下它本身就不存在。 */
|
||||
clipboard?: { writeText?: (text: string) => Promise<void> } | null
|
||||
/** 默认走「临时 textarea + document.execCommand('copy')」。 */
|
||||
legacyCopy?: (text: string) => boolean
|
||||
}
|
||||
|
||||
interface ClipboardLike {
|
||||
writeText?: (text: string) => Promise<void>
|
||||
}
|
||||
|
||||
function navigatorClipboard(): ClipboardLike | null {
|
||||
const nav = (globalThis as { navigator?: { clipboard?: ClipboardLike } }).navigator
|
||||
return nav?.clipboard ?? null
|
||||
}
|
||||
|
||||
/**
|
||||
* 优先用异步剪贴板 API，失败或不存在时退回 execCommand。
|
||||
*
|
||||
* 两个坑：一是非安全上下文里 `navigator.clipboard` 直接是 `undefined`（不是抛错），
|
||||
* 二是即便存在，用户拒绝授权 / 文档失焦时 `writeText` 也会 reject——两种都要落到回退，
|
||||
* 而不是把「没复制成功」当成已复制提示给操作员。
|
||||
*/
|
||||
export async function copyText(text: string, deps: CopyDeps = {}): Promise<boolean> {
|
||||
const clipboard = 'clipboard' in deps ? deps.clipboard : navigatorClipboard()
|
||||
if (typeof clipboard?.writeText === 'function') {
|
||||
try {
|
||||
await clipboard.writeText(text)
|
||||
return true
|
||||
} catch {
|
||||
// 落到下面的回退
|
||||
}
|
||||
}
|
||||
const fallback = deps.legacyCopy ?? legacyExecCopy
|
||||
try {
|
||||
return fallback(text)
|
||||
} catch {
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
/** 老式回退：造一个隐身 textarea 选中再 execCommand('copy')。 */
|
||||
function legacyExecCopy(text: string): boolean {
|
||||
const doc = (globalThis as { document?: Document }).document
|
||||
if (doc === undefined || doc.body === null || typeof doc.execCommand !== 'function') return false
|
||||
|
||||
const area = doc.createElement('textarea')
|
||||
area.value = text
|
||||
// aria-hidden + 定位到视口外 + 透明：既不改变布局，也不让移动端弹键盘。
|
||||
area.setAttribute('aria-hidden', 'true')
|
||||
area.style.position = 'fixed'
|
||||
area.style.top = '0'
|
||||
area.style.left = '0'
|
||||
area.style.opacity = '0'
|
||||
area.style.pointerEvents = 'none'
|
||||
doc.body.appendChild(area)
|
||||
|
||||
try {
|
||||
area.focus()
|
||||
area.select()
|
||||
area.setSelectionRange(0, area.value.length)
|
||||
return doc.execCommand('copy')
|
||||
} finally {
|
||||
// 无论成败都要摘掉临时节点：否则每点一次复制就在 body 里留一个隐身 textarea。
|
||||
area.remove()
|
||||
}
|
||||
}
|
||||
@@ -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')
|
||||
})
|
||||
@@ -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()，否则接口永远不会被请求',
|
||||
)
|
||||
})
|
||||
@@ -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\)/)
|
||||
})
|
||||
+50
-1
@@ -1,4 +1,4 @@
|
||||
import { isRawBody, isRecord, readString } from './internal'
|
||||
import { firstNumberOrNull, isRawBody, isRecord, readString } from './internal'
|
||||
import { normalizeRulePack } from './rules'
|
||||
import { readTeamRanksView, readTeamRanksViews } from './teamRanks'
|
||||
import { parseYaml } from './yaml'
|
||||
@@ -26,6 +26,8 @@ import type {
|
||||
HealthInfo,
|
||||
ImportConflictDecision,
|
||||
LiveEvents,
|
||||
NetworkAddress,
|
||||
NetworkInfo,
|
||||
Page,
|
||||
PageQuery,
|
||||
PointAdjustment,
|
||||
@@ -433,6 +435,13 @@ export interface SystemApi {
|
||||
* 不能像普通写操作那样立刻认为已经生效（与切换赛事同一套等待逻辑）。
|
||||
*/
|
||||
restore(input: BackupRestoreInput): Promise<BackupRestoreResult>
|
||||
|
||||
/**
|
||||
* 本机局域网地址（`GET /api/system/network`，recorder 及以上可读）。
|
||||
*
|
||||
* 交给大屏控制页拼「局域网大屏」地址用；访客请求会吃 403，调用方按权限不足处理。
|
||||
*/
|
||||
network(): Promise<NetworkInfo>
|
||||
}
|
||||
|
||||
/**
|
||||
@@ -703,6 +712,44 @@ function readProjectInfo(value: unknown): ProjectInfo | null {
|
||||
}
|
||||
}
|
||||
|
||||
function readNetworkAddress(value: unknown): NetworkAddress | null {
|
||||
if (!isRecord(value)) return null
|
||||
const ip = readString(value, 'ip')
|
||||
// 没有 ip 的行拼不出地址，留着只会在卡片上多出一条空链接。
|
||||
if (ip === null || ip === '') return null
|
||||
return {
|
||||
ip,
|
||||
interface: readString(value, 'interface') ?? '',
|
||||
family: readString(value, 'family') ?? 'ipv4',
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 归一化 `GET /api/system/network`。
|
||||
*
|
||||
* 端口/路径是拼地址的原料，前端不替服务端猜：缺端口就留 0，由页面判断「读不到可用地址」
|
||||
* 并给说明——编一个默认端口出来会得到一条看着对、实际打不开的链接。
|
||||
* addresses 不是数组时按「没检测到地址」处理，交给页面显示空态。
|
||||
*/
|
||||
function readNetworkInfo(value: unknown): NetworkInfo {
|
||||
const port = firstNumberOrNull(isRecord(value) ? value['port'] : null)
|
||||
const rawAddresses = isRecord(value) && Array.isArray(value['addresses']) ? value['addresses'] : []
|
||||
return {
|
||||
port: port !== null && port > 0 ? Math.floor(port) : 0,
|
||||
displayPath: normalizePath(readString(value, 'displayPath'), '/display'),
|
||||
adminPath: normalizePath(readString(value, 'adminPath'), '/admin'),
|
||||
addresses: rawAddresses
|
||||
.map(readNetworkAddress)
|
||||
.filter((item): item is NetworkAddress => item !== null),
|
||||
}
|
||||
}
|
||||
|
||||
/** 服务端没给路径时退回约定值；补前导斜杠，免得拼出 `http://ip:portdisplay`。 */
|
||||
function normalizePath(value: string | null, fallback: string): string {
|
||||
const path = value === null || value.trim() === '' ? fallback : value.trim()
|
||||
return path.startsWith('/') ? path : `/${path}`
|
||||
}
|
||||
|
||||
function createProjectsApi(http: Http): ProjectsApi {
|
||||
return {
|
||||
list: async () => {
|
||||
@@ -904,6 +951,8 @@ export class ApiClient {
|
||||
body: input,
|
||||
timeoutMs: RESTORE_TIMEOUT_MS,
|
||||
}),
|
||||
// request() 会把 {ok,data} 拆开，这里拿到的是 data 本体，再按字段归一化。
|
||||
network: async () => readNetworkInfo(await http.request<unknown>('/system/network')),
|
||||
}
|
||||
this.projects = createProjectsApi(http)
|
||||
|
||||
|
||||
@@ -0,0 +1,549 @@
|
||||
/**
|
||||
* 纯 TypeScript 二维码编码器（字节模式 / UTF-8），零依赖。
|
||||
*
|
||||
* 为什么自己写：现场是离线局域网，装不了 npm 包；而「局域网大屏」卡片要的是一个
|
||||
* 能扫的矢量码，不是一张贴图。实现按 ISO/IEC 18004 走：字节模式、1–40 版自动选版、
|
||||
* L/M/Q/H 四档纠错、8 种掩码按惩罚分择优，最后输出模块矩阵，可渲染成任意尺寸的 SVG。
|
||||
*
|
||||
* 对外只暴露两件事：`encodeQr`（要矩阵）与 `qrToSvg`（要能直接塞进卡片的字符串）。
|
||||
*/
|
||||
|
||||
/** 纠错级别：L≈7% / M≈15% / Q≈25% / H≈30% 的码字可被恢复。 */
|
||||
export type QrEcc = 'L' | 'M' | 'Q' | 'H'
|
||||
|
||||
export interface QrEncodeOptions {
|
||||
/** 纠错级别，默认 M：屏幕扫码距离近、容错够用，容量也不至于太小。 */
|
||||
ecc?: QrEcc
|
||||
/**
|
||||
* 最低版本（1–40）。默认 1。
|
||||
*
|
||||
* 保留给「同一张卡片上多个码尺寸要一致」这类排版需求；正常情况下让它自动选版。
|
||||
*/
|
||||
minVersion?: number
|
||||
}
|
||||
|
||||
export interface QrMatrix {
|
||||
/** 二维码版本 1–40，边长 = version * 4 + 17。 */
|
||||
version: number
|
||||
/** 边长（模块数，不含静区）。 */
|
||||
size: number
|
||||
ecc: QrEcc
|
||||
/** 模块矩阵：`modules[y][x]` 为 true 表示深色。不含静区。 */
|
||||
modules: boolean[][]
|
||||
}
|
||||
|
||||
export interface QrSvgOptions extends QrEncodeOptions {
|
||||
/** 每个模块占多少像素（SVG 用户单位），默认 4。矢量渲染，放大不糊。 */
|
||||
scale?: number
|
||||
/** 静区宽度（模块数），默认 4；低于 4 会显著影响识别率。 */
|
||||
margin?: number
|
||||
}
|
||||
|
||||
export const ECC_LEVELS: readonly QrEcc[] = ['L', 'M', 'Q', 'H']
|
||||
|
||||
/** 版本 1–40 的字节模式容量表（数据码字数、可容纳字节数），由下面的表推出，仅用于报错信息。 */
|
||||
const MIN_VERSION = 1
|
||||
const MAX_VERSION = 40
|
||||
const MODE_BYTE = 0x4
|
||||
const PENALTY_N1 = 3
|
||||
const PENALTY_N2 = 3
|
||||
const PENALTY_N3 = 40
|
||||
const PENALTY_N4 = 10
|
||||
|
||||
// ── 规格表（ISO/IEC 18004 表 9 与表 13–22） ─────────────────────────────────
|
||||
// 下标是版本号，[0] 是占位 -1。行序与 ECC_LEVELS 一致：L / M / Q / H。
|
||||
|
||||
const ECC_CODEWORDS_PER_BLOCK: readonly (readonly number[])[] = [
|
||||
// L
|
||||
[-1, 7, 10, 15, 20, 26, 18, 20, 24, 30, 18, 20, 24, 26, 30, 22, 24, 28, 30, 28, 28, 28, 28, 30, 30, 26, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
|
||||
// M
|
||||
[-1, 10, 16, 26, 18, 24, 16, 18, 22, 22, 26, 30, 22, 22, 24, 24, 28, 28, 26, 26, 26, 26, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28, 28],
|
||||
// Q
|
||||
[-1, 13, 22, 18, 26, 18, 24, 18, 22, 20, 24, 28, 26, 24, 20, 30, 24, 28, 28, 26, 30, 28, 30, 30, 30, 30, 28, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
|
||||
// H
|
||||
[-1, 17, 28, 22, 16, 22, 28, 26, 26, 24, 28, 24, 28, 22, 24, 24, 30, 28, 28, 26, 28, 30, 24, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30, 30],
|
||||
]
|
||||
|
||||
const NUM_ERROR_CORRECTION_BLOCKS: readonly (readonly number[])[] = [
|
||||
// L
|
||||
[-1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 4, 4, 4, 4, 4, 6, 6, 6, 6, 7, 8, 8, 9, 9, 10, 12, 12, 12, 13, 14, 15, 16, 17, 18, 19, 19, 20, 21, 22, 24, 25],
|
||||
// M
|
||||
[-1, 1, 1, 1, 2, 2, 4, 4, 4, 5, 5, 5, 8, 9, 9, 10, 10, 11, 13, 14, 16, 17, 17, 18, 20, 21, 23, 25, 26, 28, 29, 31, 33, 35, 37, 38, 40, 43, 45, 47, 49],
|
||||
// Q
|
||||
[-1, 1, 1, 2, 2, 4, 4, 6, 6, 8, 8, 8, 10, 12, 16, 12, 17, 16, 18, 21, 20, 23, 23, 25, 27, 29, 34, 34, 35, 38, 40, 43, 45, 48, 51, 53, 56, 59, 62, 65, 68],
|
||||
// H
|
||||
[-1, 1, 1, 2, 4, 4, 4, 5, 6, 8, 8, 11, 11, 16, 16, 18, 16, 19, 21, 25, 25, 25, 34, 30, 32, 35, 37, 40, 42, 45, 48, 51, 54, 57, 60, 63, 66, 70, 74, 77, 81],
|
||||
]
|
||||
|
||||
/** 格式信息里的纠错指示位（L=01 / M=00 / Q=11 / H=10），与矩阵下标不是同一套编号。 */
|
||||
const ECC_FORMAT_BITS: readonly number[] = [1, 0, 3, 2]
|
||||
|
||||
function eccIndex(ecc: QrEcc): number {
|
||||
const index = ECC_LEVELS.indexOf(ecc)
|
||||
if (index < 0) throw new RangeError(`不支持的纠错级别：${String(ecc)}`)
|
||||
return index
|
||||
}
|
||||
|
||||
function eccCodewordsPerBlock(version: number, index: number): number {
|
||||
return ECC_CODEWORDS_PER_BLOCK[index]![version]!
|
||||
}
|
||||
|
||||
function numErrorCorrectionBlocks(version: number, index: number): number {
|
||||
return NUM_ERROR_CORRECTION_BLOCKS[index]![version]!
|
||||
}
|
||||
|
||||
/**
|
||||
* 该版本「不参与功能的模块」总数（位）。
|
||||
*
|
||||
* 由几何推算而不是查表：每加一个版本多出的定位/计时/对齐/版本信息都能用式子表达，
|
||||
* 少一张 40 行的表就少一处抄错的机会。
|
||||
*/
|
||||
function numRawDataModules(version: number): number {
|
||||
let result = (16 * version + 128) * version + 64
|
||||
if (version >= 2) {
|
||||
const numAlign = Math.floor(version / 7) + 2
|
||||
result -= (25 * numAlign - 10) * numAlign - 55
|
||||
if (version >= 7) result -= 36
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
/** 该版本 + 纠错级别下的数据码字数（纠错码字不算）。 */
|
||||
function numDataCodewords(version: number, index: number): number {
|
||||
return (
|
||||
Math.floor(numRawDataModules(version) / 8) -
|
||||
eccCodewordsPerBlock(version, index) * numErrorCorrectionBlocks(version, index)
|
||||
)
|
||||
}
|
||||
|
||||
/** 对齐图案中心坐标；版本 1 没有对齐图案。 */
|
||||
function alignmentPatternPositions(version: number): number[] {
|
||||
if (version === 1) return []
|
||||
const numAlign = Math.floor(version / 7) + 2
|
||||
// 版本 32 的步长是规格里的特例，按公式算会得到 28 而正确值是 26。
|
||||
const step = version === 32 ? 26 : Math.ceil((version * 4 + 4) / (numAlign * 2 - 2)) * 2
|
||||
const result = [6]
|
||||
for (let pos = version * 4 + 10; result.length < numAlign; pos -= step) result.splice(1, 0, pos)
|
||||
return result
|
||||
}
|
||||
|
||||
function getBit(value: number, index: number): boolean {
|
||||
return ((value >>> index) & 1) !== 0
|
||||
}
|
||||
|
||||
// ── Reed–Solomon（GF(256)，本原多项式 0x11D） ───────────────────────────────
|
||||
|
||||
function reedSolomonMultiply(x: number, y: number): number {
|
||||
let z = 0
|
||||
for (let i = 7; i >= 0; i--) {
|
||||
z = (z << 1) ^ ((z >>> 7) * 0x11d)
|
||||
z ^= ((y >>> i) & 1) * x
|
||||
}
|
||||
return z & 0xff
|
||||
}
|
||||
|
||||
/** 生成多项式 (x - α^0)(x - α^1)…(x - α^(degree-1)) 的系数，最高次项省略。 */
|
||||
function reedSolomonComputeDivisor(degree: number): Uint8Array {
|
||||
const result = new Uint8Array(degree)
|
||||
result[degree - 1] = 1
|
||||
let root = 1
|
||||
for (let i = 0; i < degree; i++) {
|
||||
for (let j = 0; j < degree; j++) {
|
||||
result[j] = reedSolomonMultiply(result[j]!, root)
|
||||
if (j + 1 < degree) result[j] ^= result[j + 1]!
|
||||
}
|
||||
root = reedSolomonMultiply(root, 0x02)
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
/** 多项式除法取余，得到该块的纠错码字。 */
|
||||
function reedSolomonComputeRemainder(data: Uint8Array, divisor: Uint8Array): Uint8Array {
|
||||
const result = new Uint8Array(divisor.length)
|
||||
for (const byte of data) {
|
||||
const factor = byte ^ result[0]!
|
||||
result.copyWithin(0, 1)
|
||||
result[result.length - 1] = 0
|
||||
for (let i = 0; i < divisor.length; i++) {
|
||||
result[i] ^= reedSolomonMultiply(divisor[i]!, factor)
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
// ── 数据码字 ────────────────────────────────────────────────────────────────
|
||||
|
||||
/** 字节模式字符计数指示符的位宽：版本 1–9 是 8 位，10–40 是 16 位。 */
|
||||
function byteCountBits(version: number): number {
|
||||
return version <= 9 ? 8 : 16
|
||||
}
|
||||
|
||||
/** 该版本 + 级别下能装下的最大字节数。 */
|
||||
function byteCapacity(version: number, index: number): number {
|
||||
const bits = numDataCodewords(version, index) * 8 - 4 - byteCountBits(version)
|
||||
return Math.max(0, Math.floor(bits / 8))
|
||||
}
|
||||
|
||||
function chooseVersion(byteLength: number, index: number, minVersion: number): number {
|
||||
const start = Math.max(MIN_VERSION, Math.min(MAX_VERSION, Math.floor(minVersion)))
|
||||
for (let version = start; version <= MAX_VERSION; version++) {
|
||||
if (byteLength <= byteCapacity(version, index)) return version
|
||||
}
|
||||
throw new RangeError(
|
||||
`内容过长：${byteLength} 字节超出 ${ECC_LEVELS[index]} 级第 ${MAX_VERSION} 版的容量（${byteCapacity(MAX_VERSION, index)} 字节）`,
|
||||
)
|
||||
}
|
||||
|
||||
/** 位流拼装：模式指示符 + 字符计数 + 数据 + 终止符 + 补齐字节（0xEC / 0x11 交替）。 */
|
||||
function buildDataCodewords(bytes: Uint8Array, version: number, index: number): Uint8Array {
|
||||
const capacityBits = numDataCodewords(version, index) * 8
|
||||
const result: number[] = []
|
||||
let accumulator = 0
|
||||
let bitCount = 0
|
||||
|
||||
const pushBits = (value: number, count: number): void => {
|
||||
for (let i = count - 1; i >= 0; i--) {
|
||||
accumulator = (accumulator << 1) | ((value >>> i) & 1)
|
||||
bitCount++
|
||||
if (bitCount === 8) {
|
||||
result.push(accumulator)
|
||||
accumulator = 0
|
||||
bitCount = 0
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pushBits(MODE_BYTE, 4)
|
||||
pushBits(bytes.length, byteCountBits(version))
|
||||
for (const byte of bytes) pushBits(byte, 8)
|
||||
|
||||
// 终止符最多 4 个 0；剩余空间不足 4 位时按剩余位数补。
|
||||
pushBits(0, Math.min(4, capacityBits - result.length * 8 - bitCount))
|
||||
if (bitCount > 0) pushBits(0, 8 - bitCount)
|
||||
for (let pad = 0xec; result.length < capacityBits / 8; pad ^= 0xec ^ 0x11) result.push(pad)
|
||||
|
||||
return Uint8Array.from(result)
|
||||
}
|
||||
|
||||
/**
|
||||
* 分块算纠错再交错：二维码的纠错是按块做的，读出端逐块恢复，
|
||||
* 单块损坏不会报销整张码，所以块划分必须与规格表完全一致。
|
||||
*/
|
||||
function addEccAndInterleave(data: Uint8Array, version: number, index: number): Uint8Array {
|
||||
const numBlocks = numErrorCorrectionBlocks(version, index)
|
||||
const blockEccLength = eccCodewordsPerBlock(version, index)
|
||||
const rawCodewords = Math.floor(numRawDataModules(version) / 8)
|
||||
const numShortBlocks = numBlocks - (rawCodewords % numBlocks)
|
||||
const shortBlockLength = Math.floor(rawCodewords / numBlocks)
|
||||
const divisor = reedSolomonComputeDivisor(blockEccLength)
|
||||
|
||||
const blocks: number[][] = []
|
||||
for (let i = 0, offset = 0; i < numBlocks; i++) {
|
||||
const dataLength = shortBlockLength - blockEccLength + (i < numShortBlocks ? 0 : 1)
|
||||
const dat = Array.from(data.subarray(offset, offset + dataLength))
|
||||
offset += dataLength
|
||||
const ecc = reedSolomonComputeRemainder(Uint8Array.from(dat), divisor)
|
||||
// 短块补一个占位，让所有块等长，交错时再按位置跳过它。
|
||||
if (i < numShortBlocks) dat.push(0)
|
||||
blocks.push(dat.concat(Array.from(ecc)))
|
||||
}
|
||||
|
||||
const result: number[] = []
|
||||
for (let i = 0; i < blocks[0]!.length; i++) {
|
||||
for (let j = 0; j < blocks.length; j++) {
|
||||
if (i !== shortBlockLength - blockEccLength || j >= numShortBlocks) result.push(blocks[j]![i]!)
|
||||
}
|
||||
}
|
||||
return Uint8Array.from(result)
|
||||
}
|
||||
|
||||
// ── 掩码与惩罚分 ────────────────────────────────────────────────────────────
|
||||
|
||||
function maskBit(mask: number, x: number, y: number): boolean {
|
||||
switch (mask) {
|
||||
case 0:
|
||||
return (x + y) % 2 === 0
|
||||
case 1:
|
||||
return y % 2 === 0
|
||||
case 2:
|
||||
return x % 3 === 0
|
||||
case 3:
|
||||
return (x + y) % 3 === 0
|
||||
case 4:
|
||||
return (Math.floor(x / 3) + Math.floor(y / 2)) % 2 === 0
|
||||
case 5:
|
||||
return ((x * y) % 2) + ((x * y) % 3) === 0
|
||||
case 6:
|
||||
return (((x * y) % 2) + ((x * y) % 3)) % 2 === 0
|
||||
default:
|
||||
return (((x + y) % 2) + ((x * y) % 3)) % 2 === 0
|
||||
}
|
||||
}
|
||||
|
||||
/** 规格里的「1:1:3:1:1 定位图案」扫描历史窗口，长度固定 7。 */
|
||||
function finderPenaltyAddHistory(runLength: number, runHistory: number[], size: number): void {
|
||||
// 首段深色之前没有浅色边界，补上整条静区宽度，否则开头/结尾的伪定位图案会漏判。
|
||||
if (runHistory[0] === 0) runLength += size
|
||||
runHistory.pop()
|
||||
runHistory.unshift(runLength)
|
||||
}
|
||||
|
||||
function finderPenaltyCountPatterns(runHistory: number[]): number {
|
||||
const n = runHistory[1]!
|
||||
const core = n > 0 && runHistory[2] === n && runHistory[3] === n * 3 && runHistory[4] === n && runHistory[5] === n
|
||||
if (!core) return 0
|
||||
return (runHistory[0]! >= n * 4 && runHistory[6]! >= n ? 1 : 0) + (runHistory[6]! >= n * 4 && runHistory[0]! >= n ? 1 : 0)
|
||||
}
|
||||
|
||||
function finderPenaltyTerminateAndCount(currentRunColor: boolean, currentRunLength: number, runHistory: number[], size: number): number {
|
||||
let length = currentRunLength
|
||||
if (currentRunColor) {
|
||||
finderPenaltyAddHistory(length, runHistory, size)
|
||||
length = 0
|
||||
}
|
||||
length += size // 末尾补静区宽度的浅色
|
||||
finderPenaltyAddHistory(length, runHistory, size)
|
||||
return finderPenaltyCountPatterns(runHistory)
|
||||
}
|
||||
|
||||
function penaltyScore(modules: boolean[][], size: number): number {
|
||||
let result = 0
|
||||
|
||||
const scoreLine = (get: (i: number) => boolean): void => {
|
||||
let runColor = false
|
||||
let runLength = 0
|
||||
const runHistory = [0, 0, 0, 0, 0, 0, 0]
|
||||
for (let i = 0; i < size; i++) {
|
||||
if (get(i) === runColor) {
|
||||
runLength++
|
||||
if (runLength === 5) result += PENALTY_N1
|
||||
else if (runLength > 5) result++
|
||||
} else {
|
||||
finderPenaltyAddHistory(runLength, runHistory, size)
|
||||
if (!runColor) result += finderPenaltyCountPatterns(runHistory) * PENALTY_N3
|
||||
runColor = get(i)
|
||||
runLength = 1
|
||||
}
|
||||
}
|
||||
result += finderPenaltyTerminateAndCount(runColor, runLength, runHistory, size) * PENALTY_N3
|
||||
}
|
||||
|
||||
for (let y = 0; y < size; y++) scoreLine((x) => modules[y]![x]!)
|
||||
for (let x = 0; x < size; x++) scoreLine((y) => modules[y]![x]!)
|
||||
|
||||
// 2×2 同色块
|
||||
for (let y = 0; y < size - 1; y++) {
|
||||
for (let x = 0; x < size - 1; x++) {
|
||||
const color = modules[y]![x]!
|
||||
if (color === modules[y]![x + 1] && color === modules[y + 1]![x] && color === modules[y + 1]![x + 1]) {
|
||||
result += PENALTY_N2
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 黑白比例偏离 50% 的惩罚
|
||||
let dark = 0
|
||||
for (const row of modules) for (const cell of row) if (cell) dark++
|
||||
const total = size * size
|
||||
const k = Math.ceil(Math.abs(dark * 20 - total * 10) / total) - 1
|
||||
return result + k * PENALTY_N4
|
||||
}
|
||||
|
||||
// ── 矩阵构建 ────────────────────────────────────────────────────────────────
|
||||
|
||||
function formatBits(eccFormatBits: number, mask: number): number {
|
||||
const data = (eccFormatBits << 3) | mask
|
||||
let rem = data
|
||||
for (let i = 0; i < 10; i++) rem = (rem << 1) ^ ((rem >>> 9) * 0x537)
|
||||
return ((data << 10) | rem) ^ 0x5412
|
||||
}
|
||||
|
||||
function versionBits(version: number): number {
|
||||
let rem = version
|
||||
for (let i = 0; i < 12; i++) rem = (rem << 1) ^ ((rem >>> 11) * 0x1f25)
|
||||
return (version << 12) | rem
|
||||
}
|
||||
|
||||
function buildMatrix(version: number, eccFormatBits: number, codewords: Uint8Array): boolean[][] {
|
||||
const size = version * 4 + 17
|
||||
const modules: boolean[][] = Array.from({ length: size }, () => new Array<boolean>(size).fill(false))
|
||||
const isFunction: boolean[][] = Array.from({ length: size }, () => new Array<boolean>(size).fill(false))
|
||||
|
||||
const setFunction = (x: number, y: number, dark: boolean): void => {
|
||||
modules[y]![x] = dark
|
||||
isFunction[y]![x] = true
|
||||
}
|
||||
|
||||
/** 定位图案连静区一起画：以中心为原点 9×9，半径 4 是分隔区（浅色）。 */
|
||||
const drawFinderPattern = (centerX: number, centerY: number): void => {
|
||||
for (let dy = -4; dy <= 4; dy++) {
|
||||
for (let dx = -4; dx <= 4; dx++) {
|
||||
const x = centerX + dx
|
||||
const y = centerY + dy
|
||||
if (x < 0 || x >= size || y < 0 || y >= size) continue
|
||||
const distance = Math.max(Math.abs(dx), Math.abs(dy))
|
||||
setFunction(x, y, distance !== 2 && distance !== 4)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const drawAlignmentPattern = (centerX: number, centerY: number): void => {
|
||||
for (let dy = -2; dy <= 2; dy++) {
|
||||
for (let dx = -2; dx <= 2; dx++) {
|
||||
setFunction(centerX + dx, centerY + dy, Math.max(Math.abs(dx), Math.abs(dy)) !== 1)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 计时图案先画：第 6 行/列交替。三个定位图案随后覆盖它的两端，
|
||||
// 顺序反了会把定位图案底边/右边那一排误刷成浅色，整张码就直接废了。
|
||||
for (let i = 0; i < size; i++) {
|
||||
setFunction(6, i, i % 2 === 0)
|
||||
setFunction(i, 6, i % 2 === 0)
|
||||
}
|
||||
|
||||
drawFinderPattern(3, 3)
|
||||
drawFinderPattern(size - 4, 3)
|
||||
drawFinderPattern(3, size - 4)
|
||||
|
||||
const alignments = alignmentPatternPositions(version)
|
||||
const last = alignments.length - 1
|
||||
for (let i = 0; i < alignments.length; i++) {
|
||||
for (let j = 0; j < alignments.length; j++) {
|
||||
// 三个定位图案的角上不放对齐图案
|
||||
if ((i === 0 && j === 0) || (i === 0 && j === last) || (i === last && j === 0)) continue
|
||||
drawAlignmentPattern(alignments[i]!, alignments[j]!)
|
||||
}
|
||||
}
|
||||
|
||||
const drawFormat = (mask: number): void => {
|
||||
const data = formatBits(eccFormatBits, mask)
|
||||
for (let i = 0; i <= 5; i++) setFunction(8, i, getBit(data, i))
|
||||
setFunction(8, 7, getBit(data, 6))
|
||||
setFunction(8, 8, getBit(data, 7))
|
||||
setFunction(7, 8, getBit(data, 8))
|
||||
for (let i = 9; i < 15; i++) setFunction(14 - i, 8, getBit(data, i))
|
||||
for (let i = 0; i < 8; i++) setFunction(size - 1 - i, 8, getBit(data, i))
|
||||
for (let i = 8; i < 15; i++) setFunction(8, size - 15 + i, getBit(data, i))
|
||||
setFunction(8, size - 8, true) // 固定的深色模块
|
||||
}
|
||||
|
||||
// 先按掩码 0 占位，把格式信息区域标记成功能模块，数据码字才不会写进去。
|
||||
drawFormat(0)
|
||||
|
||||
if (version >= 7) {
|
||||
const bits = versionBits(version)
|
||||
for (let i = 0; i < 18; i++) {
|
||||
const bit = getBit(bits, i)
|
||||
const a = size - 11 + (i % 3)
|
||||
const b = Math.floor(i / 3)
|
||||
setFunction(a, b, bit)
|
||||
setFunction(b, a, bit)
|
||||
}
|
||||
}
|
||||
|
||||
// 数据码字从右下角起，每两列一组蛇形向上/向下填。
|
||||
let bitIndex = 0
|
||||
for (let right = size - 1; right >= 1; right -= 2) {
|
||||
if (right === 6) right = 5 // 第 6 列是计时图案，跳过
|
||||
for (let vert = 0; vert < size; vert++) {
|
||||
for (let j = 0; j < 2; j++) {
|
||||
const x = right - j
|
||||
const upward = ((right + 1) & 2) === 0
|
||||
const y = upward ? size - 1 - vert : vert
|
||||
if (!isFunction[y]![x] && bitIndex < codewords.length * 8) {
|
||||
modules[y]![x] = getBit(codewords[bitIndex >>> 3]!, 7 - (bitIndex & 7))
|
||||
bitIndex++
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const applyMask = (mask: number): void => {
|
||||
for (let y = 0; y < size; y++) {
|
||||
for (let x = 0; x < size; x++) {
|
||||
if (!isFunction[y]![x] && maskBit(mask, x, y)) modules[y]![x] = !modules[y]![x]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
let bestMask = 0
|
||||
let minPenalty = Number.POSITIVE_INFINITY
|
||||
for (let mask = 0; mask < 8; mask++) {
|
||||
applyMask(mask)
|
||||
drawFormat(mask)
|
||||
const penalty = penaltyScore(modules, size)
|
||||
if (penalty < minPenalty) {
|
||||
bestMask = mask
|
||||
minPenalty = penalty
|
||||
}
|
||||
applyMask(mask) // 撤销，试下一个
|
||||
}
|
||||
|
||||
applyMask(bestMask)
|
||||
drawFormat(bestMask)
|
||||
return modules
|
||||
}
|
||||
|
||||
// ── 对外接口 ────────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* 把文本编成二维码模块矩阵（字节模式 / UTF-8），自动选版。
|
||||
*
|
||||
* 内容超出第 40 版容量时抛 RangeError：与其画一张扫不出来的码，不如让调用方
|
||||
* 知道「这条内容放不下」（URL 场景下这几乎只会发生在误传整段文本时）。
|
||||
*/
|
||||
export function encodeQr(text: string, options: QrEncodeOptions = {}): QrMatrix {
|
||||
const ecc = options.ecc ?? 'M'
|
||||
const index = eccIndex(ecc)
|
||||
const bytes = new TextEncoder().encode(text)
|
||||
const version = chooseVersion(bytes.length, index, options.minVersion ?? MIN_VERSION)
|
||||
const data = buildDataCodewords(bytes, version, index)
|
||||
const codewords = addEccAndInterleave(data, version, index)
|
||||
const modules = buildMatrix(version, ECC_FORMAT_BITS[index]!, codewords)
|
||||
return { version, size: modules.length, ecc, modules }
|
||||
}
|
||||
|
||||
/** 该纠错级别下最多能编多少个字节（第 40 版）。 */
|
||||
export function qrByteCapacity(ecc: QrEcc = 'M'): number {
|
||||
return byteCapacity(MAX_VERSION, eccIndex(ecc))
|
||||
}
|
||||
|
||||
const SVG_NS = 'http://www.w3.org/2000/svg'
|
||||
|
||||
/** 无障碍标签里要放原文，URL 常带 `&` / 引号，不转义会把 aria-label 属性截断。 */
|
||||
const XML_ESCAPES: Record<string, string> = { '&': '&', '<': '<', '>': '>', '"': '"' }
|
||||
|
||||
function escapeXml(text: string): string {
|
||||
return text.replace(/[&<>"]/g, (ch) => XML_ESCAPES[ch]!)
|
||||
}
|
||||
|
||||
/** 把矩阵渲染成 SVG 字符串：一个白底 `<rect>` + 一条深色 `<path>`，任意尺寸都清晰。 */
|
||||
export function qrToSvg(text: string, options: QrSvgOptions = {}): string {
|
||||
const scale = options.scale ?? 4
|
||||
const margin = options.margin ?? 4
|
||||
const matrix = encodeQr(text, options)
|
||||
const dimension = matrix.size + margin * 2
|
||||
|
||||
let path = ''
|
||||
for (let y = 0; y < matrix.size; y++) {
|
||||
const row = matrix.modules[y]!
|
||||
for (let x = 0; x < matrix.size; x++) {
|
||||
if (row[x]) path += `M${x + margin} ${y + margin}h1v1h-1z`
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
`<svg xmlns="${SVG_NS}" width="${dimension * scale}" height="${dimension * scale}" ` +
|
||||
`viewBox="0 0 ${dimension} ${dimension}" shape-rendering="crispEdges" role="img" ` +
|
||||
`aria-label="扫码打开 ${escapeXml(text)}">` +
|
||||
`<rect width="${dimension}" height="${dimension}" fill="#FFFFFF"/>` +
|
||||
`<path d="${path}" fill="#000000"/>` +
|
||||
`</svg>`
|
||||
)
|
||||
}
|
||||
|
||||
/** 矩阵转成 `1`/`0` 逐行文本，便于测试与冻结参照比对。 */
|
||||
export function qrMatrixToRows(matrix: QrMatrix): string[] {
|
||||
return matrix.modules.map((row) => row.map((cell) => (cell ? '1' : '0')).join(''))
|
||||
}
|
||||
@@ -0,0 +1,94 @@
|
||||
import { test } from 'node:test'
|
||||
import assert from 'node:assert/strict'
|
||||
import { ApiClient, ApiError } from '../api'
|
||||
|
||||
/**
|
||||
* `GET /api/system/network` 的解析契约。
|
||||
*
|
||||
* 「局域网大屏」卡片是完全按这份数据拼地址的：端口 / 路径读错，现场拿到的就是一条
|
||||
* 打不开的链接；地址行少一个字段也得当脏数据丢掉，不能渲染成空链接。
|
||||
*/
|
||||
|
||||
function jsonResponse(data: unknown, status = 200): Response {
|
||||
return new Response(JSON.stringify({ ok: true, data }), {
|
||||
status,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
})
|
||||
}
|
||||
|
||||
/** 错误响应不走 {ok,data} 包装，服务端直接回 {ok:false,error}。 */
|
||||
function errorResponse(status: number, code: string, message: string): Response {
|
||||
return new Response(JSON.stringify({ ok: false, error: { code, message } }), {
|
||||
status,
|
||||
headers: { 'Content-Type': 'application/json' },
|
||||
})
|
||||
}
|
||||
|
||||
const NETWORK = {
|
||||
port: 19540,
|
||||
displayPath: '/display',
|
||||
adminPath: '/admin',
|
||||
addresses: [{ ip: '192.168.1.23', interface: 'eth0', family: 'ipv4' }],
|
||||
}
|
||||
|
||||
function client(reply: () => Response): ApiClient {
|
||||
return new ApiClient({ fetchImpl: async () => reply() })
|
||||
}
|
||||
|
||||
test('network 打的是 /api/system/network，端口与路径原样透传', async () => {
|
||||
let url = ''
|
||||
let method: string | undefined
|
||||
const api = new ApiClient({
|
||||
fetchImpl: async (input, init) => {
|
||||
url = String(input)
|
||||
method = init?.method
|
||||
return jsonResponse(NETWORK)
|
||||
},
|
||||
})
|
||||
|
||||
const info = await api.system.network()
|
||||
|
||||
assert.equal(url, '/api/system/network')
|
||||
assert.equal(method ?? 'GET', 'GET')
|
||||
assert.deepEqual(info, NETWORK)
|
||||
})
|
||||
|
||||
test('addresses 缺失或不是数组时按「没有可用地址」处理，不是解析失败', async () => {
|
||||
// 没插网线 / 只有回环时服务端就回空数组；接口本身是成功的。
|
||||
assert.deepEqual((await client(() => jsonResponse({ ...NETWORK, addresses: [] })).system.network()).addresses, [])
|
||||
assert.deepEqual((await client(() => jsonResponse({ port: 19540 })).system.network()).addresses, [])
|
||||
// 脏数据：没有 ip 的行拼不出地址，丢掉而不是留一条空链接。
|
||||
const dirty = await client(() =>
|
||||
jsonResponse({ ...NETWORK, addresses: [{ interface: 'eth0' }, { ip: '', family: 'ipv4' }, 'x'] }),
|
||||
).system.network()
|
||||
assert.deepEqual(dirty.addresses, [])
|
||||
})
|
||||
|
||||
test('缺端口时给 0 而不是替服务端编一个端口', async () => {
|
||||
const info = await client(() => jsonResponse({ displayPath: '/display' })).system.network()
|
||||
assert.equal(info.port, 0)
|
||||
// 路径缺失时退回约定值，且一定带前导斜杠，否则会拼出 `...:19540display`。
|
||||
assert.equal(info.displayPath, '/display')
|
||||
assert.equal(info.adminPath, '/admin')
|
||||
|
||||
const relative = await client(() => jsonResponse({ port: 8080, displayPath: 'screen' })).system.network()
|
||||
assert.equal(relative.displayPath, '/screen')
|
||||
})
|
||||
|
||||
test('路径是空白串时退回约定值', async () => {
|
||||
const info = await client(() => jsonResponse({ port: 19540, displayPath: ' ' })).system.network()
|
||||
assert.equal(info.displayPath, '/display')
|
||||
})
|
||||
|
||||
test('403 原样抛出 FORBIDDEN，不当成「没有地址」', async () => {
|
||||
await assert.rejects(
|
||||
() => client(() => errorResponse(403, 'FORBIDDEN', '需要录入员及以上权限')).system.network(),
|
||||
(error: unknown) => {
|
||||
assert.ok(error instanceof ApiError)
|
||||
assert.equal(error.code, 'FORBIDDEN')
|
||||
assert.equal(error.status, 403)
|
||||
assert.equal(error.message, '需要录入员及以上权限')
|
||||
return true
|
||||
},
|
||||
)
|
||||
})
|
||||
@@ -0,0 +1,386 @@
|
||||
import type { QrEcc } from '../qrcode'
|
||||
|
||||
/**
|
||||
* 冻结的二维码参照用例（由 `/tmp` 的临时脚本生成，不入库）。
|
||||
*
|
||||
* 每条都先用 cv2.QRCodeDetector().detectAndDecode 在 PGM 上解出原文，确认「能扫」之后
|
||||
* 才把矩阵逐行钉在这里。以后改动 qrcode.ts（掩码、纠错分块、版本表…）只要矩阵变了一位，
|
||||
* 这些用例就会红——矩阵哈希看不出哪里变了，逐行字符串能直接 diff 出位置。
|
||||
*/
|
||||
export interface FrozenQrCase {
|
||||
name: string
|
||||
text: string
|
||||
ecc: QrEcc
|
||||
version: number
|
||||
size: number
|
||||
rows: string[]
|
||||
}
|
||||
|
||||
export const FROZEN_QR_CASES: FrozenQrCase[] = [
|
||||
{
|
||||
name: '最小码 · 单字节',
|
||||
text: 'a',
|
||||
ecc: 'M',
|
||||
version: 1,
|
||||
size: 21,
|
||||
rows: [
|
||||
'111111100101101111111',
|
||||
'100000101011001000001',
|
||||
'101110101101001011101',
|
||||
'101110101011001011101',
|
||||
'101110100100101011101',
|
||||
'100000100011001000001',
|
||||
'111111101010101111111',
|
||||
'000000001100000000000',
|
||||
'100000101011011001110',
|
||||
'100110000001110111001',
|
||||
'001011100110101100000',
|
||||
'010101011001111101010',
|
||||
'110100111101111111111',
|
||||
'000000001100100000101',
|
||||
'111111100111010011110',
|
||||
'100000100010001000111',
|
||||
'101110100111010011100',
|
||||
'101110100101111101000',
|
||||
'101110100101110111011',
|
||||
'100000100011111101000',
|
||||
'111111101010100100110',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '大屏链接（M）',
|
||||
text: 'http://192.168.1.23:19540/display',
|
||||
ecc: 'M',
|
||||
version: 3,
|
||||
size: 29,
|
||||
rows: [
|
||||
'11111110100101110100101111111',
|
||||
'10000010111011110001001000001',
|
||||
'10111010101101100001001011101',
|
||||
'10111010001100110111001011101',
|
||||
'10111010111001010101101011101',
|
||||
'10000010001001100100101000001',
|
||||
'11111110101010101010101111111',
|
||||
'00000000000010100011100000000',
|
||||
'10011111101001111111110010111',
|
||||
'11011100101010100001110010110',
|
||||
'00101010011000100110100010100',
|
||||
'01111001101100110111000110001',
|
||||
'00110010000011101010011000001',
|
||||
'01100100100000000110111011011',
|
||||
'10111110110100110101110001101',
|
||||
'10101101001011101001101100101',
|
||||
'11101011010000001000010100000',
|
||||
'11001001100100010111000111110',
|
||||
'11110011011011110101100100001',
|
||||
'11000101001001000010101011100',
|
||||
'11000011001011011101111111110',
|
||||
'00000000100101010111100011000',
|
||||
'11111110101001010111101011000',
|
||||
'10000010110101000100100010011',
|
||||
'10111010101011001001111110011',
|
||||
'10111010110111111001000101101',
|
||||
'10111010010010111110100010011',
|
||||
'10000010011100101000001110101',
|
||||
'11111110110010111000100101000',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '大屏链接（L）',
|
||||
text: 'http://192.168.1.23:19540/display',
|
||||
ecc: 'L',
|
||||
version: 3,
|
||||
size: 29,
|
||||
rows: [
|
||||
'11111110111101110100101111111',
|
||||
'10000010000111110001001000001',
|
||||
'10111010010101100001001011101',
|
||||
'10111010001100110111001011101',
|
||||
'10111010001111010101101011101',
|
||||
'10000010010101100100101000001',
|
||||
'11111110101010101010101111111',
|
||||
'00000000110010100011100000000',
|
||||
'11011010010011111111101000001',
|
||||
'11110101001000100001110010110',
|
||||
'11010110110010100110100010100',
|
||||
'11101000100000110111000110001',
|
||||
'01000011111001101010011000001',
|
||||
'11001000101010000110111011011',
|
||||
'00011110001000110101110001101',
|
||||
'00100101110011101001101100101',
|
||||
'00111011010110001000010100000',
|
||||
'10100101011100010111000111110',
|
||||
'11110011110011110101100100001',
|
||||
'11101001101101000010101011100',
|
||||
'11101010001101011101111111110',
|
||||
'00000000110011010111100011000',
|
||||
'11111110001101010111101011000',
|
||||
'10000010011111000100100010011',
|
||||
'10111010110111001001111110011',
|
||||
'10111010100001111001000101101',
|
||||
'10111010000111011110100010011',
|
||||
'10000010110100001000001110101',
|
||||
'11111110110000111000100101000',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '大屏链接（H）',
|
||||
text: 'http://192.168.1.23:19540/display',
|
||||
ecc: 'H',
|
||||
version: 4,
|
||||
size: 33,
|
||||
rows: [
|
||||
'111111100010101110011001101111111',
|
||||
'100000100111110001101111101000001',
|
||||
'101110100111111010011011101011101',
|
||||
'101110100011010000000001001011101',
|
||||
'101110101101010000101010101011101',
|
||||
'100000100010011100000000101000001',
|
||||
'111111101010101010101010101111111',
|
||||
'000000001001000001001001000000000',
|
||||
'001100111111110100101110111010000',
|
||||
'110101010100000110000011111000111',
|
||||
'011110110010010010111001101001101',
|
||||
'100110011001001110111000100110000',
|
||||
'111110101010010001000100100011001',
|
||||
'000101000101100000110100010100000',
|
||||
'000111100110001111010100010100000',
|
||||
'111011001001010010111110110101110',
|
||||
'001100100001101001000100001111101',
|
||||
'100011001110101010010001001010111',
|
||||
'001000111111001000101100100110110',
|
||||
'010101001010001101100010001010010',
|
||||
'011111101110100111011111000101101',
|
||||
'110111011110010010101101001100111',
|
||||
'000111101001011110100001001011101',
|
||||
'011110011111011111111010110100011',
|
||||
'101000111011000111100001111110011',
|
||||
'000000001110011001101100100011010',
|
||||
'111111101100000101111101101011110',
|
||||
'100000100110111011000000100010110',
|
||||
'101110100110001100101011111110101',
|
||||
'101110101000111010101111010100111',
|
||||
'101110101010011111101010011001100',
|
||||
'100000100100110011100100111000001',
|
||||
'111111100011100110100010011111100',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '中文内容',
|
||||
text: '运动会积分榜',
|
||||
ecc: 'M',
|
||||
version: 2,
|
||||
size: 25,
|
||||
rows: [
|
||||
'1111111001101100101111111',
|
||||
'1000001010010110001000001',
|
||||
'1011101000110011001011101',
|
||||
'1011101001011101001011101',
|
||||
'1011101010001111101011101',
|
||||
'1000001000101010001000001',
|
||||
'1111111010101010101111111',
|
||||
'0000000001011000100000000',
|
||||
'1010101001010000100010010',
|
||||
'0100100101001100111011000',
|
||||
'1110001100001011111000100',
|
||||
'0011010100100110101110101',
|
||||
'0110001011010010100110010',
|
||||
'0000000111110011011110001',
|
||||
'1001111100100101111011100',
|
||||
'0110100010110001001011110',
|
||||
'1011101010001001111110100',
|
||||
'0000000010111101100011111',
|
||||
'1111111000111010101010010',
|
||||
'1000001000101111100011111',
|
||||
'1011101010110011111110001',
|
||||
'1011101001110010011011100',
|
||||
'1011101010000101100000101',
|
||||
'1000001001110001101100110',
|
||||
'1111111011101001010110011',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '中英混排 + 链接',
|
||||
text: '2026 职工运动会 · 局域网大屏 http://192.168.1.23:19540/display',
|
||||
ecc: 'M',
|
||||
version: 5,
|
||||
size: 37,
|
||||
rows: [
|
||||
'1111111001110101101011010110001111111',
|
||||
'1000001001111011000101101101001000001',
|
||||
'1011101011011111010110100100001011101',
|
||||
'1011101011000001111100001101001011101',
|
||||
'1011101010001101001110110001001011101',
|
||||
'1000001010000001101111011100101000001',
|
||||
'1111111010101010101010101010101111111',
|
||||
'0000000010001000000001101011100000000',
|
||||
'1011111000011101001010101101101111100',
|
||||
'1011000101010101100001110110010001110',
|
||||
'0110001010011000000011000001011011101',
|
||||
'0100100100110100111000110100111111001',
|
||||
'1100101010001100111011011110000011101',
|
||||
'0100010100111010111001011100110111010',
|
||||
'1101101010101111010110000100001001101',
|
||||
'0100100110001111011011110001011111001',
|
||||
'0110001001110100100100101101001010101',
|
||||
'1010010110010001001011111010010000110',
|
||||
'0101111000110001110101001011111010101',
|
||||
'0001000110010001010110001101010001000',
|
||||
'1010111011000101010110100101100001101',
|
||||
'1000000111010110101101011011000010010',
|
||||
'0100111100011011001111011000111101111',
|
||||
'0100110001000001000111011010100001001',
|
||||
'0011111111001101001000100100101111111',
|
||||
'1000110101111001100001011110010000110',
|
||||
'1011001101000100000011101011011100101',
|
||||
'1011100001111100110000100100111011011',
|
||||
'1001101100011010011101001000111110100',
|
||||
'0000000010000000010110100110100011010',
|
||||
'1111111001001101110111111000101011011',
|
||||
'1000001010110100111111001011100010101',
|
||||
'1011101011101110100110100100111111111',
|
||||
'1011101010000011001110011111010001001',
|
||||
'1011101010110001101010100101100010011',
|
||||
'1000001001000111010000100001100001001',
|
||||
'1111111010110111001011001101001010111',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '版本 4 满容量边界',
|
||||
text: 'http://192.168.1.23:19540/display?k=0123456',
|
||||
ecc: 'M',
|
||||
version: 4,
|
||||
size: 33,
|
||||
rows: [
|
||||
'111111100001101010010111101111111',
|
||||
'100000100100000110101100101000001',
|
||||
'101110101110001000000111001011101',
|
||||
'101110101011000100100100101011101',
|
||||
'101110101101001111001010001011101',
|
||||
'100000101001100000110101101000001',
|
||||
'111111101010101010101010101111111',
|
||||
'000000001101100010011101000000000',
|
||||
'101111100001111011111001001111100',
|
||||
'110110001111110011010001111101111',
|
||||
'011000111000011111000010000010100',
|
||||
'111100010101110101110000101011110',
|
||||
'111110110010001010011110100011001',
|
||||
'010011010001100100100000111101011',
|
||||
'000000110001000110001010100001010',
|
||||
'111110000101100100000101010101100',
|
||||
'000000110111010101101000000110001',
|
||||
'000001000000110010010111111101111',
|
||||
'010010111110101100101100100010110',
|
||||
'000000001011110110010111011011110',
|
||||
'000010111001011100100101000011000',
|
||||
'101000010100101110001111111100001',
|
||||
'101110111010111000010100001101010',
|
||||
'101111011010111010111110010100111',
|
||||
'101011101011001001111000111111001',
|
||||
'000000001110010011010000100010101',
|
||||
'111111100011011111000011101010110',
|
||||
'100000101101001011110000100010100',
|
||||
'101110101001111010001110111111011',
|
||||
'101110101110010100100000000111001',
|
||||
'101110101100111110101010111101100',
|
||||
'100000100010010100100101010110100',
|
||||
'111111101110111101101000100111010',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '版本 8 满容量边界',
|
||||
text: 'http://192.168.1.23:19540/display?k=0123456789abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmnopqrstuvwxyz0123456789abcde',
|
||||
ecc: 'M',
|
||||
version: 8,
|
||||
size: 49,
|
||||
rows: [
|
||||
'1111111001101011011010011111110010100100101111111',
|
||||
'1000001000010010000110101000101111010011101000001',
|
||||
'1011101010010100111011101010100111000001101011101',
|
||||
'1011101011011101100001010100011100011001001011101',
|
||||
'1011101011110100000111111110001111011100001011101',
|
||||
'1000001011100010100010100010010111100010001000001',
|
||||
'1111111010101010101010101010101010101010101111111',
|
||||
'0000000010101100100110100010110011100001000000000',
|
||||
'1011111000101110101110111110000101011011001111100',
|
||||
'1001010111010011100001100100111100010100111010010',
|
||||
'0111001110001011010001110111000111111011100001001',
|
||||
'1100100100001011011101010101101111110100110111000',
|
||||
'1000001010110010010100111000001001101001110000101',
|
||||
'0011010111011100000001011101011100000100001000010',
|
||||
'1110111101110001100100000110010001110010100010111',
|
||||
'0010010010111111111001010100001101011001011111001',
|
||||
'0000111011100100011110011011011000001101110000100',
|
||||
'0000100100001011100001110100001101011000001010010',
|
||||
'1010101101010101011110011111011000001100010101001',
|
||||
'0100010010101010001001000000111010100111000010000',
|
||||
'0100101000011110011110111100011101111010111000111',
|
||||
'1010110010111110110001101001001011001001011011010',
|
||||
'1110111111100001100101111110010110100110111110101',
|
||||
'0010100010000011000000100010110011100001100011010',
|
||||
'1001101011111101011111101010010100011111101010101',
|
||||
'1001100010100000101000100011111000000100100010010',
|
||||
'0011111111001000110100111111010111111011111110001',
|
||||
'1000010001000111111111110101101111100101000011011',
|
||||
'0001111011000110110001011000011000101101101010101',
|
||||
'1111010001100110001111001110111010001101110101100',
|
||||
'0011111000000011111010011100110011100011011101011',
|
||||
'1000100101111101000110101111010000101110100001010',
|
||||
'0011111010010110110110110100100111110011010110100',
|
||||
'1011100011001111011000011101110010100110010000010',
|
||||
'0011011100011000100011101100101111010001001111001',
|
||||
'1010010101001011010000000110111011000000110100011',
|
||||
'1100111110011100001110110100001101111101100110111',
|
||||
'0110100000001111010001111110101101010001001000010',
|
||||
'0100011111011100000000100101010110111110101101001',
|
||||
'0111000101111001001000011110101011100100010101000',
|
||||
'1110001010101101000111111110001101111001111110101',
|
||||
'0000000011110110011000100010011110011100100010010',
|
||||
'1111111000000100001111101011010011111011101011101',
|
||||
'1000001011010100000011100011101110110101100011001',
|
||||
'1011101011111010101101111111000001001011111110101',
|
||||
'1011101011101000010000100111011110000101101111110',
|
||||
'1011101011100011010101011011010001111010011000011',
|
||||
'1000001001110000011000001110001101011001011000001',
|
||||
'1111111011101011000111001001011000001100000001111',
|
||||
],
|
||||
},
|
||||
{
|
||||
name: '长链接',
|
||||
text: 'http://192.168.100.200:65535/display',
|
||||
ecc: 'M',
|
||||
version: 3,
|
||||
size: 29,
|
||||
rows: [
|
||||
'11111110010001101101101111111',
|
||||
'10000010110110111001001000001',
|
||||
'10111010001011101010101011101',
|
||||
'10111010010101101001101011101',
|
||||
'10111010110010110001101011101',
|
||||
'10000010011101011011001000001',
|
||||
'11111110101010101010101111111',
|
||||
'00000000001101110101000000000',
|
||||
'10101010001000101110000010010',
|
||||
'11110100000010101110001101001',
|
||||
'00101010111011001000111110111',
|
||||
'01110001000110011110011101010',
|
||||
'11000010010000011110001101011',
|
||||
'10101101111111001110001101101',
|
||||
'10110110111010101000100000011',
|
||||
'00100101100011110110110011010',
|
||||
'11000011011000100111101000011',
|
||||
'00100100111000101110011100101',
|
||||
'10101111100101000110110001011',
|
||||
'01110101001110000111011101010',
|
||||
'10100111001010000110111110000',
|
||||
'00000000110111001110100010111',
|
||||
'11111110001000100001101011011',
|
||||
'10000010010101110111100011010',
|
||||
'10111010101100111110111111011',
|
||||
'10111010010000101001010011011',
|
||||
'10111010100001101100110011101',
|
||||
'10000010001101011110110001010',
|
||||
'11111110110101001100111001011',
|
||||
],
|
||||
},
|
||||
]
|
||||
@@ -0,0 +1,164 @@
|
||||
import { test } from 'node:test'
|
||||
import assert from 'node:assert/strict'
|
||||
import { ECC_LEVELS, encodeQr, qrByteCapacity, qrMatrixToRows, qrToSvg } from '../qrcode'
|
||||
import type { QrEcc } from '../qrcode'
|
||||
import { FROZEN_QR_CASES } from './qrcode-frozen'
|
||||
|
||||
/**
|
||||
* 二维码编码器的规格验证。
|
||||
*
|
||||
* 真正确认「能扫」的是 cv2（见任务报告里逐条的解码输出）；这里钉的是规格结构与几何：
|
||||
* 版本↔边长、三个定位图案、静区、纠错分块随级别变化，以及一组 cv2 解过的冻结矩阵。
|
||||
* 冻结矩阵一红就说明编码结果变了——那怕只差一位，也可能让现场扫码失败。
|
||||
*/
|
||||
|
||||
/** 定位图案 7×7 的标准样子（外框 + 中心 3×3）。 */
|
||||
const FINDER = ['1111111', '1000001', '1011101', '1011101', '1011101', '1000001', '1111111']
|
||||
|
||||
function rowsAt(matrix: boolean[][], x0: number, y0: number): string[] {
|
||||
const out: string[] = []
|
||||
for (let y = 0; y < 7; y++) {
|
||||
let row = ''
|
||||
for (let x = 0; x < 7; x++) row += matrix[y0 + y]![x0 + x] ? '1' : '0'
|
||||
out.push(row)
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
test('边长与版本一一对应（size = version * 4 + 17）', () => {
|
||||
for (const text of ['a', 'http://192.168.1.23:19540/display', 'x'.repeat(200)]) {
|
||||
const matrix = encodeQr(text)
|
||||
assert.equal(matrix.size, matrix.version * 4 + 17)
|
||||
assert.equal(matrix.modules.length, matrix.size)
|
||||
assert.ok(matrix.modules.every((row) => row.length === matrix.size))
|
||||
}
|
||||
})
|
||||
|
||||
test('自动选版：更长的内容不会用更小的版本', () => {
|
||||
let previous = 0
|
||||
for (const length of [1, 10, 30, 60, 120, 300, 700, 1200]) {
|
||||
const version = encodeQr('u'.repeat(length)).version
|
||||
assert.ok(version >= previous, `长度 ${length} 选出的版本 ${version} 比上一档 ${previous} 还小`)
|
||||
assert.ok(version >= 1 && version <= 40)
|
||||
previous = version
|
||||
}
|
||||
})
|
||||
|
||||
test('三个角上都有标准定位图案，且周围是浅色分隔区', () => {
|
||||
const matrix = encodeQr('http://192.168.1.23:19540/display')
|
||||
const size = matrix.size
|
||||
assert.deepEqual(rowsAt(matrix.modules, 0, 0), FINDER)
|
||||
assert.deepEqual(rowsAt(matrix.modules, size - 7, 0), FINDER)
|
||||
assert.deepEqual(rowsAt(matrix.modules, 0, size - 7), FINDER)
|
||||
|
||||
// 分隔区：定位图案外侧第 8 行/列必须是浅色，否则扫不出来。
|
||||
for (let i = 0; i < 8; i++) {
|
||||
assert.equal(matrix.modules[7]![i], false)
|
||||
assert.equal(matrix.modules[i]![7], false)
|
||||
assert.equal(matrix.modules[7]![size - 1 - i], false)
|
||||
assert.equal(matrix.modules[size - 8]![i], false)
|
||||
}
|
||||
})
|
||||
|
||||
test('右下角没有定位图案（四角定位是另一种码型）', () => {
|
||||
const matrix = encodeQr('http://192.168.1.23:19540/display')
|
||||
const size = matrix.size
|
||||
assert.notDeepEqual(rowsAt(matrix.modules, size - 7, size - 7), FINDER)
|
||||
})
|
||||
|
||||
test('纠错级别越高，同样内容的版本不会更小', () => {
|
||||
const text = 'http://192.168.1.23:19540/display'
|
||||
const versions = ECC_LEVELS.map((ecc) => encodeQr(text, { ecc }).version)
|
||||
for (let i = 1; i < versions.length; i++) {
|
||||
assert.ok(versions[i]! >= versions[i - 1]!, `${ECC_LEVELS[i]} 的版本 ${versions[i]} 小于 ${ECC_LEVELS[i - 1]} 的 ${versions[i - 1]}`)
|
||||
}
|
||||
assert.equal(versions.length, 4)
|
||||
})
|
||||
|
||||
test('M 与 L 两档都能编，且容量 M < L', () => {
|
||||
assert.ok(qrByteCapacity('M') < qrByteCapacity('L'))
|
||||
assert.ok(qrByteCapacity('M') > 0)
|
||||
})
|
||||
|
||||
test('刚好塞满某版本的内容仍在那一版，再多一字节就升版', () => {
|
||||
// 逐档找出「版本切换点」，确认边界两侧的版本判定刚好差一级。
|
||||
for (const ecc of ['L', 'M'] as const) {
|
||||
let previous = encodeQr('a', { ecc }).version
|
||||
const transitions: Array<[number, number]> = []
|
||||
for (let length = 2; length <= 1500 && transitions.length < 5; length++) {
|
||||
const version = encodeQr('a'.repeat(length), { ecc }).version
|
||||
if (version !== previous) transitions.push([length, version])
|
||||
previous = version
|
||||
}
|
||||
assert.ok(transitions.length >= 5, `${ecc} 档没找到足够的版本切换点`)
|
||||
for (const [length, version] of transitions) {
|
||||
assert.equal(encodeQr('a'.repeat(length), { ecc }).version, version)
|
||||
assert.equal(encodeQr('a'.repeat(length - 1), { ecc }).version, version - 1)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
test('内容超出第 40 版容量时抛 RangeError，而不是画一张废码', () => {
|
||||
const tooLong = 'x'.repeat(qrByteCapacity('M') + 1)
|
||||
assert.throws(() => encodeQr(tooLong), RangeError)
|
||||
})
|
||||
|
||||
test('UTF-8 多字节按字节计容量（中文一字 3 字节）', () => {
|
||||
assert.equal(encodeQr('a').version, 1)
|
||||
// 同一个版本里，中文能放的「字数」必然少于 ASCII。
|
||||
const ascii = encodeQr('a'.repeat(17)).version
|
||||
const chinese = encodeQr('中'.repeat(17)).version
|
||||
assert.ok(chinese >= ascii)
|
||||
})
|
||||
|
||||
test('冻结参照：cv2 解过的矩阵逐行一致', () => {
|
||||
assert.equal(FROZEN_QR_CASES.length, 9)
|
||||
for (const reference of FROZEN_QR_CASES) {
|
||||
const matrix = encodeQr(reference.text, { ecc: reference.ecc as QrEcc })
|
||||
assert.equal(matrix.version, reference.version, `${reference.name} 版本变了`)
|
||||
assert.equal(matrix.size, reference.size, `${reference.name} 边长变了`)
|
||||
assert.deepEqual(qrMatrixToRows(matrix), reference.rows, `${reference.name} 矩阵变了`)
|
||||
}
|
||||
})
|
||||
|
||||
test('qrToSvg：viewBox / 尺寸按规模与静区算，含白底 rect 与深色 path', () => {
|
||||
const matrix = encodeQr('http://192.168.1.23:19540/display')
|
||||
const svg = qrToSvg('http://192.168.1.23:19540/display', { scale: 4, margin: 4 })
|
||||
const side = matrix.size + 8
|
||||
|
||||
assert.match(svg, /^<svg /)
|
||||
assert.match(svg, /<\/svg>$/)
|
||||
assert.match(svg, new RegExp(`viewBox="0 0 ${side} ${side}"`))
|
||||
assert.match(svg, new RegExp(`width="${side * 4}"`))
|
||||
assert.match(svg, new RegExp(`height="${side * 4}"`))
|
||||
assert.match(svg, /<rect [^>]*fill="#FFFFFF"/)
|
||||
assert.match(svg, /<path [^>]*fill="#000000"/)
|
||||
// 深色模块数与 path 里的子路径数一一对应，不能多画也不能少画。
|
||||
const dark = matrix.modules.reduce((sum, row) => sum + row.filter(Boolean).length, 0)
|
||||
const segments = svg.match(/M\d+ \d+h1v1h-1z/g) ?? []
|
||||
assert.equal(segments.length, dark)
|
||||
})
|
||||
|
||||
test('qrToSvg：静区可调，默认 4；scale 只放大不改变模块数', () => {
|
||||
const size = encodeQr('a').size
|
||||
const defaultSvg = qrToSvg('a')
|
||||
assert.match(defaultSvg, new RegExp(`viewBox="0 0 ${size + 8} ${size + 8}"`))
|
||||
assert.match(defaultSvg, new RegExp(`width="${(size + 8) * 4}"`))
|
||||
|
||||
const tight = qrToSvg('a', { margin: 2, scale: 10 })
|
||||
assert.match(tight, new RegExp(`viewBox="0 0 ${size + 4} ${size + 4}"`))
|
||||
assert.match(tight, new RegExp(`width="${(size + 4) * 10}"`))
|
||||
})
|
||||
|
||||
test('qrToSvg：SVG 里的文本按 XML 转义，不破坏属性', () => {
|
||||
const svg = qrToSvg('http://x/?a=1&b="2"')
|
||||
const label = svg.match(/aria-label="([^"]*)"/)?.[1] ?? ''
|
||||
assert.equal(label, '扫码打开 http://x/?a=1&b="2"')
|
||||
// 剩下的 & 只能作为实体开头，且不能有裸的 < >，否则属性会被提前截断。
|
||||
assert.doesNotMatch(label, /&(?!(amp|lt|gt|quot|#\d+);)/)
|
||||
assert.doesNotMatch(label, /[<>]/)
|
||||
})
|
||||
|
||||
test('ecc 非法时明确报错，不静默退回默认级别', () => {
|
||||
assert.throws(() => encodeQr('a', { ecc: 'X' as QrEcc }), RangeError)
|
||||
})
|
||||
@@ -123,9 +123,11 @@ test('同一个客户端上，普通接口仍按默认超时被掐断', async ()
|
||||
)
|
||||
})
|
||||
|
||||
test('导出接口只保留「存文件」，恢复接口只保留 restore', () => {
|
||||
test('导出接口只保留「存文件」，恢复接口只保留 restore / network', () => {
|
||||
const client = new ApiClient({ fetchImpl: async () => jsonResponse({ ok: true, data: null }) })
|
||||
|
||||
assert.deepEqual(Object.keys(client.exports), ['save'])
|
||||
assert.deepEqual(Object.keys(client.system), ['restore'])
|
||||
// system 这一组是有意收窄的：只放「不属于任何业务实体」的本机能力。
|
||||
// network 是本机局域网地址（GET /api/system/network），给大屏控制页拼地址用。
|
||||
assert.deepEqual(Object.keys(client.system), ['restore', 'network'])
|
||||
})
|
||||
@@ -673,6 +673,30 @@ export interface HealthInfo {
|
||||
version: string
|
||||
}
|
||||
|
||||
/** 本机的一个局域网地址（GET /api/system/network）。 */
|
||||
export interface NetworkAddress {
|
||||
/** 形如 `192.168.1.23`；服务端只回可用地址，回环不会被列进来。 */
|
||||
ip: string
|
||||
/** 网卡名，如 `eth0` / `wlan0` / Windows 的 `WLAN`。 */
|
||||
interface: string
|
||||
/** 地址族，当前只有 `ipv4` 会被列出（大屏地址是 IPv4 点分十进制）。 */
|
||||
family: string
|
||||
}
|
||||
|
||||
/**
|
||||
* 本机网络信息（`GET /api/system/network`，recorder 及以上可读）。
|
||||
*
|
||||
* 「局域网大屏」卡片直接用这里回的端口与路径拼地址，不在前端硬编码：
|
||||
* 现场改过端口或把大屏挂在子路径下时，卡片要跟着变。
|
||||
* 拿不到任何可用地址时 `addresses` 为空数组（没插网线 / 只有回环），不是错误。
|
||||
*/
|
||||
export interface NetworkInfo {
|
||||
port: number
|
||||
displayPath: string
|
||||
adminPath: string
|
||||
addresses: NetworkAddress[]
|
||||
}
|
||||
|
||||
/** 数据目录 `event_projs/` 下的一个赛事项目（GET /api/projects，admin）。 */
|
||||
export interface ProjectInfo {
|
||||
name: string
|
||||
|
||||
Reference in new issue
Block a user