cykj/hzdyjs

0 Fork 0

Files

T

zlwu 61f681c339 提交班干部管理

2025-07-29 16:37:42 +08:00

13 KiB

Raw Blame History

班级干部信息管理API文档

📋 文档信息

项目	信息
模块名称	班级干部信息管理
模块代码	ruoyi-xg
基础路径	`/xgClassPosMsg/xgClassPosMsg`
权限前缀	`xgClassPosMsg:xgClassPosMsg`
版本	V1.0.0
创建时间	2025-01-27
更新时间	2025-01-27

🎯 API概述

模块说明

班级干部信息管理模块提供完整的班级干部信息管理功能，包括班级干部的任命、任期管理、状态跟踪等全生命周期管理，以及用户角色关联功能。

技术规范

认证方式: Bearer Token (Sa-Token)
数据格式: JSON
响应格式: 统一使用R类型或TableDataInfo分页格式
权限控制: 基于角色的权限管理(RBAC)

核心特性

基础管理: 班级干部信息的增删改查、导入导出
任期管理: 任职日期、任期时长、到期提醒
状态跟踪: 在任、到期、辞职、免职、调任、休学等状态
用户角色关联: 自动建立学生与角色的关联关系
数据权限: 支持按部门查询班级干部信息

📊 数据模型

班级干部信息VO (XgClassPosMsgVo)

{
  "id": 1,                           // 主键ID（雪花ID）
  "deleted": 0,                      // 删除标志（0代表存在 1代表删除）
  "classId": 101,                    // 班级ID，关联xg_class_msg.id
  "className": "计算机2023-1班",      // 班级名称（联表查询获取）
  "studentId": 1001,                 // 学生ID，关联xg_student_msg.id
  "studentNo": "2023001",            // 学号
  "studentName": "张三",              // 学生姓名（冗余字段）
  "positionCode": "monitor",         // 职务编码，关联xg_class_pos_dict.position_code
  "positionName": "班长",             // 职务名称（联表查询获取）
  "appointmentDate": "2024-09-01",   // 任职日期
  "termStartDate": "2024-09-01",     // 任期开始日期
  "termEndDate": "2025-07-01",       // 任期结束日期
  "termDuration": 10,                // 任期时长（月）
  "isCurrent": 1,                    // 是否现任：0-否，1-是
  "cadreStatus": "1",                // 学生职务任职状态：1-在任，2-到期，3-辞职，4-免职，5-调任，6-休学
  "appointmentReason": "综合表现优秀", // 任命原因
  "appointmentMethod": "appointment", // 学生职务任命方式：appointment-任命，election-选举，recommendation-推荐
  "dismissalDate": null,             // 离任日期
  "dismissalReason": null,           // 离任原因
  "remark": "备注信息",               // 备注信息
  "createBy": 1,                     // 创建者
  "createTime": "2024-09-01 10:00:00", // 创建时间
  "updateBy": 1,                     // 更新者
  "updateTime": "2024-09-01 10:00:00"  // 更新时间
}

🔧 API接口列表

1. 基础管理接口

1.1 查询班级干部信息列表

接口路径: GET /xgClassPosMsg/xgClassPosMsg/list
权限标识: xgClassPosMsg:xgClassPosMsg:list
功能描述: 分页查询班级干部信息列表，支持按部门查询

请求参数:

参数名	类型	必填	说明
pageNum	integer	否	页码，默认1
pageSize	integer	否	每页大小，默认10
deptId	long	否	部门ID，用于按部门查询班级干部信息
classId	long	否	班级ID
studentId	long	否	学生ID
studentNo	string	否	学号（模糊查询）
studentName	string	否	学生姓名（模糊查询）
positionCode	string	否	职务编码
appointmentDate	string	否	任职日期
termStartDate	string	否	任期开始日期
termEndDate	string	否	任期结束日期
termDuration	integer	否	任期时长（月）
isCurrent	integer	否	是否现任：0-否，1-是
cadreStatus	string	否	学生职务任职状态
appointmentReason	string	否	任命原因
appointmentMethod	string	否	学生职务任命方式
dismissalDate	string	否	离任日期
dismissalReason	string	否	离任原因

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "rows": [
    {
      "id": 1,
      "classId": 101,
      "className": "计算机2023-1班",
      "studentId": 1001,
      "studentNo": "2023001",
      "studentName": "张三",
      "positionCode": "monitor",
      "positionName": "班长",
      "appointmentDate": "2024-09-01",
      "termStartDate": "2024-09-01",
      "termEndDate": "2025-07-01",
      "termDuration": 10,
      "isCurrent": 1,
      "cadreStatus": "1",
      "appointmentReason": "综合表现优秀",
      "appointmentMethod": "appointment",
      "createTime": "2024-09-01 10:00:00"
    }
  ],
  "total": 1
}

