Scoreboard/devdocs/README.md

运动会积分榜系统 · 开发文档集

项	内容
项目	一拖二运动会积分榜：一个服务端 + 实时积分大屏 + 裁判长管理面板
仓库	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 现场部署环境

🔴 需要主人提供：

1. 现场主机操作系统与架构（Windows / Linux；x86_64 / arm64）？
2. 主机是笔记本、迷你主机还是服务器？有几台（是否有备机）？
3. 大屏数量、尺寸、分辨率（设计分辨率待定，建议 3840×1920 或 1920×1080）？
4. 现场网络：有没有外网？是否独立交换机？大屏机用什么连接（HDMI / 无线投屏）？
5. 录入人员用什么设备（笔记本 / 平板）？平板是什么系统？

这组信息直接决定部署方案（见 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-大屏端设计 中的视觉规范标注为「占位，待定」。

---

下一步

1. 主人确认 D1–D13（可以只回「按建议」，或逐条改）。
2. 我按确认结果把文档集从 v0.1 修到 v1.0，并把 02 篇的规则整理成可执行的《积分规则细则》。
3. 定稿后进入 M1（数据库骨架），见 11-开发计划与里程碑。