班干部管理API文档

概述

模块名称: 班干部管理
模块标识: xg:classCadre
版本: V1.0.0
创建时间: 2025-01-08
更新时间: 2025-01-08

功能描述

班干部管理模块提供完整的班级干部信息管理功能，包括班干部的任命、免职、调任、续任、辞职等全生命周期管理，以及统计分析和查询功能。

核心功能

基础管理: 班干部信息的增删改查、导入导出
任免操作: 任命、免职、调任、续任、辞职等操作
查询功能: 按班级、学生、职务等多维度查询
统计分析: 班干部统计数据和图表分析
权限控制: 完整的角色权限管理

API接口列表

基础管理接口

1. 获取班干部列表

GET /xg-xx/classCadre/list

权限要求: xg:classCadre:list

请求参数:

{
  "pageNum": 1,
  "pageSize": 10,
  "studentId": "学生ID",
  "classId": "班级ID",
  "positionId": "职务ID",
  "positionLevel": "职务级别",
  "status": "任职状态",
  "isCurrent": "是否现任",
  "startDate": "开始日期",
  "endDate": "结束日期"
}

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": "1234567890123456789",
      "studentId": "1001",
      "studentName": "张三",
      "classId": "C001",
      "className": "计算机一班",
      "positionId": "P001",
      "positionName": "班长",
      "positionLevel": 1,
      "status": "在任",
      "isCurrent": true,
      "startDate": "2024-09-01",
      "endDate": "2025-07-01",
      "termMonths": 10,
      "workPerformance": "优秀",
      "phoneNumber": "13800138000",
      "email": "zhangsan@example.com",
      "createTime": "2024-09-01 10:00:00"
    }
  ],
  "total": 100
}

2. 获取班干部详情

GET /xg-xx/classCadre/{id}

权限要求: xg:classCadre:query

路径参数:

id: 班干部记录ID

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": "1234567890123456789",
    "studentId": "1001",
    "studentName": "张三",
    "classId": "C001",
    "className": "计算机一班",
    "positionId": "P001",
    "positionName": "班长",
    "positionLevel": 1,
    "status": "在任",
    "isCurrent": true,
    "startDate": "2024-09-01",
    "endDate": "2025-07-01",
    "termMonths": 10,
    "workPerformance": "优秀",
    "phoneNumber": "13800138000",
    "email": "zhangsan@example.com",
    "responsibilities": "负责班级日常管理工作",
    "permissions": "班级活动组织权限",
    "createTime": "2024-09-01 10:00:00"
  }
}

3. 新增班干部

POST /xg-xx/classCadre

权限要求: xg:classCadre:add

请求体:

{
  "studentId": "1001",
  "classId": "C001",
  "positionId": "P001",
  "startDate": "2024-09-01",
  "endDate": "2025-07-01",
  "termMonths": 10,
  "workPerformance": "良好",
  "phoneNumber": "13800138000",
  "email": "zhangsan@example.com",
  "responsibilities": "负责班级日常管理工作",
  "permissions": "班级活动组织权限",
  "remark": "备注信息"
}

响应示例:

{
  "code": 200,
  "msg": "新增成功"
}

4. 修改班干部

PUT /xg-xx/classCadre

权限要求: xg:classCadre:edit

请求体:

{
  "id": "1234567890123456789",
  "studentId": "1001",
  "classId": "C001",
  "positionId": "P001",
  "startDate": "2024-09-01",
  "endDate": "2025-07-01",
  "termMonths": 10,
  "workPerformance": "优秀",
  "phoneNumber": "13800138000",
  "email": "zhangsan@example.com",
  "responsibilities": "负责班级日常管理工作",
  "permissions": "班级活动组织权限",
  "remark": "备注信息"
}

5. 删除班干部

DELETE /xg-xx/classCadre/{ids}

权限要求: xg:classCadre:remove

路径参数:

ids: 班干部记录ID，多个用逗号分隔

6. 导出班干部数据

POST /xg-xx/classCadre/export

权限要求: xg:classCadre:export

请求体: 同列表查询参数

响应: Excel文件下载

业务功能接口

7. 按班级查询班干部

GET /xg-xx/classCadre/listByClass/{classId}

权限要求: xg:classCadre:queryByClass

路径参数:

classId: 班级ID

8. 按学生查询班干部

GET /xg-xx/classCadre/listByStudent/{studentId}

权限要求: xg:classCadre:queryByStudent

路径参数:

studentId: 学生ID

9. 按职务查询班干部

GET /xg-xx/classCadre/listByPosition/{positionId}

权限要求: xg:classCadre:queryByPosition

路径参数:

positionId: 职务ID

10. 获取我的班干部信息

GET /xg-xx/classCadre/myInfo

权限要求: xg:classCadre:query

11. 获取待处理任务

GET /xg-xx/classCadre/pendingTasks

权限要求: xg:classCadre:query

12. 获取可用职务选项

GET /xg-xx/classCadre/availablePositions

