317 lines
9.2 KiB
Markdown
317 lines
9.2 KiB
Markdown
# 宿舍卫生检查后端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格式化支持
|
||
|
||
**核心字段：**
|
||
```java
|
||
// 主表字段
|
||
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`
|
||
|
||
**新增接口：**
|
||
|
||
1. **新增宿舍卫生检查（包含学生评分数据）**
|
||
```java
|
||
@PostMapping("/addWithStudentScores")
|
||
public R<Void> addWithStudentScores(@Validated(AddGroup.class) @RequestBody XgDormHygieneCheckCompleteBo bo)
|
||
```
|
||
|
||
2. **修改宿舍卫生检查（包含学生评分数据）**
|
||
```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`
|
||
|
||
**新增方法：**
|
||
```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`
|
||
|
||
**实现特点：**
|
||
|
||
1. **事务管理**
|
||
- ✅ 使用 `@Transactional(rollbackFor = Exception.class)` 确保数据一致性
|
||
- ✅ 任何异常都会回滚所有操作
|
||
|
||
2. **新增逻辑 (`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. 事务处理策略
|
||
|
||
**新增操作：**
|
||
1. 开始事务
|
||
2. 插入主表记录，获取主键ID
|
||
3. 为每个学生插入评分记录，关联主表ID
|
||
4. 提交事务（成功）或回滚事务（失败）
|
||
|
||
**更新操作：**
|
||
1. 开始事务
|
||
2. 更新主表记录
|
||
3. 删除原有学生评分记录
|
||
4. 插入新的学生评分记录
|
||
5. 提交事务（成功）或回滚事务（失败）
|
||
|
||
### 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. 依赖注入
|
||
|
||
**新增依赖：**
|
||
```java
|
||
private final XgDormHygieneStudentScoreMapper studentScoreMapper;
|
||
```
|
||
|
||
**导入的类：**
|
||
```java
|
||
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;
|
||
```
|
||
|
||
## 文件清单
|
||
|
||
### 新增的文件
|
||
1. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/bo/XgDormHygieneCheckCompleteBo.java` - 完整表单类型
|
||
|
||
### 修改的文件
|
||
1. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/controller/XgDormHygieneCheckController.java` - 新增API接口
|
||
2. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/IXgDormHygieneCheckService.java` - 新增Service接口方法
|
||
3. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/service/impl/XgDormHygieneCheckServiceImpl.java` - 新增Service实现方法
|
||
|
||
### 依赖的文件（已存在）
|
||
1. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/bo/XgDormHygieneStudentScoreBo.java` - 学生评分BO
|
||
2. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/mapper/XgDormHygieneStudentScoreMapper.java` - 学生评分Mapper
|
||
3. `backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/XgDormHygieneStudentScore.java` - 学生评分实体
|
||
|
||
## API接口规范
|
||
|
||
### 新增接口：`POST /dormHygieneCheck/dormHygieneCheck/addWithStudentScores`
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应格式：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
### 更新接口：`PUT /dormHygieneCheck/dormHygieneCheck/updateWithStudentScores`
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**响应格式：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功"
|
||
}
|
||
```
|
||
|
||
## 测试验证
|
||
|
||
### 1. 单元测试建议
|
||
- 测试新增功能的数据完整性
|
||
- 测试更新功能的数据一致性
|
||
- 测试事务回滚机制
|
||
- 测试数据验证规则
|
||
|
||
### 2. 集成测试建议
|
||
- 使用前端测试脚本验证API接口
|
||
- 测试大数据量的性能表现
|
||
- 测试并发操作的数据一致性
|
||
|
||
### 3. 测试脚本
|
||
可以使用之前创建的前端测试脚本：
|
||
```bash
|
||
python test/宿舍卫生检查API测试脚本.py
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
1. **事务一致性**：确保两个表的操作在同一事务中完成
|
||
2. **数据完整性**：更新时删除原有数据，插入新数据
|
||
3. **性能优化**：考虑批量操作时的性能影响
|
||
4. **权限控制**：严格检查用户权限
|
||
5. **日志记录**：记录重要操作日志
|
||
6. **数据验证**：前端和后端都要进行数据验证
|
||
|
||
## 后续工作
|
||
|
||
### 1. 测试验证
|
||
- 运行单元测试验证功能正确性
|
||
- 进行集成测试验证完整流程
|
||
- 性能测试验证大数据量处理能力
|
||
|
||
### 2. 文档更新
|
||
- 更新API文档
|
||
- 更新数据库设计文档
|
||
- 更新业务模块文档
|
||
|
||
### 3. 部署上线
|
||
- 代码审查
|
||
- 测试环境验证
|
||
- 生产环境部署
|
||
|
||
---
|
||
|
||
**完成时间：** 2025-01-28
|
||
**开发人员：** 系统开发团队
|
||
**文档版本：** v1.0
|
||
**状态：** ✅ 后端API接口修改完成，等待测试验证 |