railwaysystem/README.md

# RailwaySystem 智慧培训系统

> **当前交付候选版本 (Final Candidate)**：`5a49b2e2988bf23ca2a70568264c05b24dfda1b6`  
> **远程基线分支**：`origin/feat/cicd-pipeline`  
> **自动化测试覆盖**：后端单元与契约测试 154/154 PASS，核心业务主链集成用例 6/6 PASS，Kingbase 物理断言 11/11 PASS，端到端浏览器真实验收 PASS (0 阻断 / 0 异常 / Swagger 连通)。

---

## 📖 项目简介

RailwaySystem 是一套专为铁路职工与业务学员量身打造的一站式智慧培训管理系统。系统基于 Spring Boot 2.5、若依（RuoYi-Vue）企业级底座、Vue 2.6 前端框架以及国产人大金仓（KingbaseES）高安全数据库构建。系统全面贯穿从基础教务资源维护、开班计划编排、学员批量建档、现场开班报到、课次冲突检测、多模式考勤打卡、自动结训归档到多维学情画像与综合分析的全业务生命周期。

---

## 🛠 技术架构栈

- **后端架构**：Java 8+ / Spring Boot 2.5 / Spring Security / MyBatis / PageHelper / RuoYi-Vue
  - **核心培训业务模块**：`ruoyi-train`（独立封装教务、排课、考勤、计划、住宿等完整业务域逻辑与应用服务）
  - **系统管理与支撑底座**：`ruoyi-system`、`ruoyi-framework`、`ruoyi-common`、`ruoyi-admin`
- **前端架构**：Vue 2.6 / Vue Router / Vuex / Element UI / Axios / ECharts
  - **交互工程**：`build_ui`（当前 Final Candidate 实际构建和部署使用的 Vue 前端工程）
  - **历史资产**：`RuoYi-Vue/ruoyi-ui`（若依原始/历史前端资产，不作为当前 Final Browser Acceptance 主构建源）
- **数据存储与持久化**：
  - **国产主库**：人大金仓 **KingbaseES V009R003C018**（MySQL 兼容模式，驱动版本 `com.kingbase:kingbase8:8.6.0`）
  - **缓存与会话**：Redis 6+（支持密码预检与分布式缓存）
- **发布与数据库增量 (Release DB Delta)**：
  - 当前增量版本：`CURRENT_RELEASE_DB_DELTA = 3`（包括 `001_sys_oper_log_cost_time.sql`、`002_legacy_analytics_permissions.sql`、`003_report_attendance_action_permissions.sql`）

---

## 🔄 核心业务闭环主链

系统严格遵循业务不变量与领域模型设计，构建了从教务准备到结业归档的标准业务闭环：

```mermaid
flowchart TD
    A["基础资源准备<br/>(教师/学员/课程/教室/场地/宿舍)"] --> B["培训计划 (Plan)<br/>创建开班计划 · 0:草稿"]
    B --> C["本期课程 (PlanCourse)<br/>绑定课程、教师与学时"]
    C --> D["参训学员 (Enrollment)<br/>名单批量导入 · 0:待报到"]
    D --> E["开班发布 (Plan Publish)<br/>锁定计划配置 · 1:进行中"]

    E --> F1["现场报到 (Report)<br/>人脸/刷卡/扫码核验<br/>状态更新为 1:已报到"]
    E --> F2["课次排课 (Scheduling)<br/>四维时段冲突预检<br/>(教师/教室/场地/本班)"]

    F1 --> G["课次考勤 (Attendance)<br/>签到/签退打卡，教师代签与请假修正留痕"]
    F2 --> G

    G --> H["培训结训 (Completion)<br/>计划置为 2:已结束，在读学员批量联动为 4:已完成"]
    H --> I["学情分析 (Analytics - Read Only)<br/>报到统计、考勤汇总、学习时长与综合能力画像"]
```
*(注：学员宿舍安排作为生活保障支线，电子班牌作为现场多媒体与打卡硬件设备支撑)*

---

## 🧭 文档中心导航

本项目采用**人类可读文档层（Human Documentation Layer）与技术契约事实源（Contract Sources）分层治理**：

