Scoreboard/docs/使用手册.md

# 使用手册

> 面向现场操作人员与管理员。管理面板地址：`http://<主机IP>:19540/admin`；大屏地址：`http://<主机IP>:19540/display`。
>
> 具体按钮文案与页面布局以实际界面为准；本文按当前版本整理。

---

## 1. 角色与权限

系统只有三种身份，权限是包含关系：**管理员 ⊇ 录入员 ⊇ 访客**。

| 身份 | 说明 | 能做什么 |
| --- | --- | --- |
| 访客 guest | 未登录时的默认身份，不需要建账号 | 只读查看积分榜、成绩、基础数据等公开数据；不能录入、发布、改配置 |
| 录入员 recorder | 现场记录员 | 访客全部权限 + 成绩录入 / 存草稿 / 发布 / 撤销发布 / 破纪录确认 / 积分调整 / 大屏控制 / 变更历史 |
| 管理员 admin | 赛事管理员 | 录入员全部权限 + 系统设置、用户管理、备份、审计日志、规则包与赛事项目包导入导出 |

> 未登录也能进管理面板，只是所有写操作按钮被禁用，顶部会出现「当前为访客只读视图」提示。

### 1.1 登录

1. 打开管理面板地址，进入登录页；
2. 输入账号与密码，点「登录」；
3. 首次登录或密码被管理员重置后，会自动跳到「修改密码」，改完才能继续；
4. 也可以点「以访客身份只读浏览」直接查看数据。

### 1.2 退出

点击右上角用户名旁的**退出**图标，即退出登录并回到只读访客视图。

---

## 2. 界面总览

左侧导航按用途分组：

| 分组 | 页面 |
| --- | --- |
| 总览 | 仪表盘 |
| 成绩 | 成绩录入、成绩审核、破纪录、积分调整 |
| 榜单 | 积分榜、大屏控制 |
| 数据 | 基础数据、导出、变更历史、日志 |
| 系统 | 系统设置、修改密码、关于 |

顶部栏显示：实时连接状态、服务端版本、刷新按钮、当前账号与角色、退出按钮。左侧栏底部有快捷键提示：`Ctrl+Enter` 存草稿、`Alt+Enter` 发布。

---

## 3. 仪表盘

用于快速掌握全局：

- 领先单位、已发布项目数 / 总项目数、纪录条目数、实时连接状态；
- 「当前赛程」列出小项及状态（已发布 / 待录入），点「录入」直接跳到该项目；
- 「实时积分 Top 3」显示前三名与奖牌数；
- 有待录入项目时显示「待办」提醒。

---

## 4. 成绩录入

### 4.1 选择项目

1. 左侧「项目」列表按大项分组，点选要录入的小项；
2. 每个小项带状态徽标：**已发布** 或 **待录入**；
3. 多个组别时，表格上方出现组别页签，切换组别分别录入；
4. 配了「按队内平均」通道的小项（例如「个人+团体」项目的团体通道），工具栏下方会出现 **「平均值口径」单选**：`只算有效成绩`（没有有效成绩的人不进分母）或 `全部报名人员都计入`（没成绩的按 0 计入平均）。点选后立即保存到该小项，不需要另外点保存；这是小项级设置，该小项的所有组别共用。

> 团体成绩 = 该单位在本组别所有报名项成绩的平均值（成绩从每个人那一行读），由系统算出来：正常流程是给每个参赛人员各报一条（走 10.7 的「个人报名」），成绩照常录到每个人那一行，团体那一行（如果也报了）不用填成绩。
> 选「全部报名人员都计入」时，只报了单位、一个人都没报（或队员都没成绩）的那条报名也会按 0 进分母，会把该单位的平均成绩拉低；口径与算法见 10.2「大项 / 小项」与 10.4「计分通道」。

### 4.2 录入成绩

表格列依次为：号码、单位、运动员 / 队、成绩输入、名次、状态、积分（自动）、备注。

| 列 | 操作 |
| --- | --- |
| 成绩输入 | 直接输入成绩。时间类项目按 `1:06.33` 格式；工具栏会提示当前单位（秒 / 米 / 次 / 分） |
| 名次 | 自动排名项目由系统自动计算，不可编辑；手动名次项目（录入方式为「手动名次」或比较方式为「不比较」）可直接填名次 |
| 状态 | 下拉选择：**有效**、**DNS 弃赛**、**DQ 取消**、**DNF 未完赛**、**退赛** |
| 积分（自动） | 随成绩实时计算，仅供参考 |
| 备注 | 自由填写 |

右侧「实时积分预览」显示：若现在发布，各单位积分的变化、最大分差、受影响单位数。

### 4.3 键盘流与批量录入

| 操作 | 效果 |
| --- | --- |
| `Tab` | 跳到下一个单元格（浏览器原生焦点顺序） |
| `Enter` | 在成绩格之间依次移动 |
| `Ctrl+Enter` | 存草稿 |
| `Alt+Enter` | 发布当前项目 |
| 「按成绩重排」 | 按成绩从小到大 / 从大到小重排表格行（名次仍以比较值为准） |
| 「下一格」 | 按钮方式移动焦点 |

