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

受众：产品 / 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 留档）。

13-埋点同步-设计.md 4.6 KB 文件歷史 原始文件