# 埋点数据同步方案（设计文档）

## 1. 背景与需求

- **数据源**：埋点系统后端 = Elasticsearch（生产单环境，无 dev / test）
- **量级**：约 1.4M event / 天；gz文件大小约200M; 事件类型 50+ 长尾
- **存量形式**：按天 NDJSON.gz 文件（ES `_search` 导出，每行一个 ES hit 文档）
- **增量形式**：实时写入 ES `traces-{YYYY-MM-DD}` 滚动索引
- **业务目的**：用户行为分析（留存、漏斗、转化、活跃度等）

## 2. 合规约束

- **公司原则**：敏感数据不出业务库 / 不入数仓
- **涉敏举例**：
  - 下单事件：收货地址、收件人姓名、收件人手机号
  - 其他事件按业务实际声明

## 3. 整体方案

```
                 ┌────────────────┐
                 │  埋点 ES (prod) │
                 └────┬───────────┘
                      │
         ┌────────────┴─────────────┐
         │                          │
    [增量路径]                  [历史路径]
   每日 ES → Hive          一次性 .json.gz 文件
   ES Storage Handler            按天解压解析
   映射表 SELECT                 Python 脚本
         │                          │
         └────────────┬─────────────┘
                      │
              【入仓阶段脱敏】
              （按事件类型应用规则）
                      │
                      ▼
           ┌──────────────────┐
           │   raw 层（数仓）  │
           └──────────────────┘
```

两条路径**最终落到两张 raw 表**，schema 一致；脱敏规则共用同一份配置。

## 4. 设计取舍：raw 层默认范式破例

数仓默认 raw 层走 schema-on-read landing 范式（数据原样落、ods 阶段才做类型转换 / 脏数据识别）。本场景**主动破例**：

| §8.1 理由 | 是否适用 | 说明 |
|---|---|---|
| 1. 隔离源端类型变化 | ✗ | 埋点 schema 长尾，新事件 / 新字段频繁，要求协作通知 |
| 2. 同步阶段不可失败 | △ | 部分适用，需对解析失败做容错处理 |
| 3. 保留原始精度与原文 | ✗ | 合规要求就是要丢字段 |
| 4. 脏数据可观测 | △ | 事件本身可观测，脱敏后字段不可回溯（合规接受这代价） |
| 5. schema-on-read 范式契合 | ✗ | 合规要求物理拦截敏感字段，不能等 ods 读取阶段才处理 |

**破例代价**：

- 入仓阶段需做 JSON 解析 + 字段脱敏 + 配置化逻辑
- 埋点上下游 schema 变更需协作通知（违反"隔离源端"原则）
- ods 失去"raw 一定有原始数据可回溯"的兜底保障

## 5. 脱敏策略

### 5.1 三种脱敏动作

| 动作 | 含义 | 适用 |
|---|---|---|
| `drop` | 字段直接删除，不入 raw | 高敏字段（地址、手机号、卡号等） |
| `mask` | 字段保留但用脱敏函数处理 | 中敏字段（脱敏后的姓名、订单号末四位等） |
| `reject` | 整事件不入 raw | 极敏感事件（如有） |

脱敏函数复用现有的 5 种：`md5 / month_trunc / mask_middle / keep_first_n / keep_last_n`。

### 5.2 配置驱动

所有脱敏规则集中在一份配置文件（`conf/tracking-mask.ini`）。

### 5.3 兜底策略：

- **未在配置中的事件 / 字段**：默认允许，全部原样入 raw
- **配置中显式声明 drop / mask 的字段**：按规则处理
- **风险**：新含敏事件没及时进配置 → 原文入仓 → 违规
- **风险缓解**：靠协作流程

## 6. 协作流程

| 场景 | 处理 |
|---|---|
| 新事件 + 无敏感字段 | 默认入仓，无需通知 |
| 新事件 + 有敏感字段 | 强制走流程：埋点开发方注明 → 数仓更新配置 |
| 已有事件加敏感字段 | 同上 |

## 7. 落地范围

本方案仅覆盖 raw 层入仓 + 脱敏。后续阶段（不在本方案）：

- ods 层 schema 设计（按事件分流解析 params_json）
- dwd / dws / ads 层建模

## 8.疑问

|      | dt       | _c1     |
| :--- | :------- | :------ |
| 1    | 20260407 | 1820000 |
| 2    | 20260409 | 1400000 |
| 3    | 20260408 | 1470000 |

为什么文件行数都是整万？是否设置了max_pages 上限。历史数据入仓时需打开限制。