AskaEth
9c52dc4b38
主人点名要的功能：大屏控制页加一个**可热开关**的侧边栏，在**指定的屏幕**上（不管它当前在哪一页）叠一个
**手填的赛事日程列表**，带**竖向进度条**；日程**不与登记的小项时间关联**、完全手填；竖向时间轴要好看，
**字多时字号自动缩放与换行**要做到位（不能过小、不能过大）。
设计口径（主人逐条拍板）：放不下时**围绕当前项开窗**；进度条是**一条竖向时间轴 + 三态节点**；
**深色半透明 + 毛玻璃**；已完成的项**淡化保留**；备注**默认上屏 + 一个总开关**；
明细覆盖层 / 全屏公告期间**自动收起**、结束后自动回来；编辑权限**录入员及以上**；单屏覆盖按**实例 id**。
服务端（走大屏公告那条路 —— PUT /api/settings 是 admin-only，会与「录入员可改」冲突）
- 新增 `schedule` 动作 + 白名单；`POST /api/display/command` 同一个 handler：**先校验 → 再转发 → 最后落库**
（校验排在转发前，非法配置不会在大屏上闪一帧）
- 落库到赛事库 settings 的 `display.schedule`（**不新建表、不写迁移**，随赛事包走）；
与公告共用那份「写设置键 + bumpVersion」的实现
- **读写不对称容错**：写侧严格 400（含中文提示与第几条），读侧坏数据一律静默当空 —— 老数据 / 手改库不会炸大屏
- 上限：40 条；time ≤20 / title ≤40 / note ≤60（按字符，清洗控制字符）；宽度夹 15–40；覆盖 ≤50 条
- 口径收口三处：**时间允许为空**（与管理端同口径）、**showNote 缺键 = true**（区分「键不存在」与「显式 false」）、
**`inherit` 不落库**（不再白占覆盖预算）
大屏端
- 新增 `ScheduleSidebar.vue` + `schedulePanel.ts`（纯函数：开窗 / 三态 / 整体进度 / 字号与行数 / 按显示宽度截断 /
单屏覆盖 / 抑制 / 指纹去重）
- 字号是**舞台设计坐标**（1920×1080），靠 `.stage` 的 `transform: scale()` 整体缩放，**不做二次缩放**
（wiring 断言禁止出现 `window.`/`innerWidth`/`vh`）；复用既有的 `fitRowFontPx`（**16–56px 硬上下限**）与 `textEm`；
固定点迭代 ≤4 轮；**贴下限时宁可行数少也不缩字**；标题 ≤3 行、备注 ≤2 行，超出截断
- 容器 `position:absolute; inset:0; z-index:50`（**不用 fixed** —— `.stage` 带 transform，是 fixed 后代的包含块）；
**独立于 detail 状态机**（goto 会关明细、明细会停轮播，侧边栏必须不受影响）
- 深色半透明 + `backdrop-filter`，并带 `@supports not (backdrop-filter: blur(1px))` 退化为更不透明的深底
- 关着时**不留任何 DOM**（逐字节等同于没有这个功能）；`prefers-reduced-motion` 下不做动效
管理端
- 大屏控制页（左列、公告之后）新增「赛事日程」卡片：条目表格（时间/标题/备注/已完成 + 上移/下移/删除）、
总开关、备注上屏、位置与宽度、**每块屏三态覆盖**（跟随 / 强制开 / 强制关；切回「跟随」会真删掉那条键）
- 保存走 `adminApi.displayCommand`（**不走 admin-only 的设置接口**）；本地校验不过**一个请求都不发**
- 排序只有上移 / 下移（该页面禁止挂 pointerdown/mousedown 监听，有既有测试钉着）
测试
- 服务端 16 个包全绿；前端 **1174 例**全过（基线 1096，本批 +78：大屏端 44 + 管理端 34）
- 大屏端另有 **40 项 playwright 实机**（用 `page.routeWebSocket` 假造实时通道）：开/关后 DOM 无残留、
五个页面下都在、`lock=0` 真等轮播翻页且侧边栏不掉、明细与公告期间自动收起并自动回来、
**1080p 与 4K 字号完全相同**、`reducedMotion` 下无动画；并钉住两条硬指标（真机列表高度 ≥ 纯函数预算、
容量×行高 ≤ 真机高度）
文档：`docs/升级说明` 新增 `dev_0.5.16`；`使用手册` 9.2 + 17.6；`常见问题` Q108–Q111；`上线检查清单`/`部署指南`
各一条；`devdocs/05·07·13` 同步。
⚠️ 一条**既有边界**（本版故意没改，按主人「兼容性最大化」的要求）：导出的名次口径是「通道名次优先」、
屏幕是「成绩行名次优先」，只在「先按决赛计分发布、之后又只更新名次发布一次」这种序列下分叉
（导出显示上次计分的名次）。正常赛程遇不到；遇到时对该组再「按决赛成绩发布」一次即恢复一致。
已写进《升级说明》④ 与《常见问题》Q111。
105 lines
17 KiB
Markdown
105 lines
17 KiB
Markdown
# 上线检查清单
|
||
|
||
> 比赛当天照着走一遍即可。细节见 [部署指南](./部署指南.md) 与 [使用手册](./使用手册.md)。
|
||
|
||
## 1. 交付物
|
||
|
||
| 文件 | 用途 |
|
||
| --- | --- |
|
||
| `Scoreboard Console-<版本>-x64.exe` | NSIS 安装包（推荐），双击按向导装 |
|
||
| `Scoreboard Console-<版本>-x64.zip` | 免安装包，解压即用 |
|
||
| `scoreboard.exe` | 服务端本体（已内嵌前端页面） |
|
||
|
||
> **版本号以 `dist\console\` 下的实际文件名为准**（构建时从仓库根 `VERSION` 生成，不在这里写死）。
|
||
> 校验完整性：`certutil -hashfile "Scoreboard Console-<版本>-x64.exe" SHA256`（`<版本>` 照 `dist\console\` 里的实际文件名填）
|
||
|
||
## 2. 目标机（服务端主机）
|
||
|
||
- [ ] Windows 10/11 x64，接市电（建议接 UPS）
|
||
- [ ] 端口 **19540** 未被占用：`netstat -ano | findstr 19540`
|
||
- [ ] **防火墙已放行入站 19540**（局域网设备才能连上）—— **自检口径：用另一台设备（平板 / 手机）浏览器打开 `http://<主机IP>:19540/display` 能出画面，就算放行过了**；打不开时先确认装的时候选的是哪一项：
|
||
- 装的时候选了**「为所有用户安装」**：那一档提权时装好规则，**已经自动放行**（防火墙里能看到规则 `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\Scoreboard_Console`，并自动放行防火墙）；只给当前账户用、或这台机器装不了 Program Files 时选**「仅为我安装」**（装到用户目录、防火墙要手工放行）。装完**右键桌面「赛事积分榜」快捷方式 →「属性」→ 看「目标」**核对实际装到哪个目录。⚠️ Console 自己的 `console.log` 写在**安装目录**的 `logs\` 下 —— 如果装完「运行日志」面板一直空着 / 安装目录里没有 `logs\console.log`，多半是那个目录当前账户写不进去，**改装到 `D:\Scoreboard` 这类普通目录**（向导里可以改；手工改过路径后切换装法也不会被冲掉）重装一次
|
||
- [ ] **升级（覆盖安装）前确认旧版本程序已关闭**：新版安装程序**会自动关掉**在跑的旧版本（含它拉起的 `scoreboard.exe` 服务端进程），但动手前自己在托盘 / 任务管理器确认一遍更稳（有正在录入的现场就别在赛中升级）；装完启动，确认打开的还是原来那个数据目录（「运行日志」里的 `数据目录：`）
|
||
|
||
## 3. 首次启动
|
||
|
||
- [ ] 双击 `Scoreboard_Console.exe`，启动管理窗口出现
|
||
- [ ] 服务端状态变为「运行中 · 就绪」
|
||
- [ ] 「运行日志」里 `数据目录：` 指向 `%LOCALAPPDATA%\ScoreboardConsole\data`（**不是**安装目录），且没有「都有数据 / 迁移失败」的警告
|
||
- [ ] 「运行日志」里 `用户数据目录：` 指向 `%LOCALAPPDATA%\ScoreboardConsole`，且没有「准备 … 失败」的警告（配置与规则也在那儿，见部署指南 3.5）
|
||
- [ ] 打开管理面板（窗口内「打开服务端管理面板」按钮），用管理员账号登录
|
||
- [ ] **管理员初始密码**在 `logs\console.log` 里搜 `INITIAL ADMIN CREATED`，密码就在该行上方；也可以直接打开 Console 的「运行日志」面板往上翻。首次登录会要求改密
|
||
|
||
## 4. 赛事配置（管理员）
|
||
|
||
- [ ] 「系统设置 → 赛事信息」的**基本信息**：填名称、副标题、主办方，上传**赛事会标**
|
||
- [ ] 同页的**大屏配置**：上传大屏会标、选大屏背景图，填大屏标题 / 副标题、轮播间隔与主题色（上传的图片随赛事项目包一起导出/导入）
|
||
- [ ] 同页的**字体**：确认**标题字体**与**正文字体**已选好（默认、四款内置字体，或自己上传的字体）；选完点「保存」，并核对大屏上标题与正文显示正常。上传的字体存在赛事项目的 `uploads\fonts\` 里，**导出赛事项目包会一并带走、导入后不用重新上传**（见使用手册 14.3、部署指南 8.5）
|
||
- [ ] **登录有效期按赛程设好**：到「系统设置 → 登录有效期」把有效期设成覆盖本次比赛全部时段的时长（默认 **24 小时**、可调 **1–720** 小时，跨天比赛建议 **72 小时**），并核对页面顶部「当前会话将于 … 过期」；比赛期间操作员长时间不操作也不会掉线，但它不是「永不掉线」（见使用手册 14.4、常见问题 Q89）
|
||
- [ ] **收表口径已交代**：提醒各单位报名名单里的**证件号**是系统认人的第一依据（有就优先填、填准，一人一号）；没有身份证的人用**号码布**顶替，同一个号码布不能给两个人（重号行会被跳过）；同一个人报多个组别时号码布可以重复（见报名名单导入规范）
|
||
- [ ] **赛事项目确认 / 导入**：到「导出 → 赛事项目包」核对**赛事项目列表**里带「当前」徽标的是本次要用的赛事；需要换赛事时先「导入 .zip」，再点「切换为当前赛事」（服务端会重启一次，页面显示「正在重启服务端…」，恢复后自动刷新）。账号与会话在数据目录的 `system.db` 里，**不受切换影响**，一般不用重新登录。这一步做完再往下走，否则后面看到的是别的赛事的数据
|
||
- [ ] **导入规则包**：`%LOCALAPPDATA%\ScoreboardConsole\rules\2026-驭电利刃杯军事运动会.yaml`，走「导出 → 规则包 → 选择 YAML → 预览差异 → 确认导入并全量重算」（规则目录在用户数据目录里，见部署指南 3.5）
|
||
—— 服务端不会自动加载规则包，必须导入一次
|
||
- [ ] 检查计分模板：个人前六名 `10/8/6/3/2/1`、团体 `15/10/8/4/2/1`、最后一名不得分
|
||
- [ ] **按赛事规则逐项核对过「奖牌结算开关」与「奖牌通道」**：到「基础数据 → 大项 / 小项」逐个确认要发牌的小项都勾着 **「该项启用奖牌结算」**（不该发牌的项目取消勾选）；再到「基础数据 → 计分通道」逐项核对每条通道的 **「发奖牌」** 与（个人名次通道的）**「个人奖牌并入单位金牌榜」** 是否符合本场赛会规则。关掉的通道在「大项 / 小项」页的通道摘要里会标出 `不发奖牌` / `个人奖牌不并入单位榜`（见使用手册 10.2、10.4；查不出原因时按常见问题 Q94 逐条排除）
|
||
- [ ] **升级 / 首次启动后确认奖牌榜数字与上一场一致（不是全 0）**：本版新增迁移 0020，迁移只建表不回填，服务端会在下一次启动时自动全量重算补齐名次——「运行日志」里出现 `检测到通道名次为空但已有已发布成绩，正在执行一次性全量重算` 与 `一次性全量重算完成，通道名次与奖牌榜已补齐` 是正常的，不是报错；等它跑完后刷新「积分榜 → 单位奖牌榜」，与升级前的数字（或备份里的导出件）对一遍，**不能是全 0**（见部署指南 3.4、常见问题 Q96）
|
||
- [ ] 「只排名不计分」的项目（飞行人员战斗体能）导入后应显示为不计分
|
||
- [ ] 「基础数据 → 参赛单位」里各单位的 logo 都已上传（会显示在总积分榜、单位奖牌榜、分项成绩表与个人积分榜上）
|
||
- [ ] 同页核对**单位名单齐全、没有误删**：被「彻底删除」的单位不会出现在这个列表里（它的报名、成绩与积分仍在库里，积分榜照常显示它）；发现少了就用它的编码导入一次报名表，它会重新出现（详见使用手册 10.1、常见问题 Q61–Q64）
|
||
|
||
## 5. 大屏
|
||
|
||
- [ ] 接好扩展屏后，服务管理窗口点「重新排布」
|
||
- [ ] 确认大屏锁定在「积分榜」页面；需要轮播就在后台开启
|
||
- [ ] 鼠标移到大屏上应看不到操作按钮；大屏窗口已开防熄屏
|
||
- [ ] 只有一块屏时是窗口化模式，按 **F11** 可切全屏（用于单屏测试）
|
||
- [ ] **调试标识已隐藏**：多屏 kiosk 全屏画面上不该出现「实例 … · 屏 …」；窗口化窗口（单屏）里显示这一行属正常，按 F11 全屏后它与自绘标题栏一起消失（版本号角标已移除，任何画面都不该出现）
|
||
- [ ] **显示器菜单可用**：在服务管理窗口里点「打开服务端管理面板」，进「大屏控制 → 显示器」，能看到每块屏；副屏点「创建全屏窗口」能重新开出来（单屏 / 主显示器只能窗口化，属正常）
|
||
- [ ] **在线大屏与逐屏切页**：同页右侧「在线大屏」列表能看到本机每块屏的在线实例（局域网设备也已在这一列表里，标记为「局域网浏览器」，并带一个**可读的设备标签**；两台同型号设备分不清就点「**改名**」起一个现场看得懂的名字），每行显示当前所在页；用某一行自己的下拉 +「切到此页」能把那一块屏 / 那台设备单独切走，其余屏不受影响（离线实例的控件为灰色，属正常）
|
||
- [ ] **局域网大屏能在别的设备打开**：用另一台设备（平板 / 手机）浏览器打开 `http://<主机IP>:19540/display` 能出画面，或直接扫「大屏控制 → 局域网大屏」卡片第一个地址的**二维码**；打不开时先看卡片列出的地址与提示，再按常见问题「大屏控制页显示未检测到局域网地址怎么办？」逐条排查（若卡片地址是 `169.254.x.x`，说明本网段没有 DHCP，同网段的设备照样能连）
|
||
- [ ] **公告可用**：推送一条测试公告 → 大屏全屏显示 → 到时退回原页且**底栏公告栏仍常驻显示正文** → 点「清除公告」后底栏回到「暂无公告」
|
||
- [ ] **实时赛况配置正确**：「大屏控制 → 实时赛况」卡片里模式与项目已按今天赛程选好（自动判定 / 人工指定），「当前生效」显示的就是此刻该显示的项目；大屏切到「实时赛况」页能看到该项目**已发布**成绩的实时排名（两个项目同时进行时应自动左右分栏）
|
||
- [ ] **赛事日程侧边栏可用**：到「大屏控制 → 赛事日程」（左列、公告卡下面）加两条日程 → 点「保存」→ 大屏**当前页上**应当叠出侧边栏（默认右侧 22 %）、顶部读数 `已完成 0 / 共 2`，**大屏不换页、轮播不停** → 勾一条「已完成」再保存 → 那条淡化、读数变 `已完成 1 / 共 2` → 打开一次积分明细覆盖层（或推一条公告）：侧边栏应**自动收起**，关掉后**自己回来** → 最后**按今天的口径决定总开关**（不公示就关掉，关掉后大屏应恢复原样），并用「每块屏单独设置」把不该显示的那块屏设成「强制关」。⚠️ 这是**低频动作**（每次保存全场大屏全量重拉一次），开赛前配一次即可（见使用手册 9.2 / 17.6）
|
||
- [ ] **分批发布演练**：选一个分多场跑的项目，先只填一批成绩发布（发布窗口里按当天口径选「只更新名次」或「按决赛成绩发布」，选完才确认）→ 大屏立即出现这一批的排名 → 补录下一批再发布 → 排名自动重算（未录的行不会被当成 0 分，也不挡发布）
|
||
- [ ] **分项成绩页看得全**：切到大屏「分项成绩」页，**每一栏（含第 3 栏）都从第 1 名开始**；**团体项目的名次列不应是 `-`**（升级后不用重发、不用重算，刷新即可）。⚠️ 例外：只在「团体名次」卡片里按单位录了名次、成绩行上没填的项目仍无大屏名次（见常见问题 Q105 / Q106）
|
||
- [ ] **报名项批量操作演练**：在「成绩录入」勾选几行试一次**批量退赛 → 批量恢复**（确认框会逐条列出被跳过的 dq / dns 行及原因）；「批量移出报名」是**物理删除、不可恢复**，只演示确认框、不要在真实报名上执行（详见使用手册 4.8）
|
||
- [ ] **报名名单导出演练**：「导出 → 结果导出 → 报名名单」按小项 / 组别 / 单位 / 批次筛一次并导出，核对 13 列与状态中文（正常参赛 / 已退赛 / 取消资格 / 未出场）与录入页一致
|
||
|
||
## 6. 数据与备份
|
||
|
||
- [ ] 确认数据目录 `%LOCALAPPDATA%\ScoreboardConsole\data` 下的 `backups\` 里已出现 `system-auto-*.db` 与 `event-auto-*.db`（默认每 5 分钟）
|
||
- [ ] 确认数据目录下已生成 `logs\operations\` 与 `logs\interceptions\`（服务端日志，见部署指南第 10 节），并知道操作被拒时去 `interceptions\` 当天文件里搜原因与拦截点
|
||
- [ ] 开幕前手动点一次「立即备份」（「系统设置 → 备份 → 立即备份」）
|
||
- [ ] 把整个数据目录（不只是 `backups\`：`event_projs\<当前项目名>\uploads\` 里还有会标、背景图、单位 logo 与上传的字体）拷一份到 U 盘
|
||
- [ ] 留一份成绩总表存档：到「导出 → 结果导出」导一份**全部（单页）**（`赛事成绩总表（单页）.xlsx`，一个工作簿一张表，适合比对与筛选），需要归档打印再导一份「全部」（多 sheet）
|
||
- [ ] 导出并留档一份**基础数据包**：「导出 → 基础数据 → 导出 xlsx」得到含**单位 / 大项 / 小项 / 组别**四张工作表的工作簿；它可按编码原样导回（存在就更新、绝不删除），赛前改乱基础数据时可以拿它对照 / 回灌
|
||
|
||
## 7. 现场流程演练（建议至少一次）
|
||
|
||
- [ ] 录入员登录 → 录入一条成绩 → 存草稿 → 点「**发布**」（弹出的窗口里**默认是「只更新名次（不计分、不发奖牌）」**；今天这一项要计分发牌就选「**按决赛成绩发布**」再确认）→ 大屏刷新
|
||
- [ ] 撤销发布 → 修改 → 重新发布（历史记录里能看到链路）
|
||
- [ ] 导出核对：「结果导出」里「全部」与「全部（单页）」都能正常下载（后者应是一个工作簿、只有一张表）；「积分榜」页三个榜单的卡片头各有导出——单位总分榜「导出总明细」得到 `单位积分总明细.xlsx`、单位奖牌榜「导出奖牌明细」得到 `单位奖牌明细.xlsx`、个人积分榜「导出个人明细」得到 `个人积分总明细.xlsx`；展开某单位后还能点「导出该单位明细」得到 `单位积分明细.xlsx`
|
||
- [ ] 断网 → 大屏仍显示缓存数据 → 恢复后自动补增量
|
||
- [ ] 重启服务端 → Console 自动拉起
|
||
|
||
## 8. 出问题时的回退
|
||
|
||
| 故障 | 动作 |
|
||
| --- | --- |
|
||
| 服务端无响应 | 服务管理窗口「重启服务」 |
|
||
| 导入赛事包后看不到数据 | 到「导出 → 赛事项目包 → 赛事项目列表」把该项目「切换为当前赛事」（服务端会重启一次，页面恢复后自动刷新，一般不用重新登录），详见部署指南第 8.5 节 |
|
||
| 主机死机 | 备机启动同一份部署包，把用户数据目录（`%LOCALAPPDATA%\ScoreboardConsole\`，含数据、配置与规则）拷回去 |
|
||
| 数据库损坏 | 停机，用数据目录下 `backups\` 的最新备份替换 `event_projs\<项目名>\event.db`（先删 `-wal`/`-shm`），详见部署指南第 8.3 节 |
|
||
| 大屏黑屏 / 窗口被误关 | 服务管理窗口「重新排布」；仍不行就到「大屏控制 → 显示器」点该块屏的「创建全屏窗口」；最后才用备用笔记本开同一地址 |
|
||
| 覆盖安装后数据/配置不见了 | 看「运行日志」里的 `数据目录：`、`用户数据目录：` 与迁移警告，按部署指南第 9.9 节处理 |
|
||
|
||
> 完整恢复步骤见 [部署指南 · 备份与恢复](./部署指南.md#8-备份与恢复)。
|