176 lines
6.3 KiB
Markdown
176 lines
6.3 KiB
Markdown
# 宿舍卫生检查API接口完善总结
|
||
|
||
## 项目概述
|
||
|
||
本次任务是对宿舍卫生检查管理模块的API接口进行完善，主要目标是实现同时操作两个数据表（主表和子表）的新增和更新功能。
|
||
|
||
## 完成的工作
|
||
|
||
### 1. 前端API接口完善
|
||
|
||
#### 1.1 类型定义扩展 (`types.ts`)
|
||
- ✅ 新增 `DormHygieneStudentScoreVO` 接口：学生评分数据展示类型
|
||
- ✅ 新增 `DormHygieneStudentScoreForm` 接口：学生评分数据表单类型
|
||
- ✅ 新增 `DormHygieneStudentScoreQuery` 接口：学生评分查询类型
|
||
- ✅ 新增 `DormHygieneCheckCompleteForm` 接口：完整的宿舍卫生检查表单类型（包含学生评分数据）
|
||
|
||
#### 1.2 API接口更新 (`index.ts`)
|
||
- ✅ 更新 `addDormHygieneCheck` 接口：支持同时插入主表和子表数据
|
||
- ✅ 更新 `updateDormHygieneCheck` 接口：支持同时更新主表和子表数据
|
||
- ✅ 新增学生评分相关API接口：
|
||
- `listDormHygieneStudentScores`：查询学生评分列表
|
||
- `getDormHygieneStudentScore`：查询学生评分详情
|
||
- `addDormHygieneStudentScore`：新增学生评分
|
||
- `updateDormHygieneStudentScore`：更新学生评分
|
||
- `delDormHygieneStudentScore`：删除学生评分
|
||
- `getStudentScoresByCheckId`：根据检查ID查询学生评分
|
||
- `deleteStudentScoresByCheckId`：批量删除指定检查的学生评分
|
||
|
||
### 2. 前端组件优化
|
||
|
||
#### 2.1 Dialog组件更新 (`DormHygieneCheckDialog.vue`)
|
||
- ✅ 修复表单验证规则的类型问题
|
||
- ✅ 更新 `submitForm` 方法：支持提交完整的学生评分数据
|
||
- ✅ 优化数据格式转换：将前端数据格式转换为API接口要求的格式
|
||
- ✅ 增强错误处理和用户提示
|
||
|
||
#### 2.2 主页面更新 (`index.vue`)
|
||
- ✅ 更新 `handleDialogSubmit` 方法：支持处理完整表单数据
|
||
- ✅ 添加新的类型导入：`DormHygieneCheckCompleteForm`
|
||
|
||
### 3. 后端API设计规范
|
||
|
||
#### 3.1 新增接口设计
|
||
**接口地址：** `POST /dormHygieneCheck/dormHygieneCheck/addWithStudentScores`
|
||
|
||
**实现要求：**
|
||
- 🔄 使用数据库事务确保两个表的操作原子性
|
||
- 📝 先插入主表记录，获取生成的主键ID
|
||
- 👥 为每个学生插入评分记录，关联主表ID
|
||
- ✅ 进行完整的数据验证
|
||
- 🔐 检查用户权限，记录操作日志
|
||
|
||
#### 3.2 更新接口设计
|
||
**接口地址：** `PUT /dormHygieneCheck/dormHygieneCheck/updateWithStudentScores`
|
||
|
||
**实现要求：**
|
||
- 🔄 使用数据库事务确保操作的原子性
|
||
- 📝 更新主表记录
|
||
- 🗑️ 将原有学生评分记录的 `deleted` 字段设置为 1（逻辑删除）
|
||
- ➕ 插入新的学生评分记录
|
||
- 📚 保留历史数据，便于追溯
|
||
|
||
### 4. 数据验证规则
|
||
|
||
#### 4.1 主表验证
|
||
- `checkTitle`: 必填，长度1-200字符
|
||
- `checkDate`: 必填，日期时间格式
|
||
- `checkerId`: 必填，关联用户表
|
||
- `roomId`: 必填，关联房间表
|
||
- `totalScore`: 可选，0-100分
|
||
- `hygieneGrade`: 可选，A/B/C/D
|
||
|
||
#### 4.2 学生评分表验证
|
||
- `studentId`: 必填，关联学生表
|
||
- `studentScore`: 可选，0-100分
|
||
- `attendanceStatus`: 必填，1/2/3/4
|
||
- `studentGrade`: 可选，A/B/C/D
|
||
|
||
### 5. 测试脚本开发
|
||
|
||
#### 5.1 完整测试脚本 (`test/宿舍卫生检查API测试脚本.py`)
|
||
- ✅ AES+RSA双重加密登录方法
|
||
- ✅ 新增宿舍卫生检查测试
|
||
- ✅ 更新宿舍卫生检查测试
|
||
- ✅ 查询详情和列表测试
|
||
- ✅ 学生评分数据测试
|
||
- ✅ 数据验证测试
|
||
- ✅ 错误处理测试
|
||
|
||
## 技术特点
|
||
|
||
### 1. 数据一致性保证
|
||
- 使用数据库事务确保两个表的操作原子性
|
||
- 更新时采用逻辑删除策略，保留历史数据
|
||
|
||
### 2. 类型安全
|
||
- 完整的TypeScript类型定义
|
||
- 前端数据格式与API接口格式的自动转换
|
||
|
||
### 3. 用户体验优化
|
||
- 自动为学生设置相同的个人得分和评级
|
||
- 实时数据验证和错误提示
|
||
- 完整的加载状态和操作反馈
|
||
|
||
### 4. 可维护性
|
||
- 清晰的代码结构和注释
|
||
- 完整的API文档和测试用例
|
||
- 符合项目开发规范
|
||
|
||
## 文件清单
|
||
|
||
### 前端文件
|
||
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` - 弹窗组件
|
||
4. `web/src/views/xg/xgss/dormHygieneCheck/dormHygieneCheck/index.vue` - 主页面
|
||
|
||
### 文档文件
|
||
1. `docs/开发文档/API/宿舍卫生检查管理API.md` - API接口文档
|
||
2. `docs/开发文档/宿舍卫生检查API接口完善总结.md` - 本总结文档
|
||
|
||
### 测试文件
|
||
1. `test/宿舍卫生检查API测试脚本.py` - 完整测试脚本
|
||
|
||
## 数据库表结构
|
||
|
||
### 主表：xg_dorm_hygiene_check
|
||
- 存储宿舍卫生检查的基本信息
|
||
- 包含检查标题、日期、检查员、宿舍信息、总分、等级等
|
||
|
||
### 子表：xg_dorm_hygiene_student_score
|
||
- 存储每个学生的个人评分信息
|
||
- 关联主表，包含学生信息、个人得分、出勤状态、评级等
|
||
|
||
## 使用说明
|
||
|
||
### 1. 新增操作
|
||
1. 填写宿舍卫生检查基本信息
|
||
2. 选择宿舍房间，系统自动加载学生信息
|
||
3. 设置宿舍总分和卫生等级
|
||
4. 为每个学生设置个人得分、出勤状态和评级
|
||
5. 上传附件和填写备注信息
|
||
6. 点击确定，系统同时保存主表和子表数据
|
||
|
||
### 2. 更新操作
|
||
1. 修改宿舍卫生检查基本信息
|
||
2. 调整学生评分数据
|
||
3. 点击确定，系统更新主表并重新插入学生评分数据（保留历史）
|
||
|
||
### 3. 测试验证
|
||
1. 运行测试脚本：`python test/宿舍卫生检查API测试脚本.py`
|
||
2. 验证新增、更新、查询功能
|
||
3. 检查数据一致性和完整性
|
||
|
||
## 注意事项
|
||
|
||
1. **事务一致性**：确保两个表的操作在同一事务中完成
|
||
2. **数据完整性**：更新时保留历史数据，便于追溯
|
||
3. **性能优化**：批量操作时考虑性能影响
|
||
4. **权限控制**：严格检查用户权限
|
||
5. **日志记录**：记录重要操作日志
|
||
6. **数据验证**：前端和后端都要进行数据验证
|
||
|
||
## 后续优化建议
|
||
|
||
1. **批量操作优化**：考虑使用批量插入提高性能
|
||
2. **缓存机制**：对常用数据进行缓存
|
||
3. **异步处理**：对于大量数据的操作考虑异步处理
|
||
4. **监控告警**：添加操作监控和异常告警
|
||
5. **数据备份**：定期备份重要数据
|
||
|
||
---
|
||
|
||
**完成时间：** 2025-01-28
|
||
**开发人员：** 系统开发团队
|
||
**文档版本：** v1.0 |