提交代码

docs/开发文档/学生考核审核功能说明.md

@@ -0,0 +1,148 @@
+# 学生考核审核功能说明
+
+## 📋 功能概述
+
+学生考核审核功能允许班主任查看和管理自己班级学生的考核申请，确保班主任只能查看已提交的申请，不能查看草稿状态的申请。
+
+## 🔐 权限控制
+
+### 班主任查看权限
+- **权限标识**: `assessment:approval:teacherClass`
+- **数据范围**: 仅限当前登录用户作为班主任的班级
+- **状态限制**: 只能查看已提交、班主任审核、已完成状态的申请
+
+### 考核计划查看权限
+- **权限标识**: `assessment:approval:available`
+- **数据范围**: 所有进行中和已结束的考核计划
+
+## 📊 数据过滤规则
+
+### 班主任班级申请列表查询
+
+#### 接口信息
+- **URL**: `GET /assessment/approval/teacherClass`
+- **权限**: `assessment:approval:teacherClass`
+
+#### 查询条件
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| scheduleId | Long | 否 | 考核计划ID |
+| studentNo | String | 否 | 学号（支持模糊查询） |
+| studentName | String | 否 | 学生姓名（支持模糊查询） |
+| status | String | 否 | 申请状态（2-已提交 3-班主任审核 6-已完成） |
+| pageNum | Integer | 否 | 页码，默认1 |
+| pageSize | Integer | 否 | 每页大小，默认10 |
+
+#### 强制过滤条件
+```sql
+-- 班主任只能查看自己班级的申请
+AND a.class_id IN (
+    SELECT id FROM xg_class_msg 
+    WHERE class_teacher_id = #{teacherId} 
+    AND deleted = 0 AND class_status = '1'
+)
+
+-- 排除草稿状态，只查看已提交、班主任审核、已完成的申请
+AND a.status IN ('2', '3', '6')
+```
+
+#### 状态说明
+| 状态码 | 状态名称 | 说明 |
+|--------|----------|------|
+| 1 | 草稿 | ❌ **班主任不可见** |
+| 2 | 已提交 | ✅ 班主任可见 |
+| 3 | 班主任审核 | ✅ 班主任可见 |
+| 6 | 已完成 | ✅ 班主任可见 |
+
+### 可用考核计划查询
+
+#### 接口信息
+- **URL**: `GET /assessment/approval/available`
+- **权限**: `assessment:approval:available`
+
+#### 查询条件
+```sql
+-- 只查询进行中和已结束的计划
+WHERE deleted = 0
+AND status IN ('2', '3')
+ORDER BY start_time DESC
+```
+
+#### 计划状态说明
+| 状态码 | 状态名称 | 说明 |
+|--------|----------|------|
+| 1 | 未开始 | ❌ 不可用 |
+| 2 | 进行中 | ✅ 可用 |
+| 3 | 已结束 | ✅ 可用 |
+
+## 🔍 业务逻辑
+
+### 班主任查看流程
+1. **身份验证**: 获取当前登录用户ID
+2. **班级查询**: 查询该用户作为班主任的班级列表
+3. **申请过滤**: 只查询这些班级下状态为已提交、班主任审核、已完成的申请
+4. **数据返回**: 返回过滤后的申请列表
+
+### 数据安全保证
+- **权限隔离**: 班主任只能查看自己班级的数据
+- **状态过滤**: 自动排除草稿状态的申请
+- **数据完整性**: 包含完整的申请信息、状态名称、审核人信息等
+
+## 📝 使用示例
+
+### 基本查询
+```bash
+GET /assessment/approval/teacherClass
+```
+
+### 按状态筛选
+```bash
+GET /assessment/approval/teacherClass?status=2
+```
+
+### 按学生姓名搜索
+```bash
+GET /assessment/approval/teacherClass?studentName=张三
+```
+
+### 分页查询
+```bash
+GET /assessment/approval/teacherClass?pageNum=1&pageSize=10
+```
+
+## 🧪 测试验证
+
+### 测试脚本
+使用 `test/学生考核审核API测试脚本.py` 进行功能验证：
+
+```bash
+cd test
+python 学生考核审核API测试脚本.py
+```
+
+### 测试要点
+1. ✅ 验证班主任只能查看已提交、班主任审核、已完成状态的申请
+2. ✅ 验证草稿状态的申请不会被班主任看到
+3. ✅ 验证分页查询功能正常
+4. ✅ 验证筛选条件功能正常
+5. ✅ 验证只返回班主任自己班级的数据
+
+## ⚠️ 注意事项
+
+1. **草稿状态保护**: 班主任无法查看学生草稿状态的申请，保护学生隐私
+2. **权限验证**: 所有接口都需要相应的权限标识
+3. **数据一致性**: 确保返回的数据状态与业务规则一致
+4. **性能优化**: 使用索引优化查询性能，避免全表扫描
+
+## 📚 相关文档
+
+- [学生考核管理系统API文档](./API/学生考核管理系统API.md)
+- [API文档基础规范](./API/API文档基础规范.md)
+- [后端开发规范](../.cursor/cursorrules-backend.md)
+
+---
+
+**文档版本**: v1.0.0  
+**创建时间**: 2025-01-03  
+**最后更新**: 2025-01-03  
+**维护人员**: Cursor AI