# RailwaySystem 文档现状审计与资产盘点报告 (Documentation Audit) > **文档定位**：正式归档 D.0 Documentation Current-State Audit 审计事实、文档分类、重复集群与未来归档治理建议。 > **基线版本**：Final Candidate `5a49b2e2988bf23ca2a70568264c05b24dfda1b6` (`origin/feat/cicd-pipeline`) > **审计原则**：本轮只读取并形成审计建议，**绝对不物理搬迁、不重命名底层契约目录**。 --- ## 1. docs 目录盘点与结构统计 经对工程当前 HEAD 进行全面只读扫描： * **`docs/` 目录内 Markdown 文档总数**：**70 份**（加根目录与 `doc/` 历史中心共 85 份）。 * **目录分布明细**： * `docs/README.md` (1 篇) * `docs/_meta/` (2 篇：核心场景测试矩阵与分析模块适配审计) * `docs/api-v2/` (14 篇：00~13 冻结的 API REST 契约、DTO/VO、权限与错误码) * `docs/database-v2/` (14 篇：00~13 21张物理表清单、迁移计划、Gate验证记录) * `docs/issues-v1/` (10 篇：00~09 Wave 波次编排、P0 Issue 待办、AC 验收矩阵) * `docs/development/` (8 篇：各 Issue 实施与 Smoke 验证记录) * `docs/generator-v2/` (1 篇：Kingbase 序列识别补丁说明) * `docs/handbook/deployment/` (1 篇：Kingbase JDBC 驱动供应指南) * `docs/codebase-audit/` (19 篇：00~18 历史 Phase 0 代码与数据库实测快照) --- ## 2. 文档分类与成熟度分布 对现有文档按业务性质进行深度分类统计： | 文档分类类型 | 数量 | 典型代表文件与说明 | | :--- | :---: | :--- | | **A. HUMAN_READABLE** | 3 篇 | 根目录 `README.md`、`doc/README.md`、`doc/PRD V1.0.md`（面向人类与评审）。 | | **B. AGENT_TECHNICAL** | 28 篇 | `issues-v1/` 波次分配、`api-v2/` 服务边界与设计原则、`generator-v2/` 补丁。 | | **C. CONTRACT_SOURCE** | 16 篇 | **技术最高事实源**：`api-v2/` 接口定义、`database-v2/01_table_inventory.md`、`PRD V1.0`。 | | **D. TEST_EVIDENCE** | 16 篇 | `_meta/core-business-test-matrix.md`、`database-v2/` 门禁报告、`development/issue-*` 报告。 | | **E. RELEASE_DEPLOYMENT**| 4 篇 | `kingbase-jdbc-provisioning.md`、`database-v2/02_migration_plan.md` 等。 | | **F. HISTORICAL** | 28 篇 | `codebase-audit/` 全套 19 篇、`doc/raw_materials/`、`doc/archive/`。 | | **G. DUPLICATE** | 5组集群 | 涉及 15+ 篇文档（详见第 4 节）。 | | **H. STALE (过时内容)** | 22 篇 | 旧 `docs/README.md`、`codebase-audit/` 19 篇、早期未采纳草案。 | | **I. UNKNOWN** | 0 篇 | 经过逐行读取，全部文档的来历与用途均已明确，无未知孤儿文档。 | --- ## 3. 旧入口与信息架构缺陷诊断 1. **入口断头路**：旧版 `docs/README.md` 仅列出了 `codebase-audit/`，使新人误以为旧代码就是当前状态，后续完成的 `api-v2`、`database-v2` 等核心技术资产完全隐形。 2. **同名目录混淆**：根目录下同时存在 `doc/` 和 `docs/`，缺乏上层导航协调。 3. **技术文档机翻味过重**：大量的 Gate 验证记录与 Issue 过程文档充斥着 Agent 执行日志格式，人类可读性较差。 --- ## 4. 五大重复集群与 Source of Truth 认定 (Duplication Clusters) | 重复集群主题 | 涉及文档清单 | 认定的权威事实源 (Source of Truth) | | :--- | :--- | :--- | | **Cluster 1：数据库 V2 表结构与字段** | • `doc/RailwaySystem 数据库 V2 字段设计...`
• `docs/database-v2/01_table_inventory.md`
• `docs/api-v2/06_dto_vo_catalog.md` | **[docs/database-v2/01_table_inventory.md](../database-v2/01_table_inventory.md)**
*(物理建表以当前 V2 SQL 为准)* | | **Cluster 2：P0 业务规则与验收标准** | • `docs/issues-v1/02_p0_issue_backlog.md`
• `docs/issues-v1/06_acceptance_matrix.md`
• `docs/development/issue-*.md` | **[docs/issues-v1/02_p0_issue_backlog.md](../issues-v1/02_p0_issue_backlog.md)** 与 **[docs/issues-v1/06_acceptance_matrix.md](../issues-v1/06_acceptance_matrix.md)** | | **Cluster 3：本地启动与环境搭建** | • `README.md`
• `docs/codebase-audit/07_runtime_and_environment.md`
• `docs/database-v2/00_readme.md` | 根目录 **[README.md](../../README.md)** | | **Cluster 4：权限字符与错误码** | • `docs/api-v2/10_permission_and_error_codes.md`
• `docs/issues-v1/02_p0_issue_backlog.md` | **[docs/api-v2/10_permission_and_error_codes.md](../api-v2/10_permission_and_error_codes.md)** | | **Cluster 5：排课冲突预检规则** | • `docs/api-v2/03_module_b_plan_enrollment_schedule_api.md`
• `docs/issues-v1/02_p0_issue_backlog.md` | **[docs/api-v2/03_module_b_plan_enrollment_schedule_api.md](../api-v2/03_module_b_plan_enrollment_schedule_api.md)** | --- ## 5. 历史目录界定与未来归档建议 为保证 CI/CD 与自动化工具链路不被破坏，**本轮严禁执行物理文件迁移**。未来版本建议做如下轻量归档： 1. **明确 Historical 标记**： - 将 `docs/codebase-audit/`（19 篇）在索引中统一声明为“Phase 0 历史代码快照”，防止新同学误读。 - 将 `doc/raw_materials/` 与 `doc/archive/` 保持在历史资料区。 2. **禁止擅自替代冻结契约**： - 严禁创建 `03_contracts/` 目录强行替代原有的 `api-v2/` 和 `database-v2/`，新增的 Human Handbook 必须建立在现有契约之上。 --- ## 6. 技术参考链接 (Technical References) * 文档中心总导航：[docs/README.md](../README.md) * 人类操作手册：[docs/handbook/01-project-overview.md](../handbook/01-project-overview.md) * 核心测试矩阵：[docs/_meta/core-business-test-matrix.md](core-business-test-matrix.md)