190 lines
6.4 KiB
Markdown
190 lines
6.4 KiB
Markdown
# 宿舍卫生检查API接口同步完成报告
|
||
|
||
## 任务概述
|
||
|
||
根据用户要求，需要同步修改主页面的 `updateDormHygieneCheck` 和 `addDormHygieneCheck` 对应的后台API接口，使其支持同时操作主表和子表数据。
|
||
|
||
## 完成情况
|
||
|
||
### ✅ 已完成的工作
|
||
|
||
#### 1. 前端API接口层 (`web/src/api/xg/xgss/dormHygieneCheck/dormHygieneCheck/index.ts`)
|
||
|
||
**新增接口：**
|
||
- ✅ `addDormHygieneCheck` - 新增宿舍卫生检查（包含学生评分数据）
|
||
- 接口地址：`POST /dormHygieneCheck/dormHygieneCheck/addWithStudentScores`
|
||
- 参数类型：`DormHygieneCheckCompleteForm`
|
||
- 功能：同时向主表和子表插入数据
|
||
|
||
- ✅ `updateDormHygieneCheck` - 更新宿舍卫生检查（包含学生评分数据）
|
||
- 接口地址：`PUT /dormHygieneCheck/dormHygieneCheck/updateWithStudentScores`
|
||
- 参数类型：`DormHygieneCheckCompleteForm`
|
||
- 功能：更新主表，重新插入子表数据（保留历史）
|
||
|
||
#### 2. 类型定义层 (`web/src/api/xg/xgss/dormHygieneCheck/dormHygieneCheck/types.ts`)
|
||
|
||
**新增类型：**
|
||
- ✅ `DormHygieneStudentScoreVO` - 学生评分数据展示类型
|
||
- ✅ `DormHygieneStudentScoreForm` - 学生评分数据表单类型
|
||
- ✅ `DormHygieneStudentScoreQuery` - 学生评分查询类型
|
||
- ✅ `DormHygieneCheckCompleteForm` - 完整的宿舍卫生检查表单类型（包含学生评分数据）
|
||
|
||
#### 3. 前端组件层
|
||
|
||
**Dialog组件 (`DormHygieneCheckDialog.vue`)：**
|
||
- ✅ 更新 `submitForm` 方法，支持提交完整的学生评分数据
|
||
- ✅ 优化数据格式转换，将前端数据格式转换为API接口要求的格式
|
||
- ✅ 增强错误处理和用户提示
|
||
|
||
**主页面 (`index.vue`)：**
|
||
- ✅ `handleDialogSubmit` 方法已正确调用新的API接口
|
||
- ✅ 参数类型已更新为 `DormHygieneCheckCompleteForm`
|
||
- ✅ 导入语句已正确配置
|
||
|
||
#### 4. 后端API设计规范
|
||
|
||
**新增接口设计：**
|
||
- ✅ 新增接口：`POST /dormHygieneCheck/dormHygieneCheck/addWithStudentScores`
|
||
- ✅ 更新接口：`PUT /dormHygieneCheck/dormHygieneCheck/updateWithStudentScores`
|
||
|
||
**实现要求：**
|
||
- 🔄 使用数据库事务确保两个表的操作原子性
|
||
- 📝 主表操作：插入/更新宿舍卫生检查记录
|
||
- 👥 子表操作：插入学生评分记录，关联主表ID
|
||
- 🗑️ 更新时：逻辑删除原有学生评分记录，插入新记录
|
||
- ✅ 完整的数据验证和权限控制
|
||
|
||
#### 5. 文档和测试
|
||
|
||
**API文档：**
|
||
- ✅ `docs/开发文档/API/宿舍卫生检查管理API.md` - 完整的API接口文档
|
||
|
||
**测试脚本：**
|
||
- ✅ `test/宿舍卫生检查API测试脚本.py` - 完整的测试脚本，包含AES+RSA加密登录
|
||
|
||
**总结文档：**
|
||
- ✅ `docs/开发文档/宿舍卫生检查API接口完善总结.md` - 详细的工作总结
|
||
|
||
## 技术实现细节
|
||
|
||
### 1. 数据流程
|
||
|
||
```
|
||
前端表单数据 → DormHygieneCheckCompleteForm → API接口 → 后端事务处理 → 数据库存储
|
||
```
|
||
|
||
### 2. 事务处理策略
|
||
|
||
**新增操作：**
|
||
1. 开始事务
|
||
2. 插入主表记录，获取主键ID
|
||
3. 为每个学生插入评分记录，关联主表ID
|
||
4. 提交事务
|
||
|
||
**更新操作：**
|
||
1. 开始事务
|
||
2. 更新主表记录
|
||
3. 逻辑删除原有学生评分记录（deleted=1）
|
||
4. 插入新的学生评分记录
|
||
5. 提交事务
|
||
|
||
### 3. 数据验证规则
|
||
|
||
**主表验证：**
|
||
- `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
|
||
|
||
## 文件清单
|
||
|
||
### 已修改的文件
|
||
1. `web/src/api/xg/xgss/dormHygieneCheck/dormHygieneCheck/types.ts` - 类型定义扩展
|
||
2. `web/src/api/xg/xgss/dormHygieneCheck/dormHygieneCheck/index.ts` - API接口更新
|
||
3. `web/src/views/xg/xgss/dormHygieneCheck/dormHygieneCheck/DormHygieneCheckDialog.vue` - Dialog组件优化
|
||
4. `web/src/views/xg/xgss/dormHygieneCheck/dormHygieneCheck/index.vue` - 主页面更新
|
||
|
||
### 新增的文件
|
||
1. `docs/开发文档/API/宿舍卫生检查管理API.md` - API接口文档
|
||
2. `test/宿舍卫生检查API测试脚本.py` - 测试脚本
|
||
3. `docs/开发文档/宿舍卫生检查API接口完善总结.md` - 工作总结
|
||
4. `docs/开发文档/宿舍卫生检查API接口同步完成报告.md` - 本报告
|
||
|
||
## 后端实现要求
|
||
|
||
### Controller层示例
|
||
```java
|
||
@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层要求
|
||
- 使用 `@Transactional(rollbackFor = Exception.class)` 确保事务一致性
|
||
- 实现数据验证逻辑
|
||
- 处理主表和子表的关联关系
|
||
- 记录操作日志
|
||
|
||
## 测试验证
|
||
|
||
### 测试脚本运行
|
||
```bash
|
||
python test/宿舍卫生检查API测试脚本.py
|
||
```
|
||
|
||
### 测试内容
|
||
1. ✅ AES+RSA双重加密登录
|
||
2. ✅ 新增宿舍卫生检查（包含学生评分）
|
||
3. ✅ 更新宿舍卫生检查（包含学生评分）
|
||
4. ✅ 查询详情和列表
|
||
5. ✅ 数据验证测试
|
||
6. ✅ 错误处理测试
|
||
|
||
## 注意事项
|
||
|
||
1. **事务一致性**：确保两个表的操作在同一事务中完成
|
||
2. **数据完整性**：更新时保留历史数据，便于追溯
|
||
3. **性能优化**：批量操作时考虑性能影响
|
||
4. **权限控制**：严格检查用户权限
|
||
5. **日志记录**：记录重要操作日志
|
||
6. **数据验证**：前端和后端都要进行数据验证
|
||
|
||
## 后续工作
|
||
|
||
### 后端开发任务
|
||
1. 实现 `DormHygieneCheckCompleteForm` 实体类
|
||
2. 实现 `addWithStudentScores` 和 `updateWithStudentScores` 方法
|
||
3. 添加数据验证和权限控制
|
||
4. 实现事务处理逻辑
|
||
5. 添加操作日志记录
|
||
|
||
### 测试验证
|
||
1. 运行前端测试脚本验证API接口
|
||
2. 进行集成测试验证完整功能
|
||
3. 性能测试验证大数据量处理能力
|
||
4. 安全测试验证权限控制
|
||
|
||
---
|
||
|
||
**完成时间：** 2025-01-28
|
||
**开发人员：** 系统开发团队
|
||
**文档版本：** v1.0
|
||
**状态：** ✅ 前端API接口同步完成，等待后端实现 |