cykj/hzdyjs

0 Fork 0

Files

T

zlwu 6034b215e5 提交

2026-10-20 11:50:53 +08:00

18 KiB

Raw Blame History

学生销假管理 API 接口文档

模块概述

模块名称：Student Cancel Leave / 学生销假管理
基础路径：/studentCancelLeave/studentCancelLeave
版本：v1.0
负责人：zlwu
更新时间：2025-01-27

模块功能

学生销假管理模块负责处理学生的销假申请和审批流程，包括销假信息的录入、修改、查询和删除。该模块与学生请假管理模块紧密关联，确保销假信息在两个表之间保持同步。

核心特性：

销假信息的完整生命周期管理
与学生请假表的自动同步更新
支持销假状态跟踪和地理位置记录
提供照片上传和备注功能

权限说明

权限前缀：studentCancelLeave:studentCancelLeave:
权限列表：
- studentCancelLeave:studentCancelLeave:list - 查询销假列表
- studentCancelLeave:studentCancelLeave:query - 查询销假详情
- studentCancelLeave:studentCancelLeave:add - 新增销假
- studentCancelLeave:studentCancelLeave:edit - 编辑销假
- studentCancelLeave:studentCancelLeave:remove - 删除销假
- studentCancelLeave:studentCancelLeave:export - 导出销假数据

📊 接口概览

接口分类

基础 CRUD 接口

接口名称	HTTP 方法	路径	权限要求	功能描述
查询销假列表	GET	`/studentCancelLeave/studentCancelLeave/list`	`studentCancelLeave:studentCancelLeave:list`	分页查询销假列表
查询销假详情	GET	`/studentCancelLeave/studentCancelLeave/{id}`	`studentCancelLeave:studentCancelLeave:query`	根据 ID 查询销假详情
新增销假	POST	`/studentCancelLeave/studentCancelLeave`	`studentCancelLeave:studentCancelLeave:add`	创建新的销假记录
修改销假	PUT	`/studentCancelLeave/studentCancelLeave`	`studentCancelLeave:studentCancelLeave:edit`	更新销假信息
删除销假	DELETE	`/studentCancelLeave/studentCancelLeave/{ids}`	`studentCancelLeave:studentCancelLeave:remove`	批量删除销假记录

业务逻辑接口

接口名称	HTTP 方法	路径	权限要求	功能描述
导出销假数据	POST	`/studentCancelLeave/studentCancelLeave/export`	`studentCancelLeave:studentCancelLeave:export`	导出销假数据到Excel
根据请假ID获取销假ID	GET	`/studentCancelLeave/studentCancelLeave/getCancelLeaveId/{leaveId}`	`studentCancelLeave:studentCancelLeave:query`	根据请假ID查询对应的销假ID

通用响应格式

成功响应

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        // 响应数据
    }
}

分页响应

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        // 数据列表
    ],
    "total": 100
}

错误响应

{
    "code": 400001,
    "msg": "参数错误",
    "data": null
}

🔌 详细接口说明

1. 查询销假列表

接口路径：GET /studentCancelLeave/studentCancelLeave/list
权限标识：studentCancelLeave:studentCancelLeave:list
功能描述：分页查询学生销假列表，支持多条件筛选

请求参数

参数名	类型	必填	说明
pageNum	int	否	页码，默认1
pageSize	int	否	每页大小，默认10
studentName	string	否	学生姓名（模糊查询）
studentNo	string	否	学号
className	string	否	班级名称（模糊查询）
collegeName	string	否	学院名称（模糊查询）
leaveTypeCode	string	否	请假类型编码
approvalStatus	string	否	审批状态
cancelStatus	string	否	销假状态
startTime	date	否	开始时间
endTime	date	否	结束时间

响应数据

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        {
            "id": 1,
            "studentId": 1001,
            "studentName": "张三",
            "studentNo": "2023001001",
            "className": "计算机2023-1班",
            "collegeName": "计算机学院",
            "leaveTypeName": "事假",
            "startTime": "2025-01-20 08:00:00",
            "endTime": "2025-01-22 18:00:00",
            "leaveDuration": 3.0,
            "approvalStatus": "finish",
            "cancelStatus": "1",
            "cancelTime": "2025-01-22 16:30:00",
            "cancelLocation": "北京市朝阳区",
            "cancelRemark": "已按时返校",
            "leaveId": 2001
        }
    ],
    "total": 1
}

