cykj/hzdyjs

0 Fork 0

Files

T

wuzhen a2222f63cb wuzhen update

2025-08-10 00:24:31 +08:00

19 KiB

Raw Blame History

奖学金申请管理API文档

模块名称: 奖学金申请管理
版本: v2.0
创建日期: 2025-01-01
最后更新: 2025-01-01

📋 目录

1. 概述
2. 基础管理接口
3. 业务功能接口
4. 辅助功能接口
5. 数据模型
6. 错误码说明

1. 概述

1.1 模块介绍

奖学金申请管理模块v2.0版本实现了从学生自主申请到班主任代申请的模式转换，支持班级名额分配、批量申请提交、审核流程等功能。

1.2 主要特性

✅ 班主任代申请: 支持班主任为学生批量提交申请
✅ 名额控制: 班级级别的名额分配和使用管理
✅ 时间窗口控制: 支持申请时间窗口管理
✅ 审核流程: 完整的申请审核和状态管理
✅ 材料管理: 支持申请材料上传和审核
✅ 统计分析: 提供详细的申请统计数据

1.3 权限说明

所有接口均需要Bearer Token认证，权限前缀：jcbt:scholarshipApplication:

1.4 接口基础信息

Base URL: /jcbt/scholarshipApplication
Content-Type: application/json;charset=utf-8
Authorization: Bearer {access_token}

2. 基础管理接口

2.1 查询申请记录列表

接口描述: 分页查询奖学金申请记录列表

URL: GET /jcbt/scholarshipApplication/list
权限: jcbt:scholarshipApplication:list

请求参数:

参数名	类型	必填	说明
pageNum	Integer	否	页码，默认1
pageSize	Integer	否	每页条数，默认10
batchId	Long	否	批次ID
scholarshipTypeId	Long	否	奖学金类型ID
studentCode	String	否	学生学号
studentName	String	否	学生姓名（模糊查询）
deptId	Long	否	学院ID
classId	Long	否	班级ID
applicantType	String	否	申请人类型
status	String	否	申请状态
beginCreateTime	String	否	创建开始时间
endCreateTime	String	否	创建结束时间

响应示例:

{
    "total": 100,
    "rows": [
        {
            "id": 1,
            "batchId": 1,
            "batchName": "2024-2025学年奖学金",
            "scholarshipTypeId": 1,
            "scholarshipTypeName": "国家奖学金",
            "studentCode": "2021001001",
            "studentName": "张三",
            "studentId": 1001,
            "deptId": 103,
            "deptName": "计算机学院",
            "classId": 1001,
            "className": "计算机2021-1班",
            "applicantType": "TEACHER",
            "applicantId": 2001,
            "applicantName": "李老师",
            "applicationType": "RECOMMEND",
            "comprehensiveScore": 95.5,
            "academicScore": 96.0,
            "moralScore": 95.0,
            "physicalScore": 94.0,
            "status": "SUBMITTED",
            "submitTime": "2024-03-15 10:30:00",
            "requireMaterials": 1,
            "materialStatus": "PENDING",
            "createTime": "2024-03-15 10:30:00"
        }
    ],
    "code": 200,
    "msg": "查询成功"
}

2.2 获取申请记录详情

接口描述: 根据ID查询申请记录详细信息

URL: GET /jcbt/scholarshipApplication/{id}
权限: jcbt:scholarshipApplication:query

路径参数:

参数名	类型	必填	说明
id	Long	是	申请记录ID

响应示例:

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "id": 1,
        "batchId": 1,
        "batchName": "2024-2025学年奖学金",
        "scholarshipTypeId": 1,
        "scholarshipTypeName": "国家奖学金",
        "studentCode": "2021001001",
        "studentName": "张三",
        "studentId": 1001,
        "deptId": 103,
        "deptName": "计算机学院",
        "classId": 1001,
        "className": "计算机2021-1班",
        "applicantType": "TEACHER",
        "applicantId": 2001,
        "applicantName": "李老师",
        "applicationType": "RECOMMEND",
        "applicationReason": "该学生综合成绩优秀，品学兼优",
        "applicationDescription": "详细申请说明...",
        "comprehensiveScore": 95.5,
        "academicScore": 96.0,
        "moralScore": 95.0,
        "physicalScore": 94.0,
        "aestheticScore": 93.0,
        "laborScore": 94.0,
        "awards": "国家级竞赛一等奖",
        "socialPractice": "暑期社会实践活动",
        "familyEconomicStatus": "家庭经济困难",
        "status": "SUBMITTED",
        "submitTime": "2024-03-15 10:30:00",
        "requireMaterials": 1,
        "materialStatus": "PENDING",
        "createTime": "2024-03-15 10:30:00",
        "updateTime": "2024-03-15 10:35:00"
    }
}

