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

需求文档

简介

整理和补全飞球 ETL 系统的数据库文档体系（docs/bd_manual/），包括目录结构规范化、DDL 与数据库实际状态的对比同步、ODS 层表级文档补全、以及 API JSON → ODS 字段映射文档的建立。本特性不涉及代码逻辑变更，仅涉及文档和 DDL 文件的维护。

术语表

• BD_Manual: 数据库手册目录（docs/bd_manual/），存放各层表级文档、变更记录等
• ODS: 操作数据存储层（Operational Data Store），billiards schema，保留 API 原始数据
• DWD: 明细数据层（Data Warehouse Detail），billiards_dwd schema，清洗后的维度和事实表
• DWS: 数据服务层（Data Warehouse Service），billiards_dws schema，汇总宽表和配置表
• DDL: 数据定义语言文件（database/schema_*.sql），定义表结构
• 表级文档: 以 Markdown 格式编写的单表说明文件，包含表信息、字段说明、使用示例等
• 字段映射文档: 记录 API JSON 响应字段到 ODS 表字段的对应关系和转换逻辑
• SCD2: 缓慢变化维度类型 2，用于 DWD 维度表的历史版本管理
• ETL_Admin: ETL 管理 schema（etl_admin），存放调度、游标、运行记录等元数据

需求

需求 1：规范化 BD_Manual 目录结构

用户故事： 作为数据开发人员，我希望 BD_Manual 目录结构统一规范，以便快速定位各层各类型的数据库文档。

验收标准

1. THE BD_Manual SHALL 包含以下顶层子目录：ODS/、DWD/、DWS/、ETL_Admin/
2. WHEN 某一数据层目录被访问时，THE BD_Manual SHALL 在该层目录下提供 main/（表级文档）和 changes/（变更记录）两个子目录
3. THE DWD 目录 SHALL 额外保留 Ex/ 子目录用于存放扩展表文档
4. THE BD_Manual SHALL 在根目录提供一个 README.md 索引文件，列出目录结构说明和各层文档清单
5. WHEN ETL_Admin schema 存在表时，THE BD_Manual SHALL 在 ETL_Admin/main/ 下为每张表提供表级文档

需求 2：DDL 文件与数据库实际状态对比同步

用户故事： 作为数据开发人员，我希望 DDL 文件与数据库实际表结构保持一致，以便 DDL 文件可作为可信的 schema 参考。

验收标准

1. WHEN 对比 ODS 层 DDL 文件（database/schema_ODS_doc.sql）与数据库 billiards_ods schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项（缺失表、多余表、字段差异、类型差异、约束差异）
2. WHEN 对比 DWD 层 DDL 文件（database/schema_dwd_doc.sql）与数据库 billiards_dwd schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项
3. WHEN 对比 DWS 层 DDL 文件（database/schema_dws.sql）与数据库 billiards_dws schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项
4. WHEN 对比 ETL_Admin 层 DDL 文件（database/schema_etl_admin.sql）与数据库 etl_admin schema 实际表结构时，THE 对比脚本 SHALL 输出所有差异项
5. WHEN 发现差异时，THE DDL 文件 SHALL 以数据库实际状态为准进行修正
6. WHEN DDL 文件被修正后，THE 变更记录 SHALL 在对应层的 changes/ 目录下生成一份差异说明文档

需求 3：补全 ODS 层表级文档

用户故事： 作为数据开发人员，我希望 ODS 层每张表都有完整的表级文档，以便理解原始数据结构和来源。

验收标准

1. THE ODS 表级文档 SHALL 为 billiards_ods schema 中的每张 ODS 表生成一份 Markdown 文档，存放于 docs/bd_manual/ODS/main/
2. THE ODS 表级文档 SHALL 遵循与 DWD/DWS 表级文档一致的格式，包含：表信息表格、字段说明表格、使用说明（含 SQL 示例）、可回溯性信息
3. WHEN ODS 表的字段含有 COMMENT 注释时，THE 表级文档 SHALL 将 COMMENT 中的说明、示例、JSON 字段映射信息提取并填入字段说明
4. THE ODS 表级文档的表信息 SHALL 包含 Schema、表名、主键、数据来源（API 端点或文件）、说明
5. THE ODS 表级文档 SHALL 包含 ETL 元数据字段（content_hash、source_file、source_endpoint、fetched_at、payload）的统一说明
6. THE ODS 表级文档的文件命名 SHALL 遵循 BD_manual_{表名}.md 格式

需求 4：建立 API JSON → ODS 字段映射文档

用户故事： 作为数据开发人员，我希望有一份清晰的 API 响应字段到 ODS 表字段的映射文档，以便理解数据从 API 到 ODS 的转换逻辑。

验收标准

1. THE 映射文档 SHALL 为每个 API 端点与其对应的 ODS 表建立一份映射文件，存放于 docs/bd_manual/ODS/mappings/
2. THE 映射文档 SHALL 包含以下信息：API 端点路径、对应 ODS 表名、JSON 响应路径（如 data.tenantMemberInfos）、每个字段的 JSON 路径到 ODS 列名的映射
3. WHEN 字段存在类型转换或值处理逻辑时，THE 映射文档 SHALL 记录转换规则（如时间格式转换、枚举值映射、金额精度处理）
4. THE 映射文档 SHALL 标注 ETL 补充字段（content_hash、source_file、source_endpoint、fetched_at、payload）的生成逻辑
5. THE 映射文档 SHALL 参考 models/parsers.py 中的解析逻辑和 docs/api-reference/ 中的端点文档作为信息来源
6. THE 映射文档的文件命名 SHALL 遵循 mapping_{API端点名}_{ODS表名}.md 格式

需求 5：建立 ODS 数据字典

用户故事： 作为数据开发人员，我希望有一份 ODS 层的数据字典汇总文档，以便快速查阅所有 ODS 表的概览信息。

验收标准

1. THE ODS 数据字典 SHALL 创建于 docs/dictionary/ods_tables_dictionary.md
2. THE ODS 数据字典 SHALL 列出所有 ODS 表的概览信息，包含：表名、中文说明、主键、记录数、数据来源
3. THE ODS 数据字典 SHALL 遵循与现有 DWD/DWS 数据字典一致的格式