2. 查询销假详情

接口路径：GET /studentCancelLeave/studentCancelLeave/{id}
权限标识：studentCancelLeave:studentCancelLeave:query
功能描述：根据ID查询销假详细信息

请求参数

参数名	类型	必填	说明
id	long	是	销假ID

响应数据

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "id": 1,
        "studentId": 1001,
        "studentName": "张三",
        "studentNo": "2023001001",
        "classId": 101,
        "className": "计算机2023-1班",
        "majorId": 1,
        "majorName": "计算机科学与技术",
        "collegeId": 1,
        "collegeName": "计算机学院",
        "leaveTypeCode": "SJ",
        "leaveTypeName": "事假",
        "startTime": "2025-01-20 08:00:00",
        "endTime": "2025-01-22 18:00:00",
        "leaveDuration": 3.0,
        "isLeaveSchool": "1",
        "needCancel": "1",
        "emergencyContact": "张父",
        "emergencyPhone": "13900139000",
        "leaveReason": "家中有事需要处理",
        "leaveLocation": "北京市朝阳区",
        "attachmentOssIds": "123,456",
        "approvalStatus": "finish",
        "approvalOpinion": "同意请假",
        "approvalTime": "2025-01-19 14:30:00",
        "approvalBy": 1001,
        "approvalByName": "李老师",
        "cancelStatus": "1",
        "cancelTime": "2025-01-22 16:30:00",
        "cancelLocation": "北京市朝阳区",
        "cancelPhotoOssIds": "789,101",
        "cancelRemark": "已按时返校",
        "leaveId": 2001
    }
}

3. 新增销假

接口路径：POST /studentCancelLeave/studentCancelLeave
权限标识：studentCancelLeave:studentCancelLeave:add
功能描述：新增学生销假记录，并同步更新学生请假表的销假信息

请求参数

{
    "studentId": 1001,
    "studentName": "张三",
    "studentNo": "2023001001",
    "classId": 101,
    "className": "计算机2023-1班",
    "majorId": 1,
    "majorName": "计算机科学与技术",
    "collegeId": 1,
    "collegeName": "计算机学院",
    "leaveTypeCode": "SJ",
    "leaveTypeName": "事假",
    "startTime": "2025-01-20 08:00:00",
    "endTime": "2025-01-22 18:00:00",
    "leaveDuration": 3.0,
    "isLeaveSchool": "1",
    "needCancel": "1",
    "emergencyContact": "张父",
    "emergencyPhone": "13900139000",
    "leaveReason": "家中有事需要处理",
    "leaveLocation": "北京市朝阳区",
    "attachmentOssIds": "123,456",
    "approvalStatus": "finish",
    "approvalOpinion": "同意请假",
    "approvalTime": "2025-01-19 14:30:00",
    "approvalBy": 1001,
    "approvalByName": "李老师",
    "cancelStatus": "1",
    "cancelTime": "2025-01-22 16:30:00",
    "cancelLocation": "北京市朝阳区",
    "cancelPhotoOssIds": "789,101",
    "cancelRemark": "已按时返校",
    "leaveId": 2001
}

响应数据

{
    "code": 200,
    "msg": "新增成功",
    "data": {
        "id": 1,
        "studentName": "张三",
        "studentNo": "2023001001",
        "cancelStatus": "1",
        "cancelTime": "2025-01-22 16:30:00"
    }
}

4. 修改销假 ⭐

接口路径：PUT /studentCancelLeave/studentCancelLeave
权限标识：studentCancelLeave:studentCancelLeave:edit
功能描述：修改学生销假信息，并同步更新学生请假表中的销假相关字段

⚠️ 重要说明：此接口会自动同步更新学生请假表中的销假信息，确保数据一致性。

请求参数

{
    "id": 1,
    "cancelStatus": "1",
    "cancelTime": "2025-01-22 16:30:00",
    "cancelLocation": "北京市朝阳区",
    "cancelPhotoOssIds": "789,101",
    "cancelRemark": "已按时返校，状态良好",
    "leaveId": 2001
}

响应数据

{
    "code": 200,
    "msg": "修改成功"
}

同步更新说明

当修改销假信息时，系统会自动同步更新学生请假表中的以下字段：

