Scoreboard/devdocs/01-需求与范围.md

01 · 需求与范围

所属：运动会积分榜系统 · 开发文档集 版本：v0.1（讨论稿） · 2026-09-09 上游：README · 相关：02-积分与排名规则

---

1. 项目定义

一套局域网内部署的运动会成绩与积分系统：一个服务端进程，同时对外提供实时积分大屏（只读、无人值守）和裁判长管理面板（登录、录入、审核、发布）两个前端界面；后台一改数据，前台大屏在 1 秒内完成更新。

1.1 目标

编号	目标	验收标准
G1	成绩录入到上屏的延迟可感知地「即时」	发布后 ≤1s 大屏刷新完成
G2	积分计算零差错	积分引擎单元测试覆盖全部规则分支，用例数 ≥60
G3	误操作可追溯、可撤销	每次写操作留审计日志；成绩/调整可撤销且可回滚
G4	现场不宕机、断电不丢数据	进程崩溃自动拉起；数据库每 5 分钟自动备份 + 发布前备份
G5	大屏无人值守可连续运行	断网自恢复、分辨率自适应、7×24 无内存泄漏

1.2 非目标（明确不做，避免范围蔓延）

• ❌ 公网多租户 SaaS、多赛事并行管理（本期是单赛事）。
• ❌ 在线报名系统（报名表由主办方线下收集，系统支持导入）。
• ❌ 计时/测距设备硬件对接（除非 D6 确认需要，否则只留 CSV/Excel 导入接口）。
• ❌ 移动 App（手机浏览器访问是附赠能力，不是交付项）。
• ❌ 复杂的多级审批流（本期最多两级：录入 → 裁判长发布）。

1.3 名词表

术语	含义
单位 / 代表团	参赛主体，积分榜上的行，如「第一分公司」
大项	项目的分类，如「田径」「球类」「趣味项目」
小项	具体比赛项目，如「男子100米」「拔河」，积分计算的最小单位
报名项 / entry	「某单位派某人/某队参加某小项」这一条记录
成绩 / result	某个报名项在比赛中取得的名次与成绩值
积分流水 / ledger	单位得分的原子记录，总分由流水求和得出，唯一的积分真相来源
发布	把草稿态成绩正式生效并推送上屏的动作
纪录	历史最好成绩，可被本次赛会打破并获得加分
版本号 / version	服务端单调递增的变更序号，实时同步与断线补发的依据

---

2. 角色与职责

角色	使用界面	能做什么
大屏观众	大屏端	只能看
录入员 recorder	管理端	录入成绩草稿、查看自己录入的内容
裁判长 chief	管理端	录入、修改、审核、发布、撤销、登记破纪录、加减分、控制大屏
管理员 admin	管理端	全部权限 + 用户管理 + 赛事配置 + 备份恢复

权限的落地方式（会话、路由级/服务级双重校验）见 08-安全与可靠性。

---

3. 赛事时间线（系统的使用节奏）

赛前（T-7 ~ T-1）
  建赛事 → 导入单位 → 建大项/小项 → 配置积分模板 → 导入报名表
  → 录入/导入历届纪录 → 联调彩排

赛中（比赛日）
  项目开始 → 裁判录入成绩（草稿）→ 裁判长核对 → 发布 → 大屏实时更新
  → 破纪录登记 → 公告发布

赛后（T+1）
  导出成绩册/积分表 → 归档 → 备份留档

---

4. 核心业务流程

4.1 成绩录入 → 上屏

flowchart LR
  A[裁判长选择小项] --> B[系统列出该项目全部报名项]
  B --> C[录入名次/成绩/状态]
  C --> D[系统实时校验并预览积分变化]
  D --> E{提交}
  E -->|存草稿| F[草稿态·不上屏]
  E -->|发布| G[写入积分流水]
  G --> H[重算总积分榜]
  H --> I[生成变更事件 version++]
  I --> J[WebSocket 推送]
  J --> K[大屏应用增量·播放动效]
  F --> L[稍后审核发布]

4.2 关键约束

1. 草稿绝不上屏：服务端只向大屏推送 state='published' 的数据。
2. 发布是批量事务：一个项目的整组成绩一次发布，不允许出现「发布了 3 人、还剩 5 人」的中间态。
3. 发布后修改要走撤销：作废旧积分流水 → 重新发布，全程留审计。
4. 积分只追加不修改：总分永远是 SUM(未作废流水)，任何数字都能回答「这分怎么来的」。

规则的完整定义见 02-积分与排名规则；流程对应的接口见 05-接口与实时协议。