# Data Dictionary — fansy-store v1

Семантика полей рабочей схемы `fansy`. Структура staging-схемы
`fansy_staging` повторяет её один-к-одному, плюс поле `loaded_at` и
отсутствие части ограничений (валидация — при переливе).

Обозначения: `?` — nullable; `!` — обязательное.

## participants — справочник контрагентов M2M

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| inn | varchar(10) | ! | ИНН юрлица, PK | `client_master.inn` | `7702165310` |
| ogrn | varchar(15) | ? | ОГРН | `client_master.ogrn` | `1027739132563` |
| full_name_rus | text | ! | Полное наименование на русском | `client_master.full_name` | `НКО АО НРД` |
| short_name_rus | text | ? | Короткое наименование | `client_master.short_name` | `НРД` |
| display_name_rus | text | ! | Отображаемое имя для UI | `client_master.display_name` | `НРД` |
| full_name_eng | text | ? | Полное наименование на английском | `client_master.full_name_en` | `National Settlement Depository` |
| short_name_eng | text | ? | Короткое английское | `client_master.short_name_en` | `NSD` |
| display_name_eng | text | ? | Английское display | `client_master.display_name_en` | `NSD` |
| depository_participant_code | varchar(12) | ? | Код участника M2M (депозитарий) | `m2m_codes.dep_code` | `MC0010300000` |
| broker_participant_code | varchar(12) | ? | Код участника M2M (брокер) | `m2m_codes.brk_code` | `MC0079200001` |
| is_available_for_m2m | boolean | ! | Готовность к приёму M2M | `m2m_codes.is_active` | `true` |
| comment | text | ? | Свободный комментарий | — | — |
| created_at, updated_at | timestamptz | ! | Авто | — | — |

## securities — справочник ЦБ

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| security_code | char(12) | ! | Идентификатор ЦБ в системе НРД, PK | `security_master.nsd_code` | `MM0766162534` |
| isin | char(12) | ? | ISIN | `security_master.isin` | `RU0007661625` |
| classification | varchar(4) | ? | `BOND` (облигация), `SHAR` (акция), `MFUN` (ПИФ) | `security_master.type_code` | `SHAR` |
| category | varchar(4) | ? | `ORDN`/`PREF`/`UKWN` | `security_master.category` | `ORDN` |
| security_type | varchar(256) | ? | Текстовое описание типа | `security_master.type_text` | `Акция обыкновенная` |
| security_series | text | ? | Серия выпуска (для облигаций) | `security_master.series` | `01` |
| reg_number | varchar(256) | ? | Регистрационный номер выпуска / правил ДУ ПИФ | `security_master.reg_number` | `1-01-00010-A` |
| fund_class | varchar(120) | ? | Класс паёв ПИФ | `security_master.fund_class` | `A` |
| display_name | text | ! | Отображаемое имя для UI | `security_master.display` | `Сбербанк ао` |

## clients — депоненты-физлица

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| id | uuid | ! | PK, генерируется БД | `customer.uuid` | — |
| inn | varchar(12) | ? | ИНН (10 цифр юрлицо, 12 цифр физлицо) | `customer.inn` | `771234567890` |
| last_name | varchar(50) | ! | Фамилия | `customer.last_name` | `Иванов` |
| first_name | varchar(50) | ! | Имя | `customer.first_name` | `Иван` |
| middle_name | varchar(50) | ? | Отчество | `customer.middle_name` | `Иванович` |
| birth_date | date | ? | Дата рождения | `customer.birth_date` | `1980-01-15` |

## client_documents — документы инвестора

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| id | uuid | ! | PK | — | — |
| client_id | uuid | ! | FK на `clients.id` | `customer_doc.customer_uuid` | — |
| document_type | varchar(2) | ! | Код документа по справочнику НРД (01..91) | `customer_doc.type_code` | `21` |
| series | text | ? | Серия (без пробелов) | `customer_doc.series` | `4512` |
| number | text | ! | Номер (без пробелов) | `customer_doc.number` | `654321` |
| issued_at | date | ? | Дата выдачи | `customer_doc.issued_at` | `2010-05-12` |
| issuer | text | ? | Кем выдан | `customer_doc.issuer` | `ОУФМС России` |

## iia_contracts — договоры ИИС

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| id | uuid | ! | PK | — | — |
| client_id | uuid | ! | FK на `clients.id` | — | — |
| agreement_type | varchar(3) | ! | `T12` (ИИС-1/ИИС-2) или `T03` (ИИС-3) | `iia.type` | `T03` |
| agreement_number | varchar(128) | ! | Номер договора | `iia.number` | `ИИС78/2024` |
| agreement_date | date | ! | Дата заключения | `iia.signed_at` | `2026-01-15` |
| broker_inn | varchar(10) | ! | ИНН брокера, ведущего ИИС | `iia.broker_inn` | `0707083893` |

## settlement_requisites — реквизиты депозитариев

| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| id | uuid | ! | PK |
| inn | varchar(10) | ! | ИНН депозитария, UNIQUE |
| display_name | text | ! | Отображаемое имя |

## depo_accounts — счета депо

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| id | uuid | ! | PK | — | — |
| client_id | uuid | ! | FK на `clients.id` | — | — |
| deponent_code | varchar(50) | ! | Код депонента у депозитария | `depo.deponent_code` | `DP789456` |
| account_id | varchar(50) | ! | Номер счёта депо | `depo.account_id` | `31MC0021900000F01` |
| section_id | varchar(50) | ! | Номер раздела счёта | `depo.section_id` | `P001` |
| depository_inn | varchar(10) | ! | ИНН депозитария | `depo.depository_inn` | `7702070139` |
| is_active | boolean | ! | Активен ли счёт | `depo.is_active` | `true` |
| is_trading | boolean | ! | Торговый раздел | `depo.is_trading` | `true` |

Уникальность по тройке `(deponent_code, account_id, section_id)`.

## portfolios — портфели и остатки ЦБ

| Поле | Тип | Обяз. | Описание | Источник Fansy | Пример |
|---|---|---|---|---|---|
| id | uuid | ! | PK | — | — |
| client_id | uuid | ! | FK на `clients.id` | — | — |
| depo_account_id | uuid | ! | FK на `depo_accounts.id` | — | — |
| security_code | char(12) | ! | FK на `securities.security_code` | — | `MM0766162534` |
| isin | char(12) | ? | Кэш ISIN из securities | — | `RU0007661625` |
| quantity_whole | numeric(38,0) | ? | Целое количество (для акций/облигаций) | `position.qty_whole` | `1500` |
| quantity_fractional | numeric(38,16) | ? | Дробное (для паёв) | `position.qty_fract` | `2500.7500000000000000` |
| isolation_status | varchar(4) | ! | Всегда `SGDN` | — | `SGDN` |
| valued_at | timestamptz | ! | На какой момент актуально | `position.valued_at` | `2026-03-02T11:30:00Z` |

Должно быть заполнено ровно одно из (`quantity_whole`, `quantity_fractional`).

## etl_errors — журнал ошибок ETL

| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
| id | bigserial | ! | PK |
| source_table | text | ! | Таблица в Fansy |
| source_pk | text | ? | PK записи в Fansy |
| payload | jsonb | ? | Сама запись для ретрая |
| error_message | text | ! | Сообщение об ошибке |
| created_at | timestamptz | ! | Когда зафиксирована |