140 lines
12 KiB
Markdown
140 lines
12 KiB
Markdown
|
# 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` | 房间容量不可调整至小于当前已入住人数 | 宿舍房间 |
|
||
|
|
| **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) |
|