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

## 概览

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

## 任务

- [x] 1. 创建核心采集模块 `scripts/ops/dataflow_analyzer.py`
  - [x] 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_
  - [x] 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_
  - [x] 1.3 编写属性测试：JSON 递归展开路径正确性
    - **Property 1: JSON 递归展开路径正确性**
    - 使用 hypothesis 递归策略生成任意嵌套 JSON
    - 验证：`.` 分隔路径、`[]` 数组标记、depth 等于路径深度、不遗漏叶子节点
    - **Validates: Requirements 1.1, 1.3, 1.4**
  - [x] 1.4 编写属性测试：多记录字段合并完整性
    - **Property 2: 多记录字段合并完整性与出现频率准确性**
    - 生成随机记录列表（部分字段随机缺失），验证并集完整性和 occurrence 准确性
    - **Validates: Requirements 1.2, 1.5**
  - [x] 1.5 编写单元测试：flatten_json_tree 边界情况
    - 空记录列表、单层 JSON、深层嵌套（5+ 层）、数组内嵌套对象
    - _Requirements: 1.1, 1.2, 1.3, 1.4_

- [x] 2. 实现数据库表结构查询
  - [x] 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_
  - [x] 2.2 实现 `collect_all_tables()` — 完整采集流程编排
    - 根据 config.tables 过滤表，逐表调用 API + flatten + query_table_columns
    - 单表失败不中断，记录 error 字段继续处理其余表
    - _Requirements: 2.1, 2.2, 2.3, 2.4_
  - [x] 2.3 实现 `dump_collection_results()` — 结构化 JSON 落盘
    - 输出 api_samples/、json_trees/、db_schemas/ 和 collection_manifest.json
    - _Requirements: 5.4, 5.6_

- [x] 3. 检查点 — 确保核心采集逻辑测试通过
  - 运行 `pytest tests/test_dataflow_analyzer.py -v`，确保所有测试通过，有问题请询问用户。

- [x] 4. 实现 CLI 入口 `scripts/ops/analyze_dataflow.py`
  - [x] 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_
  - [x] 4.2 实现 `main()` — 串联采集流程
    - 加载环境变量（分层叠加）、构造 AnalyzerConfig、调用 collect_all_tables + dump_collection_results
    - 输出文件名使用 `dataflow_YYYY-MM-DD_HHMMSS.md` 格式
    - _Requirements: 5.4, 5.6_
  - [x] 4.3 编写属性测试：输出文件名格式
    - **Property 3: 输出文件名格式正确性**
    - 生成随机 datetime，验证文件名匹配 `dataflow_YYYY-MM-DD_HHMMSS.md` 模式
    - **Validates: Requirements 5.6**
  - [x] 4.4 编写单元测试：CLI 参数解析和输出目录回退
    - 测试各参数组合、默认值、SYSTEM_ANALYZE_ROOT 存在/缺失
    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5_

- [x] 5. 从现有脚本迁移 API 调用和 ODS_SPECS 配置
  - [x] 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_

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

- [x] 7. 最终检查点 — 确保所有测试通过
  - 运行 `pytest tests/test_dataflow_analyzer.py -v`，确保所有测试通过，有问题请询问用户。

## 备注

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