AskaEth/Scoreboard
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(p2): 按审查清单修 103 条「建议修」+ 奖牌榜改名 + 两个守卫（dev_0.2.0）

Browse Source 
## 奖牌榜改名（主人要求）
「团体奖牌榜」→「单位奖牌榜」，界面 / 大屏渲染页 / 导出件（工作表名与
下载文件名 `单位奖牌明细.xlsx`）/ 用户文档 全部统一；`DISPLAY_PAGES` 是
大屏控制页与大屏页的共同来源，改一处两边同时生效。旧名保留为别名，
老链接与老配置（`display.pages`）照常有效。真 Chromium 验证：14 个管理端
路由 + 7 个基础数据分区 0 报错，大屏页标题已是「单位奖牌榜」。

## P2 清单（123 条，103 条标「建议修」）
按 A/B/C/D 分组、以「文件所有权互斥」分 10 个代理并行推进，另有独立复核
代理逐条核对：61 条声称已修 / 55 条证实 / 4 条部分 / 0 条不成立 / 0 垃圾。

主要交付（按风险从高到低）：
- 写入侧校验：update 路径补必填与 TrimSpace、模板 rules 重复 rank、
  「小项不存在」的四种回答、`defaultProfileId` 外键、decodeJSON 的 8MB
  上限与 413（A01–A06、D02、D03 批量上限 500）
- 危险操作：一键恢复加互斥（第二个请求当场 409）、恢复超时不再说
  「未执行」、`ConfirmDialog` pending 时锁死 ESC/遮罩/关闭
- 认证：改密与撤会话进同一事务、滑动续期写库失败不再假装成功、
  CSRF Cookie 丢失自动补发、密码长度按字符（原按字节）、
  反代 403 只在可信代理透传原 Host 时采信 `X-Forwarded-Host`（全等比较）、
  过期会话定期清理、登出补审计、登录限流可配
- 数据可见性：导出「已发布未结算」行改为 `名次 — / 积分 — / 状态未结算`、
  单位积分明细成绩列与其它导出件逐字一致、空单位也打合计行、
  基础数据包命中「已彻底删除的单位」整行跳过并报界面路径、
  报名导入换单位给明确提示、勾选报名有冲突不再假报成功
- 导入/导出：赛事包上限 512MB（**它是唯一带字体/图片的包**，字体上限
  20MB）而 multipart 内存档位独立钉在 16MB、工作簿表名尾随空格、
  导出件路由与文件名契约补全
- 前端：一次写请求只生成一个 requestId（幂等缓存此前从未命中）、
  基础数据包补 `X-Request-Id`、示例数据模式禁写扩到撤销发布/存草稿、
  访客 401 不再是裸错误、模板 `{{else if}}` 不再静默吞内容
- Console：按设计退出（切赛事/恢复）不再判成崩溃、旧数据目录读不出来
  会记日志、渲染层日志按上限截断、`service.js` 补 17 例测试

## 测试
服务端用例 610 → 674（13 包全绿，新增老库跨九条迁移升级、panic 形状、
429 落 interceptions、三态对照、avg_mode 分母、会话失效、请求体上限等）
前端 449 → 531（vue-tsc + build 通过）；Console 28 → 54（19 个文件）。
另修复一条会让整包挂死 600s 的用例（测试主协程堵在 client.Do，defer
轮不到执行 → 改为可取消 + 探针超时，改坏也 7.5s 快速失败）。

## 两个新守卫（防止再出现「组件 setup 抛异常」这类盲区）
- `web/scripts/check-declaration-order.mjs` 已进测试命令：沿 watch/
  watchEffect 的 const 依赖链查 TDZ（正是「运动员页整块空白」的根因）
- `web/scripts/smoke-admin.mjs`（`pnpm smoke`）：真 Chromium 点遍 14 个
  管理端路由 + 7 个基础数据分区 + 大屏页，任何 console 错误即失败

## 文档
- `docs/升级说明.md` 新增 dev_0.2.0 一节（三件升级必知：改名、审计前缀
  与历史记录、密码口径；现场变化；赛事包上限；反代与 CSRF）
- 使用手册 / 常见问题 / 部署指南 / 上线检查清单按实现同步
This commit is contained in:
AskaEth committed 2026-09-11 23:46:59 +08:00
1 parent db94d9c119
commit 6841cf49aa
147 files changed
+8141 -423
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

