# 艺考招生管理系统 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         # 密码加密 (PBE)
├── middleware/
│   ├── auth.go             # 登录鉴权
│   ├── security.go         # 安全校验 (防暴力入侵)
│   └── ratelimit.go        # 接口限流
├── modules/
│   ├── system/             # 系统模块
│   └── yx/                 # 艺考模块
├── logs/                   # 日志目录
│   └── 2025-12-17-1.html   # HTML格式日志
└── docs/                   # Swagger文档
```

## 快速开始

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

## 配置说明

修改 `config/config.go`:

```go
var AppConfig = &appConfig{
    // 日志配置
    Log: LogConfig{
        Level:   "debug",  // debug/info/warn/error
        Dir:     "logs",   // 日志目录
        Console: true,     // 是否输出到控制台
    },
    // 安全配置
    Security: SecurityConfig{
        Enable:    true,              // 是否启用
        HeaderKey: "X-App-Sign",      // 签名字段
        SecretKey: "yts@2025#secure", // 签名密钥
    },
    // 限流配置
    RateLimit: RateLimitConfig{
        Enable:  true,
        Default: RateLimitRule{Interval: 2, MaxRequests: 1}, // 默认2秒1次
        Rules: map[string]RateLimitRule{
            "/api/auth/login": {Interval: 5, MaxRequests: 1}, // 登录5秒1次
        },
    },
}
```

## 功能说明

### 1. 日志系统

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

```go
common.Debug("调试信息: %s", msg)
common.Info("普通信息: %s", msg)
common.Warn("警告信息: %s", msg)
common.LogError("错误信息: %s", msg)
```

### 2. 安全校验 (防暴力入侵)

请求头需携带签名:
```
X-App-Sign: MD5(timestamp + secretKey)
X-App-Timestamp: 毫秒时间戳
```

前端签名示例 (JavaScript):
```javascript
const timestamp = Date.now().toString();
const sign = md5(timestamp + 'yts@2025#secure');

fetch('/api/xxx', {
    headers: {
        'X-App-Sign': sign,
        'X-App-Timestamp': timestamp,
        'Authorization': 'Bearer ' + token
    }
});
```

### 3. 接口限流

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

默认规则: 2秒1次
超过限制返回: `{"code": 429, "message": "操作过快，请稍后再试"}`

配置示例:
```go
Rules: map[string]RateLimitRule{
    "/api/auth/login":       {Interval: 5, MaxRequests: 1},  // 5秒1次
    "/api/yx-school-majors": {Interval: 1, MaxRequests: 5},  // 1秒5次
}
```

## 中间件执行顺序

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

## 白名单配置

```go
// 安全校验白名单
middleware.AddSecurityWhitelist("/api/public/xxx")

// 限流白名单
middleware.AddRateLimitWhitelist("/api/public/xxx")

// 登录鉴权白名单
middleware.AddWhiteList("/api/public/xxx")
```

## API 接口

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

### 用户管理 `/api/sys-users`
### 院校专业 `/api/yx-school-majors`
### 历年招生 `/api/yx-history-enrolls`
### 计算专业 `/api/yx-calculation-majors`

## 日志文件示例

日志以 HTML 格式保存，支持浏览器直接打开查看:

```
logs/
├── 2025-12-17-1.html  # 第1次启动
├── 2025-12-17-2.html  # 第2次启动
└── 2025-12-18-1.html  # 新的一天
```