宿舍卫生检查管理API文档

概述

宿舍卫生检查管理模块提供完整的宿舍卫生检查功能，包括检查记录管理和学生个人评分管理。该模块支持同时操作两个数据表：xg_dorm_hygiene_check（主表）和 xg_dorm_hygiene_student_score（学生评分表）。

数据库表结构

主表：xg_dorm_hygiene_check

存储宿舍卫生检查的基本信息
包含检查标题、日期、检查员、宿舍信息、总分、等级等

子表：xg_dorm_hygiene_student_score

存储每个学生的个人评分信息
关联主表，包含学生信息、个人得分、出勤状态、评级等

API接口规范

1. 新增宿舍卫生检查（包含学生评分）

接口地址： POST /dormHygieneCheck/dormHygieneCheck/addWithStudentScores

请求参数：

{
  "checkTitle": "2025年1月宿舍卫生检查",
  "checkDate": "2025-01-28 09:00:00",
  "checkerId": 1,
  "checkerName": "张检查员",
  "checkType": "1",
  "checkLevel": "1",
  "roomId": 1,
  "roomCode": "A101",
  "roomName": "A栋101室",
  "buildingId": 1,
  "buildingName": "A栋宿舍楼",
  "areaId": 1,
  "areaName": "东区",
  "campusId": 1,
  "campusName": "主校区",
  "totalScore": 85.5,
  "hygieneGrade": "B",
  "attachmentIds": "oss1,oss2,oss3",
  "checkSummary": "宿舍整体卫生良好",
  "improvementSuggestions": "建议加强个人物品整理",
  "checkRemarks": "检查顺利完成",
  "studentData": [
    {
      "studentId": 1,
      "studentName": "张三",
      "studentNo": "2021001",
      "className": "计算机科学1班",
      "majorName": "计算机科学与技术",
      "collegeName": "信息工程学院",
      "bedId": 1,
      "bedCode": "A101-1",
      "studentScore": 85.5,
      "attendanceStatus": "1",
      "studentGrade": "B",
      "isResponsiblePerson": 0,
      "scoreRemarks": "个人卫生良好",
      "improvementNotes": "建议整理桌面物品"
    }
  ]
}

实现要求：

事务处理：使用数据库事务确保两个表的操作原子性
主表插入：插入宿舍卫生检查记录，获取生成的主键ID
子表插入：为每个学生插入评分记录，关联主表ID
数据验证：验证必填字段、数据格式、分数范围等
权限控制：检查用户权限，记录操作日志

响应格式：

{
  "code": 200,
  "msg": "新增成功",
  "data": {
    "id": 1,
    "checkTitle": "2025年1月宿舍卫生检查",
    "studentCount": 4
  }
}

2. 更新宿舍卫生检查（包含学生评分）

接口地址： PUT /dormHygieneCheck/dormHygieneCheck/updateWithStudentScores

请求参数： 与新增接口相同，但必须包含 id 字段

实现要求：

事务处理：使用数据库事务确保操作的原子性
主表更新：更新宿舍卫生检查记录
子表处理：
- 将原有学生评分记录的 deleted 字段设置为 1（逻辑删除）
- 插入新的学生评分记录
数据验证：验证记录存在性、权限等
历史保留：保留历史数据，便于追溯

响应格式：

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": 1,
    "checkTitle": "2025年1月宿舍卫生检查（更新）",
    "studentCount": 4,
    "updatedTime": "2025-01-28 10:30:00"
  }
}

后端实现示例

Controller层

@RestController
@RequestMapping("/dormHygieneCheck/dormHygieneCheck")
public class DormHygieneCheckController {
    
    @Autowired
    private DormHygieneCheckService dormHygieneCheckService;
    
    /**
     * 新增宿舍卫生检查（包含学生评分）
     */
    @PostMapping("/addWithStudentScores")
    @SaCheckPermission("dormHygieneCheck:dormHygieneCheck:add")
    public R<Void> addWithStudentScores(@RequestBody @Valid DormHygieneCheckCompleteForm form) {
        dormHygieneCheckService.addWithStudentScores(form);
        return R.ok();
    }
    
    /**
     * 更新宿舍卫生检查（包含学生评分）
     */
    @PutMapping("/updateWithStudentScores")
    @SaCheckPermission("dormHygieneCheck:dormHygieneCheck:edit")
    public R<Void> updateWithStudentScores(@RequestBody @Valid DormHygieneCheckCompleteForm form) {
        dormHygieneCheckService.updateWithStudentScores(form);
        return R.ok();
    }
}

Service层

@Service
public class DormHygieneCheckServiceImpl implements DormHygieneCheckService {
    
    @Autowired
    private DormHygieneCheckMapper dormHygieneCheckMapper;
    
    @Autowired
    private DormHygieneStudentScoreMapper studentScoreMapper;
    
