# 需求文档

## 简介

对现有 `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 负责语义分析和报告编排

现有脚本输出样本参见 `docs/reports/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 应自动发现并纳入分析范围。