# 班主任考核提交功能开发说明

## 功能概述

完善了班主任考核管理界面中的"提交考核"按钮功能，实现了完整的考核评分提交流程。

## 开发内容

### 前端部分（Vue 3 + TypeScript + Element Plus）

#### 1. API类型定义扩展
**文件位置**: `web/src/api/bzrkh/teacherAssessment/types.ts`

**新增类型定义**:
- `ClassDetailVO` - 班级详细信息
- `CoefficientVO` - 系数信息
- `AssessmentIndicatorVO` - 考核指标信息
- `SpecialWorkIndicatorVO` - 特色工作指标
- `AssessmentSubmitVO` - 考核提交数据
- `AssessmentDetailVO` - 考核详情数据

#### 2. API接口扩展
**文件位置**: `web/src/api/bzrkh/teacherAssessment/index.ts`

**新增接口**:
- `getAssessmentSubmitDetail()` - 获取考核提交详情数据
- `submitAssessmentScore()` - 提交考核评分数据

#### 3. 提交弹窗组件
**文件位置**: `web/src/views/bzrkh/teacherAssessment/submitDialog.vue`

**功能特性**:
- 9张卡片式布局：班级信息、人数系数、住校生系数、层次系数、总系数、班主任常规工作、班级管理实效、特色工作、月考核得分
- 自动系数计算：根据班级人数、住校生人数、班级层次自动计算各项系数
- 动态评分：支持自评分数输入和自评意见填写
- 实时计算：月考核得分根据公式自动计算
- 数据验证：表单验证确保数据完整性

#### 4. 主界面集成
**文件位置**: `web/src/views/bzrkh/teacherAssessment/index.vue`

**集成内容**:
- 引入提交弹窗组件
- 修改提交考核按钮逻辑
- 添加成功回调处理

### 后端部分（Spring Boot 3.4.6 + MyBatis-Plus）

#### 1. VO类创建
**文件位置**: `backend/ruoyi-modules/ruoyi-bzrkh/src/main/java/org/dromara/bzrkh/domain/vo/`

**新增VO类**:
- `ClassDetailVo.java` - 班级详细信息视图对象
- `CoefficientVo.java` - 系数信息视图对象
- `AssessmentIndicatorScoreVo.java` - 考核指标评分视图对象
- `SpecialWorkIndicatorVo.java` - 特色工作指标视图对象
- `AssessmentDetailVo.java` - 考核详情视图对象

#### 2. BO类创建
**文件位置**: `backend/ruoyi-modules/ruoyi-bzrkh/src/main/java/org/dromara/bzrkh/domain/bo/`

**新增BO类**:
- `AssessmentSubmitBo.java` - 考核提交业务对象

#### 3. Controller扩展
**文件位置**: `backend/ruoyi-modules/ruoyi-bzrkh/src/main/java/org/dromara/bzrkh/controller/TeacherAssessmentController.java`

**新增接口**:
- `getAssessmentSubmitDetail()` - 获取考核提交详情数据
- `submitAssessmentScore()` - 提交考核评分数据

#### 4. Service接口和实现扩展
**文件位置**: 
- `backend/ruoyi-modules/ruoyi-bzrkh/src/main/java/org/dromara/bzrkh/service/ITeacherAssessmentService.java`
- `backend/ruoyi-modules/ruoyi-bzrkh/src/main/java/org/dromara/bzrkh/service/impl/TeacherAssessmentServiceImpl.java`

**新增方法**:
- `getAssessmentSubmitDetail()` - 获取考核提交详情数据
- `submitAssessmentScore()` - 提交考核评分数据
- `calculateCoefficient()` - 计算系数信息（私有方法）
- `calculateStudentCountCoefficient()` - 计算人数系数（私有方法）
- `calculateBoardingCoefficient()` - 计算住校生系数（私有方法）
- `calculateLevelCoefficient()` - 计算层次系数（私有方法）
- `mergeAssessmentScores()` - 合并已保存的评分数据（私有方法）

#### 5. Mapper接口和XML扩展
**文件位置**: 
- `backend/ruoyi-modules/ruoyi-bzrkh/src/main/java/org/dromara/bzrkh/mapper/TeacherAssessmentMapper.java`
- `backend/ruoyi-modules/ruoyi-bzrkh/src/main/resources/mapper/bzrkh/TeacherAssessmentMapper.xml`

**新增方法**:
- `selectClassDetail()` - 查询班级详细信息
- `selectRoutineWorkIndicators()` - 查询班主任常规工作指标列表
- `selectClassDeductionIndicator()` - 查询班级扣分指标
- `selectSpecialWorkIndicators()` - 查询特色工作指标列表
- `selectSavedAssessmentScores()` - 查询已保存的评分数据
- `selectSchemeIdByPlanId()` - 根据计划ID查询方案ID
- `selectIndicatorIdByCode()` - 根据指标编码查询指标ID
- `deleteAssessmentScoresByPlanAndTeacher()` - 逻辑删除评分数据
- `insertAssessmentScore()` - 插入评分数据
- `updateAssessmentScoreRemark()` - 更新评分数据备注

## 核心业务逻辑

### 1. 系数计算规则

