13d9e2358a
- 添加完整的 API 接口文档 (docs/API.md) - 6 个主要接口的详细说明 - 请求/响应示例 - 错误码说明 - 多语言使用示例 - 添加开发指南 (docs/DEVELOPMENT.md) - 项目技术栈说明 - 目录结构详解 - 模块化开发教程 - 数据库设计说明 - 扩展建议
463 lines
8.2 KiB
Markdown
463 lines
8.2 KiB
Markdown
# 运动会管理系统 API 文档
|
||
|
||
## 概述
|
||
|
||
运动会记分板系统提供完整的 RESTful API 接口，支持比赛项目管理、队伍管理、成绩录入和积分统计等功能。
|
||
|
||
**Base URL**: `http://localhost:3000`
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "错误信息"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 接口列表
|
||
|
||
### 1. 配置接口
|
||
|
||
#### 获取系统配置
|
||
|
||
获取系统预置的配置信息，包括比赛类别、组别和项目类型。
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/config` |
|
||
| **方法** | `GET` |
|
||
| **认证** | 无 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET http://localhost:3000/api/config
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"categories": [
|
||
{ "value": "田赛", "label": "田赛" },
|
||
{ "value": "径赛", "label": "径赛" },
|
||
{ "value": "团体赛", "label": "团体赛" }
|
||
],
|
||
"groups": [
|
||
{ "value": "教师组", "label": "教师组" },
|
||
{ "value": "航空班组", "label": "航空班组" },
|
||
{ "value": "体育班组", "label": "体育班组" },
|
||
{ "value": "文化班甲组", "label": "文化班甲组" },
|
||
{ "value": "文化班乙组", "label": "文化班乙组" }
|
||
],
|
||
"eventTypes": {
|
||
"田赛": [
|
||
{ "name": "跳高", "unit": "米" },
|
||
{ "name": "跳远", "unit": "米" },
|
||
{ "name": "掷铅球", "unit": "米" }
|
||
],
|
||
"径赛": [
|
||
{ "name": "100m", "unit": "秒" },
|
||
{ "name": "200m", "unit": "秒" },
|
||
{ "name": "400m", "unit": "秒" },
|
||
{ "name": "4×100m", "unit": "秒" },
|
||
{ "name": "4×400m", "unit": "秒" },
|
||
{ "name": "20×50m", "unit": "秒" }
|
||
],
|
||
"团体赛": [
|
||
{ "name": "旱地龙舟", "unit": "秒" },
|
||
{ "name": "跳长绳", "unit": "次" },
|
||
{ "name": "折返跑", "unit": "秒" }
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 比赛项目接口
|
||
|
||
#### 获取比赛项目列表
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/events` |
|
||
| **方法** | `GET` |
|
||
| **认证** | 无 |
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `category` | string | 否 | 比赛类别（田赛/径赛/团体赛） |
|
||
| `group` | string | 否 | 组别 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
# 获取所有项目
|
||
curl -X GET http://localhost:3000/api/events
|
||
|
||
# 按类别筛选
|
||
curl -X GET "http://localhost:3000/api/events?category=田赛"
|
||
|
||
# 按组别筛选
|
||
curl -X GET "http://localhost:3000/api/events?group=文化班甲组"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "跳高",
|
||
"category": "田赛",
|
||
"event_group": "文化班甲组",
|
||
"unit": "米",
|
||
"status": "pending",
|
||
"created_at": "2026-03-17T10:00:00.000Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 创建比赛项目
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/events` |
|
||
| **方法** | `POST` |
|
||
| **认证** | 无 |
|
||
|
||
**请求体**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | 是 | 项目名称 |
|
||
| `category` | string | 是 | 比赛类别 |
|
||
| `event_group` | string | 是 | 组别 |
|
||
| `unit` | string | 是 | 单位（米/秒/次） |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/events \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "跳高",
|
||
"category": "田赛",
|
||
"event_group": "文化班甲组",
|
||
"unit": "米"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 队伍管理接口
|
||
|
||
#### 获取队伍列表
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/teams` |
|
||
| **方法** | `GET` |
|
||
| **认证** | 无 |
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `group` | string | 否 | 组别 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:3000/api/teams?group=文化班甲组"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "高一1班",
|
||
"team_group": "文化班甲组",
|
||
"created_at": "2026-03-17T10:00:00.000Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 创建队伍
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/teams` |
|
||
| **方法** | `POST` |
|
||
| **认证** | 无 |
|
||
|
||
**请求体**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `name` | string | 是 | 队伍名称 |
|
||
| `team_group` | string | 是 | 组别 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/teams \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"name": "高一1班",
|
||
"team_group": "文化班甲组"
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 成绩管理接口
|
||
|
||
#### 获取成绩列表
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/results` |
|
||
| **方法** | `GET` |
|
||
| **认证** | 无 |
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `event_id` | number | 否 | 比赛项目ID |
|
||
| `team_id` | number | 否 | 队伍ID |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
# 获取所有成绩
|
||
curl -X GET http://localhost:3000/api/results
|
||
|
||
# 按项目筛选
|
||
curl -X GET "http://localhost:3000/api/results?event_id=1"
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"event_id": 1,
|
||
"team_id": 1,
|
||
"score": "2.10",
|
||
"rank": 1,
|
||
"event_name": "跳高",
|
||
"category": "田赛",
|
||
"unit": "米",
|
||
"team_name": "高一1班",
|
||
"team_group": "文化班甲组",
|
||
"created_at": "2026-03-17T10:00:00.000Z"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 录入成绩
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/results` |
|
||
| **方法** | `POST` |
|
||
| **认证** | 无 |
|
||
|
||
**请求体**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `event_id` | number | 是 | 比赛项目ID |
|
||
| `team_id` | number | 是 | 队伍ID |
|
||
| `score` | string | 是 | 成绩 |
|
||
| `rank` | number | 否 | 名次（1-3自动计分） |
|
||
|
||
**积分规则**
|
||
|
||
| 名次 | 积分 | 奖牌 |
|
||
|------|------|------|
|
||
| 第1名 | 7分 | 金牌 |
|
||
| 第2名 | 5分 | 银牌 |
|
||
| 第3名 | 3分 | 铜牌 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/results \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"event_id": 1,
|
||
"team_id": 1,
|
||
"score": "2.10",
|
||
"rank": 1
|
||
}'
|
||
```
|
||
|
||
---
|
||
|
||
### 5. 记分板接口
|
||
|
||
#### 获取记分板数据
|
||
|
||
获取所有队伍的总分、金牌、银牌、铜牌统计。
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/scoreboard` |
|
||
| **方法** | `GET` |
|
||
| **认证** | 无 |
|
||
|
||
**查询参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `group` | string | 否 | 组别筛选 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X GET http://localhost:3000/api/scoreboard
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"name": "高一1班",
|
||
"team_group": "文化班甲组",
|
||
"total_score": 25,
|
||
"gold_count": 3,
|
||
"silver_count": 1,
|
||
"bronze_count": 2
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 数据初始化接口
|
||
|
||
#### 初始化示例数据
|
||
|
||
创建示例队伍和比赛项目数据（仅在首次使用时调用）。
|
||
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **URL** | `/api/seed` |
|
||
| **方法** | `POST` |
|
||
| **认证** | 无 |
|
||
|
||
**请求示例**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3000/api/seed
|
||
```
|
||
|
||
**响应示例**
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "初始化数据成功",
|
||
"data": {
|
||
"teams": 9,
|
||
"events": 9
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 400 | 请求参数错误 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### JavaScript/TypeScript
|
||
|
||
```typescript
|
||
// 使用 fetch
|
||
const events = await fetch('/api/events').then(r => r.json())
|
||
|
||
// 使用 $fetch (Nuxt)
|
||
const { data } = await useFetch('/api/events')
|
||
```
|
||
|
||
### Python
|
||
|
||
```python
|
||
import requests
|
||
|
||
# 获取比赛项目
|
||
response = requests.get('http://localhost:3000/api/events')
|
||
events = response.json()
|
||
|
||
# 录入成绩
|
||
requests.post('http://localhost:3000/api/results', json={
|
||
'event_id': 1,
|
||
'team_id': 1,
|
||
'score': '10.5',
|
||
'rank': 1
|
||
})
|
||
```
|
||
|
||
### cURL
|
||
|
||
```bash
|
||
# 获取记分板
|
||
curl http://localhost:3000/api/scoreboard
|
||
|
||
# 创建队伍
|
||
curl -X POST http://localhost:3000/api/teams \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name": "测试队伍", "team_group": "教师组"}'
|
||
```
|