1.2 获取班级干部信息详情

接口路径: GET /xgClassPosMsg/xgClassPosMsg/{id}
权限标识: xgClassPosMsg:xgClassPosMsg:query
功能描述: 根据主键获取班级干部信息详细信息

请求参数:

参数名	类型	必填	说明
id	long	是	主键ID

响应数据:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "id": 1,
    "classId": 101,
    "className": "计算机2023-1班",
    "studentId": 1001,
    "studentNo": "2023001",
    "studentName": "张三",
    "positionCode": "monitor",
    "positionName": "班长",
    "appointmentDate": "2024-09-01",
    "termStartDate": "2024-09-01",
    "termEndDate": "2025-07-01",
    "termDuration": 10,
    "isCurrent": 1,
    "cadreStatus": "1",
    "appointmentReason": "综合表现优秀",
    "appointmentMethod": "appointment",
    "dismissalDate": null,
    "dismissalReason": null,
    "remark": "备注信息",
    "createTime": "2024-09-01 10:00:00",
    "updateTime": "2024-09-01 10:00:00"
  }
}

1.3 新增班级干部信息

接口路径: POST /xgClassPosMsg/xgClassPosMsg
权限标识: xgClassPosMsg:xgClassPosMsg:add
功能描述: 新增班级干部信息，同时自动建立用户角色关联

请求参数:

{
  "classId": 101,
  "studentId": 1001,
  "studentNo": "2023001",
  "studentName": "张三",
  "positionCode": "monitor",
  "appointmentDate": "2024-09-01",
  "termStartDate": "2024-09-01",
  "termEndDate": "2025-07-01",
  "termDuration": 10,
  "isCurrent": 1,
  "cadreStatus": "1",
  "appointmentReason": "综合表现优秀",
  "appointmentMethod": "appointment",
  "remark": "备注信息"
}

响应数据:

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

重要说明:

新增班级干部信息时，系统会自动向 sys_user_role 表插入一条数据
user_id = 当前记录的 studentId
role_id = 当前记录的 id（班级干部信息ID）
此操作在事务中进行，确保数据一致性

1.4 修改班级干部信息

接口路径: PUT /xgClassPosMsg/xgClassPosMsg
权限标识: xgClassPosMsg:xgClassPosMsg:edit
功能描述: 修改班级干部信息

请求参数:

{
  "id": 1,
  "classId": 101,
  "studentId": 1001,
  "studentNo": "2023001",
  "studentName": "张三",
  "positionCode": "monitor",
  "appointmentDate": "2024-09-01",
  "termStartDate": "2024-09-01",
  "termEndDate": "2025-07-01",
  "termDuration": 10,
  "isCurrent": 1,
  "cadreStatus": "1",
  "appointmentReason": "综合表现优秀",
  "appointmentMethod": "appointment",
  "remark": "修改后的备注信息"
}

响应数据:

{
  "code": 200,
  "msg": "修改成功"
}

1.5 删除班级干部信息

接口路径: DELETE /xgClassPosMsg/xgClassPosMsg/{ids}
权限标识: xgClassPosMsg:xgClassPosMsg:remove
功能描述: 删除班级干部信息（支持批量删除），同时删除对应的用户角色关联

请求参数:

参数名	类型	必填	说明
ids	string	是	主键ID，多个用逗号分隔

响应数据:

{
  "code": 200,
  "msg": "删除成功"
}

重要说明:

删除班级干部信息时，系统会自动删除 sys_user_role 表中对应的角色关联
删除操作会先清理关联数据，再删除主数据
此操作在事务中进行，确保数据一致性

1.6 导出班级干部信息

接口路径: POST /xgClassPosMsg/xgClassPosMsg/export
权限标识: xgClassPosMsg:xgClassPosMsg:export
功能描述: 导出班级干部信息列表

请求参数: 同列表查询参数

响应数据: Excel文件下载

🔐 用户角色关联功能

功能说明

班级干部信息管理模块集成了用户角色关联功能，确保班级干部信息与系统权限管理的一致性。

关联规则

新增关联: 新增班级干部信息时，自动建立用户角色关联
- sys_user_role.user_id = xg_class_pos_msg.student_id
- sys_user_role.role_id = xg_class_pos_msg.id
删除关联: 删除班级干部信息时，自动删除对应的用户角色关联
- 根据 role_id 删除 sys_user_role 表中的记录

