# 变更审计：合并 ETL Hook 为统一分析入口

- 日期：2026-03-02 00:39:12
- Prompt-ID：P20260301-235954
- 风险标签：dir:etl, root-file
- 审计人：Kiro AI

## 变更概述

将两个功能重叠的 Kiro Hook（"Data Flow Structure Analysis" 和 "ETL Data Consistency Check"）合并为一个统一入口 "ETL Unified Analysis"。新入口支持 `--mode structure|consistency|full`（默认 full），同时为一致性检查增加每表数据截止日期展示。

## 变更文件清单

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| `scripts/ops/etl_unified_analysis.py` | 新增 | 统一编排脚本 |
| `scripts/ops/etl_consistency_check.py` | 修改 | 新增截止日期功能 |
| `.kiro/hooks/etl-unified-analysis.kiro.hook` | 新增 | 统一 hook 入口 |
| `.kiro/hooks/dataflow-analyze.kiro.hook` | 修改 | 设置 enabled=false |
| `.kiro/hooks/etl-data-consistency.kiro.hook` | 修改 | 设置 enabled=false |
| `scripts/ops/monitor_etl_run.py` | 修改 | 引用文本更新 |
| `scripts/ops/export_etl_result.py` | 修改 | 引用文本更新 |

## 改动注解

### `scripts/ops/etl_unified_analysis.py`
- 变更类型：新增
- 原始原因：用户发现 "Data Flow Structure Analysis" 和 "ETL Data Consistency Check" 两个 hook 功能重叠，希望合并为一个统一入口，减少操作步骤
- 思路分析：采用编排模式，`etl_unified_analysis.py` 本身不实现分析逻辑，而是通过 `subprocess.run` 依次调用已有的 `analyze_dataflow.py`、`gen_dataflow_report.py`、`etl_consistency_check.py`。通过 `--mode` 参数控制执行哪些阶段，`--source` 参数控制数据来源（主动调 API 或读 ETL 落盘 JSON）。full 模式下两阶段完成后合并报告输出到 `ETL_REPORT_ROOT`
- 修改结果：用户只需运行一个脚本或触发一个 hook 即可完成全部 ETL 分析。报告路径通过 `_env_paths.get_output_path()` 获取，符合产出物路径规范。支持 `--date-from`、`--date-to`、`--limit`、`--tables` 等参数透传

### `scripts/ops/etl_consistency_check.py`
- 变更类型：修改
- 原始原因：一致性检查报告中缺少每张表的数据截止日期信息，用户无法直观判断数据新鲜度
- 思路分析：新增 `_CUTOFF_DATE_COLUMN` 字典映射每张 ODS 表的时间截止字段（大部分用 `create_time`，`goods_stock_summary` 和 `stock_goods_category_tree` 用 `fetched_at`，部分表用 `createtime`）。新增 `get_data_cutoff_date()` 函数查询 `MAX(col)::date::text`。在 `check_api_vs_ods` 和 `check_ods_vs_dwd` 的返回结果中增加 `data_cutoff` 字段，报告汇总表增加"数据截止"列
- 修改结果：一致性检查报告的 API↔ODS 和 ODS↔DWD 汇总表中新增"数据截止"列，展示每表数据的最后截止日期。查询失败时静默回退显示"—"，不阻断主流程

### `.kiro/hooks/etl-unified-analysis.kiro.hook`
- 变更类型：新增
- 原始原因：为统一编排脚本提供 Kiro hook 触发入口
- 思路分析：`userTriggered` 类型 hook，prompt 中描述了默认行为（full 模式三阶段）和可选参数。继承原两个 hook 的白名单规则（ETL 元数据列、SCD2 管理列、siteProfile 嵌套字段、时间格式等价）
- 修改结果：用户可通过 Kiro 手动触发统一分析，替代原来需要分别触发两个 hook 的操作

### `.kiro/hooks/dataflow-analyze.kiro.hook`
- 变更类型：修改
- 原始原因：功能已合并到统一入口，需禁用避免重复
- 思路分析：仅将 `enabled` 字段从 `true` 改为 `false`，保留完整配置以备回退
- 修改结果：hook 不再出现在可触发列表中，但配置文件保留

### `.kiro/hooks/etl-data-consistency.kiro.hook`
- 变更类型：修改
- 原始原因：功能已合并到统一入口，需禁用避免重复
- 思路分析：同上，仅设置 `enabled: false`
- 修改结果：hook 不再出现在可触发列表中，但配置文件保留

### `scripts/ops/monitor_etl_run.py`
- 变更类型：修改（简要）
- 报告模板中"下一步"引用文本从 "ETL Data Consistency Check" 更新为 "ETL Unified Analysis（统一分析）"

### `scripts/ops/export_etl_result.py`
- 变更类型：修改（简要）
- 报告模板中"下一步"引用文本从 "ETL Data Consistency Check" 更新为 "ETL Unified Analysis（统一分析）"

## 本次对话文件变更

### 新增文件
- `docs/audit/prompt_logs/prompt_log_20260301_235954.md`

### 修改文件
- `NeoZQYY.code-workspace`
- `docs/h5_ui/pages/customer-detail.html`

## 合规检查

- ⚠️ 迁移 SQL：无
- ⚠️ DDL 基线：不涉及
- ⚠️ OpenAPI spec：不涉及（本次变更不涉及接口代码）
- ⚠️ 文档同步：无缺失项（`compliance.code_without_docs` 为空）