宿舍卫生检查后端API接口修改完成报告

任务概述

根据前端API接口的同步需求，需要修改后端Controller中的 updateDormHygieneCheck 和 addDormHygieneCheck 对应的API函数，使其支持同时操作主表和子表数据。

完成情况

✅ 已完成的工作

1. 新增完整表单类型 (`XgDormHygieneCheckCompleteBo`)

文件位置： backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/bo/XgDormHygieneCheckCompleteBo.java

功能特点：

✅ 包含主表所有字段（宿舍卫生检查信息）
✅ 包含学生评分数据列表 (List<XgDormHygieneStudentScoreBo>)
✅ 完整的数据验证注解
✅ 基础字段支持（createBy、createTime、updateBy、updateTime）
✅ JSON格式化支持

核心字段：

// 主表字段
private Long id;
private String checkTitle;
private Date checkDate;
private Long checkerId;
private String checkerName;
// ... 其他主表字段

// 学生评分数据
@Valid
@NotEmpty(message = "学生评分数据不能为空")
private List<XgDormHygieneStudentScoreBo> studentScores;

2. Controller层API接口 (`XgDormHygieneCheckController`)

文件位置： backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/controller/XgDormHygieneCheckController.java

新增接口：

新增宿舍卫生检查（包含学生评分数据）
```
@PostMapping("/addWithStudentScores")
public R<Void> addWithStudentScores(@Validated(AddGroup.class) @RequestBody XgDormHygieneCheckCompleteBo bo)
```
1. 修改宿舍卫生检查（包含学生评分数据） java @PutMapping("/updateWithStudentScores") public R<Void> updateWithStudentScores(@Validated(EditGroup.class) @RequestBody XgDormHygieneCheckCompleteBo bo)

接口特点：

✅ 完整的权限控制 (@SaCheckPermission)
✅ 操作日志记录 (@Log)
✅ 防重复提交 (@RepeatSubmit)
✅ 数据验证 (@Validated)
✅ 统一响应格式 (R<Void>)

3. Service接口层 (`IXgDormHygieneCheckService`)

文件位置： backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/IXgDormHygieneCheckService.java

新增方法：

/**
 * 新增宿舍卫生检查（包含学生评分数据）
 */
Boolean insertWithStudentScores(XgDormHygieneCheckCompleteBo bo);

/**
 * 修改宿舍卫生检查（包含学生评分数据）
 */
Boolean updateWithStudentScores(XgDormHygieneCheckCompleteBo bo);

4. Service实现层 (`XgDormHygieneCheckServiceImpl`)

文件位置： backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/impl/XgDormHygieneCheckServiceImpl.java

实现特点：

事务管理
- ✅ 使用 @Transactional(rollbackFor = Exception.class) 确保数据一致性
- ✅ 任何异常都会回滚所有操作
新增逻辑 (insertWithStudentScores) ```java // 1. 转换并保存主表数据 XgDormHygieneCheck add = MapstructUtils.convert(bo, XgDormHygieneCheck.class); boolean flag = baseMapper.insert(add) > 0;

// 2. 保存学生评分数据 for (XgDormHygieneStudentScoreBo studentScoreBo : bo.getStudentScores()) {

   XgDormHygieneStudentScore studentScore = MapstructUtils.convert(studentScoreBo, XgDormHygieneStudentScore.class);
   studentScore.setHygieneCheckId(add.getId());
   studentScoreMapper.insert(studentScore);

}


3. **更新逻辑 (`updateWithStudentScores`)**
   ```java
   // 1. 更新主表数据
   XgDormHygieneCheck update = MapstructUtils.convert(bo, XgDormHygieneCheck.class);
   boolean flag = baseMapper.updateById(update) > 0;
   
   // 2. 删除原有学生评分记录
   LambdaQueryWrapper<XgDormHygieneStudentScore> deleteWrapper = Wrappers.lambdaQuery();
   deleteWrapper.eq(XgDormHygieneStudentScore::getHygieneCheckId, bo.getId());
   studentScoreMapper.delete(deleteWrapper);
   
   // 3. 插入新的学生评分记录
   for (XgDormHygieneStudentScoreBo studentScoreBo : bo.getStudentScores()) {
       XgDormHygieneStudentScore studentScore = MapstructUtils.convert(studentScoreBo, XgDormHygieneStudentScore.class);
       studentScore.setHygieneCheckId(bo.getId());
       studentScoreMapper.insert(studentScore);
   }

