Neo-ZQYY/.kiro/specs/dataflow-structure-audit/requirements.md

需求文档

简介

对现有 scripts/ops/gen_full_dataflow_doc.py 全链路数据流文档生成器进行大幅改进，使其能够：

1. 以真实 JSON 数据（API 获取）和数据库实际表结构（information_schema 查询）为唯一数据源，不依赖 DDL 文件
2. 完整展开 JSON 层级结构，遍历所有记录拼合最全字段集
3. 为每个字段增加"字段作用"说明列，由 Kiro Agent 结合 ETL 源码和业务上下文推断
4. 改进统计总结，由 Kiro Agent 编排有业务语义的字段统计和上下游映射总结
5. 将数据采集脚本任务化，支持 CLI 参数（日期范围、条数），落盘到 SYSTEM_ANALYZE_ROOT 目录
6. 全流程通过 Kiro Hook 手动触发，Python 脚本负责机械性数据准备，Kiro Agent 负责语义分析和报告编排

现有脚本输出样本参见 export/SYSTEM/REPORTS/full_dataflow_doc/dataflow_api_ods_dwd.md。

术语表

• Analyzer：数据采集脚本（Python 模块），负责 JSON 采集和数据库表结构查询，输出结构化中间数据供 Kiro Agent 消费
• Kiro Agent：Kiro 的 AI 能力，负责映射计算、字段作用推断、统计总结编排等需要理解代码和业务上下文的工作
• JSON_Tree：API 返回 JSON 数据的完整层级结构，用 . 分隔路径表示（如 data.settleList[].amount）
• Field_Purpose：字段作用说明，由 Kiro Agent 结合 DDL COMMENT、JSON 数据样本、ETL 源码和 ODS/DWD 映射关系推断得出
• SYSTEM_ANALYZE_ROOT：环境变量，定义分析结果落盘的根目录路径
• ODS_Schema：PostgreSQL 中存储原始数据的 schema（ods 或 billiards_ods）
• DWD_Schema：PostgreSQL 中存储明细数据的 schema（dwd）
• information_schema：PostgreSQL 系统目录，提供表结构、列信息、注释等元数据

职责分工

职责	执行者	说明
API 调用获取 JSON 数据	Python 脚本	机械性数据采集，可固化
JSON 结构递归展开	Python 脚本	递归遍历、路径拼接，可固化
数据库表结构查询	Python 脚本	information_schema + pg_description 查询，可固化
JSON → ODS 映射计算	Kiro Agent	需要理解字段语义，纯字符串匹配不可靠
ODS → DWD 映射计算	Kiro Agent	需要读 ETL loader/task 源码理解数据流转
字段作用推断	Kiro Agent	需要结合代码上下文、业务语义、DDL COMMENT 综合判断
统计总结编排	Kiro Agent	需要理解业务含义，生成有意义的总结而非纯数字
报告 Markdown 生成	Kiro Agent	基于上述分析结果组装最终文档

需求

需求 1：JSON 层级结构完整展开

用户故事： 作为数据工程师，我希望看到 API 返回 JSON 的完整层级结构，以便准确理解每个嵌套字段的位置和含义。

验收标准

• 1.1 WHEN Analyzer 处理 API 返回的 JSON 记录时，THEN Analyzer SHALL 递归遍历所有嵌套层级，使用 . 分隔符表示层级路径（如 data.settleList[].amount）
• 1.2 WHEN Analyzer 分析多条 JSON 记录时，THEN Analyzer SHALL 遍历所有记录并拼合出最全字段结构，确保任何记录中出现过的字段都被包含
• 1.3 WHEN JSON 字段为数组类型时，THEN Analyzer SHALL 展开数组内元素的结构，使用 [] 标记数组层级（如 items[].name）
• 1.4 WHEN JSON 字段为嵌套对象时，THEN Analyzer SHALL 在 JSON 字段列中明确展示出层级缩进或路径前缀，使层级关系一目了然
• 1.5 IF JSON 记录中某字段在部分记录中缺失，THEN Analyzer SHALL 仍将该字段纳入最全字段结构，并标注其出现频率（出现次数/总记录数）

需求 2：ODS/DWD 表结构从数据库查询

用户故事： 作为数据工程师，我希望 ODS 和 DWD 的表结构直接从数据库查询获得，以便反映数据库的真实状态而非 DDL 文件的定义。

验收标准

• 2.1 WHEN Analyzer 获取 ODS 表结构时，THEN Analyzer SHALL 通过 information_schema.columns 联合 pg_catalog.pg_description 查询数据库获取列名、数据类型和列注释
• 2.2 WHEN Analyzer 获取 DWD 表结构时，THEN Analyzer SHALL 通过 information_schema.columns 联合 pg_catalog.pg_description 查询数据库获取列名、数据类型和列注释
• 2.3 WHEN Analyzer 列出表结构时，THEN Analyzer SHALL 列出表中所有列，包括业务字段和版本控制字段（如 valid_from、valid_to、is_current、fetched_at 等）
• 2.4 IF 数据库连接失败或表不存在，THEN Analyzer SHALL 记录错误信息并在文档中标注该表结构获取失败，不中断其余表的分析

