docs(doc): 结构化梳理项目doc与docs文档中心并补齐导航索引

- 厘清 doc（业务与产品需求）与 docs（技术架构与代码审计）的职责边界 - doc 根目录保持一期正式生效基线 PRD V1.0，甲供原始材料归整至 raw_materials/，历史过程稿归档至 archive/ - 规范化接纳 wxy_doc/ 早期原型与技术说明并完善说明 - 为 doc/、docs/ 及项目根目录补齐结构化 README.md 导航索引与一键启动指引
2026-09-14 00:39:39 +08:00
1 parent fb00f67d3b
commit b12ef9c9e4
@@ -0,0 +1,84 @@
+# RailwaySystem 智慧培训系统
+
+RailwaySystem 是一套面向铁路职工与业务学员的一站式智慧培训管理系统。系统基于 Spring Boot 2.5、若依（RuoYi-Vue）底座、Vue 2.6 与国产人大金仓（KingbaseES）数据库构建，全面覆盖从学员档案、师资管理、开班排课、报到考勤、宿舍分配、门禁授权到动态考核与综合画像的全流程业务闭环。
+
+---
+
+## 📚 文档中心快速导航
+
+本项目文档实行**业务需求与技术架构分层治理**：
+
+| 文档中心 | 目录入口 | 核心重点内容 | 适用角色 |
+| :--- | :--- | :--- | :--- |
+| **业务与产品需求中心** | [doc/README.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/README.md) | ★★★ [PRD V1.0 业务需求基线](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)（正式冻结基线，32章全景规范）、原始甲供资料、历史版本演进 | 产品经理、业务方、测试、全栈开发 |
+| **技术架构与系统审计中心** | [docs/README.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/README.md) | ★★★ [Phase 0 真实基线与审计总结](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/17_phase0_summary.md)、18 篇全景代码与数据库实测快照报告 | 架构师、后端研发、前端研发、DBA |
+
+---
+
+## 🛠 技术栈
+
+- **后端架构**：Java 8+ / Spring Boot 2.5 / Spring Security / MyBatis / PageHelper / RuoYi-Vue
+- **前端架构**：Vue 2.6 / Vue Router / Vuex / Element UI / Axios / ECharts
+- **数据库底座**：国产人大金仓 **KingbaseES V009R003C018**（MySQL 兼容模式，JDBC 驱动 8.6.0）
+- **缓存与会话**：Redis 6+
+
+---
+
+## 🚀 快速启动指南
+
+### 1. 运行前置条件
+
+1. **Java**：JDK 8、11 或 17+
+2. **Node.js**：Node 16+（系统已兼容适配 Node 22/OpenSSL 3.x）
+3. **Redis**：本地启动 Redis 服务（默认端口 `6379`，无密码）
+4. **网络/跳板机**：数据库部署在内网（`192.168.139.218:4321`），通过 Tailscale 跳板机节点 `100.70.157.41`（账号 `wzb`）建立端口转发隧道。
+
+### 2. 一键启动（推荐）
+
+项目根目录下已提供一键启动脚本 [start-local.sh](file:///Users/wzb/Desktop/项目/RailwaySystem/start-local.sh)：
+
+```bash
+cd /Users/wzb/Desktop/项目/RailwaySystem
+./start-local.sh
+```
+
+脚本将自动执行：
+- 检查并唤醒本地 Redis；
+- 检查并建立针对 Kingbase 数据库的跳板机 SSH 端口转发（`127.0.0.1:4321`）；
+- 清理历史冲突端口，启动 Spring Boot 后端（端口 `8090`）；
+- 启动前端开发服务器（端口 `8080`）。
+
+### 3. 系统默认访问入口
+
+- **前端应用界面**：[http://localhost:8080](http://localhost:8080)
+- **后端接口服务**：[http://localhost:8090](http://localhost:8090)
+- **默认管理员账号**：`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/        # 公共常量、工具类与通用组件
+├── build_ui/                # 前端工程（Vue 2 + Element UI）
+│   ├── src/api/             # 前端 Axios 接口层（含 train 培训业务接口）
+│   ├── src/views/train/     # 培训业务页面视图（学员、排课、宿舍、成绩等）
+│   └── package.json         # 前端依赖配置
+├── doc/                     # 业务与产品需求中心（PRD V1.0、原始资料与归档）
+└── docs/                    # 技术架构与代码审计中心（18 篇深度审计与快照）
+```
+
+---
+
+## 📌 开发与演进原则
+
+1. **业务基线不可逆**：任何新页面开发、字段扩充与业务校验，统一以 [PRD V1.0](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md) 为唯一依据，旧版草案已全部归档。
+2. **非破坏性演进**：对 Kingbase 数据库与若依权限系统进行改造时，严格遵循技术审计报告结论，保持历史数据安全与可回滚性。
@@ -0,0 +1,52 @@
+# RailwaySystem 业务与产品需求文档中心（doc）
+
+> **最高基线声明**：当前系统一期唯一正式冻结并生效的业务需求基线为根目录下的 [RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)。
+> 所有开发、测试、数据库建模与功能验收工作，均严格以 **PRD V1.0** 为最终判定依据。
+
+---
+
+## 目录组织架构
+
+```text
+doc/
+├── README.md                                          # 【本文件】产品与业务需求中心全景导览
+├── RailwaySystem 智慧培训系统一期 PRD V1.0.md          # ★★★ 当前唯一正式生效的一期业务需求基线（已冻结）
+├── raw_materials/                                     # 甲方原始交付需求与设计资料
+│   ├── README.md                                      # 原始材料目录说明
+│   ├── 学员管理系统功能分析_20260831.docx / .md         # 原始功能拆解与菜单规划初稿
+│   ├── 学员管理系统数据表设计_20260907_1_.docx / .md     # 原始14张培训业务表设计草案
+│   └── 学员管理系统相关需求.docx / .md                   # 原始学员培训与教务综合需求
+├── archive/                                           # 历史演进过程稿与讨论底稿归档
+│   ├── README.md                                      # 历史归档说明
+│   ├── RailwaySystem 智慧培训系统一期 PRD V0.9.md      # 一期 PRD 历史讨论稿（上一版草案）
+│   ├── RailwaySystem 一期 P0 需求确认表 V0.1.md        # 早期核心优先级对齐清单
+│   ├── RailwaySystem 一期需求分析与业务基线 V0.1.md     # 早期需求分析报告
+│   └── RailwaySystem 一期默认开发决策与需求假设 V0.1.md # 早期技术假设与边界推演
+└── wxy_doc/                                           # 早期技术原型与设计说明（仅作技术演进参考）
+    ├── README.md                                      # 目录说明
+    ├── 智慧培训系统一期详细开发说明书.md               # 早期技术说明草案（暂不使用）
+    ├── railwaysystem.html                             # 基于 ELK 的系统拓扑可视化原型
+    └── elk.bundled.js                                 # 拓扑可视化依赖 JS 引擎
+```
+
+---
+
+## 核心业务基线速览（PRD V1.0）
+
+详细业务规范请完整阅读 [RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)，主要核心域包括：
+
+| 业务域 | 涉及核心对象 | 关键业务规则与一期边界 | PRD 对应章节 |
+| :--- | :--- | :--- | :--- |
+| **基础信息** | 教师、学员、课程 | 学员身份证国密/SM4加密存储与脱敏；课程支持一期基础属性，不做多版本与审批流 | 第 5、6、7 章 |
+| **教学资源** | 教室、实训场地、电子班牌 | 支持资源状态流转；电子班牌支持与教室、课次绑定及日程轮播展示 | 第 8、9、10 章 |
+| **培训与教务** | 开班计划、开班课程、课次、参训学员 | **开班计划支持多门课程**；排课细化到具体课次；明确独立的班级—学员参训关系 | 第 11、12、13、14 章 |
+| **报到与考勤** | 开班报到、课次考勤、学习记录 | 区分班级报到与具体课次考勤；考勤记录精确关联到课次；记录学员自学与实训时长 | 第 15、16、17 章 |
+| **生活后勤** | 宿舍楼栋、房间、床位、门禁授权 | **房间与床位拆分**为两级模型；**住宿事实与门禁权限解耦**，支持按床位安排并独立下发门禁授权 | 第 18、19、20 章 |
+| **考核与画像** | 成绩科目/权重、学员得分、综合画像 | 彻底摒弃固定三列成绩，支持**动态成绩科目与权重**；多维雷达图与基础能力画像分析 | 第 21、22、23 章 |
+
+---
+
+## 业务与技术文档的对应关系
+
+- **业务需求中心 (`doc/`)**：定义**系统应该做什么、业务对象是什么、业务规则与输入输出约束**。
+- **技术审计中心 (`docs/`)**：技术人员请参阅 [docs/README.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/README.md) 及 [docs/codebase-audit/](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/)，获取当前工程架构、14张历史业务表与PRD差异对比（[14_database_code_diff.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/14_database_code_diff.md)）、KingbaseES 实测兼容性等技术事实。
@@ -0,0 +1,27 @@
+# 历史过程稿与版本归档（archive）
+
+> **状态说明**：本目录归档存放项目需求梳理与演化过程中的历史中间稿、前期调研确认表及技术假设分析文档。
+> 
+> **最高业务基线**：当前系统一期唯一正式生效的业务基线为上一层目录中的 [RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)。本目录下的历史文档已全部被 V1.0 覆盖，仅供版本追溯和决策沿革查询。
+
+---
+
+## 历史版本归档清单
+
+| 归档文档名称 | 版本号 | 生成阶段 | 历史作用说明 |
+| :--- | :--- | :--- | :--- |
+| `RailwaySystem 智慧培训系统一期 PRD V0.9.md` | V0.9 | 2026-09 上旬 | 一期产品需求初稿（已在 V1.0 中全面升华与补充边界规则） |
+| `RailwaySystem 一期 P0 需求确认表 V0.1.md` | V0.1 | 早期调研 | 核心功能优先级（P0/P1/P2）研讨与业务确认清单 |
+| `RailwaySystem 一期需求分析与业务基线 V0.1.md` | V0.1 | 早期分析 | 面向业务方需求的初步分析与功能点映射草稿 |
+| `RailwaySystem 一期默认开发决策与需求假设 V0.1.md` | V0.1 | 早期设计 | 针对甲供资料不完备部分所制定的默认技术假设与边界推演 |
+
+---
+
+## 核心演进对比
+
+- **从 V0.1 到 V0.9**：完成了甲供分散需求到结构化系统模块的归集，明确了 6 大核心模块与 14 张业务表的对应关系。
+- **从 V0.9 到 V1.0**：
+  1. 彻底厘清了“开班计划与课程多对多”、“课次排课”、“参训学员关联关系”三大领域核心对象；
+  2. 彻底解耦了“宿舍床位安排”与“门禁设备授权”，界定了物理住宿事实与设备状态的边界；
+  3. 规范了由“固定三列成绩”转向“成绩科目/权重 + 学员得分”的动态考核模型；
+  4. 明确了一期不做的功能边界（如课程多版本审批、复杂画像算法引擎等），确保一期范围收敛可控。
@@ -0,0 +1,22 @@
+# 甲方原始交付需求与设计资料（raw_materials）
+
+> **说明**：本目录归档存放项目启动与早期阶段甲方/业务方提供的原始需求、功能分析与初版数据表设计文档（包含原始 docx 及同名导出的 markdown 格式）。
+> 
+> **最高业务基线**：所有原始材料中的要求已全部整合、甄别并提炼至 [RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)。在需求冲突时，一律以 **PRD V1.0** 为准。
+
+---
+
+## 原始材料清单
+
+| 文件名 | 原始日期 | 格式 | 核心内容说明 |
+| :--- | :--- | :--- | :--- |
+| `学员管理系统相关需求.docx` / `.md` | 早期交付 | docx / md | 业务方最初提出的学员、班级、住宿、培训宏观需求与业务设想 |
+| `学员管理系统功能分析_20260831.docx` / `.md` | 2026-08-31 | docx / md | 培训系统功能模块拆解、业务流梳理与菜单原型规划初稿 |
+| `学员管理系统数据表设计_20260907_1_.docx` / `.md` | 2026-09-07 | docx / md | 早期数据库 14 张培训业务表设计草案（旧表结构初稿） |
+
+---
+
+## 演进与演变提示
+
+1. **表结构演进**：`学员管理系统数据表设计_20260907_1_` 中定义的字段与当前生产 KingbaseES 数据库存在部分类型演进（如主键 identity、timestamp 等），且与 PRD V1.0 要求的开班计划—课程、参训关系、课次对象存在结构化演进，详见技术审计文档 [14_database_code_diff.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/14_database_code_diff.md)。
+2. **需求演进**：早期需求中模糊的门禁关联、签到联动与成绩结构，已在 PRD V1.0 中建立严格的业务边界定义。
@@ -0,0 +1,14 @@
+# 早期技术参考资料（wxy_doc）
+
+> **状态说明**：本目录为王杏月师姐早期编写的系统设计与前端拓扑可视化原型资料。**仅供技术演进与历史设计参考，不作为系统一期正式业务与实现基线**。
+> 一期最新最高业务基线请以根目录 [PRD V1.0](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md) 为准。
+
+---
+
+## 目录文件清单
+
+| 文件名 | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `智慧培训系统一期详细开发说明书.md` | 技术文档 | 早期详细开发说明草案（基于旧数据表与旧需求） |
+| `railwaysystem.html` | 前端页面 | 基于 ELK 布局生成的培训系统拓扑与架构图可视化原型 |
+| `elk.bundled.js` | JS 库 | 前端拓扑布局引擎 ELK.js 打包文件，供 `railwaysystem.html` 渲染图表使用 |
@@ -0,0 +1,65 @@
+# RailwaySystem 技术架构与代码审计中心（docs）
+
+> **说明**：本目录为 RailwaySystem 智慧培训系统的技术架构设计、代码审计、数据库实测核验及运行环境全景知识库。
+> 
+> **业务基线指针**：所有技术方案与数据库重构均服务于业务需求，业务判断请严格参阅 [doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md) 以及 [doc/README.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/README.md)。
+
+---
+
+## 核心技术现状速览（Phase 0 审计结论）
+
+1. **工程架构**：前后端分离架构，后端基于 Spring Boot 2.5 + 若依 (RuoYi-Vue) 单体增强，前端基于 Vue 2.6 + Element UI。
+2. **数据库底座**：国产人大金仓 **KingbaseES V009R003C018**（JDBC 驱动 8.6.0，`database_mode=mysql`）。通过跳板机隧道（`127.0.0.1:4321` -> `192.168.139.218:4321`）直连生产实例。
+3. **数据库实测**：14 张培训业务表全部就绪，除 `train_teacher` 含有 1 条真实教师记录外，其余 13 张表数据量为 0，具备低包袱重构升级条件。
+4. **接口连通性**：已针对 Controller 增加路由别名，涵盖培训管理 14 组业务接口的探测全部达到 HTTP 200 连通。
+5. **系统启动**：已在工程根目录提供一键启动脚本 [start-local.sh](file:///Users/wzb/Desktop/项目/RailwaySystem/start-local.sh)，集成跳板机隧道打通、本地 Redis 唤醒、Mac 端口清理与前后端一键并发启动。
+
+---
+
+## 代码与数据全景审计报告清单（`codebase-audit/`）
+
+本目录下的 [codebase-audit/](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/) 包含完整的 18 篇技术审计报告，记录了对工程现状、源码实现、数据库实际 schema 与权限体系的详尽核验：
+
+### 1. 核心综述与基线标准
+
+- [17_phase0_summary.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/17_phase0_summary.md) —— ★★★ **Phase 0 工程与数据库真实基线总结（进入下一阶段前必读）**
+- [11_executive_summary.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/11_executive_summary.md) —— 全景代码审计执行摘要
+- [12_baseline_classification.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/12_baseline_classification.md) —— 真实代码基线与工程资产可信度分级
+- [00_project_overview.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/00_project_overview.md) —— 项目整体技术概况与组件关系
+- [01_project_tree.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/01_project_tree.md) —— 项目工程目录结构全貌
+
+### 2. 数据库与数据建模实测
+
+- [13_live_database_snapshot.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/13_live_database_snapshot.md) —— 实时 KingbaseES 数据库实例只读核验快照
+- [14_database_code_diff.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/14_database_code_diff.md) —— 实时数据库与当前代码及 PRD V1.0 业务对象的差异比对
+- [16_kingbase_readonly_compatibility.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/16_kingbase_readonly_compatibility.md) —— KingbaseES MySQL 模式兼容性实测报告
+- [03_database_current_state.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/03_database_current_state.md) —— 数据库静态结构与设计状态分析
+
+### 3. 后端服务与 API 盘点
+
+- [04_api_inventory.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/04_api_inventory.md) —— 后端 Controller 接口现状盘点与路由清单
+- [02_training_modules_inventory.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/02_training_modules_inventory.md) —— 培训业务模块 Java 代码资产详尽盘点
+- [09_reusable_ruoyi_capabilities.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/09_reusable_ruoyi_capabilities.md) —— 若依（RuoYi）底座可复用框架能力分析
+
+### 4. 前端组件与页面现状
+
+- [05_frontend_inventory.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/05_frontend_inventory.md) —— 前端 Vue 页面、路由及 API 请求层盘点
+
+### 5. 安全、权限与运行配置
+
+- [15_live_permission_snapshot.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/15_live_permission_snapshot.md) —— 生产菜单、角色、权限关系实时状态核验
+- [06_security_and_permissions.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/06_security_and_permissions.md) —— 权限体系与若依安全拦截机制分析
+- [07_runtime_and_environment.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/07_runtime_and_environment.md) —— 运行环境依赖、配置项与本地部署条件
+- [08_git_status.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/08_git_status.md) —— Git 提交历史与版本分支演化
+
+### 6. 业务与技术差距分析
+
+- [10_gap_and_conflict_analysis.md](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/codebase-audit/10_gap_and_conflict_analysis.md) —— 现状与预期目标的差距与冲突分析
+
+---
+
+## 关联子模块技术文档
+
+- Kingbase 兼容模式专题核验：
+  - [kingbase_compatibility_audit.md](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/docs/kingbase_compatibility_audit.md)
+  - [kingbase_fact_check.md](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/docs/kingbase_fact_check.md)