2.3 新增申请记录

接口描述: 创建新的奖学金申请记录

URL: POST /jcbt/scholarshipApplication
权限: jcbt:scholarshipApplication:add

请求体:

{
    "batchId": 1,
    "scholarshipTypeId": 1,
    "studentCode": "2021001001",
    "studentName": "张三",
    "studentId": 1001,
    "deptId": 103,
    "deptName": "计算机学院",
    "classId": 1001,
    "className": "计算机2021-1班",
    "applicantType": "TEACHER",
    "applicantId": 2001,
    "applicantName": "李老师",
    "applicationType": "RECOMMEND",
    "applicationReason": "该学生综合成绩优秀，品学兼优",
    "applicationDescription": "详细申请说明...",
    "comprehensiveScore": 95.5,
    "academicScore": 96.0,
    "moralScore": 95.0,
    "physicalScore": 94.0,
    "aestheticScore": 93.0,
    "laborScore": 94.0,
    "awards": "国家级竞赛一等奖",
    "socialPractice": "暑期社会实践活动",
    "familyEconomicStatus": "家庭经济困难",
    "requireMaterials": 1,
    "remark": "备注信息"
}

响应示例:

{
    "code": 200,
    "msg": "操作成功",
    "data": null
}

2.4 修改申请记录

接口描述: 修改申请记录信息

URL: PUT /jcbt/scholarshipApplication
权限: jcbt:scholarshipApplication:edit

请求体: 与新增接口相同，需包含id字段

2.5 删除申请记录

接口描述: 批量删除申请记录

URL: DELETE /jcbt/scholarshipApplication/{ids}
权限: jcbt:scholarshipApplication:remove

路径参数:

参数名	类型	必填	说明
ids	String	是	申请记录ID串，用逗号分隔

2.6 获取可申请奖学金类型

接口描述: 查询班级可申请的奖学金类型列表（有可用名额）

URL: GET /jcbt/scholarshipApplication/available
权限: jcbt:scholarshipApplication:available

请求参数:

参数名	类型	必填	说明
classId	Long	是	班级ID
batchId	Long	是	批次ID

响应示例:

{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "scholarshipTypeId": 1,
            "scholarshipTypeName": "国家奖学金",
            "availableQuota": 2,
            "totalQuota": 3
        },
        {
            "scholarshipTypeId": 2,
            "scholarshipTypeName": "国家励志奖学金",
            "availableQuota": 5,
            "totalQuota": 8
        }
    ]
}

3. 业务功能接口

3.1 查询我的申请记录

接口描述: 查询班主任负责班级的申请记录

URL: GET /jcbt/scholarshipApplication/my
权限: jcbt:scholarshipApplication:my

请求参数:

参数名	类型	必填	说明
applicantId	Long	是	申请人ID（班主任ID）
batchId	Long	否	批次ID

响应示例:

{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "id": 1,
            "batchName": "2024-2025学年奖学金",
            "scholarshipTypeName": "国家奖学金",
            "studentCode": "2021001001",
            "studentName": "张三",
            "className": "计算机2021-1班",
            "status": "SUBMITTED",
            "submitTime": "2024-03-15 10:30:00"
        }
    ]
}

3.2 查询待审核申请

接口描述: 查询待审核的申请记录列表

URL: GET /jcbt/scholarshipApplication/pending
权限: jcbt:scholarshipApplication:pending

请求参数:

参数名	类型	必填	说明
reviewerId	Long	否	审核人ID
status	String	否	申请状态

响应示例:

{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "id": 1,
            "batchName": "2024-2025学年奖学金",
            "scholarshipTypeName": "国家奖学金",
            "studentCode": "2021001001",
            "studentName": "张三",
            "deptName": "计算机学院",
            "className": "计算机2021-1班",
            "status": "REVIEWING",
            "submitTime": "2024-03-15 10:30:00",
            "comprehensiveScore": 95.5
        }
    ]
}

3.3 检查学生申请资格

接口描述: 检查学生是否符合申请条件

URL: GET /jcbt/scholarshipApplication/check
权限: jcbt:scholarshipApplication:check

请求参数:

参数名	类型	必填	说明
studentId	Long	是	学生ID
batchId	Long	是	批次ID
scholarshipTypeId	Long	是	奖学金类型ID

响应示例:

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "eligible": true,
        "message": "学生符合申请条件",
        "restrictions": []
    }
}

3.4 批量审核申请

接口描述: 批量审核申请记录

URL: POST /jcbt/scholarshipApplication/approve
权限: jcbt:scholarshipApplication:approve

