# 学生销假管理 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 |

### 通用响应格式

#### 成功响应

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

#### 分页响应

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

#### 错误响应

```json
{
    "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   | 否   | 结束时间                 |

#### 响应数据

```json
{
    "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 |

#### 响应数据

```json
{
    "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`
- **功能描述**：新增学生销假记录，并同步更新学生请假表的销假信息

#### 请求参数

```json
{
    "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
}
```

#### 响应数据

```json
{
    "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`
- **功能描述**：修改学生销假信息，并同步更新学生请假表中的销假相关字段

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

#### 请求参数

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

#### 响应数据

```json
{
    "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列表，多个用逗号分隔 |

#### 响应数据

```json
{
    "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 |

#### 响应数据

```json
{
    "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` 方法中，新增销假记录成功后，会自动更新学生请假表的销假字段：

```java
@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` 方法中，修改销假记录成功后，也会同步更新学生请假表：

```java
@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` 字段关联学生请假表
- 一个请假记录只能对应一个销假记录
- 销假记录必须关联到有效的请假记录

---

## 🚀 使用示例

### 前端调用示例

```javascript
// 修改销假信息
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);
  }
};
```

### 后端调用示例

```java
// 修改销假信息
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   |

---

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