Bridge-and-Join-s/docs/fansy-contract/v1

docs/fansy-contract/v1 — контракт данных с командой Fansy

ETL Fansy → принимающая БД (fansy-store) реализует другая команда разработки. С нашей стороны зафиксирован контракт: схема таблиц, индексы, миграции, требования к выгрузке и тестовые данные.

Состав каталога

• ddl/ — SQL-миграции PostgreSQL:
  • 000__roles.sql — роли fansy_etl (ETL Fansy), bj_reader (наши сервисы), bj_migrator (миграции).
  • 001__schemas.sql — две схемы: fansy_staging (куда пишет ETL) и fansy (рабочая, для нашего чтения). Гранты по ролям.
  • 002__working.sql — рабочие таблицы: participants, securities, clients, client_documents, iia_contracts, settlement_requisites, depo_accounts, portfolios, etl_errors.
  • 003__staging.sql — staging-зеркало рабочих таблиц с полем loaded_at и сниженными ограничениями.
  • 004__seed_participants.sql — предзаполнение справочника участников: НРД, БКС (5406121446), Ренессанс (7709258228), Альфа-Банк (7728168971).
• data-dictionary.md — семантика каждого поля.
• etl-requirements.md — требования к процессу выгрузки от команды Fansy: подключение, тип load (UPSERT в staging), SLA свежести по таблицам, обработка ошибок, окна простоя, ПДн.
• examples/:
  • example-claim.md — какие данные m2m-core тянет из БД для одной типовой M2M-заявки (с конкретными SQL).
  • seed-data.sql — 5 тестовых клиентов, портфели, договоры — основа для приёмочного теста.

Рабочие копии миграций

Те же файлы лежат в migrations/fansy-store/ — оттуда они применяются при инициализации БД сервиса.

Порядок согласования

1. Передать команде Fansy ссылку на эту папку (тег fansy-contract-v1).
2. Обсудить с ними SLA, окна простоя, тип load.
3. По согласовании — дать им учётку с ролью fansy_etl и подсеть для доступа.
4. Запустить совместный приёмочный тест на seed-data.sql.
5. Изменения контракта — через новую папку v2/ с changelog'ом, без правки v1/.

Принципы

• Имена таблиц/колонок — snake_case английский.
• Комментарии к таблицам и важным колонкам — на русском через COMMENT ON ... IS '...'.
• Все timestamp — timestamptz в UTC.
• DDL-права только у bj_migrator, у fansy_etl нет.
• ETL пишет ТОЛЬКО в fansy_staging.*. Перелив в fansy.* — на нашей стороне после валидации.