# Databricks SQL 重构规范

## 1. 范围和原则

本规范适用于 CHPA Databricks 数仓脚本。第一阶段目标是在不改变业务结果的前提下提高可维护性。

- 先保持业务口径，再做性能优化。
- 每个脚本只负责一个主要目标表。
- 文件头声明源表、目标表、数据粒度、写入方式和依赖。
- 持久化写入必须显式列出目标列和查询列，禁止使用 `SELECT *`。
- 逻辑重构与生产表改名分开实施。
- 为行数、唯一性、非空约束和未匹配记录建立验证查询或任务检查。

## 2. 文件和目录命名

目录结构统一为：

```text
sql/<业务域>/<阶段>/<序号>_<目标表>.sql
```

规则：

- 目录和文件名使用小写 snake_case。
- 路径和文件名不使用空格。
- 使用两位序号明确 notebook/job 的执行顺序。
- 一个脚本只写入一个主要持久化目标。像 `01 dwd_update.sql` 这种多目标脚本，应按目标表和职责拆分。

示例：

```text
sql/chpa/01_dwd/01_dwd_ims_atc_hierarchy.sql
```

## 3. 物理表命名

新表使用以下格式：

```text
[<catalog>.]<分层_schema>.<来源系统>_<对象类型>_<业务实体>[_<限定词>]
```

未启用 Unity Catalog 或依赖默认 catalog 时可以省略 catalog。分层已经由 schema 表达，表名不再重复 `dwd`、`dws` 或 `dm`。

- 来源系统：如 `ims`、`gnd`、`pharbers`。
- 对象类型：`td` 表示维度/主数据，`tf` 表示事实数据。
- 业务实体：使用稳定的业务名词，如 `atc_hierarchy`、`pack_property`。
- 限定词：按需表达粒度或变体，如 `monthly`、`province`。

`01` 组表名建议：

| 现有物理表名 | 推荐规范表名 | 首批处理方式 |
| --- | --- | --- |
| `dwd.dwd_ims_atc_hierarchy` | `dwd.ims_td_atc_hierarchy` | 保留现名 |
| `dwd.dwd_ims_nfc_hierarchy` | `dwd.ims_td_nfc_hierarchy` | 保留现名 |
| `dwd.dwd_ims_td_manufacturer_corp` | `dwd.ims_td_manufacturer_corporation` | 后续 review |
| `dwd.dwd_ims_td_pack_property` | `dwd.ims_td_pack_property` | 后续 review |
| `dwd.dwd_gnd_pharbers_prov_fact` | `dwd.pharbers_tf_province_sales` | 先确认业务粒度 |

推荐迁移顺序：

1. 创建规范名称的新表，并用兼容视图暴露旧表名。
2. 新旧表并行运行，对比数据结果。
3. 在一次受控发布中修改全部下游引用。
4. 所有消费者迁移后再移除旧名称兼容视图。

## 4. 字段命名

- 新字段使用小写 snake_case。
- 标识使用 `_id`，业务编码使用 `_code`，名称或描述使用 `_name`、`_description`。
- 日期时间后缀按真实类型使用 `_date`、`_timestamp` 或 `_at`。
- `atc`、`nfc`、`prod`、`pack` 等已形成业务共识或受输出契约约束的缩写可以保留。
- 纯逻辑重构中不直接修改持久化输出字段名。

## 5. SQL 结构和格式

脚本统一按以下顺序组织：

1. Databricks notebook 标记和脚本契约头。
2. 带显式目标列的 `INSERT OVERWRITE`。
3. 源数据标准化 CTE。
4. 业务规则 CTE。
5. 按目标表字段顺序显式编写最终 `SELECT`。

格式规则：

- SQL 关键字使用大写。
- CTE 和别名使用小写 snake_case。
- 使用四个空格缩进。
- `SELECT` 每行一个字段。
- 每个 JOIN 条件单独成行。
- 使用 `atc_level_1` 等有业务意义的别名，维护代码中不使用 `t1`、`a` 等无语义别名。
- 同一作用域出现多个关系时，所有字段都带关系限定符。

## 6. 写入和数据质量规则

- 只有可确定性重跑的全量任务可以使用 `INSERT OVERWRITE`。
- 不在一个脚本中混合无关的 `UPDATE` 和目标表构建逻辑。
- 编码补零等标准化逻辑集中到一个明确的处理阶段，避免在多个任务中重复表达式。
- 每个脚本必须声明预期目标粒度。
- 最少验证以下指标：
  - 新结果与旧结果的总行数；
  - 声明业务键的重复数；
  - 必填键的空值数；
  - 层级关联新增的未匹配记录数。

## 7. 首批兼容说明

ATC 和 NFC 脚本原样保留以下父级编码规则：

- ATC 2 级关联 1 级：取前 1 位。
- ATC 3 级关联 2 级：取前 3 位。
- ATC 4 级关联 3 级：取前 4 位。
- NFC 2 级关联 1 级：取前 1 位。
- NFC 3 级关联 2 级：取前 2 位。

任何口径简化都应先用生产样本验证这些规则。

首批上线前运行 `validation/chpa/01_dwd/validate_hierarchy_refactor.sql`。新旧双向差集必须为 0，行数必须一致；重复路径和未匹配层级作为业务 review 指标记录，不在未确认阈值前自动判定失败。