# 数仓命名规范

> 本文档是 `poyee-data-warehouse` 数据仓库的命名权威规范。所有建表、字段、文件、目录命名必须遵循本规范。
> 开发手册与 code review 的参考依据。

## 1. 核心原则

- 全部 `snake_case`，全小写，单词之间用下划线
- 全英文，禁止拼音（除约定俗成的专有名词如 `tid`、`sku`）
- 表名、字段名长度 ≤ 30 字符
- **优先级**：行业通用缩写（gmv/dau/uv）> 技术术语词根（agg/cnt/sum）> 业务术语词根
- 一个词根（root word）对应一个语义，不允许同义多词（例如 `cnt` 表计数，就不再用 `num`/`count`）

## 2. 公共组件

以下组件被各层命名规则共享引用。

### 2.1 Domain（业务域代码）

| 代码 | 中文 | 说明 |
|------|------|------|
| `trd` | 交易域 | 订单、支付、退款、购物车、拼团 |
| `usr` | 用户域 | 用户注册、登录、画像、会员、行为埋点 |
| `prd` | 商品域 | 商品、SKU、SPU、价格 |
| `shp` | 店铺域 | 店铺、商家 |
| `pub` | 公共域 | 平台、日历、地理等公共数据 |

### 2.2 Snapshot Type（快照类型）

| 代码 | 含义 | 使用场景 |
|------|------|---------|
| `inc` | 增量快照 | 数据创建后会变更（订单状态、用户信息） |
| `ful` | 全量快照 | 每次重刷全表（维度表的日常同步） |
| `apd` | 追加（append） | 数据创建后不再变更（埋点日志、交易流水） |
| `zip` | 拉链表（SCD Type 2） | 属性**可反复无规律变更**的实体（用户改地址、改手机号、改会员等级），用 `start_date` / `end_date` 追踪每次变更 |
| `acc` | 累积快照（Accumulating Snapshot） | 有**固定生命周期里程碑**的实体（拼团：发起→成团→失败/过期；订单：下单→支付→发货→签收），每个里程碑对应一列时间戳，状态单向推进 |
| `his` | 一次性历史快照 | 历史数据回刷、vendor 单批交付，导入后**永不更新、永不调度**；周期段固定写 `o` |

**zip vs acc 选择依据：**

> **acc** 适用于实体状态按**固定路径单向推进**的场景（如拼团的生命周期），里程碑是可枚举的，每个阶段填一列时间戳，填完不改。
> **zip** 适用于实体属性**可反复、无规律变更**的场景（如用户改手机号），无法预知变更次数和内容，需要用 `start_date` / `end_date` 记录每个历史版本。

**inc vs apd 判断依据：** 数据产生后还会不会变。会变 → `inc`；不会变 → `apd`。
>
> 一句话：**状态机用 acc，属性变更用 zip。**
>
> **acc 的前提条件**：同一个实体的同一个状态**只会经过一次**（每个里程碑时间戳列只写入一次，不会被覆盖）。如果业务流程存在**循环**（如审核不通过→重新提交→再审核），同一个状态会经过多次，此时 acc 的时间戳列会丢失历史。**循环场景的做法**：主表用 `inc`（保留当前状态 + 最终里程碑时间），另建一张状态流水表用 `apd`（每次状态变更追加一行，不丢历史）。

### 2.3 Refresh Cycle（刷新周期）

| 代码 | 含义 |
|------|------|
| `r` | realtime 实时 |
| `h` | hourly 小时 |
| `d` | daily 日 |
| `w` | weekly 周 |
| `m` | monthly 月 |
| `q` | quarterly 季 |
| `y` | yearly 年 |
| `o` | once 一次性 |

### 2.4 DWS 时间窗口后缀

dws 层使用时间窗口后缀替代 `{快照类型}_{刷新周期}` 二段（详见 §3.6）。

**聚合粒度（单个周期内的汇总）：**

| 代码 | 含义 |
|------|------|
| `1d` | 单日汇总 |
| `1w` | 单周汇总 |
| `1m` | 单月汇总 |
| `1q` | 单季汇总 |
| `1y` | 单年汇总 |

