# 运动会管理系统 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": "教师组"}' ```