# 心理健康测评API文档

## 1. API概述

心理健康测评模块提供班主任对班级学生进行心理健康状况评估的功能，包括测评创建、学生数据加载、心理状态评估、测评统计等功能。

### 1.1 基本信息

- **模块名称**：心理健康测评模块
- **模块代码**：ruoyi-xljk
- **API前缀**：/xljk
- **数据表**：xljk_evaluation, xljk_evaluation_detail
- **开发负责人**：Cursor AI
- **创建日期**：2025-07-02

### 1.2 功能列表

| 功能 | 描述 |
| ---- | ---- |
| 测评管理 | 创建、查询、修改、删除测评 |
| 测评明细管理 | 查询、修改学生心理状态 |
| 测评流程 | 发布测评、完成测评 |
| 数据统计 | 测评统计、重点关注学生统计 |

## 2. API列表

### 2.1 测评管理API

#### 2.1.1 查询测评列表

- **接口URL**：/xljk/evaluation/list
- **请求方式**：GET
- **接口权限**：xljk:evaluation:list
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| pageNum | int | 否 | 当前页码，默认为1 |
| pageSize | int | 否 | 每页记录数，默认为10 |
| evaluationName | string | 否 | 测评名称，支持模糊查询 |
| majorId | long | 否 | 专业ID |
| classId | long | 否 | 班级ID |
| semester | string | 否 | 学期 |
| status | string | 否 | 状态(0-草稿,1-已发布,2-已完成) |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "total": 3,
        "rows": [
            {
                "id": 1,
                "evaluationName": "2024上学期计算机2301班心理健康测评",
                "majorId": 101,
                "majorName": "计算机应用技术",
                "classId": 1001,
                "className": "计算机2301班",
                "semester": "2024上学期",
                "status": "2",
                "createName": "张班主任",
                "remark": "期末测评",
                "createBy": 2001,
                "createTime": "2025-01-10 09:00:00",
                "updateBy": 2001,
                "updateTime": "2025-01-10 10:30:00",
                "studentCount": 5,
                "focusCount": 2
            },
            {
                "id": 2,
                "evaluationName": "2024上学期电子2302班心理健康测评",
                "majorId": 102,
                "majorName": "电子商务",
                "classId": 1002,
                "className": "电子2302班",
                "semester": "2024上学期",
                "status": "0",
                "createName": "李班主任",
                "remark": "期末测评草稿",
                "createBy": 2002,
                "createTime": "2025-01-11 14:00:00",
                "updateBy": 2002,
                "updateTime": "2025-01-11 14:30:00",
                "studentCount": 0,
                "focusCount": 0
            }
        ]
    }
}
```

#### 2.1.2 获取测评详情

- **接口URL**：/xljk/evaluation/{id}
- **请求方式**：GET
- **接口权限**：xljk:evaluation:query
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| id | long | 是 | 测评ID |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "evaluationName": "2024上学期计算机2301班心理健康测评",
        "majorId": 101,
        "majorName": "计算机应用技术",
        "classId": 1001,
        "className": "计算机2301班",
        "semester": "2024上学期",
        "status": "2",
        "createName": "张班主任",
        "remark": "期末测评",
        "createBy": 2001,
        "createTime": "2025-01-10 09:00:00",
        "updateBy": 2001,
        "updateTime": "2025-01-10 10:30:00",
        "studentCount": 5,
        "focusCount": 2
    }
}
```

#### 2.1.3 新增测评

- **接口URL**：/xljk/evaluation
- **请求方式**：POST
- **接口权限**：xljk:evaluation:add
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| evaluationName | string | 是 | 测评名称 |
| majorId | long | 是 | 专业ID |
| majorName | string | 是 | 专业名称 |
| classId | long | 是 | 班级ID |
| className | string | 是 | 班级名称 |
| semester | string | 是 | 学期 |
| remark | string | 否 | 备注 |

- **请求示例**：

