fix: 审查修复波次（P0x4 + P1x30+）
- domain/rules: 计分与排名解耦、破纪录按组别、tieBreak 生效、调整分不丢、移除 aggregate 假能力 - realtime: 新建 internal/dto，快照三项契约对齐，/ws 只认会话身份 - httpapi: 流水幂等、standings 整表载荷、广播接线、强制改密、XFF 防伪造、records 写入、审计、赛事包内容、发布前备份、result.points、实例列表 - web: FormData 上传、YAML 解析、快照归一化、大屏解析层、bootstrap 降级、访客判定、主题切换 - console: 优雅关闭握手、中文化、免验证改管理员账号、选屏与日志轮转修复 - docs: 用户文档三份 + README - 主代理: 破纪录加分接线（levels 未加载导致恒 0）
This commit is contained in:
AskaEth committed
1 parent
8dae63ee70
commit
7f9701c465
61 files changed
+3844
-333
No files matched your search
+461
@@ -0,0 +1,461 @@
|
||||
# 使用手册
|
||||
|
||||
> 面向现场操作人员与管理员。管理面板地址：`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. 个人项目的报名项会关联到运动员，团体项目可以留空。
|
||||
|
||||
### 10.7 报名导入
|
||||
|
||||
1. 点「下载 CSV 模板」获取表头样例；
|
||||
2. 表头必须包含：`event_code`、`category`、`team_code`、`athlete_name`、`bib`、`seed`、`status`、`member_names`（大小写不敏感）；
|
||||
3. 把 `.csv` 或 `.xlsx` 拖入虚线框，或点击选择文件（单个文件不超过 16MB；xlsx 只解析第一个工作表）；
|
||||
4. 点「开始导入」，页面显示**新增 / 更新 / 跳过**数量；匹配不到的行会跳过并回显行号，修正后可重新上传。
|
||||
|
||||
---
|
||||
|
||||
## 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 备份
|
||||
|
||||
- 列表显示备份文件名、来源、大小、创建时间；
|
||||
- 点「立即备份」马上生成一份；
|
||||
- 右侧「恢复说明」列出停机恢复步骤（详见部署指南第 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：为什么有些页面 / 按钮看不到或不可用？**
|
||||
权限按角色控制：访客只能只读；变更历史、日志、系统设置、备份、用户管理、规则包与赛事项目包导入需要相应角色。请用对应账号登录。
|
||||
+135
@@ -0,0 +1,135 @@
|
||||
# 常见问题（FAQ）
|
||||
|
||||
> 更完整的操作步骤见 [使用手册](./使用手册.md)，部署与排障见 [部署指南](./部署指南.md)。
|
||||
|
||||
---
|
||||
|
||||
## 账号与权限
|
||||
|
||||
**Q1：初始密码是多少？**
|
||||
首次启动时随机生成、只打印一次。用 Console 启动时，在 `logs\console.log` 里搜索「初始密码」即可找到，方法见 [部署指南 · 首次登录](./部署指南.md#5-首次登录)。
|
||||
|
||||
**Q2：忘记密码怎么办？**
|
||||
先停止服务，然后在部署目录执行 `scoreboard.exe passwd -config config.yaml`，会打印新的随机密码，并要求下次登录强制改密。
|
||||
|
||||
**Q3：访客和录入员有什么区别？**
|
||||
访客只能只读查看；录入员可以录入、存草稿、发布、撤销发布、确认破纪录、做积分调整、控制大屏；管理员在此基础上还能管理用户、备份、看审计日志、导入规则包和赛事包。
|
||||
|
||||
**Q4：为什么登录后还是只读？**
|
||||
可能未登录成功、会话已过期（有效期 12 小时），或页面处于示例数据模式。看右上角是否显示账号名与角色。
|
||||
|
||||
**Q5：可以建「访客账号」吗？**
|
||||
不可以。访客是未登录时的默认身份，不需要也不允许建账号；可落库的角色只有管理员和录入员。
|
||||
|
||||
**Q6：管理员能改用户名吗？**
|
||||
管理界面里账号创建后不可改；命令行可用 `scoreboard.exe passwd -user 旧名 -new-username 新名` 修改。
|
||||
|
||||
---
|
||||
|
||||
## 成绩与积分
|
||||
|
||||
**Q7：为什么录入后大屏没变化？**
|
||||
草稿不上屏。需要「发布」（或 `Alt+Enter`），发布后 1 秒内大屏更新。
|
||||
|
||||
**Q8：发布错了怎么改？**
|
||||
撤销发布 → 修改 → 重新发布。撤销会作废该组积分流水，大屏回退到发布前状态，过程可在「变更历史」查看。
|
||||
|
||||
**Q9：为什么「发布」是灰的？**
|
||||
常见原因：未登录、服务端断开、示例数据模式，或存在阻止发布的校验错误（缺少成绩、格式无法解析、手动名次项目缺名次）。
|
||||
|
||||
**Q10：并列名次怎么处理？**
|
||||
成绩相同（或手动名次相同）自动按并列处理，显示同一名次。默认口径是「顺延」：并列第 3 各得第 3 名的分，无第 4 名，下一名第 5 名；奖牌同样并列（并列第 1 各记 1 金、无银）。具体口径由规则包配置决定。
|
||||
|
||||
**Q11：状态里的 DNS / DQ / DNF / 退赛有什么区别？**
|
||||
都是不参与名次与积分计算的异常状态：DNS = 弃赛，DQ = 取消资格，DNF = 未完赛，退赛 = 主动退出。正常成绩选「有效」。
|
||||
|
||||
**Q12：时间类成绩怎么写？**
|
||||
按 `分:秒.毫秒` 形式输入，例如 `1:06.33`；工具栏会显示当前项目的单位。
|
||||
|
||||
**Q13：能批量录入吗？**
|
||||
可以。支持从 Excel 复制后粘贴：两列及以上时第一列按单位名称 / 简称匹配行、最后一列作为成绩；单列时从当前行向下依次填充。也可以用 `Tab` / `Enter` 在格子间移动，`Ctrl+Enter` 存草稿。
|
||||
|
||||
**Q14：破纪录加分为什么点不了？**
|
||||
规则包里破纪录加分默认关闭（`recordBonus.enabled = false`）时按钮不可用；若当前角色读不到规则包，页面显示「未知」，可提交，由服务端校验决定是否加分。
|
||||
|
||||
**Q15：人工调整为什么点不了？**
|
||||
规则包里人工调整默认关闭（`manualAdjustment.enabled = false`）时不可用；以页面顶部显示的开关状态为准。
|
||||
|
||||
---
|
||||
|
||||
## 大屏
|
||||
|
||||
**Q16：大屏不亮 / 只有桌面怎么办？**
|
||||
检查 HDMI、扩展显示模式、Console「大屏窗口」状态，点「重新排布」；服务端未就绪时最多等 20 秒才开屏；单屏窗口化时按 `F11` 切全屏。详见 [部署指南 · 故障排查](./部署指南.md#9-故障排查)。
|
||||
|
||||
**Q17：单屏和多屏的显示方式有什么不同？**
|
||||
单屏时大屏以窗口化方式打开，按 `F11` 切全屏；多屏时除内置屏外每块屏一个 kiosk 全屏窗口，各锁一页，不响应 F11，也不接收鼠标。
|
||||
|
||||
**Q18：大屏为什么不自动轮播？**
|
||||
Console 启动的多屏窗口默认每屏锁定一页。到「大屏控制」点「解锁」后开始轮播，每 20 秒一页；公告页不参与轮播。
|
||||
|
||||
**Q19：推送的积分明细怎么关？**
|
||||
60 秒后自动关闭；也可以点「积分榜」页的「关闭大屏明细」立即关闭。
|
||||
|
||||
**Q20：「在线看板」为什么显示未知？**
|
||||
当前版本后端没有大屏实例上报接口，因此无法判断每块屏是否在线，「最近下发」只是本机下发指令的时间。以现场大屏实际画面为准。
|
||||
|
||||
**Q21：安卓电视能用吗？**
|
||||
可以，用电视自带浏览器访问 `http://<主机IP>:19540/display`。但它不受 Console 的 kiosk、防熄屏控制，字体与动画表现以实际设备为准。
|
||||
|
||||
**Q22：大屏时间不对怎么办？**
|
||||
系统没有外网时间同步，以主机时间为准。校准 Windows 时间与时区即可。
|
||||
|
||||
---
|
||||
|
||||
## 数据与备份
|
||||
|
||||
**Q23：备份在哪里？**
|
||||
`data\backups\`，文件名形如 `system-<时间戳>.db`、`<项目名>-<时间戳>.db`。
|
||||
|
||||
**Q24：多久备份一次？**
|
||||
当前版本需要手动触发：管理端「系统设置 → 备份 → 立即备份」，或执行 `scoreboard.exe backup -config config.yaml`。建议在开幕前、发布高峰前、每天结束时各备份一次。
|
||||
|
||||
**Q25：备份会自动删除旧的么？**
|
||||
命令行备份会按前缀滚动保留最近 20 份，超出自动清理；管理端「立即备份」当前不自动清理，请定期检查目录占用。
|
||||
|
||||
**Q26：怎么恢复备份？**
|
||||
没有一键恢复接口，需停机手工替换数据库文件（复制备份为 `event.db`，删除 `event.db-wal` / `event.db-shm`，再启动），详见 [部署指南 · 备份与恢复](./部署指南.md#8-备份与恢复)。
|
||||
|
||||
**Q27：换一台电脑怎么迁移？**
|
||||
把整个部署目录（含 `data\`）拷到新机器，启动 Console 即可。
|
||||
|
||||
**Q28：怎么切换赛事项目？**
|
||||
服务端一次只运行一个项目（默认 `default`）。导入赛事包后，需要在 Console 的 `config.json` 里给 `server.args` 加 `-project <项目名>` 并重启，详见部署指南第 8.5 节。
|
||||
|
||||
---
|
||||
|
||||
## 导出与导入
|
||||
|
||||
**Q29：能导出哪些文件？**
|
||||
四类 Excel：总表、全部（多 sheet）、分项成绩表、单位积分明细；另外可导出赛事项目包（zip）与规则包（YAML）。
|
||||
|
||||
**Q30：导出文件保存在哪？**
|
||||
浏览器默认下载目录。服务端生成的临时包位于 `data\exports\`，下载完成后自动删除。
|
||||
|
||||
**Q31：谁能导入规则包 / 赛事项目包？**
|
||||
只有管理员。两者都会整体替换数据：规则包导入后全量重算积分且不能一键撤销；赛事包覆盖同名项目前会二次确认。
|
||||
|
||||
**Q32：导入规则包后积分变了，能撤销吗？**
|
||||
不能一键撤销。纠错需要重新导入旧规则包，或逐项修正后重新发布。导入前请务必先「预览差异」。
|
||||
|
||||
---
|
||||
|
||||
## 其他
|
||||
|
||||
**Q33：系统需要联网吗？**
|
||||
不需要。完全离线运行，不依赖外网，也不需要在现场安装任何运行时。
|
||||
|
||||
**Q34：页面提示「示例数据」是什么意思？**
|
||||
表示后端未就绪或连接中断，此时所有改动只停留在界面，不会写入真实赛事。恢复连接后刷新即可。
|
||||
|
||||
**Q35：为什么登录 / 写操作偶尔被拒绝？**
|
||||
系统有频率限制：登录每 IP 每分钟 5 次，写操作每用户每分钟 30 次。稍等一分钟再试。
|
||||
|
||||
**Q36：数据目录在哪？**
|
||||
由 `config.yaml` 的 `dataDir` 指定，默认 `data`，相对服务端工作目录解析。
|
||||
+429
@@ -0,0 +1,429 @@
|
||||
# 部署指南
|
||||
|
||||
> 面向现场操作人员与管理员。本系统完全离线运行，不需要联网，不需要安装任何运行时。
|
||||
|
||||
---
|
||||
|
||||
## 1. 运行环境要求
|
||||
|
||||
| 项目 | 要求 |
|
||||
| --- | --- |
|
||||
| 服务端主机 | Windows 10 / 11，64 位（amd64） |
|
||||
| 大屏 | 通过 HDMI 接入主机；显示模式设为**扩展**；推荐 16:9、1920×1080 或 3840×2160 |
|
||||
| 网络 | 完全离线即可运行。若需要手机/平板/电视访问，用独立交换机或路由器组成局域网 |
|
||||
| 磁盘 | 建议预留 ≥ 10GB |
|
||||
| 运行时 | 无需安装 Go / Node / 数据库等任何运行时，前端已内嵌进可执行文件 |
|
||||
| 权限 | 首次运行会在部署目录下创建 `data\`、`logs\`，请确保该目录可写 |
|
||||
|
||||
> 服务端只构建 Windows amd64 一个版本。Linux / 其他平台不在交付范围内。
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取安装包
|
||||
|
||||
在**构建机**（具备 Go、Node.js、pnpm、git 环境，并能访问依赖源）上执行：
|
||||
|
||||
```bat
|
||||
deploy\build.bat
|
||||
```
|
||||
|
||||
脚本依次完成：拉取代码 → 构建前端 → 构建服务端 → 打包桌面宿主。产物落在仓库的 `dist\` 目录：
|
||||
|
||||
| 产物 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `dist\scoreboard.exe` | 服务端 | 前端已通过内嵌方式打进可执行文件，单独运行也能提供全部页面 |
|
||||
| `dist\console\Scoreboard Console-0.1.0-x64.exe` | 安装包 | NSIS 安装程序，双击按向导安装 |
|
||||
| `dist\console\Scoreboard Console-0.1.0-x64.zip` | 免安装包 | 解压即用 |
|
||||
| `dist\console\win-unpacked\` | 目录 | 未压缩的运行目录，便于现场调试 |
|
||||
|
||||
> 文件名中的 `0.1.0` 来自 `console\package.json` 的版本号，会随版本升级变化；以 `dist\console\` 下的实际文件名为准。
|
||||
>
|
||||
> 目标机器**不需要** Go / Node / pnpm，也不联网；上述工具只用于构建机。
|
||||
|
||||
---
|
||||
|
||||
## 3. 安装与首次启动
|
||||
|
||||
### 3.1 使用安装包
|
||||
|
||||
1. 双击 `Scoreboard Console-0.1.0-x64.exe`。
|
||||
2. 按向导选择安装目录（可自定义）。
|
||||
3. 安装完成后，桌面会出现名为**「赛事积分榜」**的快捷方式。
|
||||
4. 双击「赛事积分榜」启动。
|
||||
|
||||
> 程序会在自己的安装目录下创建 `data\` 与 `logs\`，请安装到当前用户有写权限的目录；若装到受保护的系统目录，可能因无写入权限而无法建库。
|
||||
|
||||
### 3.2 使用免安装包
|
||||
|
||||
1. 把 `Scoreboard Console-0.1.0-x64.zip` 解压到任意目录（建议使用纯英文路径）。
|
||||
2. 双击目录里的 `Scoreboard Console.exe` 启动。
|
||||
|
||||
### 3.3 首次启动会自动完成
|
||||
|
||||
- 拉起并守护服务端 `scoreboard.exe`；
|
||||
- 在 `data\` 下自动建库、建目录；
|
||||
- 打开服务端管理面板窗口；
|
||||
- 把大屏页面投到扩展屏；
|
||||
- 启用防熄屏；
|
||||
- 注册开机自启（仅打包后的 Windows 版本）。
|
||||
|
||||
部署目录结构（安装或解压后）：
|
||||
|
||||
```
|
||||
安装目录\
|
||||
├── Scoreboard Console.exe # 桌面宿主，双击启动
|
||||
├── resources\app.asar # Console 自身资源
|
||||
├── config.json # Console 配置（可编辑）
|
||||
├── scoreboard.exe # Go 服务端
|
||||
├── config.yaml # 服务端配置
|
||||
├── scoreboard.png # 应用图标
|
||||
├── data\ # 首次运行生成：数据库、备份
|
||||
└── logs\console.log # 首次运行生成：运行日志
|
||||
```
|
||||
|
||||
> `data\` 与二进制分离，升级时替换可执行文件即可保留数据。
|
||||
|
||||
---
|
||||
|
||||
## 4. 服务管理窗口（Scoreboard Console）
|
||||
|
||||
启动后首先看到的是「Scoreboard Console · 启动管理」窗口。
|
||||
|
||||
### 4.1 窗口按钮
|
||||
|
||||
| 位置 | 按钮 / 项 | 作用 |
|
||||
| --- | --- | --- |
|
||||
| 服务端状态 | **启动服务** | 手动拉起服务端 |
|
||||
| 服务端状态 | **停止服务** | 优雅停止服务端（会先请求服务端关闭，超时后强制结束） |
|
||||
| 服务端状态 | **重启服务** | 停止后重新启动 |
|
||||
| 服务端状态 | 状态行 | 已停止 / 启动中 / 运行中 / 停止中 / 异常退出 |
|
||||
| 服务端状态 | 服务地址、进程 PID、自动重启、防熄屏 | 实时运行信息 |
|
||||
| 服务端状态 | 服务端程序、配置文件 | 实际使用的可执行文件与配置路径 |
|
||||
| 大屏窗口 | **重新排布** | 重新枚举显示器并重开大屏窗口 |
|
||||
| 大屏窗口 | **打开服务端管理面板** | 用内置窗口打开 `http://127.0.0.1:<端口>/admin`，无需再开浏览器 |
|
||||
| 运行日志 | **自动滚动** | 日志是否跟随最新一行 |
|
||||
| 运行日志 | **清空** | 清空窗口内显示（不影响日志文件） |
|
||||
| 标题栏 | 最小化 / 最大化 / 关闭 | 关闭只是**隐藏到托盘**，服务端继续运行 |
|
||||
|
||||
### 4.2 托盘用法
|
||||
|
||||
- 托盘菜单显示当前服务端状态（如「服务端：运行中 · 就绪」）；
|
||||
- 菜单项：**启动服务**、**停止服务**、**重启服务**、**打开管理端**、**打开服务端管理面板**、**退出**；
|
||||
- 双击托盘图标 = 打开启动管理窗口；
|
||||
- **要真正退出程序，必须用托盘菜单的「退出」**；直接关窗口不会停服务端。
|
||||
|
||||
> 同一台机器只允许运行一个 Console 实例，重复启动会自动退出，避免抢占端口和大屏。
|
||||
|
||||
---
|
||||
|
||||
## 5. 首次登录
|
||||
|
||||
### 5.1 访问地址
|
||||
|
||||
| 用途 | 地址 |
|
||||
| --- | --- |
|
||||
| 本机管理面板 | `http://127.0.0.1:19540/admin` |
|
||||
| 局域网管理面板 | `http://<主机IP>:19540/admin` |
|
||||
| 大屏 | `http://<主机IP>:19540/display` |
|
||||
| 导航页 | `http://<主机IP>:19540/` |
|
||||
|
||||
> 端口默认 **19540**，以 `config.yaml` 为准。
|
||||
|
||||
### 5.2 初始账号
|
||||
|
||||
- 用户名：`admin`
|
||||
- 初始密码：**首次启动时随机生成，只打印一次**，数据库里只保存加密后的哈希，无法反查。
|
||||
|
||||
### 5.3 从日志里找初始密码
|
||||
|
||||
用 Console 启动时，服务端输出会同时显示在「运行日志」面板并写入 `logs\console.log`。初始密码所在的行形如：
|
||||
|
||||
```
|
||||
[server] 初始密码: xxxxxxxxxxxxxxxx
|
||||
```
|
||||
|
||||
在部署目录下执行以下任一命令即可找到（推荐 PowerShell，避免中文编码问题）：
|
||||
|
||||
```powershell
|
||||
Select-String -Path .\logs\console.log -Pattern '初始密码'
|
||||
```
|
||||
|
||||
```bat
|
||||
findstr /C:"初始密码" logs\console.log
|
||||
```
|
||||
|
||||
如果中文匹配不到，改用 ASCII 关键字（服务端还会输出一条 `password=` 的日志）：
|
||||
|
||||
```bat
|
||||
findstr /C:"password=" logs\console.log
|
||||
```
|
||||
|
||||
也可以直接在 Console 窗口的**运行日志**里查找「初始密码」或「已创建默认管理员」。
|
||||
|
||||
> 如果不用 Console、直接双击 `scoreboard.exe`，密码只会打印在终端窗口里，不会落文件。建议始终通过 Console 启动。
|
||||
|
||||
### 5.4 修改密码
|
||||
|
||||
- 首次登录后会自动跳到**「修改密码」**页，必须改密才能继续使用；
|
||||
- 新密码至少 8 位，需输入两次确认；
|
||||
- 修改成功后所有会话作废，需用新密码重新登录；
|
||||
- 管理员也可以在「系统设置 → 用户管理 → 重置密码」为其他用户重置。
|
||||
|
||||
### 5.5 忘记密码 / 没记下初始密码
|
||||
|
||||
在 Console 里先**停止服务**，然后在部署目录（`config.yaml` 所在目录）执行：
|
||||
|
||||
```bat
|
||||
scoreboard.exe passwd -config config.yaml
|
||||
```
|
||||
|
||||
该命令会为用户 `admin` 生成一个新的随机密码并打印出来，同时要求下次登录强制改密。可选参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
| --- | --- |
|
||||
| `-user <用户名>` | 指定要重置的用户，默认 `admin` |
|
||||
| `-password <新密码>` | 直接指定新密码；留空则随机生成并打印 |
|
||||
| `-new-username <新用户名>` | 同时修改用户名 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 端口与配置修改
|
||||
|
||||
### 6.1 服务端 `config.yaml`
|
||||
|
||||
| 项 | 当前默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `server.host` | `0.0.0.0` | 监听地址；`0.0.0.0` 表示局域网内其他设备也能访问 |
|
||||
| `server.port` | `19540` | HTTP 端口 |
|
||||
| `dataDir` | `data` | 数据目录，相对服务端工作目录解析 |
|
||||
| `log.level` | `info` | 日志级别：`debug` / `info` / `warn` / `error` |
|
||||
|
||||
### 6.2 Console `console\config.json`
|
||||
|
||||
| 项 | 当前默认值 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `server.exe` | `scoreboard.exe` | 服务端可执行文件；相对路径会在配置目录、当前目录、上级目录、`dist\` 依次查找 |
|
||||
| `server.args` | `["-config","config.yaml"]` | 传给服务端的启动参数 |
|
||||
| `server.host` / `server.port` | `127.0.0.1` / `19540` | 健康检查与打开管理面板用的地址；配成 `0.0.0.0` 时本机探测自动改走回环地址 |
|
||||
| `server.autoStart` | `true` | Console 启动后是否自动拉起服务端 |
|
||||
| `server.healthIntervalMs` | `5000` | 健康检查间隔（毫秒） |
|
||||
| `server.restartDelayMs` | `3000` | 崩溃重启的初始退避，之后逐次翻倍 |
|
||||
| `server.maxRestarts` | `0` | `0` = 无限重启 |
|
||||
| `server.shutdownTimeoutMs` | `12000` | 等待服务端优雅退出的上限 |
|
||||
| `server.healthyResetMs` | `60000` | 连续健康多久后清零崩溃计数 |
|
||||
| `display.selection` | `all-secondary` | 选屏策略，见第 7 节 |
|
||||
| `display.displays` | `[]` | 仅 `specified` 策略生效，填显示器 id 或 0 起序号 |
|
||||
| `display.pages` | `["standings","medals","individual","results"]` | 多屏时按屏序轮转锁定的页面 |
|
||||
| `display.pageParam` | `page` | 页面 URL 参数名 |
|
||||
| `display.kiosk` | `true` | 多屏时是否 kiosk 全屏（单屏恒为窗口化） |
|
||||
| `display.ignoreMouse` | `true` | 多屏窗口是否忽略鼠标 |
|
||||
| `display.reloadEveryHours` | `24` | 定时重载兜底，`0` = 关闭 |
|
||||
| `display.waitForServerMs` | `20000` | 服务端未就绪时，最多等这么久也先把大屏开出来 |
|
||||
| `display.backgroundColor` | `#0b0f1a` | 大屏窗口底色，减少加载白闪 |
|
||||
| `startup.openAtLogin` | `true` | 打包后随系统启动 |
|
||||
| `admin.width` / `admin.height` | `1040` / `760` | 启动管理窗口初始尺寸 |
|
||||
| `log.maxLines` | `2000` | 内存中保留的日志行数 |
|
||||
| `log.file` | `logs/console.log` | 日志文件，相对 `config.json` 所在目录 |
|
||||
| `log.maxFileBytes` | `4194304` | 单个日志文件上限，超出后轮转为 `.1` |
|
||||
|
||||
> 配置缺项会自动使用内置默认值；JSON 语法错误时回落到全默认值，并在窗口顶部提示。
|
||||
|
||||
### 6.3 修改端口
|
||||
|
||||
端口必须**两处一致**：
|
||||
|
||||
1. 关闭 Console（托盘 → 退出）；
|
||||
2. 修改 `config.yaml` 的 `server.port`；
|
||||
3. 修改 `console\config.json` 的 `server.port`（保持一致，否则 Console 健康检查和管理面板地址会失效）；
|
||||
4. 重新启动 Console；
|
||||
5. 之后管理面板地址变为 `http://<主机IP>:<新端口>/admin`。
|
||||
|
||||
---
|
||||
|
||||
## 7. 大屏接线
|
||||
|
||||
### 7.1 主方案：Console 驱动 HDMI
|
||||
|
||||
1. 用 HDMI 线连接主机与大屏；
|
||||
2. 在 Windows「显示设置」里把显示模式设为**扩展**（不要「复制」）；
|
||||
3. 确认分辨率与缩放（推荐 1920×1080 或 3840×2160，缩放按现场效果调整）；
|
||||
4. 启动 Console，大屏窗口会自动打开。
|
||||
|
||||
### 7.2 选屏策略（`display.selection`）
|
||||
|
||||
| 取值 | 行为 |
|
||||
| --- | --- |
|
||||
| `all-secondary`（默认） | 除内置屏外的每块屏各开一个大屏窗口；若所有屏都报告为非内置屏（纯台式机），退回「排除主屏」 |
|
||||
| `all` | 所有显示器都开大屏窗口 |
|
||||
| `specified` | 只对 `display.displays` 里列出的显示器开窗；可填显示器 id 或 0 起序号 |
|
||||
|
||||
### 7.3 单屏：窗口化 + F11
|
||||
|
||||
- 只有一块屏时，大屏以窗口化方式打开（屏幕 80% 大小、居中），并显示自绘标题栏；
|
||||
- 在窗口内按 **F11** 切换全屏 / 窗口；
|
||||
- 单屏模式不跟随显示器变化重排。
|
||||
|
||||
### 7.4 多屏：每屏锁一页
|
||||
|
||||
- 除内置屏外的每块屏各开一个 kiosk 全屏窗口；
|
||||
- 每块屏**锁定一个页面**，按 `display.pages` 的顺序轮转分配；
|
||||
- 多屏 kiosk 不响应 F11，也不接收鼠标（`ignoreMouse`）；
|
||||
- 可用的页面值：`standings`（总积分榜）、`medals`（团体奖牌榜）、`individual`（个人积分奖牌榜）、`results`（分项成绩）、`announcement`（公告）。
|
||||
|
||||
### 7.5 大屏窗口的自动行为
|
||||
|
||||
| 场景 | 行为 |
|
||||
| --- | --- |
|
||||
| 防熄屏 | Console 启动即生效，前后台都算 |
|
||||
| 服务端就绪 | 首次健康检查通过后开大屏 |
|
||||
| 服务端迟迟不就绪 | 等待超过 `waitForServerMs`（默认 20 秒）也先开，避免只见桌面 |
|
||||
| 服务端崩溃 | 按退避策略自动重启，恢复后大屏自动重载 |
|
||||
| 长时间运行 | 每 `reloadEveryHours`（默认 24 小时）自动重载一次 |
|
||||
|
||||
### 7.6 备选方案：安卓 TV / 设备自带浏览器
|
||||
|
||||
如果不用 Console 驱动 HDMI，也可以让大屏设备用自己的浏览器访问：
|
||||
|
||||
```
|
||||
http://<主机IP>:19540/display
|
||||
```
|
||||
|
||||
- 需要主机设置固定 IP，且设备与主机在同一局域网；
|
||||
- 安卓电视一般常亮，无需额外防熄屏；
|
||||
- 浏览器方案**不受** Console 的 kiosk、防熄屏、选屏控制，字体与动画表现以实际设备为准；
|
||||
- 现场以 Console + HDMI 为主方案，浏览器访问作为备用。
|
||||
|
||||
---
|
||||
|
||||
## 8. 备份与恢复
|
||||
|
||||
### 8.1 备份目录
|
||||
|
||||
所有备份都在 `data\backups\` 下，文件名为 `.db` 快照。该目录不进版本库。
|
||||
|
||||
### 8.2 如何备份
|
||||
|
||||
| 方式 | 操作 | 产物 |
|
||||
| --- | --- | --- |
|
||||
| 管理端 | 「系统设置 → 备份 → 立即备份」 | `system-<时间戳>.db` 与 `event-<时间戳>.db` |
|
||||
| 命令行 | 在部署目录执行 `scoreboard.exe backup -config config.yaml` | `system-<原因>-<时间戳>.db` 与 `<项目名>-<原因>-<时间戳>.db` |
|
||||
| 快捷脚本 | `deploy\backup.bat`（原因记 `manual`）或 `deploy\backup.bat publish`（原因记 `publish`） | 同上 |
|
||||
|
||||
- 备份使用 SQLite 的 `VACUUM INTO`，服务运行中也能安全执行，不需要停服务，也不依赖外部 `sqlite3.exe`；
|
||||
- 命令行方式会按前缀**滚动保留最近 20 份**（`system` 与赛事库各自计算），超出的旧备份自动删除；
|
||||
- 管理端「立即备份」按钮生成快照，但当前版本不会自动清理旧文件，请定期检查 `data\backups\` 占用；
|
||||
- 现场建议：开幕前、每次发布高峰前、每天结束时各备份一次。
|
||||
|
||||
### 8.3 如何恢复
|
||||
|
||||
服务端目前**没有一键恢复接口**，恢复需停机手工执行：
|
||||
|
||||
1. 在 Console 里**停止服务**，避免恢复过程中继续写入；
|
||||
2. 把当前的 `data\event_projs\<项目名>\event.db` 改名留档，确认恢复失败还能退回；
|
||||
3. 选一份目标备份复制为 `event.db`（覆盖原文件）；
|
||||
4. 同时删除同目录下的 `event.db-wal` 与 `event.db-shm`；
|
||||
5. 重新启动服务，核对积分榜与最近一次发布记录。
|
||||
|
||||
> `data\system.db` 保存账号与会话信息，一般不需要回退；如需一并回退，替换它的方法与 `event.db` 相同（同时删除 `system.db-wal` / `system.db-shm`）。
|
||||
>
|
||||
> 恢复会丢弃备份时间点之后的所有改动。现场若还有备机，优先切换备机比原地恢复更快。
|
||||
|
||||
### 8.4 整机迁移
|
||||
|
||||
把整个部署目录（含 `data\`）拷贝到另一台同版本 Windows 机器，启动 Console 即可，无需重新配置。
|
||||
|
||||
### 8.5 赛事项目包导出 / 导入
|
||||
|
||||
| 操作 | 位置 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| 导出 | 「导出 → 赛事项目包 → 导出 zip」 | 包内含 `meta.yaml`、`event.db`、`uploads/`、`rules.yaml`；整包拷走即可在另一台机器复现 |
|
||||
| 导入 | 「导出 → 赛事项目包 → 选择 .zip → 导入」 | **仅管理员**可操作；可填「重命名」，勾选「覆盖同名项目」会先二次确认 |
|
||||
|
||||
- 导入后项目落在 `data\event_projs\<项目名>\`；
|
||||
- 当前运行的服务端默认使用 `default` 项目。要让新导入的赛事生效，可在 Console 的 `config.json` 里把 `server.args` 改为 `["-config","config.yaml","-project","<项目名>"]`，然后重启 Console；也可以直接用 `scoreboard.exe -config config.yaml -project <项目名>` 启动；
|
||||
- 导入期间请勿停止服务端进程。
|
||||
|
||||
---
|
||||
|
||||
## 9. 故障排查
|
||||
|
||||
### 9.1 端口被占用，服务端起不来
|
||||
|
||||
1. 查看占用进程（Windows 命令提示符）：
|
||||
|
||||
```bat
|
||||
netstat -ano | findstr :19540
|
||||
```
|
||||
|
||||
2. 根据最后一列的 PID 结束进程：
|
||||
|
||||
```bat
|
||||
taskkill /PID <PID> /F
|
||||
```
|
||||
|
||||
3. 或按第 6.3 节把端口改到其他值（两处同时改）。
|
||||
|
||||
> 同一台机器不要启动两个 Console，否则会互相抢占端口和大屏。
|
||||
|
||||
### 9.2 大屏不亮 / 只有桌面
|
||||
|
||||
按顺序检查：
|
||||
|
||||
1. HDMI 线是否插好，大屏电源是否打开；
|
||||
2. Windows 显示设置是否为**扩展**模式；
|
||||
3. Console「大屏窗口」卡片是否显示已打开；点「重新排布」；
|
||||
4. 确认 `display.selection` 选屏策略是否漏掉了目标屏；
|
||||
5. 服务端未就绪时大屏最多等 20 秒才打开，稍等即可；
|
||||
6. 查看 Console 运行日志里的「大屏排布完成」「大屏加载」记录；
|
||||
7. 单屏窗口化时按 **F11** 可切全屏。
|
||||
|
||||
### 9.3 管理面板打不开
|
||||
|
||||
1. 确认 Console 里服务端状态为「运行中」；
|
||||
2. 本机访问 `http://127.0.0.1:19540/admin`，其他设备访问 `http://<主机IP>:19540/admin`；
|
||||
3. 确认 `config.yaml` 与 `console\config.json` 的端口一致；
|
||||
4. 检查 Windows 防火墙是否拦截了该端口；
|
||||
5. 用托盘菜单的「打开服务端管理面板」直接打开。
|
||||
|
||||
### 9.4 服务反复重启
|
||||
|
||||
- 打开 `logs\console.log`，搜索 `[server!]`，这是服务端错误输出；
|
||||
- 检查 `data\` 是否可写、磁盘是否已满；
|
||||
- 检查 `config.yaml` 语法与端口是否合法。
|
||||
|
||||
### 9.5 页面显示「示例数据」
|
||||
|
||||
- 表示前端连不上后端或接口未就绪，此时录入、发布等操作**不会写入真实赛事**；
|
||||
- 确认服务端状态为「运行中」、实时连接显示「实时在线」；
|
||||
- 恢复连接后刷新页面即可切换到真实数据。
|
||||
|
||||
### 9.6 大屏时间不对
|
||||
|
||||
- 系统没有外网 NTP，**以主机时间为准**；
|
||||
- 修改 Windows 系统时间与时区后，大屏顶部时钟会在下一次刷新时跟随（约 15 秒一次）；
|
||||
- 建议在开幕前校准主机时间。
|
||||
|
||||
### 9.7 安卓 TV 备选方案打不开
|
||||
|
||||
1. 确认电视与主机在同一局域网，主机 IP 为固定 IP；
|
||||
2. 电视浏览器地址填 `http://<主机IP>:19540/display`；
|
||||
3. 确认 `config.yaml` 的 `server.host` 为 `0.0.0.0`；
|
||||
4. 部分电视浏览器对 CSS 动画、字体支持有限，显示效果以实际设备为准。
|
||||
|
||||
### 9.8 忘记管理员密码
|
||||
|
||||
见第 5.5 节，使用 `scoreboard.exe passwd -config config.yaml` 重置。
|
||||
|
||||
---
|
||||
|
||||
## 10. 上线检查清单
|
||||
|
||||
- [ ] 服务端开机自启、崩溃自动拉起已验证
|
||||
- [ ] `data\backups\` 可写，已生成至少一份备份
|
||||
- [ ] 大屏 HDMI 输出定位正确、分辨率正确、字体正常
|
||||
- [ ] 管理端各角色账号可登录，权限正确
|
||||
- [ ] 主机 IP 固定，管理端 / 大屏地址已打印或做成二维码贴在操作台
|
||||
- [ ] 防熄屏、屏保、休眠、系统通知已关闭
|
||||
- [ ] 主机时间已校准
|
||||
- [ ] 磁盘剩余空间充足
|
||||
- [ ] 安卓 TV / 浏览器备选通道实测可打开页面
|
||||
Reference in new issue
Block a user