**滑动窗口（回看最近 n 天）：**

| 代码 | 含义 |
|------|------|
| `7d` / `30d` / `90d` / `nd` | 最近 n 天滑动窗口 |

**累计：**

| 代码 | 含义 |
|------|------|
| `td` | to date，历史至今累计 |

> 注意：`wtd`（本周至今）、`mtd`（本月至今）、`ytd`（本年至今）等**自然周期截断汇总不单独建表**，在 ads 层从 `_1w` / `_1m` 基础数据按需计算。

---

## 3. 各层命名规则

各层表名结构不同，以下逐层说明。

### 3.1 raw 层

```
raw_{域}_{源表名}_{快照类型}_{周期}
```

- `{源表名}`：保留数据源原始表名（snake_case 化），保持与源端的可追溯性
- 快照类型通常为 `inc`（CDC 增量）或 `his`（一次性历史导入）
- raw 层全字段 STRING，不做类型转换

| 示例 | 说明 |
|------|------|
| `raw_trd_order_info_inc_d` | 交易域，源表 order_info，增量，日 |
| `raw_trd_legacy_order_his_o` | 交易域，历史订单 CSV 一次性导入 |

### 3.2 ods 层

```
ods_{域}_{源表名}_{快照类型}_{周期}
```

- 表名结构与 raw 层一致，`{源表名}` 保留数据源原始表名
- ods 做的事：类型转换、空值处理、脏数据标记，但**不改表名**，保持与 raw / 源端的对应关系

| 示例 | 说明 |
|------|------|
| `ods_trd_order_info_inc_d` | 交易域，源表 order_info，增量，日 |
| `ods_prd_product_ful_d` | 商品域，源表 product，全量，日 |
| `ods_prd_category_ful_d` | 商品域，源表 category，全量，日 |

### 3.3 dim 层

```
dim_{域}_{实体}_{快照类型}_{周期}
```

- `{实体}`：维度实体名，来自多张源表宽表化后的统一命名（不再是源表名）
- 快照类型通常为 `ful`（默认）或 `zip`（需要回溯属性变更历史时）
- dim 直接从 ods 构建，不经过 dwd

| 示例 | 说明 |
|------|------|
| `dim_prd_product_ful_d` | 商品维表，每日全量快照 |
| `dim_prd_sku_ful_d` | SKU 维表（与商品一对多，独立粒度） |
| `dim_usr_user_zip_d` | 用户维表，拉链表（需追溯地址/等级变更） |
| `dim_pub_calendar_ful_o` | 日历维表，一次性全量 |

### 3.4 dwd 层

```
dwd_{域}_{业务过程}_{快照类型}_{周期}
```

- `{业务过程}`：用业务术语词根描述（见 §5），如 `order_pay`、`group_buy`、`page_view`
- 快照类型根据业务性质选择：

| 业务性质 | 快照类型 | 示例 |
|---------|---------|------|
| 不可变事件（埋点、流水） | `apd` | `dwd_usr_page_view_apd_d` |
| 有生命周期里程碑的实体（拼团、订单） | `acc` | `dwd_trd_group_buy_acc_d` |
| 有变更但无固定里程碑 | `inc` | `dwd_trd_order_detail_inc_d` |

| 示例 | 说明 |
|------|------|
| `dwd_trd_group_buy_acc_d` | 拼团明细，累积快照（里程碑：发起/成团/失败/过期） |
| `dwd_trd_order_pay_inc_d` | 订单支付明细，增量 |
| `dwd_usr_page_view_apd_d` | 页面浏览明细，追加 |
| `dwd_usr_click_apd_d` | 点击明细，追加 |

### 3.5 dws 层

```
dws_{域}_{实体}_{主题}_{时间窗口}
```

dws 层使用**时间窗口后缀**替代五段式的 `{快照类型}_{周期}` 二段，因为 dws 的快照语义与聚合窗口天然绑定，合并表达更清晰。

