poyee-data-warehouse/kb/93-架构决策.md

架构决策

重构完成后沉淀的关键架构决策（ADR），给自己看的备忘。

说明

• 本文档是重构完成态的沉淀：90-重构路线.md / 91-重构备忘.md / 92-重构进度.md 三份过程文档会在重构收尾时删除，关键决策、权衡、反悔条件压到这里留档。
• 当前仍在重构中，本文档先留骨架，内容待重构收尾时填入。
• 单条 ADR 格式按业界主流（Michael Nygard 版精简）：背景 / 决策 / 后果 / 候选方案 / 反悔条件 五段；不套公司标准模板的多余字段。

模板

新增一条决策时，复制以下模板到 §2 列表内。编号连续，不复用已弃用编号。

### ADR-NN 决策标题

- **状态**：已采纳 / 被 ADR-MM 取代 / 已弃用
- **背景**：当时面对的问题、约束、触发决策的场景。
- **决策**：最终选了什么方案，一句话。
- **后果**：带来的好处、新增的代价、影响到的模块。
- **候选方案**：考察过但否决的方案，以及否决理由。
- **反悔条件**：什么条件下会重新评估或反悔。

决策清单

ADR-01 DataX 入口默认单日，显式 -backfill 开日循环用于存量回填

• 状态：草案 老 spark-sql-starter 的 get_date_range 支持 20260401-20260410 范围格式自动展开；DataX 入口从未用过。本项目调度用 DolphinScheduler，DS 原生支持业务日期补数（时间区间选定后，按调度周期逐日实例化 task）。用户老 DS 配置即 -start-date=${dt} -stop-date=${cdt} 单日传参。2026-04-24 出现场景：接入新源表需一次性回填 N 年历史存量数据——这类一次性手工批量 DS 的日历补数组件实例化太慢，走外部工具更合适。

• 决策：DataX 入口默认单日语义（start_date / stop_date 对应一个 dt 分区），T+1 增量补数仍归 DS；hive-import 入口 2026-04-24 补 -backfill flag，显式开启后 -start-date / -stop-date 作外层回填范围，按日循环调用单日逻辑，用于存量回填。

• 后果：

  • 正面：DataX 层默认职责单一（单日），T+1 增量 / 补数 / 回溯在 DS 层统一可视化；一次性存量回填通过 -backfill 内置支持，不再需要外部 bash 循环 / 临时 dispatcher
  • 负面：参数语义轻度重载（-start-date / -stop-date 在 -backfill 模式下含义不同）；DS 任务模板规范上不得加 -backfill（团队约定）

• 候选方案：

  • DataX 入口层实现"日期范围自动展开 + 多 json 分发多 worker"作为默认行为——否决（重复 DS 职责 + 增入口常态复杂度）
  • 独立 bin/datax-backfill.py 工具文件——否决（和 hive-import 共享 100% 参数，独立文件冗余；单 flag 切换更简洁）

• 反悔条件：出现必须在 DataX 层做日期展开的默认场景（如 DS 彻底换掉）；或 -backfill 被误用频繁到需物理隔离

ADR-02 分布式分发归 DolphinScheduler worker group，DataX 不重复随机

• 状态：草案 DataX 老入口 single-job-starter.sh 内置 -random + workers.ini 权重加权随机选 worker + ssh 分发。DS 自身亦有 worker group 机制（group 绑定机器列表、task 落到 group 内一台 worker）。两层叠加：DS 选 node01 → node01 上 DataX 再 random 到 node03。【查证 kb/91 §4.4】：用户老 DS 配置不传 -random，说明 DS 层已完成分发，DataX 只在本机跑——两层分发在实际运营中就没被"同时启用"过

• 决策：DataX 入口不做 worker 分发；分布式执行在 task 粒度靠 DS worker group 承担。DataX 入口的 select_worker 等同"返回 current_host"，ssh 分支可删，workers.ini 可移除

• 后果：

  • 正面：消除两层独立随机叠加打乱 DS 负载均衡；DataX 链路大幅简化（worker.py / ssh 远端执行 / workers.ini 可裁）；维护成本下降
  • 负面：单 DS 任务节点内部的批量（多 ini + -parallel）场景无法在 DataX 层散到多 worker，要分布式必须在 DS 层拆成多 task

• 候选方案：保留 DataX 两层分发——否决，"两层独立随机"破坏 DS worker group 语义

• 反悔条件：DS 换成无 worker group 支持的调度器；或单 task 内批量规模大到 DS 拆分成本过高

