# 班主任考核方案管理API文档

## 📋 基本信息

- **模块名称**: 班主任考核方案管理
- **模块编码**: bzrkh-assessment-scheme
- **API前缀**: `/bzrkh/assessmentScheme`
- **创建时间**: 2025-01-08
- **文档版本**: V1.0.0

## 🔐 权限配置

### 权限字符列表
| 权限字符 | 权限名称 | 说明 |
|---------|---------|------|
| `bzrkh:assessmentScheme:list` | 考核方案列表查询权限 | 查看考核方案列表 |
| `bzrkh:assessmentScheme:query` | 考核方案详情查询权限 | 查看考核方案详情 |
| `bzrkh:assessmentScheme:add` | 考核方案新增权限 | 创建新的考核方案 |
| `bzrkh:assessmentScheme:edit` | 考核方案修改权限 | 编辑考核方案信息 |
| `bzrkh:assessmentScheme:remove` | 考核方案删除权限 | 删除考核方案 |
| `bzrkh:assessmentScheme:export` | 考核方案导出权限 | 导出考核方案数据 |

### 菜单配置
- **父级菜单**: 班主任考核管理
- **菜单路径**: `/bzrkh/assessmentScheme`
- **组件路径**: `bzrkh/assessmentScheme/index`
- **菜单图标**: `clipboard`

## 📊 数据字典

### 学期字典
| 字典值 | 字典标签 | 说明 |
|-------|---------|------|
| `1` | 上学期 | 学年上学期 |
| `2` | 下学期 | 学年下学期 |

### 是否字典 (sys_yes_no)
| 字典值 | 字典标签 | 说明 |
|-------|---------|------|
| `0` | 否 | 不需要 |
| `1` | 是 | 需要 |

### 状态字典 (sys_normal_disable)
| 字典值 | 字典标签 | 说明 |
|-------|---------|------|
| `0` | 正常 | 启用状态 |
| `1` | 停用 | 禁用状态 |

## 🗄️ 数据模型

### 考核方案实体 (BmzrAssessmentScheme)

| 字段名 | 类型 | 长度 | 必填 | 说明 |
|-------|------|------|------|------|
| id | bigint | 20 | ✅ | 主键ID |
| tenant_id | varchar | 20 | ✅ | 租户编号 |
| scheme_name | varchar | 100 | ✅ | 方案名称 |
| scheme_code | varchar | 50 | ✅ | 方案编码 |
| academic_year | varchar | 10 | ✅ | 学年 |
| semester | char | 1 | ✅ | 学期（1=上学期 2=下学期） |
| scheme_description | text | - | ❌ | 方案描述 |
| self_evaluation_required | char | 1 | ✅ | 是否需要自评（0=否 1=是） |
| superior_evaluation_required | char | 1 | ✅ | 是否需要上级评（0=否 1=是） |
| status | char | 1 | ✅ | 状态（0正常 1停用） |
| remark | varchar | 500 | ❌ | 备注 |
| create_dept | bigint | 20 | ❌ | 创建部门 |
| create_by | bigint | 20 | ❌ | 创建者 |
| create_time | datetime | - | ❌ | 创建时间 |
| update_by | bigint | 20 | ❌ | 更新者 |
| update_time | datetime | - | ❌ | 更新时间 |
| deleted | int | 1 | ✅ | 删除标志（0代表存在 1代表删除） |

## 🔌 API接口列表

### 1. 查询考核方案列表

**接口地址**: `GET /bzrkh/assessmentScheme/list`

**权限要求**: `bzrkh:assessmentScheme:list`

**请求参数**:
```typescript
interface BmzrAssessmentSchemeQuery extends PageQuery {
  schemeName?: string;           // 方案名称（模糊查询）
  schemeCode?: string;           // 方案编码（精确查询）
  academicYear?: string;         // 学年（精确查询）
  semester?: string;             // 学期（精确查询）
  status?: string;               // 状态（精确查询）
  selfEvaluationRequired?: string;     // 是否需要自评
  superiorEvaluationRequired?: string; // 是否需要上级评
}
```

**响应数据**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1744234567890123456,
      "tenantId": "000000",
      "schemeName": "2024-2025学年上学期班主任考核方案",
      "schemeCode": "BMZR_2024_1",
      "academicYear": "2024-2025",
      "semester": "1",
      "schemeDescription": "2024-2025学年上学期班主任考核方案",
      "selfEvaluationRequired": "1",
      "superiorEvaluationRequired": "1",
      "status": "0",
      "remark": "",
      "createTime": "2025-01-08 10:00:00",
      "updateTime": "2025-01-08 10:00:00"
    }
  ],
  "total": 1
}
```

### 2. 查询考核方案详情

**接口地址**: `GET /bzrkh/assessmentScheme/{id}`

**权限要求**: `bzrkh:assessmentScheme:query`

**路径参数**:
- `id`: 考核方案ID (必填)

**响应数据**:
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1744234567890123456,
    "tenantId": "000000",
    "schemeName": "2024-2025学年上学期班主任考核方案",
    "schemeCode": "BMZR_2024_1",
    "academicYear": "2024-2025",
    "semester": "1",
    "schemeDescription": "2024-2025学年上学期班主任考核方案",
    "selfEvaluationRequired": "1",
    "superiorEvaluationRequired": "1",
    "status": "0",
    "remark": "",
    "createTime": "2025-01-08 10:00:00",
    "updateTime": "2025-01-08 10:00:00"
  }
}
```

