# 设计文档：ODS 去重与软删除机制标准化

## 概述

本设计对 ODS 层的 `OdsTaskSpec` 配置、content_hash 去重策略、软删除语义进行标准化改造。核心原则：ODS 是追加写入的版本化存储，每次内容变更（包括删除）都是一个新版本行。

改造分四个阶段：
1. **配置精简**（方案 1）：删除无效/冗余字段，引入 SnapshotMode 枚举
2. **去重优化**（方案 2）：默认开启 skip_unchanged，hash 改用 payload + is_delete
3. **索引支持**（方案 3）：为"取最新版本"查询添加复合索引
4. **软删除语义**（方案 4）：从 UPDATE 改为 INSERT 删除版本行

## 改造前后对比

### 配置层对比

| 维度 | 改造前 | 改造后 |
|------|--------|--------|
| 去重开关 | `enable_content_hash_dedup=False`（22/23 任务关闭） | `skip_unchanged=True`（默认开启） |
| 快照策略 | `snapshot_full_table` + `snapshot_window_columns` 两个字段组合 | `SnapshotMode` 枚举（NONE/FULL_TABLE/WINDOW）+ `snapshot_time_column` |
| 冲突列 | `conflict_columns_override`（运行时不生效，仅声明性标注） | 删除，PK 唯一来源为 DDL |
| 冗余字段 | `include_site_column`/`include_page_no`/`include_page_size`（全部 False） | 删除，硬编码移除 |

### content_hash 计算对比

| 维度 | 改造前 | 改造后 |
|------|--------|--------|
| 输入 | 展平后的 merged_rec，排除 7 个元数据字段 | 原始 payload JSON + is_delete |
| 排除逻辑 | `_sanitize_record_for_hash` 递归排除 source_file/source_endpoint/fetched_at/record_index/content_hash/payload/data | 无需排除——payload 天然不含元数据字段 |
| is_delete 参与 | 不参与（is_delete 变化不改变 hash） | 参与（is_delete 变化产生新 hash → 新版本行） |
| 默认行为 | 22/23 任务不算 hash（每次抓取都插入新行） | 所有任务默认算 hash（内容不变则跳过） |

### 软删除对比

| 维度 | 改造前 | 改造后 |
|------|--------|--------|
| 操作方式 | `UPDATE ... SET is_delete=1`（修改所有历史版本） | INSERT 一条 is_delete=1 的新版本行 |
| 历史版本影响 | 所有历史版本的 is_delete 被改为 1 | 历史版本完全不变 |
| 幂等性 | 重复执行无副作用（UPDATE 幂等） | 重复执行无副作用（最新版本已是 is_delete=1 则跳过） |
| 下游取数 | `WHERE is_delete = 0`（但历史版本也被改了） | `DISTINCT ON (id) ORDER BY fetched_at DESC` + `WHERE is_delete = 0` |

### 新版本数据处理流程

#### 正常写入流程（每次 ETL 运行）

```
1. API 抓取 → 获得一批记录
2. 对每条记录：
   a. _normalize_is_delete_flag：标准化 is_delete 字段（API 可能返回 isDelete/is_deleted 等变体）
   b. 取原始 record 作为 payload
   c. _compute_content_hash(payload, is_delete) → 计算 hash
   d. 若 skip_unchanged=True：
      - 查询该业务 ID 在数据库中的最新 content_hash
      - 若 hash 相同 → 跳过（内容未变，无需新版本）
      - 若 hash 不同或无历史记录 → 继续插入
   e. INSERT INTO ods.xxx (..., content_hash, payload, is_delete, fetched_at)
      ON CONFLICT (id, content_hash) DO UPDATE ...
```

#### 软删除流程（快照对比，路径 B）

```
前提：任务配置了 snapshot_mode != NONE，且 run.snapshot_missing_delete=True

1. 收集本次抓取到的所有业务 ID → fetched_keys
2. 查询快照范围内数据库中已有的业务 ID（is_delete != 1）：
   - FULL_TABLE 模式：全表范围
   - WINDOW 模式：WHERE {snapshot_time_column} >= window_start AND < window_end
3. 差集 = 数据库中的 ID - fetched_keys → 缺失 ID
4. 对每个缺失 ID：
   a. SELECT DISTINCT ON (id) * FROM ods.xxx WHERE id = ? ORDER BY fetched_at DESC
      → 读取最新版本行
   b. 若最新版本已是 is_delete=1 → 跳过（幂等）
   c. 否则：
      - 复制最新版本行的所有字段
      - 设 is_delete = 1
      - _compute_content_hash(原payload, is_delete=1) → 新 hash
      - INSERT 新版本行（hash 不同，不会与现有行冲突）
5. 历史版本行完全不变
```

