hzdyjs/docs/开发文档/API/班主任考核方案管理API.md

班主任考核方案管理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

请求参数:

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

响应数据:

{
  "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 (必填)

响应数据:

{
  "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

请求体:

{
  "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

响应数据:

{
  "code": 200,
  "msg": "操作成功"
}

4. 修改考核方案

接口地址: PUT /bzrkh/assessmentScheme

权限要求: bzrkh:assessmentScheme:edit

请求体:

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

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

响应数据:

{
  "code": 200,
  "msg": "操作成功"
}

5. 删除考核方案

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

权限要求: bzrkh:assessmentScheme:remove

路径参数:

• ids: 考核方案ID数组，多个ID用逗号分隔

响应数据:

{
  "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