101 lines
5.3 KiB
Markdown
101 lines
5.3 KiB
Markdown
# 03. RailwaySystem 系统架构设计
|
||
|
||
> **文档定位**：阐述 RailwaySystem 的整体软件技术架构、系统分层设计、模块交互拓扑及国产化底座适配机制。
|
||
> **当前基线**：Final Candidate `5a49b2e2988bf23ca2a70568264c05b24dfda1b6` (`origin/feat/cicd-pipeline`)
|
||
|
||
---
|
||
|
||
## 1. 整体架构与技术选型
|
||
|
||
RailwaySystem 采用现代企业级“前后端分离”单体增强架构，在兼顾交付敏捷性与开发效率的同时，针对铁路行业高安全、国产化底座的要求进行了深度加固：
|
||
|
||
```mermaid
|
||
graph TD
|
||
subgraph UI["前端展示层 (build_ui)"]
|
||
Vue["Vue 2.6 + Element UI + Axios + Vue Router + Vuex + ECharts"]
|
||
end
|
||
|
||
subgraph Admin["API 网关与接入层 (ruoyi-admin)"]
|
||
Ctrl["Spring MVC 控制器 / Token 鉴权 / 日志切面 / 全局异常捕获映射 / Swagger UI"]
|
||
end
|
||
|
||
subgraph Train["培训核心业务层 (ruoyi-train)"]
|
||
S1["PlanAppService (开班计划)"]
|
||
S2["EnrollmentAppService (名单/报到)"]
|
||
S3["SchedulingAppService (排课四维预检)"]
|
||
S4["AttendanceAppService (考勤打卡/代签)"]
|
||
S5["基础资源服务 (教师/学员/场地/宿舍)"]
|
||
end
|
||
|
||
subgraph Base["系统支撑底座 (ruoyi-system / framework / common)"]
|
||
RBAC["用户与角色权限 (RBAC)"]
|
||
Menu["系统菜单 (sys_menu)"]
|
||
Log["操作日志 (sys_oper_log)"]
|
||
Dict["字典配置 (sys_dict_data)"]
|
||
end
|
||
|
||
subgraph Persistence["数据持久层 (MyBatis / PageHelper)"]
|
||
Mapper["XML 动态 SQL 映射器"]
|
||
Domain["领域实体 (Domain Entities)"]
|
||
end
|
||
|
||
subgraph Storage["国产高安全主库 (KingbaseES V9)"]
|
||
KB[("人大金仓数据库 (MySQL兼容模式)<br/>21张物理表 / BIGINT IDENTITY 序列 / 强约束与索引")]
|
||
end
|
||
|
||
UI -->|HTTP / RESTful JSON| Admin
|
||
Admin --> Train
|
||
Admin --> Base
|
||
Train --> Persistence
|
||
Base --> Persistence
|
||
Persistence -->|JDBC 8.6.0| Storage
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 核心模块解耦：`ruoyi-train` 业务域划分
|
||
|
||
为了彻底解决传统若依架构中业务代码与系统基础代码杂糅的问题，项目进行了模块级重构，将所有铁路培训业务彻底独立为 **`ruoyi-train`** Maven 子模块：
|
||
|
||
| 模块名称 | 职责定位 | 包含的核心能力与服务 |
|
||
| :--- | :--- | :--- |
|
||
| **`ruoyi-train`** | **培训业务核心领域** | 1. 教学资源（教师、学员、课程、教室、场地、宿舍、班牌）；<br/>2. 开班计划与课程绑定（`PlanAppService`, `TrainPlanCourseService`）；<br/>3. 学员参训档案与报到流水（`EnrollmentAppService`）；<br/>4. 课次排课与四维防重叠检测（`SchedulingAppService`）；<br/>5. 课次打卡与教师代签（`AttendanceAppService`）。 |
|
||
| **`ruoyi-admin`** | **Web 交互与接口暴露** | 声明 RESTful 控制器（Controller）、Swagger 注解、请求入参校验及权限注解 `@ss.hasPermi`。 |
|
||
| **`ruoyi-framework`**| **底层工程基础设施** | Spring Security 拦截器、JWT 令牌校验机制、Druid 数据源监控配置。 |
|
||
| **`ruoyi-system`** | **通用权限与元数据底座** | 用户、角色、系统菜单（`sys_menu`）、字典数据（`sys_dict_data`）的底层管理。 |
|
||
| **`ruoyi-common`** | **通用工具与异常常量** | 基础实体基类、业务状态枚举、统一响应对象 `AjaxResult`。 |
|
||
|
||
---
|
||
|
||
## 3. 国产数据库适配：人大金仓 KingbaseES
|
||
|
||
系统底层数据库运行于国产人大金仓 **KingbaseES V009R003C018** 之上，采用 `database_mode=mysql` 兼容模式：
|
||
|
||
1. **驱动治理与供应规范**：
|
||
- 采用官方商用驱动 `com.kingbase:kingbase8:8.6.0`。
|
||
- 驱动 JAR 文件通过受控构建脚本预检并置入 Maven 本地仓库，规避二进制污染与许可证风险。
|
||
2. **主键生成策略适配**：
|
||
- 传统若依在 MySQL 下依赖 `AUTO_INCREMENT`。在 Kingbase 适配中，全量 21 张表升级为统一的 `BIGINT IDENTITY` 自增序列或应用层 32 位 UUID，并定制了代码生成器自增识别补丁。
|
||
3. **高安全与事务隔离**：
|
||
- 全面支持事务隔离级别，在结训联动（`completePlan`）等关键业务场景中保证强事务一致性，任何异常即刻全量回滚。
|
||
|
||
---
|
||
|
||
## 4. 关键架构设计原则
|
||
|
||
1. **确定性安全校验**：
|
||
- 跨表核心规则由后端领域服务与数据库物理约束双重守门，杜绝前端单边绕过。
|
||
2. **敏感信息脱敏与散列存盘**：
|
||
- 学员身份证等关键数据进行哈希散列与密文存盘，对外接口响应强制执行末4位掩码数据脱敏。
|
||
3. **只读分析模型与写操作严格隔离**：
|
||
- 报表导出、打卡历史检索采用只读聚合映射（Read Model）；报到核验、考勤打卡、代签修正走独立写操作（Write Action）管道，实现读写职责清晰分离。
|
||
|
||
---
|
||
|
||
## 5. 技术参考链接 (Technical References)
|
||
|
||
* 核心服务边界划分：[docs/api-v2/07_service_boundary.md](../api-v2/07_service_boundary.md)
|
||
* 事务边界与不变量：[docs/api-v2/08_transaction_and_invariants.md](../api-v2/08_transaction_and_invariants.md)
|
||
* 数据库物理模型事实源：[docs/database-v2/01_table_inventory.md](../database-v2/01_table_inventory.md)
|
||
* Kingbase 驱动供应指南：[deployment/kingbase-jdbc-provisioning.md](deployment/kingbase-jdbc-provisioning.md)
|