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

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