技术实现细节

1. 数据流程

前端请求 → Controller → Service → Mapper → 数据库

2. 事务处理策略

新增操作：

开始事务
插入主表记录，获取主键ID
为每个学生插入评分记录，关联主表ID
提交事务（成功）或回滚事务（失败）

更新操作：

开始事务
更新主表记录
删除原有学生评分记录
插入新的学生评分记录
提交事务（成功）或回滚事务（失败）

3. 数据验证规则

主表验证：

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

学生评分表验证：

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

4. 依赖注入

新增依赖：

private final XgDormHygieneStudentScoreMapper studentScoreMapper;

导入的类：

import org.dromara.xg.domain.bo.XgDormHygieneCheckCompleteBo;
import org.dromara.xg.domain.bo.XgDormHygieneStudentScoreBo;
import org.dromara.xg.domain.XgDormHygieneStudentScore;
import org.dromara.xg.mapper.XgDormHygieneStudentScoreMapper;
import org.springframework.transaction.annotation.Transactional;

文件清单

新增的文件

backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/bo/XgDormHygieneCheckCompleteBo.java - 完整表单类型

修改的文件

backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/controller/XgDormHygieneCheckController.java - 新增API接口
backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/IXgDormHygieneCheckService.java - 新增Service接口方法
backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/impl/XgDormHygieneCheckServiceImpl.java - 新增Service实现方法

依赖的文件（已存在）

backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/bo/XgDormHygieneStudentScoreBo.java - 学生评分BO
backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/mapper/XgDormHygieneStudentScoreMapper.java - 学生评分Mapper
backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/XgDormHygieneStudentScore.java - 学生评分实体

API接口规范

新增接口：`POST /dormHygieneCheck/dormHygieneCheck/addWithStudentScores`

请求参数：

{
  "checkTitle": "2025年1月宿舍卫生检查",
  "checkDate": "2025-01-28 10:00:00",
  "checkerId": 1,
  "checkerName": "张三",
  "roomId": 1,
  "roomCode": "A101",
  "roomName": "A栋101室",
  "buildingId": 1,
  "buildingName": "A栋",
  "studentScores": [
    {
      "studentId": 1,
      "studentNo": "2021001",
      "studentName": "李四",
      "studentScore": 85.0,
      "attendanceStatus": "1",
      "studentGrade": "B"
    }
  ]
}

响应格式：

{
  "code": 200,
  "msg": "操作成功"
}

更新接口：`PUT /dormHygieneCheck/dormHygieneCheck/updateWithStudentScores`

请求参数：

{
  "id": 1,
  "checkTitle": "2025年1月宿舍卫生检查（更新）",
  "checkDate": "2025-01-28 10:00:00",
  "checkerId": 1,
  "checkerName": "张三",
  "roomId": 1,
  "roomCode": "A101",
  "roomName": "A栋101室",
  "buildingId": 1,
  "buildingName": "A栋",
  "studentScores": [
    {
      "studentId": 1,
      "studentNo": "2021001",
      "studentName": "李四",
      "studentScore": 90.0,
      "attendanceStatus": "1",
      "studentGrade": "A"
    }
  ]
}

响应格式：

{
  "code": 200,
  "msg": "操作成功"
}

测试验证

1. 单元测试建议

测试新增功能的数据完整性
测试更新功能的数据一致性
测试事务回滚机制
测试数据验证规则

2. 集成测试建议

使用前端测试脚本验证API接口
测试大数据量的性能表现
测试并发操作的数据一致性

3. 测试脚本

可以使用之前创建的前端测试脚本：

python test/宿舍卫生检查API测试脚本.py

注意事项

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

后续工作

1. 测试验证

运行单元测试验证功能正确性
进行集成测试验证完整流程
性能测试验证大数据量处理能力

2. 文档更新

更新API文档
更新数据库设计文档
更新业务模块文档

3. 部署上线

代码审查
测试环境验证
生产环境部署

完成时间： 2025-01-28
开发人员： 系统开发团队
文档版本： v1.0
状态： ✅ 后端API接口修改完成，等待测试验证

宿舍卫生检查后端API接口修改完成报告.md 9.2 KB Pysyvä linkki Historia Raaka