宿舍申请管理 API 接口文档

模块概述

模块名称: 宿舍申请管理 / Dormitory Application Management

基础路径: /dormApplication/dormApplication

版本: v1.0

负责人: zlwu

更新时间: 2025-01-15

模块功能

宿舍申请管理模块主要处理学生的宿舍调宿和退宿申请，包括：

学生宿舍调宿申请（更换床位）
学生宿舍退宿申请（释放床位）
工作流审批流程
宿舍管理员权限控制
学生信息自动更新

权限说明

权限前缀: dormApplication:dormApplication:
权限列表:
- dormApplication:dormApplication:list - 查询权限
- dormApplication:dormApplication:add - 新增权限
- dormApplication:dormApplication:edit - 编辑权限
- dormApplication:dormApplication:remove - 删除权限
- dormApplication:dormApplication:query - 查看详情权限
- dormApplication:dormApplication:export - 导出权限

📊 接口概览

接口分类

基础 CRUD 接口

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

业务逻辑接口

接口名称	HTTP 方法	路径	权限要求	功能描述
获取学生选择器	GET	`/dormApplication/dormApplication/studentOptions`	`dormApplication:dormApplication:list`	获取学生选择器选项
获取学院审批人	GET	`/dormApplication/dormApplication/getCollegeApprovers`	`dormApplication:dormApplication:list`	获取二级学院审批人列表
获取学工处审批人	GET	`/dormApplication/dormApplication/getStudentAffairsApprovers`	`dormApplication:dormApplication:list`	获取学工处审批人列表

通用响应格式

成功响应

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

分页响应

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

错误响应

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

🔍 接口详细说明

1. 查询宿舍申请列表

接口信息

接口地址: GET /dormApplication/dormApplication/list

接口描述: 分页查询宿舍申请列表，支持多条件筛选和权限过滤

权限要求: dormApplication:dormApplication:list

请求参数

参数名	类型	必填	说明	示例值
pageNum	Integer	N	页码，默认 1	1
pageSize	Integer	N	每页大小，默认 10	10
applicationName	String	N	申请名称	"张三调宿申请"
applicationType	String	N	申请类型：1-调宿，2-退宿	"1"
applicationStatus	String	N	审批状态	"draft"
studentName	String	N	学生姓名	"张三"
studentNo	String	N	学号	"20240001"
collegeName	String	N	学院名称	"计算机学院"
majorName	String	N	专业名称	"软件工程"
className	String	N	班级名称	"软工2024班"
applyTime	String	N	申请时间	"2025-01-15"

请求示例

curl -X GET "http://localhost:8080/dormApplication/dormApplication/list?pageNum=1&pageSize=10&applicationType=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        {
            "id": 1,
            "applicationName": "张三调宿申请",
            "applicationType": "1",
            "applicationStatus": "draft",
            "studentName": "张三",
            "studentNo": "20240001",
            "collegeName": "计算机学院",
            "majorName": "软件工程",
            "className": "软工2024班",
            "applyTime": "2025-01-15 10:00:00",
            "createBy": 1,
            "createTime": "2025-01-15 10:00:00"
        }
    ],
    "total": 1
}

错误码

错误码	说明	解决方案
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限
400001	参数错误	检查请求参数格式

2. 查询申请详情

接口信息

接口地址: GET /dormApplication/dormApplication/{id}

接口描述: 根据 ID 查询宿舍申请的详细信息

权限要求: dormApplication:dormApplication:query

路径参数

参数名	类型	必填	说明	示例值
id	Long	Y	申请单ID	1

请求示例

