5.6 KiB
5.6 KiB
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. 旧入口与信息架构缺陷诊断
- 入口断头路：旧版
docs/README.md仅列出了codebase-audit/，使新人误以为旧代码就是当前状态，后续完成的api-v2、database-v2等核心技术资产完全隐形。 - 同名目录混淆：根目录下同时存在
doc/和docs/，缺乏上层导航协调。 - 技术文档机翻味过重：大量的 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 (物理建表以当前 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 与 docs/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 |
| 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 |
| 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 |
5. 历史目录界定与未来归档建议
为保证 CI/CD 与自动化工具链路不被破坏，本轮严禁执行物理文件迁移。未来版本建议做如下轻量归档：
- 明确 Historical 标记：
- 将
docs/codebase-audit/（19 篇）在索引中统一声明为“Phase 0 历史代码快照”，防止新同学误读。 - 将
doc/raw_materials/与doc/archive/保持在历史资料区。
- 将
- 禁止擅自替代冻结契约：
- 严禁创建
03_contracts/目录强行替代原有的api-v2/和database-v2/，新增的 Human Handbook 必须建立在现有契约之上。
- 严禁创建
6. 技术参考链接 (Technical References)
- 文档中心总导航：docs/README.md
- 人类操作手册：docs/handbook/01-project-overview.md
- 核心测试矩阵：docs/_meta/core-business-test-matrix.md