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

实现计划：数据流结构分析重构

概览

将 scripts/ops/gen_full_dataflow_doc.py 重构为"Python 数据采集 + Kiro Agent 语义分析"双层架构。Python 脚本负责 API JSON 采集、JSON 递归展开、DB 表结构查询和结构化落盘；Kiro Agent 负责映射计算、字段作用推断、统计总结和报告组装。

任务

• 1. 创建核心采集模块 scripts/ops/dataflow_analyzer.py

  • 1.1 实现数据模型（AnalyzerConfig、FieldInfo、ColumnInfo、TableCollectionResult）
    • 使用 @dataclass 定义四个核心数据类
    • FieldInfo 包含 path、json_type、sample、depth、occurrence、total_records
    • ColumnInfo 包含 name、data_type、is_nullable、column_default、comment、ordinal_position
    • Requirements: 1.1, 1.5, 2.1, 2.2
  • 1.2 实现 flatten_json_tree() 和 _recurse_json() — JSON 递归展开
    • 递归遍历 dict（路径追加 .key）、list（路径追加 []）、标量（记录类型和样本）
    • 遍历所有记录拼合最全字段集，统计每个字段的出现频率
    • 返回 OrderedDict[str, FieldInfo]，按首次出现顺序排列
    • Requirements: 1.1, 1.2, 1.3, 1.4, 1.5
  • 1.3 编写属性测试：JSON 递归展开路径正确性
    • Property 1: JSON 递归展开路径正确性
    • 使用 hypothesis 递归策略生成任意嵌套 JSON
    • 验证：. 分隔路径、[] 数组标记、depth 等于路径深度、不遗漏叶子节点
    • Validates: Requirements 1.1, 1.3, 1.4
  • 1.4 编写属性测试：多记录字段合并完整性
    • Property 2: 多记录字段合并完整性与出现频率准确性
    • 生成随机记录列表（部分字段随机缺失），验证并集完整性和 occurrence 准确性
    • Validates: Requirements 1.2, 1.5
  • 1.5 编写单元测试：flatten_json_tree 边界情况
    • 空记录列表、单层 JSON、深层嵌套（5+ 层）、数组内嵌套对象
    • Requirements: 1.1, 1.2, 1.3, 1.4

• 2. 实现数据库表结构查询

  • 2.1 实现 query_table_columns() — 从 information_schema 查询表结构
    • 使用 information_schema.columns 联合 pg_catalog.pg_description 查询
    • 返回所有列（含版本控制字段 valid_from、valid_to、is_current、fetched_at）
    • 错误处理：连接失败或表不存在时返回空列表并记录错误
    • Requirements: 2.1, 2.2, 2.3, 2.4
  • 2.2 实现 collect_all_tables() — 完整采集流程编排
    • 根据 config.tables 过滤表，逐表调用 API + flatten + query_table_columns
    • 单表失败不中断，记录 error 字段继续处理其余表
    • Requirements: 2.1, 2.2, 2.3, 2.4
  • 2.3 实现 dump_collection_results() — 结构化 JSON 落盘
    • 输出 api_samples/、json_trees/、db_schemas/ 和 collection_manifest.json
    • Requirements: 5.4, 5.6

• 3. 检查点 — 确保核心采集逻辑测试通过

  • 运行 pytest tests/test_dataflow_analyzer.py -v，确保所有测试通过，有问题请询问用户。

• 4. 实现 CLI 入口 scripts/ops/analyze_dataflow.py

  • 4.1 实现 build_parser() 和 resolve_output_dir()
    • argparse 解析 --date-from、--date-to、--limit、--tables 参数
    • resolve_output_dir() 优先读取 SYSTEM_ANALYZE_ROOT，回退到 docs/reports/
    • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5
  • 4.2 实现 main() — 串联采集流程
    • 加载环境变量（分层叠加）、构造 AnalyzerConfig、调用 collect_all_tables + dump_collection_results
    • 输出文件名使用 dataflow_YYYY-MM-DD_HHMMSS.md 格式
    • Requirements: 5.4, 5.6
  • 4.3 编写属性测试：输出文件名格式
    • Property 3: 输出文件名格式正确性
    • 生成随机 datetime，验证文件名匹配 dataflow_YYYY-MM-DD_HHMMSS.md 模式
    • Validates: Requirements 5.6
  • 4.4 编写单元测试：CLI 参数解析和输出目录回退
    • 测试各参数组合、默认值、SYSTEM_ANALYZE_ROOT 存在/缺失
    • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5

• 5. 从现有脚本迁移 API 调用和 ODS_SPECS 配置

  • 5.1 将 gen_full_dataflow_doc.py 中的 ODS_SPECS、api_post、fetch_records 迁移到 dataflow_analyzer.py
    • 保留现有 API 调用逻辑和缓存机制
    • 适配新的 AnalyzerConfig 配置结构
    • Requirements: 1.1, 1.2, 5.1, 5.2

• 6. 创建 Kiro Hook 配置

  • 6.1 创建 .kiro/hooks/dataflow-analyze.kiro.hook
    • type: userTriggered，then.type: prompt
    • prompt 描述完整的数据采集 + 语义分析流程
    • Requirements: 6.1, 6.2, 6.3, 6.4
  • 6.2 编写单元测试：Hook 配置文件格式验证
    • 验证 JSON 结构正确、type 为 userTriggered
    • Requirements: 6.1

• 7. 最终检查点 — 确保所有测试通过

  • 运行 pytest tests/test_dataflow_analyzer.py -v，确保所有测试通过，有问题请询问用户。

备注

• 标记 * 的子任务为可选测试任务，可跳过以加速 MVP
• 每个任务引用了具体的需求编号，确保可追溯
• 属性测试验证通用正确性属性，单元测试验证具体示例和边界情况
• 需求 3（字段作用推断）和需求 4（统计总结）由 Kiro Agent 在 Hook 触发时执行，不在本实现计划中（非代码任务）