hzdyjs/docs/变更管理/code-adjust-record-2025-01-27-class-student-query.md

学生信息管理API - 新增班级学生查询功能

🔧 变更信息

• 变更日期: 2025-01-27 18:00:00
• 变更类型: 功能新增
• 变更范围: 后端API接口
• 影响模块: 学工管理 - 学生信息管理

📋 变更内容

新增API接口

• 接口路径: GET /studentMsg/studentMsg/listByClassId
• 接口功能: 查询班级中所有学生信息
• 权限要求: studentMsg:studentMsg:query

接口参数

入参

• classId (String, 必填): 班级ID
• name (String, 可选): 学生姓名（模糊查询）

出参

• R<List<XgStudentMsgVo>>: 学生信息列表

业务逻辑

1. 在 xg_student_msg 表中查询：
   • deleted = 0 (未删除)
   • student_status = '1' (在籍状态)
   • class_id = 入参的classId (班级ID)
   • name LIKE '%入参的name%' (姓名模糊查询，可选)
   • 按创建时间倒序排列

🔨 技术实现

1. Controller层

文件: XgStudentMsgController.java

@SaCheckPermission("studentMsg:studentMsg:query")
@GetMapping("/listByClassId")
public R<List<XgStudentMsgVo>> getStudentsByClassId(
    @RequestParam(required = true) String classId,
    @RequestParam(required = false) String name)

2. Service层

文件: IXgStudentMsgService.java 和 XgStudentMsgServiceImpl.java

• 新增接口方法: queryStudentsByClassId()
• 实现班级学生查询逻辑

3. Mapper层

文件: XgStudentMsgMapper.java 和 XgStudentMsgMapper.xml

新增Mapper方法

selectStudentsByClassId(String classId, String name): 根据班级ID和姓名查询学生数据

SQL实现

SELECT [完整字段列表]
FROM xg_student_msg
WHERE deleted = 0
AND student_status = '1'
AND class_id = #{classId}
AND name LIKE CONCAT('%', #{name}, '%')
ORDER BY create_time DESC

📊 数据流程

用户请求 → Controller接收参数 → Service调用Mapper → 执行SQL查询 → 返回学生列表

🧪 测试说明

测试场景

1. 正常查询: 传入有效的班级ID，验证能正确返回该班级下的所有在籍学生
2. 姓名过滤: 传入班级ID和姓名，验证能正确过滤出匹配的学生
3. 边界情况: 传入不存在的班级ID，验证返回空列表
4. 权限验证: 验证无权限用户访问被拒绝

测试参数示例

GET /studentMsg/studentMsg/listByClassId?classId=101&name=张

🔗 相关文档

• API文档: docs/开发文档/API/学生信息管理API.md
• 数据库设计: docs/设计文档/database/学工管理-学生信息管理/
• 业务需求: docs/需求文档/学工管理学生信息管理需求/

⚠️ 注意事项

1. 该接口只返回在籍状态（student_status = '1'）的学生
2. 该接口只返回未删除（deleted = 0）的学生
3. 姓名参数为可选，不传时返回班级下所有学生
4. 返回结果按创建时间倒序排列

📝 变更文件清单

1. XgStudentMsgController.java - 新增Controller方法
2. IXgStudentMsgService.java - 新增Service接口方法
3. XgStudentMsgServiceImpl.java - 新增Service实现方法
4. XgStudentMsgMapper.java - 新增Mapper接口方法
5. XgStudentMsgMapper.xml - 新增SQL查询语句

✅ 验证清单

• 接口参数验证
• 权限控制验证
• SQL查询逻辑验证
• 返回数据格式验证
• 异常处理验证