```json
{
    "evaluationName": "2024下学期计算机2301班心理健康测评",
    "majorId": 101,
    "majorName": "计算机应用技术",
    "classId": 1001,
    "className": "计算机2301班",
    "semester": "2024下学期",
    "remark": "期末测评"
}
```

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": 3
}
```

#### 2.1.4 修改测评

- **接口URL**：/xljk/evaluation
- **请求方式**：PUT
- **接口权限**：xljk:evaluation:edit
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| id | long | 是 | 测评ID |
| evaluationName | string | 是 | 测评名称 |
| majorId | long | 是 | 专业ID |
| majorName | string | 是 | 专业名称 |
| classId | long | 是 | 班级ID |
| className | string | 是 | 班级名称 |
| semester | string | 是 | 学期 |
| remark | string | 否 | 备注 |

- **请求示例**：

```json
{
    "id": 3,
    "evaluationName": "2024下学期计算机2301班心理健康测评(修改)",
    "majorId": 101,
    "majorName": "计算机应用技术",
    "classId": 1001,
    "className": "计算机2301班",
    "semester": "2024下学期",
    "remark": "期末测评(修改)"
}
```

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功"
}
```

#### 2.1.5 删除测评

- **接口URL**：/xljk/evaluation/{ids}
- **请求方式**：DELETE
- **接口权限**：xljk:evaluation:remove
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| ids | long[] | 是 | 测评ID数组 |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功"
}
```

#### 2.1.6 获取专业和班级选项

- **接口URL**：/xljk/evaluation/options/majorAndClass
- **请求方式**：GET
- **接口权限**：xljk:evaluation:query
- **请求参数**：无
- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "majors": [
            {
                "id": 101,
                "name": "计算机应用技术"
            },
            {
                "id": 102,
                "name": "电子商务"
            },
            {
                "id": 103,
                "name": "会计"
            }
        ],
        "classes": [
            {
                "id": 1001,
                "name": "计算机2301班",
                "majorId": 101
            },
            {
                "id": 1002,
                "name": "电子2302班",
                "majorId": 102
            },
            {
                "id": 1003,
                "name": "会计2303班",
                "majorId": 103
            }
        ]
    }
}
```

#### 2.1.7 获取学期选项

- **接口URL**：/xljk/evaluation/options/semester
- **请求方式**：GET
- **接口权限**：xljk:evaluation:query
- **请求参数**：无
- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        "2023上学期",
        "2023下学期",
        "2024上学期",
        "2024下学期",
        "2025上学期",
        "2025下学期"
    ]
}
```

#### 2.1.8 发布测评

- **接口URL**：/xljk/evaluation/{id}/publish
- **请求方式**：PUT
- **接口权限**：xljk:evaluation:publish
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| id | long | 是 | 测评ID |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功"
}
```

#### 2.1.9 完成测评

- **接口URL**：/xljk/evaluation/{id}/complete
- **请求方式**：PUT
- **接口权限**：xljk:evaluation:complete
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| id | long | 是 | 测评ID |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功"
}
```

#### 2.1.10 导出测评

- **接口URL**：/xljk/evaluation/export
- **请求方式**：POST
- **接口权限**：xljk:evaluation:export
- **请求参数**：同查询测评列表接口
- **返回结果**：Excel文件流

### 2.2 测评明细API

#### 2.2.1 查询测评明细列表

- **接口URL**：/xljk/evaluation/detail/list
- **请求方式**：GET
- **接口权限**：xljk:evaluation:list
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| pageNum | int | 否 | 当前页码，默认为1 |
| pageSize | int | 否 | 每页记录数，默认为10 |
| evaluationId | long | 否 | 测评ID |
| studentName | string | 否 | 学生姓名，支持模糊查询 |
| studentNo | string | 否 | 学号，支持模糊查询 |
| gender | string | 否 | 性别(0-男,1-女,2-未知) |
| mentalStatus | string | 否 | 心理状态(1-健康,2-良好,3-重点关注) |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "total": 5,
        "rows": [
            {
                "id": 101,
                "evaluationId": 1,
                "studentId": 10001,
                "studentNo": "2024001",
                "studentName": "张三",
                "gender": "0",
                "birthDate": "2005-06-15",
                "phone": "13800138001",
                "mentalStatus": "1",
                "score": null,
                "remark": null,
                "createBy": 2001,
                "createTime": "2025-01-10 09:10:00",
                "updateBy": 2001,
                "updateTime": "2025-01-10 09:10:00",
                "evaluationName": "2024上学期计算机2301班心理健康测评",
                "className": "计算机2301班",
                "majorName": "计算机应用技术",
                "semester": "2024上学期"
            },
            {
                "id": 103,
                "evaluationId": 1,
                "studentId": 10003,
                "studentNo": "2024003",
                "studentName": "王五",
                "gender": "0",
                "birthDate": "2005-09-10",
                "phone": "13800138003",
                "mentalStatus": "3",
                "score": 75,
                "remark": "近期学习压力大，需要关注",
                "createBy": 2001,
                "createTime": "2025-01-10 09:20:00",
                "updateBy": 2001,
                "updateTime": "2025-01-10 09:20:00",
                "evaluationName": "2024上学期计算机2301班心理健康测评",
                "className": "计算机2301班",
                "majorName": "计算机应用技术",
                "semester": "2024上学期"
            }
        ]
    }
}
```

