docs: 用户文档补齐「个人+团体」等新功能，修正切换赛事与账号存储位置的说法

按 407abec 之后落地的功能，对照代码逐条更新四份用户文档与 README： - 使用手册：补「个人+团体」是什么与完整配置链路、平均值口径两种分母、榜单口径（全局）折算系数、公告（全屏→底栏常驻）、报名导入两个页签、单位 logo 显示位置、17.5 调试标识；修正「账号存在各个赛事库里」的错误说法（账号与会话在数据目录的 system.db），在线看板改为指向服务管理窗口的实例卡片 - 部署指南：新增 7.5 显示器菜单 / 7.6 公告 / 7.7 调试标识与单位 logo；重写 8.5 赛事项目包（导入 ≠ 切换、包内四类内容、不能覆盖运行中的项目），并把 -project 启动参数明确标为「不要用来切赛事」 - 上线检查清单：补当前赛事、显示器菜单、单位 logo、公告四项现场核对，修正「切换后登录状态失效」 - 常见问题：重编号 Q1–Q48，新增个人+团体算分、平均值口径、只报单位、折算系数、公告底栏、单位 logo、调试标识 8 条；切换赛事与数据迁移按实测重写 - README：功能概览与文档索引同步
2026-09-10 15:16:17 +08:00
1 parent 6bd7bd1627
commit 9c6d0bd3b3
@@ -63,7 +63,7 @@ deploy\build.bat
 - 拉起并守护服务端 `scoreboard.exe`；
 - 在数据目录（默认 `%LOCALAPPDATA%\ScoreboardConsole\data`）下自动建库、建目录；
 - 打开服务端管理面板窗口；
- 把大屏页面投到扩展屏；
+- 把大屏页面投到扩展屏（只接一块屏时开成窗口化窗口，按 F11 可切全屏；见第 7 节）；
 - 启用防熄屏；
 - 注册开机自启登录项但**不启用**（任务管理器「启动」里可见、状态为「已禁用」）；需要随系统启动时，在服务管理窗口的「开机自启」开关里打开（仅打包后的 Windows 版本生效）。

@@ -117,9 +117,9 @@ deploy\build.bat
 | --- | --- | --- |
 | Console 配置 | `%LOCALAPPDATA%\ScoreboardConsole\console\config.json` | 端口、选屏策略、开机自启等（见 6.2） |
 | 服务端配置 | `%LOCALAPPDATA%\ScoreboardConsole\config.yaml` | 监听地址/端口、备份间隔、日志级别（见 6.1） |
-| 规则目录 | `%LOCALAPPDATA%\ScoreboardConsole\rules\` | 规则包 YAML；管理面板「导入规则包」时从这里选 |
+| 规则目录 | `%LOCALAPPDATA%\ScoreboardConsole\rules\` | 规则包 YAML；管理面板「导出 → 规则包 → 选择 YAML」时从这里选 |

-**怎么改**：直接编辑上表里的文件。`config.json` 与 `config.yaml` 都是 Console 启动时读一次，改完要**退出并重启 Console**（托盘 → 退出）；服务管理窗口的「配置文件」一行显示的就是 `console\config.json` 的实际路径，可用来确认。`rules\` 只是规则包存放目录，往里放文件不需要重启，但规则要在管理面板「系统设置 → 规则包 → 导入」里选文件导入后才生效（服务端不会自动加载）。安装目录里那三份是模板，改了不生效。
+**怎么改**：直接编辑上表里的文件。`config.json` 与 `config.yaml` 都是 Console 启动时读一次，改完要**退出并重启 Console**（托盘 → 退出）；服务管理窗口的「配置文件」一行显示的就是 `console\config.json` 的实际路径，可用来确认。`rules\` 只是规则包存放目录，往里放文件不需要重启，但规则要在管理面板「导出 → 规则包 → 选择 YAML → 预览差异 → 确认导入并全量重算」里导入后才生效（服务端不会自动加载）。安装目录里那三份是模板，改了不生效。

 升级/覆盖安装时：

@@ -164,7 +164,8 @@ deploy\build.bat
 | 大屏窗口 | **打开服务端管理面板** | 用内置窗口打开 `http://127.0.0.1:<端口>/admin`，无需再开浏览器 |
 | 运行日志 | **自动滚动** | 日志是否跟随最新一行 |
 | 运行日志 | **清空** | 清空窗口内显示（不影响日志文件） |