字段名	说明	来源
`cancel_status`	销假状态	销假表的 `cancelStatus`
`cancel_time`	销假时间	销假表的 `cancelTime`
`cancel_location`	销假地理位置	销假表的 `cancelLocation`
`cancel_photo_oss_ids`	销假照片	销假表的 `cancelPhotoOssIds`
`cancel_remark`	销假备注	销假表的 `cancelRemark`

事务保证：使用 @Transactional 注解确保两个表的更新操作要么全部成功，要么全部回滚。

状态保护（2026-10-19）：cancelStatus 在销假流程中使用 draft、waiting、finish 等流程状态。请假单上的 0/1/2/3（未销假、已销假、逾期未销假、无需销假）传入本接口时按 draft 保存，不会写入销假单。销假单已是 waiting、back、cancel、finish、invalid、termination 时，再次保存销假内容不会覆盖该状态。审批任务创建且流程为待审核时，若业务状态仍是旧字典值或 draft，会自动对齐为 waiting。

5. 删除销假

接口路径：DELETE /studentCancelLeave/studentCancelLeave/{ids}
权限标识：studentCancelLeave:studentCancelLeave:remove
功能描述：批量删除销假记录

请求参数

参数名	类型	必填	说明
ids	string	是	销假ID列表，多个用逗号分隔

响应数据

{
    "code": 200,
    "msg": "删除成功"
}

6. 导出销假数据

接口路径：POST /studentCancelLeave/studentCancelLeave/export
权限标识：studentCancelLeave:studentCancelLeave:export
功能描述：导出销假数据到Excel文件

请求参数

参数名	类型	必填	说明
studentName	string	否	学生姓名（模糊查询）
studentNo	string	否	学号
className	string	否	班级名称（模糊查询）
collegeName	string	否	学院名称（模糊查询）
leaveTypeCode	string	否	请假类型编码
approvalStatus	string	否	审批状态
cancelStatus	string	否	销假状态
startTime	date	否	开始时间
endTime	date	否	结束时间

响应数据

返回Excel文件流，文件名格式：学生销假_yyyyMMddHHmmss.xlsx

7. 根据请假ID获取销假ID

接口路径：GET /studentCancelLeave/studentCancelLeave/getCancelLeaveId/{leaveId}
权限标识：studentCancelLeave:studentCancelLeave:query
功能描述：根据请假ID查询对应的销假ID

请求参数

参数名	类型	必填	说明
leaveId	long	是	请假ID

响应数据

{
    "code": 200,
    "msg": "查询成功",
    "data": 1
}

📋 数据字典

销假状态 (cancelStatus)

值	说明
0	未销假
1	已销假
2	逾期未销假
3	无需销假

审批状态 (approvalStatus)

值	说明
draft	草稿
waiting	待审核
finish	已完成
cancel	已撤销
invalid	已作废
back	已退回
termination	已终止

是否离校 (isLeaveSchool)

值	说明
0	否
1	是

是否需要销假 (needCancel)

值	说明
0	否
1	是

🔧 技术实现

数据同步机制

1. 新增销假同步

在 insertByBo 方法中，新增销假记录成功后，会自动更新学生请假表的销假字段：

@Transactional(rollbackFor = Exception.class)
public XgStudentCancelLeaveVo insertByBo(XgStudentCancelLeaveBo bo) {
    // 新增销假记录
    boolean flag = baseMapper.insert(add) > 0;
    if (flag) {
        // 同步更新学生请假表中的销假相关字段
        if (bo.getLeaveId() != null) {
            XgStudentLeaveBo leaveBo = new XgStudentLeaveBo();
            leaveBo.setId(bo.getLeaveId());
            leaveBo.setCancelStatus(bo.getCancelStatus());
            leaveBo.setCancelTime(bo.getCancelTime());
            leaveBo.setCancelLocation(bo.getCancelLocation());
            leaveBo.setCancelPhotoOssIds(bo.getCancelPhotoOssIds());
            leaveBo.setCancelRemark(bo.getCancelRemark());
            
            xgStudentLeaveService.updateByBo(leaveBo);
        }
    }
}

2. 修改销假同步

在 updateByBo 方法中，修改销假记录成功后，也会同步更新学生请假表：

