03. RailwaySystem 系统架构设计

文档定位：阐述 RailwaySystem 的整体软件技术架构、系统分层设计、模块交互拓扑及国产化底座适配机制。 当前基线：Final Candidate 5a49b2e2988bf23ca2a70568264c05b24dfda1b6 (origin/feat/cicd-pipeline)

1. 整体架构与技术选型

RailwaySystem 采用现代企业级“前后端分离”单体增强架构，在兼顾交付敏捷性与开发效率的同时，针对铁路行业高安全、国产化底座的要求进行了深度加固：

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. 教学资源（教师、学员、课程、教室、场地、宿舍、班牌）； 2. 开班计划与课程绑定（`PlanAppService`, `TrainPlanCourseService`）； 3. 学员参训档案与报到流水（`EnrollmentAppService`）； 4. 课次排课与四维防重叠检测（`SchedulingAppService`）； 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 兼容模式：

驱动治理与供应规范：
- 采用官方商用驱动 com.kingbase:kingbase8:8.6.0。
- 驱动 JAR 文件通过受控构建脚本预检并置入 Maven 本地仓库，规避二进制污染与许可证风险。
主键生成策略适配：
- 传统若依在 MySQL 下依赖 AUTO_INCREMENT。在 Kingbase 适配中，全量 21 张表升级为统一的 BIGINT IDENTITY 自增序列或应用层 32 位 UUID，并定制了代码生成器自增识别补丁。
高安全与事务隔离：
- 全面支持事务隔离级别，在结训联动（completePlan）等关键业务场景中保证强事务一致性，任何异常即刻全量回滚。

4. 关键架构设计原则

确定性安全校验：
- 跨表核心规则由后端领域服务与数据库物理约束双重守门，杜绝前端单边绕过。
敏感信息脱敏与散列存盘：
- 学员身份证等关键数据进行哈希散列与密文存盘，对外接口响应强制执行末4位掩码数据脱敏。
只读分析模型与写操作严格隔离：
- 报表导出、打卡历史检索采用只读聚合映射（Read Model）；报到核验、考勤打卡、代签修正走独立写操作（Write Action）管道，实现读写职责清晰分离。

5. 技术参考链接 (Technical References)

核心服务边界划分：docs/api-v2/07_service_boundary.md
事务边界与不变量：docs/api-v2/08_transaction_and_invariants.md
数据库物理模型事实源：docs/database-v2/01_table_inventory.md
Kingbase 驱动供应指南：deployment/kingbase-jdbc-provisioning.md

5.3 KiB Raw Blame History Unescape Escape