# Конвенции Нейминга DWH (Единый Источник)

> Статус: активный стандарт для новых реализаций в этом репозитории.
>
> Основа: учебные материалы `de-roadmap/dwh-modeling`.

## Зачем этот документ

Этот справочник задает имена служебных полей. Состав колонок конкретной
таблицы проверяйте по ее DDL, а требования к учебной загрузке - по
[ТЗ](../assignment/analyst_spec.md).

## 1. Базовые правила

- Имена колонок: `snake_case`, на английском.
- Бизнес-ключи источника не переименовываем без необходимости (`book_ref`, `ticket_no`, `route_no`).
- Булевы поля начинаются с `is_` (`is_outbound`, `is_boarded`).
- Денежные и количественные поля называем по смыслу (`total_amount`, `amount`, `range_km`).

## 2. Каноничные служебные поля

| Поле | Тип (рекомендация) | Смысл | Где применять |
|---|---|---|---|
| `_load_id` | `TEXT NOT NULL` | Идентификатор запуска или исходного STG-батча; зависит от слоя | STG, ODS, DDS и DM, кроме календаря |
| `_load_ts` | `TIMESTAMP NOT NULL` | Метка загрузки; в транзакционных ODS сохраняется время STG | STG, ODS, DDS и DM, кроме календаря |
| `event_ts` | `TIMESTAMP` | Опорное время источника или получения снимка | Все таблицы STG и транзакционные ODS |
| `created_at` | `TIMESTAMP NOT NULL` | Когда строка создана в таблице слоя | DDS/DM, где есть lifecycle строки |
| `updated_at` | `TIMESTAMP NOT NULL` | Когда строка обновлена в таблице слоя | DDS/DM, где есть UPDATE |
| `valid_from` | `DATE NOT NULL` (базовый трек) | Начало действия версии SCD2 | DDS SCD2 |
| `valid_to` | `DATE` | Конец действия версии SCD2 (`NULL` = current) | DDS SCD2 |
| `hashdiff` | `TEXT NOT NULL` | Хэш атрибутов версии для детекта изменений | DDS SCD2 |

## 3. Ключи в DDS

- Бизнес-ключ измерения: суффикс `_bk` (`customer_bk`, `airport_bk`).
- Суррогатный ключ измерения: суффикс `_sk` (`customer_sk`, `airport_sk`).
- В существующих таблицах есть бизнес-ключи без `_bk`: `passenger_id`
  у пассажиров, `fare_conditions` у тарифов, `date_actual` у календаря.
  Используйте имена из DDL и ТЗ; переименовывать их в задании не нужно.

## 4. Правило времени (важно для обучения)

- В STG `event_ts` задает опору инкремента: `book_date` у бронирований,
  билетов, сегментов и посадочных талонов; `scheduled_departure` у рейсов.
  Например, у талона это дата бронирования, а не `boarding_time`.
- У снимков `airports`, `airplanes`, `routes`, `seats` в STG
  `event_ts = now()`: точного времени изменения записи в источнике здесь нет.
- `_load_ts` относится к загрузке. Какой именно слой ее поставил, указано ниже.
  Правила отбора строк описаны в руководствах [STG](../bookings_to_gp_stage.md)
  и [ODS](../bookings_to_gp_ods.md).

## 5. Применение по слоям

### STG

- Все таблицы содержат `_load_id = run_id` запуска STG, `_load_ts = now()`
  и `event_ts` по правилам выше.

### ODS

- Снимки `airports`, `airplanes`, `routes`, `seats`: `_load_id` выбранного
  STG-батча, `_load_ts = now()`, без `event_ts`. Загрузка заменяет снимок целиком.
- Транзакционные таблицы: `_load_id`, `_load_ts` и `event_ts` переносятся из STG.
  Сохраненная `_load_ts` служит границей инкремента для `UPDATE + INSERT`.

### DDS и DM

- `_load_id` измененной или вставленной строки относится к текущему запуску
  своего слоя, `_load_ts` фиксирует время записи.
- Календарь статический: у `dim_calendar` нет меток загрузки.
- `created_at` и `updated_at` используем там, где они предусмотрены DDL.
  Например, у факта и полностью пересчитываемой `route_performance` их нет.
- Для SCD2 используем:
  - `valid_from`, `valid_to`, `hashdiff`, `created_at`, `updated_at`.
- Интервалы считаем как `[valid_from, valid_to)`, current-версия: `valid_to IS NULL`.

## 6. Что проверяем в ревью

- Нет новых техполей-синнонимов вроде `loaded_at`, `ingested_at`, `batch_key`, если уже есть канон.
- Нет смешивания `event_ts` и `_load_ts` в одном смысле.
- В SCD2 не используются альтернативы `dw_start_date/dw_end_date`, если в проекте принят `valid_from/valid_to`.