curl -X GET "http://localhost:8080/dormApplication/dormApplication/1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "id": 1,
        "applicationName": "张三调宿申请",
        "applicationType": "1",
        "applicationStatus": "draft",
        "studentId": 1001,
        "studentName": "张三",
        "studentNo": "20240001",
        "collegeId": 101,
        "collegeName": "计算机学院",
        "majorId": 201,
        "majorName": "软件工程",
        "classId": 301,
        "className": "软工2024班",
        "currentCampusId": 1,
        "currentCampusName": "主校区",
        "currentBuildingId": 11,
        "currentBuildingName": "1号楼",
        "currentRoomId": 111,
        "currentRoomNo": "101",
        "currentBedId": 1111,
        "currentBedNo": "01",
        "targetCampusId": 1,
        "targetCampusName": "主校区",
        "targetBuildingId": 12,
        "targetBuildingName": "2号楼",
        "targetRoomId": 121,
        "targetRoomNo": "201",
        "targetBedId": 1211,
        "targetBedNo": "01",
        "reasonDetail": "宿舍环境不好，希望调换",
        "applyTime": "2025-01-15 10:00:00",
        "remark": "备注信息"
    }
}

错误码

错误码	说明	解决方案
404001	数据不存在	检查 ID 是否正确
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

3. 新增宿舍申请

接口信息

接口地址: POST /dormApplication/dormApplication

接口描述: 创建新的宿舍申请记录（调宿或退宿）

权限要求: dormApplication:dormApplication:add

请求参数

参数名	类型	必填	说明	示例值
applicationName	String	Y	申请名称	"张三调宿申请"
applicationType	String	Y	申请类型：1-调宿，2-退宿	"1"
studentId	Long	Y	申请学生ID	1001
studentName	String	Y	学生姓名	"张三"
studentNo	String	Y	学号	"20240001"
collegeId	Long	Y	学院ID	101
majorId	Long	Y	专业ID	201
classId	Long	Y	班级ID	301
currentCampusId	Long	N	当前校区ID（调宿必填）	1
currentBuildingId	Long	N	当前楼栋ID（调宿必填）	11
currentRoomId	Long	N	当前房间ID（调宿必填）	111
currentBedId	Long	Y	当前床位ID	1111
targetCampusId	Long	N	目标校区ID（调宿必填）	1
targetBuildingId	Long	N	目标楼栋ID（调宿必填）	12
targetRoomId	Long	N	目标房间ID（调宿必填）	121
targetBedId	Long	N	目标床位ID（调宿必填）	1211
reasonDetail	String	Y	详细原因说明	"宿舍环境不好"
applyTime	String	Y	申请时间	"2025-01-15 10:00:00"
attachmentOssIds	String	N	附件OSS ID列表	"oss1,oss2"
remark	String	N	备注信息	"备注内容"

请求体

{
    "applicationName": "张三调宿申请",
    "applicationType": "1",
    "studentId": 1001,
    "studentName": "张三",
    "studentNo": "20240001",
    "collegeId": 101,
    "majorId": 201,
    "classId": 301,
    "currentCampusId": 1,
    "currentBuildingId": 11,
    "currentRoomId": 111,
    "currentBedId": 1111,
    "targetCampusId": 1,
    "targetBuildingId": 12,
    "targetRoomId": 121,
    "targetBedId": 1211,
    "reasonDetail": "宿舍环境不好，希望调换到更好的宿舍",
    "applyTime": "2025-01-15 10:00:00",
    "remark": "备注信息"
}

请求示例

curl -X POST "http://localhost:8080/dormApplication/dormApplication" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "applicationName": "张三调宿申请",
    "applicationType": "1",
    "studentId": 1001,
    "studentName": "张三",
    "studentNo": "20240001",
    "collegeId": 101,
    "majorId": 201,
    "classId": 301,
    "currentCampusId": 1,
    "currentBuildingId": 11,
    "currentRoomId": 111,
    "currentBedId": 1111,
    "targetCampusId": 1,
    "targetBuildingId": 12,
    "targetRoomId": 121,
    "targetBedId": 1211,
    "reasonDetail": "宿舍环境不好，希望调换到更好的宿舍",
    "applyTime": "2025-01-15 10:00:00"
  }'

响应示例

{
    "code": 200,
    "msg": "新增成功",
    "data": {
        "id": 3
    }
}

