5.8 KiB
5.8 KiB
06. RailwaySystem API 与权限体系总览
文档定位：面向前端开发、集成团队及安全审计人员，系统梳理核心业务 API 契约、专用写操作（Write Actions）及 RBAC 权限体系。 当前基线：Final Candidate
5a49b2e2988bf23ca2a70568264c05b24dfda1b6(origin/feat/cicd-pipeline)
1. 核心业务 API 端点分组
系统提供遵循 RESTful 规范的标准化 API 接口体系，统一由 ruoyi-admin 暴露，业务逻辑封装于 ruoyi-train。各业务域核心端点如下：
1.1 基础教务资源接口
- 教师管理：
GET /train/teacher/list,POST /train/teacher,PUT /train/teacher,DELETE /train/teacher/{ids} - 学员主档：
GET /train/student/list,POST /train/student,PUT /train/student,GET /train/student/{id}(敏感信息脱敏) - 课程资源：
GET /train/course/list,POST /train/course,PUT /train/course - 教学空间：
GET /train/classroom/list,POST /train/classroom,GET /train/training-site/list,POST /train/training-site - 宿舍生活：
GET /train/dormitory/list,POST /train/dormitory,GET /train/dormitory/{id}/occupants(住户查询) - 电子班牌：
GET /train/board/list,POST /train/board,PUT /train/board,DELETE /train/board/{id}(后端 API 路径为/train/board，对应前端页面路由为/equip/board)
1.2 开班计划与排课编排接口
- 开班计划：
POST /train/plans—— 创建开班计划（状态置为 0:草稿）GET /train/plans/{id}—— 查询开班计划详情POST /train/plans/{id}/complete—— 一键结训强事务操作（计划状态更新为 2，联动更新在读学员参训状态为 4）
- 本期课程：
POST /train/plans/{id}/courses,GET /train/plans/{id}/courses - 学员报名：
POST /train/plans/{id}/enrollments(名单录入),PUT /train/enrollments/{id}/status(状态调整) - 课次编排：
POST /train/lessons/check-conflict—— 四维排课冲突实时预检（失焦调用，返回LessonConflictVO）POST /train/plans/{id}/lessons—— 新增课次（标准 POST 保存，严格禁止force/ignoreConflict/overrideConflict旁路参数；排课流程中Lesson detail GET: NOT CALLED）GET /train/plans/{id}/timetable—— 培训班可视化课表视图
1.3 系统管理与在线接口工具
- 系统接口 (Swagger UI)：
- 真实系统入口：
系统工具 → 系统接口 - 接口健康状况：Swagger UI 正常渲染，
v3/api-docs = 200，swagger-resources = 200，无 502 坏网关，无死链
- 真实系统入口：
- 系统工具其他可见项：表单构建、代码生成正常可见可用
2. 专用写操作 (Core Write Actions)
针对现场高频、高安全核验的业务场景，系统设计了专用的写操作端点：
| 业务动作 | HTTP 动词与 URL 路径 | 核心业务行为与事务约束 | 所需安全权限 |
|---|---|---|---|
| 开班现场报到 | POST /train/plans/{planId}/enrollments/{enrollmentId}/report(或 /train/enrollments/{enrollmentId}/report) |
核验报到时效，写入报到流水 train_class_report，联动将参训档案 enrollment_status 置为 1 (已报到)。 |
train:report:confirm |
| 课次签到打卡 | POST /train/lessons/{lessonId}/attendance/checkin(或 /train/attendance/sign-in) |
记录学员课次签到时间戳，校验是否超出允许时段，生成或更新考勤结论。 | train:attendance:checkin |
| 课次签退打卡 | POST /train/attendance/sign-out |
记录学员法定签退时间戳，结合签到时间自动核算考勤最终结论（正常/早退）。 | train:attendance:checkin |
| 教师代签/请假修正 | POST /train/lessons/{lessonId}/attendance/adjust(或 PUT /train/attendance/{checkinId}) |
教师或管理员人工修正考勤结论（0~4），强制将 manual_flag 置为 1 留痕存盘。 |
train:attendance:edit |
3. RBAC 权限体系与菜单治理
系统全面对齐若依标准的“用户—角色—菜单”基于角色的访问控制（RBAC）架构：
3.1 核心业务权限标识符
- 报到模块：
train:report:list(查询),train:report:export(导出),train:report:confirm(现场确认) - 考勤模块：
train:attendance:list(查询),train:attendance:export(导出),train:attendance:checkin(打卡),train:attendance:edit(代签调整) - 学时分析：
train:learning:list,train:learning:export - 学员画像：
train:portrait:query,train:portrait:export
3.2 发布增量 003 权限补齐机制
在最新的数据库迁移脚本 003_report_attendance_action_permissions.sql 中：
- 菜单项创建：脚本自动向
public.sys_menu表中注入了train:report:confirm(ID: 2181)、train:attendance:checkin(ID: 2182) 与train:attendance:edit(ID: 2183) 三项按钮级权限记录； - 角色绑定规范说明：
003脚本只负责在数据库中安全声明这三项可授权的原子能力项；- 角色与菜单的绑定（
sys_role_menu）属于环境运行时配置（ENVIRONMENT_CONFIGURATION），管理员可根据各局各院校的实际管理制度，在前端【系统管理 -> 角色管理】中将上述权限灵活分配给“班主任”、“任课教师”或“考勤监督员”等业务角色。
4. 技术参考链接 (Technical References)
- API V2 契约总纲：docs/api-v2/00_readme.md
- 全量 DTO/VO 字典：docs/api-v2/06_dto_vo_catalog.md
- 权限与全量错误码定义：docs/api-v2/10_permission_and_error_codes.md
- 报到与考勤权限迁移验证：docs/reports/archive/20260915/release-notes.md