80 lines
5.6 KiB
Markdown
80 lines
5.6 KiB
Markdown
# 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 字段设计...`<br>• `docs/database-v2/01_table_inventory.md`<br>• `docs/api-v2/06_dto_vo_catalog.md` | **[docs/database-v2/01_table_inventory.md](../database-v2/01_table_inventory.md)**<br>*(物理建表以当前 V2 SQL 为准)* |
|
||
| **Cluster 2：P0 业务规则与验收标准** | • `docs/issues-v1/02_p0_issue_backlog.md`<br>• `docs/issues-v1/06_acceptance_matrix.md`<br>• `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`<br>• `docs/codebase-audit/07_runtime_and_environment.md`<br>• `docs/database-v2/00_readme.md` | 根目录 **[README.md](../../README.md)** |
|
||
| **Cluster 4：权限字符与错误码** | • `docs/api-v2/10_permission_and_error_codes.md`<br>• `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`<br>• `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)
|