246 lines
10 KiB
Markdown
246 lines
10 KiB
Markdown
# 设计文档：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 语句，而非实际连接数据库。
|