# 实施计划：数据库文档整理与补全

## 概述

按照"目录结构 → DDL 对比脚本 → DDL 同步 → ODS 文档 → 映射文档 → 数据字典 → 索引"的顺序，逐步完成文档体系的整理和补全。DDL 对比脚本先编写并测试，再用它驱动实际的 DDL 同步工作。

## 任务

- [x] 1. 规范化 BD_Manual 目录结构
  - 创建 `docs/bd_manual/ETL_Admin/main/` 和 `docs/bd_manual/ETL_Admin/changes/` 目录
  - 创建 `docs/bd_manual/ODS/mappings/` 目录
  - 确认 ODS/DWD/DWS 各层均有 `main/` 和 `changes/` 子目录
  - _Requirements: 1.1, 1.2, 1.3_

- [ ] 2. 编写 DDL 对比脚本
  - [x] 2.1 实现 DDL 解析器和对比核心逻辑 (`scripts/compare_ddl_db.py`)
    - 解析 `CREATE TABLE` 语句提取表名、字段名、字段类型、约束、主键
    - 查询 `information_schema.columns` 获取数据库实际表结构
    - 实现逐表逐字段对比，输出差异分类（MISSING_TABLE、EXTRA_TABLE、MISSING_COLUMN、EXTRA_COLUMN、TYPE_MISMATCH、NULLABLE_MISMATCH）
    - 支持 `--pg-dsn`、`--schema`、`--ddl-path` 参数
    - _Requirements: 2.1, 2.2, 2.3, 2.4_

  - [x] 2.2 编写 DDL 解析器单元测试 (`tests/unit/test_compare_ddl.py`)
    - 测试 DDL 解析器正确提取表名、字段、类型、约束
    - 测试差异检测逻辑识别各类差异
    - 测试边界情况：空文件、COMMENT 含特殊字符
    - _Requirements: 2.1_

  - [x] 2.3 编写 DDL 对比属性测试
    - **Property 2: DDL 对比脚本差异检测完整性**
    - **Validates: Requirements 2.1, 2.2, 2.3, 2.4**

  - [x] 2.4 编写 DDL 修正不动点属性测试
    - **Property 3: DDL 修正后零差异（不动点）**
    - **Validates: Requirements 2.5**

- [x] 3. 检查点 — 确认对比脚本可用
  - 确保所有测试通过，如有问题请向用户确认。

- [x] 4. 执行 DDL 对比并同步
  - [x] 4.1 运行对比脚本对比四个 schema（ODS、DWD、DWS、ETL_Admin）
    - 执行 `scripts/compare_ddl_db.py` 对比每个 schema
    - 记录所有差异项
    - _Requirements: 2.1, 2.2, 2.3, 2.4_

  - [x] 4.2 修正 DDL 文件以匹配数据库实际状态
    - 以数据库为准修正 `database/schema_ODS_doc.sql`、`database/schema_dwd_doc.sql`、`database/schema_dws.sql`、`database/schema_etl_admin.sql`
    - _Requirements: 2.5_

  - [x] 4.3 生成 DDL 变更记录
    - 在对应层的 `changes/` 目录下生成差异说明文档（日期前缀命名）
    - 包含变更说明、兼容性影响、回滚策略、验证 SQL（至少 3 条）
    - _Requirements: 2.6_

- [x] 5. 检查点 — 确认 DDL 同步完成
  - 确保所有测试通过，如有问题请向用户确认。

- [x] 6. 补全 ODS 层表级文档
  - [x] 6.1 为每张 ODS 表编写表级文档 (`docs/bd_manual/ODS/main/BD_manual_{表名}.md`)
    - 从数据库 `information_schema.columns` 获取字段信息
    - 从 DDL `COMMENT ON` 注释提取字段说明、示例值、JSON 字段映射
    - 遵循 DWD/DWS 文档格式：表信息、字段说明、使用说明（含 SQL）、可回溯性
    - 包含 ETL 元数据字段统一说明
    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6_

- [x] 7. 建立 API→ODS 字段映射文档
  - [x] 7.1 为每个 API 端点编写映射文档 (`docs/bd_manual/ODS/mappings/mapping_{端点名}_{表名}.md`)
    - 参考 `docs/api-reference/endpoints/*.md` 获取端点信息和响应字段
    - 参考 DDL `COMMENT ON` 中的 `【JSON字段】` 标注获取映射关系
    - 参考 `models/parsers.py` 中 `TypeParser` 的转换方法记录类型转换规则
    - 包含 ETL 补充字段生成逻辑说明
    - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6_

- [x] 8. 建立 ODS 数据字典和 ETL_Admin 文档
  - [x] 8.1 创建 ODS 数据字典 (`docs/dictionary/ods_tables_dictionary.md`)
    - 列出所有 ODS 表概览：表名、中文说明、主键、记录数、数据来源
    - 遵循现有 DWD/DWS 数据字典格式
    - _Requirements: 5.1, 5.2, 5.3_

  - [x] 8.2 为 ETL_Admin 表编写表级文档 (`docs/bd_manual/ETL_Admin/main/BD_manual_{表名}.md`)
    - 从数据库获取 `etl_admin` schema 表结构
    - 遵循统一文档格式
    - _Requirements: 1.5_

- [x] 9. 编写 BD_Manual 根目录 README.md 索引
  - 创建 `docs/bd_manual/README.md`
  - 列出目录结构说明、各层文档清单、文档命名规范
  - _Requirements: 1.4_

- [x] 10. 编写文档验证脚本
  - [x] 10.1 实现文档覆盖率和格式验证脚本 (`scripts/validate_bd_manual.py`)
    - 验证目录结构一致性（Property 1）
    - 验证 ODS 文档覆盖率和命名规范（Property 4, 6）
    - 验证 ODS 文档格式完整性（Property 5）
    - 验证映射文档覆盖率和命名规范（Property 7, 9）
    - 验证映射文档内容完整性（Property 8）
    - 验证数据字典覆盖率（Property 10）
    - 支持 `--pg-dsn` 参数连接数据库获取表清单
    - _Requirements: 1.2, 3.1, 3.2, 3.6, 4.1, 4.2, 4.6, 5.2_

- [x] 11. 最终检查点 — 确认所有文档完整
  - 运行 `scripts/validate_bd_manual.py` 确认所有验证通过
  - 确保所有测试通过，如有问题请向用户确认。

## 备注

- 标记 `*` 的子任务为可选，可跳过以加速 MVP
- 每个任务引用了具体的需求编号以便追溯
- DDL 修正涉及 `database/` 高风险路径，完成后需触发 `/audit`
- 属性测试验证对比脚本的通用正确性，集成验证脚本验证文档体系的完整性
- ODS 表级文档和映射文档为手动编写（非自动生成），需逐表参考数据库和 API 文档