当前工程基线：Final Candidate 5a49b2e2988bf23ca2a70568264c05b24dfda1b6 (origin/feat/cicd-pipeline) 数据库增量版本：CURRENT_RELEASE_DB_DELTA = 3 (增量迁移 001_sys_oper_log_cost_time.sql、002_legacy_analytics_permissions.sql、003_report_attendance_action_permissions.sql 已就绪；007_dicts.sql 明确严禁执行) 质量状态速览：后端单元测试与契约测试 154 PASS，核心场景集成 6/6 PASS，110 次真实 HTTP 请求零 500 错误，Kingbase 物理断言 11/11 PASS，端到端浏览器自动化真实验收全量 PASS（Console 0 阻断，Swagger UI 正常连通）。

🧭 角色化阅读路线

为了帮助不同背景的读者快速找到权威资料，本文档中心提供以下角色导航路径：

graph TD
    Entry["RailwaySystem 访问入口选择"]

    subgraph R1["评审 / 领导 / 汇报"]
        V["离线交互门户<br/>visual/index.html"]
        H1["项目全景总览<br/>handbook/01"]
    end

    subgraph R2["业务 / 教务员"]
        H2["业务主链规范<br/>handbook/02"]
        H5["14大业务模块指南<br/>handbook/05"]
        PRD["业务需求PRD<br/>../doc/README.md"]
    end

    subgraph R3["开发 / 架构师"]
        H3["系统架构设计<br/>handbook/03"]
        H4["数据模型总览<br/>handbook/04"]
        H6["API与权限清单<br/>handbook/06"]
        API["API V2 事实源<br/>api-v2/"]
    end

    subgraph R4["测试 / 交付团队"]
        H7["质量保障报告<br/>handbook/07"]
        TR["综合测试报告<br/>reports/final-test-report.md"]
        BR["浏览器验收报告<br/>reports/browser-acceptance-report.md"]
        DEP["部署与发版说明<br/>reports/release-notes.md"]
    end

    Entry --> R1
    Entry --> R2
    Entry --> R3
    Entry --> R4

A. 第一次阅读（推荐入口）

如果您是第一次接触本项目，或者需要向老师、主管、客户汇报系统成果：

🌟 强力推荐直达离线交互门户：visual/index.html
- 特点：无需启动后端服务或数据库，双击即可在任意现代浏览器中离线打开。
- 内容：提供深色工业风大屏质感，涵盖系统业务主链 SVG 交互拓扑、系统六层分层架构图、14 大核心业务模块互动矩阵、核心指标 KPI 仪表盘与发版准备度看板。
📖 快速阅读项目总览白皮书：handbook/01-project-overview.md
- 专为人类读者编写，通俗阐述系统解决的教务痛点、服务对象、关键特性与一期交付边界。

B. 业务人员与教务管理路径

关注业务流程、业务规则、状态流转与功能说明的读者，请查阅：

handbook/02-business-process.md —— 核心业务全流程与状态机规范（开班计划、报到核验、四维排课冲突预检、考勤打卡与结训联动）。
handbook/05-module-guide.md —— 14 大业务模块详细指南（教师、学员、课程、教室、场地、宿舍、开班、报到、排课、考勤、班牌、统计等）。
../doc/README.md (业务需求中心与 PRD V1.0) —— 业务需求最高事实源（包含正式冻结的 PRD V1.0 原文与原始资料索引）。

C. 开发人员与架构师路径

参与系统编码、功能扩展与架构审计的研发人员，请查阅：

handbook/03-system-architecture.md —— 系统技术架构设计（Spring Boot 2.5 + 若依增强单体、ruoyi-train 核心模块、Kingbase 兼容适配模式）。
handbook/04-data-model-overview.md —— 数据模型总览（核心实体关系与关键表结构设计）。
handbook/06-api-and-permission-overview.md —— API 与权限体系速览（核心操作端点、RBAC 菜单权限与专用业务 Action）。
handbook/08-deployment-and-release.md —— 部署与运维手册（本地快速启动与生产多环境部署要求）。
handbook/deployment/kingbase-jdbc-provisioning.md —— Kingbase JDBC 8.6.0 依赖供应指南。

D. 测试与质量验收路径

负责功能验收、回归测试与质量审计的人员，请查阅：

reports/final-test-report.md —— Final Candidate 自动化测试与场景集成最终报告（154 单元测试 + 6 大场景全 PASS 证据）。
reports/browser-acceptance-report.md —— 端到端浏览器自动化验收报告（真实环境验收通过：PASS，0 阻断，Swagger 连通）。
reports/release-notes.md —— 发版说明与变更记录。
_meta/core-business-test-matrix.md —— 核心业务场景集成自动化测试矩阵。

E. Agent 与技术契约事实源（Contract Sources）

本目录下的底层契约目录为系统自动代码生成、契约测试和 Agent 审计的最高技术事实源（Source of Truth），已正式冻结，保持原路径不移动：

api-v2/ —— API V2 契约体系：
- 00_readme.md：API 体系总览与 REST 规范
- 01_api_design_principles.md ~ 05_module_d_score_learning_statistics_api.md：各业务域端点定义
- 06_dto_vo_catalog.md：DTO/VO 字段定义字典
- 08_transaction_and_invariants.md：强事务与 6 大跨表业务不变量
- 10_permission_and_error_codes.md：权限字符串与 40001~50001 业务错误码字典
database-v2/ —— 数据库 V2 物理迁移与表结构事实源：
- 01_table_inventory.md：21 张物理表字段、约束、主外键最终定义
- 05_execution_contract.md：数据库物理迁移执行契约与验证门禁
issues-v1/ —— 任务分解与验收条件：
- 02_p0_issue_backlog.md：P0 核心任务与 AC 验收条件定义
- 06_acceptance_matrix.md：AC 验收标准对应自动化用例矩阵
development/ —— 各 Issue 实施过程记录与验收报告。
_meta/documentation-audit.md —— D.0 文档现状审计与资产盘点报告。

F. 历史过程资料归档（Historical Snapshots）

⚠️ 重要提示：以下目录记录的是项目研发演进早期的阶段性快照或原始素材，仅作为工程审计与技术溯源参考，不代表当前 Final Candidate 的代码与数据库现状：

codebase-audit/：Phase 0 历史代码审计快照（基于历史 Commit e12eda05，记录了重构前旧单体结构与旧 14 张表实测状态，已被 Database V2 与 API V2 替代）。
../doc/raw_materials/：早期甲供原始需求与数据表草案。
../doc/archive/：一期 PRD V0.9、早期决策与假设讨论稿。
../doc/wxy_doc/：早期技术原型与开发说明书草案。

README.md Unescape Escape

RailwaySystem 文档中心总导航