AskaEth/Scoreboard
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
24fff8dd08a237f35e91641ca36a5ceee9ea699b
Scoreboard/docs/使用手册.md
T
AskaEth 24fff8dd08 feat: 人员唯一标识改为证件号 + 导入冲突逐条决策 
需求：人员以证件号为准（避免重名）；批量导入时若证件号已存在于本地人员数据，
先导入其余人员，再把重复的人单独列出，由用户逐条/多选决定保留已有数据还是新数据。

服务端：
- 迁移 0013：athletes 增加 id_card + 部分唯一索引（空值可共存）
- athleteDTO/CRUD 读写 idCard，重复返回 409
- 导入表头新增可选列 id_card/gender；有姓名的行必须给证件号
- 匹配顺序：证件号 → 姓名+单位（且库中证件号为空则回填）→ 新建人员
- 证件号命中但姓名/性别/单位不一致 → 冲突，本轮不落库（报名也不建）
- 新增 POST /api/entries/import/resolve（file + decisions），keep-existing/keep-new
- 10 个新测试覆盖匹配/回填/冲突/决策/唯一索引

前端：
- 运动员表单与列表新增「证件号」，搜索支持证件号
- 报名导入：新模板 10 列；导入后冲突面板（每行复选框 + existing↔incoming 差异高亮
  + 全选/清空 + 保留已有数据/使用新数据 批量与逐条），未决策项始终可见
- 勾选报名（EntryPicker）缺证件号的运动员禁止勾选并提示
- 新增 import-conflicts.test.ts 等，前端测试 39/39

文档：使用手册（运动员证件号、导入表头与冲突流程）、常见问题（证件号重复怎么办）。

注：报名行的 team_code 与人员绑定单位不一致会计入冲突，由用户决策，不会静默改单位。
2026-09-10 02:09:15 +08:00

23 KiB
Raw Blame History

使用手册

面向现场操作人员与管理员。管理面板地址：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.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 秒），点「推送公告」

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

在线看板：当前版本后端未提供大屏实例上报接口，因此在线状态恒显示「未知」，「最近下发」只是本机下发指令的时间，不代表大屏在线。

10. 基础数据

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

10.1 参赛单位

  1. 点「新增单位」；
  2. 填写代码 *（唯一，字母 / 数字 / _ / -，最长 16 位）、全称 *、简称、主题色、排序、logo 路径；
  3. 「编辑」修改；「停用」为软删除——历史成绩与积分流水保留，但新报名不再可选该单位，可随时「启用」。

10.2 大项 / 小项

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

10.3 组别

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

10.4 计分通道

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

  1. 先选中一个小项；
  2. 点「新增通道」逐条配置，同一「名次范围 + 名次来源」只能有一个通道；
  3. 点「保存全部」整体替换该小项的通道配置；
  4. 标记为「不计分」的小项，通道可以保存但不参与积分计算。

10.5 积分模板

  1. 左侧点「新建」创建模板，填写编码、名称、并列处理、破纪录加分、录取名次、末位归零；
  2. 在「名次 → 分值」表格里添加 / 移除分值明细；
  3. 保存会整体替换该模板的分值明细，请核对后再保存。

10.6 运动员

  1. 点「新增运动员」，填写姓名 *、证件号、性别、工号 / 学号、所属单位等；
  2. 证件号是人员的唯一标识（如身份证号），用于区分重名；同一个证件号不允许重复，重复会被拒绝。已有历史数据可以留空；
  3. 「编辑」修改，「停用」后不再出现在新报名选择中；
  4. 个人项目的报名项会关联到运动员，团体项目可以留空。

10.7 报名导入

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

从已有名单勾选

  1. 依次选择小项、组别、单位；
  2. 在运动员列表里按姓名 / 工号搜索并勾选：
    • 个人项目：勾选的人各生成一条报名；已报名的运动员显示「已报名」且不可重复勾选；
    • 团体 / 对抗项目：勾选的人合成一条报名，队员名单按列表顺序写入；该单位已报名时再次提交会更新队员名单；
  3. 点「加入报名」，结果同样显示新增 / 更新 / 跳过数量。