**从 Excel 粘贴**：复制区域后，在成绩格按 `Ctrl+V`。

- 两列及以上：第一列按单位名称 / 简称匹配行，最后一列作为成绩；
- 单列：从当前行开始向下依次填充。

### 4.4 防呆校验

页面下方「防呆校验」会实时列出问题：

- **错误（阻止发布）**：缺少成绩、成绩格式无法解析、手动名次项目缺少名次；
- **提醒（不阻止发布）**：成绩 ≤ 0、名次重复（请确认是否并列）、成绩与赛会纪录差距过大。

有错误时点「发布」会被拦下并提示第一处问题。

### 4.5 存草稿与发布

1. **存草稿**：保存当前组别的成绩，草稿**不会上屏**，也不计入积分榜；有未保存修改时页面会显示「有未保存修改」徽标。
2. **发布**：点击后弹出确认框，显示本次影响的单位数与最大分差；确认后成绩立即上屏并重算积分榜。
   - 发布前系统会自动把当前内容整组保存为草稿再发布，无需手动先存；
   - 示例数据模式下「发布」按钮不可用，避免把未落库的改动当成发布成功。

### 4.6 撤销发布

已发布的组别会出现「撤销发布」按钮：

1. 点击后在确认框中确认；
2. 系统作废该组已产生的积分流水，大屏回退到发布前状态；
3. 修改后重新发布即可。全程留痕，可在「变更历史」查看。

---

## 5. 成绩审核

用于在发布前统一复核草稿。

1. 左侧「待审草稿」按「小项 + 组别」分组，显示每组草稿条数，可搜索小项 / 组别 / 单位；
2. 点选一组后，右侧显示该组成绩明细（单位、运动员 / 队、成绩、名次、状态、积分）；
3. 用「整组对比 / 逐条对比」切换，查看发布后各单位积分的变化；
4. 「发布影响」列出受影响单位与分值变化；
5. 操作：
   - **发布整组**：确认后整组发布并重算积分榜；
   - **退回**：当前版本服务端没有「退回」接口，此操作**仅在管理端本地标记**，不会改动成绩数据；刷新页面后标记可能消失。如需真正退回，请通知录入员到「成绩录入」修改后重新保存。

> 草稿态永远不会上屏；发布以「小项 + 组别」为一组整体生效。

---

## 6. 破纪录

页面顶部会显示破纪录加分开关状态（来自规则包 `recordBonus.enabled`）。当前版本默认关闭；若当前角色读不到规则包，会如实显示「未知」，以服务端校验结果为准。

### 6.1 疑似破纪录

- 系统用**已发布且有效**的成绩与当前纪录自动比对，推导出疑似破纪录，草稿不参与；
- 列表显示小项、组别、单位 / 运动员、成绩、原纪录、档位（赛会 / 市级 / 省级 / 全国）、预计加分；
- **确认加分**：登记破纪录并生成加分流水、更新纪录库；开关关闭时按钮不可用；
- **拒绝**：当前版本服务端没有拒绝接口，此操作只在本地隐藏该条，刷新后会重新出现。

### 6.2 纪录库

- 按小项分组展示，可用「全部 / 赛会 / 市级 / 省级 / 全国」页签筛选，也可搜索小项或保持者；
- 每行显示档位、成绩、保持者、单位、达成时间、来源（本届 / 历史）以及是否为当前纪录。

---

## 7. 积分调整

用于人工加减分，全程留痕。

页面顶部显示人工调整开关状态（规则包 `manualAdjustment.enabled`）。若已关闭，「新增调整」按钮不可用。

### 7.1 新增调整

点「新增调整」，填写：

| 字段 | 说明 |
| --- | --- |
| 单位 * | 下拉选择参赛单位 |
| 分值 * | 正数加分、负数扣分，不能为 0 |
| 类别 * | 处罚 / 补分 / 更正 |
| 关联项目 | 可选，关联到具体小项 |
| 理由 * | 必填，会写入审计日志 |

保存后积分榜实时更新。

### 7.2 查看与作废

- 列表可按类别筛选、按单位或理由搜索，分页浏览；
- 点某行的「作废」，填写作废理由并确认，对应积分流水会一并作废；
- 已作废的记录仍保留在列表中，状态显示「已作废」。

---

## 8. 积分榜

顶部页签：**单位总分榜**、**团体奖牌榜**、**个人积分榜**；右侧搜索框可按单位或运动员过滤。

### 8.1 单位总分榜

- 列：名次、单位、总分、金、银、铜、变化、明细；
- 「变化」列显示名次升降（如 `↑2`、`↓1`）；
- 点「展开」下钻该单位的积分明细，右侧面板显示合计与每一条得分来源（项目、组别、运动员、成绩、名次、积分），每一分都可溯源。

### 8.2 团体奖牌榜 / 个人积分榜