请求参数:

参数名	类型	必填	说明
status	String	是	审核状态（APPROVED/REJECTED）
reviewerId	Long	是	审核人ID
reviewerName	String	是	审核人姓名
reviewComment	String	否	审核意见

请求体:

[1, 2, 3, 4]

响应示例:

{
    "code": 200,
    "msg": "操作成功",
    "data": null
}

4. 辅助功能接口

4.1 导出申请记录

接口描述: 导出申请记录列表为Excel文件

URL: POST /jcbt/scholarshipApplication/export
权限: jcbt:scholarshipApplication:export

请求体: 查询条件参数（与列表查询相同）

响应: Excel文件下载

4.2 导入申请记录

接口描述: 从Excel文件导入申请记录

URL: POST /jcbt/scholarshipApplication/import
权限: jcbt:scholarshipApplication:import
Content-Type: multipart/form-data

请求参数:

参数名	类型	必填	说明
file	File	是	Excel文件

4.3 获取申请统计数据

接口描述: 获取申请相关的统计信息

URL: GET /jcbt/scholarshipApplication/statistics
权限: jcbt:scholarshipApplication:statistics

请求参数:

参数名	类型	必填	说明
batchId	Long	否	批次ID
deptId	Long	否	学院ID

响应示例:

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "statistics": [
            {
                "scholarshipTypeName": "国家奖学金",
                "status": "SUBMITTED",
                "count": 25,
                "deptName": "计算机学院"
            },
            {
                "scholarshipTypeName": "国家励志奖学金",
                "status": "APPROVED",
                "count": 15,
                "deptName": "计算机学院"
            }
        ],
        "total": 40
    }
}

4.4 班主任批量申请提交

接口描述: 班主任为学生批量提交申请（v2.0核心功能）

URL: POST /jcbt/scholarshipApplication/batch
权限: jcbt:scholarshipApplication:batch

请求参数:

参数名	类型	必填	说明
batchId	Long	是	批次ID
scholarshipTypeId	Long	是	奖学金类型ID
classId	Long	是	班级ID

请求体:

[
    {
        "studentCode": "2021001001",
        "studentName": "张三",
        "studentId": 1001,
        "deptId": 103,
        "deptName": "计算机学院",
        "className": "计算机2021-1班",
        "applicantId": 2001,
        "applicantName": "李老师",
        "applicationType": "RECOMMEND",
        "applicationReason": "综合成绩优秀",
        "comprehensiveScore": 95.5,
        "academicScore": 96.0,
        "moralScore": 95.0,
        "physicalScore": 94.0,
        "aestheticScore": 93.0,
        "laborScore": 94.0
    },
    {
        "studentCode": "2021001002",
        "studentName": "李四",
        "studentId": 1002,
        "deptId": 103,
        "deptName": "计算机学院",
        "className": "计算机2021-1班",
        "applicantId": 2001,
        "applicantName": "李老师",
        "applicationType": "RECOMMEND",
        "applicationReason": "学习态度端正",
        "comprehensiveScore": 92.0,
        "academicScore": 93.0,
        "moralScore": 91.0,
        "physicalScore": 92.0,
        "aestheticScore": 90.0,
        "laborScore": 93.0
    }
]

响应示例:

{
    "code": 200,
    "msg": "操作成功",
    "data": null
}

4.5 提交申请

接口描述: 将草稿状态的申请提交审核

URL: POST /jcbt/scholarshipApplication/{id}/submit
权限: jcbt:scholarshipApplication:submit

路径参数:

参数名	类型	必填	说明
id	Long	是	申请记录ID

4.6 撤回申请

接口描述: 撤回已提交的申请

URL: POST /jcbt/scholarshipApplication/{id}/withdraw
权限: jcbt:scholarshipApplication:withdraw

路径参数:

参数名	类型	必填	说明
id	Long	是	申请记录ID

请求参数:

参数名	类型	必填	说明
reason	String	否	撤回原因

4.7 获取班级名额使用情况

接口描述: 查询班级的名额分配和使用情况

URL: GET /jcbt/scholarshipApplication/quota
权限: jcbt:scholarshipApplication:quota

请求参数:

参数名	类型	必填	说明
classId	Long	是	班级ID
batchId	Long	是	批次ID

响应示例:

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "quotas": [
            {
                "scholarshipTypeId": 1,
                "scholarshipTypeName": "国家奖学金",
                "totalQuota": 3,
                "usedQuota": 1,
                "availableQuota": 2,
                "status": "ACTIVE"
            },
            {
                "scholarshipTypeId": 2,
                "scholarshipTypeName": "国家励志奖学金",
                "totalQuota": 8,
                "usedQuota": 3,
                "availableQuota": 5,
                "status": "ACTIVE"
            }
        ],
        "totalQuota": 11,
        "usedQuota": 4,
        "availableQuota": 7
    }
}