ADR-03 零点漂移决策

• 状态：草案 T+1 按 update_time 过滤单日窗口 [day-start, day-stop) 同步时，源库在同步执行期间持续写入——跨零点的记录 update_time 会从 N 号"漂到" N+1 号，单日窗口无法捕获漂移记录。

漂移概率和漂移数据量的相关变量：

• 漂移窗口 = 执行时刻距零点的小时数。越晚跑漂移窗口越大
• 漂移窗口越大，单条记录的漂移概率越高
• 漂移窗口内用户越活跃（业务写入高峰落在漂移窗口内），漂移数据量越多

业界一般做法：小数据量、用户低活跃度的场景下，通常凌晨 0:30 前后跑 T+1，漂移窗口 30 分钟、活跃度低，单日固定窗口 [day-start, day-stop) 即可，忽略极少量漂移数据是可接受的工程权衡。

本项目特殊性：业务高峰在凌晨 6 点前，同步定时必须避开高峰定在 6 点后，漂移窗口 6 小时；且若干用户行为集中在 0-6 点，漂移窗口和活跃度两个放大因子都踩中，漂移不能忽略——需要单独设计。

极端场景佐证：某用户习惯 0-6 点更新自己的数据，若走业界做法的单日固定窗口，数仓永远只能看到该用户最早的 create_time 版本，最新状态永远抓不到。

• 决策：

  • raw 层 where 右界扩展为次日同期：where update_time >= '{day-start} 00:00' AND update_time < '{day+1-stop} 00:00'，在关闭侧加 1 天 buffer 覆盖漂移
  • buffer 取 1 天而非 N 小时：定时可变更（同步执行时刻从 6 点调到 3 点或 8 点都不影响窗口语义）+ 可维护（固定区间可复跑、可回刷）
  • raw 层不纠正分区漂移：所有抓到的记录（含"漂到次日"的）按 ini dt = start_date（业务日）统一落当日分区，分区内允许含次日漂移数据
  • ods 层 Spark SQL 用动态分区 PARTITION (dt)，按每行 update_time 真实日期归位
  • ods 写入模式：INSERT OVERWRITE 覆盖式 + 双源 union raw dt=T-1 + raw dt=T-2，按 WHERE DATE(update_time) = T-1 过滤，dedupe by (pk, max(update_time))。覆盖式写入支持重跑；双源 union 完整捕获 update_time ∈ [T-1, T) 范围的所有版本（含跨 raw 任务时段被业务覆盖更新跨日的早期版本）
  • 为什么双源 union 必要（具体例子）：

  设定：业务日 04-27，跑批日 04-28，raw 任务凌晨 03:00 跑批，业务库覆盖式更新会推 update_time 字段。

  订单 X 的 update 时间线（业务库视角）：

  • 04-27 02:00：update，update_time = 04-27 02:00（状态 A）
  • 04-28 02:00：再 update，update_time = 04-28 02:00（状态 B，跨日）

  raw 抓取过程：

  • raw dt=04-26 任务（04-27 03:00 跑批，窗口 [04-26, 04-28)）：业务库 X 是状态 A，抓到 update_time = 04-27 02:00 → 落 raw dt=04-26 / update_dt=04-27
  • raw dt=04-27 任务（04-28 03:00 跑批，窗口 [04-27, 04-29)）：业务库 X 已变成状态 B（04-27 02:00 那条 update_time 字段被覆盖到 04-28 02:00），抓到 update_time = 04-28 02:00 → 落 raw dt=04-27 / update_dt=04-28

  ods 04-28 跑批写 dt=04-27 分区（WHERE DATE(update_time)='04-27'）：

  • 单源 raw dt=04-27：X update_time = 04-28 02:00，DATE=04-28，不入 → ods dt=04-27 漏 X 的 04-27 状态 ❌
  • 双源 union raw dt=04-27 + raw dt=04-26：raw dt=04-26 里 X update_time = 04-27 02:00（DATE=04-27，入），raw dt=04-27 里 X update_time = 04-28 02:00（不入）→ ods dt=04-27 完整包含 X 的 04-27 状态 A ✓

  X 的 04-28 状态 B 第二天 ods 04-29 跑批时落 ods dt=04-28 分区，拉链表轨迹完整无断节。

  业务高峰跨零点（如本项目订单 0-6 点高峰）下，跨日漂移是常态，双源 union 是必要机制不是 defensive。

  • ods 层跨 dt 不去重：同一业务 id 允许在多个 dt 分区并存（每条代表一个"时间段状态快照"）——上层拉链表（SCD Type 2）的必要基础
  • T+1 batch 容忍边界：

  本设计基于 T+1 batch ETL，容忍范围明确：

  • 可救回：跨日漂移 1 次（双源 union 救回）；同 pk 跨多日持续 update（每天 batch capture 当日 update_time 的最新版本）
  • 不可救回：同 pk 在两次 raw 跑批之间的"日内中间状态"——例如 10/10 02:00 状态 A → 10/10 05:00 状态 B → 10/11 02:00 状态 C，raw dt=09（10/10 03:00 跑）抓到 A，raw dt=10（10/11 03:00 跑）抓到 C，B 永久丢失。这是 T+1 batch 固有限制（只能 capture 跑批时刻 snapshot），要 capture B 必须上 CDC（见 §候选方案）

  如果没有 raw 宽窗 + ods 双源（即单日固定窗口 + 单源），会出现"幽灵更新"：

  设想某用户固定在每天凌晨 2 点 update 同一条记录 X：

  • raw dt=N 任务 N+1 凌晨 3 点跑批时，X 业务库 update_time 已经变成 N+1 02:00（被覆盖到次日）
  • 单日窗口 [N, N+1) 不覆盖 update_time=N+1 02:00 → raw dt=N 漏 X
  • 第二天 raw dt=N+1 任务 N+2 凌晨 3 点跑批时，X.update_time 又变成 N+2 02:00 → 单日窗口 [N+1, N+2) 又不覆盖 → 又漏
  • 每天都漏，X 永远捕捉不到，永远漂向后方

  宽窗（48h）+ 双源 union 配套解决幽灵更新：raw dt=N 任务窗口 [N, N+2) 抓到 X update_time=N+1 02:00 漂到 N+1 范围；ods 写 dt=N+1 时双源 union（raw dt=N + raw dt=N+1）把这条早版本归位到 ods dt=N+1 分区。

