199 lines
9.1 KiB
Markdown
199 lines
9.1 KiB
Markdown
# 运动会积分榜系统 · 开发文档集
|
||
|
||
| 项 | 内容 |
|
||
| --- | --- |
|
||
| 项目 | 一拖二运动会积分榜：一个服务端 + 实时积分大屏 + 裁判长管理面板 |
|
||
| 仓库 | `ssh://git@git.yeij.top:2222/AskaEth/Scoreboard.git` |
|
||
| 作者 | AskaEth |
|
||
| 文档版本 | v0.1（讨论稿） · 2026-09-09 |
|
||
| 状态 | **待确认**：第 D1–D13 项未拍板前，不进入编码 |
|
||
|
||
> 本目录取代了早期的单文件《开发规划.md》。内容按模块拆开，改哪块就动哪份，避免一份文档越滚越长。
|
||
|
||
---
|
||
|
||
## 文档地图
|
||
|
||
| 编号 | 文档 | 内容 | 主要读者 |
|
||
| --- | --- | --- | --- |
|
||
| — | [README](./README.md) | 索引、决策清单、阅读顺序 | 全部 |
|
||
| 01 | [需求与范围](./01-需求与范围.md) | 目标/非目标、名词表、角色、赛事时间线、核心流程 | 主办方、产品 |
|
||
| 02 | [积分与排名规则](./02-积分与排名规则.md) | 积分表、并列、双倍、破纪录、tie-break | **裁判长**、开发 |
|
||
| 03 | [技术选型与架构](./03-技术选型与架构.md) | 选型对比、模块划分、数据流、目录结构、编码规范 | 开发 |
|
||
| 04 | [数据模型](./04-数据模型.md) | 表结构、约束、索引、积分流水原则 | 开发 |
|
||
| 05 | [接口与实时协议](./05-接口与实时协议.md) | REST API、Socket.IO 事件、断线重连 | 开发 |
|
||
| 06 | [大屏端设计](./06-大屏端设计.md) | 页面、轮播、动效、分辨率、无人值守 | 设计、开发 |
|
||
| 07 | [管理面板设计](./07-管理面板设计.md) | 信息架构、成绩录入、审核发布、导出 | 裁判长、开发 |
|
||
| 08 | [安全与可靠性](./08-安全与可靠性.md) | 权限、审计、备份、容灾预案 | 运维、开发 |
|
||
| 09 | [测试策略](./09-测试策略.md) | 测试分层、积分引擎用例矩阵、彩排 | 开发、测试 |
|
||
| 10 | [部署与现场方案](./10-部署与现场方案.md) | 绿色部署包、kiosk 模式、现场网络 | 现场运维 |
|
||
| 11 | [开发计划与里程碑](./11-开发计划与里程碑.md) | M0–M8、关键路径、交付物 | 全部 |
|
||
| 12 | [风险登记册](./12-风险登记册.md) | 风险、影响、概率、对策 | 全部 |
|
||
|
||
## 阅读顺序
|
||
|
||
```
|
||
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-积分与排名规则](./02-积分与排名规则.md)。
|
||
|
||
### 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-大屏端设计](./06-大屏端设计.md)。
|
||
|
||
### D8 现场部署环境
|
||
|
||
🔴 需要主人提供：
|
||
|
||
1. 现场主机**操作系统与架构**（Windows / Linux；x86_64 / arm64）？
|
||
2. 主机是笔记本、迷你主机还是服务器？有几台（是否有备机）？
|
||
3. 大屏**数量、尺寸、分辨率**（设计分辨率待定，建议 3840×1920 或 1920×1080）？
|
||
4. 现场网络：有没有外网？是否独立交换机？大屏机用什么连接（HDMI / 无线投屏）？
|
||
5. 录入人员用什么设备（笔记本 / 平板）？平板是什么系统？
|
||
|
||
这组信息直接决定部署方案（见 [10-部署与现场方案](./10-部署与现场方案.md)）。
|
||
|
||
### 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-技术选型与架构](./03-技术选型与架构.md)。🔴 如果现场机器装不了 Node 运行时，就选 B。
|
||
|
||
### D11 历史数据
|
||
|
||
🔴 是否需要导入**历届纪录**（往年纪录榜）作为纪录基准？数据现在是什么格式（Excel / 纸质 / 无）？
|
||
|
||
### D12 导出与打印
|
||
|
||
| 项 | ✅建议默认 |
|
||
| --- | --- |
|
||
| 导出总积分榜 Excel | 要 |
|
||
| 导出各单位积分明细（哪个项目拿了几分） | 要 |
|
||
| 导出成绩册（全部小项成绩） | 要 |
|
||
| 现场打印 | 不做打印排版，导出 Excel 后自行打印 |
|
||
|
||
### D13 大屏视觉方案
|
||
|
||
| 方案 | 说明 |
|
||
| --- | --- |
|
||
| A | 由主人/设计方提供新的视觉稿（PSD / Figma / 参考图），我按稿实现 |
|
||
| B（✅建议） | 先按「深色底 + 高对比数据表格」的通用赛事大屏风格做一版，用真实数据投屏后再微调 |
|
||
| C | 指定某套现成主题 |
|
||
|
||
🔴 确认视觉方向，以及是否有现成设计稿。**目前无定稿视觉**，因此 [06-大屏端设计](./06-大屏端设计.md) 中的视觉规范标注为「占位，待定」。
|
||
|
||
---
|
||
|
||
## 下一步
|
||
|
||
1. 主人确认 **D1–D13**（可以只回「按建议」，或逐条改）。
|
||
2. 我按确认结果把文档集从 v0.1 修到 v1.0，并把 02 篇的规则整理成可执行的《积分规则细则》。
|
||
3. 定稿后进入 M1（数据库骨架），见 [11-开发计划与里程碑](./11-开发计划与里程碑.md)。
|