- Зачем:
- зафиксировать оценку учебной ценности текущей конструкции (STG→ODS→DDS→DM)
и сформировать backlog задач для доработки стенда.
- Что:
- создан docs/internal/architecture_review.md с анализом 9 сильных сторон
и приоритизированным списком замечаний (P0–P3) с чеклистом задач.
- Проверка:
- cat docs/internal/architecture_review.md.
- Зачем:
- дизайн-документ описывал устаревший batch-driven подход и не фиксировал паттерн TEMP TABLE, используемый в реализации.
- Что:
- заменено описание загрузки всех UPSERT-витрин на HWM-инкрементальность через _load_ts.
- добавлена секция «Общий паттерн загрузки UPSERT-витрин» с SQL-скелетом и таблицей применимости.
- в секции «Учит» каждой витрины добавлены паттерны HWM и TEMP TABLE.
- Проверка:
- визуальная проверка docs/internal/bookings_dm_design.md.
- Зачем:
- фильтр `_load_id = '{{ run_id }}'` использовал run_id DM-DAG-а, который не совпадает с run_id DDS-DAG-а, записанным в факты — витрина не находила дельту.
- Что:
- load: заменён _load_id-фильтр на HWM-подзапрос `_load_ts > MAX(_load_ts)` из dm.sales_report.
- dq: источник затронутых дат переключён с DDS на саму витрину (где _load_id уже корректный).
- Проверка:
- `make test` — smoke-тесты зелёные.
- запуск `bookings_to_gp_dm` в Airflow после загрузки DDS.
- Зачем:
- жесткая привязка инкремента к логической дате Airflow ({{ ds }}) приводила к пустой витрине при обработке исторических и "опоздавших" (late-arriving) данных.
- Что:
- изменена фильтрация в скрипте загрузки витрины: теперь динамически определяются даты, затронутые текущим батчем (через _load_id).
- обновлены DQ-проверки для валидации только тех дат, которые были изменены в рамках запущенного батча.
- в дизайн-документ добавлено описание паттерна работы с late-arriving facts для студентов.
- Проверка:
- запуск пайплайна "с нуля" за логическую дату 2024-01-01 приводит к корректному расчету агрегатов для исторических данных 2017 года (>8000 строк).
- Зачем:
- файл позволяет AI-агентам быстро находить и использовать контекст из AGENTS.md
- Что:
- создан файл GEMINI.md с ссылкой на @AGENTS.md
- Проверка:
- cat GEMINI.md
- Зачем:
- источник хранит мультиязычные названия как JSON ({"en": "...", "ru": "..."}),
- для упрощения downstream-логики (DDS/DM) нужны чистые строки на одном языке.
- Что:
- добавлен парсинг JSON с извлечением поля 'ru' в sql/ods/airports_load.sql
(airport_name, city, country).
- добавлен парсинг JSON с извлечением поля 'ru' в sql/ods/airplanes_load.sql
(model).
- обновлена документация docs/internal/bookings_ods_design.md с примечаниями
о нормализации.
- обновлены тестовые данные в tests/test_ods_snapshot_integration.py для
соответствия JSON-формату STG.
- Проверка:
- uv run make test (15 passed).
- SELECT airport_name FROM ods.airports → "Аль-Баха" (вместо JSON).
- Зачем:
- зафиксировать архитектуру 5 витрин DM перед реализацией и отдать на ревью.
- Что:
- создан docs/internal/bookings_dm_design.md с описанием всех витрин, DAG-структуры, DQ-проверок и порядка реализации.
- Проверка:
- cat docs/internal/bookings_dm_design.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Зачем:
- dq_ods_segments падал на непустых батчах из-за orphan flight_id в ods.segments.
- Что:
- доработан sql/ods/flights_load.sql: добавлено добирание рейсов из истории stg.flights для flight_id из stg.segments текущего batch.
- добавлен контрактный тест в tests/test_ods_sql_contract.py на покрытие flight_id из segments.
- обновлена документация DAG в docs/bookings_to_gp_ods.md.
- Проверка:
- make test.
- airflow dags trigger bookings_to_gp_ods -c '{"stg_batch_id":"manual__2026-01-18T18:47:18.316091+00:00"}'.
- Зачем:
- подготовлен учебный Star Schema слой для перехода от ODS к аналитике и витринам.
- Что:
- добавлены 21 SQL-файл для DDS (DDL/LOAD/DQ) с SCD1/SCD2 и фактом `fact_flight_sales`.
- добавлены DAG `bookings_dds_ddl` и `bookings_to_gp_dds`, а также smoke-тесты структуры DAG.
- обновлены `sql/ddl_gp.sql` и документация (`README`, `docs/*`, `db_schema`) под поток `stg -> ods -> dds`.
- Проверка:
- make test.
- Зачем:
- синхронизировать db_schema.md с фактическим состоянием репозитория и текущим DDS-планом.
- Что:
- обновлён статус слоёв: STG/ODS отмечены как реализованные, DDS как слой в проектировании.
- приведены к актуальному виду DDS-объекты и нейминг (`dds.dim_*`, `dds.fact_flight_sales`, `dds.dim_routes` SCD2).
- обновлены mermaid-диаграмма, обучающие пояснения, TODO, связанные документы и история изменений.
- Проверка:
- git diff -- docs/internal/db_schema.md
- Зачем:
- устранить противоречия и пробелы в плане DDS перед реализацией.
- Что:
- HIGH: факт теперь использует point-in-time SCD2 lookup для routes,
UPDATE факта не перезаписывает dimension SK (историчность сохранена).
- MEDIUM: явная политика NULL FK в факте (3 группы: обязательные,
зависят от маршрута, зависят от расписания) + DQ с порогом 1%.
- MEDIUM: добавлены DQ-проверки SCD2 интервалов (valid_from < valid_to,
нет перекрытий версий).
- MEDIUM: DQ факта теперь проверяет calendar_sk и route_sk IS NULL
с порогом.
- LOW: добавлен стабильный tie-breaker (ticket_no) при дедупликации
passengers.
- добавлена секция backfill/reprocess политики.
- Проверка:
- cat docs/internal/bookings_dds_design.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Зачем:
- зафиксировать архитектурные решения DDS до начала реализации (для Codex).
- Что:
- создан docs/internal/bookings_dds_design.md с полным планом DDS.
- 6 измерений (calendar, airports, airplanes, tariffs, passengers, routes) + факт flight_sales.
- dim_routes реализует классический SCD2 с hashdiff.
- все остальные измерения — SCD1 UPSERT со стабильными SK.
- факт — инкрементальный UPSERT по зерну (ticket_no, flight_id).
- Проверка:
- cat docs/internal/bookings_dds_design.md.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Зачем:
- подготовлена учебная реализация ODS слоя с типизацией, UPSERT и DQ, чтобы продолжить работу от STG к DDS/DM.
- Что:
- добавлены SQL-скрипты `sql/ods/*_ddl.sql`, `sql/ods/*_load.sql`, `sql/ods/*_dq.sql` для 9 сущностей bookings.
- добавлены DAG `bookings_ods_ddl` и `bookings_to_gp_ods`, а также smoke-тесты для новых графов.
- ODS DDL интегрирован в `sql/ddl_gp.sql`; документация и план обновлены под единый запуск через `make ddl-gp`.
- Проверка:
- `make test`.
- `make ddl-gp`.
- Зачем:
- codex нашёл баги, которые сломали бы первый прогон ODS.
- Что:
- resolve batch: MAX(batch_id) заменён на ORDER BY load_dttm DESC LIMIT 1
(run_id — строка, лексикографический MAX не гарантирует хронологию).
- ручная проверка: добавлен make ddl-gp-ods (без него ODS-объекты не создадутся).
- routes/flights FK: расширено пояснение, почему проверка по route_no без
validity допустима в ODS и что учитывать при join в DDS.
- Проверка:
- make test (11 passed, 4 skipped).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Зачем:
- v2 содержал баги (CTE scope, distribution key), неточности маппинга
колонок и пробелы в описании DAG-контракта, что сломало бы реализацию.
- Что:
- исправлен CTE scope: дублирование CTE в UPDATE и INSERT statements.
- ods.tickets: DISTRIBUTED BY (ticket_no) вместо book_ref для UPSERT.
- добавлен Python-сниппет resolve_stg_batch_id (PythonOperator + XCom).
- заменены {{ params.stg_batch_id }} → {{ ti.xcom_pull(...) }} во всех SQL.
- <> заменён на IS DISTINCT FROM (NULL-safe change detection).
- DISTINCT ON заменён на ROW_NUMBER() (стандартный DE-паттерн).
- добавлена секция 4.3 с полной таблицей маппинга STG → ODS.
- routes: scheduled_departure_time → departure_time, duration без rename.
- DAG-граф: resolve_stg_batch_id как корневой таск, параллельные ветки.
- DQ: добавлена проверка «батч не пустой» для snapshot-справочников.
- DoD: убрано valid_from/valid_to, оставлено _load_id/_load_ts/event_ts.
- Проверка:
- make test (11 passed, 4 skipped).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Зачем:
- нужен единый стандарт именования полей, чтобы новые слои не расходились с учебными материалами.
- Что:
- добавлен единый документ с правилами нейминга `docs/internal/naming_conventions.md`.
- полностью переписан `docs/internal/bookings_ods_design.md` в эталонный учебный план ODS (SCD1, батч-контракт, DQ, граф DAG).
- добавлены ссылки на стандарт нейминга в `docs/README.md`, `docs/internal/db_schema.md` и `AGENTS.md`.
- Проверка:
- проверен diff по измененным файлам (`git diff`).
- Зачем:
- зафиксировать архитектурное решение для ODS слоя перед началом разработки.
- Что:
- создан файл docs/internal/bookings_ods_design.md.
- описана архитектура ODS и отличия от STG слоя.
- добавлены схемы таблиц (справочники с SCD Type 2, транзакции с UPSERT).
- Проверка:
- git show --stat HEAD
- Зачем:
- исключены ложные падения DQ при пустом source в bookings-db.
- Что:
- в TESTING.md добавлены pre-check команды COUNT(*) перед Trigger DAG.
- в docs/agent-dag-testing.md добавлена обязательная проверка source и fallback при COUNT(*) = 0.
- в таблицу типичных проблем добавлен кейс падения check_airports_dq/check_airplanes_dq с ошибкой "..._ext нет строк".
- Проверка:
- rg -n "source непустой|COUNT\(\*\) = 0|bookings-generate-day|check_airports_dq" TESTING.md docs/agent-dag-testing.md
- Зачем:
- AI-агенты пытались тестировать DAG через браузер вместо CLI/API,
так как не было явных инструкций по программному подходу.
- Что:
- добавлен docs/agent-dag-testing.md: CLI, REST API Airflow,
проверка параллельности, запросы в Greenplum, E2E-тест, шпаргалка команд.
- в AGENTS.md добавлена ссылка на новый гайд в раздел «Тестирование».
- из docs/README.md убрана ссылка (файл для людей, не для агентов).
- Проверка:
- cat docs/agent-dag-testing.md && grep agent-dag-testing AGENTS.md
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Зачем:
- необходимо зафиксировать контекст и правила работы с проектом для Claude AI.
- Что:
- создан файл CLAUDE.md с описанием структуры проекта.
- добавлены инструкции по коммитам и стилю кода.
- Проверка:
- git show --stat HEAD
- Зачем:
- линейный граф маскировал реальные зависимости данных; для эталонного
стенда важно показать менти параллельный граф там, где данные независимы.
- Что:
- airports и airplanes грузятся параллельно после check_tickets_dq.
- routes ждёт обоих (DQ проверяет ссылочную целостность на оба справочника).
- seats зависит только от airplanes и работает параллельно с веткой
routes → flights → segments → boarding_passes.
- finish_summary ждёт обе ветки (check_boarding_passes_dq + check_seats_dq).
- datetime.utcnow() заменён на datetime.now(UTC) в csv_to_greenplum.py.
- smoke-тесты дополнены проверкой параллельности и второй ветки.
- документация обновлена с ASCII-схемой нового графа.
- Проверка:
- make test (11 passed, 4 skipped), make lint — чисто.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Зачем:
- исключить нестабильные режимы генератора, в которых bookings может перестать пополняться.
- сделать причину ошибки понятной студенту сразу при запуске команд и SQL-скриптов.
- Что:
- добавлен precheck `bookings-check-jobs` в Makefile и подключён к `bookings-init` и `bookings-generate-day`.
- добавлены явные проверки `bookings.jobs = 1` в `bookings/generate_next_day.sql` и `sql/src/bookings_generate_day_if_missing.sql`.
- обновлена документация и `.env.example`: зафиксировано, что в стенде поддерживается только `BOOKINGS_JOBS=1`.
- Проверка:
- uv run make fmt.
- uv run make test.
- env BOOKINGS_JOBS=2 make bookings-init.
- env BOOKINGS_JOBS=2 make bookings-generate-day.
- make bookings-init.
- make bookings-generate-day.
- Зачем:
- предыдущий фикс ломал make bookings-init из-за невалидного SQL в Makefile.
- Что:
- удалены SQL-блоки постобработки reference-данных и cume_dist из bookings-init.
- удалён случайно добавленный gitlink _vendor/demodb.
- удалён SET LOCAL application_name из generate_next_day.sql.
- Проверка:
- uv run make fmt.
- uv run make test.
- make bookings-init.
- make bookings-generate-day.
ddadmin