- `{实体}`：聚合维度（user / product / shop）
- `{主题}`：聚合的业务主题（trade / action / group_buy）
- `{时间窗口}`：见 §2.4，常用 `1d` / `7d` / `30d` / `td`

> dws 只提供**原子粒度的聚合**（日/周/月/累计），当年周累计、当月周累计等组合窗口在 ads 层按需计算，**不在 dws 单独建表**。

| 示例 | 说明 |
|------|------|
| `dws_usr_user_trade_1d` | 用户交易日汇总 |
| `dws_usr_user_trade_td` | 用户交易历史累计 |
| `dws_usr_user_action_1d` | 用户行为（浏览/点击）日汇总 |
| `dws_prd_product_trade_1d` | 商品交易日汇总 |
| `dws_prd_product_trade_30d` | 商品交易近30天汇总 |
| `dws_trd_shop_gmv_1d` | 店铺 GMV 日汇总 |

### 3.6 tdm 层

TDM 层采用**长表（明细）+ 宽表（服务）+ 人群包（远期）**三级结构，按实体类型分表，不按标签主题拆表。详见 `23-标签体系.md`。

**标签明细长表**（EAV 结构，所有标签值纵向存放）：

```
tdm_{域}_tag_ful_d
```

| 示例 | 说明 |
|------|------|
| `tdm_usr_tag_ful_d` | 用户标签明细长表，全量，日 |
| `tdm_prd_tag_ful_d` | 商品标签明细长表，全量，日 |
| `tdm_shp_tag_ful_d` | 商家标签明细长表，全量，日 |

**核心标签宽表**（高频标签 pivot 为列，供下游直接 JOIN）：

```
tdm_{域}_profile_ful_d
```

| 示例 | 说明 |
|------|------|
| `tdm_usr_profile_ful_d` | 用户核心画像宽表，全量，日 |
| `tdm_prd_profile_ful_d` | 商品核心画像宽表，全量，日 |
| `tdm_shp_profile_ful_d` | 商家核心画像宽表，全量，日 |

**人群包**（单表，每行一个人群，`crowd_code` 区分）：

```
tdm_{域}_crowd_ful_d
```

| 示例 | 说明 |
|------|------|
| `tdm_usr_crowd_ful_d` | 用户人群包（阶段 1 用 `ARRAY<BIGINT>`，阶段 2+ 升级为 bitmap `BINARY`） |

### 3.7 ads 层

```
ads_{域}_{用途描述}
```

ads 是面向具体应用场景的输出表（报表、接口、导出），表名反映**"给谁用、干什么"**，**不带时间窗口后缀**。一张 ads 表里通常混合多个窗口的指标列（如 `order_cnt_1d`、`order_cnt_7d`、`gmv_30d`），窗口信息体现在**字段名**里而不是表名里。

| 示例 | 说明 |
|------|------|
| `ads_trd_daily_operation_report` | 交易域，运营日报 |
| `ads_usr_user_tag` | 用户域，用户标签宽表（给推荐系统） |
| `ads_trd_shop_ranking` | 交易域，店铺排行榜 |
| `ads_prd_category_analysis` | 商品域，品类分析报表 |

### 3.8 辅助表前缀

| 前缀 | 含义 | 说明 |
|------|------|------|
| `smp` | 样本表 | 抽样、调试用 |
| `tmp` | 临时表 | ETL 中间结果 |
| `test` | 测试表 | 开发测试用 |

---

## 4. 字段命名规则

| 字段类型 | 规则 | 示例 |
|---------|------|------|
| 主键 ID | `{entity}_id` | `user_id`、`order_id`、`product_id` |
| 布尔 | `is_{state}` | `is_active`、`is_deleted`、`is_weekend` |
| 时间戳 | `{action}_time` | `create_time`、`update_time`、`pay_time` |
| 日期 | `{action}_date` | `order_date`、`reg_date` |
| 金额 | `{business}_amt_{currency}` 必须带币种后缀 | `order_amt_cny`、`paid_amt_usd`、`dct_amt_cny` |
| 数量 | `{business}_cnt` | `order_cnt`、`pv_cnt` |
| 比率 | `{business}_rto` | `conv_rto`、`retn_rto` |
| 等级 | `{business}_lvl` | `user_lvl`、`vip_lvl` |
| 状态 | `{business}_status` | `order_status`、`pay_status` |

