# 宿舍卫生检查导出API文档 ## 📋 概述 本文档描述宿舍卫生检查数据导出功能的API接口,支持导出宿舍卫生检查情况以及宿舍内学生的详细卫生情况信息。 **版本**: 1.0 **创建时间**: 2025-01-29 **最后更新**: 2025-01-29 --- ## 🚀 导出功能特性 ### 📊 导出数据内容 - **宿舍卫生检查基本信息**:检查标题、检查日期、检查员、检查类型、检查级别 - **宿舍地理位置信息**:校区、宿舍区、宿舍楼、房间号 - **宿舍整体评价**:宿舍总分、卫生等级、检查总结、整改建议 - **学生详细信息**:学号、姓名、班级、专业、学院、床位号 - **学生个人评价**:个人得分、个人评级、出勤状态、是否寝室长 - **改进建议**:评分备注、改进意见 ### 📄 导出格式 - **文件格式**: Excel (.xlsx) - **文件命名**: 宿舍卫生检查数据_YYYY-MM-DD.xlsx - **编码格式**: UTF-8 --- ## 🔗 API接口详情 ### 1. 导出宿舍卫生检查数据 #### 基本信息 - **接口地址**: `POST /dormHygieneCheck/dormHygieneCheck/export` - **请求方式**: POST - **权限要求**: `dormHygieneCheck:dormHygieneCheck:export` - **返回类型**: 文件流 (application/vnd.openxmlformats-officedocument.spreadsheetml.sheet) #### 请求参数 | 参数名 | 类型 | 是否必填 | 说明 | 示例值 | |--------|------|----------|------|--------| | checkTitle | string | 否 | 检查标题 | "宿舍卫生大检查" | | checkDate | string | 否 | 检查日期 | "2025-01-29" | | checkerId | number | 否 | 检查员ID | 1001 | | checkerName | string | 否 | 检查员姓名 | "张老师" | | checkType | string | 否 | 检查类型 | "1"(日常检查) | | checkLevel | string | 否 | 检查级别 | "2"(学院) | | roomId | number | 否 | 房间ID | 2001 | | roomName | string | 否 | 房间名称 | "101" | | buildingId | number | 否 | 宿舍楼ID | 3001 | | buildingName | string | 否 | 宿舍楼名称 | "1号楼" | | areaId | number | 否 | 宿舍区ID | 4001 | | areaName | string | 否 | 宿舍区名称 | "北区" | | campusId | number | 否 | 校区ID | 5001 | | campusName | string | 否 | 校区名称 | "主校区" | | hygieneGrade | string | 否 | 卫生等级 | "A"(优秀) | | params.beginTime | string | 否 | 开始时间 | "2025-01-01" | | params.endTime | string | 否 | 结束时间 | "2025-01-31" | #### 请求示例 ```javascript // 前端调用示例 const exportData = async () => { try { const queryParams = { checkTitle: "宿舍卫生大检查", checkDate: "2025-01-29", checkType: "1", checkLevel: "2", campusName: "主校区", hygieneGrade: "A", params: { beginTime: "2025-01-01", endTime: "2025-01-31" } }; const response = await exportDormHygieneCheck(queryParams); // 创建下载链接 const blob = new Blob([response.data], { type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' }); const url = window.URL.createObjectURL(blob); const link = document.createElement('a'); link.href = url; link.download = `宿舍卫生检查数据_${new Date().toISOString().slice(0, 10)}.xlsx`; document.body.appendChild(link); link.click(); document.body.removeChild(link); window.URL.revokeObjectURL(url); } catch (error) { console.error('导出失败:', error); } }; ``` #### 响应说明 **成功响应**: - **Content-Type**: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - **Content-Disposition**: `attachment; filename="宿舍卫生检查数据_2025-01-29.xlsx"` - **响应体**: Excel文件二进制数据流 **错误响应**: ```json { "code": 500, "msg": "导出失败", "data": null } ``` --- ## 📊 Excel表格结构 ### 表头字段说明 | 列序号 | 字段名 | 说明 | 示例值 | |--------|--------|------|--------| | 1 | 检查标题 | 本次检查的主题 | "宿舍卫生大检查" | | 2 | 检查日期 | 检查进行的日期 | "2025-01-29" | | 3 | 检查员 | 执行检查的人员 | "张老师" | | 4 | 检查类型 | 检查的类别 | "日常检查" | | 5 | 检查级别 | 检查的级别 | "学院" | | 6 | 校区 | 宿舍所在校区 | "主校区" | | 7 | 宿舍区 | 宿舍所在宿舍区 | "北区" | | 8 | 宿舍楼 | 宿舍所在楼栋 | "1号楼" | | 9 | 房间号 | 宿舍房间编号 | "101" | | 10 | 宿舍总分 | 宿舍整体得分 | 85 | | 11 | 卫生等级 | 宿舍卫生等级 | "优秀" | | 12 | 学号 | 学生学号 | "2023001001" | | 13 | 学生姓名 | 学生真实姓名 | "张三" | | 14 | 班级 | 学生所在班级 | "计算机科学与技术2023-1班" | | 15 | 专业 | 学生专业 | "计算机科学与技术" | | 16 | 学院 | 学生所属学院 | "计算机学院" | | 17 | 床位号 | 学生床位编号 | "A1" | | 18 | 个人得分 | 学生个人卫生得分 | 90 | | 19 | 出勤状态 | 检查时学生出勤情况 | "在寝" | | 20 | 个人评级 | 学生个人卫生等级 | "优秀" | | 21 | 是否寝室长 | 是否担任寝室长 | "是" | | 22 | 评分备注 | 评分相关说明 | "个人卫生良好" | | 23 | 改进意见 | 针对个人的改进建议 | "保持当前状态" | | 24 | 检查总结 | 宿舍整体检查总结 | "整体卫生状况良好" | | 25 | 整改建议 | 宿舍整体整改建议 | "继续保持" | ### 数据格式说明 #### 字典值转换 - **检查类型**: 1-日常检查, 2-专项检查, 3-突击检查, 4-复查 - **检查级别**: 1-宿管员, 2-学院, 3-学校 - **卫生等级**: A-优秀, B-良好, C-合格, D-不合格 - **出勤状态**: 1-在寝, 2-外出, 3-请假, 4-其他 - **个人评级**: A-优秀, B-良好, C-合格, D-不合格 - **是否寝室长**: 1-是, 0-否 #### 数据关联说明 - 每条记录代表一个学生在特定宿舍卫生检查中的详细信息 - 如果一个宿舍有多个学生,会产生多条记录,检查基本信息重复 - 如果一个检查记录没有学生评分数据,学生相关字段显示为空 --- ## 🔧 后端实现细节 ### Controller层 ```java @SaCheckPermission("dormHygieneCheck:dormHygieneCheck:export") @Log(title = "宿舍卫生检查", businessType = BusinessType.EXPORT) @PostMapping("/export") public void export(DormHygieneCheckBo bo, HttpServletResponse response) { List list = dormHygieneCheckService.queryExportList(bo); ExcelUtils.exportExcel(list, "宿舍卫生检查数据", DormHygieneCheckExportVo.class, response); } ``` ### Service层核心逻辑 - 调用Mapper层查询导出数据 - 进行字典值转换,将代码转换为可读文本 - 返回格式化后的导出数据列表 ### Mapper层SQL查询 - 使用LEFT JOIN联合查询宿舍卫生检查表和学生评分表 - 支持多种查询条件的灵活组合 - 使用COALESCE函数处理空值 - 按检查日期和学号排序 --- ## 🛡️ 权限配置 ### 权限标识 ``` dormHygieneCheck:dormHygieneCheck:export ``` ### 权限配置SQL ```sql -- 添加导出权限菜单 INSERT INTO sys_menu (menu_name, parent_id, order_num, menu_type, visible, status, perms, remark) VALUES ('宿舍卫生检查导出', (父菜单ID), 5, 'F', '0', '0', 'dormHygieneCheck:dormHygieneCheck:export', '宿舍卫生检查导出权限'); -- 为相关角色分配权限 INSERT INTO sys_role_menu (role_id, menu_id) VALUES (角色ID, 菜单ID); ``` --- ## 🧪 测试用例 ### 测试场景1: 基础导出功能 ```javascript // 测试导出所有数据 const testBasicExport = async () => { const response = await exportDormHygieneCheck({}); // 验证返回的是Excel文件 assert(response.headers['content-type'].includes('spreadsheetml.sheet')); }; ``` ### 测试场景2: 条件筛选导出 ```javascript // 测试按条件筛选导出 const testFilteredExport = async () => { const queryParams = { checkType: "1", hygieneGrade: "A", params: { beginTime: "2025-01-01", endTime: "2025-01-31" } }; const response = await exportDormHygieneCheck(queryParams); // 验证数据筛选正确 }; ``` ### 测试场景3: 权限验证 ```javascript // 测试权限控制 const testPermission = async () => { // 使用无权限用户访问 try { await exportDormHygieneCheck({}); assert(false, '应该抛出权限错误'); } catch (error) { assert(error.response.status === 403); } }; ``` --- ## 📝 使用说明 ### 前端集成步骤 1. 在API文件中导入`exportDormHygieneCheck`方法 2. 在界面中添加导出按钮,绑定导出事件 3. 调用导出API,处理文件下载 4. 添加相应的错误处理和用户提示 ### 注意事项 - 导出功能需要相应的权限才能使用 - 大量数据导出时建议添加加载提示 - 建议在服务器端设置合理的数据量限制 - 导出的Excel文件包含敏感学生信息,需要妥善保管 ### 性能优化建议 - 对于大量数据,考虑分页导出或异步导出 - 在数据库层面优化联合查询性能 - 考虑使用缓存机制减少重复查询 --- ## 📞 联系信息 **开发团队**: 校园管理系统开发组 **技术支持**: 系统管理员 **文档维护**: 2025-01-29 --- *该文档将根据功能更新和用户反馈持续完善*