vitesse-yitisheng-web/docs/user_volunteer_controller_api_doc.md

用户志愿控制器 API 接口文档

概述

用户志愿控制器 (UserVolunteerController) 提供了志愿管理的相关接口，包括志愿保存、详情查询、名称修改、列表查询、删除和切换功能。

基础路径: /api/user/volunteer

认证方式: 需要登录认证，通过 JWT Token 进行身份验证

---

1. 保存志愿明细

保存用户选择的志愿专业列表到当前激活的志愿表中。

请求

• 方法: POST
• 路径: /api/user/volunteer/save
• Content-Type: application/json

请求参数

参数名	类型	必填	说明
keys	string[]	是	志愿专业Key列表，格式：学校代码_专业代码_招生代码

请求示例

[
  "10001_1001_001",
  "10002_2001_002",
  "10003_3001_003"
]

响应

字段名	类型	说明
code	int	状态码
message	string	响应消息
data	string	响应数据

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": "保存成功"
}

错误响应示例

{
  "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	专业详情

成功响应示例

{
  "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	响应数据

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": "更新成功"
}

错误响应示例

{
  "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	更新时间

成功响应示例

{
  "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	响应数据

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": "删除成功"
}

错误响应示例

{
  "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	响应数据

成功响应示例

{
  "code": 200,
  "message": "success",
  "data": "切换成功"
}

特殊响应示例（已是当前志愿单）

{
  "code": 200,
  "message": "success",
  "data": "已是当前志愿单，忽略切换"
}

错误码说明

错误码	说明
400	参数错误
500	获取用户成绩信息失败
500	切换失败

业务逻辑

1. 检查当前是否已是该志愿单，如果是则忽略切换
2. 执行志愿单切换操作
3. Redis 缓存同步（由 Service 层处理）

---

通用响应格式说明

成功响应

{
  "code": 200,
  "message": "success",
  "data": {}
}

错误响应

{
  "code": 错误码,
  "message": "错误信息",
  "data": null
}

常见错误码

错误码	说明
200	成功
400	请求参数错误
500	服务器内部错误

---

认证说明

所有接口都需要在请求头中携带 JWT Token：

Authorization: Bearer {token}

Token 从登录接口获取，有效期24小时。

---

注意事项

1. 保存志愿明细: 每次保存会先删除当前志愿表中的所有记录，再插入新记录
2. 批次分类: 志愿详情按 提前批、本科批、专科批 三大类分组展示
3. 数据去重: 保存志愿时会自动去重，避免重复添加相同专业
4. 顺序保持: 志愿序号按照提交的 keys 顺序依次递增
5. 权限控制: 所有操作都基于当前登录用户的身份，只能操作自己的志愿数据