# 01 · 需求与范围

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

---

## 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-安全与可靠性](./08-安全与可靠性.md)。

---

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

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

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

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

---

## 4. 核心业务流程

### 4.1 成绩录入 → 上屏

```mermaid
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-积分与排名规则](./02-积分与排名规则.md)；流程对应的接口见 [05-接口与实时协议](./05-接口与实时协议.md)。