#### 下游取数规约

```sql
-- DWD 层从 ODS 取最新有效版本的标准查询
SELECT DISTINCT ON (id) *
FROM ods.{table_name}
WHERE is_delete IS DISTINCT FROM 1   -- 排除已删除
ORDER BY id, fetched_at DESC;         -- 利用 (id, fetched_at DESC) 索引

-- 若需要包含删除状态（如审计场景）
SELECT DISTINCT ON (id) *
FROM ods.{table_name}
ORDER BY id, fetched_at DESC;
-- 然后在应用层判断 is_delete 字段
```

## 架构

改造集中在 ODS 写入管线的三个核心环节：

```mermaid
flowchart TD
    A[上游 API / JSON 回放] --> B[BaseOdsTask.execute]
    B --> C{记录处理}
    C --> D[_normalize_is_delete_flag<br/>标准化 is_delete 字段]
    D --> E[_compute_content_hash<br/>基于 payload + is_delete 算 hash]
    E --> F{skip_unchanged?}
    F -->|hash 相同| G[跳过]
    F -->|hash 不同或新记录| H[INSERT 新版本行]
    
    B --> I{快照对比}
    I -->|snapshot_mode != NONE| J[_mark_missing_as_deleted]
    J --> K[读取缺失 ID 的最新版本]
    K --> L[构造 is_delete=1 的新版本]
    L --> M{最新版本已是 is_delete=1?}
    M -->|是| N[跳过]
    M -->|否| O[INSERT 删除版本行]
```

**影响范围：**
- `apps/etl/pipelines/feiqiu/tasks/ods/ods_tasks.py` — 主要改动文件
- `db/etl_feiqiu/migrations/` — 新增索引迁移脚本
- `db/etl_feiqiu/schemas/ods.sql` — DDL 注释更新（索引）
- 7 个文档文件 — 同步更新

## 组件与接口

### 1. SnapshotMode 枚举

```python
from enum import Enum

class SnapshotMode(Enum):
    """ODS 快照软删除策略。"""
    NONE = "none"            # 不做快照对比，不触发软删除
    FULL_TABLE = "full_table"  # 全表快照：对比全表所有记录
    WINDOW = "window"        # 窗口快照：仅对比时间窗口内的记录
```

定义在 `ods_tasks.py` 顶部，与 OdsTaskSpec 同文件。

### 2. OdsTaskSpec（改造后）

```python
@dataclass(frozen=False)
class OdsTaskSpec:
    code: str
    class_name: str
    table_name: str
    endpoint: str
    data_path: Tuple[str, ...] = ("data",)
    list_key: str | None = None
    pk_columns: Tuple[ColumnSpec, ...] = ()
    extra_columns: Tuple[ColumnSpec, ...] = ()
    # --- 保留字段（语义不变）---
    include_source_file: bool = True
    include_source_endpoint: bool = True
    include_record_index: bool = False
    include_fetched_at: bool = True
    requires_window: bool = True
    time_fields: Tuple[str, str] | None = ("startTime", "endTime")
    include_site_id: bool = True
    description: str = ""
    extra_params: Dict[str, Any] = field(default_factory=dict)
    # --- 改造字段 ---
    skip_unchanged: bool = True                    # 原 enable_content_hash_dedup，默认翻转
    snapshot_mode: SnapshotMode = SnapshotMode.NONE  # 替代 snapshot_full_table + snapshot_window_columns
    snapshot_time_column: str | None = None          # WINDOW 模式的时间列

    def __post_init__(self) -> None:
        if self.snapshot_mode == SnapshotMode.WINDOW and not self.snapshot_time_column:
            raise ValueError(
                f"任务 {self.code}: snapshot_mode=WINDOW 时必须指定 snapshot_time_column"
            )
        if self.snapshot_mode != SnapshotMode.WINDOW and self.snapshot_time_column is not None:
            raise ValueError(
                f"任务 {self.code}: snapshot_mode={self.snapshot_mode.value} 时不应指定 snapshot_time_column"
            )
```

**删除的字段：**
- `conflict_columns_override` — 运行时不生效
- `include_site_column` — 全部 False
- `include_page_no` — 全部 False
- `include_page_size` — 全部 False
- `snapshot_full_table` — 被 SnapshotMode 替代
- `snapshot_window_columns` — 被 SnapshotMode + snapshot_time_column 替代
- `enable_content_hash_dedup` — 被 skip_unchanged 替代

