REFACTOR-MA/docs/sql_refactoring_standard.md

Databricks SQL 重构规范

1. 范围和原则

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

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

2. 文件和目录命名

目录结构统一为：

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

规则：

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

示例：

sql/chpa/01_dwd/01_dwd_ims_atc_hierarchy.sql

3. 物理表命名

新表使用以下格式：

[<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 指标记录，不在未确认阈值前自动判定失败。