权限要求: xg:classCadre:query

任免操作接口

13. 任命班干部

POST /xg-xx/classCadre/appoint

权限要求: xg:classCadre:appoint

请求体:

{
  "studentId": "1001",
  "classId": "C001",
  "positionId": "P001",
  "startDate": "2024-09-01",
  "endDate": "2025-07-01",
  "reason": "任命原因",
  "remark": "备注信息"
}

14. 免职班干部

POST /xg-xx/classCadre/dismiss

权限要求: xg:classCadre:dismiss

请求体:

{
  "id": "1234567890123456789",
  "reason": "免职原因",
  "effectiveDate": "2024-12-01",
  "remark": "备注信息"
}

15. 调任班干部

POST /xg-xx/classCadre/transfer

权限要求: xg:classCadre:transfer

请求体:

{
  "id": "1234567890123456789",
  "newPositionId": "P002",
  "reason": "调任原因",
  "effectiveDate": "2024-12-01",
  "remark": "备注信息"
}

16. 续任班干部

POST /xg-xx/classCadre/renew

权限要求: xg:classCadre:renew

请求体:

{
  "id": "1234567890123456789",
  "newEndDate": "2025-12-01",
  "reason": "续任原因",
  "remark": "备注信息"
}

17. 辞职申请

POST /xg-xx/classCadre/resign

权限要求: xg:classCadre:resign

请求体:

{
  "id": "1234567890123456789",
  "reason": "辞职原因",
  "effectiveDate": "2024-12-01",
  "remark": "备注信息"
}

统计查询接口

18. 获取统计数据

GET /xg-xx/classCadre/statistics

权限要求: xg:classCadre:statistics

请求参数:

{
  "collegeId": "学院ID",
  "gradeId": "年级ID",
  "startDate": "开始日期",
  "endDate": "结束日期"
}

响应示例:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "totalCount": 500,
    "currentCount": 450,
    "excellentCount": 200,
    "expiringSoonCount": 50,
    "positionDistribution": [
      {"positionName": "班长", "count": 50},
      {"positionName": "副班长", "count": 45}
    ],
    "statusDistribution": [
      {"status": "在任", "count": 450},
      {"status": "已免职", "count": 30}
    ],
    "collegeStatistics": [
      {"collegeName": "计算机学院", "count": 100},
      {"collegeName": "机械学院", "count": 80}
    ]
  }
}

19. 获取按学院统计

GET /xg-xx/classCadre/statisticsByCollege

权限要求: xg:classCadre:statistics

20. 获取按年级统计

GET /xg-xx/classCadre/statisticsByGrade

权限要求: xg:classCadre:statistics

21. 获取到期提醒

GET /xg-xx/classCadre/expiringReminder

权限要求: xg:classCadre:expireReminder

请求参数:

{
  "days": 30
}

辅助功能接口

22. 批量操作

POST /xg-xx/classCadre/batch

权限要求: xg:classCadre:batch

请求体:

{
  "operation": "dismiss",
  "ids": ["id1", "id2", "id3"],
  "reason": "批量操作原因",
  "effectiveDate": "2024-12-01"
}

23. 数据校验

POST /xg-xx/classCadre/validate

权限要求: xg:classCadre:validate

请求体:

{
  "studentId": "1001",
  "classId": "C001",
  "positionId": "P001",
  "startDate": "2024-09-01",
  "endDate": "2025-07-01"
}

数据模型

班干部信息 (XgClassCadre)

字段名	类型	说明	必填
id	Long	主键ID	是
studentId	String	学生ID	是
studentName	String	学生姓名	是
classId	String	班级ID	是
className	String	班级名称	是
positionId	String	职务ID	是
positionName	String	职务名称	是
positionLevel	Integer	职务级别	是
status	String	任职状态	是
isCurrent	Boolean	是否现任	是
startDate	Date	任职开始日期	是
endDate	Date	任职结束日期	否
termMonths	Integer	任期月数	否
workPerformance	String	工作表现	否
phoneNumber	String	联系电话	否
email	String	邮箱地址	否
responsibilities	String	职责描述	否
permissions	String	权限描述	否
remark	String	备注	否

班干部变更记录 (XgCadreChangeLog)

字段名	类型	说明	必填
id	Long	主键ID	是
cadreId	Long	班干部ID	是
operationType	String	操作类型	是
oldPositionId	String	原职务ID	否
newPositionId	String	新职务ID	否
reason	String	变更原因	否
effectiveDate	Date	生效日期	是
operatorId	Long	操作人ID	是
operatorName	String	操作人姓名	是
remark	String	备注	否

班干部职务配置 (XgCadrePositionConfig)

字段名	类型	说明	必填
id	Long	主键ID	是
positionCode	String	职务代码	是
positionName	String	职务名称	是
positionLevel	Integer	职务级别	是
maxCount	Integer	最大人数	是
responsibilities	String	职责描述	否
permissions	String	权限描述	否
isActive	Boolean	是否启用	是
sortOrder	Integer	排序	是
remark	String	备注	否

