SportMeetingAdminSys/docs/DEVELOPMENT.md

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

项目简介

这是一个基于 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/       # 模块专用组件

模块示例

// 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'
}

// 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
}

// 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	铜牌数

开发指南

开发环境

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

构建生产版本

pnpm build

预览生产版本

node .output/server/index.mjs

添加新功能

1. 添加新页面

在 app/pages/ 下创建 .vue 文件：

<template>
  <div>
    <h1>新页面</h1>
  </div>
</template>

<script setup lang="ts">
// 页面逻辑
</script>

2. 添加新 API

在 server/api/ 下创建接口文件：

// server/api/hello.get.ts
export default defineEventHandler((event) => {
  return { message: 'Hello World' }
})

3. 添加数据库表

在 server/db/index.ts 中添加表定义：

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 目录后重新构建：

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