### 3. 23 个任务的 SnapshotMode 映射

当前配置到新配置的映射规则：

| 原配置 | 新配置 |
|--------|--------|
| `snapshot_full_table=True` | `snapshot_mode=SnapshotMode.FULL_TABLE` |
| `snapshot_window_columns=("col",)` | `snapshot_mode=SnapshotMode.WINDOW, snapshot_time_column="col"` |
| 两者都未设置 | `snapshot_mode=SnapshotMode.NONE`（默认值） |

具体任务映射：

| 任务 | 原配置 | 新 snapshot_mode | snapshot_time_column |
|------|--------|-----------------|---------------------|
| ODS_ASSISTANT_ACCOUNT | snapshot_full_table=True | FULL_TABLE | None |
| ODS_MEMBER_CARD | snapshot_full_table=True | FULL_TABLE | None |
| ODS_GROUP_PACKAGE | snapshot_full_table=True | FULL_TABLE | None |
| ODS_STORE_GOODS | snapshot_full_table=True | FULL_TABLE | None |
| ODS_TENANT_GOODS | snapshot_full_table=True | FULL_TABLE | None |
| ODS_TABLE_USE | snapshot_window_columns=("create_time",) | WINDOW | "create_time" |
| ODS_ASSISTANT_LEDGER | snapshot_window_columns=("create_time",) | WINDOW | "create_time" |
| ODS_STORE_GOODS_SALES | snapshot_window_columns=("create_time",) | WINDOW | "create_time" |
| ODS_REFUND | snapshot_window_columns=("pay_time",) | WINDOW | "pay_time" |
| ODS_PLATFORM_COUPON | snapshot_window_columns=("consume_time",) | WINDOW | "consume_time" |
| ODS_MEMBER_BALANCE | snapshot_window_columns=("create_time",) | WINDOW | "create_time" |
| ODS_GROUP_BUY_REDEMPTION | snapshot_window_columns=("create_time",) | WINDOW | "create_time" |
| ODS_TABLE_FEE_DISCOUNT | snapshot_window_columns=("create_time",) | WINDOW | "create_time" |
| 其余 10 个任务 | 无快照配置 | NONE | None |

### 4. _compute_content_hash（改造后）

```python
@classmethod
def _compute_content_hash(cls, record: dict, payload: Any, is_delete: int) -> str:
    """基于原始 payload 和 is_delete 计算 content_hash。
    
    payload: 原始 API 返回的 JSON 对象（未展平）
    is_delete: 0 或 1
    """
    payload_str = json.dumps(
        payload,
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
        default=cls._hash_default,
    )
    raw = f"{payload_str}|{is_delete}"
    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
```

**关键变更：**
- 输入从"展平后的 merged_rec"改为"原始 payload + is_delete"
- 删除 `_sanitize_record_for_hash` 方法（不再需要字段排除逻辑）
- 删除 `include_fetched_at` 参数（payload 天然不含 fetched_at）
- 分隔符 `|` 确保 payload 和 is_delete 不会产生歧义

**一次性代价：** 切换后首次运行，所有记录的 hash 都会变化（因为算法不同），会插入一批新版本行。这是预期行为，后续运行恢复正常去重。

### 5. _mark_missing_as_deleted（改造后）

```python
def _mark_missing_as_deleted(self, *, table, business_pk_cols, 
                              snapshot_mode, snapshot_time_column,
                              window_start, window_end,
                              key_values, allow_empty) -> int:
    """快照对比软删除：INSERT 删除版本行，而非 UPDATE 历史版本。"""
    # 1. 查询快照范围内、is_delete != 1 的业务 ID
    # 2. 排除本次抓取到的 key_values，得到缺失 ID 集合
    # 3. 对每个缺失 ID：
    #    a. 读取最新版本行（DISTINCT ON ... ORDER BY fetched_at DESC）
    #    b. 若最新版本已是 is_delete=1，跳过
    #    c. 否则：复制该行，设 is_delete=1，重算 content_hash，INSERT
    # 4. 返回插入的删除版本行数
```

**接口变更：**
- `window_columns` 参数改为 `snapshot_mode` + `snapshot_time_column`
- `full_table` 参数删除（由 snapshot_mode 表达）
- 内部从 UPDATE 改为 SELECT + INSERT

### 6. _insert_records_schema_aware 的适配

- `compare_latest` 判断条件中 `self.SPEC.enable_content_hash_dedup` 改为 `self.SPEC.skip_unchanged`
- `_compute_content_hash` 调用签名变更：传入原始 record（作为 payload）和 is_delete 值
- 删除对 `include_site_column`、`include_page_no`、`include_page_size` 的引用

