# 艺考招生管理系统 API

## 项目概述

艺考招生管理系统是一个基于 Go + Gin + GORM + Redis 的 RESTful API 服务，用于管理和计算艺考志愿填报、成绩统计和录取概率等功能。

### 核心技术栈

- **Go 1.21+** - 主要开发语言
- **Gin** - Web 框架
- **GORM** - ORM 框架
- **MySQL 8.0** - 数据存储
- **Redis** - 会话存储和限流
- **Swaggo** - API 文档生成

### 项目架构

项目采用典型的分层架构模式：

```
server/
├── main.go                    # 应用程序入口
├── config/                    # 配置文件
│   ├── config.go              # 应用配置
│   ├── database.go            # MySQL 配置
│   └── redis.go               # Redis 配置
├── common/                    # 公共组件
│   ├── response.go            # 统一响应格式
│   ├── context.go             # 上下文工具
│   ├── logger.go              # 日志工具
│   └── password.go            # 密码加密
├── middleware/                # 中间件
│   ├── auth.go                # 登录鉴权
│   ├── security.go            # 安全校验
│   ├── ratelimit.go           # 接口限流
│   └── cors.go                # 跨域处理
├── modules/                   # 业务模块
│   ├── system/                # 系统模块 (用户认证、权限管理)
│   ├── user/                  # 用户模块 (用户相关功能)
│   └── yx/                    # 艺考模块 (核心业务)
├── docs/                      # API 文档
└── logs/                      # 日志目录
```

### 业务模块

#### 1. 系统模块 (system)
- 用户认证 (登录/登出/用户信息)
- 用户管理

#### 2. 用户模块 (user)
- 成绩管理
- 专业选择
- 志愿填报
- 用户认证

#### 3. 艺考模块 (yx)
- 院校专业管理
- 历年招生数据
- 计算专业逻辑
- 用户成绩管理
- 志愿管理
- 志愿记录管理

## 部署与运行

### 环境要求
- Go 1.21+
- MySQL 8.0
- Redis

### 快速启动

```bash
cd server
go mod tidy
swag init
go run main.go
```

### 配置说明

系统支持多环境配置文件：

- `config/config.dev.yaml` - 开发环境
- `config/config.test.yaml` - 测试环境
- `config/config.prod.yaml` - 生产环境

配置文件格式示例：
```yaml
server:
  port: 8081

database:
  driver: mysql
  host: localhost
  port: 3306
  database: yitisheng
  username: root
  password: "password"

redis:
  addr: localhost:6379
  password: "password"
  db: 1
```

## 安全机制

### 1. 登录鉴权
- 基于 JWT Token 的身份验证
- 支持白名单配置，允许特定接口无需登录访问
- Token 存储在 Redis 中，支持过期时间设置

### 2. 安全校验
- 请求头需携带签名进行验证
- 防暴力破解机制
- 支持白名单配置

### 3. 接口限流
- 基于 Redis 滑动窗口算法
- 支持按用户ID或IP限流
- 可为不同接口配置不同限流规则

## API 接口

### 认证相关
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/user/auth/login | 用户登录 |
| POST | /api/user/auth/logout | 用户登出 |
| GET | /api/user/auth/info | 获取当前用户信息 |

### 系统管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/sys-users | 获取用户列表 |
| POST | /api/sys-users | 创建用户 |
| PUT | /api/sys-users/:id | 更新用户 |
| DELETE | /api/sys-users/:id | 删除用户 |

### 艺考相关
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/yx-school-majors | 获取院校专业列表 |
| GET | /api/yx-history-enrolls | 获取历年招生数据 |
| GET | /api/yx-calculation-majors | 获取计算专业数据 |
| GET | /api/yx-user-scores | 获取用户成绩 |
| GET | /api/yx-volunteers | 获取志愿列表 |
| POST | /api/yx-volunteers | 创建志愿 |
| PUT | /api/yx-volunteers/:id | 更新志愿 |
| DELETE | /api/yx-volunteers/:id | 删除志愿 |

### 中间件执行顺序

```
请求 -> 安全校验 -> 限流 -> 登录鉴权 -> Controller
```

## 数据实体

### YxVolunteer (志愿表)
- ID: 主键
- VolunteerName: 志愿单名称
- ScoreId: 关联成绩ID
- CreateType: 生成类型 (1.手动生成, 2.智能生成)
- State: 状态 (0-未使用, 1-使用中, 2-历史)
- CreateBy: 创建人
- CreateTime: 创建时间
- UpdateBy: 更新人
- UpdateTime: 更新时间

## 常量定义

### 业务状态常量
- StateActive ("1") - 使用中
- StateInactive ("0") - 未使用/已删除
- StateHistory ("2") - 历史记录

### 令牌相关
- TokenHeader: "Authorization"
- HeaderTokenPrefix: "Bearer "
- RedisTokenExpire: 24小时

## 日志系统

- 支持 debug/info/warn/error 级别
- 输出到 HTML 文件，按日期和启动次数命名
- 可配置是否同时输出到控制台

## 开发规范

### 代码风格
- 使用 Go 语言标准格式 (go fmt)
- 遵循 Go 语言命名规范
- 使用有意义的变量和函数名

### 错误处理
- 统一使用 common.Error(c, code, message) 返回错误
- 业务错误码使用 HTTP 标准码或自定义业务码
- 记录详细错误日志便于调试

### 接口文档
- 使用 Swaggo 注解生成 API 文档
- 所有公开接口都应有完整的文档注释
- 包含请求参数、响应格式和错误码说明

## 额外说明

项目还包含一些 Java 代码文件，如 `ScoreUtil.java`，这表明项目可能正在从 Java 版本迁移到 Go 版本，或者 Java 版本作为参考。Go 版本中的 `server/modules/yx/service/score_util.go` 文件可能包含与 Java 版本相同功能的实现。

## 注意事项

- 开发环境中的安全校验默认关闭 (enable: false)
- 生产环境务必开启安全校验
- 需要配置合适的限流规则防止恶意请求
- 定期清理日志文件避免磁盘空间不足