feat(import): 报名模板按「小项 × 组别」分工作表；号码布判重改认证件号；备份改原子落盘

三件事合成一次提交（其中两件都落在 handlers_config.go，无法按文件拆开）：一、分工作表报名模板（新增能力） - 新增 GET /api/entries/template.xlsx：按当前赛事的「小项 × 组别」生成模板，一个小项组别一张工作表，工作表名 = <小项>@<组别>（31 字符上限、重名自动去重）。 - 导入解析器认工作表名还原小项 + 组别；若与表内列冲突则报错，不静默取其一。 - 小项名与组别名禁用 @，基础数据界面 / 规则包导入 / 服务端校验三处一并拦截。 - 单表 CSV/XLSX 导入路径不回归。二、号码布判重（修误判） - 旧逻辑依赖证件号本身，而证件号是可选字段 → 同一个人报多个项目会被整块拦下。 - 改为：号码布相同且证件号相同 → 判定为同一人报多项，放行；号码布相同且证件号都能填且不同 → 仍报错（真抢号）；一方证件号为空 → 放行并给提示。 - 团体行的号码布一并纳入查重。三、自动备份的关停与落盘（修数据安全隐患） - export.Service 增加 Wait()：StartAuto 的协程进 WaitGroup，关停时 join（10 秒上限，超时只记 WARN 不拖死关闭），不再在备份写到一半时退出。 - vacuumInto 改为先写 <最终名>.tmp-<随机> 再 rename，失败则删临时文件； Backup / SafetySnapshot / ExportProjectZip 三个调用方一并受益。 - 新增 isFinalBackupName，ListBackups / safetyCopies / KindOfBackupName 统一过滤中间文件，避免半截 .db 被列进备份列表、进而被「一键恢复」选中。文档：docs/ 五份（使用手册 / 报名名单导入规范 / 升级说明 / 部署指南 / 上线检查清单）同步。
2026-09-14 01:10:16 +08:00
1 parent b74768b7d5
commit 1b8a37ff8c
@@ -18,15 +18,16 @@
 - [ ] Windows 10/11 x64，接市电（建议接 UPS）
 - [ ] 端口 **19540** 未被占用：`netstat -ano | findstr 19540`
 - [ ] **防火墙已放行入站 19540**（局域网设备才能连上）—— **自检口径：用另一台设备（平板 / 手机）浏览器打开 `http://<主机IP>:19540/display` 能出画面，就算放行过了**；打不开时先确认装的时候选的是哪一项：
