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 2026-09-10 17:45:11 +08:00
1 parent 9c6d0bd3b3
commit fc96d17660
42 files changed
+2451 -95

No files matched your search

+63 -27
View File
@@ -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\`(规则包目录),也都在安装目录之外,同样不会被覆盖安装或卸载删掉。