• 后果：

  • 正面：不漏漂移记录；raw 简单（只管多抓、不管分对）；ods 动态分区自动归位；同 id 多 dt 并存作为拉链表底层
  • 负面：raw 每日抓量约翻倍；ods SQL 必须统一动态分区写法 + 双源 union，开发规范需明文约束

• 候选方案：

  • 单日窗口 [day-start, day-stop) 固定区间（无 buffer）：业界小公司通用做法，本项目因漂移窗口 + 活跃度双放大否决
  • 动态 now 右界 [day-start, now)：可复现性、复跑、补数场景难处理，否决
  • 精确匹配漂移的半天 buffer [day-start, day+6h-stop)：和具体同步时刻耦合，调定时就得改窗口，否决
  • ods 跨 dt 按 (pk, max(update_time)) 去重：破坏拉链表基础，否决
  • ods 单源 raw dt=T-1（不 union raw dt=T-2）：业务覆盖式更新跨日漂移场景下，漏 update_time=T-1 的早期版本（业务库该记录 update_time 已被推到 T 范围，raw dt=T-1 抓到的 DATE=T 不入），拉链表轨迹断一节，否决（具体例子见 §决策"为什么双源 union 必要"）
  • ods INSERT INTO 追加 + 分区内去重（早先并列方案 B）：意图保留"每日 ods 跑时刻"的中间快照轨迹。但与"支持重跑"语义冲突（追加模式重跑会重复入数据），且方案 A 双源 union 已能完整捕获跨日漂移版本，方案 B 的"中间快照"价值不抵复杂度代价，否决
  • 源库 REPEATABLE READ snapshot isolation：业务库长事务风险，否决
  • CDC（PG 逻辑复制 / MySQL binlog 流读）：架构正路，需独立立项，本阶段不取（见 kb/12 CDC 演进节）

• 反悔条件：迁 CDC

ADR-04 DataX speed 三级注入（L1 conf / L2 ini / L3 CLI）

• 状态：草案 老代码 job_config_generator.py:60-67 把 speed 三参（channel / byte / record）按工作时段硬编码：07:50-19:00 走 channel=10 / byte=10MB / record=40k（保护业务 DB），其余时段走 channel=6 / byte=256MB / record=100k。时段边界和各档值完全写死在 Python 代码里，调优需要改代码 + 发布。压测 / 回填场景下 speed 是高频调参项，需要运行时覆盖能力。

