团队建模规范

适用范围：所有数据开发、数仓工程师、数据产品经理
核心原则：上游稳定，下游灵活；分层解耦，按需演进

一、整体架构与分层职责

📌 依赖方向：
DWD → DWS / DWT
DWS → DWT_enhanced
DWD/DWS/DWT → ADS
禁止循环依赖！

二、命名规范

三、字段设计规范

⚠️ Array 存 ID，不存 name！
✅ 预计算常用标志位：is_valid = ARRAY_CONTAINS(tag_codes, 'valid')

四、码值管理规范（必须遵守）

1. 禁止直接使用业务系统 UUID 或原始码值

• UUID 可读性差、性能差、无法跨系统统一

2. 必须使用数仓标准码值体系

• 维度表：realtime_dim.dim_status（含 status_id, status_code, status_name）
• 映射表：realtime_dim.dim_code_mapping（桥接业务系统 → 数仓码值）

3. DWD 层必须完成码值转换

-- 正确示例
SELECT 
  map.target_code_id AS status_id,
  map.target_code_value AS status_code
FROM ods_table o
JOIN dim_code_mapping map 
  ON map.source_system = 'crm'
  AND map.source_code_type = 'contact_status'
  AND map.source_code_value = o.status_uuid;

-- 正确示例
SELECT 
  map.target_code_id AS status_id,
  map.target_code_value AS status_code
FROM ods_table o
JOIN dim_code_mapping map 
  ON map.source_system = 'crm'
  AND map.source_code_type = 'contact_status'
  AND map.source_code_value = o.status_uuid;

4. ADS 层可直接使用中文名

SELECT s.status_name 
FROM dwd_table d
JOIN dim_status s ON d.status_id = s.status_id;

SELECT s.status_name 
FROM dwd_table d
JOIN dim_status s ON d.status_id = s.status_id;

五、数据安全与合规

✅ 所有脱敏规则必须在《清洗规则表.xlsx》中明确定义

六、演进型建模机制

场景：需新增群体特征（如“所在省高潜企业密度”）

正确路径：

1. 保持基础 DWT 不变：dwt_company_profile
2. 新增 DWS 聚合：dws_province_high_potential_summary
3. 创建增强 DWT：dwt_company_profile_enhanced
4. ADS 引用新特征：ads_sales_company_list

禁止行为：

• 直接修改原 DWT 表
• 让 DWS 依赖 DWT_enhanced（造成循环）
• 未评估影响就上线变更

📎 变更必须填写《模型变更影响评估表.xlsx》，走灰度上线流程

七、ADS 出口控制（红线！）

• 所有业务查询、报表、导出、API 必须通过 ADS 层
• 禁止任何应用直连 DWD/DWS/DWT/ODS
• ADS 表必须：
  • 拍平 Array：ARRAY_TO_STRING(source_codes, ',')
  • 格式化字段：is_valid=1 → '有效'
  • 宽表设计：JOIN 多层数据，一次查询满足需求

八、配套工具与交付物

九、口诀（新人必背）

DWD建模要扁平，Array存ID别存名；
DWS聚合要轻量，DWT画像要稳定；
基础画像保稳定，群体特征另建表；
依赖链路要单向，演进不乱靠分层；
ADS出口唯一门，新人照做不出错！

📌 本规范为团队强制标准，所有数仓模型开发必须遵守。
违反规范将导致模型无法上线、数据口径混乱、维护成本飙升。