| 入口推荐 | 文档位置 | 说明与适用对象 |
| :--- | :--- | :--- |
| 🌟 **视觉化展示门户 (推荐首先访问)** | [docs/visual/index.html](docs/visual/index.html) | **纯静态可离线浏览**。面向评审专家、客户与业务方的交互式展示门户，含业务流程拓扑、系统架构图、14 大模块导览与质量看板。 |
| 📚 **人类操作手册与架构白皮书** | [docs/handbook/](docs/handbook/) | 面向项目经理、开发与测试人员的系统级手册（涵盖项目总览、业务流程、架构设计、数据模型、模块指南与部署运维）。 |
| 📑 **综合验收与测试报告** | [docs/reports/](docs/reports/) | 包含自动化集成测试报告、发版说明 (Release Notes) 与浏览器端到端验收记录。 |
| 📋 **业务需求基线中心** | [doc/README.md](doc/README.md) | ★★★ [PRD V1.0 业务需求基线](doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md)（正式冻结基线，32章全景规范）、原始甲供资料、历史版本演进。 |
| 🔒 **冻结技术契约 (Source of Truth)** | [docs/api-v2/](docs/api-v2/)<br>[docs/database-v2/](docs/database-v2/) | 开发与 Agent 技术事实源。包含冻结的 REST API 契约、DTO/VO 字典、21 张物理表字段规范与权限错误码。 |
| 📋 **技术文档全景索引** | [docs/README.md](docs/README.md) | 技术文档中心主索引，提供面向不同角色（业务/研发/测试/历史审计）的精确导读。 |

---

## 🚀 快速启动指南

### 1. 环境准备
- **JDK**：Java 8、11 或 17+
- **Node.js**：Node 16+（已兼容 Node 22 与 OpenSSL 3.x）
- **Redis**：本地启动 Redis 6+ 服务（默认端口 `6379`，无密码）
- **数据库**：KingbaseES 8.6.0（通过跳板机隧道转发 `127.0.0.1:4321` 直连）

### 2. 一键本地启动（开发模式）
项目根目录下提供了全自动化本地启动脚本 [start-local.sh](start-local.sh)：
```bash
./start-local.sh
```
该脚本将自动唤醒本地 Redis、建立 Kingbase SSH 隧道、启动 Spring Boot 后端（端口 `8090`）以及启动前端工程（端口 `8080`）。

### 3. 系统默认访问入口
- **前端系统界面**：[http://localhost:8080](http://localhost:8080)（本地开发） / `http://192.168.139.230:8082`（生产部署环境）
- **后端 API 服务**：[http://localhost:8090](http://localhost:8090)（本地开发） / `http://192.168.139.230:8092`（生产部署环境）
- **初始管理账号**：`admin` / `admin123`

---

## 📁 目录结构导览

```text
RailwaySystem/
├── README.md                # 【本文件】项目总览、架构导览与启动指南
├── start-local.sh           # 本地一键启动脚本（集成数据库隧道与前后端并发启动）
├── RuoYi-Vue/               # 后端工程（Spring Boot 单体增强版）
│   ├── ruoyi-admin/         # Web 启动入口与 Controller 接口层
│   ├── ruoyi-framework/     # 框架核心配置、WebSecurity 与拦截器
│   ├── ruoyi-system/        # 核心业务模块（含培训管理业务 Entity/Mapper/Service）
│   ├── ruoyi-common/        # 公共常量、工具类与通用组件
│   └── ruoyi-ui/            # 若依原始/历史前端资产（不作为当前 Final Browser Acceptance 主构建源）
├── build_ui/                # 当前 Final Candidate 实际构建和部署使用的 Vue 前端工程
│   ├── src/api/             # 前端 Axios 接口层（含 train 培训业务接口）
│   ├── src/views/train/     # 培训业务页面视图（学员、排课、宿舍、考勤等）
│   └── package.json         # 前端依赖与 Webpack 构建配置
├── deploy/                  # 生产部署、平滑重启脚本与 Nginx 示例配置
├── doc/                     # 业务与产品需求中心（PRD V1.0、原始资料与归档）
├── docs/                    # 技术架构、发布门禁、Human Documentation 与代码审计中心
│   ├── visual/              # 视觉化交互展示门户（8 篇可离线全景架构与流程展示）
│   ├── handbook/            # 人类操作白皮书与开发指南（01~09 全景手册）
│   ├── reports/             # 验收测试报告与发版说明
│   ├── _meta/               # 发布准备度、门禁清单与最终浏览器验收证据
│   ├── api-v2/              # REST API 契约与 DTO/VO 字典
│   └── database-v2/         # 数据库 V2 物理模型与迁移断言
└── scripts/                 # 驱动预检与质量断言脚本
```

---

## 📌 开发与演进原则

1. **业务基线不可逆**：任何新页面开发、字段扩充与业务校验，统一以 [PRD V1.0](doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md) 为唯一依据，旧版草案已全部归档。
2. **非破坏性演进**：对 Kingbase 数据库与若依权限系统进行改造时，严格遵循技术审计报告结论，保持历史数据安全与可回滚性。