# raw 层接入流程

> 新业务库表（PG）入数仓 raw 层的标准流程。**生成 → 评审 → 配置裁剪脱敏 → 落地 → 文档化**一条线，由 sync 生成器 + DDL 生成器 + mask 配置三件协同。

## 流程总览

```
┌──────────────────┐
│ Step 1：跑 sync   │ 不带 -mask-conf
│ 生成器（初版）    │ → workspace 全字段 ini + md
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 2：业务+数仓 │ 字段评审：哪些不入仓 / 哪些脱敏
│ 评审字段          │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 3：写 mask   │ jobs/raw/{域}/{table}.mask.ini
│ 配置              │ 参考 conf/templates/datax/mask/
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 4：跑 sync   │ 带 -mask-conf
│ 生成器（终版）    │ → workspace 几乎可用 ini + md（留档）
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 5：微调 ini   │ → jobs/raw/{域}/{table}.ini
│ + 提交            │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 6：md 同步   │ 字段表复制到 kb/24-raw 建模.md 对应章节
│ 到建模文档        │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 7：跑 DDL    │ -l raw -ini xxx.ini
│ 生成器 + 微调     │ → manual/ddl/raw/{域}/{table}_create.sql
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Step 8：PR 提交   │ 四件套：mask.ini + sync.ini + DDL + kb/24 章节
│ 四件套            │
└──────────────────┘
```

## 8 步详解

### Step 1：生成全字段初版

```
python3 bin/datax-sync-template-gen.py \
  -ds postgresql/{env}-{instance} \
  -t public.{table_name} \
  -o
```

输出 `workspace/{yyyymmdd}/{table_name}.ini` + `.md`：

- **md 头部探查段**（每次跑都做）：行数估值（`pg_class.reltuples`）、锚点字段 `create_time` / `update_time` 存在性 + 抽样非空率（`TABLESAMPLE SYSTEM(1) LIMIT 1000`）、软删字段命中（`del` 子串，含噪声待人工筛）
- **md 字段表**：全字段无裁剪，脱敏类型列空白
- **ini**：全字段，无 `[mask]` 段

### Step 2：业务方 + 数仓评审字段

会议 + 字段表对照，确定每个字段：

- **不入仓**（trim）：PII / 三方凭证 / 业务库内部技术字段 / 业务冗余等
- **脱敏入仓**（mask_middle / md5 / month_trunc 等）：保留字段但敏感值不出业务库
- **保留**：默认入仓

同时基于 md 探查段评审：

- **锚点字段维护质量**：`update_time` 抽样非空率 < 95% → 业务方需补维护或换锚点（如改用 `create_time`、改全量同步）
- **软删字段命名**：含噪声命中（如 `delivery_end_time` 中"del"误命中）人工筛除，确认主软删字段名；多张表命名不一致时（`del_flag` vs `del_flg`）推动后端统一
- **隐性裁字段**：PG 业务库有 / 分析师库 inbox 草稿无的字段（在 mask.ini 注释里标出）找业务库后端对账是否入仓

输出：会议纪要里逐字段决策。

### Step 3：写 mask 配置

落位 `jobs/raw/{域}/{table}.mask.ini`，参考 `conf/templates/datax/mask/mask.template.ini` 格式。

```ini
[mask]
# field = method
field1 = trim
field2 = mask_middle
field3 = md5
```

### Step 4：跑 sync 生成器（终版）

```
python3 bin/datax-sync-template-gen.py \
  -ds postgresql/{env}-{instance} \
  -t public.{table_name} \
  -mask-conf jobs/raw/{域}/{table_name}.mask.ini \
  -o
```

输出：

- `workspace/{yyyymmdd}/{table_name}.ini` —— reader.column 已剔除 trim 字段，[mask] 段已渲染
- `workspace/{yyyymmdd}/{table_name}.md` —— 脱敏类型列已填

留档不动 workspace 版本。

### Step 5：微调 + 提交 sync.ini

复制 workspace ini → `jobs/raw/{域}/{table_name}.ini`，**手动微调**：

- 头注释（作者 / 工单号 / 状态 / 配套 DDL 路径）
- writer.path 表名后缀（`_inc_d` / `_his_o` 等，按业务实际）
- writer.fileName 同上
- writer.dataSource（hdfs ref，按目标 HDFS 集群）
- splitPk（auto-detect 不准时手调）
- where（如非 update_time 锚点改字段）
- fetchSize / 其他细节

不限于补注释——**根据实际情况调**。

### Step 6：md 同步到 raw 建模文档

复制 workspace `.md` 字段表 → `kb/24-raw 建模.md` 对应表章节。**人工维护**——后期 raw 建模文档由人类驱动更新，不做脚本自动追加。

### Step 7：跑 DDL 生成器 + 微调

```
python3 bin/hive-ddl-gen.py -l raw -ini jobs/raw/{域}/{table_name}.ini -o
```

> **注**：DDL 生成器 ods 阶段暂未实现，本流程当前只覆盖 raw。

输出 `workspace/{yyyymmdd}/{table_name}_create.sql`，复制 → `manual/ddl/raw/{域}/{table_name}_create.sql`，手动微调（表注释 / 字段注释完善 / LOCATION 路径核实）。

### Step 8：PR 提交四件套

一次 PR 包含：

- `jobs/raw/{域}/{table_name}.mask.ini`（裁剪脱敏配置）
- `jobs/raw/{域}/{table_name}.ini`（sync 配置）
- `manual/ddl/raw/{域}/{table_name}_create.sql`（raw 建表 DDL）
- `kb/24-raw 建模.md` 对应表章节（字段三态决策文档化）

## 暂未实现的阶段（后期）

按 kb/93 ADR 决策推进：

- **ods DDL 生成**（ADR-06）：DDL 生成器加 `-l ods` 支持，类型映射 conf 驱动 + 技术字段（`etl_time` / `src_sys` / `src_tbl`）
- **数据质量任务**（ADR-07）：注册 `conf/dq.ini` 的表自动跑 schema 变更探查（mask conf 作 ground truth）+ 数据量比对（PG vs Hive count + 阈值告警）