    /**
     * 新增宿舍卫生检查（包含学生评分）
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void addWithStudentScores(DormHygieneCheckCompleteForm form) {
        // 1. 验证数据
        validateFormData(form);
        
        // 2. 插入主表
        DormHygieneCheck entity = convertToEntity(form);
        dormHygieneCheckMapper.insert(entity);
        
        // 3. 插入学生评分数据
        if (form.getStudentData() != null && !form.getStudentData().isEmpty()) {
            for (DormHygieneStudentScoreForm studentForm : form.getStudentData()) {
                DormHygieneStudentScore studentEntity = convertToStudentEntity(studentForm);
                studentEntity.setHygieneCheckId(entity.getId());
                studentScoreMapper.insert(studentEntity);
            }
        }
    }
    
    /**
     * 更新宿舍卫生检查（包含学生评分）
     */
    @Override
    @Transactional(rollbackFor = Exception.class)
    public void updateWithStudentScores(DormHygieneCheckCompleteForm form) {
        // 1. 验证数据
        validateFormData(form);
        validateRecordExists(form.getId());
        
        // 2. 更新主表
        DormHygieneCheck entity = convertToEntity(form);
        dormHygieneCheckMapper.updateById(entity);
        
        // 3. 逻辑删除原有学生评分记录
        studentScoreMapper.logicDeleteByCheckId(entity.getId());
        
        // 4. 插入新的学生评分数据
        if (form.getStudentData() != null && !form.getStudentData().isEmpty()) {
            for (DormHygieneStudentScoreForm studentForm : form.getStudentData()) {
                DormHygieneStudentScore studentEntity = convertToStudentEntity(studentForm);
                studentEntity.setHygieneCheckId(entity.getId());
                studentScoreMapper.insert(studentEntity);
            }
        }
    }
    
    /**
     * 验证表单数据
     */
    private void validateFormData(DormHygieneCheckCompleteForm form) {
        // 验证必填字段
        if (StringUtils.isBlank(form.getCheckTitle())) {
            throw new ServiceException("检查标题不能为空");
        }
        if (form.getRoomId() == null) {
            throw new ServiceException("房间ID不能为空");
        }
        
        // 验证分数范围
        if (form.getTotalScore() != null) {
            if (form.getTotalScore() < 0 || form.getTotalScore() > 100) {
                throw new ServiceException("宿舍总分必须在0-100分之间");
            }
        }
        
        // 验证学生数据
        if (form.getStudentData() != null) {
            for (DormHygieneStudentScoreForm student : form.getStudentData()) {
                if (student.getStudentScore() != null) {
                    if (student.getStudentScore() < 0 || student.getStudentScore() > 100) {
                        throw new ServiceException("学生个人得分必须在0-100分之间");
                    }
                }
            }
        }
    }
    
    /**
     * 验证记录是否存在
     */
    private void validateRecordExists(Long id) {
        DormHygieneCheck existing = dormHygieneCheckMapper.selectById(id);
        if (existing == null) {
            throw new ServiceException("记录不存在");
        }
    }
}

Mapper层

@Mapper
public interface DormHygieneStudentScoreMapper extends BaseMapperPlus<DormHygieneStudentScore, DormHygieneStudentScoreVO> {
    
    /**
     * 根据检查ID逻辑删除学生评分记录
     */
    @Update("UPDATE xg_dorm_hygiene_student_score SET deleted = 1, update_time = NOW(), update_by = #{updateBy} WHERE hygiene_check_id = #{checkId} AND deleted = 0")
    int logicDeleteByCheckId(@Param("checkId") Long checkId, @Param("updateBy") Long updateBy);
    
    /**
     * 根据检查ID查询学生评分列表
     */
    @Select("SELECT * FROM xg_dorm_hygiene_student_score WHERE hygiene_check_id = #{checkId} AND deleted = 0")
    List<DormHygieneStudentScore> selectByCheckId(@Param("checkId") Long checkId);
}

数据验证规则

主表验证

checkTitle: 必填，长度1-200字符
checkDate: 必填，日期时间格式
checkerId: 必填，关联用户表
roomId: 必填，关联房间表
totalScore: 可选，0-100分
hygieneGrade: 可选，A/B/C/D

学生评分表验证

studentId: 必填，关联学生表
studentScore: 可选，0-100分
attendanceStatus: 必填，1/2/3/4
studentGrade: 可选，A/B/C/D

错误处理

常见错误码

400: 参数验证失败
401: 权限不足
404: 记录不存在
500: 服务器内部错误

错误响应格式

{
  "code": 400,
  "msg": "检查标题不能为空",
  "data": null
}

注意事项

事务一致性：确保两个表的操作在同一事务中完成
数据完整性：更新时保留历史数据，便于追溯
性能优化：批量操作时考虑性能影响
权限控制：严格检查用户权限
日志记录：记录重要操作日志
数据验证：前端和后端都要进行数据验证

测试用例

新增测试

正常新增：提供完整有效数据
数据验证：测试必填字段、格式验证
权限测试：测试不同用户权限
异常测试：测试网络异常、数据库异常

更新测试

正常更新：更新现有记录
记录不存在：更新不存在的记录
学生数据变更：测试学生数据的增删改
历史数据：验证历史数据保留

文档版本： v1.0
创建时间： 2025-01-28
维护人员： 系统开发团队

宿舍卫生检查管理API.md 10 KB История Исходник