console/README.md
+8 -5
View File
@@ -25,6 +25,7 @@ console/
│ ├── userpaths.js # 配置/规则目录解析 + 首次复制迁移（config.json / config.yaml / rules）
│ ├── userpaths.test.js # 配置/规则路径的单元测试
│ ├── service.js # 服务端子进程守护：spawn / 日志转发 / 健康检查 / 自动重启
│ ├── service.test.js # 守护逻辑的单元测试（注入假 spawn/时钟/HTTP）
│ ├── instances.js # 已连接大屏实例看板：复用管理面板登录态读 /api/display/instances
│ ├── account.js # 管理员账号重置：参数校验 + 调 scoreboard.exe passwd
│ ├── displays.js # 大屏窗口管理：选屏、kiosk、排布、24h 重载
@@ -87,6 +88,7 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
- Console 把最终目录通过服务端的 `-data <绝对路径>` 传下去，`passwd` 子命令带同一个参数，保证改的是同一个库里的账号；
- 迁移只在**打包态**做一次：**目标目录为空（或不存在）且 `<安装目录>\data` 有数据**时，用 `fs.renameSync` 把旧目录整体改名过去（同盘秒完成）。跨盘、权限不足等任何失败都只记日志，旧数据原地保留；
- **「没有旧数据」与「读不到旧目录」分开处理**：旧目录不存在/存在但空才是 `no-legacy`（不写日志）；旧目录读不出来（EACCES、ENOTDIR 等）返回 `legacy-unreadable` 并写一条「读不到旧数据目录」警告，绝不当成「没有旧数据」静默跳过（回归测试见 `main/datadir.test.js`）；
- 两边都有数据时**不做任何动作**，只写一条醒目日志提示人工确认，两份都不会被自动删除；
- 迁移结果与最终数据目录都写进 `logs/console.log`（搜「数据目录」「已把旧数据从」）；
- 数据目录若仍在安装目录内，启动时会额外打一条警告。
@@ -126,7 +128,8 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
| 页面锁定 | 每块屏各锁一页，URL 形如 `http://127.0.0.1:19540/display?page=standings&lock=1&screen=<id>&instance=<host>-<id>`，页序按 `display.pages` 轮转 |
| 防熄屏 | Console 启动即生效，退出时释放；前台后台都算 |
| 服务端就绪 | 首次 `/api/health` 通过后开大屏窗口；等待超过 `display.waitForServerMs` 也先开，避免现场只见桌面 |
| 服务端崩溃 | 按 `restartDelayMs` 递增退避自动重启（`maxRestarts=0` 为无限）；持续健康 `healthyResetMs` 后崩溃计数清零；恢复健康后自动重载大屏 |
| 服务端崩溃 | 按 `restartDelayMs` **线性**退避（第 N 次等 N × `restartDelayMs`，最多 5 倍）自动重启（`maxRestarts=0` 为无限）；持续健康 `healthyResetMs` 后崩溃计数清零；恢复健康后自动重载大屏 |
| 服务端按设计退出 | 切换赛事 / 一键恢复时服务端**先回执 200 再自己优雅退出**（退出码 0）。这种退出**不当崩溃**：状态是「重启中」（黄灯，不是红灯）、崩溃计数不 +1、同样按 `restartDelayMs` 自动拉起。判定见 `service.js` 的 `isPlannedExit`：退出码 0 **且**落在预期退出窗口内（最后一次健康检查通过后最多 15 秒，HealthInterval 更大时按两个探测周期放宽）——刚起来就退 0 或卡死很久才退 0 都仍按崩溃处理 |
| 数据目录 | 默认 `%LOCALAPPDATA%\ScoreboardConsole\data`（安装目录之外，覆盖安装/卸载都不删），启动时按 `-data <绝对路径>` 交给服务端；打包态首次启动做一次性迁移（见「数据目录」一节），开发态不接管 |
| 配置与规则 | 同样在 `%LOCALAPPDATA%\ScoreboardConsole\`（`console\config.json`、`config.yaml`、`rules\`），打包态首次从安装目录复制、之后只用用户目录那份；拉起服务端时 `-config` 传绝对路径（见「配置与规则目录」一节） |
| 停止服务 | 先 `POST server.shutdownPath` 并带 `X-Shutdown-Token`（启动时用 `crypto.randomBytes(32)` 生成，经环境变量 `SCOREBOARD_SHUTDOWN_TOKEN` 只交给该子进程）请求服务端优雅关闭；受理后最多等 `shutdownTimeoutMs`，超时或接口不可用（404/连接失败）再强杀 |
@@ -137,7 +140,7 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
| 服务端管理面板 | 用独立无边框 Electron 窗口加载 `http://127.0.0.1:<port>/admin`（`shell-preload.js` 暴露 `window.desktopShell`），不再调系统浏览器；面板页在浏览器里直接打开时标题栏自动不渲染 |
| 显示器菜单 | 面板页的「大屏控制 → 显示器」卡片经 `display:list` / `display:open` / `display:close` / `display:relayout` 指挥本机开窗：按屏创建、聚焦、收窗。**全屏只在「多于一块屏 + 非主屏」时放行**，判定在主进程做，页面传 `fullscreen: true` 也会被降级为窗口化；面板页只拿到这几条白名单通道，拿不到 `ipcRenderer` |
| 管理员账号 | 主进程 `spawn` 同目录 `scoreboard.exe passwd -config <同一份配置> -data <同一个数据目录> -user <当前用户名> -new-username <新用户名> -password <新密码>`（留空 = 不改 / 随机生成）。本机进程、不经 HTTP，因此免登录验证；用户名/密码含空格、制表符或换行会被主进程拒绝，密码不进日志。`passwd` 会作废该用户全部会话，UI 提交前二次确认并提示 |
| 日志 | 内存环形缓冲（`log.maxLines`）+ 文件 `logs/console.log`（超 `maxFileBytes` 轮转一份 `.1`，轮转前会删掉旧 `.1` 以兼容 Windows）；文件固定落在部署包根目录（打包态 = 安装目录），不随配置搬到用户数据目录 |
| 日志 | 内存环形缓冲（`log.maxLines`）+ 文件 `logs/console.log`（超 `maxFileBytes` 轮转一份 `.1`，轮转前会删掉旧 `.1` 以兼容 Windows）；文件固定落在部署包根目录（打包态 = 安装目录），不随配置搬到用户数据目录；管理窗口按同一个 `log.maxLines` 截断（超上限从头部丢，长跑不变卡） |
| 服务管理窗口的路径显示 | 「服务端程序」「配置文件」两行分别是解析出的 `scoreboard.exe` 与 Console 自己那份 `config.json` 的绝对路径（打包态后者在用户数据目录里，见上一节） |
## 配置项（`config.json`；打包态生效的是用户数据目录里那份）
@@ -150,7 +153,7 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
| `server.host` / `server.port` | `127.0.0.1` / `19540` | 健康检查、关闭握手与管理面板地址（`0.0.0.0` 会自动换成回环地址探测） |
| `server.autoStart` | `true` | Console 启动后是否立刻拉起服务端 |
| `server.healthIntervalMs` | `5000` | 健康检查间隔 |
| `server.restartDelayMs` | `3000` | 重启基础退避，每次翻倍，最多 5 倍 |
| `server.restartDelayMs` | `3000` | 重启基础退避：**第 N 次等 N × 本值**（×1..×5，线性，不是翻倍） |
| `server.maxRestarts` | `0` | 0 = 无限重启 |
| `server.shutdownPath` | `/api/shutdown` | 优雅关闭握手接口（需服务端实现并校验 `X-Shutdown-Token`），不可用时回退强杀 |
| `server.shutdownTimeoutMs` | `5000` | 服务端受理关闭请求后等待其自行退出的上限，超过则强杀 |
@@ -165,7 +168,7 @@ electron-builder 生成的卸载器结尾是 `RMDir /r $INSTDIR`，而**覆盖
| `display.waitForServerMs` | `20000` | 服务端未就绪时开大屏的兜底等待 |
| `display.backgroundColor` | `#0b0f1a` | 窗口底色，减少加载白闪 |
| `startup.openAtLogin` | `false` | 默认注册但不启用（任务管理器可见、已禁用）；在服务管理窗口「开机自启」开关里控制（开发态不注册） |
| `admin.width` / `admin.height` | `1040` / `760` | 管理窗口初始尺寸（服务端管理面板窗口按 `width` 不小于 1100 取用） |
| `admin.width` / `admin.height` | `1280` / `860` | 管理窗口初始尺寸（服务端管理面板窗口按 `width` 不小于 1100 取用） |
| `log.maxLines` / `log.file` / `log.maxFileBytes` | `2000` / `logs/console.log` / `4194304` | 日志缓冲与文件；`log.file` 相对部署包根目录解析（不随配置搬到用户数据目录） |
配置缺项自动用内置默认值，文件不存在或 JSON 语法错误时回落到全默认值，并在管理窗口顶部给出提示。
@@ -182,7 +185,7 @@ pnpm dist # electron-builder --win --x64 → ../dist/console/
pnpm pack # 只出目录，不生成安装包，便于现场调试
```
- 产物：NSIS 安装包 + zip（`Scoreboard Console-0.1.1-x64.*`）。
- 产物：NSIS 安装包 + zip，文件名形如 `Scoreboard Console-<版本>-x64.*`。`<版本>` 不是手写的：`deploy/prepare-extra.mjs` 在打包前读仓库根 `VERSION`（当前 `dev_0.1.8`）去掉 `dev_` 前缀写进 `console/package.json` 的 `version`，`artifactName` 用 `${productName}-${version}-${arch}.${ext}` 展开 —— 也就是说**这里不要手改版本号**，改仓库根的 `VERSION`。
- `extraFiles` 会把 `../dist/scoreboard.exe`、`../config.yaml`、`config.json`、`../rules` 拷到安装目录 —— 这四样里的后三样（`config.json`、`config.yaml`、`rules/`）在打包态只当**模板**：首次启动时复制到用户数据目录，之后 Console 与 `backup.bat` 都只用用户目录那份（见「配置与规则目录」一节）。`config.json` 缺失时 Console 会回落到内置默认值。
- 部署包根目录的说明书是可选的：`deploy/prepare-extra.mjs` 在打包前按一张清单暂存到 `console/extra/`（`extraFiles` 会把该目录内容平铺到安装目录根）：`docs/使用手册.md` → `使用说明.txt`，`docs/报名名单导入规范.md` → `报名名单导入规范.txt`（各自优先取 `docs/` 下的同名 `.txt`）。缺哪个就在构建日志里注明并跳过。
- 图标在 `resources/icon.ico`（`package.json` 的 `win.icon` 指向它）。