# 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)