# 运动会记分板系统 - 开发指南

## 项目简介

这是一个基于 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