• 决策：speed 三参走三级合并，优先级 L1 < L2 < L3。

  • L1 conf/datax-tuning.conf：项目级默认，承载宽松时段 relaxed_period.{start,stop} 边界 + strict/relaxed 两档各 3 个 speed 参值，共 8 个 key；时段配置用 HH:MM 字符串，代码解析为 HHMM 整数比较
  • L2 DataX ini 新增可选 [speed] 段：单 ini 级覆盖 channel / byte / record；一旦在 L2 显式写了，忽略时段判断直接使用
  • L3 CLI -channel / -byte / -record：本次运行级覆盖，bin/datax-{hive-import,hdfs-export}-starter.py 暴露，逐层透传到 dw_base.datax.cli gen-json 子进程，最终到 JobConfigGenerator
  • 合并发生在 JobConfigGenerator.assemble() 内存里，结果写进生成的 json（job.setting.speed + core.transport.channel.speed）；ini / conf 文件本身不动
  • 时段判断采用左闭右开 [start, stop)；每 key 的来源打印到 stdout 便于审计
  • schema 以宽松时段为基准（区间内 relaxed、区间外 strict）：原计划 strict_period 不工作——本项目业务高峰跨午夜（12:00 至次日 06:00），HHMM 整数比较 1200 ≤ x < 0600 为空集；宽松时段在低峰期（如 06:00-12:00）天然连续不跨日

• 后果：

  • 正面：压测 / 回填 speed 调参不用改代码；时段分档逻辑可配，业务高峰期调整不用发布；单 ini 特殊场景可用 L2 覆盖；ADR 级改动只加约 350 行代码 + 10 条单测
  • 负面：参数语义复杂度上升（3 层合并规则）——通过 [tuning] log 逐层打印缓解；conf/datax-tuning.conf 是新文件需同步到所有 worker（sync-all.sh 已覆盖）

• 候选方案：

  • 只做 L1（conf 外配，不要 L2 L3）——否决，压测高频调 speed 不想改 conf 再部署
  • 参数全外配（speed + reader.fetchSize + writer.batchSize）——否决，fetchSize/batchSize 低频调，现有 ini 覆盖硬编码 够用，外配反而复杂
  • CLI 用合成 flag --datax-conf key=value,...——否决，speed 高频用独立 flag 更直观，Spark 入口风格参考

• 反悔条件：三级注入使用场景长期 <5%（即 L2 L3 基本不用），退回单层 conf；或者 DataX 被替换

ADR-05 DWD 事实表设计：默认"事件 vs 状态"拆派组合，acc 累积快照仅留例外口子

• 状态：已采纳

老 kb/20 §5.5 走"合 vs 拆"二分法（粒度相同则合粒度不同则拆），举例订单履约 / 拼团生命周期均"合到 acc 累积快照"——一行一实体，每个里程碑一列时间戳，状态单向推进。该写法属 Kimball 维度建模理论里的 Accumulating Snapshot Fact Table，在传统数仓（Teradata / Oracle / Greenplum）里是经典模式。

2026-04-26 启动埋点 + 业务库接入业务建模时重新审视，发现两个核心问题：

1. Hive 技术栈不友好：Hive ORC 普通表不支持原生 UPDATE，acc 模式（每经过里程碑回写时间戳列）只能"INSERT OVERWRITE 整张表 / 整个分区"实现，每天扫近 N 天 ODS 重算，写入开销大、性能粗暴。要解此约束需开 Hive ACID（CDH 6 支持但少用 + 性能折损）或上 Iceberg / Hudi / Delta Lake，本项目都不具备
2. 业务流程多有循环：拼团有审核机制（提交 → 拒绝 → 重新提交 → 再审核），订单亦有退款 / 重派单等循环。Kimball 对 acc 的前提是"每个状态只经过一次"——循环场景 acc 的时间戳列会丢失历史，不适用

期间在 inbox 收了一篇分层分区语义草稿，主张"事实表只承载事件、状态归 DIM 拉链"。讨论后认为该结论方向正确，但论证过度（直接否定 Kimball 三类事实表的全部）；最终采纳折中表述：默认拆派 + 留 acc 例外口子。

