在准备环境前提交次全部更改。

.kiro/specs/dwd-phase1-refactor/design.md

@@ -0,0 +1,245 @@
+# 设计文档：DWD 第一阶段重构
+
+## 概述
+
+本次重构针对 `DwdLoadTask`（`tasks/dwd/dwd_load_task.py`），目标是：
+
+1. 统一事实表增量窗口模式，消除水位线与窗口两套并行的范围过滤
+2. 删除回补机制（`_insert_missing_by_pk`），简化事实表写入路径
+3. 清理已确认的死代码、未使用常量和方法
+4. 修复 `_build_column_mapping()` 的参数 bug
+
+所有改动集中在 `dwd_load_task.py` 一个文件（加上删除 `base_dwd_task.py`、更新两个外部引用），属于低风险重构。重构后代码路径更清晰，为第二阶段架构重构（E/T/L → `process_segment` 钩子）做好准备。
+
+## 架构
+
+### 当前架构（重构前）
+
+```mermaid
+graph TD
+    A[DwdLoadTask.load] --> B{事实表?}
+    B -->|是| C{use_window?}
+    C -->|是| D["_merge_fact_increment(window_start, window_end)"]
+    C -->|否| E["_get_fact_watermark() → watermark"]
+    E --> F["_merge_fact_increment(watermark)"]
+    D --> G["_insert_missing_by_pk（回补）"]
+    F --> G
+    B -->|否| H{scd_cols_present?}
+    H -->|是| I[_merge_dim_scd2]
+    H -->|否| J[_merge_dim_type1_upsert]
+```
+
+### 目标架构（重构后）
+
+```mermaid
+graph TD
+    A[DwdLoadTask.load] --> B{事实表?}
+    B -->|是| D["_merge_fact_increment(window_start, window_end)"]
+    D --> R[返回计数]
+    B -->|否| I[_merge_dim_scd2]
+```
+
+关键变化：
+- 事实表路径：消除 `use_window` 分支判断，始终传 `context.window_start/window_end`；删除水位线获取和回补步骤
+- 维度表路径：消除 `scd_cols_present` 条件判断，直接调用 `_merge_dim_scd2`（所有 17 张维度表都有 SCD2 列）
+
+## 组件与接口
+
+### 变更组件清单
+
+| 组件 | 变更类型 | 说明 |
+|------|----------|------|
+| `DwdLoadTask.load()` | 修改 | 删除 `use_window` 判断，始终传 `context.window_start/window_end` |
+| `DwdLoadTask._merge_fact_increment()` | 修改 | 删除 `watermark` 分支和回补调用；`window_start`/`window_end` 改为必填参数 |
+| `DwdLoadTask._merge_dim()` | 修改 | 删除 Type1 分支，直接调用 `_merge_dim_scd2` |
+| `DwdLoadTask._build_column_mapping()` | 修改 | 将 `ods_table` 和 `cur` 加入方法签名 |
+| `DwdLoadTask._get_fact_watermark()` | 删除 | 水位线机制不再需要 |
+| `DwdLoadTask._insert_missing_by_pk()` | 删除 | 回补机制不再需要 |
+| `DwdLoadTask._pick_order_column()` | 删除 | 从未被调用的死代码 |
+| `DwdLoadTask._merge_dim_type1_upsert()` | 删除 | Type1 分支永远不触发 |
+| `DwdLoadTask._upsert_scd2_row()` | 删除 | 已被批量方法替代 |
+| `DwdLoadTask._close_current_dim()` | 删除 | 已被 `_close_current_dim_bulk` 替代 |
+| `DwdLoadTask._insert_dim_row()` | 删除 | 已被 `_insert_dim_rows_bulk` 替代 |
+| `FACT_ORDER_CANDIDATES` 常量 | 删除 | 配合 `_pick_order_column` 删除 |
+| `FACT_MISSING_FILL_TABLES` 常量 | 删除 | 配合回补机制删除 |
+| `base_dwd_task.py` | 删除文件 | 死代码，从未被使用 |
+| `debug_dwd.py` | 修改 | 内联时间列候选列表，替代对 `FACT_ORDER_CANDIDATES` 的引用 |
+| `integrity_checker.py` | 修改 | 内联时间列候选列表，替代对 `FACT_ORDER_CANDIDATES` 的引用 |
+
+### 接口变更详情
+
+#### `_merge_fact_increment()` 签名变更
+
+```python
+# 重构前
+def _merge_fact_increment(
+    self, cur, dwd_table, ods_table, dwd_cols, ods_cols,
+    dwd_types, ods_types,
+    window_start: datetime | None = None,  # 可选
+    window_end: datetime | None = None,    # 可选
+) -> Dict[str, int]:
+
+# 重构后
+def _merge_fact_increment(
+    self, cur, dwd_table, ods_table, dwd_cols, ods_cols,
+    dwd_types, ods_types,
+    window_start: datetime,   # 必填
+    window_end: datetime,     # 必填
+) -> Dict[str, int]:
+```
+
+#### `_build_column_mapping()` 签名变更
+
+```python
+# 重构前（bug：引用了外部作用域的 ods_table 和 cur）
+def _build_column_mapping(
+    self, dwd_table: str, pk_cols: Sequence[str], ods_cols: Sequence[str]
+) -> Dict[str, tuple[str, str | None]]:
+
+# 重构后
+def _build_column_mapping(
+    self, cur, dwd_table: str, ods_table: str,
+    pk_cols: Sequence[str], ods_cols: Sequence[str]
+) -> Dict[str, tuple[str, str | None]]:
+```
+
+#### `_merge_dim()` 简化
+
+```python
+# 重构前
+def _merge_dim(self, cur, dwd_table, ods_table, dwd_cols, ods_cols, now):
+    pk_cols = self._get_primary_keys(cur, dwd_table)
+    scd_cols_present = any(c.lower() in self.SCD_COLS for c in dwd_cols)
+    if scd_cols_present:
+        return self._merge_dim_scd2(...)
+    return self._merge_dim_type1_upsert(...)
+
+# 重构后
+def _merge_dim(self, cur, dwd_table, ods_table, dwd_cols, ods_cols, now):
+    return self._merge_dim_scd2(cur, dwd_table, ods_table, dwd_cols, ods_cols, now)
+```
+
+#### `load()` 事实表分支简化
+
+```python
+# 重构前
+use_window = bool(
+    self.config.get("run.window_override.start")
+    and self.config.get("run.window_override.end")
+)
+fact_counts = self._merge_fact_increment(
+    ...,
+    window_start=context.window_start if use_window else None,
+    window_end=context.window_end if use_window else None,
+)
+
+# 重构后
+fact_counts = self._merge_fact_increment(
+    ...,
+    window_start=context.window_start,
+    window_end=context.window_end,
+)
+```
+
+### 外部引用处理
+
+`FACT_ORDER_CANDIDATES` 被两个外部模块引用，删除后需要同步处理：
+
+1. **`scripts/debug/debug_dwd.py`**：将候选列表内联为模块级常量 `_TIME_COLUMN_CANDIDATES`
+2. **`quality/integrity_checker.py`**：将候选列表内联为模块级常量 `_TIME_COLUMN_CANDIDATES`
+
+两处内联的列表内容与原 `FACT_ORDER_CANDIDATES` 相同：`["pay_time", "create_time", "update_time", "occur_time", "settle_time", "start_use_time", "fetched_at"]`。这些模块的用途是调试和完整性检查，与 DWD 装载的核心逻辑无关，内联不会引入耦合问题。
+
+## 数据模型
+
+本次重构不涉及数据库 schema 变更。所有 DWD 表结构、ODS 表结构、`FACT_MAPPINGS` 和 `TABLE_MAP` 保持不变。
+
+变更仅影响运行时行为：
+- 事实表增量 SQL 的 WHERE 条件从"水位线或窗口"统一为"窗口"
+- 回补 LEFT JOIN SQL 不再执行
+- 维度表合并路径从"SCD2 或 Type1"统一为"SCD2"
+
+
+## 正确性属性
+
+*属性（Property）是一种在系统所有有效执行中都应成立的特征或行为——本质上是对系统应做什么的形式化陈述。属性是人类可读规格说明与机器可验证正确性保证之间的桥梁。*
+
+基于验收标准的前置分析，以下属性覆盖了本次重构的核心正确性要求。静态代码结构检查（方法/常量/文件是否存在）通过单元测试覆盖，不作为属性列出。
+
+### Property 1: 事实表增量 SQL 始终使用窗口范围条件
+
+*For any* 有效的事实表映射（`TABLE_MAP` 中 `dwd_` 前缀的表）和任意的 `window_start`/`window_end` 时间对（`window_start < window_end`），`_merge_fact_increment()` 生成的主增量 SQL 的 WHERE 子句 SHALL 包含 `fetched_at >= window_start AND fetched_at < window_end` 条件，且不包含单边水位线条件（`fetched_at > watermark`）。
+
+**Validates: Requirements 1.1, 1.2**
+
+### Property 2: 事实表增量不执行回补 SQL
+
+*For any* 有效的事实表映射和任意的窗口参数，`_merge_fact_increment()` 执行的 SQL 语句列表中 SHALL 不包含 LEFT JOIN 回补查询（即不包含 `LEFT JOIN ... WHERE ... IS NULL` 模式的 SQL）。
+
+**Validates: Requirements 2.3**
+
+### Property 3: 事实表主增量 SQL 结构等价性
+
+*For any* 有效的事实表映射、列集合和窗口参数，重构后 `_merge_fact_increment()` 生成的主增量 `INSERT INTO ... SELECT ... ON CONFLICT` SQL 的结构（列列表、SELECT 表达式、ON CONFLICT 子句）SHALL 与重构前窗口模式（`use_window=True`）生成的 SQL 结构相同。
+
+**Validates: Requirements 5.2, 5.5**
+
+### Property 4: 维度表始终走 SCD2 路径
+
+*For any* 有效的维度表映射（`TABLE_MAP` 中 `dim_` 前缀的表），调用 `_merge_dim()` SHALL 始终委托给 `_merge_dim_scd2()`，不经过任何条件分支判断。
+
+**Validates: Requirements 3.8, 5.1**
+
+## 错误处理
+
+本次重构不引入新的错误处理逻辑，保留现有机制：
+
+| 场景 | 处理方式 | 变更 |
+|------|----------|------|
+| 单表事实增量 SQL 执行失败（含类型转换错误） | `load()` 中 `try/except` 捕获，回滚该表事务，记录错误日志，继续处理下一张表 | 无变更（需求 2.4：异常自然传播到 load() 层面） |
+| 维度表 SCD2 合并失败 | 同上 | 无变更 |
+| ODS 表缺少 `fetched_at` 列 | `_merge_fact_increment` 记录 error 日志并返回零计数 | 无变更 |
+| DWD 表无法获取列信息 | `load()` 记录 warning 并跳过该表 | 无变更 |
+
+删除回补机制后，原本由回补兜底的"部分行丢失"场景不再存在——类型转换失败会导致整条 SQL 报错、整张表事务回滚，这是正确的行为（需求 2.4）。
+
+## 测试策略
+
+### 测试框架
+
+- 单元测试：`pytest`，使用 `FakeDB`/`FakeCursor`（`tests/unit/task_test_utils.py`）
+- 属性测试：`hypothesis`，最少 100 次迭代
+- 测试位置：
+  - 单元测试：`apps/etl/pipelines/feiqiu/tests/unit/test_dwd_phase1_refactor.py`
+  - 属性测试：`tests/test_dwd_phase1_properties.py`（monorepo 根目录）
+
+### 双轨测试方法
+
+**单元测试**覆盖：
+- 静态代码结构验证（死代码/常量/方法已删除）
+- `_build_column_mapping()` bug 修复后的调用正确性
+- `_merge_dim()` 直接调用 SCD2 的行为
+- 外部模块（`debug_dwd.py`、`integrity_checker.py`）导入不报错
+- 表过滤功能（`dwd.only_tables`）回归
+
+**属性测试**覆盖：
+- Property 1: 事实表 SQL 窗口条件（通过 FakeCursor 捕获 SQL，验证 WHERE 子句）
+- Property 2: 无回补 SQL（通过 FakeCursor 捕获所有执行的 SQL，验证无 LEFT JOIN）
+- Property 3: SQL 结构等价性（对比重构前后生成的 SQL）
+- Property 4: 维度表 SCD2 路径（通过 mock 验证调用链）
+
+### 属性测试配置
+
+- 库：`hypothesis`
+- 每个属性最少 100 次迭代
+- 每个属性测试标注对应的设计属性编号
+- 标注格式：`# Feature: dwd-phase1-refactor, Property N: {property_text}`
+
+### 测试数据生成策略
+
+使用 `hypothesis` 的 `@st.composite` 策略生成：
+- 随机的 `window_start`/`window_end` 时间对（确保 `start < end`）
+- 随机的列名集合（确保包含 `fetched_at` 和至少一个主键列）
+- 随机的 `FACT_MAPPINGS` 条目（列名 → 源列 + 可选类型转换）
+
+使用 `FakeCursor` 捕获执行的 SQL 语句，而非实际连接数据库。