diff --git a/README.md b/README.md index 7b9d08f93..a846276a2 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,13 @@ flowchart LR | 你的目标 | 推荐直达入口 | 核心内容与说明 | | :--- | :--- | :--- | | 🌟 **想快速了解项目现在做到哪了** | [**docs/current/**](docs/current/README.md) | **【首选入口】** 当前系统状态速览、试用数据大盘、需求落地度与行动计划。 | -| 📋 **想对照一期功能需求与待确认项** | [**docs/requirements/**](docs/requirements/一期需求实现进度表.md) | 一期需求逐项代码实现进度表、以及面向甲方的待确认清单 (P0/P1/P2)。 | +| 📋 **想对照一期功能需求与待确认项** | [**docs/requirements/**](docs/requirements/README.md) | 一期正式 PRD V1.0、逐项代码实现进度表、以及面向甲方的待确认清单 (P0/P1/P2)。 | | 📚 **想系统了解业务流程与技术架构** | [**docs/handbook/**](docs/handbook/01-project-overview.md) | 面向团队的系统级手册（涵盖项目总览、业务流程、架构设计、数据模型与开发部署）。 | | 🔌 **想对接后端 API 接口或 DTO 契约** | [**docs/api-v2/**](docs/api-v2/00_readme.md) | 冻结的 REST API 契约、入参出参模型定义与业务错误码规范。 | | 🗄️ **想查阅国产金仓数据库物理表结构** | [**docs/database-v2/**](docs/database-v2/01_table_inventory.md) | 21 张真实物理业务表字段清单、索引约束与迁移方案说明。 | | 🖥️ **想给领导/老师/专家进行生动展示** | [**docs/visual/index.html**](docs/visual/index.html) | **纯静态离线交付门户**，包含可交互业务状态机拓扑、系统架构图与 14 大模块导览。 | | 📑 **想查阅最终验收结果与测试日志** | [**docs/reports/**](docs/reports/README.md) | 包含当前唯一的最终验收报告 (FINAL_PHASE1) 及各轮次自动化测试证据链。 | +| 🏛️ **想查阅甲方原始材料与历史设计** | [**docs/archive/**](docs/archive/README.md) | 归档的甲方原始 Word/需求原件、早期需求草案、历史原型与数据库设计演进。 | --- diff --git a/doc/.gitkeep b/doc/.gitkeep deleted file mode 100644 index e69de29bb..000000000 diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index ea0c38a08..000000000 --- a/doc/README.md +++ /dev/null @@ -1,52 +0,0 @@ -# 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 实测兼容性等技术事实。 diff --git a/docs/README.md b/docs/README.md index 00c6b0382..3f40f26c4 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,7 @@ │ (包含 api-v2 / database-v2 / development) │ │ 5. 想给领导、老师或评审专家进行生动展示？ ──► [docs/visual/] │ │ 6. 想查阅最终验收报告或历史自动化测试证据？ ──► [docs/reports/] │ +│ 7. 想查阅甲方原始需求与早期设计演进草案？ ──► [docs/archive/] │ └────────────────────────────────────────────────────────────────────────┘ ``` @@ -38,8 +39,9 @@ --- -### 2. 📋 [docs/requirements/](requirements/一期需求实现进度表.md) — 业务需求与确认清单 +### 2. 📋 [docs/requirements/](requirements/README.md) — 业务需求与确认清单 连接业务与代码的正式事实依据： +- [一期PRD-V1.0.md](requirements/一期PRD-V1.0.md)：一期系统正式业务需求冻结基线（领域对象、业务规则与输入输出约束） - [一期需求实现进度表.md](requirements/一期需求实现进度表.md)：按模块逐项核对每一条需求的前后端代码实现、页面位置与测试证据 - [甲方需求确认清单.md](requirements/甲方需求确认清单.md)：面向沈阳房建公寓段业务老师提炼的待确认分级清单（P0 核心 18 项、P1 细节 12 项、P2 规划 8 项） @@ -87,3 +89,12 @@ - **当前唯一终验报告**：[FINAL_PHASE1_20260917_101044/](reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/README.md)（含 [执行总摘要](reports/integrated-acceptance/FINAL_PHASE1_20260917_101044/executive-summary.md)） - **过程性测试证据**：Round 1~3B 自动化测试日志、DMS 实测探针、Playwright 无头浏览器运行截图 - **早期归档报告**：[archive/20260915/](reports/archive/20260915/)（已被终检报告全面覆盖的早期旧报告） + +--- + +### 7. 🏛️ [docs/archive/](archive/README.md) — 历史资料归档中心 +归档项目启动与早期研发阶段的原始交付与过程资产（HISTORICAL REFERENCE）： +- **[raw-materials/](archive/raw-materials/README.md)**：甲方原始交付需求、功能分析与初版数据表设计（docx / md 原件） +- **[requirements-history/](archive/requirements-history/README.md)**：需求演进过程稿（PRD V0.9、V0.1 调研表、业务基线草案） +- **[legacy-design/](archive/legacy-design/README.md)**：早期技术原型资料（详细开发说明书草案、ELK 拓扑原型） +- **[database-history/](archive/database-history/README.md)**：历史数据库设计资料（Kingbase DDL 规范草稿） diff --git a/docs/api-v2/00_readme.md b/docs/api-v2/00_readme.md index 18040e65b..1a97c9f81 100644 --- a/docs/api-v2/00_readme.md +++ b/docs/api-v2/00_readme.md @@ -1,8 +1,8 @@ # RailwaySystem Phase 2：API Contract / DTO-VO / Service Boundary Design > **阶段状态：** Phase 2 契约设计冻结稿 (Review Round 1 修订版) -> **业务最高基线：** `doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md` -> **数据持久化基线：** `doc/RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md` (21张表) +> **业务最高基线：** [一期 PRD V1.0](../requirements/一期PRD-V1.0.md) +> **数据持久化基线：** [`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) (21张表) > **代码生成器基线：** `generator-v2-ready-20260914` (只读验证通过) > **审查基线：** `docs/api-v2/12_contract_review_round1.md` (Review Round 1 判定通过: A) > **设计原则：** 业务工作台驱动 / 业务流程闭环驱动，坚决抵制 21 张表单表 CRUD 堆砌。 @@ -89,19 +89,19 @@ flowchart LR | 序号 | 文档名称 | 核心内容 | |:---|:---|:---| -| 00 | [`00_readme.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/00_readme.md) | 阶段总纲、架构全景、领域标识映射、最小合约视图与文档索引 | -| 01 | [`01_api_design_principles.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/01_api_design_principles.md) | API 架构原则、Resource vs Command、分页规范、返回包装与确定性/优先级定义 | -| 02 | [`02_module_a_base_resource_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/02_module_a_base_resource_api.md) | Module A 基础主数据 API 契约（教师、学员、课程、资源、教室、场地、班牌、宿舍） | -| 03 | [`03_module_b_plan_enrollment_schedule_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/03_module_b_plan_enrollment_schedule_api.md) | Module B 核心业务 API 契约（计划、工作台、本期课程、参训名单、排课冲突预检、课表、报到） | -| 04 | [`04_module_c_accommodation_attendance_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/04_module_c_accommodation_attendance_api.md) | Module C 过程执行 API 契约（宿舍预分配、调整、门禁同步、班牌签到/签退、考勤修正） | -| 05 | [`05_module_d_score_learning_statistics_api.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/05_module_d_score_learning_statistics_api.md) | Module D 业务成效 API 契约（成绩配置、打分台账、学习记录接入、统计下钻、学员画像） | -| 06 | [`06_dto_vo_catalog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/06_dto_vo_catalog.md) | DTO / VO 领域模型资产全集（明确字段、类型、校验规则与用例映射） | -| 07 | [`07_service_boundary.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/07_service_boundary.md) | 业务编排 Application Service 与基础 CRUD Service 的职责与协作边界 | -| 08 | [`08_transaction_and_invariants.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/08_transaction_and_invariants.md) | 事务控制边界、并发锁策略与 5 大跨表业务不变量 + 1 项报到生命周期策略落地规范 | -| 09 | [`09_external_adapter_contract.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/09_external_adapter_contract.md) | 外部适配器契约（班牌/人脸考勤、智能门禁、VR/3D学习接入，Mock与轻量异步机制） | -| 10 | [`10_permission_and_error_codes.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/10_permission_and_error_codes.md) | RuoYi RBAC 权限字符定义与全业务错误码模型规范 | -| 11 | [`11_open_questions.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/11_open_questions.md) | PRD V-01 ~ V-14 现场验证问题映射、API 影响与隔离应对策略 | -| 12 | [`12_contract_review_round1.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/api-v2/12_contract_review_round1.md) | Contract Review Round 1 审查报告（越界修正、P0/P1/P2裁定、结论A） | +| 00 | [`00_readme.md`](00_readme.md) | 阶段总纲、架构全景、领域标识映射、最小合约视图与文档索引 | +| 01 | [`01_api_design_principles.md`](01_api_design_principles.md) | API 架构原则、Resource vs Command、分页规范、返回包装与确定性/优先级定义 | +| 02 | [`02_module_a_base_resource_api.md`](02_module_a_base_resource_api.md) | Module A 基础主数据 API 契约（教师、学员、课程、资源、教室、场地、班牌、宿舍） | +| 03 | [`03_module_b_plan_enrollment_schedule_api.md`](03_module_b_plan_enrollment_schedule_api.md) | Module B 核心业务 API 契约（计划、工作台、本期课程、参训名单、排课冲突预检、课表、报到） | +| 04 | [`04_module_c_accommodation_attendance_api.md`](04_module_c_accommodation_attendance_api.md) | Module C 过程执行 API 契约（宿舍预分配、调整、门禁同步、班牌签到/签退、考勤修正） | +| 05 | [`05_module_d_score_learning_statistics_api.md`](05_module_d_score_learning_statistics_api.md) | Module D 业务成效 API 契约（成绩配置、打分台账、学习记录接入、统计下钻、学员画像） | +| 06 | [`06_dto_vo_catalog.md`](06_dto_vo_catalog.md) | DTO / VO 领域模型资产全集（明确字段、类型、校验规则与用例映射） | +| 07 | [`07_service_boundary.md`](07_service_boundary.md) | 业务编排 Application Service 与基础 CRUD Service 的职责与协作边界 | +| 08 | [`08_transaction_and_invariants.md`](08_transaction_and_invariants.md) | 事务控制边界、并发锁策略与 5 大跨表业务不变量 + 1 项报到生命周期策略落地规范 | +| 09 | [`09_external_adapter_contract.md`](09_external_adapter_contract.md) | 外部适配器契约（班牌/人脸考勤、智能门禁、VR/3D学习接入，Mock与轻量异步机制） | +| 10 | [`10_permission_and_error_codes.md`](10_permission_and_error_codes.md) | RuoYi RBAC 权限字符定义与全业务错误码模型规范 | +| 11 | [`11_open_questions.md`](11_open_questions.md) | PRD V-01 ~ V-14 现场验证问题映射、API 影响与隔离应对策略 | +| 12 | [`12_contract_review_round1.md`](12_contract_review_round1.md) | Contract Review Round 1 审查报告（越界修正、P0/P1/P2裁定、结论A） | --- diff --git a/docs/archive/README.md b/docs/archive/README.md new file mode 100644 index 000000000..fb2352bfe --- /dev/null +++ b/docs/archive/README.md @@ -0,0 +1,72 @@ +# SYFJGYD学员管理系统 — 历史资料归档中心 (Archive) + +> **历史归档声明 (HISTORICAL REFERENCE)**： +> 本目录归档存放项目启动与早期研发阶段的**甲方原始资料、早期需求草案、早期技术原型与历史数据库设计稿**。 +> 本目录所有内容仅供溯源、审计与沿革参考，**不作为当前系统实现的验收与业务依据**。 +> +> - **当前一期正式生效需求基线**：[docs/requirements/一期PRD-V1.0.md](../requirements/一期PRD-V1.0.md) +> - **当前一期需求代码实现状态**：[docs/requirements/一期需求实现进度表.md](../requirements/一期需求实现进度表.md) +> - **当前面向甲方待确认事项**：[docs/requirements/甲方需求确认清单.md](../requirements/甲方需求确认清单.md) +> - **当前数据库物理结构事实源**：[docs/database-v2/](../database-v2/01_table_inventory.md) 与 `RuoYi-Vue/sql/train/v2/` +> - **当前系统运行与试用现状**：[docs/current/](../current/README.md) + +--- + +## 🧭 历史资料组织架构 + +```text +docs/archive/ +├── README.md # 【本文件】统一历史资料归档入口全景导览 +├── raw-materials/ # 甲方原始交付需求、功能分析与初版数据表设计（docx / md 原件） +├── requirements-history/ # 需求演进过程稿（PRD V0.9、V0.1 调研表、业务基线草案） +├── legacy-design/ # 早期技术原型资料（详细开发说明书草案、ELK 拓扑原型） +└── database-history/ # 历史数据库设计资料（Kingbase DDL 规范草稿） +``` + +--- + +## 📂 归档子目录职责与清单 + +### 1. 甲方原始资料：`raw-materials/` +- **定位**：项目启动阶段业务方提供的原始需求文件、功能模块初稿与初版数据表设计草案。 +- **清单**： + - `学员管理系统相关需求.docx` / `.md`：业务方最初提出的学员、班级、住宿、培训宏观需求与业务设想； + - `学员管理系统功能分析_20260831.docx` / `.md`：培训系统功能模块拆解、业务流梳理与菜单原型规划初稿； + - `学员管理系统数据表设计_20260907_1_.docx` / `.md`：早期数据库数据表设计草案； + - `README.md`：原始交付材料说明与演变提示。 +- **演变说明**：所有有效需求已提炼至 [一期PRD-V1.0.md](../requirements/一期PRD-V1.0.md)，表结构差异详见 [14_database_code_diff.md](../codebase-audit/14_database_code_diff.md)。 + +### 2. 早期需求草案：`requirements-history/` +- **定位**：需求演进与讨论过程中的中间草稿，用于追溯决策依据。 +- **清单**： + - `RailwaySystem 智慧培训系统一期 PRD V0.9.md`：一期产品需求讨论草案（已升级为 V1.0）； + - `RailwaySystem 一期 P0 需求确认表 V0.1.md`：核心功能优先级研讨与业务确认清单； + - `RailwaySystem 一期需求分析与业务基线 V0.1.md`：面向业务方需求的初步分析与功能点映射草稿； + - `RailwaySystem 一期默认开发决策与需求假设 V0.1.md`：早期针对甲供资料不完备部分制定的默认技术假设； + - `README.md`：历史版本归档清单与核心演进对比。 + +### 3. 早期技术原型：`legacy-design/` +- **定位**：早期编写的系统设计与前端拓扑可视化原型（HISTORICAL REFERENCE）。 +- **清单**： + - `智慧培训系统一期详细开发说明书.md`：早期技术说明草案（基于旧数据表与旧需求）； + - `railwaysystem.html`：基于 ELK 布局引擎生成的培训系统架构与业务拓扑可视化原型； + - `elk.bundled.js`：前端拓扑布局引擎打包库； + - `README.md`：早期技术原型归档说明。 + +### 4. 旧数据库设计：`database-history/` +- **定位**：数据库建模阶段的历史设计冻结稿，供追溯字段设计思路。 +- **清单**： + - `RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`：早期数据表字段与 DDL 设计草案； + - `README.md`：明确该文档为历史设计资料，物理事实源已迁移至 `docs/database-v2/`。 + +--- + +## 📌 历史资料与当前正式入口对应关系 + +| 历史资料分类 | 对应历史文档 | 当前生效的正式替代入口 | 说明 | +| :--- | :--- | :--- | :--- | +| **正式业务需求** | `requirements-history/PRD V0.9` | [**docs/requirements/一期PRD-V1.0.md**](../requirements/一期PRD-V1.0.md) | 一期唯一正式冻结的业务需求基线。 | +| **需求实现跟踪** | `requirements-history/P0确认表` | [**docs/requirements/一期需求实现进度表.md**](../requirements/一期需求实现进度表.md) | 按功能点跟踪前后端代码与验证状态。 | +| **待确认事项** | `raw-materials/相关需求` | [**docs/requirements/甲方需求确认清单.md**](../requirements/甲方需求确认清单.md) | 聚焦待与段方开会对齐的业务事项。 | +| **数据库物理表** | `database-history/DDL规范` | [**docs/database-v2/01_table_inventory.md**](../database-v2/01_table_inventory.md) | 物理建表与初始化脚本位于 `RuoYi-Vue/sql/train/v2/`。 | +| **系统架构与指南** | `legacy-design/详细开发说明书` | [**docs/handbook/01-project-overview.md**](../handbook/01-project-overview.md) | 系统级团队操作手册与全景指南。 | diff --git a/docs/archive/database-history/README.md b/docs/archive/database-history/README.md new file mode 100644 index 000000000..f8c0e0aa3 --- /dev/null +++ b/docs/archive/database-history/README.md @@ -0,0 +1,24 @@ +# 历史数据库设计资料归档 (database-history) + +> **历史归档声明 (HISTORICAL REFERENCE)**： +> 本目录下的 [`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) 是数据库建模阶段的历史设计资料，仅供追溯设计演变与字段初衷参考。 +> **不得作为当前数据库物理结构与迁移的判定依据**。 + +--- + +## 🗄️ 当前真实数据库事实源 + +如需查阅当前系统正在使用的真实国产人大金仓（KingbaseES）物理表结构、字段定义、外键约束、索引以及 DDL 脚本，请务必以以下两处为唯一权威事实源： + +1. **结构设计与字段字典**：[**docs/database-v2/01_table_inventory.md**](../../database-v2/01_table_inventory.md) + （包含 21 张物理表字段清单、类型映射规范与索引说明）； +2. **可执行 DDL 生产脚本**：[`RuoYi-Vue/sql/train/v2/`](../../../RuoYi-Vue/sql/train/v2/) + （包含当前集成验收库与共享试用库所执行的最终物理表结构初始化 SQL）。 + +--- + +## 📋 包含的历史设计文件 + +| 文档名称 | 原始版本 | 性质说明 | +| :--- | :--- | :--- | +| [`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) | V1.0 (冻结设计稿) | 早期 21 张培训业务表字段设计草案与 Kingbase DDL 理论规范 | diff --git a/doc/RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md b/docs/archive/database-history/RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md similarity index 100% rename from doc/RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md rename to docs/archive/database-history/RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md diff --git a/doc/wxy_doc/README.md b/docs/archive/legacy-design/README.md similarity index 51% rename from doc/wxy_doc/README.md rename to docs/archive/legacy-design/README.md index 52d9d6218..64ff1839a 100644 --- a/doc/wxy_doc/README.md +++ b/docs/archive/legacy-design/README.md @@ -1,7 +1,9 @@ -# 早期技术参考资料（wxy_doc） +# 早期技术与原型设计资料归档 (legacy-design) -> **状态说明**：本目录为王杏月师姐早期编写的系统设计与前端拓扑可视化原型资料。**仅供技术演进与历史设计参考，不作为系统一期正式业务与实现基线**。 -> 一期最新最高业务基线请以根目录 [PRD V1.0](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md) 为准。 +> **历史归档声明 (HISTORICAL REFERENCE)**： +> 本目录归档存放王杏月师姐早期编写的系统设计与前端拓扑可视化原型资料。 +> **仅供技术演进与历史设计参考，不作为系统一期正式业务与实现基线**。 +> 一期最新最高业务基线请参见：[docs/requirements/一期PRD-V1.0.md](../../requirements/一期PRD-V1.0.md)。 --- diff --git a/doc/wxy_doc/elk.bundled.js b/docs/archive/legacy-design/elk.bundled.js similarity index 100% rename from doc/wxy_doc/elk.bundled.js rename to docs/archive/legacy-design/elk.bundled.js diff --git a/doc/wxy_doc/railwaysystem.html b/docs/archive/legacy-design/railwaysystem.html similarity index 100% rename from doc/wxy_doc/railwaysystem.html rename to docs/archive/legacy-design/railwaysystem.html diff --git a/doc/wxy_doc/智慧培训系统一期详细开发说明书.md b/docs/archive/legacy-design/智慧培训系统一期详细开发说明书.md similarity index 100% rename from doc/wxy_doc/智慧培训系统一期详细开发说明书.md rename to docs/archive/legacy-design/智慧培训系统一期详细开发说明书.md diff --git a/doc/raw_materials/README.md b/docs/archive/raw-materials/README.md similarity index 76% rename from doc/raw_materials/README.md rename to docs/archive/raw-materials/README.md index 8fd4b7410..07e2f97e5 100644 --- a/doc/raw_materials/README.md +++ b/docs/archive/raw-materials/README.md @@ -1,8 +1,8 @@ -# 甲方原始交付需求与设计资料（raw_materials） +# 甲方原始交付需求与设计资料（raw-materials） > **说明**：本目录归档存放项目启动与早期阶段甲方/业务方提供的原始需求、功能分析与初版数据表设计文档（包含原始 docx 及同名导出的 markdown 格式）。 -> -> **最高业务基线**：所有原始材料中的要求已全部整合、甄别并提炼至 [RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)。在需求冲突时，一律以 **PRD V1.0** 为准。 +> +> **最高业务基线**：所有原始材料中的要求已全部整合、甄别并提炼至 [一期PRD-V1.0.md](../../requirements/一期PRD-V1.0.md)。在需求冲突时，一律以 **PRD V1.0** 为准。 --- @@ -18,5 +18,5 @@ ## 演进与演变提示 -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)。 +1. **表结构演进**：`学员管理系统数据表设计_20260907_1_` 中定义的字段与当前生产 KingbaseES 数据库存在部分类型演进（如主键 identity、timestamp 等），且与 PRD V1.0 要求的开班计划—课程、参训关系、课次对象存在结构化演进，详见技术审计文档 [14_database_code_diff.md](../../codebase-audit/14_database_code_diff.md)。 2. **需求演进**：早期需求中模糊的门禁关联、签到联动与成绩结构，已在 PRD V1.0 中建立严格的业务边界定义。 diff --git a/doc/raw_materials/学员管理系统功能分析_20260831.docx b/docs/archive/raw-materials/学员管理系统功能分析_20260831.docx similarity index 100% rename from doc/raw_materials/学员管理系统功能分析_20260831.docx rename to docs/archive/raw-materials/学员管理系统功能分析_20260831.docx diff --git a/doc/raw_materials/学员管理系统功能分析_20260831.md b/docs/archive/raw-materials/学员管理系统功能分析_20260831.md similarity index 100% rename from doc/raw_materials/学员管理系统功能分析_20260831.md rename to docs/archive/raw-materials/学员管理系统功能分析_20260831.md diff --git a/doc/raw_materials/学员管理系统数据表设计_20260907_1_.docx b/docs/archive/raw-materials/学员管理系统数据表设计_20260907_1_.docx similarity index 100% rename from doc/raw_materials/学员管理系统数据表设计_20260907_1_.docx rename to docs/archive/raw-materials/学员管理系统数据表设计_20260907_1_.docx diff --git a/doc/raw_materials/学员管理系统数据表设计_20260907_1_.md b/docs/archive/raw-materials/学员管理系统数据表设计_20260907_1_.md similarity index 100% rename from doc/raw_materials/学员管理系统数据表设计_20260907_1_.md rename to docs/archive/raw-materials/学员管理系统数据表设计_20260907_1_.md diff --git a/doc/raw_materials/学员管理系统相关需求.docx b/docs/archive/raw-materials/学员管理系统相关需求.docx similarity index 100% rename from doc/raw_materials/学员管理系统相关需求.docx rename to docs/archive/raw-materials/学员管理系统相关需求.docx diff --git a/doc/raw_materials/学员管理系统相关需求.md b/docs/archive/raw-materials/学员管理系统相关需求.md similarity index 100% rename from doc/raw_materials/学员管理系统相关需求.md rename to docs/archive/raw-materials/学员管理系统相关需求.md diff --git a/doc/archive/README.md b/docs/archive/requirements-history/README.md similarity index 83% rename from doc/archive/README.md rename to docs/archive/requirements-history/README.md index 6e6babe13..5cb1df888 100644 --- a/doc/archive/README.md +++ b/docs/archive/requirements-history/README.md @@ -1,8 +1,8 @@ -# 历史过程稿与版本归档（archive） +# 需求演进过程稿与历史版本归档 (requirements-history) > **状态说明**：本目录归档存放项目需求梳理与演化过程中的历史中间稿、前期调研确认表及技术假设分析文档。 -> -> **最高业务基线**：当前系统一期唯一正式生效的业务基线为上一层目录中的 [RailwaySystem 智慧培训系统一期 PRD V1.0.md](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md)。本目录下的历史文档已全部被 V1.0 覆盖，仅供版本追溯和决策沿革查询。 +> +> **最高业务基线**：当前系统一期唯一正式生效的业务基线为 [一期PRD-V1.0.md](../../requirements/一期PRD-V1.0.md)。本目录下的历史文档已全部被 V1.0 覆盖，仅供版本追溯和决策沿革查询。 --- diff --git a/doc/archive/RailwaySystem 一期 P0 需求确认表 V0.1.md b/docs/archive/requirements-history/RailwaySystem 一期 P0 需求确认表 V0.1.md similarity index 100% rename from doc/archive/RailwaySystem 一期 P0 需求确认表 V0.1.md rename to docs/archive/requirements-history/RailwaySystem 一期 P0 需求确认表 V0.1.md diff --git a/doc/archive/RailwaySystem 一期需求分析与业务基线 V0.1.md b/docs/archive/requirements-history/RailwaySystem 一期需求分析与业务基线 V0.1.md similarity index 100% rename from doc/archive/RailwaySystem 一期需求分析与业务基线 V0.1.md rename to docs/archive/requirements-history/RailwaySystem 一期需求分析与业务基线 V0.1.md diff --git a/doc/archive/RailwaySystem 一期默认开发决策与需求假设 V0.1.md b/docs/archive/requirements-history/RailwaySystem 一期默认开发决策与需求假设 V0.1.md similarity index 100% rename from doc/archive/RailwaySystem 一期默认开发决策与需求假设 V0.1.md rename to docs/archive/requirements-history/RailwaySystem 一期默认开发决策与需求假设 V0.1.md diff --git a/doc/archive/RailwaySystem 智慧培训系统一期 PRD V0.9.md b/docs/archive/requirements-history/RailwaySystem 智慧培训系统一期 PRD V0.9.md similarity index 100% rename from doc/archive/RailwaySystem 智慧培训系统一期 PRD V0.9.md rename to docs/archive/requirements-history/RailwaySystem 智慧培训系统一期 PRD V0.9.md diff --git a/docs/current/02-phase1-status.md b/docs/current/02-phase1-status.md index 7e006d39b..f6250f06a 100644 --- a/docs/current/02-phase1-status.md +++ b/docs/current/02-phase1-status.md @@ -23,6 +23,7 @@ 如需查阅每一条需求的详细代码文件位置、SQL 表名、测试用例或具体待确认问题，请点击以下权威文档： +- 📖 [**一期 PRD V1.0 (业务定义与需求基线)**](../requirements/一期PRD-V1.0.md)：一期系统正式业务需求冻结基线，涵盖核心领域对象、业务规则与一期开发边界。 - 📋 [**一期需求实现进度表 (逐项核验)**](../requirements/一期需求实现进度表.md)：包含域 A~G 共数十项功能点的前后端代码文件、断言证据与下一步建议。 - ❓ [**一期甲方需求确认清单 (开会对齐)**](../requirements/甲方需求确认清单.md)：系统归纳 P0(核心阻塞 18 项)、P1(业务形态 12 项)、P2(长远规划 8 项) 业务确认表。 diff --git a/docs/database-v2/00_readme.md b/docs/database-v2/00_readme.md index ce1e6f0c1..5251d1a9e 100644 --- a/docs/database-v2/00_readme.md +++ b/docs/database-v2/00_readme.md @@ -1,9 +1,9 @@ # RailwaySystem 数据库 V2 DDL 生成与设计审查概览 (Round 2 最终静态收尾版) -> **设计状态**：数据库 V2 物理 DDL 最终静态收尾就绪（已完成 Round 2 全部 7 项缺陷修复，达到“允许进入测试迁移”标准） -> **最高依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) -> **业务背景参考**：[`RailwaySystem 智慧培训系统一期 PRD V1.0.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem%20智慧培训系统一期%20PRD%20V1.0.md) -> **技术基线**：`main@4b450f46`，KingbaseES V009R003C018 (`database=training`, `schema=public`, `database_mode=mysql`) +> **设计状态**：数据库 V2 物理 DDL 最终静态收尾就绪（已完成 Round 2 全部 7 项缺陷修复，达到“允许进入测试迁移”标准） +> **最高依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) +> **业务背景参考**：[`一期 PRD V1.0`](../requirements/一期PRD-V1.0.md) +> **技术基线**：`main@4b450f46`，KingbaseES V009R003C018 (`database=training`, `schema=public`, `database_mode=mysql`) > **操作定位**：**纯静态收尾与审查阶段**（严禁执行 SQL、严禁修改真实库、严禁改动业务代码、严禁自动 git commit）。 --- @@ -30,49 +30,49 @@ | 序号 / 关卡 | 脚本文件 | 事务边界 | 核心职责 | | :---: | :--- | :---: | :--- | -| **Gate A** | [`000_tx_capability_probe.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) | 探针显式事务 | **执行前能力探针**：测试 DDL 事务回滚能力，若表残留强行阻断 | -| **Gate B** | [`000_preflight.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_preflight.sql) | 纯只读骨架断言 | **Phase 0.5 骨架强校验**：集合差集校验 14 PK + 24 FK + 7 UNIQUE + 6 Identity + 9 Triggers | -| **Stage 1** | [`001_backup_current_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | `BEGIN ... COMMIT` | 备份当前 14 张表数据快照；增加防覆盖强校验，禁止 DROP CASCADE | -| **Stage 2** | [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | `BEGIN ... COMMIT` | 创建 8 张 V2 新表（无 `IF NOT EXISTS`，住宿默认0预分配，无业务默认值） | -| **Stage 3** | [`003_alter_master_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | `BEGIN ... COMMIT` | 卸载旧触发器与外键，调整 8 张主表（严格 `ADD COLUMN`，加容量 CHECK） | -| **Stage 4** | [`004_rebuild_business_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) | `BEGIN ... COMMIT` | 校验 0 行后重构 5 张表（删除 `verify_result`/`checkin_way` 业务默认值） | -| **Stage 5** | [`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql) | `BEGIN ... COMMIT` | 集中定义 13 组 UNIQUE、26 组 `ON DELETE NO ACTION` 外键与 9 条单行 CHECK | -| **Stage 6** | [`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql) | `BEGIN ... COMMIT` | 建立外键索引、排课复合冲突索引与双非空过滤的部分唯一索引（无 `IF NOT EXISTS`） | -| **-** | [`007_dicts.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/007_dicts.sql) | - | 声明 16 组业务字典注册脚本（**本结构迁移阶段跳过不执行**，留待权限阶段） | -| **Stage 7** | [`008_migrate_teacher.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | `BEGIN ... COMMIT` | 平滑迁移 1 条教师真实数据，校验完整后固化 `status`/`del_flag` 为 NOT NULL 并删除旧列 | -| **Stage 8** | [`009_drop_legacy_score.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql) | `BEGIN ... COMMIT` | 前置 0 行强阻断校验后，显式解绑旧约束，常规 DROP 淘汰旧表 `train_score_info` | -| **Stage 9** | [`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) | 纯只读深度断言 | **“定义级深度验收”** 全量自动化强断言（逐表、列列表、外键删除规则、CHECK定义、默认值） | +| **Gate A** | [`000_tx_capability_probe.sql`](../../RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) | 探针显式事务 | **执行前能力探针**：测试 DDL 事务回滚能力，若表残留强行阻断 | +| **Gate B** | [`000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql) | 纯只读骨架断言 | **Phase 0.5 骨架强校验**：集合差集校验 14 PK + 24 FK + 7 UNIQUE + 6 Identity + 9 Triggers | +| **Stage 1** | [`001_backup_current_schema.sql`](../../RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | `BEGIN ... COMMIT` | 备份当前 14 张表数据快照；增加防覆盖强校验，禁止 DROP CASCADE | +| **Stage 2** | [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | `BEGIN ... COMMIT` | 创建 8 张 V2 新表（无 `IF NOT EXISTS`，住宿默认0预分配，无业务默认值） | +| **Stage 3** | [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | `BEGIN ... COMMIT` | 卸载旧触发器与外键，调整 8 张主表（严格 `ADD COLUMN`，加容量 CHECK） | +| **Stage 4** | [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) | `BEGIN ... COMMIT` | 校验 0 行后重构 5 张表（删除 `verify_result`/`checkin_way` 业务默认值） | +| **Stage 5** | [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) | `BEGIN ... COMMIT` | 集中定义 13 组 UNIQUE、26 组 `ON DELETE NO ACTION` 外键与 9 条单行 CHECK | +| **Stage 6** | [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) | `BEGIN ... COMMIT` | 建立外键索引、排课复合冲突索引与双非空过滤的部分唯一索引（无 `IF NOT EXISTS`） | +| **-** | [`007_dicts.sql`](../../RuoYi-Vue/sql/train/v2/007_dicts.sql) | - | 声明 16 组业务字典注册脚本（**本结构迁移阶段跳过不执行**，留待权限阶段） | +| **Stage 7** | [`008_migrate_teacher.sql`](../../RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | `BEGIN ... COMMIT` | 平滑迁移 1 条教师真实数据，校验完整后固化 `status`/`del_flag` 为 NOT NULL 并删除旧列 | +| **Stage 8** | [`009_drop_legacy_score.sql`](../../RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql) | `BEGIN ... COMMIT` | 前置 0 行强阻断校验后，显式解绑旧约束，常规 DROP 淘汰旧表 `train_score_info` | +| **Stage 9** | [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) | 纯只读深度断言 | **“定义级深度验收”** 全量自动化强断言（逐表、列列表、外键删除规则、CHECK定义、默认值） | ### 2.2 应急回滚资产清单 (`RuoYi-Vue/sql/train/v2/rollback/`) | 序号 | 回滚文件 | 核心职责 | | :---: | :--- | :--- | -| **0** | [`000_phase05_exact_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql) | **Phase 0.5 真实物理基线 DDL**（14表字段、PK、24个FK、7组UNIQUE、9个触发器） | -| **1** | [`001_rollback_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/001_rollback_new_tables.sql) | 显式解除外键依赖，按拓扑反序常规 DROP 8 张 V2 新增表（`BEGIN ... COMMIT`） | -| **2** | [`002_rollback_modified_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/002_rollback_modified_tables.sql) | 基于 `000_phase05_exact_schema.sql` 精确结构重建 13 张表，灌回 `bak_v1_*` 数据并核验教师行数 | -| **3** | [`003_restore_legacy_score.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/003_restore_legacy_score.sql) | 基于精确 DDL 重建历史 `train_score_info` 表及 3 个外键与唯一约束 | -| **4** | [`README.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/README.md) | 应急回滚指南（解耦结构与数据，明确依赖 `000` 结构与 `bak_v1_*` 数据的执行规范） | +| **0** | [`000_phase05_exact_schema.sql`](../../RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql) | **Phase 0.5 真实物理基线 DDL**（14表字段、PK、24个FK、7组UNIQUE、9个触发器） | +| **1** | [`001_rollback_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/rollback/001_rollback_new_tables.sql) | 显式解除外键依赖，按拓扑反序常规 DROP 8 张 V2 新增表（`BEGIN ... COMMIT`） | +| **2** | [`002_rollback_modified_tables.sql`](../../RuoYi-Vue/sql/train/v2/rollback/002_rollback_modified_tables.sql) | 基于 `000_phase05_exact_schema.sql` 精确结构重建 13 张表，灌回 `bak_v1_*` 数据并核验教师行数 | +| **3** | [`003_restore_legacy_score.sql`](../../RuoYi-Vue/sql/train/v2/rollback/003_restore_legacy_score.sql) | 基于精确 DDL 重建历史 `train_score_info` 表及 3 个外键与唯一约束 | +| **4** | [`README.md`](../../RuoYi-Vue/sql/train/v2/rollback/README.md) | 应急回滚指南（解耦结构与数据，明确依赖 `000` 结构与 `bak_v1_*` 数据的执行规范） | ### 2.3 架构与设计审查技术文档 (`docs/database-v2/`) | 序号 | 文档名称 | 主要内容 | | :---: | :--- | :--- | -| **1** | [`00_readme.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/00_readme.md) | 本阶段全景综述、规范基线与资产索引导航 | -| **2** | [`01_table_inventory.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/01_table_inventory.md) | 21 张正式业务表清单、新旧对比、三大核心 ID 落地映射、字段默认值修正 | -| **3** | [`02_migration_plan.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/02_migration_plan.md) | 迁移执行流水线、双门禁 (Gate A/B) 准入机制、单文件显式事务边界与断点恢复 | -| **4** | [`03_constraint_index_review.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/03_constraint_index_review.md) | PK、26 组 NO ACTION 外键、13 组 UNIQUE、9 条 CHECK 与复合索引全面审查 | -| **5** | [`04_risk_review.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/04_risk_review.md) | **R-01 至 R-17** 全景风险深度剖析（固化架构决策 A/B，解耦双 source_type） | -| **6** | [`05_execution_contract.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/05_execution_contract.md) | **执行契约**（Gate A 事务探针 + Gate B 精确骨架 + 显式事务与即刻熔断） | -| **7** | [`06_review_round1_changes.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/06_review_round1_changes.md) | **Round 1 修订闭环记录表**（17 项评审意见落实明细） | -| **8** | [`07_review_round2_changes.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/07_review_round2_changes.md) | **Round 2 修订闭环记录表**（R2-01 ~ R2-07 最终静态收尾明细） | +| **1** | [`00_readme.md`](00_readme.md) | 本阶段全景综述、规范基线与资产索引导航 | +| **2** | [`01_table_inventory.md`](01_table_inventory.md) | 21 张正式业务表清单、新旧对比、三大核心 ID 落地映射、字段默认值修正 | +| **3** | [`02_migration_plan.md`](02_migration_plan.md) | 迁移执行流水线、双门禁 (Gate A/B) 准入机制、单文件显式事务边界与断点恢复 | +| **4** | [`03_constraint_index_review.md`](03_constraint_index_review.md) | PK、26 组 NO ACTION 外键、13 组 UNIQUE、9 条 CHECK 与复合索引全面审查 | +| **5** | [`04_risk_review.md`](04_risk_review.md) | **R-01 至 R-17** 全景风险深度剖析（固化架构决策 A/B，解耦双 source_type） | +| **6** | [`05_execution_contract.md`](05_execution_contract.md) | **执行契约**（Gate A 事务探针 + Gate B 精确骨架 + 显式事务与即刻熔断） | +| **7** | [`06_review_round1_changes.md`](06_review_round1_changes.md) | **Round 1 修订闭环记录表**（17 项评审意见落实明细） | +| **8** | [`07_review_round2_changes.md`](07_review_round2_changes.md) | **Round 2 修订闭环记录表**（R2-01 ~ R2-07 最终静态收尾明细） | --- ## 3. 人工 Review 准入与优先建议 建议高级技术负责人优先 Review 以下关键文件： -1. **优先审查 Round 2 修订记录表**：[`docs/database-v2/07_review_round2_changes.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/07_review_round2_changes.md)（核验 R2-01 ~ R2-07 修复明细）； -2. **优先审查执行契约与探针**：[`docs/database-v2/05_execution_contract.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/05_execution_contract.md) 与 [`RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql)（核验 Gate A 事务原子性实证机制）； -3. **优先审查 Preflight 骨架校验**：[`RuoYi-Vue/sql/train/v2/000_preflight.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_preflight.sql)（核验集合比对 14 PK + 24 FK + 7 UNIQUE + 6 Identity + 9 Triggers）； -4. **优先审查 Verify 定义级验收**：[`RuoYi-Vue/sql/train/v2/010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql)（核验定义级断言、CHECK 逻辑与默认值强断言）； -5. **优先审查核心建表与重构脚本**：[`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) 与 [`004_rebuild_business_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql)（核验无 `IF NOT EXISTS`、无业务默认值及住宿状态 0）。 +1. **优先审查 Round 2 修订记录表**：[`docs/database-v2/07_review_round2_changes.md`](07_review_round2_changes.md)（核验 R2-01 ~ R2-07 修复明细）； +2. **优先审查执行契约与探针**：[`docs/database-v2/05_execution_contract.md`](05_execution_contract.md) 与 [`RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql`](../../RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql)（核验 Gate A 事务原子性实证机制）； +3. **优先审查 Preflight 骨架校验**：[`RuoYi-Vue/sql/train/v2/000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql)（核验集合比对 14 PK + 24 FK + 7 UNIQUE + 6 Identity + 9 Triggers）； +4. **优先审查 Verify 定义级验收**：[`RuoYi-Vue/sql/train/v2/010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql)（核验定义级断言、CHECK 逻辑与默认值强断言）； +5. **优先审查核心建表与重构脚本**：[`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) 与 [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql)（核验无 `IF NOT EXISTS`、无业务默认值及住宿状态 0）。 diff --git a/docs/database-v2/01_table_inventory.md b/docs/database-v2/01_table_inventory.md index 1121375da..8125897ac 100644 --- a/docs/database-v2/01_table_inventory.md +++ b/docs/database-v2/01_table_inventory.md @@ -1,6 +1,6 @@ # RailwaySystem 数据库 V2 表结构清单与模型比对 (Round 1 修订版) -> **技术依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) +> **技术依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) > **状态**：一期 21 张培训业务表全覆盖冻结清单（已完成 Round 1 字段与约束精确审查修订）。 --- @@ -47,9 +47,9 @@ V2 架构通过三个领域核心 ID 彻底取代旧模型中跨多表重复冗 | 核心 ID 标识 | 业务实体表 | 业务语义 | 衍生与引用的业务表 | | :--- | :--- | :--- | :--- | -| **`enrollment_id`** | [`train_enrollment`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L72) | **某学员参加某一期培训班的参训全生命周期档案** | `train_accommodation`
`train_class_report`
`train_student_checkin`
`train_student_score`
`train_study_duration`
`train_student_portrait` | -| **`plan_course_id`** | [`train_plan_course`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L52) | **某一期培训班中包含的某一门具体课程实例** | `train_lesson`
`train_score_item`
`train_study_duration` | -| **`lesson_id`** | [`train_lesson`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L106) | **本期某门课程中的具体一次教学活动（课表课次）** | `train_student_checkin` | +| **`enrollment_id`** | [`train_enrollment`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L72) | **某学员参加某一期培训班的参训全生命周期档案** | `train_accommodation`
`train_class_report`
`train_student_checkin`
`train_student_score`
`train_study_duration`
`train_student_portrait` | +| **`plan_course_id`** | [`train_plan_course`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L52) | **某一期培训班中包含的某一门具体课程实例** | `train_lesson`
`train_score_item`
`train_study_duration` | +| **`lesson_id`** | [`train_lesson`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L106) | **本期某门课程中的具体一次教学活动（课表课次）** | `train_student_checkin` | --- diff --git a/docs/database-v2/02_migration_plan.md b/docs/database-v2/02_migration_plan.md index dc6238af5..df4440b5a 100644 --- a/docs/database-v2/02_migration_plan.md +++ b/docs/database-v2/02_migration_plan.md @@ -1,7 +1,7 @@ # RailwaySystem 数据库 V2 迁移执行计划 (Round 1 修订版) -> **执行基线**：KingbaseES V009R003C018 (`schema=public`) -> **设计依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) 及 Round 1 审查要求 +> **执行基线**：KingbaseES V009R003C018 (`schema=public`) +> **设计依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) 及 Round 1 审查要求 > **前置条件**：当前正式库中 `train_teacher` 精确包含 1 行数据，其余 13 张现有表均为 0 行。 --- @@ -36,7 +36,7 @@ flowchart TD ## 2. 阶段明细与操作规范 ### Stage 0: 只读基线预检 Preflight -- **执行脚本**：[`000_preflight.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_preflight.sql) +- **执行脚本**：[`000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql) - **目标**：纯只读排查当前环境确实精确处于 Phase 0.5 初始状态。 - **核验准则**： - 14 张旧表全部存在，8 张 V2 新表均不存在； @@ -45,35 +45,35 @@ flowchart TD - **阻断控制**：任何一项不符合，立即抛出异常中止，拒绝进入未知环境。 ### Stage 1: 数据快照备份 -- **执行脚本**：[`001_backup_current_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) +- **执行脚本**：[`001_backup_current_schema.sql`](../../RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) - **目标**：在显式事务中为当前 14 张培训旧表建立物理快照（`bak_v1_*`）。 - **防覆盖控制**：若检测到既有 `bak_v1_*` 已存在，立即抛出异常强阻断，杜绝二次执行覆盖最初 V1 备份。 ### Stage 2: 物理结构准备 - **执行脚本**： - 1. [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql)：新建 8 张 V2 表（`t_id` 必填，场地互斥 CHECK，分数非负 CHECK）； - 2. [`003_alter_master_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql)：卸载主数据旧触发器，显式解除旧外键，调整 8 张主数据表结构（移除猜测默认值，加 `capacity > 0` CHECK）； - 3. [`004_rebuild_business_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql)：校验 0 行后，显式解绑旧外键并常规 DROP，按照 `enrollment_id` / `lesson_id` 重建 5 张业务表（增加学时时间与单号系统匹配 CHECK）。 + 1. [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql)：新建 8 张 V2 表（`t_id` 必填，场地互斥 CHECK，分数非负 CHECK）； + 2. [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql)：卸载主数据旧触发器，显式解除旧外键，调整 8 张主数据表结构（移除猜测默认值，加 `capacity > 0` CHECK）； + 3. [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql)：校验 0 行后，显式解绑旧外键并常规 DROP，按照 `enrollment_id` / `lesson_id` 重建 5 张业务表（增加学时时间与单号系统匹配 CHECK）。 ### Stage 3: 完整性约束与索引注入 - **执行脚本**： - 1. [`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql)：集中为 21 张表建立 13 组 UNIQUE 约束、26 组 `ON DELETE NO ACTION` 外键与全量单行 CHECK 约束； - 2. [`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql)：创建外键索引、排课多维复合冲突索引及双非空部分唯一索引。 + 1. [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql)：集中为 21 张表建立 13 组 UNIQUE 约束、26 组 `ON DELETE NO ACTION` 外键与全量单行 CHECK 约束； + 2. [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql)：创建外键索引、排课多维复合冲突索引及双非空部分唯一索引。 ### Stage 4: 数据平滑迁移与旧表淘汰 - **执行脚本**： - 1. [`008_migrate_teacher.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql)：将教师历史数据映射至新列，校验数据完整性后将 `status` 与 `del_flag` 固化为 NOT NULL，安全删除旧列； - 2. [`009_drop_legacy_score.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql)：前置 0 行校验后，显式解除历史约束并安全常规 DROP。 + 1. [`008_migrate_teacher.sql`](../../RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql)：将教师历史数据映射至新列，校验数据完整性后将 `status` 与 `del_flag` 固化为 NOT NULL，安全删除旧列； + 2. [`009_drop_legacy_score.sql`](../../RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql)：前置 0 行校验后，显式解除历史约束并安全常规 DROP。 ### Stage 5: 全面自动化强断言验收 -- **执行脚本**：[`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) +- **执行脚本**：[`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) - **目标**：实现“失败即失败”，逐表逐项强断言，出现任何偏差直接抛异常报错。 --- ## 3. 业务字典脚本定位特别说明 -[`007_dicts.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/007_dicts.sql) **在当前数据库结构迁移阶段明确跳过、不执行**。 +[`007_dicts.sql`](../../RuoYi-Vue/sql/train/v2/007_dicts.sql) **在当前数据库结构迁移阶段明确跳过、不执行**。 原因：该脚本向 `sys_dict_*` 系统表写入业务字典数据，属于 API 契约与权限设计范畴。当前阶段保持数据库结构与应用层配置解耦，待后续权限设计阶段统一执行。 --- @@ -81,4 +81,4 @@ flowchart TD ## 4. 断点恢复与精确回滚机制 - **单脚本失败自动撤销**：由于各脚本包含显式 `BEGIN ... COMMIT`，单脚本内部任何错误会自动触发事务 ROLLBACK，数据库保持在上一个脚本执行成功的整齐状态； -- **精确全量回滚保障**：若需全量还原，严格基于 [`rollback/000_phase05_exact_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql) 的真实物理 DDL 重建结构，结合 `bak_v1_*` 快照灌回数据，彻底消除 CTAS 丢失结构缺陷。 +- **精确全量回滚保障**：若需全量还原，严格基于 [`rollback/000_phase05_exact_schema.sql`](../../RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql) 的真实物理 DDL 重建结构，结合 `bak_v1_*` 快照灌回数据，彻底消除 CTAS 丢失结构缺陷。 diff --git a/docs/database-v2/03_constraint_index_review.md b/docs/database-v2/03_constraint_index_review.md index 64e18576c..c06f75dcc 100644 --- a/docs/database-v2/03_constraint_index_review.md +++ b/docs/database-v2/03_constraint_index_review.md @@ -1,7 +1,7 @@ # RailwaySystem 数据库 V2 约束与索引技术审查报告 (Round 1 修订版) -> **审查依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/doc/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) 及 Round 1 审查要求 -> **审查对象**：[`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql) 与 [`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql) +> **审查依据**：[`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md`](../archive/database-history/RailwaySystem%20数据库%20V2%20字段设计与%20Kingbase%20DDL%20规范%20V1.0.md) 及 Round 1 审查要求 +> **审查对象**：[`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) 与 [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) --- @@ -114,7 +114,7 @@ V2 DDL 共注入 13 组核心业务 UNIQUE 约束： ## 5. 索引（INDEX）审查 -[`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql) 包含外键索引、排课多维复合索引与部分唯一索引： +[`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) 包含外键索引、排课多维复合索引与部分唯一索引： 1. **外键索引**：为所有 26 组外键列配置独立 B-Tree 索引，杜绝父表更新锁定子表或关联全表扫描； 2. **排课多维冲突高频复合索引**： diff --git a/docs/database-v2/04_risk_review.md b/docs/database-v2/04_risk_review.md index 98482a4ed..9807f1149 100644 --- a/docs/database-v2/04_risk_review.md +++ b/docs/database-v2/04_risk_review.md @@ -1,7 +1,7 @@ # RailwaySystem 数据库 V2 关键设计风险深度审查报告 (R-01 ~ R-17) -> **审查定位**：数据库底层引擎兼容性、约束边界、数据一致性与应用层 Service 协同审查 -> **技术基线**：KingbaseES V009R003C018 (`schema=public`, `database_mode=mysql`)、MyBatis 3.5.x、RuoYi-Vue 基础架构 +> **审查定位**：数据库底层引擎兼容性、约束边界、数据一致性与应用层 Service 协同审查 +> **技术基线**：KingbaseES V009R003C018 (`schema=public`, `database_mode=mysql`)、MyBatis 3.5.x、RuoYi-Vue 基础架构 > **版本状态**：Round 2 审查最终静态收尾版（固化架构决策 A/B，解耦 source_type 语义，清除业务选择型默认值） --- diff --git a/docs/database-v2/05_execution_contract.md b/docs/database-v2/05_execution_contract.md index b15f99593..21923cc1f 100644 --- a/docs/database-v2/05_execution_contract.md +++ b/docs/database-v2/05_execution_contract.md @@ -1,7 +1,7 @@ # RailwaySystem 数据库 V2 迁移执行契约 (Execution Contract) -> **适用范围**：数据库 V2 迁移在测试环境与未来生产环境中的正式执行规范 -> **技术基线**：KingbaseES V009R003C018 (`database=training`, `schema=public`, `database_mode=mysql`) +> **适用范围**：数据库 V2 迁移在测试环境与未来生产环境中的正式执行规范 +> **技术基线**：KingbaseES V009R003C018 (`database=training`, `schema=public`, `database_mode=mysql`) > **核心原则**：**双门禁强准入 (Gate A/B)、单文件显式事务、纯 SQL 执行器兼容、失败即刻熔断** --- @@ -43,18 +43,18 @@ graph TD | 阶段 | 脚本文件 | 事务边界 | 失败处理与影响 | | :---: | :--- | :---: | :--- | -| **Gate A** | [`000_tx_capability_probe.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) | 探针显式事务 | **强阻断**：实证探测实例 DDL 回滚能力。若表残留立即抛出异常并中止，严禁进入后续阶段 | -| **Gate B** | [`000_preflight.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_preflight.sql) | 纯只读骨架断言 | **强阻断**：集合差集校验 14旧表PK、24旧表FK、7组UNIQUE、6个identity主键、9触发器与行数基线，任何不符立即中止 | -| **Stage 1** | [`001_backup_current_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | `BEGIN ... COMMIT` | **强阻断**：全量快照 14 张表至 `bak_v1_*`；若已存在备份表则阻断；失败全单回滚 | -| **Stage 2** | [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | `BEGIN ... COMMIT` | 创建 V2 新增 8 张表；严禁 `IF NOT EXISTS`；失败事务回滚，新表全部撤销 | -| **Stage 3** | [`003_alter_master_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | `BEGIN ... COMMIT` | 调整 8 张主数据表；移除旧触发器与阻断外键，添加 V2 新列；失败事务回滚 | -| **Stage 4** | [`004_rebuild_business_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) | `BEGIN ... COMMIT` | 断言 0 行后重构 5 张业务表；失败事务回滚，原表结构保持不变 | -| **Stage 5** | [`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql) | `BEGIN ... COMMIT` | 集中注入 13 组 UNIQUE、26 组 FK (NO ACTION)、9 组 CHECK；失败事务回滚 | -| **Stage 6** | [`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql) | `BEGIN ... COMMIT` | 创建外键索引、排课多维复合索引及双非空部分唯一索引；失败事务回滚 | -| **-** | [`007_dicts.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/007_dicts.sql) | - | **【本迁移流水线跳过不执行】** 业务字典留待应用接口及权限配置阶段接入 | -| **Stage 7** | [`008_migrate_teacher.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | `BEGIN ... COMMIT` | 迁移并断言教师 1 行数据，固化 NOT NULL，安全清理旧列；失败事务回滚 | -| **Stage 8** | [`009_drop_legacy_score.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql) | `BEGIN ... COMMIT` | 断言 0 行后下线旧表 `train_score_info`；失败事务回滚，旧表完好保留 | -| **Stage 9** | [`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) | 纯只读深度断言 | **强阻断**：定义级全量验收 21 表、UNIQUE 列清单、FK NO ACTION、CHECK 表达式、12 Identity、默认值及系统表零受损 | +| **Gate A** | [`000_tx_capability_probe.sql`](../../RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) | 探针显式事务 | **强阻断**：实证探测实例 DDL 回滚能力。若表残留立即抛出异常并中止，严禁进入后续阶段 | +| **Gate B** | [`000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql) | 纯只读骨架断言 | **强阻断**：集合差集校验 14旧表PK、24旧表FK、7组UNIQUE、6个identity主键、9触发器与行数基线，任何不符立即中止 | +| **Stage 1** | [`001_backup_current_schema.sql`](../../RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | `BEGIN ... COMMIT` | **强阻断**：全量快照 14 张表至 `bak_v1_*`；若已存在备份表则阻断；失败全单回滚 | +| **Stage 2** | [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | `BEGIN ... COMMIT` | 创建 V2 新增 8 张表；严禁 `IF NOT EXISTS`；失败事务回滚，新表全部撤销 | +| **Stage 3** | [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | `BEGIN ... COMMIT` | 调整 8 张主数据表；移除旧触发器与阻断外键，添加 V2 新列；失败事务回滚 | +| **Stage 4** | [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) | `BEGIN ... COMMIT` | 断言 0 行后重构 5 张业务表；失败事务回滚，原表结构保持不变 | +| **Stage 5** | [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) | `BEGIN ... COMMIT` | 集中注入 13 组 UNIQUE、26 组 FK (NO ACTION)、9 组 CHECK；失败事务回滚 | +| **Stage 6** | [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) | `BEGIN ... COMMIT` | 创建外键索引、排课多维复合索引及双非空部分唯一索引；失败事务回滚 | +| **-** | [`007_dicts.sql`](../../RuoYi-Vue/sql/train/v2/007_dicts.sql) | - | **【本迁移流水线跳过不执行】** 业务字典留待应用接口及权限配置阶段接入 | +| **Stage 7** | [`008_migrate_teacher.sql`](../../RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | `BEGIN ... COMMIT` | 迁移并断言教师 1 行数据，固化 NOT NULL，安全清理旧列；失败事务回滚 | +| **Stage 8** | [`009_drop_legacy_score.sql`](../../RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql) | `BEGIN ... COMMIT` | 断言 0 行后下线旧表 `train_score_info`；失败事务回滚，旧表完好保留 | +| **Stage 9** | [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) | 纯只读深度断言 | **强阻断**：定义级全量验收 21 表、UNIQUE 列清单、FK NO ACTION、CHECK 表达式、12 Identity、默认值及系统表零受损 | --- @@ -87,6 +87,6 @@ graph TD - 若流水线中任何一个脚本执行报错，**严禁跳过该步骤继续执行后续脚本**！ - 单文件具备 `BEGIN ... COMMIT`，当前失败脚本的所有物理改动会自动回滚撤销。 2. **应急回滚调用准则**： - - 若在 Stage 2 ~ Stage 8 中途发生不可调和的异常，必须立即暂停，并由 DBA 评估调用 [`rollback/`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/) 脚本； + - 若在 Stage 2 ~ Stage 8 中途发生不可调和的异常，必须立即暂停，并由 DBA 评估调用 [`rollback/`](../../RuoYi-Vue/sql/train/v2/rollback/) 脚本； - 回滚流水线严格按照：`001_rollback_new_tables.sql` -> `002_rollback_modified_tables.sql` -> `003_restore_legacy_score.sql` 倒序执行； - 回滚完毕后，必须运行 `000_preflight.sql` 校验是否完全恢复至 Phase 0.5 精确基线。 diff --git a/docs/database-v2/06_review_round1_changes.md b/docs/database-v2/06_review_round1_changes.md index 667d78bdd..52c8211ae 100644 --- a/docs/database-v2/06_review_round1_changes.md +++ b/docs/database-v2/06_review_round1_changes.md @@ -1,7 +1,7 @@ # RailwaySystem 数据库 V2 DDL Review 修订记录表 (Round 1) -> **评审周期**：Round 1 -> **评审基线**：高级技术负责人第一轮人工 Review 意见 +> **评审周期**：Round 1 +> **评审基线**：高级技术负责人第一轮人工 Review 意见 > **状态**：**已全部闭环解决 (100% Resolved)** --- @@ -10,20 +10,20 @@ | 问题编号 | 模块分类 | 原问题描述 | 涉及修改文件 | 具体修改内容与工程落地 | 解决状态 | | :---: | :---: | :--- | :--- | :--- | :---: | -| **REV-01** | **P0 架构** | 破坏性迁移脚本无事务边界，遇错可能部分提交；包含客户端 `\echo` 指令 | [`001`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql)~[`009`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql), [`05_execution_contract.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/05_execution_contract.md) | 所有物理 DDL 脚本全面使用 `BEGIN ... COMMIT` 包裹，彻底删除 `\echo` 改造为纯 SQL，建立统一执行契约文档 | **已解决** | -| **REV-02** | **P0 基线** | 缺乏迁移前置环境基线校验，可能在未知或已被破坏的环境中误执行 | [`000_preflight.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_preflight.sql) | 新增前置纯只读检查脚本，强校验当前环境必须精确符合 Phase 0.5 状态（14表、行数、触发器等），任何不符立即抛出异常中止 | **已解决** | -| **REV-03** | **P0 备份** | 001 脚本使用 `DROP TABLE IF EXISTS bak_v1_*`，误执行可能覆盖最初 V1 备份 | [`001_backup_current_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | 增加强防重校验，若已存在任意 `bak_v1_*` 表立即抛异常阻断，严禁自动 DROP 覆盖既有历史备份 | **已解决** | -| **REV-04** | **P0 回滚** | CTAS 无法保留约束、默认值、触发器和 Identity，不能作为回滚结构来源 | [`rollback/000_phase05_exact_schema.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql), [`rollback/002`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/002_rollback_modified_tables.sql), [`rollback/003`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/003_restore_legacy_score.sql) | 新增标准 Phase 0.5 完整物理 DDL；重构回滚脚本，严格基于真实 DDL 重建结构，仅用 `bak_v1_*` 还原数据，解耦结构与数据 | **已解决** | -| **REV-05** | **P0 验收** | 010_verify 很多检查仅输出文本，最终未强行阻断，存在假阳性漏报隐患 | [`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) | 重构为真正的“失败即失败”，逐表、逐列、逐外键（删除规则）、逐唯一约束、逐索引进行 PL/pgSQL 强断言，出现任何不符立即抛异常终止 | **已解决** | -| **REV-06** | **字段规范** | `train_lesson.t_id` 原定义为可空，与排课必要性要求冲突 | [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | 将 `train_lesson.t_id` 设为 `VARCHAR(32) NOT NULL`，并在 010 中强断言 | **已解决** | -| **REV-07** | **字段规范** | `train_teacher` 新增的 `status` 与 `del_flag` 未在迁移后固化为 NOT NULL | [`008_migrate_teacher.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | 迁移历史教师数据并完成数据完整性校验后，显式执行 `ALTER COLUMN SET NOT NULL` | **已解决** | -| **REV-08** | **字段规范** | `train_student_score.score` 存在未经确认的 `DEFAULT 0`，掩盖未录入状态 | [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql) | 删除 `DEFAULT 0`，保留 `NOT NULL`，增加 `CHECK (score >= 0.00)`；未录成绩不建行，0 分代表真实得分 | **已解决** | -| **REV-09** | **字段规范** | 宿舍表 `dorm_floor` 默认值 `'1'` 和 `capacity` 默认值 `4` 属于 AI 猜测 | [`003_alter_master_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql), [`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql) | 移除所有业务默认值猜测，字段保持 NOT NULL 由管理员录入，增加 `CHECK (capacity > 0)` 约束 | **已解决** | -| **REV-10** | **字段规范** | `train_electronic_board.board_name` 包含 `DEFAULT ''` 空串伪造合法值 | [`003_alter_master_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | 彻底移除 `DEFAULT ''`，改为 `VARCHAR(100) NOT NULL`，由用户录入明确设备名 | **已解决** | -| **REV-11** | **业务语义** | 学员来源出现“统招学员”等高校概念，两处 `source_type` 含义含糊 | [`002`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`003`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql), [`007_dicts.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/007_dicts.sql) | 彻底剥离高校术语，区分：`student.source_type` 为主档来源（管理员/Excel/平台同步）；`enrollment.source_type` 为参训名单来源（指派/报名/推荐/调训） | **已解决** | -| **REV-12** | **业务语义** | 教学资源类型字典与 V2 冻结稿存在分类差异 | [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`007_dicts.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/007_dicts.sql) | 严格对齐 V2 冻结稿：1文档, 2视频, 3 3D模型, 4 VR资源, 5外部教学链接, 6其他 | **已解决** | -| **REV-13** | **约束安全** | 学习记录部分唯一索引当 `source_system = NULL` 且 `source_event_id != NULL` 时发生幂等逃逸 | [`004`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql), [`005`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql), [`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql) | 索引条件修正为双非空 `WHERE source_system IS NOT NULL AND source_event_id IS NOT NULL`；增加 CHECK 约束强制单号非空时系统名必填 | **已解决** | -| **REV-14** | **依赖解耦** | 脚本滥用 `DROP TABLE ... CASCADE` 掩盖未预期依赖 | [`004`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql), [`009`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql), [`rollback`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/rollback/) | 迁移与回滚脚本全面显式解除已知约束，改用常规 `DROP TABLE`，禁止使用 CASCADE 掩盖隐式依赖 | **已解决** | -| **REV-15** | **数据一致** | 排课场地类型与教室/实训场地未在数据库层实现单行互斥；学时时间未核验先后 | [`002`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`004`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql), [`005_constraints.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/005_constraints.sql) | `train_lesson` 增加 `chk_lesson_venue` 互斥 CHECK；`train_study_duration` 增加 `end_time >= start_time` CHECK 约束 | **已解决** | -| **REV-16** | **风险扩展** | 风险报告需要补充跨班级关联、班牌一致性、宿舍重叠计算等高级业务风险 | [`04_risk_review.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/04_risk_review.md) | 在文档中新增 **R-11 至 R-15** 五项重大业务与并发一致性风险深度剖析 | **已解决** | -| **REV-17** | **执行控制** | 结构迁移阶段执行 007_dicts 会污染空库测试基线 | [`02_migration_plan.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/02_migration_plan.md), [`05_execution_contract.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/05_execution_contract.md) | 正式明确 007 在本阶段暂不执行，等后续 API/权限设计阶段统一执行 | **已解决** | +| **REV-01** | **P0 架构** | 破坏性迁移脚本无事务边界，遇错可能部分提交；包含客户端 `\echo` 指令 | [`001`](../../RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql)~[`009`](../../RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql), [`05_execution_contract.md`](05_execution_contract.md) | 所有物理 DDL 脚本全面使用 `BEGIN ... COMMIT` 包裹，彻底删除 `\echo` 改造为纯 SQL，建立统一执行契约文档 | **已解决** | +| **REV-02** | **P0 基线** | 缺乏迁移前置环境基线校验，可能在未知或已被破坏的环境中误执行 | [`000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql) | 新增前置纯只读检查脚本，强校验当前环境必须精确符合 Phase 0.5 状态（14表、行数、触发器等），任何不符立即抛出异常中止 | **已解决** | +| **REV-03** | **P0 备份** | 001 脚本使用 `DROP TABLE IF EXISTS bak_v1_*`，误执行可能覆盖最初 V1 备份 | [`001_backup_current_schema.sql`](../../RuoYi-Vue/sql/train/v2/001_backup_current_schema.sql) | 增加强防重校验，若已存在任意 `bak_v1_*` 表立即抛异常阻断，严禁自动 DROP 覆盖既有历史备份 | **已解决** | +| **REV-04** | **P0 回滚** | CTAS 无法保留约束、默认值、触发器和 Identity，不能作为回滚结构来源 | [`rollback/000_phase05_exact_schema.sql`](../../RuoYi-Vue/sql/train/v2/rollback/000_phase05_exact_schema.sql), [`rollback/002`](../../RuoYi-Vue/sql/train/v2/rollback/002_rollback_modified_tables.sql), [`rollback/003`](../../RuoYi-Vue/sql/train/v2/rollback/003_restore_legacy_score.sql) | 新增标准 Phase 0.5 完整物理 DDL；重构回滚脚本，严格基于真实 DDL 重建结构，仅用 `bak_v1_*` 还原数据，解耦结构与数据 | **已解决** | +| **REV-05** | **P0 验收** | 010_verify 很多检查仅输出文本，最终未强行阻断，存在假阳性漏报隐患 | [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) | 重构为真正的“失败即失败”，逐表、逐列、逐外键（删除规则）、逐唯一约束、逐索引进行 PL/pgSQL 强断言，出现任何不符立即抛异常终止 | **已解决** | +| **REV-06** | **字段规范** | `train_lesson.t_id` 原定义为可空，与排课必要性要求冲突 | [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) | 将 `train_lesson.t_id` 设为 `VARCHAR(32) NOT NULL`，并在 010 中强断言 | **已解决** | +| **REV-07** | **字段规范** | `train_teacher` 新增的 `status` 与 `del_flag` 未在迁移后固化为 NOT NULL | [`008_migrate_teacher.sql`](../../RuoYi-Vue/sql/train/v2/008_migrate_teacher.sql) | 迁移历史教师数据并完成数据完整性校验后，显式执行 `ALTER COLUMN SET NOT NULL` | **已解决** | +| **REV-08** | **字段规范** | `train_student_score.score` 存在未经确认的 `DEFAULT 0`，掩盖未录入状态 | [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) | 删除 `DEFAULT 0`，保留 `NOT NULL`，增加 `CHECK (score >= 0.00)`；未录成绩不建行，0 分代表真实得分 | **已解决** | +| **REV-09** | **字段规范** | 宿舍表 `dorm_floor` 默认值 `'1'` 和 `capacity` 默认值 `4` 属于 AI 猜测 | [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql), [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) | 移除所有业务默认值猜测，字段保持 NOT NULL 由管理员录入，增加 `CHECK (capacity > 0)` 约束 | **已解决** | +| **REV-10** | **字段规范** | `train_electronic_board.board_name` 包含 `DEFAULT ''` 空串伪造合法值 | [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) | 彻底移除 `DEFAULT ''`，改为 `VARCHAR(100) NOT NULL`，由用户录入明确设备名 | **已解决** | +| **REV-11** | **业务语义** | 学员来源出现“统招学员”等高校概念，两处 `source_type` 含义含糊 | [`002`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`003`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql), [`007_dicts.sql`](../../RuoYi-Vue/sql/train/v2/007_dicts.sql) | 彻底剥离高校术语，区分：`student.source_type` 为主档来源（管理员/Excel/平台同步）；`enrollment.source_type` 为参训名单来源（指派/报名/推荐/调训） | **已解决** | +| **REV-12** | **业务语义** | 教学资源类型字典与 V2 冻结稿存在分类差异 | [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`007_dicts.sql`](../../RuoYi-Vue/sql/train/v2/007_dicts.sql) | 严格对齐 V2 冻结稿：1文档, 2视频, 3 3D模型, 4 VR资源, 5外部教学链接, 6其他 | **已解决** | +| **REV-13** | **约束安全** | 学习记录部分唯一索引当 `source_system = NULL` 且 `source_event_id != NULL` 时发生幂等逃逸 | [`004`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql), [`005`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql), [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) | 索引条件修正为双非空 `WHERE source_system IS NOT NULL AND source_event_id IS NOT NULL`；增加 CHECK 约束强制单号非空时系统名必填 | **已解决** | +| **REV-14** | **依赖解耦** | 脚本滥用 `DROP TABLE ... CASCADE` 掩盖未预期依赖 | [`004`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql), [`009`](../../RuoYi-Vue/sql/train/v2/009_drop_legacy_score.sql), [`rollback`](../../RuoYi-Vue/sql/train/v2/rollback/) | 迁移与回滚脚本全面显式解除已知约束，改用常规 `DROP TABLE`，禁止使用 CASCADE 掩盖隐式依赖 | **已解决** | +| **REV-15** | **数据一致** | 排课场地类型与教室/实训场地未在数据库层实现单行互斥；学时时间未核验先后 | [`002`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql), [`004`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql), [`005_constraints.sql`](../../RuoYi-Vue/sql/train/v2/005_constraints.sql) | `train_lesson` 增加 `chk_lesson_venue` 互斥 CHECK；`train_study_duration` 增加 `end_time >= start_time` CHECK 约束 | **已解决** | +| **REV-16** | **风险扩展** | 风险报告需要补充跨班级关联、班牌一致性、宿舍重叠计算等高级业务风险 | [`04_risk_review.md`](04_risk_review.md) | 在文档中新增 **R-11 至 R-15** 五项重大业务与并发一致性风险深度剖析 | **已解决** | +| **REV-17** | **执行控制** | 结构迁移阶段执行 007_dicts 会污染空库测试基线 | [`02_migration_plan.md`](02_migration_plan.md), [`05_execution_contract.md`](05_execution_contract.md) | 正式明确 007 在本阶段暂不执行，等后续 API/权限设计阶段统一执行 | **已解决** | diff --git a/docs/database-v2/07_review_round2_changes.md b/docs/database-v2/07_review_round2_changes.md index 888a424a3..d8884441c 100644 --- a/docs/database-v2/07_review_round2_changes.md +++ b/docs/database-v2/07_review_round2_changes.md @@ -1,7 +1,7 @@ # RailwaySystem 数据库 V2 DDL Review Round 2 变更记录 (最终静态收尾) -> **修订阶段**：数据库 V2 DDL Review Round 2（最终静态收尾） -> **最高依据**：`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md` +> **修订阶段**：数据库 V2 DDL Review Round 2（最终静态收尾） +> **最高依据**：`RailwaySystem 数据库 V2 字段设计与 Kingbase DDL 规范 V1.0.md` > **修订目标**：解决高级技术负责人 Final Static Review 提出的 7 个核心静态问题（R2-01 ~ R2-07），使数据库 V2 DDL 达到“允许进入测试迁移”状态。 --- @@ -15,8 +15,8 @@ accommodation_status SMALLINT NOT NULL DEFAULT 1 ``` - **修改文件**： - - [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L142) - - [`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) + - [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L142) + - [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) - **修改后实现**： ```sql accommodation_status SMALLINT NOT NULL DEFAULT 0 @@ -37,9 +37,9 @@ - `train_student_checkin.checkin_way`: `DEFAULT 1` - `train_class_report.verify_result`: `DEFAULT 1` - **修改文件**： - - [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) - - [`004_rebuild_business_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) - - [`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) + - [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) + - [`004_rebuild_business_tables.sql`](../../RuoYi-Vue/sql/train/v2/004_rebuild_business_tables.sql) + - [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) - **修改后实现**： 上述 6 个字段全部移除 `DEFAULT` 声明，仅保留 `SMALLINT NOT NULL`。`010_verify.sql` 中增加只读断言：上述字段的 `column_default` 必须全部为 `NULL`，若存在默认值当场抛异常。 - **验证方式**：静态 grep 全局检索与 `010_verify.sql` 断言校验。 @@ -54,9 +54,9 @@ COMMENT ON COLUMN train_enrollment.source_type IS '进入本期培训名单的来源 (1:组织指派, 2:自主报名, 3:单位推荐, 4:统一调训)'; ``` - **修改文件**： - - [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L94) - - [`04_risk_review.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/04_risk_review.md) - - [`01_table_inventory.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/01_table_inventory.md) + - [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql#L94) + - [`04_risk_review.md`](04_risk_review.md) + - [`01_table_inventory.md`](01_table_inventory.md) - **修改后实现**： - 注释修改为： ```sql @@ -74,7 +74,7 @@ - **问题**：原 `000_preflight.sql` 仅做了表存在性、行数和少量代表性约束判断，未能覆盖完整的 Phase 0.5 物理结构骨架，若存在“少一个正确FK + 多一个错误FK”的对冲情况可能假阳性通过。 - **原实现**：部分抽检 + 触发器循环判断。 - **修改文件**： - - [`000_preflight.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_preflight.sql) + - [`000_preflight.sql`](../../RuoYi-Vue/sql/train/v2/000_preflight.sql) - **修改后实现**： 采用 CTE `VALUES(...)` 构造预期基线集合，与系统目录做全集合差集比对： - 14 个旧表 PK (table_name + constraint_name + column_name) @@ -94,7 +94,7 @@ - **问题**：原 010 验收脚本主要核验对象名称存在性，对约束内部的具体列排序、外键删除规则、CHECK 表达式逻辑等未做定义级校验。 - **原实现**：检查约束名称与 `count(*) = 26` 等数量判断。 - **修改文件**： - - [`010_verify.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/010_verify.sql) + - [`010_verify.sql`](../../RuoYi-Vue/sql/train/v2/010_verify.sql) - **修改后实现**： - **UNIQUE 验收**：必须断言 `table_name` + `constraint_name` + `column_list`（如 `train_enrollment(plan_id, student_id)`）； - **FK 验收**：必须断言源表、源列、目标表、目标列及 `delete_rule = 'NO ACTION'`，严禁 CASCADE； @@ -114,9 +114,9 @@ - `ADD COLUMN IF NOT EXISTS ...` (003) - `CREATE INDEX IF NOT EXISTS ...` (006) - **修改文件**： - - [`002_create_new_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) - - [`003_alter_master_tables.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) - - [`006_indexes.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/006_indexes.sql) + - [`002_create_new_tables.sql`](../../RuoYi-Vue/sql/train/v2/002_create_new_tables.sql) + - [`003_alter_master_tables.sql`](../../RuoYi-Vue/sql/train/v2/003_alter_master_tables.sql) + - [`006_indexes.sql`](../../RuoYi-Vue/sql/train/v2/006_indexes.sql) - **修改后实现**： - 002 中 8 张新增表全部改为严格 `CREATE TABLE`； - 003 中新增字段全部改为严格 `ADD COLUMN`； @@ -131,8 +131,8 @@ - **问题**：迁移执行契约依赖事务的原子性（`BEGIN ... COMMIT / ROLLBACK`）。当前环境为 KingbaseES V009R003C018 (`database_mode=mysql`)，需在正式执行 V2 前实证验证当前数据库实例对 DDL 的事务回滚支持能力。 - **原实现**：未设立 DDL 事务能力前置探针。 - **修改文件**： - - 新增：[`RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql`](file:///Users/wzb/Desktop/项目/RailwaySystem/RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) - - [`05_execution_contract.md`](file:///Users/wzb/Desktop/项目/RailwaySystem/docs/database-v2/05_execution_contract.md) + - 新增：[`RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql`](../../RuoYi-Vue/sql/train/v2/000_tx_capability_probe.sql) + - [`05_execution_contract.md`](05_execution_contract.md) - **修改后实现**： - 创建独立的安全探针脚本（作为 Gate A）： - **Phase A**：`BEGIN -> CREATE TABLE public.__railway_v2_tx_probe -> ALTER TABLE -> ROLLBACK`； diff --git a/docs/handbook/01-project-overview.md b/docs/handbook/01-project-overview.md index a01c581ef..1616b04f3 100644 --- a/docs/handbook/01-project-overview.md +++ b/docs/handbook/01-project-overview.md @@ -100,7 +100,7 @@ graph TD ## 6. 技术参考链接 (Technical References) -* 业务需求最高基线：[业务需求中心与 PRD V1.0](../../doc/README.md) +* 业务需求最高基线：[一期 PRD V1.0](../requirements/一期PRD-V1.0.md) 与 [业务需求中心](../requirements/README.md) * 系统业务全流程与状态机：[02-business-process.md](02-business-process.md) * 系统技术架构设计：[03-system-architecture.md](03-system-architecture.md) * 核心 API 契约总览：[docs/api-v2/00_readme.md](../api-v2/00_readme.md) diff --git a/docs/handbook/05-module-guide.md b/docs/handbook/05-module-guide.md index 7b2a490fe..aa08b4705 100644 --- a/docs/handbook/05-module-guide.md +++ b/docs/handbook/05-module-guide.md @@ -153,7 +153,7 @@ ## 5. 技术参考链接 (Technical References) -* 业务需求最高基线：[业务需求中心与 PRD V1.0](../../doc/README.md) +* 业务需求最高基线：[一期 PRD V1.0](../requirements/一期PRD-V1.0.md) 与 [业务需求中心](../requirements/README.md) * 核心业务主链规范：[02-business-process.md](02-business-process.md) * API 端点清单：[06-api-and-permission-overview.md](06-api-and-permission-overview.md) * 自动化测试验证矩阵：[07-testing-and-acceptance.md](07-testing-and-acceptance.md) diff --git a/docs/issues-v1/00_readme.md b/docs/issues-v1/00_readme.md index beb5a3291..03892438d 100644 --- a/docs/issues-v1/00_readme.md +++ b/docs/issues-v1/00_readme.md @@ -1,7 +1,7 @@ # RailwaySystem Phase 3：P0 Epic / Issue 任务拆分总纲 > **阶段状态：** Phase 3 任务分解完成稿 (正式基线) -> **业务最高基线：** `doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md` +> **业务最高基线：** [一期 PRD V1.0](../requirements/一期PRD-V1.0.md) > **数据库基线：** `db-v2-migration-passed-20260914` (21张表 KingbaseES 物理迁移验证通过) > **代码生成器基线：** `generator-v2-ready-20260914` (Kingbase 只读验证通过) > **API 契约基线：** `api-v2-contract-v1.0.1` (89 个物理 API 端点，P0: 53, P1: 34, P2: 2) @@ -20,7 +20,7 @@ 1. **业务能力驱动，拒绝单表 CRUD：** 严禁以数据库物理表为单位拆分 Issue（如禁止设立“开发 train_lesson CRUD”），必须按“可独立交付与验收的业务动作/能力”进行拆分（如“实现课次排课与三类资源冲突检测”）； 2. **只拆 P0，严格范围控制：** - 锁定 53 个 P0 API 作为本轮研发唯一核心目标； - - 34 个 P1 辅助 API 与 2 个 P2 远期 API 仅在 [`07_p1_p2_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/07_p1_p2_backlog.md) 中登记备查，不计入开发排期。 + - 34 个 P1 辅助 API 与 2 个 P2 远期 API 仅在 [`07_p1_p2_backlog.md`](07_p1_p2_backlog.md) 中登记备查，不计入开发排期。 3. **主数据最小必要集合原则：** - 基础主数据不作为全量阻塞项，仅建设支撑主业务链路所必需的最小集合（Teacher, Student, Course, Classroom, TrainingSite, Dormitory）。 4. **不变量与并发控制强行绑定：** @@ -109,13 +109,13 @@ flowchart TD | 序号 | 文档名称 | 核心内容 | |:---|:---|:---| -| 00 | [`00_readme.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/00_readme.md) | 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引 | -| 01 | [`01_epic_overview.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/01_epic_overview.md) | 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单 | -| 02 | [`02_p0_issue_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/02_p0_issue_backlog.md) | 26 个 P0 Issue 详细技术卡片（严格包含 22 项技术定义与 Given/When/Then 验收准则） | -| 03 | [`03_dependency_graph.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/03_dependency_graph.md) | Mermaid DAG 依赖图，清晰展示串行依赖与并行泳道 | -| 04 | [`04_wave_plan.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/04_wave_plan.md) | Wave 0 ~ Wave 7 开发推进批次计划、进入条件、产出目标与退出准则 | -| 05 | [`05_agent_assignment.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/05_agent_assignment.md) | Gemini Flash 与 Codex 研发分工建议及 Generator (YES/PARTIAL/NO) 执行策略 | -| 06 | [`06_acceptance_matrix.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/06_acceptance_matrix.md) | 全链路追踪矩阵 (UC → API → Issue → Test) 及 5 大 Invariant / 1 项生命周期策略归属矩阵 | -| 07 | [`07_p1_p2_backlog.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/07_p1_p2_backlog.md) | 34 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划 | -| 08 | [`08_risk_register.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/08_risk_register.md) | 技术风险登记册、稳定资源锁策略、外部 Mock 隔离与 CG-01 裁决辅助表 | -| 09 | [`09_issue_review_round1.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/09_issue_review_round1.md) | Phase 3 Issue Review Round 1 审查整改记录与结论报告 | +| 00 | [`00_readme.md`](00_readme.md) | 阶段总纲、最高原则、主链路、统计总览、Contract Gap 分析与文档索引 | +| 01 | [`01_epic_overview.md`](01_epic_overview.md) | 12 个业务 Epic 概览、目标、业务边界与包含的 Issue 对应清单 | +| 02 | [`02_p0_issue_backlog.md`](02_p0_issue_backlog.md) | 26 个 P0 Issue 详细技术卡片（严格包含 22 项技术定义与 Given/When/Then 验收准则） | +| 03 | [`03_dependency_graph.md`](03_dependency_graph.md) | Mermaid DAG 依赖图，清晰展示串行依赖与并行泳道 | +| 04 | [`04_wave_plan.md`](04_wave_plan.md) | Wave 0 ~ Wave 7 开发推进批次计划、进入条件、产出目标与退出准则 | +| 05 | [`05_agent_assignment.md`](05_agent_assignment.md) | Gemini Flash 与 Codex 研发分工建议及 Generator (YES/PARTIAL/NO) 执行策略 | +| 06 | [`06_acceptance_matrix.md`](06_acceptance_matrix.md) | 全链路追踪矩阵 (UC → API → Issue → Test) 及 5 大 Invariant / 1 项生命周期策略归属矩阵 | +| 07 | [`07_p1_p2_backlog.md`](07_p1_p2_backlog.md) | 34 个 P1 辅助 API 与 2 个 P2 远期 API 的统一登记与后续演进规划 | +| 08 | [`08_risk_register.md`](08_risk_register.md) | 技术风险登记册、稳定资源锁策略、外部 Mock 隔离与 CG-01 裁决辅助表 | +| 09 | [`09_issue_review_round1.md`](09_issue_review_round1.md) | Phase 3 Issue Review Round 1 审查整改记录与结论报告 | diff --git a/docs/issues-v1/08_risk_register.md b/docs/issues-v1/08_risk_register.md index 0961c82cd..adb16f62e 100644 --- a/docs/issues-v1/08_risk_register.md +++ b/docs/issues-v1/08_risk_register.md @@ -91,7 +91,7 @@ - **技术隐患：** 数据库物理外键仅约束了 ID 的存在性，无法感知“班级”拓扑。一旦串线，将导致整个统计报表与学员档案全面污染。 - **强制工程对策：** 1. 全面落实 5 大跨表硬业务不变量（INV-01 ~ INV-05）； - 2. 每一条不变量由唯一的 Application Service 负责强制校验（详见 [`06_acceptance_matrix.md`](file:///Users/wzb/Desktop/%E9%A1%B9%E7%9B%AE/RailwaySystem/docs/issues-v1/06_acceptance_matrix.md)）； + 2. 每一条不变量由唯一的 Application Service 负责强制校验（详见 [`06_acceptance_matrix.md`](06_acceptance_matrix.md)）； 3. 任何违背不变量的操作直接抛出全局业务异常（如 `ATTENDANCE_PLAN_MISMATCH (40080)`），从根源杜绝脏数据。 --- diff --git a/docs/requirements/README.md b/docs/requirements/README.md new file mode 100644 index 000000000..ce8749fba --- /dev/null +++ b/docs/requirements/README.md @@ -0,0 +1,24 @@ +# SYFJGYD学员管理系统 — 需求与业务基线中心 (Requirements) + +> **最高原则**：严格区分“业务需求定义”、“代码实现现状”与“外部待确认事项”，三者职责明确、各司其职，不得相互混淆或替代。 + +--- + +## 🧭 需求文档矩阵与职责边界 + +本目录统领系统一期全部正式业务需求、逐项落地实现进度以及面向甲方的待对齐清单： + +| 权威文档 | 文档性质 | 职责与定位说明 | 适用场景 | +| :--- | :--- | :--- | :--- | +| [**一期PRD-V1.0.md**](一期PRD-V1.0.md) | **需求定义（业务基线）** | **一期唯一正式冻结的业务需求基线**。
定义系统应该做什么、业务领域模型（教师、学员、开班、课程、排课、考勤、成绩、宿舍、门禁等）、业务规则约束与一期开发边界。
不随日常开发进度而变动。 | 业务领域模型学习、规则裁决、验收准则对照 | +| [**一期需求实现进度表.md**](一期需求实现进度表.md) | **当前实现状态（代码事实）** | **客观反映一期各项规划功能在代码与数据库层面的实际落地度**。
逐项梳理域 A~G 几十个细分功能点的前后端代码文件、数据库表名、331项自动化测试与浏览器验证状态（区分 `DONE_VERIFIED`、`IN_PROGRESS`、`PARTIAL_FUNCTION` 与 `EXTERNAL_BLOCKER`）。 | 开发跟踪、代码走查、功能完成度盘点 | +| [**甲方需求确认清单.md**](甲方需求确认清单.md) | **待业务确认项（沟通清单）** | **提炼需要与沈阳房建公寓段业务主管/指导老师现场开会对齐的关键事项**。
系统归纳 P0（核心业务阻塞 18 项）、P1（业务形态优化 12 项）与 P2（长远规划 8 项）问题清单与推荐建议。 | 甲方会议、业务调研、客户沟通与策略确认 | + +--- + +## 📌 使用指引 + +1. **若需要了解业务逻辑与功能规则**：请通读 [一期PRD-V1.0.md](一期PRD-V1.0.md)； +2. **若需要核对系统某项功能到底做没做、在哪个文件**：请查阅 [一期需求实现进度表.md](一期需求实现进度表.md)； +3. **若需要与段方领导/老师沟通确认业务细节**：请调阅 [甲方需求确认清单.md](甲方需求确认清单.md)； +4. **若需要了解系统当前整体运行状态与共享试用说明**：请前往上层速览中心 [docs/current/](../current/README.md)。 diff --git a/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md b/docs/requirements/一期PRD-V1.0.md similarity index 98% rename from doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md rename to docs/requirements/一期PRD-V1.0.md index 80b677457..8b6659d44 100644 --- a/doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md +++ b/docs/requirements/一期PRD-V1.0.md @@ -1,10 +1,13 @@ # RailwaySystem 智慧培训系统一期 PRD V1.0 -> **版本：** V1.0 -> **文档状态：** 一期内部开发基线 -> **修订依据：** 第二次项目会议结论 -> **适用阶段：** 业务模型冻结 → 数据库 V2 → API 设计 → Issue 拆分 → 开发 -> **后续版本：** 现场验证后根据甲方反馈升级 V1.1 +> **版本：** V1.0 +> **文档状态：** 一期内部开发基线 +> **修订依据：** 第二次项目会议结论 +> **适用阶段：** 业务模型冻结 → 数据库 V2 → API 设计 → Issue 拆分 → 开发 +> **后续版本：** 现场验证后根据甲方反馈升级 V1.1
+> - **当前定位**：一期正式业务需求冻结基线
+> - **当前实现状态请参见**：[一期需求实现进度表.md](一期需求实现进度表.md)
+> - **甲方待确认事项请参见**：[甲方需求确认清单.md](甲方需求确认清单.md) > > 本版本遵循一个核心原则： > diff --git a/docs/requirements/一期需求实现进度表.md b/docs/requirements/一期需求实现进度表.md index 67567f81e..f8e1c3fb9 100644 --- a/docs/requirements/一期需求实现进度表.md +++ b/docs/requirements/一期需求实现进度表.md @@ -25,7 +25,7 @@ 为确保所有结论具备事实可查性，本次梳理严格遵循以下证据优先级与版本边界界定： * **当前正式生产 Release 边界**：当前正式生产 Release（Commit SHA: `08419b635bafb872ab8e150b086fa2a894272e1b`，基于生产发布分支 `feat/cicd-pipeline`）**尚未包含 R.3 DMS 业务代码**。因此，凡涉及 DMS 业务编排、门禁适配器、Token 管理与 Mock 验证的内容，一律明确标注为 `FEATURE_BRANCH_VERIFIED`（独立研发分支已验证）以及 `NOT_YET_RELEASED_TO_PRODUCTION`（尚未并入当前生产发布分支），严禁误报为“当前生产系统已上线”。 -* **Tier 1（开发基线）**：`doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md`，一期内部开发正式基线。 +* **Tier 1（开发基线）**：[一期PRD-V1.0.md](一期PRD-V1.0.md)，一期内部开发正式基线。 * **Tier 2（会议依据）**：第二次项目会议结论、第三次内部会议记录。用于解释业务背景、修正理解偏差。**明确铁律：会议中的探讨与设想 ≠ 自动冻结为一期正式需求**。 * **Tier 3（客观事实）**：当前正式代码库、KingbaseES 物理表结构、当前正式生产 Release、端到端 E2E 证据包（`RBAC_E2E_R2_20260916_102500`、`DEMO_E2E_20260915_122800`）、DMS R.3 设计与 QA 验证资产。用于判定功能是否真实代码实现与测试通过。严禁仅凭 API Contract 设计文档作为“代码已实现”的依据。 * **Tier 4（参考资产）**：早期历史说明书、旧版 HTML 原型与旧数据库设计，仅供溯源参考。 @@ -216,8 +216,8 @@ 本文档严格基于以下工程资产与历史资料进行梳理与事实断言，全篇不包含任何真实明文密码、密钥或敏感配置： -1. **PRD 开发基线**：`doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md`（一期内部开发正式基线）； -2. **历史需求与原始材料**：`doc/raw_materials/学员管理系统相关需求.md`、`doc/raw_materials/学员管理系统功能分析_20260831.md`； +1. **PRD 开发基线**：[一期PRD-V1.0.md](一期PRD-V1.0.md)（一期内部开发正式基线）； +2. **历史需求与原始材料**：`docs/archive/raw-materials/学员管理系统相关需求.md`、`docs/archive/raw-materials/学员管理系统功能分析_20260831.md`； 3. **会议纪要与决策**：第二次项目会议结论（业务最小闭环原则、一班多课、排除二期智慧基地控制）、第三次内部会议记录（DMS 预研事实、SSO 探讨、组织架构讨论、Demo 数据需求）； 4. **生产 Release 与发版说明**：`docs/reports/release-notes.md`（v1.0.0-final-candidate 发版说明，对应正式生产 Release `08419b63`）、`docs/_meta/final-release-readiness.md`； 5. **R.2 RBAC 真实三角色验收证据包**：`docs/reports/e2e-r2/RBAC_E2E_R2_20260916_102500/`（含 `report.md`、`role-matrix.md`、`account-binding-results.md`、`idor-results.md` 等）； diff --git a/docs/requirements/甲方需求确认清单.md b/docs/requirements/甲方需求确认清单.md index 557da1c43..116282e35 100644 --- a/docs/requirements/甲方需求确认清单.md +++ b/docs/requirements/甲方需求确认清单.md @@ -117,7 +117,7 @@ 本文档严格基于以下工程事实与资料编制，绝无凭空编造： -1. **PRD 需求基准**：`doc/RailwaySystem 智慧培训系统一期 PRD V1.0.md`（特别是第 28 节“当前仍需现场验证的问题” V-01 ~ V-14）； +1. **PRD 需求基准**：[一期PRD-V1.0.md](一期PRD-V1.0.md)（特别是第 28 节“当前仍需现场验证的问题” V-01 ~ V-14）； 2. **历次项目会议结论**：第二次项目会议结论（最小闭环原则、排除智慧基地中控）、第三次内部会议记录（DMS 测试事实、SSO 讨论、组织架构来源、演示数据任务）； 3. **已落地的测试验收证据**： * 三角色权限验收报告：`docs/reports/e2e-r2/RBAC_E2E_R2_20260916_102500/report.md`