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

> 受众：产品 / CTO。实现细节见 `14-埋点同步-开发.md`；全量事件+字段目录见 `16-埋点raw建模.md`；事件粒度重构见 `93-架构决策.md` ADR-13。

## 1. 背景与需求

- **数据源**：埋点 = 神策（Sensors Analytics）SDK 格式；后端 ES，按天 `_search` 导出为 NDJSON.gz（每行一个 ES hit，载荷在 `_source`）
- **交付形式**：运维每天把昨日 gz 放到固定服务器 `/data/upload/traces/traces-YYYY-MM-DD.json.gz`；历史存量一次性补
- **量级**：约 200 万 event / 天，gz 约 200M；事件类型长尾（已上线 164 个自定义事件 + 神策预置）
- **业务目的**：用户行为分析（留存、漏斗、转化、活跃度）

## 2. 合规约束

- **公司原则**：敏感数据不入数仓（物理拦截，不能等 ods）
- **已确认含敏**：收货四要素（`receiverName` / `receiverTelephone` / `receiverArea` / `receiverAddress`），出现在 5 个下单/地址类事件（明细见 `16-埋点raw建模.md`）

## 3. 整体方案（单文件离线路径）

```
固定服务器 gz（运维每日放昨日 + 历史一次性）
        │  hdfs put 到临时目录
        ▼
   Spark SQL（读 gz text → 脱敏 UDF）   ← 入仓前脱敏（合规破例，见 §4）
        ▼
   raw 薄表（脱敏后 _source 整行 JSON）
        ▼
   ods（解析拍平公共属性 + params 半结构化）
        ▼
   dwd（事件分类，待埋点重构后建，ADR-13）
```

- **统一为单一文件路径**：不再走"实时 ES Storage Handler 增量"那条 lane（实时计算后置，见 `kb/20 §6` 脚注）。历史与增量同一套 SQL + 包装脚本，仅 `-dt` 传参不同（增量=昨日，历史=补跑多 dt）。
- **raw 单表** `raw.raw_usr_traces_apd_d`（不可变事件流 → `apd_d` 追加）。

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

数仓默认 raw 走 schema-on-read landing（原样落、ods 再解析）。本场景**主动破例**——入仓前先脱敏：

| `22-业务库raw建模` §0.1 理由 | 适用 | 说明 |
|---|---|---|
| 1. 隔离源端类型变化 | ✗ | 埋点 schema 长尾，新事件/字段需协作通知 |
| 2. 同步阶段不可失败 | △ | 对 JSON 解析失败做容错（返回 null，raw 兜底） |
| 3. 保留原始精度与原文 | ✗ | 合规就是要丢字段 |
| 4. 脏数据可观测 | △ | 事件可观测，脱敏后字段不可回溯（合规接受） |
| 5. schema-on-read 契合 | ✗ | 合规要求物理拦截，不能等 ods |

**破例最小化**：raw 只做脱敏、**不拍平**（仍是"近原样落 _source"，只是删了敏感字段）；拍平/类型转换归 ods、事件分类归 dwd。

## 5. 脱敏策略

### 5.1 脱敏动作

| 动作 | 含义 | 现状 |
|---|---|---|
| `drop`（=trim） | 整字段删除，不入 raw | **当前唯一启用**（收货四要素） |
| `mask` | 字段保留、值脱敏 | 备用，方法见下 |

脱敏方法清单复用项目单一真值（`conf/templates/datax/mask/mask.template.ini`）：`md5 / month_trunc / mask_middle / keep_first_n / keep_last_n`。机制不复用 `datax/mask.py`（那是源 DB 端 SQL 脱敏；埋点无源库），方法语义与 ini 格式复用、执行另写（`dw_base/tracking/mask.py`）。

### 5.2 配置驱动

脱敏规则集中在 `conf/tracking-mask.ini`，按事件分段 `[event:<事件名>]`，作用于 `properties` 顶层与 `params` 两层。

### 5.3 兜底

- 未在配置声明的事件/字段 → 全字段原样入 raw
- **风险**：新含敏事件没及时进配置 → 原文入仓 → 违规
- **缓解**：靠协作流程（§6）；配置缺失时入仓 UDF fail-fast（不静默放过）

## 6. 协作流程

| 场景 | 处理 |
|---|---|
| 新事件 + 无敏感字段 | 默认入仓，无需通知 |
| 新事件 + 有敏感字段 / 老事件加敏感字段 | 强制走流程：埋点开发方注明 → 数仓更新 `tracking-mask.ini` |

## 7. 落地范围

- ✅ raw 入仓 + 脱敏、ods 解析拍平（已落地并冒烟验证）
- ⬜ dwd 事件建模：等埋点重构（ADR-13 行为大类+参数）后建统一事件宽表；当前 event explosion 下不抢跑

## 8. 数据特性（探查实测）

- **行数非整万**：早期小样本"整万"是误读，全量解析实测精确（如 20250906 = 2,042,539 行）；**ES 导出无 max_pages 截断**。
- **事件日 vs 文件日**：ES 按东八区事件日分索引，文件内 ~99.4% 事件日=文件日，~0.6% 是 SDK 离线晚传的迟到事件（最老到 2024）+ 极少时钟偏差未来事件。**ods 按 N=1 不归位、dt=文件日，业务允许此小偏差**（分布与窗口决策见 workspace 留档）。