biss/Exam_registration
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init

Browse Source
This commit is contained in:
biss
2026-03-20 21:41:00 +08:00
commit 3d1d4cf506
53 changed files with 7105 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

613
API_DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,613 @@
# 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