事务处理

所有用户角色关联操作都在事务中进行
关联操作失败不会影响主业务流程，但会记录警告日志
使用 @Transactional(rollbackFor = Exception.class) 确保数据一致性

异常处理

用户角色关联操作异常会被捕获并记录日志
不会抛出异常影响主业务流程
通过日志记录操作结果和异常信息

📝 数据字典

学生职务任职状态 (cadre_status)

编码	名称	说明
1	在任	正常任职状态
2	到期	任期已结束
3	辞职	主动辞职
4	免职	被免职
5	调任	调任其他职务
6	休学	因休学暂停职务

学生职务任命方式 (appointment_method)

编码	名称	说明
appointment	任命	直接任命
election	选举	通过选举产生
recommendation	推荐	通过推荐产生

是否现任 (is_current)

编码	名称	说明
0	否	非现任职务
1	是	现任职务

🔒 权限说明

权限标识列表

权限标识	权限名称	说明
xgClassPosMsg:xgClassPosMsg:list	班级干部信息列表	查看班级干部信息列表
xgClassPosMsg:xgClassPosMsg:query	班级干部信息查询	查询班级干部信息详情
xgClassPosMsg:xgClassPosMsg:add	班级干部信息新增	新增班级干部信息
xgClassPosMsg:xgClassPosMsg:edit	班级干部信息修改	修改班级干部信息
xgClassPosMsg:xgClassPosMsg:remove	班级干部信息删除	删除班级干部信息
xgClassPosMsg:xgClassPosMsg:export	班级干部信息导出	导出班级干部信息

数据权限

支持按部门查询班级干部信息
通过 deptId 参数控制数据权限范围
自动包含子部门的数据

🚨 错误码说明

错误码	错误信息	说明
40001	学生不存在	指定的学生ID不存在
40002	班级不存在	指定的班级ID不存在
40003	职务不存在	指定的职务编码不存在
40004	学生已担任该职务	学生已经担任该职务
40005	班级干部记录不存在	指定的班级干部记录不存在
40006	操作权限不足	当前用户没有操作权限
40007	数据校验失败	提交的数据不符合规则
40008	用户角色关联失败	用户角色关联操作失败

📋 使用示例

1. 查询班级干部信息

// 查询指定部门的班级干部信息
const response = await api.get('/xgClassPosMsg/xgClassPosMsg/list', {
  params: {
    deptId: 101,
    pageNum: 1,
    pageSize: 10
  }
});
console.log(response.data);

2. 新增班级干部

// 新增班级干部信息
const addData = {
  classId: 101,
  studentId: 1001,
  studentNo: "2023001",
  studentName: "张三",
  positionCode: "monitor",
  appointmentDate: "2024-09-01",
  termStartDate: "2024-09-01",
  termEndDate: "2025-07-01",
  termDuration: 10,
  isCurrent: 1,
  cadreStatus: "1",
  appointmentReason: "综合表现优秀",
  appointmentMethod: "appointment"
};
const response = await api.post('/xgClassPosMsg/xgClassPosMsg', addData);

3. 删除班级干部

// 删除班级干部信息
const response = await api.delete('/xgClassPosMsg/xgClassPosMsg/1,2,3');

⚠️ 注意事项

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

📈 更新日志

版本	日期	更新内容
V1.0.0	2025-01-27	初始版本，完整的班级干部信息管理API
V1.0.1	2025-01-27	新增用户角色关联功能

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

13 KiB Raw Blame History Unescape Escape

班级干部信息管理API文档

📋 文档信息

🎯 API概述

模块说明

技术规范

核心特性

📊 数据模型

班级干部信息VO (XgClassPosMsgVo)

🔧 API接口列表

1. 基础管理接口

1.1 查询班级干部信息列表

1.2 获取班级干部信息详情

1.3 新增班级干部信息

1.4 修改班级干部信息

1.5 删除班级干部信息

1.6 导出班级干部信息

🔐 用户角色关联功能

功能说明

关联规则

事务处理

异常处理

📝 数据字典

学生职务任职状态 (cadre_status)

学生职务任命方式 (appointment_method)

是否现任 (is_current)

🔒 权限说明

权限标识列表

数据权限

🚨 错误码说明

📋 使用示例

1. 查询班级干部信息

2. 新增班级干部

3. 删除班级干部

⚠️ 注意事项

📈 更新日志

13 KiB

Raw Blame History