# 学生考核审核功能说明

## 📋 功能概述

学生考核审核功能允许班主任查看和管理自己班级学生的考核申请，确保班主任只能查看已提交的申请，不能查看草稿状态的申请。

## 🔐 权限控制

### 班主任查看权限
- **权限标识**: `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