AskaEth
99c91f99f7
## 需求（主人原话）
> 「双打我给他定义的是团队赛事，团队赛事不应该本来就是可以配置多个人的吗」
> 「把队员身份证留住，**应该是服务于整个团体报名**」
**现状问题**：界面（`EntryPicker`）**本来就能勾多个运动员**，但提交时只把姓名拼成文字
（`entrySelection.ts` 的 `input.athletes.map(a => a.name)` 存进 `entries.member_names TEXT`）→ **身份全丢**
→ 系统不知道队里坐着谁 → **所有团体/对抗项目都给不出个人分、个人奖牌，上不了个人积分榜**。
## 口径
- **运动员的唯一标识是号码布**（主人明确更正，不是证件号）。
- **每个队员各拿一份完整的个人分** —— 是「**复制**」不是「拆」（与联队 `splitSharePoints` 正好相反）。
- **个人奖牌每人各一枚**；**单位总分与单位奖牌不受影响**（由通道开关 `count_to_team` / `count_to_team_medals` 控制）。
## 一、数据
- 迁移 `0026_entry_athletes.sql`：新表 `entry_athletes(entry_id, athlete_id, sort_order)`，PK `(entry_id, athlete_id)`，两个外键都 `ON DELETE CASCADE`。
`entries` **一个字节没动**（`member_names` 保留为显示用名单；多队唯一键 `(category_id,team_id,squad) WHERE athlete_id IS NULL` 未触碰）。
- **老数据回填（尽力而为）**：拿 `member_names` 去 `athletes` 匹配 —— **号码布优先**，其次「姓名 + 单位」且同单位同名唯一；**匹配不上留空**，不硬猜。
## 二、引擎
- `RankedResult.MemberCopy`（报名项那份 `false`、队员副本 `true`）；**只在 `scope=athlete` 通道展开**（`scope=team` 与 `basis=aggregate` 不展开）。
- **单位维度不重复计算的三道锁**（本单最大的坑）：
1. 队员副本流水 `count_to_team` **恒为 false** —— 单位总分那条 SQL 第一句就跳过它，而个人榜不看这个开关；
2. 单位奖牌仍按**报名项**去重、且报名项那份**排在最前**；
3. 队员副本**照抄 `TeamID` 与 `Shares`**（不换单位、不另造份额 —— 联队报名尤其危险）。
反面也测了：个人奖牌若按报名项去重会**一枚都发不出来**（被 `AthleteID=0` 那份吃掉），故改为按「报名项 + 运动员」去重。
## 三、写 / 读
- `PUT /api/entries/{id}/athletes`（recorder+、CSRF）：body `{"athletes":[{"athleteId":12}],"requestId":"..."}`，**只认 athleteId**；空数组＝清空；
改完当场重算推榜。400：athleteId 缺/不存在、同一人两次、>30 人、个人报名不能挂队员。
- 读：`entryDTO.athletes: [{athleteId, name, bib}]`（**始终是数组**）；`memberNames` 原样保留，**两者可并存**（没档案的人只能留文字）。
## 四、导入
- 报名表「队员名单」列现在**按号码布认人**（命中即关联，同时保留文字）；⚠️ **姓名完全不做匹配**（同名会认错，而认错的分已经上了榜）；匹配不上**不报错、只当文字**。
- 边界逐条有 notice/报错：跨单位号码布**照关联 + notice**（号码布是唯一标识）；同格重号只关联一次 + notice；**个人行**写了号码布只留文字 + notice；**认出 >30 人整行拦下**；成功时一条汇总 notice。
- **更新路必须重算**：老表先导入、成绩已发布，之后补上号码布重传 —— 不在更新路重算就会出现「名单里有队员、榜上没有他」（删掉该条件即红）。
## 五、界面与显示
- 补报名勾的人**真正提交**（导入成功后追加 `PUT /athletes`，**只发需要变的**：勾了人的单位、以及原来有队员这次一个没勾的（发 `[]`）；一个都没勾且原来也没队员的一律不发）；**队员写失败单独提示**（报名本身已加入，不冒充「加入报名失败」）。
- **改队员**：录入页「运动员/队」那格的**「队员」小按钮**（只有纯团体行才有），弹窗勾选式名单；**与「成员单位与份额」是两个独立写请求**（份额管「分给哪些单位」、队员管「这条报名里有哪几个人」）。
- 显示统一写法 **`姓名（号码布）`**（导出件；大屏只写姓名与 ` / ` 分隔 —— 号码布太长会把整屏字号压下去）；**没有队员关联的老数据一个字不变**；
⚠️ **一条报名仍只占一行**（有护栏测试钉着）；`squad`（队）与 `athletes`（队员）**正交**。
## 验证
- 全量自检两轮**全绿、`EXIT=0`**：服务端 14 包 / 前端 **921 例** 0 fail / Console 68 例 0 fail。
- 各块先红后绿并留原始输出；**老数据零变化**有 golden 对拍（引擎层 / 接口层 / 导出层逐行 dump）。
## 文档
`docs/报名名单导入规范.md`（队员列语义升级，列数仍是 13）、`docs/使用手册.md`（新增 4.13 团体报名的队员）、
`docs/升级说明.md`（新增 `dev_0.5.6` 一节）。
## 版本
`dev_0.5.5` → **`dev_0.5.6`**（含数据迁移 `0026`）；安装器素材同步重生成（照例只动 `brand.bmp` 两张）。
Scoreboard · 赛事积分榜系统
一套局域网内部署的赛事成绩与积分系统：一个服务端 + 两个界面，后台一改数据，前台大屏实时跟着变。
| 界面 | 地址 | 用途 |
|---|---|---|
| 实时积分大屏 | /display |
只读、无人值守；成绩发布后 1 秒内更新 |
| 管理面板 | /admin |
录入、发布成绩，控制大屏；未登录可只读查看全部赛事数据 |
功能概览
- 四个榜：总积分榜、团体奖牌榜、个人积分奖牌榜、分项成绩表
- 录入即上屏：成绩录入 → 发布 → 大屏即时更新
- 可追溯、可撤销：草稿不上屏；发布后纠错走「撤销发布 → 改 → 重新发布」，全程留痕
- 变更历史：仿 Git 图谱，一眼看清成绩是怎么变成现在这样的
- 现场公开：积分明细可下钻，争议时一键推送到大屏
- 全屏公告：推送后先全屏显示（5–120 秒），随即常驻大屏底部公告栏，直到替换或清除
- 分批发布：一个项目分多场跑（如跑道 8 条、30 人分 4 场）时，每跑完一批就能先发布一批——空成绩只是提示、不再挡发布，未录的行自动跳过，补录后再发一次即自动重算；名次与积分先按已发布的那部分算，大屏立刻有内容
- 实时赛况大屏页：新增「实时赛况」页，显示当前进行中项目的实时排名（名次 / 运动员·队 / 单位 / 成绩）；1 个项目单栏、2 个自动左右分栏；当前项目按「人工指定 → 排期命中（开始时间前后 30 分钟）→ 最近发布过成绩的项目」判定，下一场开始前持续显示上一场；可在「大屏控制 → 实时赛况」卡片配置
- 显式批次层：组别之下可再分批（
第 1 批、第 2 批…），录入页按批筛选、只在自己这一批里找人；支持手动勾选设置批次、报名表可选列heat、以及按人数「一键均分」。批次只是录入 / 展示分组，不参与算分——名次与积分仍按「小项 + 组别」计算 - 成绩框实时提示：聚焦成绩格打字时旁边浮出小气泡——合法显示解析结果（
1:06→= 66 秒）、可疑 / 不合法直接说原因并带出那一格原文；不挡输入、不改行高，与发布前防呆同一套口径 - 窄屏 / 手机可用：管理面板适配窄窗口与手机浏览器（局域网访问
/admin）：侧栏收成抽屉、宽表格横向滑动、对话框不超出屏幕、触控目标放大 - 小项类型齐全：个人 / 团体 / 对抗比赛 / 个人+团体（同一个项目同时按个人与团体通道记分）
- 多显示器：支持多屏各锁一页（kiosk 全屏），也能在管理端为指定显示器单独开窗或收窗；「大屏控制」页的「在线大屏」列表实时显示每个在线实例（含局域网浏览器打开的
/display）当前在哪一页，可逐屏 / 逐设备单独切页 - 规则可配置：积分规则以规则包（YAML）描述，可导入导出、跨赛事复用
- 运动员名册：启用 / 停用 / 彻底删除三档——「停用」保留全部历史数据、随时可启用；「彻底删除」把人员档案连同他名下的报名、成绩与积分流水一起删掉且不可恢复，并自动按新排序重算受影响小项的排名与积分（大屏同步更新）
- 参赛单位名册：启用 / 停用 / 彻底删除三档——「停用」保留全部历史数据、随时可启用；「彻底删除」是假删除，只把单位从列表里移除（界面上没有恢复入口），它的报名、成绩、积分流水与名下运动员全部保留，积分榜不会变化；报名表里再次用到该单位编码会让它自动恢复
- 赛事独立存档：每个赛事一个独立项目目录，整包可导出/导入（含会标、背景图、单位 logo 与上传的字体），并可在管理端页内一键切换当前赛事
- 结果导出：Excel 总表、全部（多 sheet）、全部（单页）、分项成绩表、单位积分明细可分别导出；「积分榜」页三个榜单的卡片头各有自己的明细导出——单位总分榜导出总明细（总表 + 每个有数据的单位一张分表）、团体奖牌榜导出奖牌明细（逐枚奖牌列出来源）、个人积分榜导出个人明细（逐条得分来源，与个人榜一致且不受折算系数影响），展开单位还能导出该单位明细
- 日志可复盘：服务端在数据目录
logs\下按「放行 / 拦截」两类分目录落盘——operations\记放行的写操作与常规运行日志，interceptions\记我们主动拦下的报错与服务端异常；拦截日志带中文原因与拦截点文件:行 函数名、操作人与 requestId，两类都按天 + 按大小轮转并自动清理旧文件（见部署指南第 10 节） - 成绩写法容错：时间类接受
66、66.33、1:06、1:06.33、1分06秒、1小时2分3秒等写法（全角冒号 / 全角数字也认），秒位 ≥ 60 会被拒但报错写明原因；成绩格里的示例是带「例」字的淡色斜体灰字，不会和已填内容混淆 - 单位 logo：大屏端的积分榜、奖牌榜、分项成绩表与个人榜都会显示参赛单位 logo（个人榜显示在姓名前；管理端页面只负责上传与配置，不显示 logo）
- 大屏字体可配：标题字体与正文字体可在「系统设置 → 赛事信息 → 字体」里从四款内置字体中选，或上传自己的字体（ttf / otf / woff / woff2，单个不超过 20 MiB）；只作用于大屏，加载失败自动回落默认字体，字体文件随赛事项目包一起导出/导入
快速开始
- 解压部署包
- 双击
Scoreboard_Console.exe（现场推荐：守护服务端、把大屏投到扩展屏、防熄屏、开机自启） - 浏览器打开终端提示的地址
大屏 http://<主机IP>:19540/display
管理面板 http://<主机IP>:19540/admin
也可以直接双击
scoreboard.exe（Linux 下执行./scoreboard）只跑服务端，大屏投放与进程守护需自行接管。完全离线运行，不依赖外网，不需要安装任何运行时。
文档
- 升级说明：每次升级前先看——这一版改了什么、升级后要补做什么、分数/奖牌为什么变化、5 分钟核对清单
- 上线检查清单：比赛当天照着走一遍的核对表（含交付物、目标机、首次启动、赛事项目包与规则包导入、大屏与公告、备份与回退）
- 部署指南：运行环境、安装与首次启动、端口与配置、大屏接线、赛事项目包导入/切换、备份恢复、故障排查
- 使用手册：角色权限、各功能页面的操作步骤、大屏端使用、常见操作问题
- 报名名单导入规范：报名表该用什么格式、11 列逐列怎么填、个人/团体/「个人+团体」三种项目的填法、常见报错对照（可直接发给各单位填表人）
- 常见问题（FAQ）：账号、成绩与积分、大屏、数据备份、导出导入
- 规则包格式：见 rules/README.md
许可证
MIT