## 5. 术语词根字典

### 5.1 业务术语（按域）

> 表格说明：
> - **后端惯用名称**：源系统数据库中的字段名，raw/ods 层保留原名，dwd 及以上统一为**标准缩写**
> - **英文全称**：字段命名的语义依据
> - **标准缩写**：数仓 dwd 及以上层使用的字段名词根
> - **类型**：实体 / 动作 / 属性 / 金额 / 状态 / 指标 / 枚举值

### 5.2 数仓技术术语

| 词根 | 含义 |
|------|------|
| `agg` | aggregate 聚合 |
| `sum` / `avg` / `max` / `min` | 求和/平均/最大/最小 |
| `cnt` | count 计数 |
| `dist` | distinct 去重 |
| `pct` | percentage 百分比 |
| `rto` | ratio 比率 |
| `rnk` | rank 排名 |
| `tot` | total 总计 |
| `src` | source 来源 |
| `etl` | ETL 标识 |
| `dt` | 分区日期 |
| `hr` | 分区小时 |

### 5.3 行业通用缩写（最高优先级，直接使用）

`pv` `uv` `dau` `wau` `mau` `gmv` `arpu` `arppu` `ltv` `cac` `roi` `ctr` `cvr` `cpa` `sku` `spu`

### 5.4 源系统字典（ODS 层使用）

两段式 `{source_type}_{ingestion_method}`：
- 源类型：`pg` / `es` / `csv` / `excel` / `api`
- 接入方式：`datax` / `cdc` / `excel` / `csv` / `manual`
- 常见组合：`pg_datax`、`pg_cdc`、`es_file`、`csv_manual`

## 6. 技术字段规范（所有表均需包含）

| 字段 | 出现在 | 类型 | 含义 |
|------|-------|------|------|
| `etl_time` | 所有层 | timestamp | ETL 处理时间 |
| `src_sys` | ODS | string | 源系统标识 |
| `src_tbl` | ODS | string | 源表名 |
| `dt` | 分区字段 | string | 分区日期 `yyyy-MM-dd` |
| `hr` | 分区字段（可选） | string | 分区小时 |
| `start_date` / `end_date` | 拉链表（zip） | string | 有效期，`end_date=9999-12-31` 表示当前 |

## 7. SQL 示例

**ODS 层：**
```sql
CREATE TABLE IF NOT EXISTS ods.ods_trd_order_info_inc_d (
    order_id        BIGINT    COMMENT '订单ID',
    user_id         BIGINT    COMMENT '用户ID',
    shop_id         BIGINT    COMMENT '店铺ID',
    order_amt_cny   DECIMAL(18,2) COMMENT '订单金额(人民币)',
    order_status    STRING    COMMENT '订单状态',
    create_time     TIMESTAMP COMMENT '创建时间',
    update_time     TIMESTAMP COMMENT '更新时间',
    is_deleted      BOOLEAN   COMMENT '是否删除',
    src_sys         STRING    COMMENT '源系统',
    src_tbl         STRING    COMMENT '源表',
    etl_time        TIMESTAMP COMMENT 'ETL时间'
) COMMENT '订单贴源增量表'
PARTITIONED BY (dt STRING)
STORED AS ORC;
```

**DWD 层（acc 累积快照）：**
```sql
CREATE TABLE IF NOT EXISTS dwd.dwd_trd_group_buy_acc_d (
    group_buy_id       BIGINT    COMMENT '拼团ID',
    initiator_user_id  BIGINT    COMMENT '发起人用户ID',
    product_id         BIGINT    COMMENT '商品ID',
    required_cnt       INT       COMMENT '成团所需人数',
    current_cnt        INT       COMMENT '当前参团人数',
    status             STRING    COMMENT '状态: initiated/succeeded/failed/expired',
    initiate_time      TIMESTAMP COMMENT '发起时间',
    succeed_time       TIMESTAMP COMMENT '成团时间',
    fail_time          TIMESTAMP COMMENT '失败时间',
    expire_time        TIMESTAMP COMMENT '过期时间',
    group_duration_sec BIGINT    COMMENT '成团耗时(秒)',
    etl_time           TIMESTAMP COMMENT 'ETL时间'
) COMMENT '拼团累积快照明细表'
PARTITIONED BY (dt STRING)
STORED AS ORC;
```

