code-adjust-record-2025-01-17-stuColBatchClass-setScope-api.md 4.6 KB

学生信息收集批次班级权限设置API开发记录

日期: 2025-01-17
开发者: Cursor AI
变更类型: 新增功能
影响范围: 后端API接口

📋 变更概述

在 XgStuColBatchClassController.java 中新增了 setScope API接口,用于设置学生信息收集批次的班级权限。

🔧 具体变更

1. Controller层变更

文件: backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/controller/XgStuColBatchClassController.java

新增内容

  • 添加了 setScope API接口
  • 接口路径: POST /stuColBatchClass/stuColBatchClass/setScope
  • 入参: batchId (批次ID)、deptIds (授权的班级ID列表)
  • 添加了事务注解 @Transactional(rollbackFor = Exception.class)
  • 直接注入 XgStuColBatchClassMapper 用于数据库操作

实现逻辑

  1. 第一步: 遍历deptIds,通过SQL查询班级信息
  2. 第二步: 清理历史权限数据(逻辑删除)
  3. 第三步: 插入新的权限数据

2. Mapper层变更

文件: backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/mapper/XgStuColBatchClassMapper.java

新增方法

  • clearHistoryPermissions(Long batchId): 清理历史权限数据
  • selectClassInfoByDeptIds(List<Long> deptIds): 根据部门ID查询班级信息

3. XML映射文件变更

文件: backend/ruoyi-modules/ruoyi-xg/src/main/resources/mapper/stuColBatchClass/XgStuColBatchClassMapper.xml

新增内容

  • 添加了 XgStuColBatchClassVoResult ResultMap
  • 实现了 clearHistoryPermissions 的SQL更新语句
  • 实现了 selectClassInfoByDeptIds 的SQL查询语句
  • 查询条件: deleted = 0 AND class_status = '1'

4. VO类规范修复

文件: backend/ruoyi-modules/ruoyi-xg/src/main/java/org/dromara/xg/domain/vo/XgStuColBatchClassVo.java

修复内容

  • 添加了基础字段: createBy、createTime、updateBy、updateTime
  • 添加了 @JsonFormat 注解进行时间格式化
  • 符合项目VO类基础字段规范要求

🎯 技术特性

数据一致性保证

  • ✅ 使用 @Transactional 注解确保事务一致性
  • ✅ 先清理历史数据,再插入新数据
  • ✅ 异常时自动回滚

参数验证

  • ✅ 使用 @NotNull 和 @NotEmpty 进行参数校验
  • ✅ 批次ID和班级ID列表均为必填项

权限控制

  • ✅ 使用 @SaCheckPermission 进行权限验证
  • ✅ 权限标识: stuColBatchClass:stuColBatchClass:setScope

操作日志

  • ✅ 使用 @Log 记录操作日志
  • ✅ 业务类型: BusinessType.UPDATE

防重复提交

  • ✅ 使用 @RepeatSubmit 防止重复提交

📊 API接口详情

请求信息

  • 方法: POST
  • 路径: /stuColBatchClass/stuColBatchClass/setScope
  • Content-Type: application/x-www-form-urlencoded

请求参数

响应格式

{
  "code": 200,
  "msg": "权限设置成功,共设置 X 个班级权限",
  "data": null
}

🔍 业务逻辑

第一步:查询班级信息

  • 通过 dept_id 关联 xg_class_msg 表的 id 字段
  • 查询条件: deleted = 0 AND class_status = '1'
  • 获取字段: college_id, college_name, major_id, major_name, id, class_name

第二步:清理历史权限

  • SQL: UPDATE xg_stu_col_batch_class SET deleted = 1 WHERE batch_id = #{batchId}
  • 逻辑删除,保留历史数据

第三步:插入新权限

  • 遍历查询到的班级信息
  • 构建 XgStuColBatchClass 实体对象
  • 批量插入到 xg_stu_col_batch_class 表

✅ 质量保证

代码规范

  • ✅ 遵循项目开发规范
  • ✅ 使用统一的响应格式 R<Void>
  • ✅ 完整的异常处理机制
  • ✅ 详细的注释说明

数据库规范

  • ✅ 使用逻辑删除,不物理删除数据
  • ✅ 包含完整的基础字段
  • ✅ 事务一致性保证

安全性

  • ✅ 参数验证防止非法输入
  • ✅ 权限控制确保访问安全
  • ✅ 防重复提交保护

🚀 后续优化建议

  1. 性能优化: 可考虑使用批量插入提高性能
  2. 日志完善: 可添加更详细的操作日志记录
  3. 缓存机制: 可考虑添加缓存减少数据库查询
  4. 异步处理: 对于大量数据可考虑异步处理

📝 测试建议

  1. 单元测试: 测试各个步骤的逻辑正确性
  2. 集成测试: 测试完整的API调用流程
  3. 异常测试: 测试各种异常情况的处理
  4. 性能测试: 测试大量数据的处理性能

备注: 本次开发严格按照项目规范进行,确保了代码质量和数据一致性。

参数名 类型 必填 说明
batchId Long 是 批次ID
deptIds List 是 授权的班级ID列表