#### 2.2.2 根据测评ID查询明细列表

- **接口URL**：/xljk/evaluation/detail/evaluation/{evaluationId}
- **请求方式**：GET
- **接口权限**：xljk:evaluation:query
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| evaluationId | long | 是 | 测评ID |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "id": 101,
            "evaluationId": 1,
            "studentId": 10001,
            "studentNo": "2024001",
            "studentName": "张三",
            "gender": "0",
            "birthDate": "2005-06-15",
            "phone": "13800138001",
            "mentalStatus": "1",
            "score": null,
            "remark": null,
            "createBy": 2001,
            "createTime": "2025-01-10 09:10:00",
            "updateBy": 2001,
            "updateTime": "2025-01-10 09:10:00"
        },
        {
            "id": 102,
            "evaluationId": 1,
            "studentId": 10002,
            "studentNo": "2024002",
            "studentName": "李四",
            "gender": "0",
            "birthDate": "2005-03-22",
            "phone": "13800138002",
            "mentalStatus": "2",
            "score": null,
            "remark": null,
            "createBy": 2001,
            "createTime": "2025-01-10 09:15:00",
            "updateBy": 2001,
            "updateTime": "2025-01-10 09:15:00"
        }
    ]
}
```

#### 2.2.3 获取学生信息

- **接口URL**：/xljk/evaluation/detail/students/{classId}
- **请求方式**：GET
- **接口权限**：xljk:evaluation:query
- **排序方式**：按学号 `studentNo` 降序返回，确保默认展示最新学号
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| classId | long | 是 | 班级ID |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "id": 10001,
            "studentNo": "2024001",
            "studentName": "张三",
            "gender": "0",
            "birthDate": "2005-06-15",
            "phone": "13800138001"
        },
        {
            "id": 10002,
            "studentNo": "2024002",
            "studentName": "李四",
            "gender": "0",
            "birthDate": "2005-03-22",
            "phone": "13800138002"
        }
    ]
}
```

#### 2.2.4 批量新增测评明细

- **接口URL**：/xljk/evaluation/detail/batch
- **请求方式**：POST
- **接口权限**：xljk:evaluation:add
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| 数组 | array | 是 | 测评明细数组 |

- **请求示例**：

```json
[
    {
        "evaluationId": 3,
        "studentId": 10001,
        "studentNo": "2024001",
        "studentName": "张三",
        "gender": "0",
        "birthDate": "2005-06-15",
        "phone": "13800138001"
    },
    {
        "evaluationId": 3,
        "studentId": 10002,
        "studentNo": "2024002",
        "studentName": "李四",
        "gender": "0",
        "birthDate": "2005-03-22",
        "phone": "13800138002"
    }
]
```

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功"
}
```

#### 2.2.5 批量更新学生心理状态

- **接口URL**：/xljk/evaluation/detail/batch/mentalStatus
- **请求方式**：PUT
- **接口权限**：xljk:evaluation:edit
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| 数组 | array | 是 | 学生心理状态数组 |

- **请求示例**：

```json
[
    {
        "id": 101,
        "mentalStatus": "1"
    },
    {
        "id": 102,
        "mentalStatus": "2"
    },
    {
        "id": 103,
        "mentalStatus": "3",
        "score": 75,
        "remark": "近期学习压力大，需要关注"
    }
]
```

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功"
}
```

#### 2.2.6 获取重点关注学生列表