- 团体奖牌榜显示金、银、铜与合计；
- 个人积分榜显示运动员、单位、个人总分与奖牌数。

### 8.3 推送明细到大屏

1. 展开某个单位的明细；
2. 点「推送到大屏」；
3. 所有大屏会弹出半屏明细覆盖层，**60 秒后自动关闭**；
4. 想立即关闭，点页面顶部「关闭大屏明细」并确认。

---

## 9. 大屏控制

| 区块 | 操作 |
| --- | --- |
| 切页 | 选择「总积分榜 / 团体奖牌榜 / 个人积分榜 / 最新成绩」，点「立即跳转」 |
| 锁定与刷新 | **锁定**：停止自动轮播并停在当前页；**解锁**：恢复轮播；**强制刷新**：让所有大屏重新拉取快照，用于排障 |
| 公告 | 输入公告文字，设置「滚动时长」（5–120 秒，实际是全屏展示的秒数），点「推送公告」；点「清除公告」撤下当前公告 |

页面顶部徽标显示当前是「轮播中」还是「已锁定」。

**公告**：点「推送公告」后所有大屏先**全屏**展示这条公告，到时间后自动退回原来的页面（没锁定就继续轮播），公告正文留在底栏的「公告」槽位继续显示，直到被新公告替换或点「清除公告」。公告卡片顶部徽标显示「当前公告：有 / 无」，徽标下面那一行就是当前公告正文（没有公告时显示「暂无公告（大屏底栏显示占位）」）。公告会随赛事设置保存：新开的大屏窗口、断线重连之后，会先把当前公告再全屏播一遍（默认 15 秒）后留在底栏；点「清除公告」后底栏回到「暂无公告」占位。

**在线看板**：本页这块在线状态是**本机占位显示**（管理端网页没有接服务端的实例接口），因此恒显示「未知」，「最近下发」只是本机下发指令的时间，**不代表大屏在线**。要看真正在线的实例，用**服务管理窗口**的「已连接的大屏实例」卡片——它读服务端的 `GET /api/display/instances`，每 5 秒刷新一次，列出在线实例数与各自页面（需先以记录员及以上身份在管理面板登录过）。

### 9.1 显示器菜单（重建被关掉的大屏窗口）

扩展屏上的大屏窗口平时由服务管理程序（Console）按配置自动开出来，只有在**有人手动关掉了某块屏的大屏窗口**时才需要这一节。

这张「显示器」卡片只在**从服务管理窗口点「打开服务端管理面板」打开的面板**里可用；用浏览器直接打开管理面板时，卡片只显示一行提示，这是正常的。

1. **窗口页面**：先选好新窗口锁定显示哪一页（默认「总积分榜」）；
2. **显示器列表**：逐块屏列出名称、分辨率、缩放、是否主显示器，以及当前是否已开窗口（「已开窗口（全屏）」「已开窗口（窗口化）」或「未开窗口」）；
3. **每行的按钮**：
   - 该屏已经有窗口 → **聚焦窗口**：把窗口提到最前，不重建、不打断正在展示的比分；
   - 该屏还没有窗口，且允许多屏全屏 → **创建全屏窗口**；
   - 该屏还没有窗口，但不允许全屏 → **创建窗口（窗口化）**，行内会注明「单显示器 / 主显示器只能窗口化」；
   - 已开窗口的行还有一个 **关闭窗口**：全屏大屏窗口是锁定鼠标的，万一开到了错误的屏上，从大屏本身退不出来，用这个按钮收掉；
4. **重新排布（按设置重建全部窗口）**：按服务管理程序里的选屏配置重建所有大屏窗口。不在该配置范围内的窗口会被关掉，所以日常只想恢复某一块屏时，请优先用上面的「创建」按钮。

**为什么单显示器 / 主显示器只能创建窗口化窗口**：全屏窗口会盖住整块屏，而且没有标题栏和关闭按钮。单显示器上开全屏，等于把操作人员的桌面整个盖住；主显示器上开全屏，会把服务管理窗口、管理面板这些工作窗口全部遮住——现场又没有键盘可以退出来。所以这两种情况下按钮只提供窗口化：窗口约占屏幕 80%、居中显示、带标题栏，随时可关。只有「本机有多于一块显示器，且目标不是主显示器」时才放行全屏。

**副屏全屏窗口被误关后，一键恢复**：

1. 在服务管理窗口点「打开服务端管理面板」；
2. 进入管理端「大屏控制」页；
3. 在「显示器」卡片里找到那块副屏（那一行没有「主显示器」标记，且分辨率/缩放与副屏一致），点它的 **创建全屏窗口**；
4. 列表刷新后该行显示「已开窗口（全屏）」，副屏上即出现全屏积分榜。

多块副屏都被关掉时，在同一张卡片里逐块点「创建全屏窗口」即可；改用「重新排布」也行，但前提是这些屏都在 Console 的选屏配置里。

---

## 10. 基础数据

