提交代码
This commit is contained in:
zlwu committed
1 parent
5e0af12650
commit
7c78b3cf29
9 files changed
+791
-11
No files matched your search
@@ -0,0 +1,289 @@
|
||||
# 宿舍卫生检查导出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<DormHygieneCheckExportVo> 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
|
||||
|
||||
---
|
||||
|
||||
*该文档将根据功能更新和用户反馈持续完善*
|
||||
Reference in new issue
Block a user