- **接口URL**：/xljk/evaluation/detail/focus
- **请求方式**：GET
- **接口权限**：xljk:evaluation:query
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| pageNum | int | 否 | 当前页码，默认为1 |
| pageSize | int | 否 | 每页记录数，默认为10 |
| evaluationId | long | 否 | 测评ID |
| studentName | string | 否 | 学生姓名，支持模糊查询 |
| studentNo | string | 否 | 学号，支持模糊查询 |
| gender | string | 否 | 性别(0-男,1-女,2-未知) |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "total": 2,
        "rows": [
            {
                "id": 103,
                "evaluationId": 1,
                "studentId": 10003,
                "studentNo": "2024003",
                "studentName": "王五",
                "gender": "0",
                "birthDate": "2005-09-10",
                "phone": "13800138003",
                "mentalStatus": "3",
                "score": 75,
                "remark": "近期学习压力大，需要关注",
                "createBy": 2001,
                "createTime": "2025-01-10 09:20:00",
                "updateBy": 2001,
                "updateTime": "2025-01-10 09:20:00",
                "evaluationName": "2024上学期计算机2301班心理健康测评",
                "className": "计算机2301班",
                "majorName": "计算机应用技术",
                "semester": "2024上学期"
            },
            {
                "id": 105,
                "evaluationId": 1,
                "studentId": 10005,
                "studentNo": "2024005",
                "studentName": "钱七",
                "gender": "1",
                "birthDate": "2005-07-20",
                "phone": "13800138005",
                "mentalStatus": "3",
                "score": 80,
                "remark": "家庭情况特殊，需要关注",
                "createBy": 2001,
                "createTime": "2025-01-10 09:30:00",
                "updateBy": 2001,
                "updateTime": "2025-01-10 09:30:00",
                "evaluationName": "2024上学期计算机2301班心理健康测评",
                "className": "计算机2301班",
                "majorName": "计算机应用技术",
                "semester": "2024上学期"
            }
        ]
    }
}
```

### 2.3 统计分析API

#### 2.3.1 获取测评统计数据

- **接口URL**：/xljk/evaluation/{id}/statistics
- **请求方式**：GET
- **接口权限**：xljk:evaluation:statistics
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| id | long | 是 | 测评ID |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "evaluationName": "2024上学期计算机2301班心理健康测评",
        "className": "计算机2301班",
        "semester": "2024上学期",
        "createName": "张班主任",
        "createTime": "2025-01-10 09:00:00",
        "totalCount": 5,
        "healthyCount": 2,
        "goodCount": 1,
        "focusCount": 2,
        "healthyPercent": 40.0,
        "goodPercent": 20.0,
        "focusPercent": 40.0,
        "maleCount": 3,
        "femaleCount": 2,
        "maleFocusCount": 1,
        "femaleFocusCount": 1
    }
}
```

#### 2.3.2 获取重点关注学生统计

- **接口URL**：/xljk/evaluation/statistics/focus
- **请求方式**：GET
- **接口权限**：xljk:evaluation:statistics
- **请求参数**：

| 参数名 | 类型 | 是否必须 | 描述 |
| ------ | ---- | -------- | ---- |
| majorId | long | 否 | 专业ID |
| classId | long | 否 | 班级ID |
| semester | string | 否 | 学期 |

- **返回示例**：

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "totalStudentCount": 10,
        "totalFocusCount": 4,
        "totalFocusRate": 40.0,
        "classStats": [
            {
                "className": "计算机2301班",
                "studentCount": 5,
                "focusCount": 2,
                "focusRate": 40.0
            },
            {
                "className": "电子2302班",
                "studentCount": 5,
                "focusCount": 2,
                "focusRate": 40.0
            }
        ],
        "semesterStats": [
            {
                "semester": "2023下学期",
                "studentCount": 5,
                "focusCount": 2,
                "focusRate": 40.0
            },
            {
                "semester": "2024上学期",
                "studentCount": 5,
                "focusCount": 2,
                "focusRate": 40.0
            }
        ]
    }
}
```

## 3. 数据字典

### 3.1 测评状态(xljk_evaluation_status)

| 编码 | 标签 | 描述 |
| ---- | ---- | ---- |
| 0 | 草稿 | 测评创建后的初始状态 |
| 1 | 已发布 | 测评发布后的状态 |
| 2 | 已完成 | 测评完成后的状态 |

### 3.2 心理状态(xljk_mental_status)

| 编码 | 标签 | 描述 |
| ---- | ---- | ---- |
| 1 | 健康 | 心理状态健康 |
| 2 | 良好 | 心理状态良好 |
| 3 | 重点关注 | 需要重点关注的心理状态 |

## 4. 注意事项

1. 测评状态流转：草稿 -> 已发布 -> 已完成，不能跳过中间状态
2. 草稿状态的测评可以修改和删除，已发布和已完成状态的测评不能删除
3. 已完成状态的测评不能修改学生心理状态
4. 重点关注状态的学生必须填写分数
5. 测评完成后，会统计各状态学生人数和比例
6. 班主任只能查看和管理自己创建的测评