Exam_registration/API_DOCUMENTATION.md

# API 接口测试文档

## 基础信息

- **Base URL**: `http://localhost:8080/api`
- **认证方式**: JWT Bearer Token
- **请求格式**: JSON (Content-Type: application/json)

## 认证接口

### 1. 用户登录

**接口**: `POST /login`

**请求参数**:
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}
```

**说明**: 
- 登录成功后返回 JWT Token
- Token 有效期 24 小时（可在配置文件中修改）
- 后续请求需在 Header 中携带：`Authorization: Bearer {token}`

---

### 2. 用户注册

**接口**: `POST /register`

**请求参数**:
```json
{
  "username": "testuser",
  "password": "123456",
  "real_name": "张三",
  "id_card": "110101199001011234",
  "email": "test@example.com",
  "phone": "13800138000"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": null
}
```

---

## 考试管理接口

### 3. 获取考试列表

**接口**: `GET /exams`

**请求参数**:
```
page=1&pageSize=10
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "title": "2024 年春季英语等级考试",
        "code": "ENG-2024-001",
        "subject": "英语",
        "exam_location": "北京市朝阳区考试中心",
        "exam_fee": 150.00,
        "max_candidates": 500,
        "status": 1,
        "start_time": "2024-04-15T09:00:00Z",
        "end_time": "2024-04-15T11:00:00Z"
      }
    ],
    "total": 10,
    "page": 1,
    "pageSize": 10
  }
}
```

---

### 4. 获取考试详情

**接口**: `GET /exams/:id`

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "title": "2024 年春季英语等级考试",
    "description": "本次考试为英语等级考试...",
    "start_time": "2024-04-15T09:00:00Z",
    "end_time": "2024-04-15T11:00:00Z",
    "registration_start": "2024-03-01T00:00:00Z",
    "registration_end": "2024-04-01T23:59:59Z",
    "max_candidates": 500,
    "exam_fee": 150.00,
    "exam_location": "北京市朝阳区考试中心",
    "subject": "英语",
    "status": 1
  }
}
```

---

### 5. 创建考试（需管理员权限）

**接口**: `POST /exams`

**Header**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "title": "2024 年夏季数学竞赛",
  "code": "MATH-2024-001",
  "description": "全市高中数学竞赛",
  "start_time": "2024-07-15 09:00:00",
  "end_time": "2024-07-15 12:00:00",
  "registration_start": "2024-06-01 00:00:00",
  "registration_end": "2024-07-01 23:59:59",
  "max_candidates": 300,
  "exam_fee": 100.00,
  "exam_location": "北京市第一中學",
  "subject": "数学"
}
```

---

### 6. 更新考试

**接口**: `PUT /exams/:id`

**请求参数**:
```json
{
  "title": "更新的考试名称",
  "max_candidates": 400
}
```

---

### 7. 删除考试

**接口**: `DELETE /exams/:id`

**响应**: 删除成功返回空数据

---

## 报名管理接口

### 8. 创建报名

**接口**: `POST /registrations`

**Header**: `Authorization: Bearer {token}`

**请求参数**:
```json
{
  "exam_id": 1,
  "remark": "首次参加，请多关照"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "user_id": 2,
    "exam_id": 1,
    "status": 0,
    "payment_status": 0,
    "remark": "首次参加，请多关照"
  }
}
```

**状态码说明**:
- 0: 待审核
- 1: 已通过
- 2: 已拒绝
- 3: 已取消

---

### 9. 获取报名列表

**接口**: `GET /registrations`

**请求参数**:
```
user_id=2&exam_id=1&page=1&pageSize=10&status=0
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 2,
        "exam_id": 1,
        "status": 1,
        "payment_status": 1,
        "ticket_number": "TKT11712345678",
        "exam_seat": "A-001",
        "audit_comment": "审核通过",
        "user": {
          "username": "testuser",
          "real_name": "张三"
        },
        "exam": {
          "title": "2024 年春季英语等级考试",
          "code": "ENG-2024-001"
        }
      }
    ],
    "total": 1
  }
}
```

---

### 10. 审核报名（管理员）

**接口**: `PUT /registrations/:id/audit`

**请求参数**:
```json
{
  "status": 1,
  "comment": "审核通过，请按时参加考试"
}
```

**说明**: 
- status: 1-通过，2-拒绝
- comment: 审核意见

---

### 11. 更新报名信息

**接口**: `PUT /registrations/:id`

**请求参数**:
```json
{
  "remark": "更新备注信息"
}
```

---

### 12. 取消报名

**接口**: `DELETE /registrations/:id`

---

## 考试通知接口

### 13. 获取通知列表

**接口**: `GET /notices`

**请求参数**:
```
exam_id=1&page=1&pageSize=10
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "exam_id": 1,
        "title": "关于考试时间的通知",
        "content": "原定于...",
        "type": 2,
        "publish_time": "2024-03-15T10:00:00Z"
      }
    ],
    "total": 5
  }
}
```

**通知类型**:
- 1: 普通通知
- 2: 重要通知
- 3: 紧急通知

---

### 14. 创建通知（管理员）

**接口**: `POST /notices`

**请求参数**:
```json
{
  "exam_id": 1,
  "title": "考场规则说明",
  "content": "考生须知...",
  "type": 1
}
```

---

## 成绩管理接口

### 15. 录入成绩（管理员）

**接口**: `POST /scores`

**请求参数**:
```json
{
  "user_id": 2,
  "exam_id": 1,
  "score": 85.5,
  "total_score": 100,
  "remark": "成绩优秀"
}
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "user_id": 2,
    "exam_id": 1,
    "score": 85.5,
    "total_score": 100,
    "pass": true,
    "rank": 0,
    "published": false
  }
}
```

---

### 16. 批量录入成绩（管理员）

**接口**: `POST /scores/batch`

**请求参数**:
```json
[
  {
    "user_id": 2,
    "score": 85.5,
    "total_score": 100
  },
  {
    "user_id": 3,
    "score": 92.0,
    "total_score": 100
  }
]
```

**说明**: 
- exam_id 从查询参数或当前上下文中获取
- 自动计算是否及格（>=60 分）

---

### 17. 查询个人成绩

**接口**: `GET /scores/exam/:exam_id`

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "user_id": 2,
    "exam_id": 1,
    "score": 85.5,
    "total_score": 100,
    "pass": true,
    "rank": 5,
    "published": true
  }
}
```