状态码说明

任职状态 (status)

draft: 草稿
waiting: 待审核
complete: 在任
expired: 已到期
dismissed: 已免职
transferred: 已调任
resigned: 已辞职

操作类型 (operationType)

appoint: 任命
dismiss: 免职
transfer: 调任
renew: 续任
resign: 辞职
modify: 修改

工作表现 (workPerformance)

excellent: 优秀
good: 良好
average: 一般
poor: 较差

权限说明

角色权限分配

角色	权限范围	说明
超级管理员	全部权限	所有操作权限
学生处管理员	全部权限	所有操作权限
二级学院管理员	除删除外的权限	不能删除班干部记录
辅导员	基础管理和任免权限	可进行班干部任免操作
班级教师	查看和统计权限	只能查看相关信息
学生	仅查看权限	只能查看班干部信息

权限标识列表

权限标识	权限名称	说明
xg:classCadre:list	班干部列表	查看班干部列表
xg:classCadre:query	班干部查询	查询班干部详情
xg:classCadre:add	班干部新增	新增班干部
xg:classCadre:edit	班干部修改	修改班干部信息
xg:classCadre:remove	班干部删除	删除班干部记录
xg:classCadre:export	班干部导出	导出班干部数据
xg:classCadre:import	班干部导入	导入班干部数据
xg:classCadre:appoint	班干部任命	任命班干部
xg:classCadre:dismiss	班干部免职	免职班干部
xg:classCadre:transfer	班干部调任	调任班干部
xg:classCadre:renew	班干部续任	续任班干部
xg:classCadre:resign	班干部辞职	辞职申请
xg:classCadre:statistics	统计查看	查看统计数据
xg:classCadre:batch	批量操作	批量处理
xg:classCadre:validate	数据校验	数据有效性校验

错误码说明

错误码	错误信息	说明
40001	学生不存在	指定的学生ID不存在
40002	班级不存在	指定的班级ID不存在
40003	职务不存在	指定的职务ID不存在
40004	学生已担任该职务	学生已经担任该职务
40005	职务人数已满	该职务已达到最大人数限制
40006	任职日期冲突	任职时间与现有记录冲突
40007	班干部记录不存在	指定的班干部记录不存在
40008	操作权限不足	当前用户没有操作权限
40009	数据校验失败	提交的数据不符合规则
40010	批量操作失败	批量操作部分失败

使用示例

1. 查询班级班干部

// 查询计算机一班的所有班干部
const response = await api.get('/xg-xx/classCadre/listByClass/C001');
console.log(response.data);

2. 任命班干部

// 任命张三为班长
const appointData = {
  studentId: '1001',
  classId: 'C001',
  positionId: 'P001',
  startDate: '2024-09-01',
  endDate: '2025-07-01',
  reason: '综合表现优秀，具备领导能力'
};
const response = await api.post('/xg-xx/classCadre/appoint', appointData);

3. 获取统计数据

// 获取计算机学院的班干部统计
const response = await api.get('/xg-xx/classCadre/statistics', {
  params: { collegeId: 'COL001' }
});
console.log(response.data);

注意事项

数据一致性: 班干部信息与学生信息、班级信息保持一致
权限控制: 严格按照角色权限进行操作控制
变更记录: 所有重要操作都会记录变更日志
任期管理: 注意任期时间的合理性和连续性
状态管理: 正确维护班干部的任职状态
并发控制: 防止同时操作导致的数据冲突

更新日志

版本	日期	更新内容
V1.0.0	2025-01-08	初始版本，完整的班干部管理API

文档维护: Cursor AI 辅助
最后更新: 2025-01-08
文档状态: 已完成

班干部管理API.md 14 KB Historie Surový

班干部管理API文档

概述

功能描述

核心功能

API接口列表

基础管理接口

1. 获取班干部列表

2. 获取班干部详情

3. 新增班干部

4. 修改班干部

5. 删除班干部

6. 导出班干部数据

业务功能接口

7. 按班级查询班干部

8. 按学生查询班干部

9. 按职务查询班干部

10. 获取我的班干部信息

11. 获取待处理任务

12. 获取可用职务选项

任免操作接口

13. 任命班干部

14. 免职班干部

15. 调任班干部

16. 续任班干部

17. 辞职申请

统计查询接口

18. 获取统计数据

19. 获取按学院统计

20. 获取按年级统计

21. 获取到期提醒

辅助功能接口

22. 批量操作

23. 数据校验

数据模型

班干部信息 (XgClassCadre)

班干部变更记录 (XgCadreChangeLog)

班干部职务配置 (XgCadrePositionConfig)

状态码说明

任职状态 (status)

操作类型 (operationType)

工作表现 (workPerformance)

权限说明

角色权限分配

权限标识列表

错误码说明

使用示例

1. 查询班级班干部

2. 任命班干部

3. 获取统计数据

注意事项

更新日志

班干部管理API.md 14 KB

Historie Surový