页面分七个分区，从左到右依次是：参赛单位、大项 / 小项、组别、计分通道、积分模板、运动员、报名导入。

### 10.1 参赛单位

1. 点「新增单位」；
2. 填写代码 *（唯一，字母 / 数字 / `_` / `-`，最长 16 位）、全称 *、简称、主题色、排序、logo（可点输入框右侧「上传图片」直接传，png / jpg / webp / gif，单张不超过 5 MiB；也能手填已有路径，留空则不显示）；
3. 「编辑」修改；「停用」为软删除——历史成绩与积分流水保留，但新报名不再可选该单位，可随时「启用」。

> 上传的 logo 会显示在**大屏**的总积分榜、团体奖牌榜、分项成绩与个人积分奖牌榜上（个人积分奖牌榜显示在运动员姓名前面）；没传 logo 的单位不占位，队名不会因此错位。管理端页面不显示 logo。

### 10.2 大项 / 小项

1. 左侧选择或新增大项（编码、名称、简称、默认积分模板、排序）；
2. 右侧维护该大项下的小项：点「新增小项」，填写编码、名称、类型（个人 / 团体 / 对抗 / 比赛 / 个人+团体）、录入方式（自动排名 / 手动名次）、成绩类型（时间 / 距离 / 计数 / 得分 / 无成绩）、比较方式（越小越好 / 越大越好 / 不比较）、状态、是否计分等；
3. 小项行上的「配置组别」「配置计分通道」可直接跳到对应分区；
4. 删除大项 / 小项会二次确认。

**「个人+团体」是什么**

用于团体与个人赛事合并的项目：同一条成绩会同时按个人通道与团体通道记分（具体通道见 10.4「计分通道」）。

- 个人通道按个人成绩排名给分，分**只记在个人积分榜**，不计入单位总分；
- 团体通道把本单位成员在该组别的成绩**取平均**后排名，按团体模板给分，这部分才进单位总分；
- 平均值的分母（「平均值口径」）在**成绩录入页**选，见 4.1：`只算有效成绩`时，一个人都没成绩的单位不参与团体排名、不得分；`全部报名人员都计入`时，没成绩的按 0 计入，分母是本单位在该组别的报名条数（一人一条报名时就是报名人数）。

**配一个「个人+团体」小项的完整链路**

1. 在「大项 / 小项」新建小项，类型选「个人+团体」，保存；
2. 到「组别」分区配置组别（团体平均是按组别算的，参赛的组别都要有）；
3. 到「计分通道」分区配上两条通道并「保存全部」——新建小项不会自动生成通道：
   - 个人通道：名次范围 `个人名次`、名次来源 `按成绩自动排名`、选个人积分模板、**「计入单位总分」取消勾选**；
   - 团体通道：名次范围 `团体名次`、名次来源 `按队内平均`、选团体积分模板、「计入单位总分」保持勾选；
   - （导入规则包时，规则包里的 `channelTemplates` 会按项目类型自动生成这两条通道，见 11.3。）
4. 到「报名导入」把参赛人员报上：切到「个人报名」一人报一条（团体平均取的就是这些人的成绩）——注意「个人+团体」类型默认停在「团体报名」页签，要手动切过去；只想让某个单位参加团体、暂不登记具体人员时，也可以用「团体报名」只报单位；
5. 到「成绩录入」逐人录成绩，顺便在「平均值口径」里选好分母口径；发布后个人榜与单位总分同时更新。

> 「个人+团体」项目的个人通道要有成绩才给分，所以参赛人员必须按人报名（团体报名只报单位不会产生个人成绩）。

### 10.3 组别

1. 先在上方选中一个小项；
2. 点「新增组别」，填写名称、权重、性别、年龄上下限；
3. 用「上移 / 下移」调整顺序，「移除」删除；
4. 点「保存全部」整体替换该小项的组别配置。**若该项目已有报名数据，服务端会拒绝替换。**

### 10.4 计分通道

通道 = 「排谁的名次 + 名次从哪来 + 用哪张积分模板」。

1. 先选中一个小项；
2. 点「新增通道」逐条配置，同一「名次范围 + 名次来源」只能有一个通道；
3. 点「保存全部」整体替换该小项的通道配置；
4. 标记为「不计分」的小项，通道可以保存但不参与积分计算；
5. 「名次来源」选「按队内平均」时，把同一个单位（或个人）在该组别的成绩**取平均**后排名，并列按积分模板的并列口径处理（默认顺延）；平均值分母取录入页选的「平均值口径」——`只算有效成绩`时是本单位有有效成绩的条数（一个人都没有效成绩的单位不参与团体排名、不得分），`全部报名人员都计入`时是本单位在该组别的报名条数（没成绩的按 0 计入）。报名表里 `status` 不是 `registered` 的报名项（弃赛 / 取消）既不算参与，也不进分母；
6. 每条通道有一个「计入单位总分」开关，默认打开。关掉后该通道的分只记在个人头上，不进单位总分——「个人+团体」项目的个人通道就靠它做到只记个人。

