# 用户志愿控制器 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. **权限控制**: 所有操作都基于当前登录用户的身份，只能操作自己的志愿数据