**DWS 层：**
```sql
CREATE TABLE IF NOT EXISTS dws.dws_usr_user_trade_1d (
    user_id         BIGINT        COMMENT '用户ID',
    order_cnt       BIGINT        COMMENT '当日订单数',
    pay_amt_cny     DECIMAL(18,2) COMMENT '当日支付金额',
    refund_cnt      BIGINT        COMMENT '当日退款数',
    group_buy_cnt   BIGINT        COMMENT '当日参团数',
    etl_time        TIMESTAMP     COMMENT 'ETL时间'
) COMMENT '用户交易日汇总'
PARTITIONED BY (dt STRING)
STORED AS ORC;
```

**ADS 层：**
```sql
CREATE TABLE IF NOT EXISTS ads.ads_trd_daily_operation_report (
    order_cnt_1d        BIGINT        COMMENT '当日订单数',
    pay_amt_1d_cny      DECIMAL(18,2) COMMENT '当日支付金额',
    order_cnt_7d        BIGINT        COMMENT '近7天订单数',
    pay_amt_30d_cny     DECIMAL(18,2) COMMENT '近30天支付金额',
    group_buy_succeed_rto_1d DECIMAL(5,4) COMMENT '当日成团率',
    etl_time            TIMESTAMP     COMMENT 'ETL时间'
) COMMENT '运营日报'
PARTITIONED BY (dt STRING)
STORED AS ORC;
```

## 8. 各层命名速查

| 层 | 表名结构 | 第三段含义 | 末段 |
|----|---------|-----------|------|
| raw | `raw_{域}_{源表名}_{快照}_{周期}` | 数据源原始表名 | 快照+周期 |
| ods | `ods_{域}_{源表名}_{快照}_{周期}` | 数据源原始表名 | 快照+周期 |
| dim | `dim_{域}_{实体}_{快照}_{周期}` | 维度实体名 | 快照+周期 |
| dwd | `dwd_{域}_{业务过程}_{快照}_{周期}` | 业务过程名 | 快照+周期 |
| dws | `dws_{域}_{实体}_{主题}_{窗口}` | 聚合维度+主题 | 时间窗口后缀 |
| tdm | `tdm_{域}_{tag\|profile\|crowd_*}_ful_d` | 表类型（长表/宽表/人群包） | `ful_d` |
| ads | `ads_{域}_{用途描述}` | 应用场景 | 无 |

## 9. 合规 Checklist（建表前自检）

- [ ] 表名符合所在层的命名结构（见 §3 和 §8 速查表）
- [ ] 表名全小写 snake_case，长度 ≤ 30
- [ ] 字段全小写 snake_case，无拼音
- [ ] 金额字段带币种后缀 `_amt_cny`/`_amt_usd`
- [ ] 布尔字段以 `is_` 开头
- [ ] 时间字段以 `_time`（时间戳）或 `_date`（日期）结尾
- [ ] 包含 `etl_time` 字段
- [ ] ODS 表包含 `src_sys`、`src_tbl`
- [ ] 分区字段为 `dt`（必须）、`hr`（小时级可选）
- [ ] 所有字段都有 COMMENT
- [ ] 存储格式为 ORC
- [ ] 词根使用了 §5 字典，未引入同义新词
- [ ] dwd 层快照类型选择正确：不可变事件→`apd`，有里程碑→`acc`，有变更→`inc`
- [ ] dim 层快照类型选择正确：默认→`ful`，需追溯属性变更→`zip`
- [ ] dws 层使用时间窗口后缀而非快照+周期
- [ ] ads 层表名不带时间窗口后缀，窗口信息在字段名中体现