表格导入

  1. 点「下载 CSV 模板」获取表头样例；
  2. 表头共 10 列：event_code、category、team_code、athlete_name、id_card、gender、bib、seed、status、member_names（大小写不敏感）。其中 id_card（证件号）与 gender（性别）为可选列，缺失不影响导入，其余列必须包含；
  3. 只要有姓名的行必须填 id_card，否则该行报错并跳过；gender 只认「男」「女」，其他值忽略；同一份文件里同一个证件号重复出现时，重复的行会报错；
  4. 人员匹配顺序：先按证件号匹配已有人员；没匹配到，再按「姓名 + 单位」匹配且该人员证件号为空，视为同一人并回填证件号（不算冲突）；都没匹配到则新建人员；
  5. 把 .csv 或 .xlsx 拖入虚线框，或点击选择文件（单个文件不超过 16MB；xlsx 只解析第一个工作表）；
  6. 点「开始导入」，页面显示新增 / 更新 / 跳过数量；匹配不到的行会跳过并回显行号，修正后可重新上传。

证件号冲突的处理

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

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

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

号码布、种子等字段无法在勾选界面填写，仍需通过表格导入。

11. 导出

页面分三个页签。

11.1 结果导出（xlsx）

导出项 内容 文件名
总表 总积分榜 + 团体奖牌榜 + 个人积分奖牌榜，一个工作簿 总积分榜.xlsx
全部 总表 + 全部分项，多 sheet 工作簿，适合归档打印 赛事成绩总表.xlsx
分项成绩表 选择一个小项导出成绩与积分 分项成绩表.xlsx
单位积分明细 选择一个单位，逐项列出得分来源 单位积分明细.xlsx
  • 「分项成绩表」需先选择小项，「单位积分明细」需先选择单位；
  • 导出文件由浏览器直接下载，表头、合并单元格与字体已按打印模板预设。

11.2 赛事项目包

  • 导出 zip：包内含 meta.yaml、event.db、uploads/、rules.yaml，整包拷走即可在另一台机器复现整场赛事；
  • 导入 zip（仅管理员）：选择 .zip，可填「重命名」，勾选「覆盖同名项目」会先二次确认；导入完成后需重启服务端并指定项目名才会切换到该赛事（详见部署指南第 8.5 节）。

11.3 规则包

  • 导出 rules.yaml：导出积分模板、并列规则、破纪录加分、计分通道与项目覆盖；
  • 导入（仅管理员）：
    1. 选择 .yaml / .yml 文件；
    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 赛事信息

字段 说明
赛事名称 * 必填
副标题 / 主办方 可选，显示在大屏顶部
大屏标题 / 大屏副标题 大屏顶部标题区
轮播间隔（秒） 控制大屏底部滚动条（奖牌榜 Top3 / 最新完成项目 / 公告）的切换间隔，5–120 秒
主题色 大屏主色，如 #3482FF
个人积分榜上屏 开关；关闭后大屏不展示个人积分榜

改完点「保存」；未保存时显示「未保存」徽标，点「放弃修改」可还原。

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

15. 修改密码

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

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

16. 关于

展示系统名称、版本号、构建时间、运行模式，以及技术栈与开源许可、字体清单、键盘快捷键、部署信息（服务端端口、访问地址、赛事项目名）。

17. 大屏端使用

17.1 页面

大屏支持五个页面：

页面 内容
总积分榜 名次、单位、总分，以及名次升降箭头（约 2 秒后淡出）
团体奖牌榜 名次、单位、金 / 银 / 铜、合计
个人积分奖牌榜 名次、姓名、单位、总分、奖牌
分项成绩 最新已完成项目的成绩
公告 管理端手动推送的文字

17.2 轮播与锁定

  • Console 启动的多屏大屏窗口默认每屏锁定一页，不轮播；
  • 在管理端「大屏控制」点「解锁」后开始整页轮播，每 20 秒切换一页；
  • 公告页是手动触发的页面，不参与自动轮播；个人积分榜可在「赛事信息」里关闭上屏；
  • 点「锁定」可停在当前页。

17.3 明细覆盖层

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

17.4 断线与自愈

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

18. 常见操作问题

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

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

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

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

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

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

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

Q：公告怎么发？多久消失？ 在「大屏控制 → 公告」输入文字，设置滚动时长（5–120 秒）后点「推送公告」；到时后自动回到之前的页面。

Q：怎么切换到另一个赛事项目？ 当前服务端一次只运行一个赛事项目（默认 default）。导入赛事项目包后，需要重启服务端并指定 -project <项目名> 才能切换，详见部署指南第 8.5 节。

Q：导出的文件在哪里？ 结果导出和赛事包由浏览器下载到默认下载目录；服务端自身也会在 data\exports\ 下生成临时包（导出完成后自动删除）。

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

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

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

Reference in new issue View Git Blame Copy Permalink