docs(kb): 93 加 ADR-06 DDL 生成器 + ADR-07 数据质量配置化（草案）

kb/93-架构决策.md

@@ -192,3 +192,109 @@
   - 引擎栈升级到支持高效 UPDATE 的存储（Iceberg / Hudi / Delta Lake），acc 实现成本 / 性能不再是问题，可重新评估
   - DIM 拉链表实现复杂度成为团队瓶颈（开发提效需要）
   - 实际场景中跨表 JOIN 性能 / 维护成本超出预期
+
+### ADR-06 DDL 生成器 raw + ods 双层方案（raw 已实施待补，ods 待实施）
+
+- **状态**：草案
+
+  raw / ods 表 DDL 长期手写（参考 sync ini column 列表 + 类型映射）易错且重复——80+ 字段表抄一遍 PG schema 已经痛苦，未来 50 张业务表 × 2 层（raw + ods）无法维护。需要工具自动出 DDL，开发者只做表注释 / LOCATION / 字段注释微调。
+
+- **决策**：
+
+  - 新建 `bin/datax-ddl-gen.py` 一脚本两层产出（独立于 `datax-sync-template-gen.py`，单脚本一职责）
+  - 命令 `python3 bin/datax-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 任务的表：
+
+  ```ini
+  [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。