### 10.5 积分模板

1. 左侧点「新建」创建模板，填写编码、名称、并列处理、破纪录加分、录取名次、末位归零；
2. 在「名次 → 分值」表格里添加 / 移除分值明细；
3. 保存会整体替换该模板的分值明细，请核对后再保存；
4. 页面下方的「榜单口径（全局）」卡片设置**个人项目得分折算系数**（默认 1，步进 0.1，必须大于 0 且不超过 100）：`单位总分 = Σ 只记单位的流水 + 系数 × Σ 记到个人的流水`。它是**全局**设置（键名 `standings.individual_to_team_weight`，不随某一张模板保存，所有模板与所有计分通道共用；导入规则包时，规则包里的同名配置会覆盖它），只有管理员能改，点「保存榜单口径」后榜单按新系数立即变化。「个人+团体」项目的个人通道已经用「计入单位总分」关掉了折算，这里的系数对它没有影响。

### 10.6 运动员

1. 点「新增运动员」，填写姓名 *、性别、年龄、所属单位 *、工号 / 学号、证件号、号码布等（年龄可留空，填了必须是 0–120 的整数）；
2. **证件号（如身份证号）与号码布二者取其一**即可唯一标识一个人，用于区分重名；两个人员不能共用同一个证件号，也不能共用同一个号码布，重复会被拒绝；没有身份证信息的人可以只填号码布。已有历史数据两项可以都为空；
3. 「编辑」修改，「停用」后不再出现在新报名选择中；
4. 个人项目的报名项会关联到运动员，团体项目可以留空。

### 10.7 报名导入

报名有两种方式，都在本页完成：**从已有名单勾选**适合零散补报，**表格导入**适合批量录入。

**从已有名单勾选**

这张卡片分成「个人报名 / 团体报名」两个页签，页签下方的小项与组别选择是两个页签共用的。选中某个小项后会自动切到与该小项类型相符的页签（个人项目 → 个人报名；团体 / 对抗 / 个人+团体 → 团体报名），也可以手动切换；切到的页签与小项类型不符时页面会提示一句，生成的报名以当前页签为准。

**个人报名**（一人一条报名）

1. 选择单位，按姓名 / 工号搜索并在运动员列表里勾选：已报名的运动员显示「已报名」且不可重复勾选；证件号与号码布都没有的运动员显示「缺证件号/号码布」、不能勾选，请先到「运动员」分区补齐其中一项；
2. 点「加入报名」，结果同样显示**新增 / 更新 / 跳过**数量；报名会自动带上该运动员的证件号（优先）或号码布。

**团体报名**（一个单位一条报名）

1. 在参赛单位清单里勾选要参加本组别的单位，**默认一个都不勾**——不参加的单位不勾即可；每行显示该单位是否「已报名」、已登记几名队员；
2. 要登记队员时点该行的「登记队员」展开名单逐个勾选（可按姓名 / 工号搜索）；一个队员都不勾就是**纯单位报名**，队员名单之后还能再补；
3. 勾选「已报名」的单位会出现「提交将清空原名单」提醒：再次提交是用本次登记的队员覆盖原名单；
4. 点「加入报名」，一次为所有勾选的单位各建一条报名。
   - 「全选」只勾启用中且还没报名的单位（已停用的单位要单独勾），且不会展开队员面板；「清空」只取消单位勾选，已登记的队员名单留着，重新勾上就回来。

**表格导入**

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

1. 点「下载 CSV 模板」获取表头样例；
2. 表头共 11 列：`event_code`、`category`、`team_code`、`athlete_name`、`id_card`、`gender`、`age`、`bib`、`seed`、`status`、`member_names`（大小写不敏感）。其中 `id_card`（证件号）、`gender`（性别）、`age`（年龄）为可选列，缺失不影响导入，其余列必须包含；
3. **只要有姓名的行，`id_card` 与 `bib` 必须至少填一个**，否则该行报错并跳过；`gender` 只认「男」「女」，其他值忽略；`age` 可留空，填了必须是 0–120 的整数；同一份文件里同一个证件号或同一个号码布重复出现时，重复的行会报错；
4. 人员匹配顺序：
   1. 先按 `id_card` 匹配已有人员；
   2. 没匹配到，再按 `bib`（号码布）匹配；
   3. 还没匹配到，按「姓名 + 单位」匹配且该人员证件号为空，视为同一人，把表里给的证件号 / 号码布 / 年龄补进去（不算冲突）；如果该人员已有号码布且与表里不同，则算冲突；
   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. 点「开始导入」，页面显示**新增 / 更新 / 跳过**数量；匹配不到的行会跳过并回显行号，修正后可重新上传。

**人员信息冲突的处理**

导入时如果某个证件号或号码布在系统里已经存在，但表里的姓名、性别、年龄、单位或号码布与已有人员不一致，这个人会被列为**冲突**，本次不写入（该人的报名也不会创建）。处理办法：

