SportMeetingAdminSys/docs/API.md

运动会管理系统 API 文档

概述

运动会记分板系统提供完整的 RESTful API 接口，支持比赛项目管理、队伍管理、成绩录入和积分统计等功能。

Base URL: http://localhost:3000

---

通用响应格式

成功响应

{
  "success": true,
  "data": { ... }
}

错误响应

{
  "success": false,
  "message": "错误信息"
}

---

接口列表

1. 配置接口

获取系统配置

获取系统预置的配置信息，包括比赛类别、组别和项目类型。

项目	说明
URL	/api/config
方法	GET
认证	无

请求示例

curl -X GET http://localhost:3000/api/config

响应示例

{
  "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	否	组别

请求示例

# 获取所有项目
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=文化班甲组"

响应示例

{
  "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	是	单位（米/秒/次）

请求示例

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	否	组别

请求示例

curl -X GET "http://localhost:3000/api/teams?group=文化班甲组"

响应示例

{
  "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	是	组别

请求示例

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

请求示例

# 获取所有成绩
curl -X GET http://localhost:3000/api/results

# 按项目筛选
curl -X GET "http://localhost:3000/api/results?event_id=1"

响应示例

{
  "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分	铜牌

请求示例

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	否	组别筛选

请求示例

curl -X GET http://localhost:3000/api/scoreboard

响应示例

{
  "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
认证	无

请求示例

curl -X POST http://localhost:3000/api/seed

响应示例

{
  "success": true,
  "message": "初始化数据成功",
  "data": {
    "teams": 9,
    "events": 9
  }
}

---

错误码说明

错误码	说明
400	请求参数错误
404	资源不存在
500	服务器内部错误

---

使用示例

JavaScript/TypeScript

// 使用 fetch
const events = await fetch('/api/events').then(r => r.json())

// 使用 $fetch (Nuxt)
const { data } = await useFetch('/api/events')

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

# 获取记分板
curl http://localhost:3000/api/scoreboard

# 创建队伍
curl -X POST http://localhost:3000/api/teams \
  -H "Content-Type: application/json" \
  -d '{"name": "测试队伍", "team_group": "教师组"}'