@Transactional(rollbackFor = Exception.class)
public Boolean updateByBo(XgStudentCancelLeaveBo bo) {
    // 修改销假记录
    boolean flag = baseMapper.updateById(update) > 0;
    
    if (flag) {
        // 同步更新学生请假表中的销假相关字段
        if (bo.getLeaveId() != null) {
            XgStudentLeaveBo leaveBo = new XgStudentLeaveBo();
            leaveBo.setId(bo.getLeaveId());
            leaveBo.setCancelStatus(bo.getCancelStatus());
            leaveBo.setCancelTime(bo.getCancelTime());
            leaveBo.setCancelLocation(bo.getCancelLocation());
            leaveBo.setCancelPhotoOssIds(bo.getCancelPhotoOssIds());
            leaveBo.setCancelRemark(bo.getCancelRemark());
            
            xgStudentLeaveService.updateByBo(leaveBo);
        }
    }
    
    return flag;
}

事务管理

使用 @Transactional(rollbackFor = Exception.class) 确保数据一致性
如果销假表更新失败或请假表更新失败，都会回滚整个事务
保证两个表的数据始终保持同步

关联关系

销假表通过 leave_id 字段关联学生请假表
一个请假记录只能对应一个销假记录
销假记录必须关联到有效的请假记录

🚀 使用示例

前端调用示例

// 修改销假信息
const updateCancelLeave = async (data) => {
  try {
    const response = await request({
      url: '/studentCancelLeave/studentCancelLeave',
      method: 'put',
      data: {
        id: 1,
        cancelStatus: '1',
        cancelTime: '2025-01-22 16:30:00',
        cancelLocation: '北京市朝阳区',
        cancelPhotoOssIds: '789,101',
        cancelRemark: '已按时返校',
        leaveId: 2001
      }
    });
    
    if (response.code === 200) {
      console.log('销假信息修改成功，已同步更新请假表');
    }
  } catch (error) {
    console.error('修改失败:', error);
  }
};

后端调用示例

// 修改销假信息
XgStudentCancelLeaveBo bo = new XgStudentCancelLeaveBo();
bo.setId(1L);
bo.setCancelStatus("1");
bo.setCancelTime(new Date());
bo.setCancelLocation("北京市朝阳区");
bo.setCancelRemark("已按时返校");
bo.setLeaveId(2001L);

boolean result = xgStudentCancelLeaveService.updateByBo(bo);
if (result) {
    log.info("销假信息修改成功，已同步更新请假表");
}

⚠️ 注意事项

1. 数据一致性

销假信息修改时会自动同步更新学生请假表
确保 leaveId 字段正确关联到有效的请假记录
使用事务保证数据一致性

2. 权限控制

所有接口都需要相应的权限标识
建议在业务层面进行权限验证
注意数据访问范围的控制

3. 性能考虑

大量数据查询时建议使用分页
导出功能可能耗时较长，建议异步处理
注意缓存策略的使用

4. 错误处理

接口调用失败时会返回相应的错误码和错误信息
建议在前端进行适当的错误处理
记录详细的错误日志便于问题排查

📝 更新日志

版本	日期	更新内容	更新人
v1.0	2025-01-27	初始版本，包含完整的CRUD接口	zlwu
v1.1	2025-01-27	新增同步更新学生请假表功能	zlwu

📋 文档维护：本文档会随着接口的更新而持续维护，如有疑问请联系开发团队。

18 KiB Raw Blame History Unescape Escape

学生销假管理 API 接口文档

模块概述

模块功能

权限说明

📊 接口概览

接口分类

基础 CRUD 接口

业务逻辑接口

通用响应格式

成功响应

分页响应

错误响应

🔌 详细接口说明

1. 查询销假列表

请求参数

响应数据

2. 查询销假详情

请求参数

响应数据

3. 新增销假

请求参数

响应数据

4. 修改销假 ⭐

请求参数

响应数据

同步更新说明

5. 删除销假

请求参数

响应数据

6. 导出销假数据

请求参数

响应数据

7. 根据请假ID获取销假ID

请求参数

响应数据

📋 数据字典

销假状态 (cancelStatus)

审批状态 (approvalStatus)

是否离校 (isLeaveSchool)

是否需要销假 (needCancel)

🔧 技术实现

数据同步机制

1. 新增销假同步

2. 修改销假同步

事务管理

关联关系

🚀 使用示例

前端调用示例

后端调用示例

⚠️ 注意事项

1. 数据一致性

2. 权限控制

3. 性能考虑

4. 错误处理

📝 更新日志

18 KiB

Raw Blame History