# 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.*` — на нашей
  стороне после валидации.