运动会积分榜系统 · 开发文档集
| 项 | 内容 |
|---|---|
| 项目 | 一拖二运动会积分榜：一个服务端 + 实时积分大屏 + 裁判长管理面板 |
| 仓库 | ssh://git@git.yeij.top:2222/AskaEth/Scoreboard.git |
| 作者 | AskaEth |
| 文档版本 | v0.1（讨论稿） · 2026-09-09 |
| 状态 | 待确认：第 D1–D13 项未拍板前，不进入编码 |
本目录取代了早期的单文件《开发规划.md》。内容按模块拆开，改哪块就动哪份，避免一份文档越滚越长。
文档地图
| 编号 | 文档 | 内容 | 主要读者 |
|---|---|---|---|
| — | README | 索引、决策清单、阅读顺序 | 全部 |
| 01 | 需求与范围 | 目标/非目标、名词表、角色、赛事时间线、核心流程 | 主办方、产品 |
| 02 | 积分与排名规则 | 积分表、并列、双倍、破纪录、tie-break | 裁判长、开发 |
| 03 | 技术选型与架构 | 选型对比、模块划分、数据流、目录结构、编码规范 | 开发 |
| 04 | 数据模型 | 表结构、约束、索引、积分流水原则 | 开发 |
| 05 | 接口与实时协议 | REST API、Socket.IO 事件、断线重连 | 开发 |
| 06 | 大屏端设计 | 页面、轮播、动效、分辨率、无人值守 | 设计、开发 |
| 07 | 管理面板设计 | 信息架构、成绩录入、审核发布、导出 | 裁判长、开发 |
| 08 | 安全与可靠性 | 权限、审计、备份、容灾预案 | 运维、开发 |
| 09 | 测试策略 | 测试分层、积分引擎用例矩阵、彩排 | 开发、测试 |
| 10 | 部署与现场方案 | 绿色部署包、kiosk 模式、现场网络 | 现场运维 |
| 11 | 开发计划与里程碑 | M0–M8、关键路径、交付物 | 全部 |
| 12 | 风险登记册 | 风险、影响、概率、对策 | 全部 |
阅读顺序
01 需求 → 02 规则 → 03 架构 → 04 数据模型 → 05 接口 → 06/07 界面 → 08 可靠性 → 09 测试 → 10 部署 → 11 计划 → 12 风险
规则先行：02 篇是整个系统的心脏，规则定不下来，数据模型和积分引擎都不能动工。
文档维护约定
| 改动内容 | 要同步更新的文档 |
|---|---|
| 积分规则、排名规则 | 02（必须）→ 04（表结构）→ 09（用例） |
| 新增业务角色 | 01 → 08 |
| 新增接口 / 实时事件 | 05 → 04 |
| 大屏页面增减 | 06 → 05（事件载荷） |
| 现场环境变化 | 10 → 03（选型）→ 08（容灾） |
| 决策清单拍板 | README（勾掉 🔴）→ 对应模块 |
决策清单（🔴 待主人拍板）
「✅建议」是推荐默认值。主人可以只回复「按建议」，或逐条改。
D1 赛事规模与结构
| 项 | ✅建议默认 |
|---|---|
| 参赛单位数 | 7 个（初估，以实际报名为准） |
| 大项数 | 3 类：团队项目 / 个人项目 / 球类项目 |
| 小项数 | 26 个（8 团队 + 12 个人 + 6 球类） |
| 运动员数量级 | ≤300 人 |
| 是否多年办赛 | 是，需要保留历届数据（为纪录榜服务） |
🔴 请确认：实际参赛单位数量与项目结构？是否会有多个「组别」（如职工组/青年组/女子组）？
D2 积分规则
| 项 | ✅建议默认 |
|---|---|
| 名次积分表 | 前 8 名：9 / 7 / 6 / 5 / 4 / 3 / 2 / 1 |
| 并列名次 | 名次顺延：并列第 2 → 两人各得第 2 名分值，无第 3 名，下一名是第 4 名 |
| 团体/接力项目 | 双倍积分（multiplier = 2） |
| 球类项目 | 双倍积分 |
| 报名不足 8 人 | 按实际名次取分，空缺名次分值作废 |
| 弃权 / DNS / DSQ | 0 分，且不占名次（名次顺延） |
| 破纪录加分 | 赛会纪录 +2、市级 +5、省级 +8（取最高一条，不累加） |
| 扣分 / 处罚 | 支持人工调整，必须填理由，记入审计 |
🔴 请确认：积分表分值、是否双倍、破纪录加分档位与规则。详见 02-积分与排名规则。
D3 排名规则
| 项 | ✅建议默认 |
|---|---|
| 主榜 | 总积分榜（总分降序） |
| 同分 tie-break | 金牌数 → 银牌数 → 铜牌数 → 单位编码 |
| 是否要奖牌榜 | 要（金/银/铜计数） |
| 是否要个人积分榜 | 要（个人总分榜，用于大屏展示） |
| 并列奖牌计数 | 两人并列第 1 → 各记 1 金，无银牌（即名次顺延） |
D4 审核流程
| 方案 | 说明 |
|---|---|
| A（✅建议） | 两级：裁判录入草稿 → 裁判长确认发布 → 上屏。发布前可随意改，发布后修改需「撤销发布」 |
| B | 一级：录入即上屏。简单但风险高，录错一个数全场都看见 |
| C | 三级：录入 → 复核 → 发布 |
🔴 现场只有一位裁判长操作的话，选 A 还是 B？我强烈建议 A，理由：录入必然有笔误，A 的成本只是多一次点击。
D5 用户与权限
| 项 | ✅建议默认 |
|---|---|
| 账号数 | 3–5 个：1 个管理员 + 1–2 个裁判长 + 若干录入员 |
| 角色 | admin（全部）/ chief（录入+审核+发布+调整）/ recorder（仅录入草稿）/ viewer（只读） |
| 大屏端 | 不需要登录（只读），可选 display_key 防止外人误开 |
| 会话时长 | 12 小时（覆盖整个比赛日） |
🔴 确认角色划分是否够用。
D6 成绩来源
| 方案 | 说明 |
|---|---|
| A（✅建议） | 纯手工录入 + 支持从 Excel/CSV 批量粘贴导入 |
| B | 对接计时设备（需设备型号与协议，本期不承诺） |
| C | 线下 Excel 整理后整表导入 |
🔴 现场实际怎么产生成绩？如果是手写记录后录入，A 的「快速录入模式」是开发重点。
D7 大屏页面
| 页 | 内容 | ✅建议 |
|---|---|---|
| P1 | 总积分榜（全单位，含名次升降箭头） | 轮播页 |
| P2 | 奖牌榜 | 轮播页 |
| P3 | 纪录榜（历史最好成绩） | 轮播页 |
| P4 | 最新成绩 / 刚刚产生名次的项目 | 轮播页 |
| P5 | 单项成绩榜（当前正在进行的项目） | 轮播页 |
| P6 | 公告 / 图文 | 手动触发 |
| — | 是否自动轮播 | 是，每页 20s，可后台锁定某页 |
🔴 确认页面清单与轮播策略（自动 / 固定 / 手动）。详见 06-大屏端设计。
D8 现场部署环境
🔴 需要主人提供：
- 现场主机操作系统与架构（Windows / Linux；x86_64 / arm64）？
- 主机是笔记本、迷你主机还是服务器？有几台（是否有备机）？
- 大屏数量、尺寸、分辨率（设计分辨率待定，建议 3840×1920 或 1920×1080）？
- 现场网络：有没有外网？是否独立交换机？大屏机用什么连接（HDMI / 无线投屏）？
- 录入人员用什么设备（笔记本 / 平板）？平板是什么系统？
这组信息直接决定部署方案（见 10-部署与现场方案）。
D9 是否需要手机看榜
| 方案 | 说明 |
|---|---|
| A（✅建议） | 局域网内手机可看（大屏页自适应），不开公网 |
| B | 需要外网可访问（要额外考虑域名、HTTPS、安全加固） |
| C | 完全不需要 |
D10 技术栈
| 方案 | 说明 |
|---|---|
| A（✅建议） | Node.js 22 + TypeScript + Fastify + Socket.IO + SQLite + Vue 3 + Vite |
| B | Go 1.26 单二进制（chi + websocket + 纯 Go SQLite + embed 前端） |
详见 03-技术选型与架构。🔴 如果现场机器装不了 Node 运行时，就选 B。
D11 历史数据
🔴 是否需要导入历届纪录（往年纪录榜）作为纪录基准？数据现在是什么格式（Excel / 纸质 / 无）？
D12 导出与打印
| 项 | ✅建议默认 |
|---|---|
| 导出总积分榜 Excel | 要 |
| 导出各单位积分明细（哪个项目拿了几分） | 要 |
| 导出成绩册（全部小项成绩） | 要 |
| 现场打印 | 不做打印排版，导出 Excel 后自行打印 |
D13 大屏视觉方案
| 方案 | 说明 |
|---|---|
| A | 由主人/设计方提供新的视觉稿（PSD / Figma / 参考图），我按稿实现 |
| B（✅建议） | 先按「深色底 + 高对比数据表格」的通用赛事大屏风格做一版，用真实数据投屏后再微调 |
| C | 指定某套现成主题 |
🔴 确认视觉方向，以及是否有现成设计稿。目前无定稿视觉，因此 06-大屏端设计 中的视觉规范标注为「占位，待定」。
下一步
- 主人确认 D1–D13（可以只回「按建议」，或逐条改）。
- 我按确认结果把文档集从 v0.1 修到 v1.0，并把 02 篇的规则整理成可执行的《积分规则细则》。
- 定稿后进入 M1（数据库骨架），见 11-开发计划与里程碑。