### 3. 新增考核方案

**接口地址**: `POST /bzrkh/assessmentScheme`

**权限要求**: `bzrkh:assessmentScheme:add`

**请求体**:
```json
{
  "schemeName": "2024-2025学年上学期班主任考核方案",
  "schemeCode": "BMZR_2024_1",
  "academicYear": "2024-2025",
  "semester": "1",
  "schemeDescription": "2024-2025学年上学期班主任考核方案详细描述",
  "selfEvaluationRequired": "1",
  "superiorEvaluationRequired": "1",
  "status": "0",
  "remark": "备注信息"
}
```

**校验规则**:
- `schemeName`: 必填，方案名称不能为空
- `schemeCode`: 必填，方案编码不能为空，且在同租户下唯一
- `academicYear`: 必填，学年不能为空
- `semester`: 必填，学期不能为空，值为 1 或 2
- `selfEvaluationRequired`: 必填，是否需要自评，值为 0 或 1
- `superiorEvaluationRequired`: 必填，是否需要上级评，值为 0 或 1
- `status`: 必填，状态不能为空，值为 0 或 1

**响应数据**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 4. 修改考核方案

**接口地址**: `PUT /bzrkh/assessmentScheme`

**权限要求**: `bzrkh:assessmentScheme:edit`

**请求体**:
```json
{
  "id": 1744234567890123456,
  "schemeName": "2024-2025学年上学期班主任考核方案（修改）",
  "schemeCode": "BMZR_2024_1",
  "academicYear": "2024-2025",
  "semester": "1",
  "schemeDescription": "修改后的方案描述",
  "selfEvaluationRequired": "1",
  "superiorEvaluationRequired": "1",
  "status": "0",
  "remark": "修改备注"
}
```

**校验规则**: 与新增接口相同，额外需要 `id` 字段

**响应数据**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 5. 删除考核方案

**接口地址**: `DELETE /bzrkh/assessmentScheme/{ids}`

**权限要求**: `bzrkh:assessmentScheme:remove`

**路径参数**:
- `ids`: 考核方案ID数组，多个ID用逗号分隔

**响应数据**:
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

### 6. 导出考核方案

**接口地址**: `POST /bzrkh/assessmentScheme/export`

**权限要求**: `bzrkh:assessmentScheme:export`

**请求体**: 与查询列表接口参数相同

**响应**: Excel文件下载

## 🎯 业务规则

### 数据唯一性约束
1. 同一租户下，`schemeCode`（方案编码）必须唯一
2. 建议同一租户、学年、学期下只有一个启用的考核方案

### 状态管理
1. 新建方案默认状态为"正常"（0）
2. 停用的方案不影响已关联的考核计划
3. 删除方案时需要检查是否被考核计划引用

### 权限控制
1. 普通用户只能查看考核方案
2. 管理员可以进行增删改操作
3. 超级管理员拥有所有权限

## 🔧 技术实现

### 后端技术栈
- **框架**: Spring Boot 3.4.6
- **数据库**: MySQL 8.0+
- **ORM**: MyBatis-Plus
- **权限**: Sa-Token

### 前端技术栈
- **框架**: Vue 3.5.13 + TypeScript 5.8.3
- **UI组件**: Element Plus
- **HTTP客户端**: Axios

### 数据库表
- **主表**: `bmzr_assessment_scheme` (班主任考核方案表)

## 🧪 测试用例

### 功能测试
1. ✅ 考核方案列表查询（支持分页、筛选）
2. ✅ 考核方案详情查询
3. ✅ 考核方案新增（包含表单验证）
4. ✅ 考核方案修改（包含表单验证）
5. ✅ 考核方案删除（支持批量删除）
6. ✅ 考核方案导出（Excel格式）

### 权限测试
1. ✅ 无权限用户访问受限
2. ✅ 不同角色权限差异化控制

### 数据验证测试
1. ✅ 必填字段验证
2. ✅ 数据格式验证
3. ✅ 唯一性约束验证

## 📝 更新日志

### V1.0.0 (2025-01-08)
- ✅ 基础CRUD功能实现
- ✅ 权限配置完成
- ✅ 前后端代码生成
- ✅ API文档编写

## 🔗 相关文档

- **数据库设计**: `docs/设计文档/database/班主任考核管理/bmzr_assessment_tables.sql`
- **字典配置**: `docs/设计文档/database/班主任考核管理/bmzr_dict_data_mysql.sql`
- **权限配置**: `backend/ruoyi-modules/ruoyi-bzrkh/班主任考核方案权限配置.sql`