### 7. BaseOdsTask.execute 的适配

- `snapshot_full_table` / `snapshot_window_columns` 的读取改为 `spec.snapshot_mode` / `spec.snapshot_time_column`
- `_mark_missing_as_deleted` 调用参数适配
- 删除对已移除字段的引用

## 数据模型

### ODS 表结构（不变）

所有 23 个 ODS 表的 DDL 结构不变，PK 仍为 `(业务id, content_hash)`。

### 新增索引（迁移脚本）

每张含 `fetched_at` 列的 ODS 表新增复合索引：

```sql
-- 迁移脚本：db/etl_feiqiu/migrations/YYYY-MM-DD__add_ods_latest_version_indexes.sql
-- 为 DISTINCT ON (id) ORDER BY id, fetched_at DESC 查询模式提供索引支持

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_ods_member_profiles_latest
    ON ods.member_profiles (id, fetched_at DESC);

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_ods_member_balance_changes_latest
    ON ods.member_balance_changes (id, fetched_at DESC);

-- ... 对每张含 fetched_at 的 ODS 表重复此模式
-- 索引命名规范：idx_ods_{table_name}_latest
-- 业务主键列名因表而异（大多数是 id，少数是 recharge_order_id、sitegoodsstockid 等）
```

**注意：**
- `include_fetched_at=False` 的任务（如 ODS_ASSISTANT_ACCOUNT）其表中 fetched_at 列有 DEFAULT now()，实际仍有值，也需要索引。但需确认 DDL 中是否所有表都有 fetched_at 列。
- 索引定义需同步写入 `db/etl_feiqiu/schemas/ods.sql`（DDL 源文件），确保新环境初始化时自动创建索引。
- 迁移脚本 `db/etl_feiqiu/migrations/YYYY-MM-DD__add_ods_latest_version_indexes.sql` 用于已有环境的增量部署。

### 下游查询规约

DWD 层从 ODS 取数的标准模式：

```sql
SELECT DISTINCT ON (id) *
FROM ods.{table_name}
WHERE is_delete = 0  -- 或 is_delete IS DISTINCT FROM 1
ORDER BY id, fetched_at DESC;
```

此查询利用新增的 `(id, fetched_at DESC)` 索引，避免全表扫描。

## 正确性属性

*正确性属性是系统在所有合法执行路径上都应保持的特征或行为——本质上是对"系统应该做什么"的形式化陈述。属性是人类可读规格与机器可验证正确性保证之间的桥梁。*

### Property 1: SnapshotMode 与 snapshot_time_column 一致性

*For any* OdsTaskSpec 实例，当 snapshot_mode 为 WINDOW 时 snapshot_time_column 必须为非空字符串，当 snapshot_mode 为 FULL_TABLE 或 NONE 时 snapshot_time_column 必须为 None；违反此约束应抛出 ValueError。

**Validates: Requirements 2.3, 2.4, 2.5, 2.6**

### Property 2: content_hash 确定性

*For any* 原始 payload（合法 JSON 对象）和 is_delete 值（0 或 1），对相同的 (payload, is_delete) 输入调用 `_compute_content_hash` 应始终产生相同的 SHA-256 哈希值。

**Validates: Requirements 5.1, 5.4**

### Property 3: content_hash 区分性

*For any* 两组不同的 (payload, is_delete) 输入（payload 不同或 is_delete 不同），`_compute_content_hash` 应产生不同的哈希值。

**Validates: Requirements 5.5**

### Property 4: skip_unchanged 跳过内容未变的记录

*For any* ODS 任务（skip_unchanged=True），当一条记录的 content_hash 与数据库中该业务 ID 最新版本的 content_hash 相同时，该记录应被计入 skipped 而非 inserted。

**Validates: Requirements 4.3, 8.5**

### Property 5: 记录数闭合不变量

*For any* 非空记录列表被写入 ODS 时，`fetched == inserted + updated + skipped` 恒成立。

**Validates: Requirements 8.3**

### Property 6: 软删除构造正确性

*For any* 快照对比中发现的缺失业务 ID，`_mark_missing_as_deleted` 应读取该 ID 的最新版本行，构造一条 is_delete=1 的新版本行，其 content_hash 基于原始 payload + is_delete=1 重算，并通过 INSERT（而非 UPDATE）写入。

**Validates: Requirements 7.1, 7.2, 7.4**

### Property 7: 软删除幂等性

