all-project/docs/开发文档/API/班主任考核计划管理API.md

班主任考核计划管理API文档

概述

班主任考核计划管理模块用于管理班主任考核的各类计划，包括计划的创建、修改、删除、查询以及状态管理等功能。

基本信息

• 模块名称: 班主任考核计划管理
• 模块编码: bzrkh
• API前缀: /bzrkh/assessmentPlan
• 创建时间: 2025-01-08
• 版本: v1.0.0

权限配置

菜单权限配置

以下是班主任考核计划管理模块所需的权限配置SQL：

-- ==========================================
-- 班主任考核计划管理权限配置
-- ==========================================

-- 删除已存在的菜单
DELETE FROM sys_menu WHERE menu_name = '班主任考核计划管理' AND parent_id IN (
    SELECT id FROM (SELECT * FROM sys_menu) t WHERE t.menu_name = '班主任考核管理'
);

-- 插入班主任考核计划管理菜单
INSERT INTO sys_menu (tenant_id, menu_name, parent_id, order_num, path, component, query_param, is_frame, is_cache, menu_type, visible, status, perms, icon, create_dept, create_by, create_time, remark) 
VALUES ('000000', '班主任考核计划管理', 
    (SELECT id FROM (SELECT * FROM sys_menu) t WHERE t.menu_name = '班主任考核管理' LIMIT 1), 
    3, 'assessmentPlan', 'bzrkh/assessmentPlan/index', '', 1, 0, 'C', '0', '0', 'bzrkh:assessmentPlan:list', 'fa fa-calendar-check-o', 103, 1, NOW(), '班主任考核计划管理菜单');

-- 获取刚插入的菜单ID
SET @menu_id = LAST_INSERT_ID();

-- 插入按钮权限
INSERT INTO sys_menu (tenant_id, menu_name, parent_id, order_num, path, component, query_param, is_frame, is_cache, menu_type, visible, status, perms, icon, create_dept, create_by, create_time, remark) VALUES
('000000', '班主任考核计划查询', @menu_id, 1, '', '', '', 1, 0, 'F', '0', '0', 'bzrkh:assessmentPlan:query', '#', 103, 1, NOW(), ''),
('000000', '班主任考核计划新增', @menu_id, 2, '', '', '', 1, 0, 'F', '0', '0', 'bzrkh:assessmentPlan:add', '#', 103, 1, NOW(), ''),
('000000', '班主任考核计划修改', @menu_id, 3, '', '', '', 1, 0, 'F', '0', '0', 'bzrkh:assessmentPlan:edit', '#', 103, 1, NOW(), ''),
('000000', '班主任考核计划删除', @menu_id, 4, '', '', '', 1, 0, 'F', '0', '0', 'bzrkh:assessmentPlan:remove', '#', 103, 1, NOW(), ''),
('000000', '班主任考核计划导出', @menu_id, 5, '', '', '', 1, 0, 'F', '0', '0', 'bzrkh:assessmentPlan:export', '#', 103, 1, NOW(), '');

权限字符说明

权限字符	权限名称	说明
bzrkh:assessmentPlan:list	考核计划列表	查询考核计划列表的权限
bzrkh:assessmentPlan:query	考核计划查询	查询单个考核计划详情的权限
bzrkh:assessmentPlan:add	考核计划新增	新增考核计划的权限
bzrkh:assessmentPlan:edit	考核计划修改	修改考核计划信息的权限
bzrkh:assessmentPlan:remove	考核计划删除	删除考核计划的权限
bzrkh:assessmentPlan:export	考核计划导出	导出考核计划数据的权限

API接口列表

1. 查询考核计划列表

接口地址: GET /bzrkh/assessmentPlan/list

接口描述: 分页查询班主任考核计划列表

权限要求: bzrkh:assessmentPlan:list

请求参数:

参数名	类型	必填	说明
pageNum	integer	否	页码，默认1
pageSize	integer	否	每页数量，默认10
planName	string	否	计划名称（模糊查询）
planCode	string	否	计划编码（精确查询）
schemeId	integer	否	考核方案ID
academicYear	string	否	学年（模糊查询）
semester	string	否	学期（1=上学期 2=下学期）
planStatus	string	否	计划状态（0=禁用 1=启用）
beginCreateTime	string	否	创建开始时间
endCreateTime	string	否	创建结束时间

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "rows": [
    {
      "id": 1,
      "tenantId": "000000",
      "planName": "2024年上学期班主任考核计划",
      "planCode": "PLAN202401",
      "schemeId": 1,
      "schemeName": "标准考核方案",
      "academicYear": "2023-2024",
      "semester": "1",
      "planStartTime": "2024-01-01 00:00:00",
      "planEndTime": "2024-06-30 23:59:59",
      "dataExtractStartTime": "2024-01-01 00:00:00",
      "dataExtractEndTime": "2024-06-30 23:59:59",
      "planStatus": "1",
      "description": "2024年上学期班主任考核计划",
      "remark": "测试计划",
      "createTime": "2025-01-08 10:00:00"
    }
  ],
  "total": 1
}

2. 获取考核计划详情

接口地址: GET /bzrkh/assessmentPlan/{id}

接口描述: 根据ID获取班主任考核计划详细信息

权限要求: bzrkh:assessmentPlan:query

路径参数:

