78 lines
5.8 KiB
Markdown
78 lines
5.8 KiB
Markdown
# 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`<br>*(或 `/train/enrollments/{enrollmentId}/report`)* | 核验报到时效，写入报到流水 `train_class_report`，联动将参训档案 `enrollment_status` 置为 1 (已报到)。 | `train:report:confirm` |
|
||
| **课次签到打卡** | `POST /train/lessons/{lessonId}/attendance/checkin`<br>*(或 `/train/attendance/sign-in`)* | 记录学员课次签到时间戳，校验是否超出允许时段，生成或更新考勤结论。 | `train:attendance:checkin` |
|
||
| **课次签退打卡** | `POST /train/attendance/sign-out` | 记录学员法定签退时间戳，结合签到时间自动核算考勤最终结论（正常/早退）。 | `train:attendance:checkin` |
|
||
| **教师代签/请假修正**| `POST /train/lessons/{lessonId}/attendance/adjust`<br>*(或 `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` 中：
|
||
1. **菜单项创建**：脚本自动向 `public.sys_menu` 表中注入了 `train:report:confirm` (ID: 2181)、`train:attendance:checkin` (ID: 2182) 与 `train:attendance:edit` (ID: 2183) 三项按钮级权限记录；
|
||
2. **角色绑定规范说明**：
|
||
- `003` 脚本只负责在数据库中安全声明这三项可授权的原子能力项；
|
||
- **角色与菜单的绑定（`sys_role_menu`）属于环境运行时配置（ENVIRONMENT_CONFIGURATION）**，管理员可根据各局各院校的实际管理制度，在前端【系统管理 -> 角色管理】中将上述权限灵活分配给“班主任”、“任课教师”或“考勤监督员”等业务角色。
|
||
|
||
---
|
||
|
||
## 4. 技术参考链接 (Technical References)
|
||
|
||
* API V2 契约总纲：[docs/api-v2/00_readme.md](../api-v2/00_readme.md)
|
||
* 全量 DTO/VO 字典：[docs/api-v2/06_dto_vo_catalog.md](../api-v2/06_dto_vo_catalog.md)
|
||
* 权限与全量错误码定义：[docs/api-v2/10_permission_and_error_codes.md](../api-v2/10_permission_and_error_codes.md)
|
||
* 报到与考勤权限迁移验证：[docs/reports/archive/20260915/release-notes.md](../reports/archive/20260915/release-notes.md)
|