1. 导入结果里会单独列出冲突人员，每条显示已有数据、新数据，以及不一致的字段（含年龄与号码布）；
2. 用左侧复选框选中一条或多条（也可以全选），再点「保留已有数据」或「使用新数据」：
   - **保留已有数据**：人员字段沿用系统里已有的，按这个人的信息建 / 更新报名；
   - **使用新数据**：用表里的姓名、性别、年龄、单位、号码布等更新该人员，再建 / 更新报名；
3. **没有做决定的冲突不会被写入**，可以稍后再处理；全部处理完后冲突列表清空。

> 「从已有名单勾选」走的是同一个导入通道，人员匹配与冲突处理规则完全一致。

种子等字段无法在勾选界面填写，仍需通过表格导入；号码布取自人员档案，勾选时会自动写入报名。团体报名登记的队员名单只存姓名，不会带动运动员档案。

---

## 11. 导出

页面分三个页签。

### 11.1 结果导出（xlsx）

| 导出项 | 内容 | 文件名 |
| --- | --- | --- |
| 总表 | 总积分榜 + 团体奖牌榜 + 个人积分奖牌榜，一个工作簿 | `总积分榜.xlsx` |
| 全部 | 总表 + 全部分项，多 sheet 工作簿，适合归档打印 | `赛事成绩总表.xlsx` |
| 分项成绩表 | 选择一个小项导出成绩与积分 | `分项成绩表.xlsx` |
| 单位积分明细 | 选择一个单位，逐项列出得分来源 | `单位积分明细.xlsx` |

- 「分项成绩表」需先选择小项，「单位积分明细」需先选择单位；
- 导出文件由浏览器直接下载，表头、合并单元格与字体已按打印模板预设。

### 11.2 赛事项目包

服务端一次只打开一个赛事项目，页面上看到的数据全部来自「当前」的那一项，其余项目只是躺在数据目录里的数据。

**赛事项目列表**

- 列出数据目录下的全部项目，含项目名、更新时间与占用大小，当前打开的那一项带「当前」徽标；
- 每行的「切换为当前赛事」用于切换（仅管理员），切换过程见下面「导入后怎样才算生效」；
- 列表里出现「缺 event.db」的项目不可切换，说明该目录不是完整的赛事包。

**导出 zip**：包内含 `meta.yaml`、`event.db`、`uploads/`、`rules.yaml`，整包拷走即可在另一台机器复现整场赛事。`uploads/` 里除了会标、背景图与单位 logo，还包含**上传到赛事信息里的字体**（在 `uploads/fonts/` 下），字体设置也随赛事库一起走，导入后不用重新上传字体。

**导入 zip**（仅管理员）：选择 `.zip`，可填「重命名」，勾选「覆盖同名项目」会先二次确认。导入只把数据解到数据目录，**不会自动切换当前赛事**，所以导入完成后页面会提示「已导入为 xxx，但它还不是当前赛事」。

**导入后怎样才算生效**

1. 在导入完成的结果框里点「立即切换并重启服务端」（也可以稍后在赛事项目列表里点该项目的「切换为当前赛事」）；
2. 服务端把项目名写进**数据目录根下**的 `active_project.txt`（不在赛事项目目录里）后退出，由服务管理窗口自动拉起，并打开刚切换的赛事；下次启动即使不带启动参数，也仍然是这个赛事；
3. 期间页面显示「正在重启服务端…」，每 1.5 秒探测一次服务端是否回来，恢复后自动刷新页面（最多等 60 秒）；
4. 超过 60 秒仍未恢复时，页面会提示打开服务管理窗口确认服务端状态，待其显示「运行中」后手动刷新本页。

> 切换会让服务端重启，正在录入的成绩页会短暂无法提交，请避开比赛进行中操作。
> 账号与会话存在**数据目录根下的 `system.db`**（系统库）里，属于整个系统而不属于某个赛事库，所以切换赛事**不会**让你退出登录；万一重启后页面变成只读访客视图，登录一次即可，忘记密码用 `scoreboard.exe passwd` 重置（见常见问题「忘记密码怎么办」）。

### 11.3 规则包

