216 lines
30 KiB
Markdown
216 lines
30 KiB
Markdown
# RailwaySystem 文档信息架构审计草案 (Document Audit Draft) - Phase A.1 CORRECTION
|
||
> **状态：** DRAFT / RUNTIME_PENDING (Phase A.1 修正输出，禁止 git add)
|
||
> **审计基线分支：** `integration/wave2-20260914`
|
||
> **基线 Commit (命令实测值)：** `196c6c47c70330119693f2ab7a6c35b8a22d5300` (短哈希 `196c6c47`)
|
||
> **工作区 HEAD：** `87322511c78e9109c7fe5af000d3db74b5c6cdfc`
|
||
> **审计人：** Documentation Architect
|
||
> **核心原则：**
|
||
> 1. **严禁主观推断**：Documentation Architect 是信息架构师，不是代码事实裁判。凡未经 Integration 源码直接确认的枚举、字段、状态、不变量与端口，一律不得写成确定事实。
|
||
> 2. **事实置信度分离**：全量文档按 `Fact Confidence` 严格区分事实来源与可靠程度。
|
||
> 3. **环境依赖标记**：凡依赖真实服务运行、网络通信与界面渲染的内容，一律标记为 `RUNTIME_PENDING`。
|
||
|
||
---
|
||
|
||
## 一、审计概览与统计指标
|
||
|
||
本轮对 `docs/` 目录下全部 **68** 份技术文档、设计草案、评审纪要及开发验收报告进行了逐一深入审计（涵盖 67 份基线跟踪文档与 1 份未跟踪本地会话记录）。
|
||
|
||
### 1. 动作推荐汇总统计 (已彻底复审原 KEEP 分类)
|
||
| 推荐动作 (Recommended Action) | 文件数量 | 占比 | 核心定义与处理说明 |
|
||
|:---|:---:|:---:|:---|
|
||
| **KEEP** | **0** | **0.0%** | **经严格核验，原 8 篇 KEEP 文档均包含旧状态、旧 API、旧不变量或未落地设计，无法满足“100% 符合当前代码事实”的标准，已全数重分类，无原样保留项。** |
|
||
| **UPDATE_FROM_CODE** | 4 | 5.9% | 核心技术规范骨架有效，但存在旧接口示例、旧分层或旧不变量（如 Scheduling 需补充 Soft Warning 语义），需根据代码事实就地重构更新。 |
|
||
| **UPDATE_AFTER_RUNTIME** | 5 | 7.3% | 强依赖真实运行环境。包括环境实操手册、全局入口、权限与错误码终态核查、端到端验收矩阵与风险登记册，待 Final Runtime Gate 终态冻结后更新。 |
|
||
| **MERGE** | 21 | 30.9% | 文档所含工程事实与业务规则具有长期参考价值，但分散在零散文件或跨域混杂，提炼其高价值事实并入各 Module 文档或系统 Handbook。 |
|
||
| **ARCHIVE** | 35 | 51.5% | 历史阶段性过程产物。包括 Phase 0 遗留代码快照、中间审查报告、数据库迁移阶段流水、会话 log 等，统一移入 `docs/archive/` 永久备查。 |
|
||
| **REVIEW_REQUIRED** | 3 | 4.4% | 涉及硬件外设防腐适配器、成绩/学时遗留代码或打卡考勤范围，与当前代码存在较大落差，需交由 Codex 与架构师核验决策。 |
|
||
| **GENERATED** | 0 | 0.0% | 现有存量文档均为手工维护 Markdown，规划未来由 CI/CD 自动生成的文档标记为该类型。 |
|
||
| **合计** | **68** | **100.0%** | — |
|
||
|
||
### 2. 事实置信度分布统计 (Fact Confidence)
|
||
- `CODE_VERIFIED`：**0**（作为 Phase A.1 文档审计，未经 Codex 专项任务书逐行核验前，存量文档不擅自赋予代码完全验证标签）
|
||
- `DOC_ONLY`：**11**（设计期提出的契约与规范，需结合代码求证）
|
||
- `RUNTIME_PENDING`：**5**（强依赖运行时环境与实测数据）
|
||
- `HISTORICAL`：**47**（历史过程记录、审查报告、迁移验证流水、前期快照）
|
||
- `VERIFY_WITH_CODE`：**5**（在当前代码中有对应实现，但细节状态与枚举必须经 Codex 深度核验）
|
||
|
||
---
|
||
|
||
## 二、全量 68 份文档逐项审计明细表
|
||
|
||
> **分类映射定义（12大类）：**
|
||
> 1. `Product / Business` | 2. `Architecture` | 3. `API / Contract` | 4. `Database` | 5. `Frontend` | 6. `Security / Permission`
|
||
> 7. `Runtime / Deployment` | 8. `Testing / Release` | 9. `Module Documentation` | 10. `Historical Development Record`
|
||
> 11. `Database Migration Asset` | 12. `Generated Human Documentation`
|
||
>
|
||
> **Fact Confidence 取值定义：**
|
||
> `CODE_VERIFIED` \| `DOC_ONLY` \| `RUNTIME_PENDING` \| `HISTORICAL` \| `VERIFY_WITH_CODE`
|
||
|
||
| 序号 | 路径 (Path) | 标题 (Title) | 分类 (Category) | 时态 (Temporal) | 事实置信度 (Fact Confidence) | 重复/重叠文档 | 建议动作 (Action) | 处置理由与重构建议 (Reason) |
|
||
|:---:|:---|:---|:---|:---:|:---:|:---|:---:|:---|
|
||
| 1 | `docs/README.md` | RailwaySystem 技术架构与代码审计中心（docs） | 2. Architecture | history | `RUNTIME_PENDING` | 无 | **UPDATE_AFTER_RUNTIME** | 仅记录 Phase 0 审计目录，严重滞后。需待 Runtime 终态与信息架构重组完成后重写为全局总入口。 |
|
||
| 2 | `docs/conversation_record.md` | RailwaySystem 会话全流程记录归档 | 10. Historical Development Record | history | `HISTORICAL` | `generator-v2/01`, `development/issue-01-03` | **ARCHIVE** | 记录特定调试会话的流水账，属过程追溯材料，归入 `archive/conversations/`。 |
|
||
| 3 | `docs/api-v2/00_readme.md` | Phase 2：API Contract / DTO-VO / Service Boundary Design | 3. API / Contract | current | `DOC_ONLY` | `01`~`10` 章节总述 | **MERGE** | 作为 API 契约总纲，核心规范与目录架构提炼合并入 `handbook/api/api-overview.md`。 |
|
||
| 4 | `docs/api-v2/01_api_design_principles.md` | RailwaySystem API 设计原则与规范 | 3. API / Contract | current | `VERIFY_WITH_CODE` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。核查发现文中包含未实现的 Command API 示例，需从代码核验后修正示例。 |
|
||
| 5 | `docs/api-v2/02_module_a_base_resource_api.md` | Module A：人员与基础资源 API 契约 | 3. API / Contract | current | `VERIFY_WITH_CODE` | 各基础模块开发验收文档 | **MERGE** | 揉杂 5 个基础业务域，违反高内聚。应提炼并分别合并入各独立 `docs/modules/*.md`。 |
|
||
| 6 | `docs/api-v2/03_module_b_plan_enrollment_schedule_api.md` | Module B：开班计划与排课 API 契约 | 3. API / Contract | current | `VERIFY_WITH_CODE` | `development/issue-02-01`, `issue-02-02` | **MERGE** | 核心主链路契约。应按业务域拆解合并入 Plan, PlanCourse, Enrollment, Scheduling, Board 模块。 |
|
||
| 7 | `docs/api-v2/04_module_c_accommodation_attendance_api.md` | Module C：住宿 / 门禁 / 考勤 API 契约 | 3. API / Contract | review | `DOC_ONLY` | 遗留打卡 Controller | **REVIEW_REQUIRED** | 混杂门禁授权与外设打卡，需 Codex 核验当前代码实际落地端点与 mock 机制。 |
|
||
| 8 | `docs/api-v2/05_module_d_score_learning_statistics_api.md` | Module D：成绩 / 学习 / 统计 / 画像 API 契约 | 3. API / Contract | review | `DOC_ONLY` | 遗留 Controller 代码 | **REVIEW_REQUIRED** | 所列端点多为遗留若依旧版实现或 P1 规划，与当前 Wave 2 存在落差，需 Codex 核查实际可用性。 |
|
||
| 9 | `docs/api-v2/06_dto_vo_catalog.md` | RailwaySystem DTO / VO 领域模型目录与字段规范 | 3. API / Contract | current | `VERIFY_WITH_CODE` | 后端代码中的 DTO/VO 类 | **MERGE** | 集中定义了核心模型，但难独立维护。通用规约并入 Handbook，具体字段拆入各模块文档。 |
|
||
| 10 | `docs/api-v2/07_service_boundary.md` | RailwaySystem Service 聚合边界与模块责任划分 | 2. Architecture | current | `DOC_ONLY` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。经查文中设计的独立 ApplicationService 分层与当前多包单体实际结构不一致，需依代码重构。 |
|
||
| 11 | `docs/api-v2/08_transaction_and_invariants.md` | RailwaySystem 事务边界与业务不变量设计 | 2. Architecture | current | `DOC_ONLY` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。旧“排课无重叠”硬不变量与当前 Warning 语义冲突，必须从代码核验后重写。 |
|
||
| 12 | `docs/api-v2/09_external_adapter_contract.md` | 外部系统适配器契约设计 (Integration Contract) | 2. Architecture | current | `DOC_ONLY` | 无 | **REVIEW_REQUIRED** | 原标记 KEEP。文中人脸与门禁 SPI 接口在代码中未落地，属设计资产，需架构师核验后定位。 |
|
||
| 13 | `docs/api-v2/10_permission_and_error_codes.md` | 权限字符与业务错误码规范 | 6. Security / Permission | review | `RUNTIME_PENDING` | 数据库 sys_menu 及异常类 | **UPDATE_AFTER_RUNTIME** | 错误码与权限规范良好，但必须经由 Runtime 实测与 Codex 逐行核实真实抛出错误码后定稿。 |
|
||
| 14 | `docs/api-v2/11_open_questions.md` | 现场验证问题映射与 API 应对策略 (Open Questions) | 1. Product / Business | history | `HISTORICAL` | 各模块业务规则 | **ARCHIVE** | 早期现场需求调研备忘录，其有效结论已固化至设计契约中，原件归入 `archive/`。 |
|
||
| 15 | `docs/api-v2/12_contract_review_round1.md` | Phase 2 Contract Review Round 1 审查报告 | 8. Testing / Release | history | `HISTORICAL` | `api-v2/13` 补丁 | **ARCHIVE** | 里程碑评审会议纪要，结论已通过 V1.0.1 补丁闭环，归档作为过程质保资产。 |
|
||
| 16 | `docs/api-v2/13_contract_patch_v1.0.1.md` | API Contract V1.0.1 Patch 说明 | 3. API / Contract | current | `DOC_ONLY` | `api-v2/00`, `02`, `06` | **MERGE** | 记录了 CG-01~CG-04 修正，其技术事实合并入各模块文档后，补丁说明归档。 |
|
||
| 17 | `docs/codebase-audit/00_project_overview.md` | 代码基线审计：项目概览 | 2. Architecture | history | `HISTORICAL` | 系统全景 | **ARCHIVE** | Phase 0 历史概览，基于遗留工程快照，归入 `archive/phase0-audit/`。 |
|
||
| 18 | `docs/codebase-audit/01_project_tree.md` | 简化项目树 | 2. Architecture | history | `HISTORICAL` | `handbook/architecture/` | **ARCHIVE** | Phase 0 单体工程目录树快照，已被当前多包结构取代，归档。 |
|
||
| 19 | `docs/codebase-audit/02_training_modules_inventory.md` | 培训业务模块与 14 组 CRUD 盘点 | 1. Product / Business | history | `HISTORICAL` | 各模块业务背景 | **MERGE** | 包含对旧 14 张培训业务表的业务逻辑剖析，有价值的背景提炼入 Handbook，原件归档。 |
|
||
| 20 | `docs/codebase-audit/03_database_current_state.md` | 数据库当前状态 (Phase 0) | 4. Database | history | `HISTORICAL` | `database-v2/` 体系 | **ARCHIVE** | 记录旧库 73 张表历史结构，已被 Database V2 物理迁移彻底取代，归档。 |
|
||
| 21 | `docs/codebase-audit/04_api_inventory.md` | 培训接口盘点 (Phase 0) | 3. API / Contract | history | `HISTORICAL` | `api-v2/` 体系 | **ARCHIVE** | 旧若依无契约 CRUD 接口清单，已被全面重构，归档。 |
|
||
| 22 | `docs/codebase-audit/05_frontend_inventory.md` | 培训前端现状 (Phase 0) | 5. Frontend | history | `HISTORICAL` | `build_ui/` 现有视图 | **ARCHIVE** | Phase 0 前端遗留视图快照，归入归档目录。 |
|
||
| 23 | `docs/codebase-audit/06_security_and_permissions.md` | 权限与账号体系 (Phase 0) | 6. Security / Permission | history | `HISTORICAL` | 若依通用安全设计 | **MERGE** | 提取其对若依原生鉴权机制的分析入 Handbook 安全篇，原件归档。 |
|
||
| 24 | `docs/codebase-audit/07_runtime_and_environment.md` | 启动方式与运行环境 | 7. Runtime / Deployment | review | `RUNTIME_PENDING` | CI/CD 与部署手册 | **UPDATE_AFTER_RUNTIME** | 记录了 Docker、JDK、Node 运行要求，必须以 Final Runtime Gate 实测报告为准更新。 |
|
||
| 25 | `docs/codebase-audit/08_git_status.md` | Git 状态（只读快照） | 10. Historical Development Record | history | `HISTORICAL` | 无 | **ARCHIVE** | 当时审计执行时的临时 git status 备份，纯历史过程数据，归档。 |
|
||
| 26 | `docs/codebase-audit/09_reusable_ruoyi_capabilities.md` | 可复用的若依能力 | 2. Architecture | current | `HISTORICAL` | 无 | **MERGE** | 原标记 KEEP。经查包含大量 Phase 0 历史缺陷分析，应提炼若依复用能力入 Handbook，原件归档。 |
|
||
| 27 | `docs/codebase-audit/10_gap_and_conflict_analysis.md` | 当前实现与未来业务设计的冲突点 | 1. Product / Business | history | `HISTORICAL` | `issues-v1/02` | **ARCHIVE** | Phase 0 识别的 12 项业务冲突均已在 Phase 2/3 消化落地，归档。 |
|
||
| 28 | `docs/codebase-audit/11_executive_summary.md` | 代码基线审计 Executive Summary | 1. Product / Business | history | `HISTORICAL` | 阶段总结报告 | **ARCHIVE** | Phase 0 审计管理层摘要，作为里程碑审计成果归档。 |
|
||
| 29 | `docs/codebase-audit/12_baseline_classification.md` | Phase 0：当前 Git 基线分类 | 10. Historical Development Record | history | `HISTORICAL` | 无 | **ARCHIVE** | 早期基线分类与标签管理方案，归入历史资产。 |
|
||
| 30 | `docs/codebase-audit/13_live_database_snapshot.md` | Kingbase 实时数据库快照 (Phase 0) | 4. Database | history | `HISTORICAL` | 旧库结构 | **ARCHIVE** | 当时只读探测快照，作为历史基准归档。 |
|
||
| 31 | `docs/codebase-audit/14_database_code_diff.md` | 设计文档、实时Kingbase与代码三方差异 | 4. Database | history | `HISTORICAL` | 旧差异报告 | **ARCHIVE** | 当时三方一致性校验报告，归入归档目录。 |
|
||
| 32 | `docs/codebase-audit/15_live_permission_snapshot.md` | 培训菜单与权限实时快照 | 6. Security / Permission | history | `HISTORICAL` | 权限审计 | **ARCHIVE** | 记录了当时 23 个菜单项无权限字符串的事实，归入归档目录。 |
|
||
| 33 | `docs/codebase-audit/16_kingbase_readonly_compatibility.md` | Kingbase 只读兼容性核验 | 4. Database | current | `HISTORICAL` | 无 | **MERGE** | 原标记 KEEP。内含旧代码生成器把 db 当 schema 的历史记录（已修复），提炼经验入 Handbook 后归档。 |
|
||
| 34 | `docs/codebase-audit/17_phase0_summary.md` | Phase 0 工程与数据库真实基线总结 | 10. Historical Development Record | history | `HISTORICAL` | 里程碑总结 | **ARCHIVE** | Phase 0 阶段性总结，归档存查。 |
|
||
| 35 | `docs/codebase-audit/18_phase05_runtime_fix.md` | Phase 0.5 基础运行修复审计报告 | 8. Testing / Release | history | `HISTORICAL` | 修复记录 | **ARCHIVE** | 早期启动修复与运行阻断排除验证报告，归档存查。 |
|
||
| 36 | `docs/database-v2/00_readme.md` | 数据库 V2 DDL 生成与设计审查概览 | 4. Database | current | `DOC_ONLY` | `database-v2/01` | **MERGE** | 数据库总体架构与设计思想，提炼合并入 `handbook/database/data-architecture.md`。 |
|
||
| 37 | `docs/database-v2/01_table_inventory.md` | 数据库 V2 表结构清单与模型比对 | 4. Database | current | `DOC_ONLY` | 各模块数据表设计 | **MERGE** | 21 张物理表字段字典，总表并入数据模型 Handbook，分表拆入各 Module 文档。 |
|
||
| 38 | `docs/database-v2/02_migration_plan.md` | 数据库 V2 迁移执行计划 | 11. Database Migration Asset | history | `HISTORICAL` | 执行脚本 | **ARCHIVE** | 6 阶段迁移计划，物理迁移已执行通过，归入 `archive/migrations/`。 |
|
||
| 39 | `docs/database-v2/03_constraint_index_review.md` | 数据库 V2 约束与索引技术审查报告 | 4. Database | current | `HISTORICAL` | 无 | **MERGE** | 原标记 KEEP。属于阶段性审查报告，将外键拓扑与索引建议并入 Handbook 数据库章节，原件归档。 |
|
||
| 40 | `docs/database-v2/04_risk_review.md` | 数据库 V2 关键设计风险深度审查报告 | 4. Database | history | `HISTORICAL` | 风险登记册 | **ARCHIVE** | 针对 R-01~R-17 风险的审查，已在迁移中落地规避，归入归档。 |
|
||
| 41 | `docs/database-v2/05_execution_contract.md` | 数据库 V2 迁移执行契约 | 11. Database Migration Asset | history | `HISTORICAL` | 迁移计划 | **ARCHIVE** | 迁移过程执行约束，属于实施过程约束，归档。 |
|
||
| 42 | `docs/database-v2/06_review_round1_changes.md` | 数据库 V2 DDL Review 修订记录表 (Round 1) | 11. Database Migration Asset | history | `HISTORICAL` | 修订日志 | **ARCHIVE** | 第一次 DDL 修改纪要，归档。 |
|
||
| 43 | `docs/database-v2/07_review_round2_changes.md` | 数据库 V2 DDL Review Round 2 变更记录 | 11. Database Migration Asset | history | `HISTORICAL` | 修订日志 | **ARCHIVE** | 第二次 DDL 修改纪要，归档。 |
|
||
| 44 | `docs/database-v2/08_gate_ab_validation.md` | 数据库 V2 双门禁验证报告 (Gate A / Gate B) | 8. Testing / Release | history | `HISTORICAL` | 门禁报告 | **ARCHIVE** | 静态语法与隔离门禁通过报告，归入测试归档。 |
|
||
| 45 | `docs/database-v2/09_stage1_backup_validation.md` | 数据库 V2 Stage 1 备份阶段验证报告 | 11. Database Migration Asset | history | `HISTORICAL` | 备份日志 | **ARCHIVE** | Stage 1 备份验证流水，归入迁移归档。 |
|
||
| 46 | `docs/database-v2/10_stage2_6_structure_validation.md` | 数据库 V2 Stage 2~6 结构迁移验证报告 | 11. Database Migration Asset | history | `HISTORICAL` | 结构验证 | **ARCHIVE** | DDL 实际生效验证流水，归入迁移归档。 |
|
||
| 47 | `docs/database-v2/11_final_migration_validation.md` | 数据库 V2 最终迁移验收报告 (010_verify PASS) | 8. Testing / Release | history | `HISTORICAL` | 终验报告 | **ARCHIVE** | 010_verify 脚本全绿验收里程碑报告，归入归档。 |
|
||
| 48 | `docs/database-v2/12_generator_v2_readonly_validation.md` | Database V2 Generator 只读验证报告 | 8. Testing / Release | history | `HISTORICAL` | 生成器补丁 | **ARCHIVE** | 代码生成器只读验证测试报告，归档。 |
|
||
| 49 | `docs/database-v2/13_generator_kingbase_fix_validation.md` | Generator Kingbase V2 元数据适配修复报告 | 8. Testing / Release | history | `HISTORICAL` | `generator-v2/01` | **ARCHIVE** | 代码生成器 Kingbase 元数据适配复验记录，归档。 |
|
||
| 50 | `docs/development/demo-electronic-board-cleanup.md` | Electronic Board Demo-Safe Cleanup 实施报告 | 9. Module Documentation | current | `HISTORICAL` | ElectronicBoard 模块 | **ARCHIVE** | 班牌清洗方案报告，核心清洗规则提炼入 `modules/11_electronic-board.md` 后原件归档。 |
|
||
| 51 | `docs/development/issue-01-01-teacher.md` | ISSUE-01-01：师资主数据开发与验收报告 | 9. Module Documentation | current | `HISTORICAL` | Teacher 模块 | **MERGE** | 师资主数据开发验收事实，提取规则、API 与前端交互合并入 `modules/06_teacher.md`。 |
|
||
| 52 | `docs/development/issue-01-02-student.md` | ISSUE-01-02：学员基础主数据开发与验收报告 | 9. Module Documentation | current | `HISTORICAL` | Student 模块 | **MERGE** | 学员脱敏、身份证校验、双来源模型合并入 `modules/05_student.md`。 |
|
||
| 53 | `docs/development/issue-01-03-course.md` | ISSUE-01-03：课程库基础资料开发与验收文档 | 9. Module Documentation | current | `HISTORICAL` | Course 模块 | **MERGE** | 课程属性、学时课时换算规则合并入 `modules/07_course.md`。 |
|
||
| 54 | `docs/development/issue-01-04-space.md` | ISSUE-01-04：教学空间资源维护开发验收文档 | 9. Module Documentation | current | `HISTORICAL` | Classroom & Site 模块 | **MERGE** | 教室与实训场地分离建模、容量规则合并入 `modules/08_classroom.md` 与 `modules/09_training-site.md`。 |
|
||
| 55 | `docs/development/issue-01-05-dormitory.md` | ISSUE-01-05：宿舍房间与楼宇基础数据维护开发验收文档 | 9. Module Documentation | current | `HISTORICAL` | Dormitory 模块 | **MERGE** | 楼宇、房间、床位动态计算模型合并入 `modules/10_dormitory.md`。 |
|
||
| 56 | `docs/development/issue-02-01-plan.md` | ISSUE-02-01：培训计划生命周期开发验收 | 9. Module Documentation | current | `HISTORICAL` | Plan 模块 | **MERGE** | 计划状态机、编号规则、生命周期流转合并入 `modules/01_plan.md`。 |
|
||
| 57 | `docs/development/issue-02-02-plan-course.md` | ISSUE-02-02：本期培训课程引入与配置开发验收 | 9. Module Documentation | current | `HISTORICAL` | PlanCourse 模块 | **MERGE** | 本期课程选择、讲师选派、计划课时匹配规则合并入 `modules/02_plan-course.md`。 |
|
||
| 58 | `docs/generator-v2/01_kingbase_import_identity_patch.md` | Generator 基础设施补丁 — Kingbase Import Identity | 10. Historical Development Record | history | `HISTORICAL` | `database-v2/13` | **ARCHIVE** | 代码生成器底层驱动补丁技术记录，归入历史开发记录归档。 |
|
||
| 59 | `docs/issues-v1/00_readme.md` | Phase 3：P0 Epic / Issue 任务拆分总纲 | 1. Product / Business | history | `HISTORICAL` | `issues-v1/01` | **ARCHIVE** | Phase 3 任务分解管理方案，研发已完成，归入项目管理归档。 |
|
||
| 60 | `docs/issues-v1/01_epic_overview.md` | Phase 3：Epic 架构概览 (Epic Overview) | 1. Product / Business | current | `DOC_ONLY` | 业务全流程 | **MERGE** | 紧扣 PRD 的业务能力域与主链路设计，提炼合并入系统业务架构与流程全景图。 |
|
||
| 61 | `docs/issues-v1/02_p0_issue_backlog.md` | Phase 3：P0 Issue 详细清单 (P0 Issue Backlog) | 1. Product / Business | current | `DOC_ONLY` | 各模块具体规范 | **MERGE** | 包含 26 个 Issue 的详尽设计，应按业务域拆解合并入各具体 Module 文档，原全局清单归档。 |
|
||
| 62 | `docs/issues-v1/03_dependency_graph.md` | Phase 3：Issue 依赖关系有向无环图 (Dependency DAG) | 10. Historical Development Record | history | `HISTORICAL` | 排期图表 | **ARCHIVE** | 敏捷研发批次依赖 DAG 图，属于研发调度历史资产，归档。 |
|
||
| 63 | `docs/issues-v1/04_wave_plan.md` | Phase 3：开发批次计划 (Wave Plan) | 10. Historical Development Record | history | `HISTORICAL` | 研发排期 | **ARCHIVE** | Wave 0~7 开发推进计划，研发阶段性资产，归档。 |
|
||
| 64 | `docs/issues-v1/05_agent_assignment.md` | 研发分工与代码生成器策略 | 10. Historical Development Record | history | `HISTORICAL` | 研发组织方案 | **ARCHIVE** | 多 Agent 研发调度与分工规范，归档。 |
|
||
| 65 | `docs/issues-v1/06_acceptance_matrix.md` | Phase 3：端到端验收矩阵与追踪表 | 8. Testing / Release | review | `RUNTIME_PENDING` | 最终验收报告 | **UPDATE_AFTER_RUNTIME** | 53 个 P0 API 端到端追踪表，必须待 Runtime Gate 最终实测验证后更新并标记 CLOSED。 |
|
||
| 66 | `docs/issues-v1/07_p1_p2_backlog.md` | Phase 3：P1 / P2 需求储备池 (Backlog Register) | 1. Product / Business | current | `DOC_ONLY` | 无 | **UPDATE_FROM_CODE** | 原标记 KEEP。经查部分被列为 P1 的修改端点已在 Wave 2 实现，需从代码核验后剔除已实现项。 |
|
||
| 67 | `docs/issues-v1/08_risk_register.md` | 技术与业务风险登记册 (Risk Register) | 8. Testing / Release | review | `RUNTIME_PENDING` | 已知问题列表 | **UPDATE_AFTER_RUNTIME** | 记录并发锁与业务一致性风险，必须待 Runtime Gate 实测结束后标记最终缓解状态。 |
|
||
| 68 | `docs/issues-v1/09_issue_review_round1.md` | Issue Review Round 1 评审整改报告 | 8. Testing / Release | history | `HISTORICAL` | 评审整改记录 | **ARCHIVE** | 记录 Phase 3 初审整改过程与落地证明，归入过程质量归档。 |
|
||
|
||
---
|
||
|
||
## 三、推荐的目标信息架构与物理目录树
|
||
|
||
遵循 **“工程事实 (Handbook/Modules) — 人类表达 (Visual/Demo) — 历史记录 (Archive)”** 严格三权分立原则：
|
||
|
||
```text
|
||
docs/
|
||
├── README.md # [SSOT] 全局文档总索引与快速导航入口 (UPDATE_AFTER_RUNTIME)
|
||
│
|
||
├── handbook/ # [系统级工程事实指南与架构规范]
|
||
│ ├── business/
|
||
│ │ ├── business-overview.md # 铁路全流程培训业务价值与闭环说明 (MERGE)
|
||
│ │ └── future-backlog.md # 二期需求储备池 (需从代码核验已实现项后维护) (UPDATE_FROM_CODE)
|
||
│ ├── architecture/
|
||
│ │ ├── system-architecture.md # 总体分层与多包架构 (RuoYi-Vue + ruoyi-train) (MERGE)
|
||
│ │ ├── service-boundaries.md # 模块聚合边界与禁止越权规则 (UPDATE_FROM_CODE)
|
||
│ │ └── transactions-and-invariants.md # 事务边界与核心业务不变量 (含排课 Soft Warning 语义) (UPDATE_FROM_CODE)
|
||
│ ├── api/
|
||
│ │ ├── api-principles.md # RESTful API 设计准则与规范 (UPDATE_FROM_CODE)
|
||
│ │ └── permissions-and-errors.md # 全局错误码与权限字符规范 (UPDATE_AFTER_RUNTIME)
|
||
│ ├── database/
|
||
│ │ ├── data-architecture.md # 21张物理表架构总览与关系字典 (MERGE)
|
||
│ │ ├── indexes-and-constraints.md # 约束、索引与高并发锁优化规范 (MERGE)
|
||
│ │ └── kingbase-compatibility.md # 金仓 KingbaseES 避坑实战指南 (MERGE)
|
||
│ ├── engineering/
|
||
│ │ ├── ruoyi-capabilities.md # 若依框架可复用工程能力指南 (MERGE)
|
||
│ │ └── external-adapters.md # 门禁/硬件外设防腐层集成契约 (REVIEW_REQUIRED)
|
||
│ └── deployment/
|
||
│ ├── runtime-environment.md # 运行环境、依赖栈与配置规格 (端口以实测为准) (UPDATE_AFTER_RUNTIME)
|
||
│ └── cicd-pipeline.md # GitLab CI/CD 流水线配置说明 (VERIFY_WITH_CODE)
|
||
│
|
||
├── modules/ # [11大高内聚独立业务模块全要素文档]
|
||
│ ├── 01_plan.md # 培训计划生命周期模块 (状态机: VERIFY_WITH_CODE)
|
||
│ ├── 02_plan-course.md # 本期培训课程引入与配置模块
|
||
│ ├── 03_enrollment.md # 学员参训档案与名单导入模块 (sourceType: VERIFY_WITH_CODE)
|
||
│ ├── 04_scheduling.md # 智能排课、课次编排与冲突检测模块 (Soft Warning 语义)
|
||
│ ├── 05_student.md # 学员基础主档与隐私安全脱敏模块
|
||
│ ├── 06_teacher.md # 师资资源主数据管理模块
|
||
│ ├── 07_course.md # 课程基础资源库模块
|
||
│ ├── 08_classroom.md # 普通教室教学空间资源模块
|
||
│ ├── 09_training-site.md # 铁路实训演练场地模块
|
||
│ ├── 10_dormitory.md # 学员宿舍楼宇与房态房源模块
|
||
│ └── 11_electronic-board.md # 电子班牌模块 (仅确认绑定教室，场地支持: VERIFY_WITH_CODE)
|
||
│
|
||
├── visual/ # [现代化交互式 HTML 文档站与汇报大屏]
|
||
│ ├── index.html # 视觉文档站仪表盘主入口
|
||
│ ├── system-overview.html # 交互式系统全景与指标看板
|
||
│ ├── business-flow.html # 动态主业务闭环全流程流转图
|
||
│ ├── architecture.html # 分层技术架构与防腐层交互拓扑图
|
||
│ ├── data-model.html # 21张表核心实体 ER 关系与模型关系图
|
||
│ ├── api-map.html # 53个 P0 API 全局交互式全景地图
|
||
│ ├── deployment.html # 运行环境、容器拓扑与 GitLab CI/CD 流程图
|
||
│ ├── demo.html # 16:9 高保真交互式答辩/演示 Presentation (截图以实测为准)
|
||
│ └── modules/ # 11大模块专属交互式展示页面
|
||
│
|
||
├── assets/ # [工程静态资产与真实截图集中营]
|
||
│ ├── diagrams/ # 架构图、流程图、时序图矢量 SVG / Mermaid 源码
|
||
│ └── screenshots/ # Runtime Gate 捕获的高保真实测 UI 截图
|
||
│
|
||
├── archive/ # [历史过程产物与阶段性追溯材料归档 (35份)]
|
||
│ ├── conversations/ # 会话调试与操作过程日志
|
||
│ ├── reviews/ # 阶段性 Review 审查报告 (Round 1/2)
|
||
│ ├── migrations/ # Database V2 物理迁移阶段验证与测试记录
|
||
│ ├── phase0-audit/ # Phase 0 历史基线与旧库审计快照
|
||
│ └── phase3-planning/ # Phase 3 敏捷排期、DAG 依赖图与分工计划
|
||
│
|
||
└── _meta/ # [架构治理元数据与核验清单]
|
||
├── document-audit-draft.md # [本文档] Phase A.1 文档信息架构审计草案 (修正版)
|
||
└── code-verification-checklist.md # 严密事实抽取任务书 (无预设猜测答案)
|
||
```
|
||
|
||
---
|
||
|
||
## 四、11 大 Module 规格要素定义
|
||
|
||
未来在 `docs/modules/*.md` 中建立的每个模块文档，均须统一严格覆盖以下 **18 项要素**：
|
||
|
||
1. **模块是什么 (Definition)**：一句话定义其领域边界。
|
||
2. **业务价值 (Value Proposition)**：解决什么核心管理痛点与业务收益。
|
||
3. **在总业务流程的位置 (Position in Flow)**：前置依赖谁，后置触发谁。
|
||
4. **用户入口 (User Entry)**：菜单路径、导航定位、角色视窗。
|
||
5. **页面与组件 (Pages & Components)**：对应的 Vue 视图文件与子组件（如 `TimetablePanel.vue`）。
|
||
6. **核心业务流程 (Core Workflow)**：带泳道或时序的端到端业务流转。
|
||
7. **状态与状态机 (State Machine)**：从代码中提取的枚举值及其状态迁移矩阵 (`VERIFY_WITH_CODE`)。
|
||
8. **核心业务规则 (Business Invariants)**：硬性校验、软性警告 (Soft Warning)、超编限制。
|
||
9. **API 契约 (API Contract)**：端点、HTTP 方法、请求头。
|
||
10. **DTO / VO 规格 (Data Contracts)**：入参校验规则与出参脱敏规范。
|
||
11. **数据库物理结构 (Database Tables)**：涉及的主从物理表、关键字段与唯一索引。
|
||
12. **安全与权限控制 (Security & Perms)**：按钮级 `v-hasPermi` 与接口 `@ss.hasPermi` 映射。
|
||
13. **业务错误码 (Business Errors)**：模块专属错误码常量与提示文本。
|
||
14. **跨模块联动 (Cross-Module Interactions)**：只读引用边界与领域事件通知。
|
||
15. **Runtime 验证 (Runtime Verification)**：自动化与实测验证用例集（标记 `RUNTIME_PENDING`）。
|
||
16. **当前已知限制 (Known Limitations)**：本期未支持特性与二期演进计划。
|
||
17. **代码导航 (Code Map)**：Controller, Service, Mapper, XML, Vue 关键物理源码超链接。
|
||
18. **Demo 演练步骤 (Demo Walkthrough)**：5步内可复现的完整演示剧本。
|