# 跑步成绩管理系统

**Repository Path**: hzq/marathon

## Basic Information

- **Project Name**: 跑步成绩管理系统
- **Description**: 121231231312
- **Primary Language**: TypeScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-29
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 马拉松成绩管理系统

一个完整的马拉松成绩管理系统，支持成绩录入、编辑、浏览、排行榜和统计功能。

## 技术栈

- **前端**: React + TypeScript + Tailwind CSS + shadcn/ui
- **后端**: Go + Gin + GORM + MySQL
- **部署**: Docker + Docker Compose

## 功能特性

### 核心功能
- ✅ 员工管理（CRUD）
- ✅ 部门管理
- ✅ 成绩录入、编辑、删除
- ✅ 成绩审核流程
- ✅ 多维度排行榜
- ✅ 个人/部门/全局统计
- ✅ 数据可视化图表
- ✅ 通知系统
- ✅ 移动端适配

### 排行榜类型
- 全公司总榜
- 部门排行榜
- 年度排行榜
- 距离分类榜（全程/半程/10km/5km）

### 统计报表
- 仪表盘统计
- 个人数据统计
- 部门数据统计
- 趋势分析图表

## 快速开始

### 方式一：使用 Docker Compose（推荐）

```bash
# 1. 克隆项目
git clone <repository-url>
cd marathon-system

# 2. 启动所有服务
docker-compose up -d

# 3. 访问系统
# 前端: http://localhost
# 后端API: http://localhost:8080
# MySQL: localhost:3306
```

### 方式二：手动启动

#### 启动后端

```bash
cd backend

# 1. 安装Go依赖
go mod download

# 2. 配置数据库（编辑 config.yaml）
vim config.yaml

# 3. 创建数据库
mysql -u root -p < database/schema.sql

# 4. 运行服务
go run main.go

# 服务将在 http://localhost:8080 启动
```

#### 启动前端

```bash
cd app

# 1. 安装依赖
npm install

# 2. 配置API地址（创建 .env 文件）
echo "VITE_API_URL=http://localhost:8080/api/v1" > .env

# 3. 启动开发服务器
npm run dev

# 4. 访问 http://localhost:5173
```

## 默认账号

| 工号 | 密码 | 姓名 | 部门 |
|------|------|------|------|
| E001 | 123456 | 张三 | 研发一组 |
| E002 | 123456 | 李四 | 研发一组 |
| E003 | 123456 | 王五 | 研发二组 |
| E004 | 123456 | 赵六 | 市场部 |
| E005 | 123456 | 钱七 | 财务部 |

## API文档

### 认证
- `POST /api/v1/auth/login` - 登录
- `POST /api/v1/auth/register` - 注册

### 成绩管理
- `GET /api/v1/results` - 成绩列表
- `POST /api/v1/results` - 创建成绩
- `PUT /api/v1/results/:id` - 更新成绩
- `DELETE /api/v1/results/:id` - 删除成绩

### 排行榜
- `GET /api/v1/rankings/all` - 全公司总榜
- `GET /api/v1/rankings/department` - 部门榜
- `GET /api/v1/rankings/year` - 年度榜

### 统计
- `GET /api/v1/statistics/dashboard` - 仪表盘
- `GET /api/v1/statistics/personal` - 个人统计
- `GET /api/v1/statistics/department` - 部门统计

## 项目结构

```
.
├── app/                 # 前端项目
│   ├── src/
│   │   ├── api/        # API调用
│   │   ├── components/ # 组件
│   │   └── sections/   # 页面区块
│   └── package.json
│
├── backend/             # 后端项目
│   ├── internal/
│   │   ├── handler/    # HTTP处理器
│   │   ├── service/    # 业务逻辑
│   │   ├── repository/ # 数据访问
│   │   └── model/      # 数据模型
│   ├── database/
│   │   └── schema.sql  # 数据库结构
│   └── main.go
│
└── docker-compose.yml   # Docker编排
```

## 数据库设计

### 核心表

| 表名 | 说明 |
|------|------|
| department | 部门信息 |
| employee | 员工信息 |
| race_result | 成绩记录 |
| user_notification | 通知消息 |
| operation_log | 操作日志 |

## 开发指南

### 添加新API

1. 在 `backend/internal/model/` 添加模型
2. 在 `backend/internal/repository/` 添加仓库方法
3. 在 `backend/internal/service/` 添加业务逻辑
4. 在 `backend/internal/handler/` 添加HTTP处理器
5. 在 `backend/main.go` 注册路由
6. 在 `app/src/api/` 添加前端API调用

### 前端组件开发

1. 在 `app/src/components/` 创建组件
2. 在 `app/src/sections/` 创建页面区块
3. 使用 shadcn/ui 组件库
4. 使用 Tailwind CSS 进行样式设计

## 部署

### 生产环境部署

```bash
# 1. 构建镜像
docker-compose build

# 2. 启动服务
docker-compose up -d

# 3. 查看日志
docker-compose logs -f

# 4. 停止服务
docker-compose down
```

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| DB_HOST | 数据库地址 | mysql |
| DB_PORT | 数据库端口 | 3306 |
| DB_USER | 数据库用户 | root |
| DB_PASSWORD | 数据库密码 | marathon123 |
| DB_NAME | 数据库名 | marathon_db |
| JWT_SECRET | JWT密钥 | your-secret-key |

## 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/xxx`)
3. 提交更改 (`git commit -am 'Add xxx'`)
4. 推送分支 (`git push origin feature/xxx`)
5. 创建 Pull Request

## 许可证

MIT License