> 规则包文件放在 `%LOCALAPPDATA%\ScoreboardConsole\rules\`（安装包里附带的那份会在首次启动时复制过去；见部署指南 3.5）。

- **导出 rules.yaml**：导出积分模板、并列规则、破纪录加分、计分通道与项目覆盖；
- **导入**（仅管理员）：
  1. 选择 `.yaml` / `.yml` 文件（就是上面那个 `rules\` 目录里的）；
  2. 点「预览差异」，查看格式是否兼容、影响多少个小项、逐条改动；
  3. 确认无误后点「确认导入并全量重算」，服务端会按新规则重算全部已发布积分。

> 规则导入会立即改变积分榜与大屏，且**不能一键撤销**，纠错需重新导入旧规则包。

---

## 12. 变更历史

仿 Git 图谱的只读操作记录。

1. 顶部可筛选小项，以及「全部时间 / 近 24 小时 / 近 7 天」；
2. 左侧时间轴最新在上，节点显示动作（发布 / 撤销发布 / 编辑）、项目、操作人、时间与备注；
3. 点节点，右侧显示操作人、影响单位与成绩前后对比（diff）；
4. 本页**不提供一键回滚**。纠错请到「成绩录入」走「撤销发布 → 修改 → 重新发布」。

---

## 13. 日志

审计日志，只读、不可删除，记录谁在什么时候改了什么。

1. 可按「动作」「实体」筛选，点「清除筛选」复位；
2. 列表显示时间、操作人、IP、动作、实体、请求 ID；关键动作会带「关键」标记；
3. 点某行「对比」展开，查看改动前后的 JSON 差异；
4. 筛选与分页作用于最近 200 条记录；
5. 该页面仅管理员可查看。

---

## 14. 系统设置

页面分三个页签，均需要管理员权限。

### 14.1 用户管理

| 操作 | 说明 |
| --- | --- |
| 新建用户 | 填写账号 *、显示名 *、角色 *（管理员 / 录入员）、初始密码 *（至少 8 位）；新用户首次登录强制改密 |
| 编辑 | 修改显示名、角色、启用状态；账号创建后不可改 |
| 停用 | 二次确认后该用户无法登录，正在使用的会话也会失效 |
| 重置密码 | 生成随机密码，**只显示一次**，可复制后交给用户；旧密码立即失效 |

> 访客身份由系统默认提供，不需要也不允许建「访客账号」。

### 14.2 备份

- 列表显示备份文件名、来源、大小、创建时间；
- 点「立即备份」马上生成一份；
- 服务端默认每 5 分钟自动备份一次，自动、手动、发布前备份都按 `backup.keep`（默认 20 份）滚动保留；
- 右侧「恢复说明」列出停机恢复步骤（详见部署指南第 8 节）。

### 14.3 赛事信息

| 字段 | 说明 |
| --- | --- |
| 赛事名称 * | 必填 |
| 副标题 / 主办方 | 可选，显示在大屏顶部 |
| 赛事会标 | 图片，显示在大屏左上角。点「上传图片」选文件即可（png / jpg / webp / gif，单张不超过 5 MiB）；上传的图片存在赛事项目目录的 `uploads/` 里，会随赛事包一起导出/导入 |
| 大屏标题 / 大屏副标题 | 大屏顶部标题区 |
| 大屏会标 | 图片，只对大屏生效；留空则用上面的「赛事会标」 |
| 大屏背景图 | 图片，铺满大屏底层；留空则用内置深色背景 |
| 轮播间隔（秒） | 控制大屏底部滚动条（奖牌榜 Top3 / 最新完成项目 / 公告）的切换间隔，5–120 秒 |
| 主题色 | 大屏主色，如 `#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）。

> 修改大屏标题、主题色、字体等会立即影响所有在线大屏，请避开颁奖或播报时段。

---

## 15. 修改密码

1. 输入原密码；
2. 输入新密码（至少 8 位）并再次确认；
3. 点「修改密码」；
4. 修改成功后所有会话作废，需要用新密码重新登录。

首次登录或密码被管理员重置后，会强制进入本页。

---

## 16. 关于

展示系统名称、版本号、构建时间、运行模式，以及技术栈与开源许可、字体清单（四款内置字体的用途与授权；给大屏换字体见 14.3）、键盘快捷键、部署信息（服务端端口、访问地址、赛事项目名）。

---

## 17. 大屏端使用

### 17.1 页面

大屏支持五个页面：

| 页面 | 内容 |
| --- | --- |
| 总积分榜 | 名次、单位（单位 logo + 单位名）、总分，以及名次升降箭头（约 2 秒后淡出） |
| 团体奖牌榜 | 名次、单位（带单位 logo）、金 / 银 / 铜、合计 |
| 个人积分奖牌榜 | 名次、姓名（姓名前显示所属单位 logo）、单位、总分、奖牌 |
| 分项成绩 | 最新已完成项目的成绩，单位列名字前显示单位 logo |
| 公告 | 管理端推送的公告：推送后先全屏展示，之后常驻底栏的「公告」槽位 |

> 单位 logo 取自「基础数据 → 参赛单位」里上传的图片（见 10.1），按行内文字大小显示，不会撑开行高；没传 logo 的单位不占位，图片临时加载不出来时保留占位、刷新后恢复，队名不会跳动。

> 大屏的标题字体与正文字体取自「系统设置 → 赛事信息 → 字体」（见 14.3）：可选四款内置字体，也可以上传自己的字体；上传字体加载失败时自动回落到默认字体，画面不会出现方块或空白。

### 17.2 轮播与锁定

- Console 启动的多屏大屏窗口默认**每屏锁定一页**，不轮播；
- 在管理端「大屏控制」点「解锁」后开始整页轮播，**每 20 秒切换一页**；
- 公告页是手动触发的页面，不参与自动轮播；个人积分榜可在「赛事信息」里关闭上屏；
- 底部滚条固定有「公告」槽位：管理端推送过公告就一直显示最近那条，没有公告时显示「暂无公告」（见第 9 节）；
- 点「锁定」可停在当前页。

