blp/railwaysystem
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
01dfa9f386f59fa058ad8349378f795a67f27832
railwaysystem/docs/_meta/document-audit-draft.md
T

30 KiB
Raw Blame History

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
  2. Runtime / Deployment | 8. Testing / Release | 9. Module Documentation | 10. Historical Development Record
  3. 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)” 严格三权分立原则：

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步内可复现的完整演示剧本。
Reference in new issue View Git Blame Copy Permalink