docs: 添加 API 文档和开发指南

- 添加完整的 API 接口文档 (docs/API.md)
  - 6 个主要接口的详细说明
  - 请求/响应示例
  - 错误码说明
  - 多语言使用示例

- 添加开发指南 (docs/DEVELOPMENT.md)
  - 项目技术栈说明
  - 目录结构详解
  - 模块化开发教程
  - 数据库设计说明
  - 扩展建议
This commit is contained in:
Administrator 2026-03-18 12:41:15 +08:00
parent 94dbd0d34c
commit 13d9e2358a
2 changed files with 740 additions and 0 deletions

462
docs/API.md Normal file
View File

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

278
docs/DEVELOPMENT.md Normal file
View File

@ -0,0 +1,278 @@
# 运动会记分板系统 - 开发指南
## 项目简介
这是一个基于 Nuxt 3 + Element Plus + SQLite 的运动会管理系统,采用模块化架构设计,便于扩展和维护。
## 技术栈
| 技术 | 说明 |
|------|------|
| Nuxt 3 | Vue 3 全栈框架 |
| Element Plus | UI 组件库 |
| SQLite | 轻量级数据库 |
| better-sqlite3 | Node.js SQLite 驱动 |
| pnpm | 包管理器 |
## 目录结构
```
SportMeetingAdminSys/
├── app/ # 前端应用
│ ├── layouts/ # 布局组件
│ │ └── default.vue # 默认侧边栏布局
│ ├── modules/ # 功能模块
│ │ └── scoreboard/ # 计分板模块
│ │ ├── index.ts # 模块配置
│ │ ├── api.ts # API 函数
│ │ ├── mod.ts # 模块导出
│ │ └── *.vue # 可复用组件
│ └── pages/ # 页面路由
│ ├── index.vue # 首页
│ ├── events.vue # 比赛项目管理
│ ├── teams.vue # 队伍管理
│ ├── results.vue # 成绩录入
│ └── scoreboard.vue # 记分板
├── server/ # 后端 API
│ ├── api/ # API 路由
│ │ ├── config/ # 配置接口
│ │ ├── events/ # 比赛项目
│ │ ├── teams/ # 队伍管理
│ │ ├── results/ # 成绩管理
│ │ └── scoreboard/ # 记分板
│ └── db/ # 数据库
│ └── index.ts # SQLite 连接
├── data/ # 数据目录
│ └── sports.db # SQLite 数据库
└── docs/ # 文档
└── API.md # API 文档
```
## 模块化开发
### 创建新模块
`app/modules/` 目录下创建新模块:
```
app/modules/新模块名/
├── index.ts # 模块配置和常量
├── api.ts # API 函数封装
├── mod.ts # 统一导出
├── README.md # 模块文档
└── components/ # 模块专用组件
```
### 模块示例
```typescript
// app/modules/my-module/index.ts
export const myModule = {
name: 'my-module',
version: '1.0.0'
}
export const API_ENDPOINTS = {
LIST: '/api/my-resource',
CREATE: '/api/my-resource',
UPDATE: '/api/my-resource/:id',
DELETE: '/api/my-resource/:id'
}
```
```typescript
// app/modules/my-module/api.ts
export const fetchMyResource = async (params?: any) => {
const res = await $fetch(API_ENDPOINTS.LIST, { params })
return res.data
}
export const createMyResource = async (data: any) => {
const res = await $fetch(API_ENDPOINTS.CREATE, {
method: 'POST',
body: data
})
return res.data
}
```
```typescript
// app/modules/my-module/mod.ts
export * from './index'
export * from './api'
```
## 数据库设计
### 表结构
#### events - 比赛项目
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| name | TEXT | 项目名称 |
| category | TEXT | 类别(田赛/径赛/团体赛) |
| event_group | TEXT | 组别 |
| unit | TEXT | 单位(米/秒/次) |
| status | TEXT | 状态 |
| created_at | DATETIME | 创建时间 |
#### teams - 队伍
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| name | TEXT | 队伍名称 |
| team_group | TEXT | 组别 |
| created_at | DATETIME | 创建时间 |
#### results - 成绩
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| event_id | INTEGER | 外键,关联 events |
| team_id | INTEGER | 外键,关联 teams |
| score | TEXT | 成绩 |
| rank | INTEGER | 名次 |
| created_at | DATETIME | 创建时间 |
#### team_scores - 团队积分
| 字段 | 类型 | 说明 |
|------|------|------|
| id | INTEGER | 主键 |
| team_id | INTEGER | 外键,关联 teams |
| total_score | INTEGER | 总分 |
| gold_count | INTEGER | 金牌数 |
| silver_count | INTEGER | 银牌数 |
| bronze_count | INTEGER | 铜牌数 |
## 开发指南
### 开发环境
```bash
# 安装依赖
pnpm install
# 启动开发服务器
pnpm dev
```
### 构建生产版本
```bash
pnpm build
```
### 预览生产版本
```bash
node .output/server/index.mjs
```
## 添加新功能
### 1. 添加新页面
`app/pages/` 下创建 `.vue` 文件:
```vue
<template>
<div>
<h1>新页面</h1>
</div>
</template>
<script setup lang="ts">
// 页面逻辑
</script>
```
### 2. 添加新 API
`server/api/` 下创建接口文件:
```typescript
// server/api/hello.get.ts
export default defineEventHandler((event) => {
return { message: 'Hello World' }
})
```
### 3. 添加数据库表
`server/db/index.ts` 中添加表定义:
```typescript
db.exec(`
CREATE TABLE IF NOT EXISTS new_table (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL
)
`)
```
## 扩展建议
### 可扩展模块
1. **报名模块** (`modules/registration`)
- 运动员报名
- 资格审核
- 报名统计
2. **赛程模块** (`modules/schedule`)
- 赛程安排
- 时间管理
- 场地分配
3. **数据分析模块** (`modules/analysis`)
- 成绩分析
- 数据可视化
- 报表导出
4. **通知模块** (`modules/notification`)
- 比赛通知
- 成绩推送
- 实时更新
### UI 扩展
- 添加图表展示 (ECharts)
- 添加打印功能
- 添加数据导出 (Excel/PDF)
- 添加实时刷新
## 常见问题
### 数据库锁定
如果遇到数据库锁定错误,检查是否有其他进程正在访问数据库。
### 模块导入失败
确保在 `nuxt.config.ts` 中正确配置了模块路径别名。
### 构建失败
清理 `.nuxt``.output` 目录后重新构建:
```bash
rm -rf .nuxt .output
pnpm build
```
## 贡献指南
1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/新功能`)
3. 提交更改 (`git commit -m '添加新功能'`)
4. 推送分支 (`git push origin feature/新功能`)
5. 创建 Pull Request
## License
MIT