参数名	类型	必填	说明
id	integer	是	考核计划ID

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "tenantId": "000000",
    "planName": "2024年上学期班主任考核计划",
    "planCode": "PLAN202401",
    "schemeId": 1,
    "academicYear": "2023-2024",
    "semester": "1",
    "planStartTime": "2024-01-01 00:00:00",
    "planEndTime": "2024-06-30 23:59:59",
    "dataExtractStartTime": "2024-01-01 00:00:00",
    "dataExtractEndTime": "2024-06-30 23:59:59",
    "planStatus": "1",
    "description": "2024年上学期班主任考核计划",
    "remark": "测试计划",
    "createTime": "2025-01-08 10:00:00"
  }
}

3. 新增考核计划

接口地址: POST /bzrkh/assessmentPlan

接口描述: 新增班主任考核计划

权限要求: bzrkh:assessmentPlan:add

请求体:

{
  "planName": "2024年下学期班主任考核计划",
  "planCode": "PLAN202402",
  "schemeId": 1,
  "academicYear": "2023-2024",
  "semester": "2",
  "planStartTime": "2024-07-01 00:00:00",
  "planEndTime": "2024-12-31 23:59:59",
  "dataExtractStartTime": "2024-07-01 00:00:00",
  "dataExtractEndTime": "2024-12-31 23:59:59",
  "planStatus": "1",
  "description": "2024年下学期班主任考核计划",
  "remark": "新学期计划"
}

字段验证规则:

字段名	验证规则	说明
planName	必填，长度不超过100	计划名称
planCode	必填，长度不超过50	计划编码，系统内唯一
schemeId	必填	考核方案ID
academicYear	必填，长度不超过10	学年
semester	必填，只能是1或2	学期
planStartTime	必填	计划开始时间
planEndTime	必填	计划结束时间
planStatus	只能是0或1	计划状态
description	长度不超过500	计划描述
remark	长度不超过500	备注

响应示例:

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

4. 修改考核计划

接口地址: PUT /bzrkh/assessmentPlan

接口描述: 修改班主任考核计划

权限要求: bzrkh:assessmentPlan:edit

请求体:

{
  "id": 1,
  "planName": "2024年上学期班主任考核计划（修改）",
  "planCode": "PLAN202401",
  "schemeId": 1,
  "academicYear": "2023-2024",
  "semester": "1",
  "planStartTime": "2024-01-01 00:00:00",
  "planEndTime": "2024-06-30 23:59:59",
  "dataExtractStartTime": "2024-01-01 00:00:00",
  "dataExtractEndTime": "2024-06-30 23:59:59",
  "planStatus": "1",
  "description": "修改后的计划描述",
  "remark": "修改后的备注"
}

响应示例:

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

5. 删除考核计划

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

接口描述: 批量删除班主任考核计划

权限要求: bzrkh:assessmentPlan:remove

路径参数:

参数名	类型	必填	说明
ids	string	是	考核计划ID数组，多个用逗号分隔

响应示例:

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

6. 修改考核计划状态

接口地址: PUT /bzrkh/assessmentPlan/changeStatus

接口描述: 修改班主任考核计划的启用/禁用状态

权限要求: bzrkh:assessmentPlan:edit

请求体:

{
  "id": 1,
  "planStatus": "0"
}

响应示例:

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

7. 导出考核计划

接口地址: POST /bzrkh/assessmentPlan/export

接口描述: 导出班主任考核计划数据

权限要求: bzrkh:assessmentPlan:export

请求体: 与查询列表接口相同的查询条件

响应: Excel文件下载

8. 获取可用考核方案选项

接口地址: GET /bzrkh/assessmentPlan/schemes/options

接口描述: 获取可用的考核方案选项列表

权限要求: bzrkh:assessmentPlan:list

响应示例:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "schemeName": "标准考核方案",
      "schemeCode": "SCHEME001",
      "academicYear": "2023-2024",
      "semester": "1",
      "status": "0"
    }
  ]
}

错误码说明

错误码	错误信息	说明
400	计划编码已存在	计划编码在系统中已存在
400	计划名称不能为空	必填字段校验失败
400	学期只能是1或2	学期字段值不合法
403	无访问权限	用户没有对应的操作权限
404	数据不存在	指定的考核计划不存在

数据字典

学期字典 (sys_semester)

字典值	字典标签	说明
1	上学期	第一学期
2	下学期	第二学期

计划状态字典 (plan_status)

字典值	字典标签	说明
0	禁用	禁用状态
1	启用	启用状态

注意: 此模块使用自定义状态字典，与系统默认的 sys_normal_disable 字典定义相反，严格按照数据库字段设计：plan_status char(1) NOT NULL DEFAULT '1' COMMENT '计划状态（0=禁用 1=启用 ）'

测试用例

1. 正常流程测试

1. 新增考核计划
2. 查询考核计划列表
3. 查看考核计划详情
4. 修改考核计划信息
5. 修改考核计划状态
6. 导出考核计划数据
7. 删除考核计划

2. 异常场景测试

1. 使用重复的计划编码新增计划
2. 使用无效的学期值
3. 删除不存在的计划
4. 无权限用户访问接口

注意事项

1. 计划编码在租户内必须唯一
2. 计划的开始时间不能大于结束时间
3. 数据提取时间不能超出计划时间范围
4. 删除计划前需要检查是否有关联的考核数据
5. 状态为禁用的计划不能执行考核操作

版本更新记录

版本	更新时间	更新内容
v1.0.0	2025-01-08	初始版本，实现基本的CRUD功能