错误码

错误码	说明	解决方案
400001	参数错误	检查必填参数是否缺失
400002	数据已存在	检查唯一字段是否重复
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

参数验证规则

applicationName: 长度 2-100 字符，不能为空
applicationType: 只能为 "1" 或 "2"
studentId: 必须为正整数
studentName: 长度 2-50 字符，不能为空
studentNo: 长度 6-20 字符，不能为空
reasonDetail: 长度 5-500 字符，不能为空
applyTime: 必须为有效的时间格式

4. 修改宿舍申请

接口信息

接口地址: PUT /dormApplication/dormApplication

接口描述: 更新宿舍申请信息（仅限草稿状态的申请）

权限要求: dormApplication:dormApplication:edit

请求参数

参数名	类型	必填	说明	示例值
id	Long	Y	申请单ID	1
applicationName	String	Y	申请名称	"张三调宿申请"
applicationType	String	Y	申请类型：1-调宿，2-退宿	"1"
studentId	Long	Y	申请学生ID	1001
reasonDetail	String	Y	详细原因说明	"宿舍环境不好"
targetBedId	Long	N	目标床位ID（调宿时必填）	1211
remark	String	N	备注信息	"修改后的备注"

请求体

{
    "id": 1,
    "applicationName": "张三调宿申请（修改）",
    "applicationType": "1",
    "studentId": 1001,
    "reasonDetail": "宿舍环境不好，希望调换到更好的宿舍（修改原因）",
    "targetBedId": 1211,
    "remark": "修改后的备注"
}

请求示例

curl -X PUT "http://localhost:8080/dormApplication/dormApplication" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "applicationName": "张三调宿申请（修改）",
    "reasonDetail": "宿舍环境不好，希望调换到更好的宿舍（修改原因）",
    "targetBedId": 1211
  }'

响应示例

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

错误码

错误码	说明	解决方案
404001	数据不存在	检查 ID 是否正确
400001	参数错误	检查参数格式是否正确
403002	状态不允许	只能修改草稿状态的申请
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

5. 删除宿舍申请

接口信息

接口地址: DELETE /dormApplication/dormApplication/{ids}

接口描述: 批量删除宿舍申请（仅限草稿状态的申请）

权限要求: dormApplication:dormApplication:remove

路径参数

参数名	类型	必填	说明	示例值
ids	String	Y	申请单ID 列表，多个用逗号分隔	"1,2,3"

请求示例

curl -X DELETE "http://localhost:8080/dormApplication/dormApplication/1,2,3" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

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

错误码

错误码	说明	解决方案
400001	参数错误	检查 ID 格式是否正确
403003	状态不允许	只能删除草稿状态的申请
401001	未登录	请先登录获取 token
403001	无权限	请联系管理员分配权限

🎯 业务逻辑接口

1. 获取学生选择器选项

接口信息

接口地址: GET /dormApplication/dormApplication/studentOptions

接口描述: 获取学生选择器选项列表，支持按学号、姓名检索

权限要求: dormApplication:dormApplication:list

请求参数

参数名	类型	必填	说明	示例值
pageNum	Integer	N	页码，默认 1	1
pageSize	Integer	N	每页大小，默认 10	10
studentName	String	N	学生姓名	"张三"
studentNo	String	N	学号	"20240001"

请求示例

curl -X GET "http://localhost:8080/dormApplication/dormApplication/studentOptions?pageNum=1&pageSize=10&studentName=张三" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        {
            "studentId": 1001,
            "studentName": "张三",
            "studentNo": "20240001",
            "collegeName": "计算机学院",
            "majorName": "软件工程",
            "className": "软工2024班"
        }
    ],
    "total": 1
}

2. 获取二级学院审批人列表

接口信息

接口地址: GET /dormApplication/dormApplication/getCollegeApprovers

接口描述: 根据学院ID获取二级学院审批人列表

权限要求: dormApplication:dormApplication:list

