13d9e2358a
- 添加完整的 API 接口文档 (docs/API.md) - 6 个主要接口的详细说明 - 请求/响应示例 - 错误码说明 - 多语言使用示例 - 添加开发指南 (docs/DEVELOPMENT.md) - 项目技术栈说明 - 目录结构详解 - 模块化开发教程 - 数据库设计说明 - 扩展建议
279 lines
6.0 KiB
Markdown
279 lines
6.0 KiB
Markdown
# 运动会记分板系统 - 开发指南
|
|
|
|
## 项目简介
|
|
|
|
这是一个基于 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
|