需求 3：字段作用说明列

用户故事： 作为数据工程师，我希望每个字段都有作用说明，以便快速理解字段的业务含义和在数据流中的角色。

验收标准

• 3.1 WHEN Kiro Agent 生成 API 源字段表格、ODS 表格或 DWD 表格时，THEN Agent SHALL 为每个字段增加"字段作用"列
• 3.2 WHEN Kiro Agent 推断字段作用时，THEN Agent SHALL 读取相关 ETL 源码（loader、task、model），结合 DDL COMMENT、JSON 数据样本和映射关系综合判断
• 3.3 WHEN API 源字段未被 ODS 处理时，THEN Agent SHALL 在"处理"列（原"说明"列改名）中明确标注该字段被忽略且未处理
• 3.4 WHEN ODS 或 DWD 字段有 DDL COMMENT 注释时，THEN Agent SHALL 优先使用该注释作为字段作用说明

需求 4：改进统计总结

用户故事： 作为数据工程师，我希望每个表格结束后有详细的统计总结，以便快速掌握字段覆盖情况和上下游映射关系。

验收标准

• 4.1 WHEN API 源字段表格结束时，THEN Kiro Agent SHALL 生成详细统计总结，包括：总字段数、已映射到 ODS 的字段数、仅存于 payload 的字段数、被忽略的嵌套对象数、各 JSON 类型字段分布
• 4.2 WHEN ODS 表格结束时，THEN Kiro Agent SHALL 生成统计总结，包括：总列数、业务列数、元数据列数、有上游 JSON 映射的列数、有下游 DWD 映射的列数、上下游覆盖率
• 4.3 WHEN DWD 表格结束时，THEN Kiro Agent SHALL 生成统计总结，包括：总列数、有 ODS 来源的列数、ETL 派生列数、SCD2 版本控制列数、上游 ODS 表名和映射类型（维度/事实）

需求 5：数据采集脚本 CLI 化与落盘

用户故事： 作为数据工程师，我希望通过 CLI 参数控制数据采集范围和输出位置，以便为 Kiro Agent 提供新鲜的结构化数据。

验收标准

• 5.1 WHEN 用户通过 CLI 执行 Analyzer 时，THEN Analyzer SHALL 支持 --date-from 和 --date-to 参数定义数据获取的日期范围
• 5.2 WHEN 用户通过 CLI 执行 Analyzer 时，THEN Analyzer SHALL 支持 --limit 参数定义每个端点获取的最大记录条数（默认 200）
• 5.3 WHEN 用户通过 CLI 执行 Analyzer 时，THEN Analyzer SHALL 支持 --tables 参数指定要分析的表名列表（逗号分隔），缺省时分析全部表
• 5.4 WHEN Analyzer 确定输出目录时，THEN Analyzer SHALL 从环境变量 SYSTEM_ANALYZE_ROOT 读取落盘根目录，并将采集数据和最终报告保存到该目录下按日期组织的子目录中
• 5.5 IF SYSTEM_ANALYZE_ROOT 未配置，THEN Analyzer SHALL 回退到默认目录 docs/reports/
• 5.6 WHEN Analyzer 生成文档时，THEN Analyzer SHALL 使用包含日期和时间戳的文件名（如 dataflow_2025-01-15_143022.md），避免覆盖历史文件

需求 6：Kiro Hook 集成

用户故事： 作为开发者，我希望通过 Kiro Hook 手动触发完整的数据流分析流程，一键完成数据采集和语义分析。

验收标准

• 6.1 WHEN Hook 被配置时，THEN Hook SHALL 以 userTriggered 类型注册，允许开发者在 Kiro 中手动触发
• 6.2 WHEN Hook 被触发时，THEN Hook SHALL 先调用 Python 脚本完成数据采集（API JSON + DB 表结构），再由 Kiro Agent 基于采集数据执行语义分析（映射计算、字段作用推断、总结编排）
• 6.3 WHEN Kiro Agent 执行语义分析时，THEN Agent SHALL 读取 ETL 源码（loader、task、model、scd 等模块）理解数据流转逻辑
• 6.4 WHEN 分析完成时，THEN Hook SHALL 将最终 Markdown 报告保存到 SYSTEM_ANALYZE_ROOT 目录，并输出文件路径和关键统计摘要
• 6.5 WHEN 有 2 个及以上 ETL 连接器完成并启用时，THEN Hook SHALL 涵盖所有已启用的连接器，对每个连接器的 API → ODS → DWD 链路分别执行分析

注：当前仅有飞球（feiqiu）连接器，但架构设计需预留多连接器扩展能力。未来新增连接器时，Hook 应自动发现并纳入分析范围。