Neo-ZQYY/.kiro/specs/bd-manual-docs-consolidation/tasks.md

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

概述

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

任务

• 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 对比脚本

  • 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

  • 2.2 编写 DDL 解析器单元测试 (tests/unit/test_compare_ddl.py)

    • 测试 DDL 解析器正确提取表名、字段、类型、约束
    • 测试差异检测逻辑识别各类差异
    • 测试边界情况：空文件、COMMENT 含特殊字符
    • Requirements: 2.1

  • 2.3 编写 DDL 对比属性测试

    • Property 2: DDL 对比脚本差异检测完整性
    • Validates: Requirements 2.1, 2.2, 2.3, 2.4

  • 2.4 编写 DDL 修正不动点属性测试

    • Property 3: DDL 修正后零差异（不动点）
    • Validates: Requirements 2.5

• 3. 检查点 — 确认对比脚本可用

  • 确保所有测试通过，如有问题请向用户确认。

• 4. 执行 DDL 对比并同步

  • 4.1 运行对比脚本对比四个 schema（ODS、DWD、DWS、ETL_Admin）

    • 执行 scripts/compare_ddl_db.py 对比每个 schema
    • 记录所有差异项
    • Requirements: 2.1, 2.2, 2.3, 2.4

  • 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

  • 4.3 生成 DDL 变更记录

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

• 5. 检查点 — 确认 DDL 同步完成

  • 确保所有测试通过，如有问题请向用户确认。

• 6. 补全 ODS 层表级文档

  • 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

• 7. 建立 API→ODS 字段映射文档

  • 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

• 8. 建立 ODS 数据字典和 ETL_Admin 文档

  • 8.1 创建 ODS 数据字典 (docs/dictionary/ods_tables_dictionary.md)

    • 列出所有 ODS 表概览：表名、中文说明、主键、记录数、数据来源
    • 遵循现有 DWD/DWS 数据字典格式
    • Requirements: 5.1, 5.2, 5.3

  • 8.2 为 ETL_Admin 表编写表级文档 (docs/bd_manual/ETL_Admin/main/BD_manual_{表名}.md)

    • 从数据库获取 etl_admin schema 表结构
    • 遵循统一文档格式
    • Requirements: 1.5

• 9. 编写 BD_Manual 根目录 README.md 索引

  • 创建 docs/bd_manual/README.md
  • 列出目录结构说明、各层文档清单、文档命名规范
  • Requirements: 1.4

• 10. 编写文档验证脚本

  • 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

• 11. 最终检查点 — 确认所有文档完整

  • 运行 scripts/validate_bd_manual.py 确认所有验证通过
  • 确保所有测试通过，如有问题请向用户确认。

备注

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