-| 已连接的大屏实例 | — | 显示在线大屏窗口的数量与各自页面，5 秒刷新；需先在管理面板登录过才能读到 |
+| 已连接的大屏实例 | — | 显示在线大屏窗口的数量与各自页面，5 秒刷新；需先在管理面板登录过（记录员及以上）才能读到 |
+| 管理员账号 | **重置账号** | 本机直接调用同目录的 `scoreboard.exe passwd`，自动带上用户目录里的 `config.yaml` 与数据目录，**不需要登录**；会作废该用户的全部登录会话（见 5.5） |
 | 标题栏 | 最小化 / 最大化 / 关闭 | 关闭只是**隐藏到托盘**，服务端继续运行 |

 ### 4.2 托盘用法
@@ -225,7 +226,9 @@ findstr /C:"INITIAL ADMIN CREATED" logs\console.log

 ### 5.5 忘记密码 / 没记下初始密码

-在 Console 里先**停止服务**，然后在安装目录（`scoreboard.exe` 所在目录）执行：
+**首选：服务管理窗口的「管理员账号」卡片。** 在卡片里填「当前用户名」（默认 `admin`），「新用户名」「新密码」留空即「不改名 / 随机生成」，点「重置账号」，命令输出会直接显示在卡片里。这条路径不需要登录，Console 会自动用上用户目录里的 `config.yaml` 与数据目录。
+
+**命令行方式**：在 Console 里先**停止服务**，然后在安装目录（`scoreboard.exe` 所在目录）执行：

 ```bat
 scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -data "%LOCALAPPDATA%\ScoreboardConsole\data"
@@ -326,16 +329,41 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da

 - 只有一块屏时，大屏以窗口化方式打开（屏幕 80% 大小、居中），并显示自绘标题栏；
 - 在窗口内按 **F11** 切换全屏 / 窗口；
- 单屏模式不跟随显示器变化重排。
+- 单屏模式不跟随显示器变化重排；
+- 窗口化时右上角会显示「实例 … · 屏 …」与数据版本号（`v<n>`）供现场核对；按 F11 全屏后「实例 · 屏」自动隐藏，版本号角标仍在（它只跟「这个窗口是不是窗口化打开的」有关，见 7.7）。

 ### 7.4 多屏：每屏锁一页

 - 除内置屏外的每块屏各开一个 kiosk 全屏窗口；
 - 每块屏**锁定一个页面**，按 `display.pages` 的顺序轮转分配；
- 多屏 kiosk 不响应 F11，也不接收鼠标（`ignoreMouse`）；
- 可用的页面值：`standings`（总积分榜）、`medals`（团体奖牌榜）、`individual`（个人积分奖牌榜）、`results`（分项成绩）、`announcement`（公告）。
+- 多屏 kiosk 不响应 F11，也不接收鼠标（`ignoreMouse`），也不显示任何调试标识与版本号角标；
+- 可用的页面值：`standings`（总积分榜）、`medals`（团体奖牌榜）、`individual`（个人积分奖牌榜）、`results`（分项成绩）、`announcement`（公告）；管理端切页用的是同一批页面的规范名 `team-medals` / `athlete-standings` / `event-results`，两种写法大屏都认。

-### 7.5 大屏窗口的自动行为
+### 7.5 在管理端单独控制某块屏
+
+管理端「大屏控制」页有**显示器**卡片，可以给指定显示器单独开窗或收窗。这张卡片只在**从服务管理窗口点「打开服务端管理面板」打开的那个窗口**里可用；用浏览器直接打开管理面板时，卡片会提示此功能不可用。
+
+- 列出本机每块显示器（名称、分辨率、缩放、是否主显示器、当前有没有大屏窗口、是全屏还是窗口化）；
+- 先在「窗口页面」里选页面，再对某块屏点「创建全屏窗口」或「创建窗口（窗口化）」；已经开着窗口的屏显示「聚焦窗口」与「关闭窗口」；
+- **全屏只对「多显示器 + 非主显示器」开放**：只接一块屏、或选中的是主显示器时只能创建窗口化窗口（全屏会把桌面整个盖住又退不出来）。请求被降级时窗口照开，提示里会写明原因；
+- 「重新排布」按 Console 配置的选屏策略重建全部窗口，不在策略内的窗口会被关掉。
+
+副屏的全屏窗口被误关时，用这里的「创建全屏窗口」就能恢复，不必重启 Console。
+
+### 7.6 公告
+
+管理端「大屏控制 → 公告」推送后：
+
+- 大屏先**全屏**显示这条公告，时长取「滚动时长」（5–120 秒，实际就是全屏展示的秒数），到时自动退回推送前的那一页；
+- 公告正文随后留在**大屏底部的公告栏**（底栏固定的「公告」槽位）常驻显示，直到被下一条公告替换或点了「清除公告」才消失；
+- 公告正文存在服务端设置里：断线重连、重开大屏窗口都会重新拿到它（新开的窗口会先全屏放 15 秒再落回底栏）；点「清除公告」后底栏回到「暂无公告」。
+
+### 7.7 大屏画面里的调试标识与单位 logo
+
+- **调试标识**：只有窗口化打开的大屏窗口才会显示「实例 … · 屏 …」与数据版本号 `v<n>`（`v<n>` 是数据版本号，与管理面板顶部的版本号一致就说明这块屏已跟上服务端）；**多屏 kiosk 全屏完全不带这些标识**，窗口化窗口按 F11 全屏后「实例 · 屏」也会隐藏、版本号角标仍在。要一个完全干净的展示画面，就用多屏 kiosk；
+- **单位 logo**：参赛单位的 logo 会显示在总积分榜、团体奖牌榜、分项成绩表与个人积分榜上（个人榜显示在姓名前）；没上传 logo 的单位不占位。logo 在「基础数据 → 参赛单位」里上传，随赛事项目包一起导出/导入（见 8.5）。
+
+### 7.8 大屏窗口的自动行为

 | 场景 | 行为 |
 | --- | --- |
@@ -345,7 +373,7 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da
 | 服务端崩溃 | 按退避策略自动重启，恢复后大屏自动重载 |
 | 长时间运行 | 每 `reloadEveryHours`（默认 24 小时）自动重载一次 |

-### 7.6 备选方案：安卓 TV / 设备自带浏览器
+### 7.9 备选方案：安卓 TV / 设备自带浏览器

 如果不用 Console 驱动 HDMI，也可以让大屏设备用自己的浏览器访问：

@@ -412,14 +440,34 @@ http://<主机IP>:19540/display

 ### 8.5 赛事项目包导出 / 导入

+服务端**一次只打开一个赛事项目**，页面上看到的数据全部来自标记为「当前」的那一项，其余项目只是躺在数据目录里的数据。导入赛事包**不会自动切换**当前赛事，导入后要再点一次「切换为当前赛事」才生效（见下面的步骤）。
+
 | 操作 | 位置 | 说明 |
 | --- | --- | --- |
 | 导出 | 「导出 → 赛事项目包 → 导出 zip」 | 包内含 `meta.yaml`、`event.db`、`uploads/`、`rules.yaml`；整包拷走即可在另一台机器复现 |
 | 导入 | 「导出 → 赛事项目包 → 选择 .zip → 导入」 | **仅管理员**可操作；可填「重命名」，勾选「覆盖同名项目」会先二次确认 |
+| 切换 | 「导出 → 赛事项目包 → 赛事项目列表 → 切换为当前赛事」 | 只有管理员可操作；会让服务端重启一次 |

- 导入后项目落在 `<数据目录>\event_projs\<项目名>\`；
- 当前运行的服务端默认使用 `default` 项目。要让新导入的赛事生效，可在 Console 的用户配置 `config.json` 里给 `server.args` 加 `"-project","<项目名>"`，然后重启 Console；也可以直接用 `scoreboard.exe -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -project <项目名> -data "%LOCALAPPDATA%\ScoreboardConsole\data"` 启动；
- 导入期间请勿停止服务端进程。
+包内含四类内容：
+
+- `meta.yaml`：包格式标识、项目名、赛事名称/副标题/主办方、导出时间，以及每个文件的 SHA-256 清单（导入时逐个校验，对不上就拒绝）；
+- `event.db`：赛事库快照（用 `VACUUM INTO` 生成，导出时服务端可以继续写入），成绩、基础数据、积分规则都在里面；
+- `uploads/`：**全部上传图片**——赛事会标、大屏会标、大屏背景图、各参赛单位 logo 等（在「系统设置 → 赛事信息」与「基础数据 → 参赛单位」里上传的那批文件）。导入时会连图片一起落到新项目目录，切换过去后直接显示，不用重新上传；
+- `rules.yaml`：当前规则包的一份 YAML 副本，便于单独复用到别的赛事；规则本身存在赛事库里，导入后即刻生效，这份只是副本。
+
+导出界面同一页的「结果导出」标签可以把最终结果导成 xlsx：**总表**（总积分榜 + 团体奖牌榜 + 个人积分奖牌榜，一个工作簿）、**全部**（总表 + 全部分项）、**分项成绩表**（按小项）、**单位积分明细**（按单位）四项各自可单独导出打印。
+
+导入与切换：
+
+1. 导入把包解到 `<数据目录>\event_projs\<项目名>\`（项目名可用「重命名」覆盖）。**导入只是把数据落盘，不会切换当前赛事**，所以导入完成后页面会提示「已导入为 xxx，但它还不是当前赛事」；导入期间请勿停止服务端进程；
+2. 在导入结果框里点「立即切换并重启服务端」，或稍后在**赛事项目列表**里点该项目的「切换为当前赛事」（列表会显示每个项目的项目名、更新时间、占用大小，当前打开的那项带「当前」徽标，缺 `event.db` 的项目不可切换）；
+3. 切换 = 服务端把项目名写进 `<数据目录>\active_project.txt` 后优雅退出，由 Console 自动拉起并打开新赛事（页面会显示「正在重启服务端…」，恢复后自动刷新，最多等 60 秒）。**所以切换需要 Console 在运行**；如果是不经 Console、直接双击 `scoreboard.exe` 跑的，切换后要自己把服务端重新启动一次；
+4. 之后即使不带任何启动参数，服务端也仍然打开这个赛事（记忆文件生效）；换了别的赛事再切一次即可。
+
+- 不能覆盖**正在运行**的赛事项目：对当前赛事的同名包，导入会被直接拒绝（先切到别的赛事再导）；
+- 勾选「覆盖同名项目」时，旧目录会先改名保留、新项目落盘成功后才删除它；
+- 参赛单位 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 手工备份 / 迁移整个数据目录

@@ -463,10 +511,13 @@ http://<主机IP>:19540/display
 1. HDMI 线是否插好，大屏电源是否打开；
 2. Windows 显示设置是否为**扩展**模式；
 3. Console「大屏窗口」卡片是否显示已打开；点「重新排布」；
-4. 确认 `display.selection` 选屏策略是否漏掉了目标屏；
-5. 服务端未就绪时大屏最多等 20 秒才打开，稍等即可；
-6. 查看 Console 运行日志里的「大屏排布完成」「大屏加载」记录；
-7. 单屏窗口化时按 **F11** 可切全屏。
+4. 在服务管理窗口点「打开服务端管理面板」，到「大屏控制 → 显示器」里看该块屏的状态，点它的「创建全屏窗口」重新开出来（副屏全屏窗口被误关时最有效，见 7.5）；
+5. 确认 `display.selection` 选屏策略是否漏掉了目标屏；
+6. 服务端未就绪时大屏最多等 20 秒才打开，稍等即可；
+7. 查看 Console 运行日志里的「大屏排布完成」「大屏加载」记录；
+8. 单屏窗口化时按 **F11** 可切全屏。
+
+> 「大屏控制」页的显示器卡片只在**从服务管理窗口点「打开服务端管理面板」打开的那个窗口**里可用；用浏览器直接打开管理面板看不到这组按钮（页面会给出说明）。

 ### 9.3 管理面板打不开

@@ -491,7 +542,7 @@ http://<主机IP>:19540/display
 ### 9.6 大屏时间不对

 - 系统没有外网 NTP，**以主机时间为准**；
- 修改 Windows 系统时间与时区后，大屏顶部时钟会在下一次刷新时跟随（约 15 秒一次）；
+- 大屏顶部时钟精确到秒、每秒刷新，改完 Windows 系统时间与时区后立刻跟随；
 - 建议在开幕前校准主机时间。

 ### 9.7 安卓 TV 备选方案打不开
@@ -531,7 +582,11 @@ http://<主机IP>:19540/display
 - [ ] 「运行日志」里的 `用户数据目录：` 指向 `%LOCALAPPDATA%\ScoreboardConsole`，且没有「准备 … 失败」警告（配置与规则也在用户目录里，见 3.5）
 - [ ] 数据目录的 `backups\` 可写，已生成至少一份备份
 - [ ] 已把数据目录整个拷一份到 U 盘（含 `event_projs\<项目名>\uploads\` 里的图片）
+- [ ] **当前赛事正确**：「导出 → 赛事项目包 → 赛事项目列表」里带「当前」徽标的是本次要用的那个项目（刚导入的包要切换过去才算生效，见 8.5）
 - [ ] 大屏 HDMI 输出定位正确、分辨率正确、字体正常
+- [ ] **显示器菜单可用**：在服务管理窗口打开的「大屏控制」页里能看到每块屏并「创建全屏窗口」，副屏被误关时能重开（见 7.5）
+- [ ] **单位 logo 已上传且在榜上显示**（总积分榜 / 团体奖牌榜 / 分项成绩表 / 个人积分榜，见 7.7）
+- [ ] **公告可用**：推送一条测试公告，全屏到时后底栏仍能看到正文，点「清除公告」后底栏回到「暂无公告」（见 7.6）
 - [ ] 管理端各角色账号可登录，权限正确
 - [ ] 主机 IP 固定，管理端 / 大屏地址已打印或做成二维码贴在操作台
 - [ ] 防熄屏、屏保、休眠、系统通知已关闭