181 lines
6.0 KiB
Markdown
181 lines
6.0 KiB
Markdown
# 05 · 接口与实时协议
|
||
|
||
> 所属：运动会积分榜系统 · 开发文档集
|
||
> 版本：v0.1（讨论稿） · 2026-09-09
|
||
> 上游：[README](./README.md) · 相关：[04-数据模型](./04-数据模型.md)、[06-大屏端设计](./06-大屏端设计.md)
|
||
|
||
---
|
||
|
||
# 第一部分 · 实时同步协议
|
||
|
||
## 1. 通道
|
||
|
||
- **Socket.IO**，路径 `/socket.io`，与 HTTP 同端口。
|
||
- 房间：`display`（所有大屏）、`admin`（所有管理端）、`admin:<userId>`（定向通知，如「你的草稿已被发布」）。
|
||
- 传输：优先 WebSocket，失败自动降级 polling（Socket.IO 内建）。
|
||
|
||
## 2. 版本号 + 快照/增量（保证断线不错乱）
|
||
|
||
```
|
||
服务端维护单调递增 version（等于 change_log.id 最大值）
|
||
|
||
客户端连接
|
||
└─ emit "hello" { role, lastVersion }
|
||
├─ lastVersion 为空 或 太旧（增量超阈值）→ "snapshot" { version, data }
|
||
└─ 可增量 → "catchup" { fromVersion, changes:[...], version }
|
||
服务端有变更
|
||
└─ emit "change" { version, changes:[...] }
|
||
客户端应用后
|
||
└─ emit "ack" { version } // 服务端据此识别慢客户端
|
||
服务端每 10s
|
||
└─ emit "heartbeat" { version, serverTime }
|
||
客户端发现 version 落后 → emit "resync"
|
||
```
|
||
|
||
## 3. 事件清单
|
||
|
||
| 事件 | 方向 | 载荷 |
|
||
| --- | --- | --- |
|
||
| `hello` | C→S | `{ role, lastVersion?, displayKey? }` |
|
||
| `snapshot` | S→C | `{ version, settings, teams, events, standings, records, latestResults }` |
|
||
| `catchup` | S→C | `{ fromVersion, version, changes[] }` |
|
||
| `change` | S→C | `{ version, changes[] }` |
|
||
| `resync` | C→S | `{}` |
|
||
| `ack` | C→S | `{ version }` |
|
||
| `heartbeat` | S→C | `{ version, serverTime }` |
|
||
| `display:command` | S→C | `{ action: 'goto'\|'lock'\|'unlock'\|'reload'\|'announce', payload }` |
|
||
|
||
`changes[]` 元素形如：
|
||
|
||
```jsonc
|
||
{ "entity": "result", "id": 42, "action": "upsert", "data": { } }
|
||
```
|
||
|
||
`action` 取值：`upsert` / `void` / `replace`（`replace` 用于整体替换的列表，如积分榜）。
|
||
|
||
## 4. 断线与降级
|
||
|
||
| 场景 | 行为 |
|
||
| --- | --- |
|
||
| 大屏断网 | 继续显示 localStorage 最后一次快照，右上角显示「⚠ 连接中断 · 数据可能不是最新」 |
|
||
| 大屏重连 | 按 `lastVersion` 增量补发；补不上就整包快照 |
|
||
| 管理端断网 | 顶部横幅提示，禁止提交写操作（避免双写） |
|
||
| 服务端重启 | 客户端自动重连，版本号从数据库恢复（不重置） |
|
||
| 多管理端同时改同一项目 | 服务端事务串行化；后提交者收到冲突提示，前端刷新最新数据 |
|
||
|
||
## 5. 幂等与顺序
|
||
|
||
- 客户端按 `version` 去重：重复或乱序的变更直接丢弃。
|
||
- 服务端写操作带 `requestId`，重复提交返回首次结果。
|
||
|
||
---
|
||
|
||
# 第二部分 · REST API
|
||
|
||
## 6. 约定
|
||
|
||
- 前缀 `/api`，JSON，UTF-8。
|
||
- 认证：`HttpOnly` Cookie 会话 + CSRF Token（管理端）；大屏端免认证只读。
|
||
- 统一响应：`{ ok: true, data }` / `{ ok: false, error: { code, message, detail? } }`。
|
||
- 分页：`?page=&size=`，返回 `{ items, total, page, size }`。
|
||
|
||
## 7. 接口清单（初稿）
|
||
|
||
### 认证
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| POST | `/api/auth/login` | 登录 |
|
||
| POST | `/api/auth/logout` | 登出 |
|
||
| GET | `/api/auth/me` | 当前用户 |
|
||
|
||
### 基础配置
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET/PUT | `/api/settings` | 赛事配置 |
|
||
| GET/POST/PUT/DELETE | `/api/teams[/:id]` | 单位 CRUD |
|
||
| GET/POST/PUT/DELETE | `/api/sports[/:id]` | 大项 CRUD |
|
||
| GET/POST/PUT/DELETE | `/api/events[/:id]` | 小项 CRUD |
|
||
| GET/POST/PUT | `/api/scoring-profiles[/:id]` | 积分模板 |
|
||
| GET/POST/PUT | `/api/athletes[/:id]` | 运动员 |
|
||
| POST | `/api/entries/import` | 导入报名表 |
|
||
|
||
### 成绩（核心）
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/events/:id/entries` | 该项目全部报名项 + 现有成绩 |
|
||
| PUT | `/api/results/draft` | 批量保存草稿（一次一个项目的整组） |
|
||
| POST | `/api/results/publish` | 发布（触发积分重算与推送） |
|
||
| POST | `/api/results/unpublish` | 撤销发布 |
|
||
| POST | `/api/results/:id/void` | 作废单条成绩 |
|
||
| GET | `/api/results?eventId=&state=` | 查询 |
|
||
|
||
### 积分与排名
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/standings` | 总积分榜（含奖牌数） |
|
||
| GET | `/api/standings/teams/:id/breakdown` | 某单位积分明细（可解释每一分） |
|
||
| GET | `/api/standings/athletes` | 个人积分榜 |
|
||
| GET/POST | `/api/adjustments[/:id/void]` | 人工加减分 |
|
||
|
||
### 纪录
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| GET | `/api/records` | 纪录榜 |
|
||
| POST | `/api/record-breaks` | 登记破纪录 |
|
||
| POST | `/api/record-breaks/:id/approve` | 确认加分 |
|
||
|
||
### 大屏控制与导出
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
| --- | --- | --- |
|
||
| POST | `/api/display/command` | 切页 / 锁定 / 刷新 / 公告 |
|
||
| GET | `/api/export/standings.xlsx` | 导出总积分榜 |
|
||
| GET | `/api/export/breakdown.xlsx` | 导出单位积分明细 |
|
||
| GET | `/api/export/results.xlsx` | 导出成绩册 |
|
||
| GET | `/api/audit-logs` | 审计日志 |
|
||
| POST | `/api/backup` | 立即备份 |
|
||
| GET | `/api/health` | 健康检查（供运维/守护脚本） |
|
||
|
||
## 8. 错误码
|
||
|
||
| code | 含义 |
|
||
| --- | --- |
|
||
| `AUTH_REQUIRED` / `AUTH_FAILED` / `FORBIDDEN` | 认证与权限 |
|
||
| `VALIDATION_FAILED` | 入参不合法（附字段级 detail） |
|
||
| `CONFLICT` | 并发修改冲突 |
|
||
| `STATE_INVALID` | 状态不允许该操作（如未发布就想撤销发布） |
|
||
| `RATE_LIMITED` | 触发限流 |
|
||
| `INTERNAL` | 服务端异常 |
|
||
|
||
---
|
||
|
||
# 附录 · 实时事件样例
|
||
|
||
```jsonc
|
||
// 服务端 → 大屏
|
||
{
|
||
"event": "change",
|
||
"data": {
|
||
"version": 128,
|
||
"changes": [
|
||
{
|
||
"entity": "result",
|
||
"id": 512,
|
||
"action": "upsert",
|
||
"data": { "eventId": 7, "entryId": 88, "rank": 1, "resultText": "11.58", "state": "published" }
|
||
},
|
||
{
|
||
"entity": "standings",
|
||
"action": "replace",
|
||
"data": [ { "teamId": 1, "totalPoints": 186, "gold": 5, "rank": 1 } ]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|