all-project/docs/开发文档/API/宿舍卫生检查导出API.md

宿舍卫生检查导出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"

请求示例

// 前端调用示例
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文件二进制数据流

错误响应:

{
  "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层

@SaCheckPermission("dormHygieneCheck:dormHygieneCheck:export")
@Log(title = "宿舍卫生检查", businessType = BusinessType.EXPORT)
@PostMapping("/export")
public void export(DormHygieneCheckBo bo, HttpServletResponse response) {
    List<DormHygieneCheckExportVo> list = dormHygieneCheckService.queryExportList(bo);
    ExcelUtils.exportExcel(list, "宿舍卫生检查数据", DormHygieneCheckExportVo.class, response);
}

Service层核心逻辑

• 调用Mapper层查询导出数据
• 进行字典值转换，将代码转换为可读文本
• 返回格式化后的导出数据列表

Mapper层SQL查询

• 使用LEFT JOIN联合查询宿舍卫生检查表和学生评分表
• 支持多种查询条件的灵活组合
• 使用COALESCE函数处理空值
• 按检查日期和学号排序

---

🛡️ 权限配置

权限标识

dormHygieneCheck:dormHygieneCheck:export

权限配置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: 基础导出功能

// 测试导出所有数据
const testBasicExport = async () => {
  const response = await exportDormHygieneCheck({});
  // 验证返回的是Excel文件
  assert(response.headers['content-type'].includes('spreadsheetml.sheet'));
};

测试场景2: 条件筛选导出

// 测试按条件筛选导出
const testFilteredExport = async () => {
  const queryParams = {
    checkType: "1",
    hygieneGrade: "A",
    params: {
      beginTime: "2025-01-01",
      endTime: "2025-01-31"
    }
  };
  const response = await exportDormHygieneCheck(queryParams);
  // 验证数据筛选正确
};

测试场景3: 权限验证

// 测试权限控制
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

---

该文档将根据功能更新和用户反馈持续完善