---

### 18. 获取成绩列表（管理员）

**接口**: `GET /scores`

**请求参数**:
```
exam_id=1&page=1&pageSize=10
```

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "user_id": 2,
        "exam_id": 1,
        "score": 85.5,
        "total_score": 100,
        "pass": true,
        "rank": 1,
        "published": true,
        "user": {
          "username": "testuser",
          "real_name": "张三"
        }
      }
    ],
    "total": 50
  }
}
```

---

### 19. 发布成绩（管理员）

**接口**: `PUT /scores/:id/publish`

**说明**: 发布后学生才能查看成绩

---

### 20. 删除成绩

**接口**: `DELETE /scores/:id`

---

## 用户信息接口

### 21. 获取当前用户信息

**接口**: `GET /user/info`

**Header**: `Authorization: Bearer {token}`

**响应示例**:
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 2,
    "username": "testuser",
    "real_name": "张三",
    "email": "test@example.com",
    "phone": "13800138000",
    "role": "user",
    "status": 1
  }
}
```

---

### 22. 更新用户信息

**接口**: `PUT /user/info`

**请求参数**:
```json
{
  "real_name": "李四",
  "email": "lisi@example.com",
  "phone": "13900139000"
}
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权（Token 无效或过期） |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## Postman 使用示例

### 1. 设置环境变量

在 Postman 中设置环境变量：
- `base_url`: http://localhost:8080
- `token`: {{login 后自动填充}}

### 2. Pre-request Script

在 Collection 的 Pre-request Script 中添加：
```javascript
// 自动添加 Token
pm.request.headers.add({
  key: 'Authorization',
  value: 'Bearer ' + pm.environment.get('token')
});
```

### 3. Test Scripts

在登录接口的 Tests 中添加：
```javascript
// 自动保存 Token
var jsonData = pm.response.json();
if (jsonData.code === 200) {
  pm.environment.set('token', jsonData.data.token);
}
```

---

## cURL 测试示例

### 登录
```bash
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

### 获取考试列表
```bash
curl -X GET "http://localhost:8080/api/exams?page=1&pageSize=10"
```

### 创建考试（需要 Token）
```bash
curl -X POST http://localhost:8080/api/exams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -d '{
    "title": "测试考试",
    "code": "TEST-001",
    "start_time": "2024-05-01 09:00:00",
    "end_time": "2024-05-01 11:00:00"
  }'
```

---

**文档版本**: v1.0  
**最后更新**: 2024-03-20