*For any* 业务 ID，若其最新版本已经是 is_delete=1，再次执行 `_mark_missing_as_deleted` 不应插入新的删除版本行。

**Validates: Requirements 7.3, 8.7**

### Property 8: 软删除不修改历史版本

*For any* 软删除操作执行后，数据库中该业务 ID 的所有历史版本行（执行前已存在的行）的内容应保持不变——不应有 UPDATE 语句作用于 ODS 表。

**Validates: Requirements 7.4, 8.6**

## 错误处理

### OdsTaskSpec 校验错误

- `SnapshotMode.WINDOW` + `snapshot_time_column=None` → `__post_init__` 抛出 `ValueError`
- `SnapshotMode.FULL_TABLE/NONE` + `snapshot_time_column` 不为 None → `__post_init__` 抛出 `ValueError`
- 这些错误在任务注册时（模块加载时）即触发，属于 fail-fast 设计

### hash 算法切换的一次性代价

- 首次运行后所有记录的 content_hash 都会变化，导致全量插入新版本行
- 这是预期行为，不是错误
- 日志中应记录 "hash 算法已变更，本次运行将插入全量新版本" 的提示信息
- 后续运行恢复正常去重

### 软删除的边界情况

- 缺失 ID 在数据库中无任何记录（从未抓取过）→ 跳过，不插入删除版本
- 缺失 ID 的最新版本已是 is_delete=1 → 跳过（幂等性）
- 快照范围内无任何记录且 allow_empty=False → 返回 0，不执行任何操作

### 迁移脚本错误

- `CREATE INDEX CONCURRENTLY` 不能在事务块内执行 → 迁移脚本需单独执行
- 索引创建失败不影响数据写入，仅影响查询性能 → 可重试

## 测试策略

### 属性测试（hypothesis）

使用 `pytest` + `hypothesis` 库，每个属性测试至少运行 100 次迭代。

**测试文件：** `apps/etl/pipelines/feiqiu/tests/unit/test_ods_dedup_properties.py`

| 属性 | 测试方法 | 生成策略 |
|------|---------|---------|
| Property 1 | 生成随机 SnapshotMode + snapshot_time_column 组合，验证校验逻辑 | `st.sampled_from(SnapshotMode)` × `st.one_of(st.none(), st.text(min_size=1))` |
| Property 2 | 生成随机 JSON payload + is_delete，验证两次调用结果相同 | `st.dictionaries(st.text(), st.text())` × `st.sampled_from([0, 1])` |
| Property 3 | 生成两组不同的 (payload, is_delete)，验证 hash 不同 | 同上，加 `assume(pair1 != pair2)` |
| Property 4 | 用 PkAwareFakeDB 预设最新 hash，验证相同记录被跳过 | `_ods_record_with_id` 策略 |
| Property 5 | 生成随机记录列表，验证 fetched == inserted + updated + skipped | `st.lists(_ods_record_with_id)` |
| Property 6 | 用 FakeDB 模拟缺失 ID 场景，验证 INSERT 而非 UPDATE | `st.lists(st.integers())` |
| Property 7 | 预设最新版本 is_delete=1，验证不产生新行 | 同上 |
| Property 8 | 执行软删除后检查 FakeDB 中无 UPDATE 语句 | 同上 |

每个测试用注释标注：`# Feature: ods-dedup-standardize, Property N: {title}`

### 单元测试

**测试文件：** 适配现有 `test_ods_tasks.py` 和 `test_debug_ods_properties.py`

- 适配 OdsTaskSpec 构造函数变更（删除旧字段，使用新字段）
- 适配 `_compute_content_hash` 签名变更
- 适配 `_mark_missing_as_deleted` 参数变更
- 验证 SnapshotMode 枚举的边界情况（edge cases from prework 2.5, 2.6）

### 现有测试适配

现有测试中需要适配的关键点：
- `test_debug_ods_properties.py` 中的 Property 4（content_hash 确定性）需要适配新的 `_compute_content_hash` 签名
- `test_debug_ods_properties.py` 中的 Property 5（快照删除标记）需要适配新的 INSERT 语义（检查 INSERT 而非 UPDATE）
- `test_ods_tasks.py` 中的所有任务测试需要确保在新的 OdsTaskSpec 下仍能正常运行

### 测试执行命令

```bash
# ETL 单元测试（包含属性测试）
cd apps/etl/pipelines/feiqiu && pytest tests/unit -v

# 仅运行本次改造的属性测试
cd apps/etl/pipelines/feiqiu && pytest tests/unit/test_ods_dedup_properties.py -v
```