feat: 字体可配并随赛事包打包 + 大屏调试标识收敛 + 报名表 CSV 编码兼容
三块改动，均为现场反馈：
一、字体配置与随包打包（此前「没有入口可以配置字体」，导出包也不带字体）
- 服务端新增 httpapi/fonts.go 与 4 条路由：GET /api/fonts（recorder）、
POST /api/fonts（admin，multipart file）、DELETE /api/fonts/{name}（admin）、
GET /uploads/fonts/{name}（匿名——大屏 @font-face 不带会话）
- 上传限 ttf/otf/woff/woff2、单个 20 MiB；文件名经 safeFontName 收敛且需与
fontContentType 往返一致，挡住路径穿越；重名 409、删除被引用字体 409
- 新增设置键 display.font_title / display.font_body（DTO fontTitle/fontBody，
随快照下发给大屏），写入时校验取值合法
- 导出：接上一直没被赋值的 IncludeFonts/FontsDir；包内落点用 uploads/fonts/
（运行时只读这里，落顶层 fonts/ 等于没人读）
- 大屏按配置动态注册字体并挂 --display-font-title/body，加载失败静默回落默认字体
- 管理端「赛事信息」新增字体区块：标题/正文字体下拉、上传、字体库、实时预览
二、大屏显示收敛
- 数据版本号角标 vN 彻底移除（原先只有窗口化窗口会显示，两处显隐口径不一致）
- 窗口化窗口按 F11 全屏后自绘标题栏不让位：根因是 Console 用 win.setFullScreen()
做窗口级全屏，而页面用 document.fullscreenElement 判断，后者恒为 null；
新增 display-preload.js 下发窗口级全屏状态，页面侧 shell.ts 把两级全屏取或，
无 preload 时（浏览器直连 /display）回落到文档级监听
三、报名表 CSV 编码兼容（用户报「解析中文字符遇到编码问题」）
- 服务端不再把原始字节直接喂给 csv.Reader：先摘 UTF-8 BOM，再认 UTF-16 LE/BE
BOM，其余非合法 UTF-8 按 GB18030 解（GBK 是其子集）
- 修复前症状：GBK 文件（Excel 另存为 CSV 的默认编码）中文变乱码；带 BOM 的文件
（Excel「CSV UTF-8」，也正是我们自己模板的格式）把 BOM 拼进第一列表头，
报「报名表缺少列 event_code」——连「下载模板→填→传回来」都走不通
- golang.org/x/text 由 indirect 提升为直接依赖，未新增外部依赖
测试：服务端 12 包全绿（新增 fonts_test.go / fonts_internal_test.go /
handlers_import_encoding_test.go）；前端 vue-tsc 通过、pnpm build 通过、157 例全过；
Console 语法检查 17 个文件通过。docs/ 与 devdocs/ 同步更新。
This commit is contained in:
AskaEth committed
1 parent
9c6d0bd3b3
commit
fc96d17660
42 files changed
+2451
-95
No files matched your search
+3
-2
@@ -34,6 +34,7 @@
|
||||
|
||||
- [ ] 「系统设置 → 赛事信息」的**基本信息**：填名称、副标题、主办方，上传**赛事会标**
|
||||
- [ ] 同页的**大屏配置**：上传大屏会标、选大屏背景图，填大屏标题 / 副标题、轮播间隔与主题色（上传的图片随赛事项目包一起导出/导入）
|
||||
- [ ] 同页的**字体**：确认**标题字体**与**正文字体**已选好（默认、四款内置字体，或自己上传的字体）；选完点「保存」，并核对大屏上标题与正文显示正常。上传的字体存在赛事项目的 `uploads\fonts\` 里，**导出赛事项目包会一并带走、导入后不用重新上传**（见使用手册 14.3、部署指南 8.5）
|
||||
- [ ] **赛事项目确认 / 导入**：到「导出 → 赛事项目包」核对**赛事项目列表**里带「当前」徽标的是本次要用的赛事；需要换赛事时先「导入 .zip」，再点「切换为当前赛事」（服务端会重启一次，页面显示「正在重启服务端…」，恢复后自动刷新）。账号与会话在数据目录的 `system.db` 里，**不受切换影响**，一般不用重新登录。这一步做完再往下走，否则后面看到的是别的赛事的数据
|
||||
- [ ] **导入规则包**：`%LOCALAPPDATA%\ScoreboardConsole\rules\2026-驭电利刃杯军事运动会.yaml`，走「导出 → 规则包 → 选择 YAML → 预览差异 → 确认导入并全量重算」（规则目录在用户数据目录里，见部署指南 3.5）
|
||||
—— 服务端不会自动加载规则包，必须导入一次
|
||||
@@ -47,7 +48,7 @@
|
||||
- [ ] 确认大屏锁定在「积分榜」页面；需要轮播就在后台开启
|
||||
- [ ] 鼠标移到大屏上应看不到操作按钮；大屏窗口已开防熄屏
|
||||
- [ ] 只有一块屏时是窗口化模式，按 **F11** 可切全屏（用于单屏测试）
|
||||
- [ ] **调试标识已隐藏**：多屏 kiosk 全屏画面上不该出现「实例 … · 屏 …」与版本号角标；窗口化窗口（单屏）里显示这两个属正常，按 F11 全屏后「实例 · 屏」隐藏、版本号角标仍在
|
||||
- [ ] **调试标识已隐藏**：多屏 kiosk 全屏画面上不该出现「实例 … · 屏 …」；窗口化窗口（单屏）里显示这一行属正常，按 F11 全屏后它与自绘标题栏一起消失（版本号角标已移除，任何画面都不该出现）
|
||||
- [ ] **显示器菜单可用**：在服务管理窗口里点「打开服务端管理面板」，进「大屏控制 → 显示器」，能看到每块屏；副屏点「创建全屏窗口」能重新开出来（单屏 / 主显示器只能窗口化，属正常）
|
||||
- [ ] **公告可用**：推送一条测试公告 → 大屏全屏显示 → 到时退回原页且**底栏公告栏仍常驻显示正文** → 点「清除公告」后底栏回到「暂无公告」
|
||||
|
||||
@@ -55,7 +56,7 @@
|
||||
|
||||
- [ ] 确认数据目录 `%LOCALAPPDATA%\ScoreboardConsole\data` 下的 `backups\` 里已出现 `system-auto-*.db` 与 `event-auto-*.db`（默认每 5 分钟）
|
||||
- [ ] 开幕前手动点一次「立即备份」（「系统设置 → 备份 → 立即备份」）
|
||||
- [ ] 把整个数据目录（不只是 `backups\`：`event_projs\<当前项目名>\uploads\` 里还有会标、背景图与单位 logo）拷一份到 U 盘
|
||||
- [ ] 把整个数据目录（不只是 `backups\`：`event_projs\<当前项目名>\uploads\` 里还有会标、背景图、单位 logo 与上传的字体）拷一份到 U 盘
|
||||
|
||||
## 7. 现场流程演练（建议至少一次）
|
||||
|
||||
|
||||
+32
-4
@@ -359,6 +359,7 @@
|
||||
4. 都没匹配到则新建人员（姓名、性别、年龄、单位、证件号、号码布）；
|
||||
5. `bib` 列会同时写入人员档案与报名记录；从已有名单勾选生成的报名也会带上人员的证件号（优先）或号码布；
|
||||
6. 把 `.csv` 或 `.xlsx` 拖入虚线框，或点击选择文件（单个文件不超过 16MB；xlsx 只解析第一个工作表）；
|
||||
- **CSV 编码不用管**：UTF-8、带 BOM 的 UTF-8（Excel 的「CSV UTF-8」）、GBK / GB18030（中文 Windows 上 Excel「另存为 CSV」的默认编码）、UTF-16 都能直接导入，中文不会乱码，服务端会自动识别；
|
||||
7. 点「开始导入」，页面显示**新增 / 更新 / 跳过**数量；匹配不到的行会跳过并回显行号，修正后可重新上传。
|
||||
|
||||
**人员信息冲突的处理**
|
||||
@@ -403,7 +404,7 @@
|
||||
- 每行的「切换为当前赛事」用于切换（仅管理员），切换过程见下面「导入后怎样才算生效」；
|
||||
- 列表里出现「缺 event.db」的项目不可切换，说明该目录不是完整的赛事包。
|
||||
|
||||
**导出 zip**：包内含 `meta.yaml`、`event.db`、`uploads/`、`rules.yaml`，整包拷走即可在另一台机器复现整场赛事。
|
||||
**导出 zip**：包内含 `meta.yaml`、`event.db`、`uploads/`、`rules.yaml`，整包拷走即可在另一台机器复现整场赛事。`uploads/` 里除了会标、背景图与单位 logo，还包含**上传到赛事信息里的字体**（在 `uploads/fonts/` 下），字体设置也随赛事库一起走，导入后不用重新上传字体。
|
||||
|
||||
**导入 zip**（仅管理员）：选择 `.zip`，可填「重命名」，勾选「覆盖同名项目」会先二次确认。导入只把数据解到数据目录，**不会自动切换当前赛事**，所以导入完成后页面会提示「已导入为 xxx，但它还不是当前赛事」。
|
||||
|
||||
@@ -490,10 +491,32 @@
|
||||
| 主题色 | 大屏主色，如 `#3482FF` |
|
||||
| 个人积分榜上屏 | 开关；关闭后大屏不展示个人积分榜 |
|
||||
| 个人榜奖牌列 | 开关，默认展示；关闭后个人积分榜不显示金 / 银 / 铜三列 |
|
||||
| 标题字体 / 正文字体 | 下拉选择，分别作用于大屏标题与大屏正文；第一项是「默认（跟随系统）」，之后是四款内置字体与已上传的字体。只影响大屏画面，管理端界面字体不变 |
|
||||
| 字体库 | 「上传字体」按钮与已上传字体列表（每行显示字体名与地址，可「删除」） |
|
||||
|
||||
改完点「保存」；未保存时显示「未保存」徽标，点「放弃修改」可还原。
|
||||
|
||||
> 修改大屏标题、主题色等会立即影响所有在线大屏，请避开颁奖或播报时段。
|
||||
**字体区块**
|
||||
|
||||
四款内置字体随程序分发，不用上传：`Noto Sans SC（思源黑体同源）`、`Noto Serif SC（思源宋体同源）`、`MiSans`、`Source Han Sans CN（思源黑体）`。区块底部的「预览」会按当前所选字体实时渲染一行中文，先看效果再保存。
|
||||
|
||||
上传自己的字体：
|
||||
|
||||
1. 在「字体库」点「上传字体」，选择本地字体文件；
|
||||
2. 只支持 `.ttf` / `.otf` / `.woff` / `.woff2`，**单个文件不超过 20 MiB**；格式不符或超过上限会在上传前直接提示；
|
||||
3. 上传成功后，新字体立刻出现在两个下拉里（按文件名显示）；**文件名重复会被拒绝**，需要先删掉旧文件或改名后再传；
|
||||
4. 字体文件落在**当前赛事项目目录的 `uploads/fonts/`** 下，列表里会显示它的地址 `/uploads/fonts/<文件名>`；文件名里的中文会保留，其他特殊字符会被换成下划线。
|
||||
|
||||
选好字体后点「保存」提交：服务端会校验字体是否真实存在，选了无效字体会被拒绝并给出中文提示。保存后大屏按新字体重新渲染；**字体文件加载失败时大屏自动回落到默认字体**，不会出现方块或空白。
|
||||
|
||||
删除已上传的字体：
|
||||
|
||||
1. 在「字体库」列表里点该行的「删除」，二次确认后生效；
|
||||
2. **正在被标题字体或正文字体使用的字体不能删**，会提示「正在被大屏使用，请先在赛事信息里改掉标题/正文字体」：先把下拉改成别的字体并保存，再回来删。
|
||||
|
||||
> 字体文件就在赛事的 `uploads/fonts/` 里，所以**导出赛事项目包会连字体一起带走**，导入后直接可用、不用重新上传；字体设置存在赛事库里，也随包走（见 11.2）。
|
||||
|
||||
> 修改大屏标题、主题色、字体等会立即影响所有在线大屏，请避开颁奖或播报时段。
|
||||
|
||||
---
|
||||
|
||||
@@ -510,7 +533,7 @@
|
||||
|
||||
## 16. 关于
|
||||
|
||||
展示系统名称、版本号、构建时间、运行模式，以及技术栈与开源许可、字体清单、键盘快捷键、部署信息（服务端端口、访问地址、赛事项目名）。
|
||||
展示系统名称、版本号、构建时间、运行模式，以及技术栈与开源许可、字体清单（四款内置字体的用途与授权；给大屏换字体见 14.3）、键盘快捷键、部署信息（服务端端口、访问地址、赛事项目名）。
|
||||
|
||||
---
|
||||
|
||||
@@ -530,6 +553,8 @@
|
||||
|
||||
> 单位 logo 取自「基础数据 → 参赛单位」里上传的图片（见 10.1），按行内文字大小显示，不会撑开行高；没传 logo 的单位不占位，图片临时加载不出来时保留占位、刷新后恢复，队名不会跳动。
|
||||
|
||||
> 大屏的标题字体与正文字体取自「系统设置 → 赛事信息 → 字体」（见 14.3）：可选四款内置字体，也可以上传自己的字体；上传字体加载失败时自动回落到默认字体，画面不会出现方块或空白。
|
||||
|
||||
### 17.2 轮播与锁定
|
||||
|
||||
- Console 启动的多屏大屏窗口默认**每屏锁定一页**，不轮播；
|
||||
@@ -552,7 +577,10 @@
|
||||
|
||||
### 17.5 调试标识
|
||||
|
||||
窗口化（带标题栏的调试窗口）时，右上角会显示「实例 x · 屏 x」与数据版本号 `vN`：前者用来分辨这块屏是哪个实例，后者是**数据版本号**（不是软件版本），和仪表盘「实时连接」里显示的「版本 N」一致，就说明这块屏已经跟上服务端。**kiosk 全屏窗口不显示这些调试标识**，正式上屏的画面是干净的；窗口化窗口按 F11 全屏后，「实例 · 屏」也会一起隐藏。多屏 kiosk 窗口不响应 F11，也不显示任何调试标识与版本号角标。
|
||||
窗口化（带标题栏的调试窗口）**且没有全屏**时，右上角会显示一行「实例 x · 屏 x」，用来分辨这块屏是哪个实例。除此之外没有别的调试标识——**数据版本号 `vN` 角标已经去掉，任何情况下都不再显示**；需要核对某块屏有没有跟上服务端时，用管理端仪表盘「实时连接」里的「版本 N」对照。
|
||||
|
||||
- **kiosk 全屏窗口**（多屏时每屏一个）不显示任何调试标识，正式上屏的画面是干净的；多屏 kiosk 也不响应 F11。
|
||||
- 单屏窗口化窗口按 **F11** 全屏后，自绘标题栏与「实例 · 屏」会一起消失、画面铺满整块屏；再按一次 F11 回到窗口化，标题栏与标识一起回来。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+63
-27
@@ -132,11 +132,10 @@ Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点
|
||||
|
||||
没显示就去「基础数据 → 参赛单位 → 编辑 → Logo 路径」上传或填写该单位的 logo（管理端页面本身不显示 logo，只在大屏上显示）。上传的图片存在该赛事的 `data\event_projs\<项目名>\uploads\` 里，会随赛事项目包一起导出 / 导入。
|
||||
|
||||
**Q27：「实例 x · 屏 x」和右上角的版本号角标怎么不见了？**
|
||||
这两个都只是**调试标识**：只在窗口化的调试窗口里显示，正式上屏（多屏 kiosk 全屏，或单屏窗口化后按 `F11` 全屏）都不显示。
|
||||
**Q27：「实例 x · 屏 x」这个标识怎么不见了？**
|
||||
它只是**调试标识**：只在窗口化的调试窗口里、并且**没有全屏**时显示，用来分辨这块屏是哪个实例。正式上屏（多屏 kiosk 全屏，或单屏窗口化后按 `F11` 全屏）都不显示——按 F11 时它会和自绘标题栏一起收起来，再按一次就回来。
|
||||
|
||||
- 「实例 x · 屏 x」用来分辨这块屏是哪个实例，窗口化后按 F11 全屏也会隐藏；
|
||||
- 角标里的 `vN` 是**数据版本号**（不是软件版本）：需要现场核对某块屏有没有跟上服务端时，先把该窗口切回窗口化让角标出现，它和仪表盘「实时连接」里显示的「版本 N」一致就说明这块屏已经同步。
|
||||
以前右上角还有一个 `vN` 数据版本号角标，**现在已经去掉，任何情况下都不再显示**。要核对某块屏有没有跟上服务端，看管理端仪表盘「实时连接」里的「版本 N」。
|
||||
|
||||
**Q28：「在线看板」为什么显示未知？**
|
||||
页面上那一块是本地占位节点：系统不按「指令送达」推断大屏是否在线，也不展示每块屏的实际上报状态，所以「在线」列恒为未知，卡片上写着「在线状态未知（占位）」；「最近下发」只是本机下发指令的时间，**不代表大屏在线**。以现场大屏的实际画面为准。
|
||||
@@ -147,35 +146,65 @@ Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点
|
||||
**Q30：大屏时间不对怎么办？**
|
||||
系统没有外网时间同步，以主机时间为准。校准 Windows 时间与时区即可。
|
||||
|
||||
**Q31：大屏的字体在哪里改？**
|
||||
在「系统设置 → 赛事信息 → **字体**」区块（需要管理员）：**标题字体**与**正文字体**两个下拉，第一项是「默认（跟随系统）」，后面是四款内置字体与已上传的字体；区块底部的「预览」会按所选字体实时渲染一行中文，选完点页面上的「保存」生效。这两个设置**只影响大屏画面**，管理端界面的字体不变。
|
||||
|
||||
四款内置字体随程序分发，不用上传：`Noto Sans SC（思源黑体同源）`、`Noto Serif SC（思源宋体同源）`、`MiSans`、`Source Han Sans CN（思源黑体）`。
|
||||
|
||||
**Q32：怎么上传自己的字体？**
|
||||
1. 到「系统设置 → 赛事信息 → 字体 → 字体库」，点「上传字体」选择本地字体文件；
|
||||
2. 上传成功后，新字体立刻出现在两个下拉里（按文件名显示，文件名里的中文会保留，其他特殊字符会换成下划线）；
|
||||
3. 在「标题字体」「正文字体」下拉里选上它，再点页面上的「保存」——下拉的改动要保存才生效；
|
||||
4. 字体文件存在当前赛事项目的 `data\event_projs\<项目名>\uploads\fonts\` 里，列表里会显示它的地址 `/uploads/fonts/<文件名>`。
|
||||
|
||||
**Q33：字体支持哪些格式？有大小限制吗？**
|
||||
只支持 `.ttf` / `.otf` / `.woff` / `.woff2`，**单个文件不超过 20 MiB**；格式不符或超过上限，会在上传前就直接提示，不会传到服务端。同一个文件名再传一次会被拒绝（提示「已存在，请先删除或重命名后再上传」），所以换字体请先删掉旧的、或把文件改成别的名字。上传的字体不做格式解析，损坏的文件传得上去，但大屏加载不了会回落到默认字体（见 Q34）。
|
||||
|
||||
**Q34：为什么上传的字体在大屏上没生效？**
|
||||
按这个顺序排查：
|
||||
|
||||
- **保存了吗**：「赛事信息」里的下拉选完要点页面上的「保存」，没保存时页面显示「未保存」徽标；保存时服务端会校验字体是否存在，选了不存在的字体会直接报错；
|
||||
- **看错地方了**：这两个设置只作用于**大屏**，管理端界面的字体不受影响，别拿管理端的显示效果判断；
|
||||
- **字体文件加载失败**：大屏是无人值守的，字体只是外观，加载失败时会**静默回落到默认字体**（不会出现方块或空白）。检查 `data\event_projs\<项目名>\uploads\fonts\` 下的文件是否还在（被手工删掉就会出现这种情况），必要时重新上传并保存一次；
|
||||
- **大屏还没刷新**：保存会立刻下发给在线大屏；仍没变化可以重开大屏窗口，或等大屏自动重载。
|
||||
|
||||
**Q35：为什么删不掉某个字体？**
|
||||
**正在被标题字体或正文字体使用的字体不允许删除**，会提示「正在被大屏使用，请先在赛事信息里改掉标题/正文字体」。先把这两个下拉改成别的字体并**保存**，再回「字体库」点该行的「删除」（会有二次确认，删除前请确认大屏上已不再使用它）。
|
||||
|
||||
**Q36：换一台机器还要重新传字体吗？**
|
||||
不用。字体文件就在当前赛事项目的 `uploads\fonts\` 里，所以**导出赛事项目包（zip）会连字体一起带走**，导入到另一台机器后直接可用、不用重新上传；字体设置存在赛事库里，也随包走（见 Q43）。
|
||||
|
||||
只有一个小陷阱：`backups\` 里的 `.db` 快照**不含**字体这些上传文件（见 Q37），如果只拷数据库快照换机器，字体就没了——记得把 `event_projs\<项目名>\uploads\` 一起拷（见 Q54）。
|
||||
|
||||
---
|
||||
|
||||
## 数据与备份
|
||||
|
||||
**Q31：备份在哪里？**
|
||||
在数据目录下的 `backups\`，默认即 `%LOCALAPPDATA%\ScoreboardConsole\data\backups\`（数据目录改过就按改后的路径找，见 Q48）。
|
||||
**Q37：备份在哪里？**
|
||||
在数据目录下的 `backups\`，默认即 `%LOCALAPPDATA%\ScoreboardConsole\data\backups\`（数据目录改过就按改后的路径找，见 Q54）。
|
||||
|
||||
文件是数据库快照，命名形如 `system-<原因>-<时间戳>.db` 与 `event-<原因>-<时间戳>.db`：`system` 是系统库（账号、会话），`event` 是赛事库（成绩、积分、报名、基础数据），原因是 `auto` / `manual` / `publish`，时间戳是「年月日-时分秒」，例如 `event-publish-20260910-120500.db`。
|
||||
|
||||
> 备份里只有数据库，**上传的图片**（赛事会标、大屏背景图、单位 logo）不在其中，它们在 `data\event_projs\<项目名>\uploads\` 里，需要另外归档。
|
||||
> 备份里只有数据库，**上传的图片与字体**（赛事会标、大屏背景图、单位 logo、自定义字体）不在其中，它们在 `data\event_projs\<项目名>\uploads\` 里（字体在 `uploads\fonts\`），需要另外归档。
|
||||
|
||||
**Q32：多久备份一次？**
|
||||
**Q38：多久备份一次？**
|
||||
服务端会自动备份，默认每 5 分钟一次（`config.yaml` 的 `backup.intervalMinutes`，设成 `0` 可关闭）。也可以手动触发：管理端「系统设置 → 备份 → 立即备份」，或执行 `scoreboard.exe backup -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -data "%LOCALAPPDATA%\ScoreboardConsole\data"`（部署目录下的 `deploy\backup.bat` 已经带好这些路径）。另外每次发布成绩前会自动备一份。
|
||||
|
||||
**Q33：备份会自动删除旧的么？**
|
||||
**Q39：备份会自动删除旧的么？**
|
||||
会。自动、手动、命令行三种方式都按 `backup.keep`（默认 20 份）滚动保留，`system` 库与赛事库各自计算。
|
||||
|
||||
**Q34：怎么恢复备份？**
|
||||
**Q40：怎么恢复备份？**
|
||||
没有一键恢复接口，需停机手工替换数据库文件：在 Console 里停止服务，到 `<数据目录>\event_projs\<项目名>\` 把目标备份复制为 `event.db`（覆盖原文件），删掉同目录的 `event.db-wal` 与 `event.db-shm`，再启动服务，详见 [部署指南 · 备份与恢复](./部署指南.md#8-备份与恢复)。
|
||||
|
||||
**Q35：换一台电脑怎么迁移？**
|
||||
**Q41：换一台电脑怎么迁移？**
|
||||
用户数据目录和安装目录都要带走：
|
||||
|
||||
- **用户数据目录** `%LOCALAPPDATA%\ScoreboardConsole\`（里面是 `data\` + `config.yaml` + `console\config.json` + `rules\`）：整个拷到新机器的同一位置即可，赛事数据、账号、配置、规则包原样接管；
|
||||
- **用户数据目录** `%LOCALAPPDATA%\ScoreboardConsole\`（里面是 `data\` + `config.yaml` + `console\config.json` + `rules\`）：整个拷到新机器的同一位置即可，赛事数据、账号、配置、规则包原样接管，`data\` 里自然也包括上传的图片与字体；
|
||||
- **安装目录**（`Scoreboard_Console.exe`、`scoreboard.exe` 等）：按同样路径放好，或用新机器上的安装包装一遍（安装目录里那几份配置与规则只是模板，拷不拷都行）。
|
||||
|
||||
只拷安装目录会丢数据——成绩、账号、配置、规则包都在用户数据目录里。若数据目录放到了别处，还要同步改 `console\config.json` 的 `server.dataDir`。详见部署指南第 8.4 节。
|
||||
|
||||
**Q36：怎么切换赛事项目？**
|
||||
**Q42：怎么切换赛事项目？**
|
||||
启动时服务端会自动打开**上次打开的赛事**，不用改启动参数。切换在页面里完成：管理面板「导出 → 赛事项目包 → **赛事项目列表**」里找到目标项目（带「当前」徽标的就是正在打开的那一项），点「切换为当前赛事」。服务端会退出并由服务管理窗口自动拉起，页面显示「正在重启服务端…」，恢复后自动刷新；最多等 60 秒，超时就打开服务管理窗口确认服务端状态，待其显示「运行中」后手动刷新本页。
|
||||
|
||||
- 导入赛事包**不会**自动切换当前赛事，导入完成的结果框里直接给了「立即切换并重启服务端」按钮；
|
||||
@@ -189,57 +218,64 @@ Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点
|
||||
|
||||
## 导出与导入
|
||||
|
||||
**Q37：能导出哪些文件？**
|
||||
**Q43：能导出哪些文件？**
|
||||
四类 Excel：总表、全部（多 sheet）、分项成绩表、单位积分明细；另外可导出赛事项目包（zip）与规则包（YAML）。
|
||||
|
||||
**Q38：导出文件保存在哪？**
|
||||
**Q44：导出文件保存在哪？**
|
||||
浏览器默认下载目录。服务端生成的临时包位于 `data\exports\`，下载完成后自动删除。
|
||||
|
||||
**Q39：谁能导入规则包 / 赛事项目包？**
|
||||
**Q45：谁能导入规则包 / 赛事项目包？**
|
||||
只有管理员。两者都会整体替换数据：规则包导入后全量重算积分且不能一键撤销；赛事包覆盖同名项目前会二次确认。
|
||||
|
||||
**Q40：导入赛事包后为什么看不到数据？**
|
||||
**Q46：导入赛事包后为什么看不到数据？**
|
||||
因为导入只把包解到数据目录，**不会自动切换当前赛事**。服务端启动时只打开一个赛事项目（启动参数 `-project` 指定的那个；没带参数时用上次切换记下的，从未切换过则是 `default`），页面上看到的是它的数据——通常是导入前那个空赛事，所以看着像「没导进去」。
|
||||
|
||||
处理办法：在「导出 → 赛事项目包」的**赛事项目列表**里找到刚导入的项目（导入完成的结果框里也直接给了「立即切换并重启服务端」按钮），点「切换为当前赛事」。服务端会退出并由服务管理窗口自动拉起，页面显示「正在重启服务端…」，恢复后自动刷新，数据就出来了。超过 60 秒仍未恢复时，请打开服务管理窗口确认服务端状态，待其显示「运行中」后手动刷新本页。
|
||||
|
||||
> 切换会让服务端重启，比赛进行中请避开操作。账号与会话不在赛事库里（见 Q36），一般不用重新登录；万一回到只读访客视图，登录一次即可，若原密码登不上就用 `scoreboard.exe passwd` 重置。
|
||||
> 切换会让服务端重启，比赛进行中请避开操作。账号与会话不在赛事库里（见 Q42），一般不用重新登录；万一回到只读访客视图，登录一次即可，若原密码登不上就用 `scoreboard.exe passwd` 重置。导入的赛事包里如果带了自定义字体，切换过去后大屏直接可用，不用重新上传（见 Q36）。
|
||||
|
||||
**Q41：导入规则包后积分变了，能撤销吗？**
|
||||
**Q47：导入规则包后积分变了，能撤销吗？**
|
||||
不能一键撤销。纠错需要重新导入旧规则包，或逐项修正后重新发布。导入前请务必先「预览差异」。
|
||||
|
||||
**Q42：导入时提示证件号重复怎么办？**
|
||||
**Q48：导入时提示证件号重复怎么办？**
|
||||
证件号与号码布是人员的两项唯一标识，系统不允许两个人员共用同一个证件号，用来区分重名。
|
||||
|
||||
- **在「运动员」里新增 / 编辑时提示重复**：说明该证件号已属于另一个人员。请先核对是不是同一个人：是，就直接用已有记录；不是，请检查证件号是否填错。已有历史数据可以没有证件号。
|
||||
- **表格导入时出现重复**：分两种情况。同一份文件里同一个证件号重复出现，重复的行会报错并跳过，改好后重新上传；证件号在系统中已存在、但姓名、性别或单位不一致的，会列为「冲突」，本次不写入（报名也不会创建），需要在导入结果里勾选后逐条或多选决定「保留已有数据」还是「使用新数据」，没有做决定的人不会被写入。详细步骤见 [使用手册 · 报名导入](./使用手册.md#107-报名导入)。
|
||||
|
||||
**Q43：人员没有身份证，只有号码布，能报名吗？**
|
||||
**Q49：人员没有身份证，只有号码布，能报名吗？**
|
||||
可以。证件号与号码布二者取其一即可作为人员唯一标识：在「运动员」里只填号码布也能保存；报名表里有姓名的行，`id_card` 与 `bib` 至少填一个就能导入；从已有名单勾选报名时，两项里有一项就能勾选。号码布会同时写入人员档案与报名记录。
|
||||
|
||||
**Q44：号码布重复了怎么办？**
|
||||
**Q50：号码布重复了怎么办？**
|
||||
号码布和证件号一样是人员唯一标识，系统不允许两个人员共用同一个号码布。
|
||||
|
||||
- **在「运动员」里新增 / 编辑时提示重复**：说明该号码布已属于另一个人员。请先核对是不是同一个人：是，就直接用已有记录；不是，请检查号码布是否填错。
|
||||
- **表格导入时出现重复**：同一份文件里同一个号码布重复出现，重复的行会报错并跳过，改好后重新上传；号码布在系统中已存在、但姓名、性别或单位不一致的，会列为「冲突」，本次不写入（报名也不会创建），需要在导入结果里勾选后决定「保留已有数据」还是「使用新数据」。详细步骤见 [使用手册 · 报名导入](./使用手册.md#107-报名导入)。
|
||||
|
||||
**Q51：导入 CSV 时中文变成乱码，或者提示「报名表缺少列 event_code」怎么办？**
|
||||
**不用转码，直接传原文件就行。** 服务端会自己识别编码：UTF-8、带 BOM 的 UTF-8（Excel 的「CSV UTF-8」）、GBK / GB18030（中文 Windows 上 Excel「另存为 CSV」的默认编码）、UTF-16（PowerShell `Export-Csv` 的默认编码）都能正常导入。
|
||||
|
||||
- 这两种症状以前长这样：GBK 文件的中文单位名、运动员名**变成乱码**；带 BOM 的文件报「**报名表缺少列 event_code**」——看着像表头写错，其实是 BOM 粘在了第一列表头上。现在都已修好，两种文件都直接传。
|
||||
- 如果还是报「报名表缺少列 xxx」，那就是表头真的不对：第一行必须是英文列名（`event_code,category,team_code,athlete_name,…`），不能是中文标题行，上面也不要有多余的标题行或合并单元格。最稳妥的做法是下载页面上的「CSV 模板」照着填。
|
||||
- xlsx 不受影响，它自带编码信息。
|
||||
|
||||
---
|
||||
|
||||
## 其他
|
||||
|
||||
**Q45：系统需要联网吗？**
|
||||
**Q52：系统需要联网吗？**
|
||||
不需要。完全离线运行，不依赖外网，也不需要在现场安装任何运行时。
|
||||
|
||||
**Q46：页面提示「示例数据」是什么意思？**
|
||||
**Q53：页面提示「示例数据」是什么意思？**
|
||||
表示后端未就绪，此时所有改动只停留在界面，不会写入真实赛事。恢复连接后刷新即可。
|
||||
|
||||
> 注意区分：顶部若只是显示「连接中断」，说明实时推送断了（数据可能不是最新），但写操作仍会照常提交给服务端并做校验。
|
||||
|
||||
**Q47：为什么登录 / 写操作偶尔被拒绝？**
|
||||
**Q54：为什么登录 / 写操作偶尔被拒绝？**
|
||||
系统有频率限制：登录每 IP 每分钟 5 次，写操作每用户每分钟 30 次。稍等一分钟再试。
|
||||
|
||||
**Q48：数据目录在哪？**
|
||||
默认 `%LOCALAPPDATA%\ScoreboardConsole\data`（当前用户的本地应用数据目录，升级 / 覆盖安装 / 卸载都不会删）。里面是 `system.db`（账号、会话）、`event_projs\<项目名>\`（每个赛事的 `event.db` 与上传图片 `uploads\`）、`backups\`、`exports\`。
|
||||
**Q55：数据目录在哪？**
|
||||
默认 `%LOCALAPPDATA%\ScoreboardConsole\data`（当前用户的本地应用数据目录，升级 / 覆盖安装 / 卸载都不会删）。里面是 `system.db`（账号、会话）、`event_projs\<项目名>\`（每个赛事的 `event.db` 与上传资源 `uploads\`，图片与自定义字体都在里面，字体在 `uploads\fonts\`）、`backups\`、`exports\`。
|
||||
|
||||
同一层还有 `config.yaml`（服务端配置）、`console\config.json`（Console 配置）与 `rules\`（规则包目录），也都在安装目录之外，同样不会被覆盖安装或卸载删掉。
|
||||
|
||||
|
||||
+16
-13
@@ -93,7 +93,7 @@ deploy\build.bat
|
||||
|
||||
### 3.4 数据放在哪里（升级/卸载都不会删）
|
||||
|
||||
覆盖安装时安装程序会**先静默运行旧版卸载器**，而卸载器会把整个安装目录删掉，所以数据库、规则、用户、上传的图片都不能放在安装目录里。现在的规则：
|
||||
覆盖安装时安装程序会**先静默运行旧版卸载器**，而卸载器会把整个安装目录删掉，所以数据库、规则、用户、上传的图片与字体都不能放在安装目录里。现在的规则：
|
||||
|
||||
| 场景 | 数据目录 |
|
||||
| --- | --- |
|
||||
@@ -102,6 +102,7 @@ deploy\build.bat
|
||||
| 直接双击 `scoreboard.exe`（不经 Console） | 服务端默认行为不变：用工作目录下的 `data\`，**这种用法在覆盖安装时仍会丢数据** |
|
||||
|
||||
- Console 启动时会把这个目录用 `-data` 参数交给服务端，界面上方「运行日志」里能看到 `数据目录：...` 这一行；
|
||||
- **上传资源随赛事项目走**：赛事会标、大屏背景图、单位 logo，以及「赛事信息 → 字体」里上传的**字体文件**，都在 `<数据目录>\event_projs\<项目名>\uploads\` 里（字体在 `uploads\fonts\`）。它们是文件而不是数据库记录，**不在 `backups\` 的 `.db` 快照里**，备份 / 迁移时要连这个目录一起拷（见 8.5、8.6）；
|
||||
- **一次性迁移**：如果新数据目录还是空的，而旧的 `<安装目录>\data` 里有数据，Console 会在启动时把旧目录**整体改名**过去（同盘很快），日志里会写「已把旧数据从 X 迁移到 Y」。任何失败（跨盘、权限不足等）都只记日志，旧数据原地保留，不会被删；
|
||||
- 如果两个目录里**都有数据**，Console 不做任何动作，只写一条警告日志，由现场人工决定保留哪一份；
|
||||
- 迁移只在安装包版本（打包后）执行一次，`pnpm start` 之类的开发运行不会碰仓库里的 `data\`；
|
||||
@@ -129,7 +130,8 @@ deploy\build.bat
|
||||
- 规则目录只在首次复制一次，之后你往里面放的规则包不会被模板顶掉；
|
||||
- 某一处建不出来或不可写（权限、杀毒软件拦截等）时**只记日志并回落到安装目录里那份**，绝不因此启动失败；代价是那份改动仍会在覆盖安装时丢失，日志里会明确写出来；
|
||||
- 开发运行（`pnpm start`）不接管这三项，仍用仓库里的 `console\config.json`、`config.yaml`、`rules\`；
|
||||
- 不用 Console、直接双击 `scoreboard.exe` 时，服务端仍按工作目录下的 `config.yaml` 读配置，**不受这套保护**。
|
||||
- 不用 Console、直接双击 `scoreboard.exe` 时，服务端仍按工作目录下的 `config.yaml` 读配置，**不受这套保护**；
|
||||
- 上传的图片与字体不在这三项里，位置见 3.4：它们随赛事项目存放在数据目录的 `event_projs\<项目名>\uploads\`（字体在 `uploads\fonts\`），同样在安装目录之外，覆盖安装不会动它们；**但它们不在 `backups\` 的数据库快照里**，备份 / 迁移时要连这个目录一起拷（见 8.6）。
|
||||
|
||||
> 从老版本覆盖升级上来的第一次启动：安装目录里那三份在覆盖安装时**就已经被旧卸载器删过一遍**（新装进去的是新版模板），Console 只能把模板复制到用户目录，升级前改在安装目录里的配置需要重做一遍。**从本版本起**（也就是改动落在上表位置之后），配置与规则才会跨升级保留。
|
||||
|
||||
@@ -328,15 +330,15 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
|
||||
### 7.3 单屏：窗口化 + F11
|
||||
|
||||
- 只有一块屏时，大屏以窗口化方式打开（屏幕 80% 大小、居中），并显示自绘标题栏；
|
||||
- 在窗口内按 **F11** 切换全屏 / 窗口；
|
||||
- 在窗口内按 **F11** 切换全屏 / 窗口：全屏时自绘标题栏与「实例 · 屏」标识一起隐藏、画面铺满整块屏；再按一次恢复；
|
||||
- 单屏模式不跟随显示器变化重排；
|
||||
- 窗口化时右上角会显示「实例 … · 屏 …」与数据版本号（`v<n>`）供现场核对；按 F11 全屏后「实例 · 屏」自动隐藏，版本号角标仍在（它只跟「这个窗口是不是窗口化打开的」有关，见 7.7）。
|
||||
- 窗口化且未全屏时右上角显示一行「实例 … · 屏 …」供现场核对（数据版本号角标已移除，见 7.7）。
|
||||
|
||||
### 7.4 多屏：每屏锁一页
|
||||
|
||||
- 除内置屏外的每块屏各开一个 kiosk 全屏窗口；
|
||||
- 每块屏**锁定一个页面**，按 `display.pages` 的顺序轮转分配；
|
||||
- 多屏 kiosk 不响应 F11，也不接收鼠标（`ignoreMouse`），也不显示任何调试标识与版本号角标；
|
||||
- 多屏 kiosk 不响应 F11，也不接收鼠标（`ignoreMouse`），也不显示任何调试标识；
|
||||
- 可用的页面值：`standings`（总积分榜）、`medals`（团体奖牌榜）、`individual`（个人积分奖牌榜）、`results`（分项成绩）、`announcement`（公告）；管理端切页用的是同一批页面的规范名 `team-medals` / `athlete-standings` / `event-results`，两种写法大屏都认。
|
||||
|
||||
### 7.5 在管理端单独控制某块屏
|
||||
@@ -360,7 +362,7 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
|
||||
|
||||
### 7.7 大屏画面里的调试标识与单位 logo
|
||||
|
||||
- **调试标识**：只有窗口化打开的大屏窗口才会显示「实例 … · 屏 …」与数据版本号 `v<n>`（`v<n>` 是数据版本号，与管理面板顶部的版本号一致就说明这块屏已跟上服务端）；**多屏 kiosk 全屏完全不带这些标识**，窗口化窗口按 F11 全屏后「实例 · 屏」也会隐藏、版本号角标仍在。要一个完全干净的展示画面，就用多屏 kiosk；
|
||||
- **调试标识**：只有**窗口化且没有全屏**的大屏窗口才会显示一行「实例 … · 屏 …」；**多屏 kiosk 全屏完全不带调试标识**，单屏窗口化窗口按 F11 全屏后它也会连同自绘标题栏一起隐藏。数据版本号角标 `v<n>` 已移除，任何情况下都不再显示（要核对某块屏是否跟上服务端，看管理端仪表盘「实时连接」里的「版本 N」）。要一个完全干净的展示画面，就用多屏 kiosk；
|
||||
- **单位 logo**：参赛单位的 logo 会显示在总积分榜、团体奖牌榜、分项成绩表与个人积分榜上（个人榜显示在姓名前）；没上传 logo 的单位不占位。logo 在「基础数据 → 参赛单位」里上传，随赛事项目包一起导出/导入（见 8.5）。
|
||||
|
||||
### 7.8 大屏窗口的自动行为
|
||||
@@ -452,7 +454,7 @@ http://<主机IP>:19540/display
|
||||
|
||||
- `meta.yaml`：包格式标识、项目名、赛事名称/副标题/主办方、导出时间，以及每个文件的 SHA-256 清单（导入时逐个校验，对不上就拒绝）；
|
||||
- `event.db`：赛事库快照（用 `VACUUM INTO` 生成，导出时服务端可以继续写入），成绩、基础数据、积分规则都在里面；
|
||||
- `uploads/`：**全部上传图片**——赛事会标、大屏会标、大屏背景图、各参赛单位 logo 等（在「系统设置 → 赛事信息」与「基础数据 → 参赛单位」里上传的那批文件）。导入时会连图片一起落到新项目目录，切换过去后直接显示，不用重新上传；
|
||||
- `uploads/`：**全部上传资源**——赛事会标、大屏会标、大屏背景图、各参赛单位 logo，以及**上传的字体**（放在 `uploads/fonts/` 下，见使用手册 14.3）。导入时会连文件一起落到新项目目录的 `uploads/`，切换过去后图片直接显示、字体直接可用，不用重新上传；
|
||||
- `rules.yaml`：当前规则包的一份 YAML 副本，便于单独复用到别的赛事；规则本身存在赛事库里，导入后即刻生效，这份只是副本。
|
||||
|
||||
导出界面同一页的「结果导出」标签可以把最终结果导成 xlsx：**总表**（总积分榜 + 团体奖牌榜 + 个人积分奖牌榜，一个工作簿）、**全部**（总表 + 全部分项）、**分项成绩表**（按小项）、**单位积分明细**（按单位）四项各自可单独导出打印。
|
||||
@@ -466,21 +468,21 @@ http://<主机IP>:19540/display
|
||||
|
||||
- 不能覆盖**正在运行**的赛事项目：对当前赛事的同名包，导入会被直接拒绝（先切到别的赛事再导）；
|
||||
- 勾选「覆盖同名项目」时，旧目录会先改名保留、新项目落盘成功后才删除它；
|
||||
- 参赛单位 logo、会标、背景图都在 `uploads\` 里，所以**备份 / 迁移时要连 `event_projs\<项目名>\uploads\` 一起拷**（见 8.6）；
|
||||
- 参赛单位 logo、会标、背景图与上传的字体都在 `uploads\` 里，所以**备份 / 迁移时要连 `event_projs\<项目名>\uploads\` 一起拷**（见 8.6）；
|
||||
- **不要用 `-project` 启动参数来切赛事**：显式传 `-project` 时，服务端会顺手把它写回「上次打开的赛事」记忆文件，于是以后每次启动都优先打开这个项目——在页面里切完、重启后又被拉回去。只有在「刻意把一台机器固定成只开某一个项目」时才这么用：在 Console 的用户配置 `config.json` 里给 `server.args` 加 `"-project","<项目名>"` 后重启 Console，或直接 `scoreboard.exe -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -project <项目名> -data "%LOCALAPPDATA%\ScoreboardConsole\data"` 启动（见 6.2）。
|
||||
|
||||
### 8.6 手工备份 / 迁移整个数据目录
|
||||
|
||||
快照备份之外，数据库文件、上传的图片、备份都可以整体拷走：
|
||||
快照备份之外，数据库文件、上传的图片与字体、备份都可以整体拷走：
|
||||
|
||||
1. 在 Console 里**停止服务**（托盘 → 停止服务），避免拷贝过程中继续写入；
|
||||
2. 把整个数据目录 `%LOCALAPPDATA%\ScoreboardConsole\data` 复制到 U 盘或其他盘（里面含 `system.db`、`event_projs\`（数据库 + `uploads\` 图片）、`backups\`）；
|
||||
2. 把整个数据目录 `%LOCALAPPDATA%\ScoreboardConsole\data` 复制到 U 盘或其他盘（里面含 `system.db`、`event_projs\`（数据库 + `uploads\` 图片与字体）、`backups\`）；
|
||||
3. 恢复时把整个目录拷回去，然后：
|
||||
- 拷回**原路径**：直接启动 Console 即可；
|
||||
- 拷到**别的路径**：先建好目标目录并放入数据，再在用户配置 `console\config.json` 里把 `server.dataDir` 指向它，重启 Console；
|
||||
4. 恢复完成后在管理端核对赛事、账号、上传图片是否齐全。
|
||||
4. 恢复完成后在管理端核对赛事、账号、上传图片与字体是否齐全。
|
||||
|
||||
> 只拷 `backups\` 里的 `.db` 快照也能救回成绩数据，但上传的背景图/会标在 `event_projs\<项目名>\uploads\` 里，不拷这个目录会丢图片。
|
||||
> 只拷 `backups\` 里的 `.db` 快照也能救回成绩数据，但上传的背景图/会标/单位 logo **与自定义字体**在 `event_projs\<项目名>\uploads\` 里（字体在 `uploads\fonts\`），不拷这个目录会丢这些文件，大屏上表现为图片不显示、字体回落成默认字体。
|
||||
|
||||
---
|
||||
|
||||
@@ -581,11 +583,12 @@ http://<主机IP>:19540/display
|
||||
- [ ] 「运行日志」里的 `数据目录：` 指向 `%LOCALAPPDATA%\ScoreboardConsole\data`（不是安装目录），且没有迁移警告
|
||||
- [ ] 「运行日志」里的 `用户数据目录：` 指向 `%LOCALAPPDATA%\ScoreboardConsole`，且没有「准备 … 失败」警告（配置与规则也在用户目录里，见 3.5）
|
||||
- [ ] 数据目录的 `backups\` 可写，已生成至少一份备份
|
||||
- [ ] 已把数据目录整个拷一份到 U 盘（含 `event_projs\<项目名>\uploads\` 里的图片）
|
||||
- [ ] 已把数据目录整个拷一份到 U 盘（含 `event_projs\<项目名>\uploads\` 里的图片与字体）
|
||||
- [ ] **当前赛事正确**：「导出 → 赛事项目包 → 赛事项目列表」里带「当前」徽标的是本次要用的那个项目（刚导入的包要切换过去才算生效，见 8.5）
|
||||
- [ ] 大屏 HDMI 输出定位正确、分辨率正确、字体正常
|
||||
- [ ] **显示器菜单可用**：在服务管理窗口打开的「大屏控制」页里能看到每块屏并「创建全屏窗口」，副屏被误关时能重开（见 7.5）
|
||||
- [ ] **单位 logo 已上传且在榜上显示**（总积分榜 / 团体奖牌榜 / 分项成绩表 / 个人积分榜，见 7.7）
|
||||
- [ ] **大屏字体已选好并核对**：「系统设置 → 赛事信息 → 字体」里选了标题字体与正文字体，大屏上显示正常；上传的字体在数据目录 `event_projs\<项目名>\uploads\fonts\` 里，导出赛事项目包会一并带走（见 8.5）
|
||||
- [ ] **公告可用**：推送一条测试公告，全屏到时后底栏仍能看到正文，点「清除公告」后底栏回到「暂无公告」（见 7.6）
|
||||
- [ ] 管理端各角色账号可登录，权限正确
|
||||
- [ ] 主机 IP 固定，管理端 / 大屏地址已打印或做成二维码贴在操作台
|
||||
|
||||
Reference in new issue
Block a user