5. 数据模型

5.1 申请状态枚举

状态值	说明	描述
DRAFT	草稿	申请记录已创建但未提交
SUBMITTED	已提交	申请已提交，等待审核
REVIEWING	审核中	申请正在审核过程中
APPROVED	已通过	申请审核通过
REJECTED	已拒绝	申请审核被拒绝
WITHDRAWN	已撤回	申请人主动撤回申请

5.2 申请人类型枚举

类型值	说明	描述
STUDENT	学生申请	学生自主申请（v1.0模式）
TEACHER	教师代申请	班主任代学生申请（v2.0模式）

5.3 申请类型枚举

类型值	说明	描述
RECOMMEND	教师推荐	班主任推荐学生申请
AUTO	自动评定	系统根据成绩自动评定
DIRECT	直接指定	学院直接指定学生

5.4 材料状态枚举

状态值	说明	描述
PENDING	待上传	材料尚未上传
PARTIAL	部分上传	部分材料已上传
COMPLETE	完整上传	所有材料已上传完整

6. 错误码说明

6.1 通用错误码

错误码	说明	解决方案
400	请求参数错误	检查请求参数格式和必填项
401	认证失败	检查Token是否有效
403	权限不足	联系管理员分配相应权限
404	资源不存在	检查资源ID是否正确
500	服务器内部错误	联系技术支持

6.2 业务错误码

错误信息	说明	解决方案
"该学生在此批次中已有申请记录"	学生重复申请	检查申请记录，避免重复提交
"班级可用名额不足"	名额不够	等待名额释放或调整名额分配
"只有草稿状态的申请才能提交"	状态错误	检查申请状态
"已审核的申请不能撤回"	撤回限制	已审核申请无法撤回
"申请时间窗口未开放"	时间限制	等待申请时间窗口开放

7. 使用示例

7.1 班主任批量申请流程

// 1. 查询可申请的奖学金类型
const availableTypes = await fetch('/jcbt/scholarshipApplication/available?classId=1001&batchId=1', {
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    }
});

// 2. 检查班级名额使用情况
const quotaUsage = await fetch('/jcbt/scholarshipApplication/quota?classId=1001&batchId=1', {
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    }
});

// 3. 批量提交申请
const batchSubmit = await fetch('/jcbt/scholarshipApplication/batch?batchId=1&scholarshipTypeId=1&classId=1001', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify([
        {
            "studentCode": "2021001001",
            "studentName": "张三",
            "studentId": 1001,
            "deptId": 103,
            "deptName": "计算机学院",
            "className": "计算机2021-1班",
            "applicantId": 2001,
            "applicantName": "李老师",
            "applicationType": "RECOMMEND",
            "applicationReason": "综合成绩优秀",
            "comprehensiveScore": 95.5,
            "academicScore": 96.0
        }
    ])
});

7.2 审核申请流程

// 1. 查询待审核申请
const pendingApplications = await fetch('/jcbt/scholarshipApplication/pending?status=SUBMITTED', {
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    }
});

// 2. 批量审核
const batchApprove = await fetch('/jcbt/scholarshipApplication/approve?status=APPROVED&reviewerId=3001&reviewerName=王老师&reviewComment=审核通过', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer ' + token,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify([1, 2, 3])
});

文档维护: 技术团队
联系方式: tech@example.com
最后更新: 2025-01-01

19 KiB Raw Blame History Unescape Escape

奖学金申请管理API文档

📋 目录

1. 概述

1.1 模块介绍

1.2 主要特性

1.3 权限说明

1.4 接口基础信息

2. 基础管理接口

2.1 查询申请记录列表

2.2 获取申请记录详情

2.3 新增申请记录

2.4 修改申请记录

2.5 删除申请记录

2.6 获取可申请奖学金类型

3. 业务功能接口

3.1 查询我的申请记录

3.2 查询待审核申请

3.3 检查学生申请资格

3.4 批量审核申请

4. 辅助功能接口

4.1 导出申请记录

4.2 导入申请记录

4.3 获取申请统计数据

4.4 班主任批量申请提交

4.5 提交申请

4.6 撤回申请

4.7 获取班级名额使用情况

5. 数据模型

5.1 申请状态枚举

5.2 申请人类型枚举

5.3 申请类型枚举

5.4 材料状态枚举

6. 错误码说明

6.1 通用错误码

6.2 业务错误码

7. 使用示例

7.1 班主任批量申请流程

7.2 审核申请流程

19 KiB

Raw Blame History