# 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 脱敏类型列空白。

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

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

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

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

### 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/datax-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 + 阈值告警）