12 KiB
12 KiB
RailwaySystem 权限字符与业务错误码规范
设计依据： 全面沿用若依成熟的 RBAC 权限控制体系与全局异常拦截机制。 实施原则： 权限字符标准化归一为
train:*前缀；错误码统一收敛并与若依ServiceException及AjaxResult深度融合，拒绝重复造轮子。 Review Round 1 修订： 严禁引入任何硬编码的“不及格/不合格结业”阻断错误码；报到逾期错误码调整为生命周期时限告警。
1. 权限编码规范 (RuoYi RBAC)
系统一期主要服务于三类角色：培训管理员 (admin)、任课教师 (teacher)、参训学员 (student)。
所有 API 严格通过 @PreAuthorize("@ss.hasPermi('train:xxx:xxx')") 进行鉴权拦截。
1.1 Module A：人员与基础资源权限 (23 个权限字符)
| 权限字符 | 权限名称 | 对应主要 API | 适用角色 |
|---|---|---|---|
train:teacher:list |
教师查询/导出 | GET /train/teacher/list |
管理员, 教师 |
train:teacher:query |
教师详情 | GET /train/teacher/{tId} |
管理员, 教师 |
train:teacher:add |
教师新增 | POST /train/teacher |
管理员 |
train:teacher:edit |
教师修改/启停用 | PUT /train/teacher/{tId} |
管理员 |
train:student:list |
学员库查询 | GET /train/student/list |
管理员 |
train:student:query |
学员详情 | GET /train/student/{sId} |
管理员 |
train:student:add |
学员单条录入 | POST /train/student |
管理员 |
train:student:edit |
学员档案修改 | PUT /train/student/{sId} |
管理员 |
train:student:import |
学员Excel导入 | POST /train/student/import |
管理员 |
train:course:list |
课程库列表 | GET /train/course/list |
管理员, 教师 |
train:course:query |
课程详情 | GET /train/course/{cId} |
管理员, 教师 |
train:course:add |
课程新增 | POST /train/course |
管理员 |
train:course:edit |
课程修改/绑资源 | PUT /train/course/{cId} |
管理员 |
train:resource:list |
教学资源列表 | GET /train/resource/list |
管理员, 教师 |
train:resource:edit |
教学资源增删改 | POST/PUT/DELETE /train/resource |
管理员 |
train:classroom:list |
教室列表 | GET /train/classroom/list |
管理员, 教师 |
train:classroom:edit |
教室维护 | POST/PUT /train/classroom |
管理员 |
train:site:list |
实训场地列表 | GET /train/training-site/list |
管理员, 教师 |
train:site:edit |
实训场地维护 | POST/PUT /train/training-site |
管理员 |
train:board:list |
电子班牌查询 | GET /train/electronic-board/list |
管理员 |
train:board:edit |
电子班牌注册维护 | POST/PUT /train/electronic-board |
管理员 |
train:dormitory:list |
宿舍房间/房态查询 | GET /train/dormitory/list |
管理员, 宿管 |
train:dormitory:edit |
宿舍房间维护 | POST/PUT /train/dormitory |
管理员, 宿管 |
1.2 Module B：开班计划与排课权限 (17 个权限字符)
| 权限字符 | 权限名称 | 对应主要 API | 适用角色 |
|---|---|---|---|
train:plan:list |
培训计划列表 | GET /train/plans |
管理员, 教师 |
train:plan:query |
计划详情/工作台/课表 | GET /train/plans/{planId}/* |
管理员, 教师 |
train:plan:add |
创建培训计划 | POST /train/plans |
管理员 |
train:plan:edit |
编辑培训计划/配课 | PUT /train/plans/{planId}, POST /courses |
管理员 |
train:plan:complete |
结束培训计划 | POST /train/plans/{planId}/complete |
管理员 |
train:enrollment:list |
参训名单查询 | GET /train/plans/{planId}/enrollments |
管理员, 教师 |
train:enrollment:query |
参训档案详情 | GET /train/enrollments/{enrollmentId} |
管理员 |
train:enrollment:add |
添加参训人员 | POST /train/plans/{planId}/enrollments |
管理员 |
train:enrollment:import |
Excel批量导入参训人员 | POST /train/plans/{planId}/enrollments/batch |
管理员 |
train:enrollment:edit |
修改参训状态 | PUT /train/enrollments/{enrollmentId}/status |
管理员 |
train:enrollment:remove |
移除参训人员 | DELETE /train/enrollments/{enrollmentId} |
管理员 |
train:lesson:query |
课次详情/冲突预检 | POST /train/lessons/check-conflict |
管理员, 教师 |
train:lesson:add |
新增课次排课 | POST /train/plans/{planId}/lessons |
管理员 |
train:lesson:edit |
修改课次排课 | PUT /train/lessons/{lessonId} |
管理员 |
train:lesson:remove |
删除课次 | DELETE /train/lessons/{lessonId} |
管理员 |
train:report:confirm |
学员报到确认 | POST /train/enrollments/{enrollmentId}/report |
管理员, 学员自助 |
train:report:list |
报到记录列表 | GET /train/plans/{planId}/reports |
管理员 |
1.3 Module C：住宿、门禁与考勤权限 (8 个权限字符)
| 权限字符 | 权限名称 | 对应主要 API | 适用角色 |
|---|---|---|---|
train:accommodation:list |
住宿安排查看 | GET /train/plans/{planId}/accommodations |
管理员, 宿管 |
train:accommodation:assign |
批量预分配宿舍 | POST /train/plans/{planId}/accommodations/preallocate |
管理员, 宿管 |
train:accommodation:adjust |
单人调房/走读设置 | PUT /train/enrollments/{enrollmentId}/accommodation* |
管理员, 宿管 |
train:dormauth:list |
门禁状态查询 | GET /train/plans/{planId}/dorm-auths |
管理员, 宿管 |
train:dormauth:sync |
门禁授权同步/重试 | POST /train/accommodations/{accommodationId}/auth/sync |
管理员 |
train:attendance:list |
考勤查询 | GET /train/lessons/{lessonId}/attendance |
管理员, 教师 |
train:attendance:checkin |
课次打卡签到/签退 | POST /train/attendance/sign-in, sign-out |
班牌回调, 教师 |
train:attendance:edit |
人工修正/补录考勤 | PUT /train/attendance/{checkinId}, POST /manual-add |
管理员, 教师 |
1.4 Module D：成绩、学习、统计与画像权限 (8 个权限字符)
| 权限字符 | 权限名称 | 对应主要 API | 适用角色 |
|---|---|---|---|
train:score:query |
成绩查询/台账矩阵 | GET /train/plans/{planId}/scores/matrix |
管理员, 教师 |
train:score:config |
配置成绩项目与权重 | POST /train/plans/{planId}/score-items |
管理员 |
train:score:edit |
录入单条/批量成绩 | POST /train/scores/entry |
管理员, 教师 |
train:score:import |
Excel批量导入成绩 | POST /train/plans/{planId}/scores/import |
管理员, 教师 |
train:learning:list |
学习记录列表查询 | GET /train/plans/{planId}/study-records |
管理员, 教师 |
train:statistics:query |
统计概览/下钻分析 | GET /train/plans/{planId}/statistics/* |
管理员, 领导 |
train:portrait:query |
学员画像查询 | GET /train/enrollments/{enrollmentId}/portrait |
管理员, 教师, 学员 |
train:portrait:generate |
刷新/生成学员画像 | POST /train/enrollments/{enrollmentId}/portrait/generate |
管理员 |
2. 统一业务错误码模型字典 (40000 ~ 40999)
系统全面兼容若依的 ServiceException 体系。后端业务校验不通过时，统一抛出带有特定错误码的 ServiceException，由若依框架现有的 GlobalExceptionHandler 统一捕获，转换输出为标准的 AjaxResult.error(code, msg)。
| 错误码 | 常量定义 | 默认错误提示信息 | 对应模块/用例 |
|---|---|---|---|
| 40001 | TEACHER_PHONE_DUPLICATED |
教师手机号码已存在 | 教师管理 |
| 40002 | STUDENT_IDCARD_DUPLICATED |
学员身份证号已建档，不可重复录入 | 学员管理 |
| 40003 | COURSE_CODE_DUPLICATED |
课程编码已存在 | 课程库 |
| 40004 | RESOURCE_IN_USE |
该教学资源已被课程引用，无法删除 | 教学资源 |
| 40005 | BOARD_SN_DUPLICATED |
电子班牌 SN 设备编号已存在 | 电子班牌 |
| 40006 | DORM_ROOM_DUPLICATED |
同一楼栋下该宿舍房号已存在 | 宿舍房间 |
| 40007 | DORM_CAPACITY_CANNOT_SHRINK |
房间容量不可调整至小于当前已入住人数 | 宿舍房间 |
| 40008 | CLASSROOM_NAME_DUPLICATED |
教室名称已存在 | 教室 |
| 40009 | SITE_NAME_DUPLICATED |
实训场地名称已存在 | 实训场地 |
| 40010 | PLAN_TIME_INVALID |
培训计划起止时间不合法 (结束时间必须晚于开始时间) | 开班计划 (UC-01) |
| 40011 | PLAN_NAME_DUPLICATED |
同名培训计划已存在 | 开班计划 (UC-01) |
| 40012 | PLAN_STATUS_LOCKED |
当前培训计划已结训或取消，不允许修改 | 开班计划 (UC-02) |
| 40013 | PLAN_LESSON_OUT_OF_BOUNDS |
调整培训时间导致现有已排课次超出计划周期 | 开班计划 (UC-02) |
| 40014 | PLAN_ALREADY_COMPLETED |
培训计划已经结训，不可重复执行结训 | 开班计划 (UC-29) |
| 40020 | PLAN_COURSE_DUPLICATED |
该课程已添加到本期培训计划中 | 课程配置 (UC-03) |
| 40021 | PLAN_COURSE_HAS_LESSONS |
该课程已排定课次，请先删除关联课次后再移除课程 | 课程配置 |
| 40022 | PLAN_COURSE_HAS_SCORE_ITEMS |
该课程已关联成绩考核项目，不可直接移除 | 课程配置 |
| 40030 | ENROLLMENT_DUPLICATED |
该学员已在本班参训名单中，不可重复添加 | 参训管理 (UC-04) |
| 40031 | RECRUIT_LIMIT_EXCEEDED |
参训人数已超出本期计划招生上限 | 参训管理 (UC-04) |
| 40032 | ENROLLMENT_HAS_BUSINESS_DATA |
该学员已产生考勤或成绩数据，不可删除参训档案 | 参训管理 |
| 40040 | LESSON_TEACHER_CONFLICT |
教师排课时间冲突：该教师在指定时段已有其他教学任务 | 排课冲突 (UC-07/10) |
| 40041 | LESSON_CLASSROOM_CONFLICT |
教室排课时间冲突：该教室在指定时段已被占用 | 排课冲突 (UC-07/10) |
| 40042 | LESSON_SITE_CONFLICT |
实训场地排课时间冲突：该实训场地在指定时段已被占用 | 排课冲突 (UC-07/10) |
| 40043 | LESSON_PLAN_OVERLAP |
本班课次时间重叠：同一培训班不可在同一时段上多门课 | 排课冲突 (UC-07/10) |
| 40044 | LESSON_ALREADY_HAS_ATTENDANCE |
该课次已有学员签到打卡，禁止修改上课时间 | 课次维护 (UC-08) |
| 40050 | REPORT_ALREADY_CONFIRMED |
该学员已完成报到确认，无需重复报到 | 学员报到 (UC-15) |
| 40051 | REPORT_DEADLINE_WARNING |
已超过本期培训报到截止时间，触发时限提醒 | 学员报到 (UC-15) |
| 40060 | DORM_CAPACITY_EXCEEDED |
候选宿舍总可用床位不足，无法满足当前分配需求 | 住宿分配 (UC-12) |
| 40061 | DORM_GENDER_CONFLICT |
宿舍性别属性与学员性别不符，严禁混住 | 住宿分配 (UC-12/13) |
| 40062 | DORM_ROOM_FULL |
目标宿舍房间床位已满，无法调入 | 住宿调整 (UC-13) |
| 40070 | STUDENT_FACE_DATA_MISSING |
学员未采集人脸照片，无法下发门禁授权 | 门禁同步 (UC-16) |
| 40071 | DOOR_DEVICE_OFFLINE |
目标门锁设备离线，门禁授权下发失败 | 门禁同步 (UC-16) |
| 40080 | ATTENDANCE_PLAN_MISMATCH |
业务不变量校验失败：考勤学员与课次所属培训班不一致 | 考勤管理 (UC-17) |
| 40090 | SCORE_WEIGHT_SUM_INVALID |
成绩项目配置不合法：各项有效权重之和必须等于100% | 成绩配置 (UC-20) |
| 40091 | SCORE_ITEM_COURSE_MISMATCH |
成绩项目关联的课程不属于当前培训计划 | 成绩配置 (UC-20) |
| 40092 | SCORE_EXCEEDS_FULL_SCORE |
录入分数超出该项目设定的满分上限 | 成绩录入 (UC-21) |
| 40093 | SCORE_PLAN_MISMATCH |
业务不变量校验失败：成绩录入学员工号与科目所属班次不符 | 成绩录入 (UC-21) |
| 40100 | STUDY_EVENT_INVALID |
外部学习记录数据不合法 (结束时间早于开始时间或时长为负) | 学习接入 (UC-24) |
| 40110 | PORTRAIT_NOT_FOUND |
该学员画像尚未生成，请先执行画像刷新 | 学员画像 (UC-28) |
补录说明： 错误码
40008(CLASSROOM_NAME_DUPLICATED) 与40009(SITE_NAME_DUPLICATED) 属于 Issue Backlog 已有要求在错误码 Catalog 中的遗漏补录，不是新增业务需求。