### 17.3 明细覆盖层

- 管理端推送单位积分明细后，大屏右侧弹出半屏覆盖层，显示该单位每一分的来源；
- 默认 **60 秒后自动关闭**并恢复轮播；
- 管理端「关闭大屏明细」可立即关闭。

### 17.4 断线与自愈

- 与后端断开时，大屏顶部显示离线角标，并继续展示本地缓存的最近一份快照；
- 连接恢复后自动拉取最新数据；
- 大屏每 24 小时自动重载一次，Console 同时启用防熄屏。

### 17.5 调试标识

窗口化（带标题栏的调试窗口）**且没有全屏**时，右上角会显示一行「实例 x · 屏 x」，用来分辨这块屏是哪个实例。除此之外没有别的调试标识——**数据版本号 `vN` 角标已经去掉，任何情况下都不再显示**；需要核对某块屏有没有跟上服务端时，用管理端仪表盘「实时连接」里的「版本 N」对照。

- **kiosk 全屏窗口**（多屏时每屏一个）不显示任何调试标识，正式上屏的画面是干净的；多屏 kiosk 也不响应 F11。
- 单屏窗口化窗口按 **F11** 全屏后，自绘标题栏与「实例 · 屏」会一起消失、画面铺满整块屏；再按一次 F11 回到窗口化，标题栏与标识一起回来。

---

## 18. 常见操作问题

**Q：为什么录入的成绩大屏上没有？**
草稿不会上屏。需要点「发布」（或 `Alt+Enter`），发布成功后立即更新。

**Q：发布后发现有错怎么办？**
到「成绩录入」找到该组，点「撤销发布」→ 修改 → 重新发布。撤销会作废该组积分流水，大屏回退；全程可在「变更历史」追溯。

**Q：并列名次怎么显示？**
成绩相同（或手动名次相同）即视为并列，显示同一名次，例如两个「3」。积分按规则包里的并列口径计算，默认是「顺延」：并列第 3 各得第 3 名的分，无第 4 名，下一名是第 5 名。奖牌也按并列处理，并列第 1 各记 1 金、无银牌。

**Q：为什么「发布」按钮是灰的？**
可能原因：当前是访客未登录（只读）、处于示例数据模式，或校验存在错误。页面会给出对应提示。

> 顶部显示「连接中断」不会再禁用按钮：实时推送断了只意味着数据可能不是最新，写操作照常提交并由服务端校验。

**Q：为什么页面显示「示例数据」？**
说明前端连不上后端或接口未就绪，此时操作不会写入真实赛事。请检查 Console 里服务端是否为「运行中」，恢复后刷新页面。

**Q：大屏上的积分明细怎么关？**
在「积分榜」页点「关闭大屏明细」，或在「大屏控制」里锁定 / 切换页面；不操作时 60 秒后自动关闭。

**Q：公告怎么发？多久消失？**
在「大屏控制 → 公告」输入文字，设置「滚动时长」（5–120 秒，即全屏展示的秒数）后点「推送公告」：大屏会先全屏显示，到时间后自动回到原来的页面，公告**不会消失**，会留在底栏「公告」槽位继续显示，直到你推一条新的或点「清除公告」。公告卡片上会显示当前公告正文与「当前公告：有 / 无」；新开的大屏、断线重连后会把当前公告再全屏播一遍（默认 15 秒）后留在底栏。

**Q：怎么切换到另一个赛事项目？**
在「导出 → 赛事项目包」的**赛事项目列表**里找到目标项目，点「切换为当前赛事」：服务端会退出并由服务管理窗口自动拉起，页面显示「正在重启服务端…」，恢复后自动刷新，同时记下「上次打开的赛事」，下次启动即使不带参数也仍打开它。详见部署指南第 8.5 节。**别**用 Console 的 `config.json` 给 `server.args` 加 `-project` 来切赛事：那样每次启动都会优先打开并写回这个项目，页面里切完、重启后又被拉回去。

**Q：导出的文件在哪里？**
结果导出和赛事包由浏览器下载到默认下载目录；服务端自身也会在数据目录下的 `exports\` 里生成临时包（导出完成后自动删除）。数据目录默认是 `%LOCALAPPDATA%\ScoreboardConsole\data`，详见部署指南第 3.4 节。

**Q：登录多久会过期？**
会话有效期 12 小时。过期后自动回到只读访客视图，重新登录即可。

**Q：为什么登录失败次数多了会被暂时拒绝？**
登录有频率限制（每个 IP 每分钟 5 次），写操作也有频率限制（每个用户每分钟 30 次）。稍等一分钟再试即可。

**Q：为什么有些页面 / 按钮看不到或不可用？**
权限按角色控制：访客只能只读；变更历史、日志、系统设置、备份、用户管理、规则包与赛事项目包导入需要相应角色。请用对应账号登录。