-      - 装的时候选了**「为所有用户安装」**：安装程序提权时**已经自动放行**（防火墙里能看到规则 `Scoreboard Console (TCP 19540)`），不用再手工加；
-      - 装的时候选了**「仅为我安装」**：不申请提权、装不了规则，在**管理员** cmd 里手工放行一次
+      - 装的时候选了**「为所有用户安装」**：那一档提权时装好规则，**已经自动放行**（防火墙里能看到规则 `Scoreboard Console (TCP 19540)`），不用再手工加；
+      - 装的时候选了**「仅为我安装」**（含**受限账户**的机器 —— 新版安装器会自动降到这一档）：**不加规则**，在**管理员** cmd 里手工放行一次
        `netsh advfirewall firewall add rule name="Scoreboard 19540" dir=in action=allow protocol=TCP localport=19540`
        （也可以改用「为所有用户安装」重跑一次安装程序，让它自动放行）
      —— 临时「关闭防火墙」只用于**验证**是不是它挡的，验证完要恢复；正式开赛前一定放行，不要一直关着防火墙。改过端口就把 `19540` 换成实际端口，安装程序只会自动放行默认端口 `19540`，改过端口的一律手工放行
 - [ ] 数据/配置目录可写：默认 `%LOCALAPPDATA%\ScoreboardConsole\`（数据在 `data\`，配置与规则是 `console\config.json`、`config.yaml`、`rules\`；都在安装目录之外，升级/卸载都不会删），需要放行杀毒/防火墙
 - [ ] 大屏通过 HDMI 接在**同一台机器**上（系统显示模式设为「扩展」）
 - [ ] 显示器数量确认：只接一块屏时大屏只能窗口化（按 F11 可切全屏）；要每屏一个 kiosk 全屏窗口就得接第二块屏（见部署指南 7.3、7.5）
- [ ] **安装目录不要选 `C:\Program Files`**（那里普通用户没写权限，日志会写不进去）；装到 D 盘等普通目录即可，向导里可以改路径
+- [ ] **安装位置与装法符合预期**：向导里**默认是「为所有用户安装」**（装到 `C:\Program Files\Scoreboard_Console`，并自动放行防火墙）；只给当前账户用、或这台机器装不了 Program Files 时选**「仅为我安装」**（装到用户目录、防火墙要手工放行）。装完**右键桌面「赛事积分榜」快捷方式 →「属性」→ 看「目标」**核对实际装到哪个目录。⚠️ Console 自己的 `console.log` 写在**安装目录**的 `logs\` 下 —— 如果装完「运行日志」面板一直空着 / 安装目录里没有 `logs\console.log`，多半是那个目录当前账户写不进去，**改装到 `D:\Scoreboard` 这类普通目录**（向导里可以改；手工改过路径后切换装法也不会被冲掉）重装一次
+- [ ] **升级（覆盖安装）前确认旧版本程序已关闭**：新版安装程序**会自动关掉**在跑的旧版本（含它拉起的 `scoreboard.exe` 服务端进程），但动手前自己在托盘 / 任务管理器确认一遍更稳（有正在录入的现场就别在赛中升级）；装完启动，确认打开的还是原来那个数据目录（「运行日志」里的 `数据目录：`）

 ## 3. 首次启动

@@ -526,6 +526,7 @@

 1. 左侧选择或新增大项（编码、名称、简称、默认积分模板、排序）；
 2. 右侧维护该大项下的小项：点「新增小项」，填写编码、名称、类型（个人 / 团体 / 对抗 / 比赛 / 个人+团体）、录入方式（自动排名 / 手动名次）、成绩类型（时间 / 距离 / 计数 / 得分 / 无成绩）、比较方式（越小越好 / 越大越好 / 不比较）、状态、是否计分、**是否结算奖牌**等；
+   - **小项名里不能用 `@`**：它是「分工作表报名模板」里工作表名「小项名称@组别名称」的分隔符（见 10.7），填了会当场标红说明；已经带 `@` 的历史名字不影响任何报名、成绩与积分，只会在下载分工作表模板时被点名，改名即可；
 3. 小项行上的「配置组别」「配置计分通道」可直接跳到对应分区；
 4. 删除大项 / 小项会二次确认。

@@ -568,6 +569,7 @@

 1. 先在上方选中一个小项；
 2. 点「新增组别」，填写名称、权重、性别、年龄上下限、排序；
+   - **组别名里不能用 `@`**（小项名同）：它是「分工作表报名模板」里工作表名「小项名称@组别名称」的分隔符（见 10.7），填了会当场标红说明。已经带 `@` 的历史名字不影响任何报名、成绩与积分，只会在下载分工作表模板时被点名，改名即可；
 3. 用「上移 / 下移」调整顺序，「移除」删除；
 4. 点「保存」提交。**已有报名数据的小项**：改名 / 改年龄 / 改性别 / 改权重 / 改排序会**就地保存**——组别本身不重建，挂在它下面的报名、成绩与积分流水一条不动；其中**改权重会立即按新权重重算该项目已发布成绩的积分与榜单**，改名 / 改年龄 / 改性别 / 改排序不会。**新增或删除组别**仍走「整体替换」，有报名数据时服务端会拒绝（组别一重建，挂在它下面的报名就断链了）——要增删请先撤掉增删操作、只保存字段修改。

@@ -681,8 +683,15 @@

 > 报名表的完整格式、每一列怎么填、个人 / 团体 / 「个人+团体」三种项目的填法和常见报错对照，见单独一份文档 [报名名单导入规范](./报名名单导入规范.md)——**可以直接把那份文件发给各单位填表人**。

-1. 点「下载 CSV 模板」获取表头样例；
+1. 点「下载模板」拿表头样例。四个按钮对应两种模板，**两种都能导入**：
+   - 「**中文表头 / 英文表头**」＝**单表模板**（`entries-template-zh.csv` / `entries-template-en.csv`）：一份表装全部报名，每行都要填「项目编码」与「组别」两列；
+   - 「**分工作表 · 中文表头 / 分工作表 · 英文表头**」＝**分工作表模板**（`.xlsx`）：按当前赛事已配好的**小项 × 组别各建一张工作表**，表名是「**小项名称@组别名称**」（例如 `100 米跑@男子组 30岁以下`），范围由表名承担，数据区只填人和单位。小项组别多时用它更不容易抄串；
+   - 两种模板的表头与列顺序完全一样，只有「范围从哪来」不同（详细规范见 [报名名单导入规范 · 第八节](./报名名单导入规范.md)）；
 2. 表头共 12 列：`event_code`、`category`、`team_code`、`athlete_name`、`id_card`、`gender`、`age`、`bib`、`seed`、`heat`、`status`、`member_names`（大小写不敏感）。其中 `id_card`（证件号）、`gender`（性别）、`age`（年龄）、`heat`（批次）为可选列，缺失不影响导入，其余列必须包含；
+   - 用**分工作表模板**时，`event_code`、`category` 两列也可以整列不要或整列留空（范围由工作表名决定）；一旦填了就必须与工作表名一致，不一致的那一行会报错并跳过；
+   - 工作表名必须是「小项名称@组别名称」；工作簿里只要有**一张**表名带 `@`，整份文件就按分工作表模板处理，别的表名不合规会**整份拒绝并点名是哪张表**（不让数据无声消失）；
+   - 小项名与组别名里**不允许出现 `@`**（它是表名里的分隔符）：新建 / 编辑小项与组别时界面会当场拦下并说明原因；**已经带 `@` 的历史名字不影响报名与成绩**，但下载分工作表模板时会被点名要求先改名；
+   - 表名超过 Excel 的 31 字符上限、或两个组合截断后撞名时，系统会确定性地截断（保留开头）并自动加 `(2)`/`(3)` 后缀——**下载下来的表名就是最终名字，不要手工改**；
 3. **只要有姓名的行，`id_card` 与 `bib` 必须至少填一个**，否则该行报错并跳过；`gender` 只认「男」「女」，其他值忽略；`age` 可留空，填了必须是 0–120 的整数；**证件号是系统认人的第一依据**，同一个证件号在同一份文件里重复出现**不报错**（同一个人报多个组别时会重复，导入结果里会给一条「证件号 XXXX 在本表中出现 N 次（同一人报名多个组别）」提示）；同一小项同一个组别里出现两次同样的证件号才按**真重复**进冲突列表；**同一个号码布给了两个不同的人会报错并跳过**（同一个人报多个组别时号码布可以重复）；
 4. 人员匹配顺序（**证件号是单人的唯一标识**）：
   1. 先按 `id_card`（证件号）匹配：命中即认作同一人；姓名 / 性别 / 年龄 / 单位 / 号码布与他的档案对不上时进「冲突」列表，等你逐条决定（见下）；
@@ -700,7 +709,8 @@
   - `未出场` / `未到` / `缺席` → 未出场。
   留空即「正常参赛」。真正认不出的写法会给出中文行级错误、该行跳过，例如「第 12 行：status「已报到」无法识别，只能填 registered / scratched / dq / dns（或留空）」；
 6. `bib` 列会同时写入人员档案与报名记录；从已有名单勾选生成的报名也会带上人员的证件号与号码布；
-7. 把 `.csv` 或 `.xlsx` 拖入虚线框，或点击选择文件（单个文件不超过 32MB；xlsx 只解析第一个工作表）；
+7. 把 `.csv` 或 `.xlsx` 拖入虚线框，或点击选择文件（单个文件不超过 32MB）；
+   - **xlsx 怎么读**：只有一张工作表（或表名都不像分工作表模板）时，按单表模板只读**第一张**，其余工作表会在导入结果里提示「没有读」；只要有一张表名带 `@`，整份文件按**分工作表模板**处理，每张工作表各按自己的表名（小项@组别）导入；
   - **CSV 编码不用管**：UTF-8、带 BOM 的 UTF-8（Excel 的「CSV UTF-8」）、GBK / GB18030（中文 Windows 上 Excel「另存为 CSV」的默认编码）、UTF-16 都能直接导入，中文不会乱码，服务端会自动识别；
 8. 点「开始导入」，页面显示**新增 / 更新 / 跳过**数量；匹配不到的行会跳过并回显行号，修正后可重新上传。

@@ -10,7 +10,7 @@

 ### 一句话

-**两条数据迁移、三处计分口径变化、安装器换新，升级后建议重新导入一次新版规则包**：迁移 `0022` 把「小项已被删除、积分流水却还挂在榜上」的历史脏数据一次性作废（**只影响分数，不影响名次与奖牌，人工调整分不受影响**）；迁移 `0023` 给计分通道加一列「聚合口径」（默认「平均」，不切就与升级前一样）；**单位奖牌榜改为按奖牌数独立排名，可能与积分榜顺序不同**；安装界面全面重做（**安装逻辑不变**）。
+**两条数据迁移、三处计分口径变化、安装器换新，升级后建议重新导入一次新版规则包**：迁移 `0022` 把「小项已被删除、积分流水却还挂在榜上」的历史脏数据一次性作废（**只影响分数，不影响名次与奖牌，人工调整分不受影响**）；迁移 `0023` 给计分通道加一列「聚合口径」（默认「平均」，不切就与升级前一样）；**单位奖牌榜改为按奖牌数独立排名，可能与积分榜顺序不同**；安装器换新——界面全面重做，并且**安装时改了三处行为**（一启动就申请管理员、自动关闭正在运行的旧版本、装到哪与「上次安装目录」的关系，见 ③）。

 ### ① 数据迁移：两条（0022 / 0023）

@@ -46,11 +46,20 @@
 - 重新导入规则包会把这条口径按规则包的值写回库里（本赛会包是 **总分 → 金 → 银 → 铜 → 单位编码**）：**此前导入过排序口径写法不同的规则包**的机器，这一段里单位的先后可能变化——**变的是顺序，分数与奖牌都不变**，看到顺序变了不要当成故障。
 - **单位奖牌榜不受这条影响**：它固定按金 → 银 → 铜 → 单位编码（见上面第 2 条）。

-### ③ 安装器换新（界面重做，安装逻辑不变）
+### ③ 安装器换新（界面重做 + 三处安装行为变化）

- 安装程序（`Scoreboard Console-<版本>-x64.exe`）**界面全面重做**：欢迎 / 目录 / 许可 / 进度 / 完成各页与按钮换成新素材，并**支持 4K 高 DPI**（系统缩放到 200% 时界面按缩放后的尺寸排布，字与按钮不会糊成一团）。
- **安装逻辑一个字没改**：装到哪、装什么、桌面快捷方式（「赛事积分榜」）、卸载方式、覆盖安装时先静默跑一遍旧卸载器、数据与配置在 `%LOCALAPPDATA%\ScoreboardConsole\`（**覆盖安装不会丢**）——全部与升级前一致。
- 默认安装模式是**「为所有用户安装」**（装到 Program Files，安装时提一次权）；**这台机器上次装过时，向导沿用上次的装法**，静默安装也可以用 `/allusers` / `/currentuser` 指定。这一趟**仍然自动放行防火墙入站 19540**（在防火墙里能看到规则 `Scoreboard Console (TCP 19540)`），局域网大屏不用再手工放行；选「仅为我安装」的机器要手工放行（命令见《部署指南》7.5）。
+- **界面全面重做**：安装程序（`Scoreboard Console-<版本>-x64.exe`）的欢迎 / 目录 / 许可 / 进度 / 完成各页与按钮换成新素材，并**支持 4K 高 DPI**（系统缩放到 200% 时界面按缩放后的尺寸排布，字与按钮不会糊成一团）。
+- **① 安装程序现在一启动就申请管理员**：双击安装包会**先弹一次 UAC**（Windows 的「是否允许此应用对你的设备进行更改？」），点「是」之后整个安装过程都在提权状态下进行 —— 装到 `C:\Program Files\…`、自动放行防火墙入站 19540（规则名 `Scoreboard Console (TCP 19540)`，卸载时会自动删掉）都靠它。
+  - **管理员机器**：会弹这一次 UAC；装完不用再手工放行防火墙。
+  - **受限账户（不是管理员）的机器**：**不会弹 UAC**（弹了也没用），安装程序会**自动降级为「仅为我安装」**，装到你的用户目录（`%LOCALAPPDATA%\Programs\…`），**不装**到 Program Files，也**加不了**防火墙规则 —— 这种机器要照《部署指南》7.5 在管理员账户下手工放行一次。
+- **② 安装时会自动关闭正在运行的旧版本**：升级前**不用手工退出**「赛事积分榜」——安装程序会自己找到在跑的旧版本进程并关掉（连它拉起的 `scoreboard.exe` 服务端进程一起关）。以前那个「请先关闭程序」的提示框会被新界面压在下面，看不到又挡着流程，现场很容易卡在那儿出不来。
+- **③ 安装位置（装到哪个目录）**：
+  - 向导里**默认填这台机器上次装的那个目录**；
+  - 切换「为所有用户安装 / 仅为我安装」时，**目录输入框会跟着变成该模式的默认目录**（分别是 `C:\Program Files\Scoreboard_Console` 和你的用户目录）；
+  - 但你**手工改过路径（或点过「浏览…」）之后，再切模式也不会冲掉你填的那个目录** —— 想回到模式默认目录，把路径清空重新切一次模式即可；
+  - 想知道这次装到哪了：右键桌面「赛事积分榜」快捷方式 →「属性」→ 看「目标」。
+- **静默安装**（`安装包.exe /S`，无人值守用）：**会跳过旧版本卸载器** —— 旧卸载器自己可能弹一个没人能点的提权框，跳过它才能保证无人值守下一定跑得完。静默安装也可以用 `/allusers` / `/currentuser` 指定装法；用 `/D=` 指定目录时**以 `/D=` 为准**（不取「上次安装目录」的记忆）。
+- 装到哪、装什么、桌面快捷方式（「赛事积分榜」）、卸载方式、数据与配置在 `%LOCALAPPDATA%\ScoreboardConsole\`（**覆盖安装不会丢**）—— 这些与升级前一致（交互式升级仍会先跑一遍旧版本的卸载器，这也是数据不能放在安装目录里的原因，见《部署指南》3.4）。

 ### ④ 升级后建议：把新版规则包重新导入一次

@@ -4,6 +4,7 @@
 > 给负责收表、填表的同志看即可，不需要懂系统内部。
 >
 > 配套模板可在系统里直接下载：**基础数据 → 报名导入 →「中文表头」/「英文表头」**（两个文件列数与列顺序完全一样，只有表头语言不同，按手上表格的样子选）。
+> 小项与组别很多时，同一处还有**「分工作表 · 中文表头 / 分工作表 · 英文表头」**：一个小项组别再抄串——**一个小项 × 一个组别一张工作表**，表名写成「小项名称@组别名称」，详见第八节。

 ---

@@ -19,12 +20,14 @@

 一共 12 列。系统**同时认两套表头**——英文一套、中文一套，**两套都能导入**，也可以**中英混着写**（每一列各自认名字，例如英文 `event_code` 配中文「姓名」）。**英文是规范列名**：老的英文模板一个字都不用改，照常导入；中文只是给习惯看中文的人用的同义写法。

-下载模板时有两个按钮，按手上表格的样子选：
+下载模板时按手上表格的样子选：

 - 「**中文表头**」→ 文件 `entries-template-zh.csv`
 - 「**英文表头**」→ 文件 `entries-template-en.csv`
+- 「**分工作表 · 中文表头**」/「**分工作表 · 英文表头**」→ 文件 `entries-template-zh.xlsx` / `entries-template-en.xlsx`
+  （一个小项组别一张工作表，见第八节；表头语言与上面两个按钮同一套口径）

-两个文件**列数与列顺序完全一样，只有表头语言不同**，示例行也一样。列的**先后顺序可以随便调**，多出来的列系统会忽略。
+单表模板的两个文件**列数与列顺序完全一样，只有表头语言不同**，示例行也一样。列的**先后顺序可以随便调**，多出来的列系统会忽略。

 | 英文表头（规范列名） | 中文表头（同义写法） | 这一列是 |
 |---|---|---|
@@ -208,6 +211,7 @@
 - [ ] `status` 只用那 4 个英文词（大小写都行）或第三节列的中文别名，不写别的词；拿不准就留空
 - [ ] `heat` 要么留空，要么是 1–999 的整数（不参与算分，只是录入分组）
 - [ ] 全表没有因为"怕麻烦"把某些列删掉——**表头 8 个必须列一个都不能少**（哪怕整列是空的）
+- [ ] 用的是**分工作表模板**时：每张工作表的名字都是「小项名称@组别名称」、没有多余的工作表；「项目编码 / 组别」两列要么整列留空、要么与表名一字不差（见第八节）

 ---

@@ -233,7 +237,9 @@
 | 第 N 行：heat 需要是 1-999 的整数（留空表示未分批） | `heat` 填了非整数、0、负数或超过 999 的值（如 `第1批`、`一组`、`1000`） | 改成 1–999 的整数，或者整格留空（= 未分批）；批次只影响录入分组，不参与算分 |
 | 提示「冲突」，人员没有写入 | 按证件号（或号码布、「姓名 + 单位」唯一命中）的人在系统里已有记录，但姓名 / 证件号 / 性别 / 年龄 / 单位 / 号码布跟表里**对不上** | 在导入结果里逐条选「保留已有数据」或「使用新数据」，选完再提交 |
 | 文件传不上去 | 超过 32MB | 拆分上传，或改用 xlsx |
-| 只导入了第一张表 | xlsx 只读第一个工作表 | 把要导入的数据放在第一个工作表里 |
+| 工作表「XXX」没能定出是哪个小项、哪个组别 | 这是一份**分工作表模板**（有工作表名里带 `@`），但工作簿里混进了别的表（备注表、说明表），或者表名写得不合规 | 删掉多余的工作表，或把表名改成「小项名称@组别名称」（见第八节）；只有一张表、数据都在里面时，把它存成 CSV 用单表模板导 |
+| 本行项目编码 XXX 不是工作表名里那个小项 / 本行组别 XXX 与工作表名里的组别不一致 | 分工作表模板里范围由**工作表名**决定，而这一行的「项目编码 / 组别」两格又填了别的值 | 把那两格**清空**（留空即按工作表名走），或改成与工作表名一致的值 |
+| 工作表「XXX」是隐藏表，按约定不参与导入 | 工作簿里有隐藏工作表 | 要在它里面导数据就先取消隐藏并改名成「小项名称@组别名称」，否则忽略这条提示即可 |

 ---

@@ -254,7 +260,73 @@

 ---

-## 八、给填写人的最短提示（一页版）
+## 八、分工作表模板（一个小项组别一张表）
+
+前面几节讲的都是**单表模板**：一份表装下全部报名，「项目编码」与「组别」两列每行都要抄一遍。
+小项一多（几十个小项 × 几个组别），抄这两列又累又容易串行——所以系统还提供一种
+**分工作表模板（xlsx）**：**一个小项 × 一个组别 = 一张工作表**，范围写在**表名**上，数据区只填人。
+
+> 两种模板**都能导入**，谁也替代不了谁：单表 CSV 老填表人照旧用，分工作表模板给「一个小项组别再抄串了」的场合。
+> 「基础数据 → 报名导入」里四个下载按钮分别对应：**中文表头 / 英文表头**（单表 CSV）、
+> **分工作表 · 中文表头 / 分工作表 · 英文表头**（xlsx）。
+
+### 8.1 工作表怎么命名
+
+| 规则 | 说明 |
+|---|---|
+| 表名 = **小项名称** `@` **组别名称** | 例如小项「100 米跑」+ 组别「男子组 30岁以下」→ 工作表名 `100 米跑@男子组 30岁以下` |
+| 用的是**名称**，不是编码 | 就是「基础数据 → 大项 / 小项」里的小项名、「组别」里的组别名，一字不差 |
+| 一张表只能对一个组合 | 一个小项组别一张表；两列都不用填——**范围由表名说了算** |
+| 表名里**不能有** `@` 以外的花样 | `:` `\` `/` `?` `*` `[` `]` 会被系统自动换成同形的全角字符（Excel 不允许工作表名里有它们） |
+
+**小项名称与组别名称里禁止使用 `@`（全角 `＠` 也不行）。** 理由是它就是表名里的分隔符：
+名字里再出现一个 `@`，系统就分不清哪个 `@` 是分隔符、哪一个是名字的一部分。
+- 界面（新建 / 编辑小项、编辑组别）会当场拦下并说明原因；
+- 规则包里的小项名同样拦；服务端接口也拦（改接口、导 Excel 都绕不过去）；
+- **已经存在**的历史名字里若带 `@`：不影响任何报名、成绩与积分，但**分工作表模板会生成不出来**——
+  下载时会明确告诉你「哪一个小项 / 组别带 @，请先改名」，改名后再下载即可（改名不丢数据）。
+
+### 8.2 数据怎么填
+
+- 每张工作表**第 1 行就是表头**（与单表模板同样的 12 列、中英两套都认），**从第 2 行开始填人**；
+- **「项目编码」「组别」两列可以整列留空**——表名已经说明了是哪个小项、哪个组别；
+  一旦填了，就**必须与表名一致**，不一致的那一行会报错并跳过（系统不猜、也不会挑一个用）；
+- 其余列与单表模板完全一样（第三节逐列说明照样适用）；
+- **只填了表头、没填人的那张表**会被跳过并给一条提示（= 这个组别没人报名），其余表照常导入；
+- 不要在工作簿里加「说明」之类的工作表：**只要工作簿里有一张表名带 `@`**，整份文件就按分工作表模板处理，
+  其它表名（例如 `Sheet1`、`备注`）必须也是「小项名称@组别名称」的形状，否则**整份拒绝**并点名是哪张表——
+  静默跳过意味着你填在第 3 张表里的几十行数据无声消失，结果面板上却还显示「导入成功」。
+
+### 8.3 表名太长、或者两个组合撞名了怎么办
+
+Excel 对工作表名有硬限制：**最长 31 个字符**，同一份工作簿里**不能重名**。系统的处理是确定的，不用你操心：
+
+- **太长**：小项名与组别名各保留开头的一段（小项名优先保留，组别名至少留 8 个字符），拼起来不超过 31 字符。
+  截断后的表名仍是原名的一段开头（保留头部、去掉尾巴），人一眼能认出是哪一项：小项名
+  `第三届全国职工运动会田径比赛男子甲组100米跑决赛` + 组别名 `30岁以下公开组`，算出来是
+  `第三届全国职工运动会田径比赛男子甲组100米@30岁以下公开组`（小项名留下 22 个字符，组别名留下 8 个）；
+- **撞名**：截断后如果两张表名字一样，后一张会自动加 `(2)`、`(3)` 后缀（Excel 里重名会让后一张把前一张**覆盖掉**，数据无声消失，所以这一步必须做）；
+- 下载下来的模板里这些名字**是最终名字**，照原样填、原样传回来即可；**不要手工改工作表名**，改了就对不上号了。
+
+> 小项或组别**改过名字**（或改了截断规则之后重新下载）时：旧模板里的表名对不上新名字，导入会报
+> 「工作表『XXX』没能定出是哪个小项、哪个组别」。这时**重新下载一份模板**、把数据粘过去最稳。
+
+### 8.4 与单表模板的关系
+
+| | 单表模板（CSV / XLSX） | 分工作表模板（XLSX） |
+|---|---|---|
+| 文件形态 | 一张表装全部报名 | 一个小项组别一张工作表 |
+| 范围从哪来 | 每行的「项目编码 / 组别」两列 | **工作表名**（「项目编码 / 组别」可留空） |
+| 表名限制 | 随便（`Sheet1`、`报名表` 都行） | 必须「小项名称@组别名称」 |
+| 多张工作表的文件 | 只读第一张，其余在导入结果里提示「没有读」 | 每张表各导各的 |
+| 适合 | 零散补报、小规模、沿用老表格 | 小项组别多、按项目分工填表 |
+
+两种模板**解析口径完全一致**：表头、认人顺序、冲突处理、行级报错都共用同一套代码，
+只有「范围从哪来」这一点不同。
+
+---
+
+## 九、给填写人的最短提示（一页版）

 > 1. 用系统里下载的模板（**中文表头 / 英文表头都能用**，见第二节），**第一行不要动**、同一列不要写两遍；
 > 2. **一个人一行**；一个人报几项就写几行；
@@ -48,12 +48,15 @@ deploy\build.bat

 ### 3.1 使用安装包

-1. 双击 `Scoreboard Console-<版本>-x64.exe`（版本以 `dist\console\` 下实际文件名为准）。
-2. 按向导选择安装目录（可自定义）。
-3. 安装完成后，桌面会出现名为**「赛事积分榜」**的快捷方式。
+1. 双击 `Scoreboard Console-<版本>-x64.exe`（版本以 `dist\console\` 下实际文件名为准）。**安装程序一启动就会申请管理员权限**：Windows 会先弹一次 UAC（「是否允许此应用对你的设备进行更改？」），点「是」。**受限账户（不是管理员）的机器不会弹** —— 它拿不到「为所有用户」那一档，安装程序会自动降级为「仅为我安装」（见第 2 步）。
+2. 按向导选**装法与安装目录**：
+   - **「为所有用户安装」**（新版默认）：装到 `C:\Program Files\Scoreboard_Console`，并在这一趟**自动放行防火墙入站 19540**（防火墙里能看到规则 `Scoreboard Console (TCP 19540)`，卸载时自动删掉）。**升级时不用手工关掉旧版本** —— 安装程序会自己找到并关闭在跑的旧版本（含它拉起的 `scoreboard.exe` 服务端进程），见 3.4。
+   - **「仅为我安装」**：装到当前用户的目录（`%LOCALAPPDATA%\Programs\Scoreboard_Console`；受限账户会落到这一档）；**不加防火墙规则**，局域网大屏要照 7.5 手工放行一次。
+   - **安装位置**：向导里**默认填这台机器上次装的目录**；切换上面两种装法时，目录输入框会跟着变成该模式的默认目录；**手工改过路径（或点过「浏览…」）之后再切模式也不会冲掉你填的** —— 想回到模式默认目录，把路径清空重新切一次模式。
+3. 安装完成后，桌面会出现名为**「赛事积分榜」**的快捷方式（右键 →「属性」→ 看「目标」，可确认这次装到了哪个目录）。
 4. 双击「赛事积分榜」启动。

-> 赛事数据、配置与规则都存放在 `%LOCALAPPDATA%\ScoreboardConsole\`（不随安装目录走，见 3.4、3.5）；服务端日志在数据目录的 `data\logs\` 下，Console 自己的 `console.log` 在安装目录的 `logs\` 下（见第 10 节）；安装目录本身只要当前用户可写即可。
+> 赛事数据、配置与规则都存放在 `%LOCALAPPDATA%\ScoreboardConsole\`（不随安装目录走，见 3.4、3.5）；服务端日志在数据目录的 `data\logs\` 下，Console 自己的 `console.log` 在**安装目录**的 `logs\` 下（见第 10 节），所以**安装目录要当前账户写得进去**。⚠️ 新版安装器默认装到 `C:\Program Files\Scoreboard_Console`；如果装完发现「运行日志」面板一直是空的、安装目录下没有 `logs\console.log`（多半就是写不进去），**改装到一个当前账户可写的普通目录**（例如 `D:\Scoreboard`）重装一次即可。

 ### 3.2 使用免安装包

@@ -101,7 +104,7 @@ deploy\build.bat

 ### 3.4 数据放在哪里（升级/卸载都不会删）

-覆盖安装时安装程序会**先静默运行旧版卸载器**，而卸载器会把整个安装目录删掉，所以数据库、规则、用户、上传的图片与字体都不能放在安装目录里。现在的规则：
+覆盖安装时安装程序会**先静默运行旧版卸载器**，而卸载器会把整个安装目录删掉，所以数据库、规则、用户、上传的图片与字体都不能放在安装目录里。**例外**：用 `安装包.exe /S` 做的**静默安装会跳过旧卸载器**（旧卸载器在无人值守的会话里可能弹一个没人能点的提权框）—— 但这只影响静默安装那一条路，手工卸载与交互式升级照样会删安装目录，所以数据仍然必须放在安装目录之外。现在的规则：

 | 场景 | 数据目录 |
 | --- | --- |
@@ -405,8 +408,10 @@ scoreboard.exe passwd -config "%LOCALAPPDATA%\ScoreboardConsole\config.yaml" -da

 **防火墙要放行入站 19540**（默认端口，改过端口就换成实际端口）。安装包会替你放行，分两种情况：

- 安装时选了**「为所有用户安装」**：安装程序会弹 UAC 提权，**提权那一趟就顺手把入站 19540 放行了**（规则名 `Scoreboard Console (TCP 19540)`），装完不用再管；卸载时会自动把这条规则删掉。
- 安装时选了**「仅为我安装」**：全程不申请提权，装不了防火墙规则，**必须手工放行**。也可以重新跑一次安装程序、这次选「为所有用户安装」，让它自动放行。
+- 安装时选了**「为所有用户安装」**：**提权那一趟就顺手把入站 19540 放行了**（规则名 `Scoreboard Console (TCP 19540)`），装完不用再管；卸载时会自动把这条规则删掉。
+- 安装时选了**「仅为我安装」**：这一趟**不加防火墙规则**（装到用户目录，安装程序只在「为所有用户安装」那一档才去改防火墙），**必须手工放行**。也可以重新跑一次安装程序、这次选「为所有用户安装」，让它自动放行。
+
+> ⚠️ **新版安装器一启动就会申请管理员**（`RequestExecutionLevel highest`，见 3.1）：**管理员账户**的机器上，双击安装包先弹一次 UAC，**无论最后选哪种装法都会弹这一次** —— 选「为所有用户安装」才顺手放行防火墙、装到 `C:\Program Files\…`；选「仅为我安装」只装到用户目录、不加规则。**受限账户**的机器不弹 UAC，会自动落到「仅为我安装」那一档，所以这种机器一定要手工放行。

 手工兜底（给「仅为我安装」的机器，以及改过端口、装了才发现要放行的机器）——在**管理员** cmd 里跑：

@@ -453,7 +458,7 @@ http://<主机IP>:19540/display

 - 这个地址不用手敲：管理端「大屏控制 → 局域网大屏」卡片里有**可复制的完整链接**与**二维码**（第一个地址），别的设备扫码或在浏览器里粘贴即可打开（该卡片需录入员及以上登录才看得到）；
 - 需要主机设置固定 IP，且设备与主机在同一局域网；
- **主机防火墙要放行入站 19540**（默认端口）：装的时候选**「为所有用户安装」**，安装程序提权时会自动放行，不用再管；选了「仅为我安装」就得手工放行一次，命令与说明见 7.5；
+- **主机防火墙要放行入站 19540**（默认端口）：**「为所有用户安装」会自动放行**（那一档提权时装好规则），不用再管；**「仅为我安装」不加规则、必须手工放行一次**（命令与说明见 7.5）。装的时候选哪一档，取决于 3.1 里那几行 —— 新版安装器一启动就申请管理员，但只有「为所有用户」那一趟才顺手改防火墙；
 - 安卓电视一般常亮，无需额外防熄屏；
 - 浏览器方案**不受** Console 的 kiosk、防熄屏、选屏控制，字体与动画表现以实际设备为准；
 - 现场以 Console + HDMI 为主方案，浏览器访问作为备用。