#### 人数系数（K2）
- 班级人数36～40人（含36人），系数为1
- 超过40人，每增加1名学生，系数增加0.02
- 少于36人，每减少1名学生，系数减少0.02
- 本项系数最低0.7

#### 住校生系数（K3）
- 根据住校生人数，按人均0.005计算

#### 层次系数（K1）
- 技师班（K1=0.95）
- 高级工班（K1=1）
- 中级工班（K1=1.05）
- 预备技师班（K1=0.95）
- 中高职一体（K1=1）

#### 总系数（K）
- 计算公式：K = K1 * (K2 + K3)

### 2. 月考核得分计算

#### 自评模式（修正后公式）
- 计算公式：总系数（K）* （（班主任常规工作自评分之和 + 班级扣分项满分值） - 按班级扣分50%计的分值 + 特色工作总分值）
- 班级扣分项满分值：固定50分（来自指标设置）
- 修正原因：确保基础分值不受扣分影响，提高计算结果的合理性

#### 审核模式（保持不变）
- 计算公式：总系数（K）* （班主任常规工作上级评分之和 + 班级管理实效上级评分 + 特色工作上级评分之和）

#### 公式变化对比
- **修正前**：K × (常规工作自评分 - 班级扣分50% + 特色工作总分)
- **修正后**：K × ((常规工作自评分 + 50) - 班级扣分50% + 特色工作总分)
- **关键变化**：新增班级扣分项满分值（50分）确保基础分值

### 3. 数据存储逻辑
1. 先逻辑删除该计划下该教师的历史评分数据
2. 插入班主任常规工作指标评分
3. 插入班级扣分指标评分
4. 插入特色工作指标评分（4个固定指标）
5. 将总体评价存储到备注字段

## 权限配置

### API接口权限
- `bzrkh:teacherAssessment:list` - 查看班级和考核计划列表
- `bzrkh:teacherAssessment:detail` - 查看考核详情
- `bzrkh:teacherAssessment:submit` - 提交考核

详细权限配置请参考：`班主任考核提交功能权限配置.md`

## 数据准备

### 必要的指标数据
系统需要以下5个考核指标才能正常运行：

1. `bzrwjkf001` - 班级扣分
2. `bzrtsgz001` - 及时并妥善处理好学生违纪事件
3. `bzrtsgz002` - 班级活动获奖情况
4. `bzrtsgz003` - 班级宣传工作有特色
5. `bzrtsgz004` - 其他

数据插入脚本：`班主任考核提交功能必要数据.sql`

## 部署说明

### 1. 数据库脚本执行
```sql
-- 执行必要数据插入脚本
source 班主任考核提交功能必要数据.sql;
```

### 2. 后端编译重启
```bash
# 编译ruoyi-bzrkh模块
mvn clean compile -pl ruoyi-modules/ruoyi-bzrkh

# 重启应用服务
# （请根据实际部署方式重启服务）
```

### 3. 前端构建
```bash
# 前端无需重新构建，代码已支持热更新
# 如需构建：
npm run build:prod
```

### 4. 权限配置
1. 登录系统管理后台
2. 进入系统管理-菜单管理
3. 为班主任考核相关菜单配置权限
4. 为相关角色分配权限

## 测试验证

### 1. 基础功能测试
- [ ] 班主任登录系统
- [ ] 查看考核计划列表
- [ ] 点击"提交考核"按钮
- [ ] 弹窗正常显示9张卡片
- [ ] 系数自动计算正确

### 2. 评分功能测试
- [ ] 班主任常规工作指标可正常输入评分
- [ ] 班级扣分可正常输入，50%计算正确
- [ ] 特色工作4个指标可正常输入评分
- [ ] 月考核得分自动计算正确

### 3. 数据保存测试
- [ ] 提交评分数据成功
- [ ] 数据正确保存到数据库
- [ ] 再次打开弹窗数据正确回显

## 技术亮点

1. **响应式系数计算**：前端实时计算各项系数，提供直观的数据展示
2. **组件化设计**：弹窗组件独立封装，便于维护和复用
3. **数据一致性**：采用逻辑删除+重新插入的方式确保数据一致性
4. **权限控制**：完整的权限控制体系，确保数据安全
5. **用户体验**：直观的卡片式布局，清晰的数据展示
6. **实时人数统计**：班级总人数从xg_student_msg表实时统计，确保数据准确性

## 班级人数统计规则（2025-01-27更新）

### 班级总人数统计
- **数据来源**: `xg_student_msg`表
- **统计条件**: 
  - `class_id` = 班级ID
  - `student_status` = '1'（正常状态）
  - `deleted` = 0（未逻辑删除）
- **统计方式**: COUNT(1)

### 住校生人数统计
- **数据来源**: `xg_student_msg`表
- **统计条件**:
  - `class_id` = 班级ID
  - `student_status` = '1'（正常状态）
  - `dormitory_room` IS NOT NULL AND `dormitory_room` != ''（有宿舍信息）
  - `deleted` = 0（未逻辑删除）
- **统计方式**: COUNT(1)

## 待扩展功能

1. 学生违规处分信息查看功能
2. 考核结果审核功能
3. 考核数据统计分析功能
4. 考核历史记录查询功能

---

**开发完成时间**: 2025-01-27  
**开发版本**: V1.0.0  
**测试状态**: 待测试验证