docs(kb): 加 25-raw 接入流程 + mask 配置模板

README.md

@@ -87,6 +87,7 @@ PG/ES ──DataX(raw)──> RAW ──> ODS ──> DWD ──> DWS ──> TD
 | [22-指标体系](kb/22-指标体系.md) | **指标字典**：指标 / 维度 / 度量定义与口径 |
 | [23-标签体系](kb/23-标签体系.md) | **TDM 画像**：用户 / 商品 / 商家标签 |
 | [24-raw 建模](kb/24-raw建模.md) | **raw 层字段裁剪决策**：各 raw 表三态标记（保留 / 明性裁 / 隐性裁）+ 决策理由溯源 |
+| [25-raw 接入流程](kb/25-raw接入流程.md) | **新表入仓标准 8 步**：sync 生成器 + mask 配置 + DDL 生成器 + raw 建模文档协同 |
 
 ### 3x 开发流程
 

conf/templates/datax/mask/mask.template.ini

@@ -0,0 +1,27 @@
+# DataX sync 配置的脱敏配置模板
+# 落位：jobs/raw/{域}/{table}.mask.ini（与 sync.ini 同级一对一）
+#
+# 用途（双消费）：
+#   1. sync 生成器（bin/datax-sync-template-gen.py --mask-conf）
+#      → 生成几乎可用 ini：trim 字段从 reader.column 剔除（保持 PG 原顺序）；
+#                          其他 method 渲染 [mask] 段供 DataX reader 端脱敏
+#      → md 脱敏类型列填好（kb/24 raw 建模文档手动同步）
+#   2. 数据质量模块（后期实现）→ schema 变更探查 ground truth
+
+[mask]
+# 格式：{field} = {method}
+# method ∈ trim / md5 / month_trunc / mask_middle / keep_first_n / keep_last_n
+#
+# - trim         字段不入 raw（reader column 不查询）
+# - md5          字段保留，值替换为 md5 hash
+# - month_trunc  时间字段保留，截断到月（脱敏到日精度）
+# - mask_middle  字符串保留，中间用 * 脱敏
+# - keep_first_n 字符串保留前 n 字符（n 可配置，如 keep_first_2）
+# - keep_last_n  字符串保留后 n 字符
+#
+# 例：
+# payment_num = trim          ; 三方支付流水号，不入仓
+# shipping_address = trim     ; PII 地址，不入仓
+# receiver_name = mask_middle ; 收件人姓名，中间脱敏
+# receiver_phone = trim       ; 手机号，不入仓
+# bank_account = md5          ; 银行账号，hash

kb/25-raw接入流程.md

@@ -0,0 +1,150 @@
+# 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 + 阈值告警）