请求参数

参数名	类型	必填	说明	示例值
collegeId	Long	Y	学院ID	101

请求示例

curl -X GET "http://localhost:8080/dormApplication/dormApplication/getCollegeApprovers?collegeId=101" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "userId": 201,
            "userName": "lisi",
            "nickName": "李四",
            "deptId": 101
        }
    ]
}

3. 获取学工处审批人列表

接口信息

接口地址: GET /dormApplication/dormApplication/getStudentAffairsApprovers

接口描述: 获取学工处审批人列表

权限要求: dormApplication:dormApplication:list

请求示例

curl -X GET "http://localhost:8080/dormApplication/dormApplication/getStudentAffairsApprovers" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

响应示例

{
    "code": 200,
    "msg": "查询成功",
    "data": [
        {
            "userId": 301,
            "userName": "wangwu",
            "nickName": "王五",
            "deptId": 999
        }
    ]
}

📋 数据字典

申请类型枚举

值	名称	说明
1	调宿申请	学生申请更换床位
2	退宿申请	学生申请退宿

申请状态枚举

值	名称	说明
draft	草稿	申请已创建，待提交
waiting	待审核	申请已提交，等待审批
finish	已完成	审批通过，操作已执行
cancel	已撤销	申请被撤销
back	已退回	审批退回
invalid	已作废	申请已作废
termination	已终止	流程已终止

学生状态枚举

值	名称	说明
1	在校生	正常在校学生
2	休学	学生休学状态
3	退学	学生退学状态
4	毕业	学生已毕业

🔄 版本历史

v1.0.0 - 2025-01-15

✅ 初始版本发布
✅ 完成宿舍申请基础 CRUD 接口
✅ 完成学生选择器接口
✅ 完成审批人获取接口
✅ 集成工作流审批流程
✅ 实现调宿和退宿业务逻辑

📖 相关文档

数据库设计：数据库设计文档
业务需求：业务需求文档
工作流文档：工作流开发规范
退宿逻辑说明：退宿逻辑详细说明
API基础规范：API文档基础规范

📞 联系方式

开发团队：校园管理系统开发团队

负责人：zlwu

邮箱：dev@hzdyjs.edu.cn

文档维护：实时更新，如有问题请及时反馈

📌 重要提醒：

所有接口都需要先登录获取 token
请求头必须包含 Authorization: Bearer {token}
参数验证失败会返回详细的错误信息
生产环境请使用 HTTPS 协议
申请状态为非草稿状态时，只能查看不能修改或删除
退宿和调宿操作通过工作流审批完成后自动执行，无需手动调用业务接口

宿舍申请管理API.md 19 KB Permalink Histórico Raw

宿舍申请管理 API 接口文档

模块概述

模块功能

权限说明

📊 接口概览

接口分类

基础 CRUD 接口

业务逻辑接口

通用响应格式

成功响应

分页响应

错误响应

🔍 接口详细说明

1. 查询宿舍申请列表

接口信息

请求参数

请求示例

响应示例

错误码

2. 查询申请详情

接口信息

路径参数

请求示例

响应示例

错误码

3. 新增宿舍申请

接口信息

请求参数

请求体

请求示例

响应示例

错误码

参数验证规则

4. 修改宿舍申请

接口信息

请求参数

请求体

请求示例

响应示例

错误码

5. 删除宿舍申请

接口信息

路径参数

请求示例

响应示例

错误码

🎯 业务逻辑接口

1. 获取学生选择器选项

接口信息

请求参数

请求示例

响应示例

2. 获取二级学院审批人列表

接口信息

请求参数

请求示例

响应示例

3. 获取学工处审批人列表

接口信息

请求示例

响应示例

📋 数据字典

申请类型枚举

申请状态枚举

学生状态枚举

🔄 版本历史

v1.0.0 - 2025-01-15

📖 相关文档

📞 联系方式

宿舍申请管理API.md 19 KB

Permalink Histórico Raw