• 决策：默认采用"事件 vs 状态"拆派组合：

  • DWD 事实表只承载业务事件（不可变事实），命名 dwd_{域}_{业务过程}_apd_d，append-only，业务时间分区
  • 实体当前状态进 DIM 拉链表，命名 dim_{域}_{实体}_zip_d，SCD Type 2 每次状态变更生成新行
  • 循环状态机天然支持：事件流水任意次重复追加，DIM 拉链每次变更生成新行可完整回溯
  • acc 不一刀切禁用：极少数严格不循环、固定线性里程碑场景（如不可逆的合同审批流程）按需评估，新建 acc 表时在 PR / 设计稿里说明选型理由

• 后果：

  • 正面：
  • 与 Hive 列存"只追加 + 分区"模型天然契合，不需要 UPDATE
  • 状态查询走拉链表 is_current 切片或按 dt 切片，直观
  • 循环 / 单向状态机统一同一套建模，降低团队心智负担
  • 与阿里 OneData / 字节 / 美团 Hive 数仓主流做法对齐
  • 负面：
  • 跨表 JOIN（"下单数 - 退单数 = 实际下单数"）成为常态，但维度建模本就支持
  • DIM 拉链表实现复杂度高于 acc 单表（每日变更 pk 检测 + 原行 end_date 置昨天 + 新行 insert）
  • 状态查询需要 join dim 拉链而非读单表，少量查询复杂度

• 候选方案：

  • 保留老 §5.5 合派 acc：经典 Kimball 但不适合 Hive 技术栈 + 不支持循环——否决
  • 完全禁用 acc：inbox 草稿原版主张"事实表出现需要更新状态就是建模错"——过度扩大化，放弃了 Kimball 三类事实表的理论丰富性，未来引擎栈升级（Iceberg / Hudi）想用 acc 又得反悔——否决，留例外口子
  • inc 主表 + apd 流水表 fallback（kb/21 §2.2 老循环 fallback 方案）：inc 只保留最新状态，状态历史靠 apd 流水还原，但状态查询要 join 流水表算最新值，远不如拉链表 is_current 直接——否决

• 反悔条件：

  • 引擎栈升级到支持高效 UPDATE 的存储（Iceberg / Hudi / Delta Lake），acc 实现成本 / 性能不再是问题，可重新评估
  • DIM 拉链表实现复杂度成为团队瓶颈（开发提效需要）
  • 实际场景中跨表 JOIN 性能 / 维护成本超出预期

ADR-06 DDL 生成器 raw + ods 双层方案（raw ✅ 2026-04-29，ods 待实施）

• 状态：草案

raw / ods 表 DDL 长期手写（参考 sync ini column 列表 + 类型映射）易错且重复——80+ 字段表抄一遍 PG schema 已经痛苦，未来 50 张业务表 × 2 层（raw + ods）无法维护。需要工具自动出 DDL，开发者只做表注释 / LOCATION / 字段注释微调。

• 决策：

  • 新建 bin/hive-ddl-gen.py 一脚本两层产出（独立于 datax-sync-template-gen.py，单脚本一职责）
  • 命令 python3 bin/hive-ddl-gen.py -l {raw|ods} -ini <sync.ini path> [-o [DIR]]
  • 必须显式 -l 指定层级——避免 raw / ods 误生成；不做"同时生成两层"
  • raw 层（本轮范围）：
  • 输入：裁剪后 sync.ini（reader.column 已是入仓字段集）
  • 复用 datax-sync-template-gen.py 的 resolve_datasource + query_columns_full 拿字段中文注释 + PG 类型
  • 输出：全字段 STRING + dt STRING 分区 + ORC + LOCATION 从 ini writer.path 推
  • 头注释自己生成 placeholder（作者 / 工单 / 状态 / 配套 ini 路径），不解析 ini 头
  • ods 层（暂未实施）：
  • 输入：sync.ini + 类型映射 conf
  • 类型映射 conf 落 conf/pg-to-hive-type.ini，PG type → Hive type 规则（参考 kb/20 §8.4.1）
  • 输出：typed 字段 + dt STRING 分区 + 技术字段（etl_time / src_sys / src_tbl）+ ORC
  • numeric(p,s) 是否保留原精度还是统一 DECIMAL(20,4)：实施时拍板
  • mask conf 中字段类型可能因脱敏方法变化（如 month_trunc 时间 → STRING），实施时考虑
  • -l ods 在 ods 实施前报"未实现"

• 后果：

  • 正面：手写 DDL 工作量从 80+ 行降到 < 10 行微调；新表入仓周期缩短；字段中文注释从 PG pg_description 自动取，避免手抄漏
  • 负面：工具复杂度 + 单测成本；ods 类型映射 conf 维护（极端类型可能需要个例处理）

