515 lines
12 KiB
Markdown
515 lines
12 KiB
Markdown
# 用户志愿控制器 API 接口文档
|
||
|
||
## 概述
|
||
|
||
用户志愿控制器 (UserVolunteerController) 提供了志愿管理的相关接口，包括志愿保存、详情查询、名称修改、列表查询、删除和切换功能。
|
||
|
||
**基础路径**: `/api/user/volunteer`
|
||
|
||
**认证方式**: 需要登录认证，通过 JWT Token 进行身份验证
|
||
|
||
---
|
||
|
||
## 1. 保存志愿明细
|
||
|
||
保存用户选择的志愿专业列表到当前激活的志愿表中。
|
||
|
||
**请求**
|
||
|
||
- **方法**: `POST`
|
||
- **路径**: `/api/user/volunteer/save`
|
||
- **Content-Type**: `application/json`
|
||
|
||
**请求参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|--------|------|----------------------------------------|
|
||
| keys | string[] | 是 | 志愿专业Key列表，格式：`学校代码_专业代码_招生代码` |
|
||
|
||
**请求示例**
|
||
|
||
```json
|
||
[
|
||
"10001_1001_001",
|
||
"10002_2001_002",
|
||
"10003_3001_003"
|
||
]
|
||
```
|
||
|
||
**响应**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------|--------|----------|
|
||
| code | int | 状态码 |
|
||
| message | string | 响应消息 |
|
||
| data | string | 响应数据 |
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": "保存成功"
|
||
}
|
||
```
|
||
|
||
**错误响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "未找到计算表名",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码说明**
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|----------------------------|
|
||
| 500 | 获取用户成绩信息失败 |
|
||
| 500 | 未找到计算表名 |
|
||
| 500 | 查找志愿表失败 |
|
||
| 500 | 请先创建志愿表 |
|
||
| 500 | 查找专业信息失败 |
|
||
| 500 | 删除旧数据失败 |
|
||
| 500 | 保存失败 |
|
||
|
||
**业务逻辑**
|
||
|
||
1. 对传入的keys进行去重处理
|
||
2. 获取当前登录用户的激活成绩信息
|
||
3. 查找当前激活的志愿表
|
||
4. 根据keys查找对应的专业信息
|
||
5. 构建志愿记录列表，保持提交顺序
|
||
6. 先删除旧的志愿记录，再批量插入新记录
|
||
|
||
---
|
||
|
||
## 2. 获取当前志愿单详情
|
||
|
||
获取当前激活志愿单的详细信息，包括志愿记录按批次分组展示。
|
||
|
||
**请求**
|
||
|
||
- **方法**: `GET`
|
||
- **路径**: `/api/user/volunteer/detail`
|
||
|
||
**请求参数**
|
||
|
||
无
|
||
|
||
**响应**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------|--------|--------------------|
|
||
| code | int | 状态码 |
|
||
| message | string | 响应消息 |
|
||
| data | object | 志愿详情数据 |
|
||
|
||
**data 数据结构**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|------------|--------|--------------------------|
|
||
| volunteer | object | 志愿单基本信息 |
|
||
| items | object | 按批次分组的志愿明细 |
|
||
|
||
**items 数据结构**
|
||
|
||
| 批次 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| 提前批 | array | 提前批志愿记录列表 |
|
||
| 本科批 | array | 本科批志愿记录列表 |
|
||
| 专科批 | array | 专科批志愿记录列表 |
|
||
|
||
**志愿记录项数据结构**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|------------------------|---------|--------------------------------|
|
||
| volunteerID | string | 志愿单ID |
|
||
| schoolCode | string | 学校代码 |
|
||
| majorCode | string | 专业代码 |
|
||
| enrollmentCode | string | 招生代码 |
|
||
| indexs | int | 志愿序号 |
|
||
| batch | string | 批次 |
|
||
| enrollProbability | float64 | 录取概率 |
|
||
| studentConvertedScore | float64 | 学生折合分 |
|
||
| calculationMajorID | string | 计算专业ID |
|
||
| schoolName | string | 学校名称 |
|
||
| majorName | string | 专业名称 |
|
||
| planNum | int | 计划人数 |
|
||
| tuition | string | 学费 |
|
||
| province | string | 省份 |
|
||
| schoolNature | string | 院校性质 |
|
||
| institutionType | string | 院校类型 |
|
||
| majorDetail | string | 专业详情 |
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"volunteer": {
|
||
"id": "123456789",
|
||
"volunteerName": "我的志愿表",
|
||
"scoreId": "987654321",
|
||
"createType": 1,
|
||
"state": 1
|
||
},
|
||
"items": {
|
||
"提前批": [
|
||
{
|
||
"volunteerID": "123456789",
|
||
"schoolCode": "10001",
|
||
"majorCode": "1001",
|
||
"enrollmentCode": "001",
|
||
"indexs": 1,
|
||
"batch": "本科提前批",
|
||
"schoolName": "某某大学",
|
||
"majorName": "美术学",
|
||
"planNum": 30,
|
||
"tuition": "8000元/年",
|
||
"enrollProbability": 85.5
|
||
}
|
||
],
|
||
"本科批": [],
|
||
"专科批": []
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------------------------|
|
||
| 500 | 获取用户成绩信息失败 |
|
||
| 500 | 查找志愿表失败 |
|
||
| 500 | 查找志愿明细失败 |
|
||
|
||
**批次分类规则**
|
||
|
||
- **提前批**: `提前批`、`本科提前批`
|
||
- **专科批**: `高职高专`、`专科批`
|
||
- **本科批**: 其他所有批次
|
||
|
||
---
|
||
|
||
## 3. 编辑志愿单名称
|
||
|
||
修改志愿单的名称。
|
||
|
||
**请求**
|
||
|
||
- **方法**: `PUT`
|
||
- **路径**: `/api/user/volunteer/updateName`
|
||
|
||
**请求参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 说明 |
|
||
|--------|--------|------|--------|------------|
|
||
| id | string | 是 | query | 志愿单ID |
|
||
| name | string | 是 | query | 志愿单名称 |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
PUT /api/user/volunteer/updateName?id=123456789&name=我的新志愿表
|
||
```
|
||
|
||
**响应**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------|--------|----------|
|
||
| code | int | 状态码 |
|
||
| message | string | 响应消息 |
|
||
| data | string | 响应数据 |
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": "更新成功"
|
||
}
|
||
```
|
||
|
||
**错误响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "参数错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码说明**
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|----------------|
|
||
| 400 | 参数错误 |
|
||
| 500 | 更新失败 |
|
||
|
||
---
|
||
|
||
## 4. 获取当前用户志愿单列表
|
||
|
||
分页查询当前用户的志愿单列表。
|
||
|
||
**请求**
|
||
|
||
- **方法**: `GET`
|
||
- **路径**: `/api/user/volunteer/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 默认值 | 说明 |
|
||
|--------|------|------|-------|--------|--------|
|
||
| page | int | 否 | query | 1 | 页码 |
|
||
| size | int | 否 | query | 10 | 每页数量 |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
GET /api/user/volunteer/list?page=1&size=10
|
||
```
|
||
|
||
**响应**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------|--------|----------|
|
||
| code | int | 状态码 |
|
||
| message | string | 响应消息 |
|
||
| data | object | 响应数据 |
|
||
|
||
**data 数据结构**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|--------|--------------|
|
||
| items | array | 志愿单列表 |
|
||
| total | int64 | 总数量 |
|
||
|
||
**志愿单数据结构**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------------|---------|------------------------------|
|
||
| id | string | 志愿单ID |
|
||
| volunteerName | string | 志愿单名称 |
|
||
| scoreId | string | 关联成绩ID |
|
||
| createType | int | 生成类型 (1.手动, 2.智能) |
|
||
| state | string | 状态 (0.未使用, 1.使用中, 2.历史) |
|
||
| createBy | string | 创建人 |
|
||
| createTime | string | 创建时间 |
|
||
| updateBy | string | 更新人 |
|
||
| updateTime | string | 更新时间 |
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"items": [
|
||
{
|
||
"id": "123456789",
|
||
"volunteerName": "我的志愿表",
|
||
"scoreId": "987654321",
|
||
"createType": 1,
|
||
"state": "1",
|
||
"createBy": "user001",
|
||
"createTime": "2026-01-31T10:00:00Z"
|
||
}
|
||
],
|
||
"total": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误码说明**
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|----------------|
|
||
| 500 | 查询失败 |
|
||
|
||
---
|
||
|
||
## 5. 删除志愿单
|
||
|
||
删除指定的志愿单。
|
||
|
||
**请求**
|
||
|
||
- **方法**: `DELETE`
|
||
- **路径**: `/api/user/volunteer/delete`
|
||
|
||
**请求参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 说明 |
|
||
|--------|--------|------|-------|----------|
|
||
| id | string | 是 | query | 志愿单ID |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
DELETE /api/user/volunteer/delete?id=123456789
|
||
```
|
||
|
||
**响应**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------|--------|----------|
|
||
| code | int | 状态码 |
|
||
| message | string | 响应消息 |
|
||
| data | string | 响应数据 |
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": "删除成功"
|
||
}
|
||
```
|
||
|
||
**错误响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 400,
|
||
"message": "参数错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**错误码说明**
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|----------------|
|
||
| 400 | 参数错误 |
|
||
| 500 | 删除失败 |
|
||
|
||
---
|
||
|
||
## 6. 切换当前志愿单
|
||
|
||
切换当前激活的志愿单。
|
||
|
||
**请求**
|
||
|
||
- **方法**: `POST`
|
||
- **路径**: `/api/user/volunteer/switch`
|
||
|
||
**请求参数**
|
||
|
||
| 参数名 | 类型 | 必填 | 位置 | 说明 |
|
||
|--------|--------|------|-------|----------|
|
||
| id | string | 是 | query | 志愿单ID |
|
||
|
||
**请求示例**
|
||
|
||
```
|
||
POST /api/user/volunteer/switch?id=123456789
|
||
```
|
||
|
||
**响应**
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|----------|--------|----------|
|
||
| code | int | 状态码 |
|
||
| message | string | 响应消息 |
|
||
| data | string | 响应数据 |
|
||
|
||
**成功响应示例**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": "切换成功"
|
||
}
|
||
```
|
||
|
||
**特殊响应示例（已是当前志愿单）**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": "已是当前志愿单，忽略切换"
|
||
}
|
||
```
|
||
|
||
**错误码说明**
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|----------------------------|
|
||
| 400 | 参数错误 |
|
||
| 500 | 获取用户成绩信息失败 |
|
||
| 500 | 切换失败 |
|
||
|
||
**业务逻辑**
|
||
|
||
1. 检查当前是否已是该志愿单，如果是则忽略切换
|
||
2. 执行志愿单切换操作
|
||
3. Redis 缓存同步（由 Service 层处理）
|
||
|
||
---
|
||
|
||
## 通用响应格式说明
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 错误码,
|
||
"message": "错误信息",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 常见错误码
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|--------------------|
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 认证说明
|
||
|
||
所有接口都需要在请求头中携带 JWT Token：
|
||
|
||
```
|
||
Authorization: Bearer {token}
|
||
```
|
||
|
||
Token 从登录接口获取，有效期24小时。
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **保存志愿明细**: 每次保存会先删除当前志愿表中的所有记录，再插入新记录
|
||
2. **批次分类**: 志愿详情按 提前批、本科批、专科批 三大类分组展示
|
||
3. **数据去重**: 保存志愿时会自动去重，避免重复添加相同专业
|
||
4. **顺序保持**: 志愿序号按照提交的 keys 顺序依次递增
|
||
5. **权限控制**: 所有操作都基于当前登录用户的身份，只能操作自己的志愿数据 |