• 候选方案：

  • 维持手写 DDL：80+ 字段表手抄成本不可接受——否决
  • 合并到 datax-sync-template-gen.py 加 --ddl raw/ods flag：单脚本多产物耦合度高，sync 模板 vs DDL 两件事语义不同——否决，独立脚本
  • DDL 同时生成 raw + ods：两层语义不同（raw 全 STRING / ods typed），合一会引入复杂分支逻辑——否决，分两次跑

• 反悔条件：

  • 业务表数稳定 < 5 张永远不再加：手写也能撑，工具失去 ROI
  • 引擎换非 Hive（Doris / ClickHouse），DDL 生成需重写

ADR-07 数据质量配置化方案（mask conf 双消费 + dq 注册表）

• 状态：草案

raw / ods 入仓后需要监控两类质量问题：(a) PG 业务库 schema 变更（新增 / 删除字段）没及时通知数仓 → 字段悄悄漏入或老字段入仓后失效；(b) PG vs Hive 行数不一致 → 同步任务可能漏抓数据。当前依赖人工巡检不可持续。merchant_open 是 schema drift 实例：PG 业务库有此字段，分析师库没同步过来，本次 generator 跑出来才发现——证明流程缺失，需 dq 任务补齐。

• 决策：

一、复用 mask conf 作 schema drift 探查的 ground truth

jobs/raw/{域}/{table}.mask.ini 是单一真值——sync 生成器和 dq 模块双消费：

• sync 生成器：读 mask conf 出几乎可用 ini（已实施，见 ADR-06 / sync 脚本 -mask-conf）
• dq 模块：读 mask conf trim 字段集 + ini reader.column 保留集 = "数仓已知字段全集"，与 PG 实时字段集做差，差非空 → schema drift 告警

二、注册表机制

conf/dq.ini 列出需 dq 任务的表：

  [card_group_order_info]
  domain = trd
  sync_ini = jobs/raw/trd/raw_trd_card_group_order_info_inc_d.ini
  mask_conf = jobs/raw/trd/raw_trd_card_group_order_info_inc_d.mask.ini
  count_threshold = 0.01

dq 任务 daily 跑：遍历注册表 → 每张表跑两类检查 → 异常推 alerter。

三、检查类型

1. Schema drift 探查：

   • 拿 PG 实时字段集（pg_catalog 查询）
   • 拿数仓已知字段集（mask conf trim ∪ ini reader.column）
   • 对称差非空 → alerter 推 "新增 [...] / 已删 [...]"
   • 数仓 review → 决策（保留 / trim / 脱敏）→ 更新 mask conf + sync ini + DDL + kb/24

2. 数据量比对：

   • PG count(*) WHERE update_time ∈ [day-start, day+1-stop)
   • Hive count(*) WHERE dt='{业务日}'
   • 差额 / PG 总量 > count_threshold → alerter
   • raw 48h 宽窗机制下两边可能略偏，阈值容忍

四、实现归属

• dw_base/dq/（kb/92 已建空骨架）
• 子模块：schema_drift.py + count_check.py + runner.py（读 conf/dq.ini 调度）
• 入口：bin/dq-runner.py 命令行 / DS 调度

• 复用 datax-sync-template-gen.py 的 resolve_datasource + query_columns_full + pg8000

• 后果：

  • 正面：流程缺失（schema drift / 行数差）由 dq 任务补齐，不再依赖人工巡检；mask conf 单一真值消除"裁剪记录散落 ini + kb 双写"
  • 负面：dq 任务上线前需稳定 mask conf 格式（已在 ADR 锁定）；告警阈值需调试期摸合理值

• 候选方案：

  • 不做 dq，靠人工巡检：表数 ≥ 10 张后撑不住——本阶段（< 5 张）允许暂缓但不否决
  • 用现成开源 dq 工具（Great Expectations / Apache Griffin 等）：本项目数据量 / 表数不需要重型框架，自己写薄壳更可控——否决重型工具
  • mask conf 不复用，dq 单独维护字段清单：双写 ground truth 易漂移——否决，复用 mask conf

• 反悔条件：

  • dq 任务范围扩大到字段值校验 / 维度一致性 / 业务规则等复杂检查，自研薄壳吃不下，迁 Apache Griffin
  • mask conf 格式本身需要重大调整，dq 模块可能要解耦自己维护

• 实施节奏：表数 ≥ 5 张时启动；< 5 张靠人工巡检 + 偶尔重跑 sync 生成器 diff。