arm-ka-docs/model/entities-v5.20.md

АРМ КА — описание сущностей модели данных v5.20

Источник истины по структуре — data-model-v5.20.dbml (полный). Диаграммы по частям — diagrams/ (part01…09 svg/png; перерисовываются make diagrams из текущего DBML). Здесь — что каждая таблица значит для бизнеса, как связана с соседями и откуда взялась.

Что изменилось в v5.20 (решения владельца 21.10.2026; RSHB/arm-ka-docs#147, OQ-161, AURORA-1442)

№	Изменение	Решение
1	document: is_modified (not null, default false), original_values (jsonb), modified_by (FK → app_user), modified_at	Аналитик уточняет период и счёт документа ОСВ, если они распознаны неверно (context/05-domain-rules.md §9.5 п. 12; OQ-161, вариант 2). Новые значения пишутся на месте — в period_year, period_quarter, is_cumulative, osv_account_code той же строки document; при первой правке прежние значения этих четырёх полей копируются в original_values и дальше не меняются; is_modified — текущие отличаются от исходных. Так же устроена правка сумм osv_entry (original_values) — первичка не мутируется: файл, JSON результата в S3 и исходные значения остаются как пришли. Копия document (второй документ с другим file_ordinal) отвергнута: file_ordinal — номер документа в documents[] результата, а не номер редакции; копия задвоила бы строки ОСВ, подтверждение и привязки. Строки osv_entry при смене счёта не меняются (у них свои коды субсчетов)

Остальные таблицы и enum — как в v5.19. Реализация — одна миграция в arm-core: только добавляет колонки (is_modified = false, остальные NULL); откат на данных с is_modified = true останавливается с ошибкой (потерялись бы исходные значения).

Что изменилось в v5.19 (решения владельца 17.10.2026, Р-1…Р-19; RSHB/arm-ka-docs#116)

Change openspec/changes/archive/2026-10-19-unified-statement-normalization: формы ББ/ОФР нормализуются общим кодом сервисов, контракт результата v2.0; ядро хранит результат как пришёл (context/05-domain-rules.md §11, §9.3, §9.5).

№	Изменение	Решение
1	financial_statement_line: снята уникальность (meta_id, line_code) (индекс остаётся неуникальным); новые row_index, source_ref (частичный уникальный (meta_id, source_ref) WHERE source_ref IS NOT NULL), line_status (enum statement_line_status: ok / unreadable / missing / detail), line_code_text, parent_row_index, needs_review, is_confirmed	Повтор кода — законный случай (один код, разные наименования; Р-4): хранятся все строки, чтения «по коду» идут через агрегат формы по коду (сумма строк ok, не хранится — DECISION-5). Строки без кода хранятся со статусом (Р-8, отменяет OQ-36 / OQ-141): detail — расшифровка под строкой с кодом, в §7, агрегаты, КФО и ЕХ не входит; unreadable / missing блокируют подтверждение, пока у них есть суммы (Р-13). Порядок и положение в источнике (row_index, source_ref) нужны экрану, чтобы показать строку и предупреждение у места. Признак «строка создана правкой аналитика» — row_index IS NULL (прежний признак line_code_original_value IS NULL не годится: у строк unreadable / missing / detail источника кода тоже нет); line_code_original_value — код из результата как пришёл, правками не меняется
2	financial_statement_value: source_text, needs_review, is_confirmed, confirmed_by, confirmed_at	needs_review хранится (пересматривает п. 4 v5.13): его считает сервис («подтверждение проверкой» §7 — Р-5, Р-7), ядро пересчитывает только после правок; подтверждение ячейки без правки аналитиком переживает пересчёт. Сырой текст источника — подсказка ячейки
3	financial_statement_column: period_kind, label_confidence	Относительные подписи бланка 66н («На отчётную дату», «На 31 декабря предыдущего года») — дата колонки от эффективной даты документа, ядро досчитывает после правки даты отчёта (Р-6); колонка без даты остаётся с period_kind = none
4	financial_statement_meta: form_variant (enum statement_form_variant), needs_review_fields, header_source (jsonb), organization_name_original_value, organization_name_modified	Упрощённая форма — свой набор соотношений §7 (NULL — документ до v5.19 или результат 1.x, набор полный); поля шапки, требующие проверки (сейчас — неуверенная дата отчёта); сырой текст и уверенность всех полей шапки результата (<поле>_text, <поле>_confidence) — подсказка у поля на экране; наименование организации правится, как ИНН
5	Новая таблица document_issue + enum document_issue_kind, issue_severity, issue_source	Предупреждения и нарушения §7 документа с уровнем и привязкой к строкам (line_ids), колонке (column_id, а вне колонок формы — column_index), полю шапки; у нарушения — codes (коды цели и членов); как пришли от сервиса или посчитаны ядром. Очищается при перезагрузке файла; при пересчёте после правки relation / soft заменяются целиком, warning сервиса сохраняются, кроме снимаемых правкой. Единственный источник нарушений для экрана и подтверждения: для результатов 1.x ядро один раз при приёме считает §7 копией arm_statements и пишет записи с source = core; формы до миграции не пересчитываются (база очищается, Р-24). Ведётся и у документов ОСВ — предупреждения листа OSV_* результата 2.0
6	recognition_job.statements_version	Коммит копии общего кода arm_statements, которым посчитан результат (service.statements_version); расхождение с копией ядра при пересчёте — info
7	document: уникальность (stored_file_id, document_type, osv_account_code) — частичная, кроме BALANCE / INCOME; новая колонка file_ordinal + уникальный (stored_file_id, file_ordinal)	Вторая форма того же типа в файле хранится (Р-10, Р-15); при двух формах одного типа и периода ни одна не автоподтверждается, подтверждение второй при подтверждённой первой — 409 DUPLICATE_FORM (Р-18). ОСВ по счёту, расшифровка и прочий — по-прежнему один на тип на файл (§9.5 п. 2)
8	related_group.crm_id (varchar, nullable, unique)	ID ГСК/ГСЗ в ЕЦП CRM из форм 51-03, 51-04, 77-02 (AURORA-1619, arm-core#112, OQ-33); вводится вручную, импорт ЕЦП не заполняет (OQ-91); уникален, как crm_id ГК и ЮЛ

Остальные таблицы и enum — как в v5.18. Реализация — одна миграция в arm-core; перед выкладкой база очищается от форм ББ/ОФР (решение владельца 18.10.2026, Р-24), поэтому миграция только добавляет колонки, таблицу и значения по умолчанию и §7 по существующим формам не считает. Заполнение (миграция проходит и на непустой базе): row_index — NULL у строк, созданных правкой (line_code_original_value IS NULL), у остальных — по возрастанию line_code в форме; line_status = ok, needs_review значений — НЕ values_ok, source_text = string_value, period_kind — absolute при period_date, иначе none, header_source — из *_original_value, file_ordinal — по (created_at, id) в файле; document_issue пуст — у форм, оставшихся в неочищенной базе, нарушения до первой правки не показываются. Откат гарантирован на пустой БД и на данных, которые v5.18 представляет без потери первичных данных и ручного ввода (без повторов кода, строк без кода, двух форм одного типа в файле, crm_id групп и правленого наименования организации); на таких данных downgrade останавливается с ошибкой, а производные колонки v5.19 и document_issue удаляет с записью в журнал миграции.

Что изменилось в v5.18 (решения владельца 09.10.2026, RSHB/arm-ka-docs#90)

№	Изменение	Решение
1	stored_file.consolidation_id (uuid, nullable, FK → consolidation) + индекс (legal_entity_id, consolidation_id)	Файл загружается в консолидацию (период ГК) и становится основой её «рабочего стола» (полный состав стола — context/05-domain-rules.md §9.5 п. 11), общего для всех версий периода; NULL — загрузка без контекста (страница ЮЛ, монозаёмщики, API). Панель «Первичные документы» в версии показывает рабочий стол консоли для ЮЛ плюс файлы с документами, привязанными к версиям консоли. Что использует конкретная версия — по-прежнему consolidation_document; заморозка после VERIFIED — привязки и ex_snapshot. Привязка файла к версии (consolidation_file) отвергнута: рабочие версии периода делят первичку, а новая версия после VERIFIED подхватывает подтверждённое (openspec/changes/console-files/design.md)
2	Note recognition_job.reply_deadline	Без изменения структуры: срок ответа OCR — 20 мин (OQ-159)

Остальные таблицы и enum — как в v5.17. Реализация — миграция 0006 в arm-core (backfill consolidation_id по consolidation_document).

Что изменилось в v5.17 (решение владельца 07.10.2026, пересмотр OQ-31, RSHB/arm-ka-docs#53)

№	Изменение	Решение
1	legal_entity.kpp и legal_entity_history.kpp (varchar, nullable)	КПП юридического лица нужен (макет: колонка «КПП» на экранах 50, 61, поле форм 51-02, 79; фронтенд: «в ручке получения ЮЛ не приходит КПП»). Формат — 9 символов: 4 цифры, 2 символа (цифра или латинская A–Z), 3 цифры, иначе INVALID_KPP. У ИП (entity_type = ИП) КПП запрещён. Для ЮЛ необязателен: существующие записи и импорт без колонки остаются валидными. Уникален по-прежнему только inn (КПП — атрибут; сопоставление контрагентов ОСВ по ИНН не меняется). Изменение КПП — обычная правка со снимком в legal_entity_history. Отменяет п. 2 v5.14 («КПП не вводится»)

Остальные таблицы и enum — как в v5.16. Реализация — миграция 0005 в arm-core.

Что изменилось в v5.16 (Срез 4, решения владельца 06.10.2026)

№	Изменение	Решение
1	Enum counterparty_match_kind (INN, NAME, ALIAS, MANUAL, PROPAGATED) и колонка osv_entry.counterparty_match_kind (nullable)	Способ сопоставления контрагента строки ОСВ хранится. NULL ⇔ counterparty_id NULL; INN / NAME / ALIAS — шаг автоматического резолва при маппинге (ИНН; точное имя; нормализованное имя ЮЛ или алиас); MANUAL — ручное сопоставление аналитиком; PROPAGATED — автоприменение по имени в версии (DOC-221278 п. 12–13). Вычислять на чтение нельзя: после ручного связывания появляется алиас, и ручное сопоставление неотличимо от ALIAS. Миграция 0004 заполняет колонку по уже смапленным строкам (ИНН без пробелов = legal_entity.inn → INN; trim(name) = legal_entity.name → NAME; остальные с counterparty_id → ALIAS — приближение: ручных сопоставлений до Среза 4 не было)
2	Семантика consolidation_document	Без изменения структуры: строка создаётся при подтверждении документа (по документам ЮЛ — членов периметра версий «в работе») и при добавлении ЮЛ в периметр (подтверждённые подходящие документы подхватываются); удаляется при замене/удалении файла и исключении ЮЛ из периметра. Для одной (ЮЛ, document_type, osv_account_code, период, признак нарастающего) привязан один документ — самый поздний confirmed_at (D-5 Среза 4)
3	Семантика consolidation_lock	Без изменения структуры: блокировка без истечения по времени — активна, пока её не снял владелец, администратор или не перехватил другой пользователь с CONSOLIDATION_EDIT по причине (OQ-119)

Пробелы квартальной склейки и сама сводная ОСВ по-прежнему не хранятся (DECISION-5). Остальные таблицы и enum — как в v5.15 (43 таблицы; enum — 28). Реализация — миграция 0004 в arm-core.

Что изменилось в v5.15 (Срез 2c, решения владельца 05.10.2026)

№	Изменение	Решение
1	osv_data_type + NU (после BU)	Строки налогового учёта из ОСВ «БУ, НУ» хранятся в osv_entry как есть (OQ-45); контракт результата допускал NU с v1.0, ядро раньше такой строки принять не могло
2	app_user.email — в нижнем регистре	Без изменения структуры: нормализация при записи (seed, администрирование), поиск по lower(email) сохраняется, уникальность — существующий UNIQUE по email (OQ-59). Expression-индекс lower(email) не вводится: сверка ORM↔DBML не умеет expression-индексы. Миграция 0003 приводит существующие email к нижнему регистру (при дублях по регистру — падает, слияние решает человек)
3	Семантика stored_file.status, recognition_job.group_schema	Без изменения структуры: PROCESSING ставит inbox по ack сервиса, PROCESSED/ERROR — цикл маппинга результата (OQ-67); маппинг выполняется отдельно от inbox (OQ-69); group_schema заполняет маппер; «Итого» в osv_entry не хранится (OQ-01)
4	Индексы osv_entry (parent_entry_id), osv_entry (recognition_job_id), stored_file (current_recognition_job_id)	Индексы для удаления файла и обхода дерева строк: без них проверки FK (в том числе self-FK parent_entry_id) при DELETE /files/{id} и очистке файла перед повторным маппингом шли seq scan'ом. Замер: DELETE документа 1000 строк 8,6 с → 16 мс на 200 тыс. строк. Обычные (не unique) индексы; закрывает OQ-117 (I-1 финального ревью Среза 2c)

Остальные таблицы и enum — как в v5.14 (43 таблицы, 27 enum). Реализация — миграция 0003 в arm-core.

Что изменилось в v5.14 (Срез 1, решения владельца 04.10.2026)

№	Изменение	Решение
1	related_group_member.kind + индекс (legal_entity_id, kind) WHERE is_current	ЮЛ состоит одновременно в одной ГСК и одной ГСЗ (но только в одной группе каждого вида). Отменяет ANL-030 / v5.8 («только в одной ГСК или ГСЗ»). kind — денормализация related_group.kind (равенство проверяет ядро при записи, тест на рассинхрон); индекс не выразить через join, триггер не выбран. Закрывает OQ-32
2	КПП	Не вводится (отменено в v5.17: КПП введён). Поле есть только в макете; у legal_entity его нет, импорт его не читает (закрывал OQ-31 до v5.17)
3	Семантика company_group.crm_id, base_regional_office_id	Без изменения структуры: crm_id = «iD ГК» выгрузки ЕЦП CRM, base_regional_office_id = «Базовый РФ ГК в CRM»; флаги «входит в ГСК/ГСЗ» выгрузки → членство в одной неявной ГСК/ГСЗ на ГК (правила — 05-domain-rules.md §13)
4	audit_action + LEGAL_ENTITY_CHANGE, USER_CHANGE	Журнал изменений ЮЛ (создание/изменение/закрытие/перевод, алиасы) и пользователей (создание/деактивация администратором) — ТЗ 8.2; в v5.13 для них не было действия (были GROUP_CHANGE, MEMBERSHIP_CHANGE, USER_ROLE_CHANGE)

Остальные таблицы и enum — как в v5.13 (43 таблицы). Реализация — миграция 0002 в arm-core.

Что изменилось в v5.13 (ревью 30.09–01.10)

№	Замечание	Решение
1	Вместо RBAC «в коде» — роли и права	permission + role_permission возвращены; права только через роли, прямых назначений пользователю нет. Исключения — заведением роли
2	osv_entry.parent_entry_id не нужен — храним только строки с контрагентами	Отложено. Открыт вопрос: хранить ли строки уровня ACCOUNT для сверки «Σ контрагентов = итог счёта»; аналитика «Парсинг ОСВ» п.11 пока говорит «все строки»
3	osv_group_schema не особо нужна	Убрана. Схема шапки — recognition_job.group_schema jsonb; тип строки — osv_entry.group_type
4	financial_statement_value.needs_review непонятен	Убран: производное от confidence / is_recognized, порог может меняться
5	В recognition_job не нужны и result, и raw_result	Оставлен только result_s3_object_id. Сырой ответ ИС Сканирование — S3 raw/{job_id}.json по конвенции, в БД не регистрируется
6	stored_file.fields_modified — что это	Счётчик «исправлено полей» с карточки документа (v5.7). Убран — COUNT(is_modified) по данным
6-бис	document_type не предусматривает несколько ОСВ или ББ+ОФР в одном файле	Разделение файл / документ: stored_file — физический файл, document — логическая единица (1:N). Чек-лист, проверки, подтверждение, FK разобранных данных, consolidation_document, ex_snapshot_item — на document. Замена (superseded_by) — файл целиком
7	file_type: убрать Р7	Убран. xls/xlsx/xlsb → tabular-parser, pdf/png/jpg → scan-gateway

Принципы модели (коротко):

• Первичка не редактируется: файлы и распознанные значения хранятся как пришли; правки аналитика — рядом (is_modified, original_*) и в аудите.
• Производные консолидации в работе (сводная ОСВ, пары ВГО, шахматка) не хранятся — считаются запросом. Хранятся только ручные решения (корректировки, гудвилл, подтверждение КФО клиента).
• При верификации всё замораживается в Единое хранилище (ЕХ) как самодостаточный срез, который не зависит от таблиц консолидации.
• Единственный писатель в БД — ядро arm-core; сервисы распознавания видят только NATS и S3.
• Права — данные (role_permission), ограничения по ЗО/филиалу/статусу — policy-слой поверх прав.

---

Часть 01 — Группы компаний, организации, филиалы

Сущность	Что это	Ключевые связи	Откуда
regional_office	Филиал банка: головной офис (ГО, is_head_office) и региональные филиалы (РФ). Определяет зону видимости пользователя и закрепление ГК.	← company_group.base_regional_office_id, legal_entity.regional_office_id, app_user.regional_office_id	ТЗ 8.1
company_group	Группа компаний (ГК) — верхний уровень справочника клиентов. Текущее состояние (SCD4). crm_id = «iD ГК» из ЕЦП CRM (NULL, если создана вручную Куратором; v5.14 — семантика по выгрузке), внутренний code, закрепление за филиалом (base_regional_office_id = «Базовый РФ ГК в CRM»), флаг архива.	→ regional_office; ← legal_entity, related_group, consolidation	ТЗ 6.1, Прил. 2; макет
company_group_history	Прошлые снимки ГК: каждое изменение — новая строка с valid_from/valid_to.	→ company_group	ТЗ 6.10, 8.2
legal_entity	Юридическое лицо / ИП. Натуральный ключ — ИНН; v5.17: kpp — КПП (9 символов, nullable, только у ЮЛ, не ключ). company_group_id = текущая ГК; NULL = монозаёмщик. close_date — закрыто/архивировано.	→ company_group, regional_office; ← related_group_member, stored_file, document, osv_entry.counterparty_id, consolidation_member	ТЗ 6.1, Прил. 2; ЕХ 6.1
legal_entity_history	Прошлые снимки ЮЛ + вид события (создание, изменение, переход в другую ГК, закрытие, вывод из ГК) и дата вступления в силу.	→ legal_entity	ТЗ 8.2; макет
legal_entity_alias	Словарь написаний контрагента: как имя встречается в ОСВ и нормализованный ключ для матчинга. Пополняется при ручном сопоставлении.	→ legal_entity	ТЗ 6.5
related_group	ГСК или ГСЗ внутри ГК; kind различает. Для ГСК формируется КФО. Иерархия не поддерживается. v5.19: crm_id — ID группы в ЕЦП CRM (вручную, уникален).	→ company_group; ← related_group_member, consolidation.related_group_id	ТЗ 6.1, Прил. 2
related_group_member	Состав ГСК/ГСЗ — история членства (SCD2). v5.14: ЮЛ может одновременно входить в одну ГСК и одну ГСЗ (не более одной группы каждого вида): колонка kind = related_group.kind (денормализация) и частичный уникальный индекс (legal_entity_id, kind) WHERE is_current. Решение владельца 04.10.2026, отменяет ANL-030.	→ related_group, legal_entity	ТЗ 6.1; макет [79]

Часть 02 — Пользователи, роли, права

Сущность	Что это	Ключевые связи	Откуда
app_user	Пользователь АРМ. Аутентификация внешняя (РАИСА/SSO, external_id). Филиал (ГО/РФ), зона ответственности (ДКБ/ДМСБ/ДМ), табельный номер. Видимость данных = права роли + филиал + ЗО.	→ regional_office; ← user_role, все *_by поля	ТЗ 8.1, Прил. 2
role	Роли: seed из ТЗ 8.1 (КА РФ, КА ГО, РКА, КМ, Куратор ГО, Эксперт, Администратор; is_system) + роли, заведённые администратором для исключений. v5.13: код роли в бизнес-логике не проверяется — только права.	← user_role, role_permission	ТЗ 8.1
permission	v5.13. Атомарное право «объект × действие»: DIRECTORY/DOCUMENT/CONSOLIDATION/KFO/EX/EXPORT/USERS/AUDIT × VIEW/EDIT/APPROVE/VERIFY/DELETE/EXPORT/ADMIN. Seed, привязан к коду — администратор новые коды не создаёт. Право говорит «может»; policy-слой (ЗО, филиал, статус КФО) — «эту ли и сейчас ли».	← role_permission	ТЗ Прил. 2, сноска 29
role_permission	v5.13. Матрица доступов как данные: effective_permissions(user) = ∪ permissions(roles(user)). Редактируется администратором на экране «Изменение ролей и прав доступа»; история — audit_event(ROLE_PERMISSION_CHANGE). Прямых прав у пользователя нет.	→ role, permission	ТЗ Прил. 2; макет
user_role	Назначение ролей пользователю (M:N). История — в аудите.	→ app_user, role	ТЗ 8.1

Часть 03 — Бухгалтерские справочники и правила

Сущность	Что это	Ключевые связи	Откуда
chart_of_account	План счетов с иерархией, тип A/P/AP, признак забалансового. Seed — полный план 1С; нестандартные субсчета клиентов добавляет администратор.	← osv_entry.account_id, elimination_rule_account, required_document_rule	ТЗ 6.2/6.5, Прил. 3/4
elimination_rule	Правило элиминации из Прил. 3 (ББ) / Прил. 4 (ОФР) как данные: пара статей, сторона, мера, режим, НДС, акцизы. Версионируется.	← elimination_rule_account, correction.rule_id; версия фиксируется в consolidation_version	ТЗ 6.4, Прил. 3/4
elimination_rule_account	Счета/субсчета каждой стороны правила, включая исключения («76 кроме 76.7.1»).	→ elimination_rule, chart_of_account	ТЗ Прил. 3/4
required_document_rule	Какие документы обязательны по подходу. v5.13: сверяется с document (тип + счёт + период), а не с файлом: выполнено = есть document CONFIRMED у каждого ЮЛ периметра.	→ chart_of_account	ТЗ 5.1, 6.2, сноска 12

Часть 04 — Файлы, документы, S3, задания распознавания

Сущность	Что это	Ключевые связи	Откуда
s3_object	Реестр всех объектов в S3: бакет-роль, ключ, размер, sha256, срок жизни, ссылка на архив в data lake. Единая точка ретеншна (5 лет по ТЗ 8.4) и дедупа.	← stored_file, recognition_job	ТЗ 6.2, 8.4; ЕХ 8.3
stored_file	v5.13: только физический файл одной загрузки: чей (ЮЛ), формат, hash, кто/когда загрузил, статус обработки (UPLOADED → PROCESSING → PROCESSED / ERROR / SUPERSEDED), версия при замене. v5.18: consolidation_id — консолидация, в контексте которой файл загружен (основа «рабочего стола консоли», общего для версий периода; полный состав — context/05-domain-rules.md §9.5 п. 11; NULL — без контекста). Что внутри файла — document. Замена — файл целиком со всеми документами.	→ legal_entity, consolidation, s3_object, recognition_job; ← document, recognition_job	ТЗ 6.2, 8.2; UC-01…05
document	v5.13, новая. Логический документ внутри файла: ББ, ОФР, ОСВ по счёту (osv_account_code), расшифровка, прочее. Период, отчётная дата, где в файле (locator: лист / страницы), статус проверки (RECOGNIZED / NEEDS_CHECK / CONFIRMED / ERROR), результаты проверок периода и контрагента, кто подтвердил. Один файл → N документов (PDF с ББ+ОФР; xlsx с несколькими ОСВ). Создаёт ядро при маппинге результата recognition_job. На документ ссылаются разобранные данные, чек-лист, консолидация и ЕХ. v5.19: file_ordinal — индекс документа в documents[] результата (у всех документов); формы ББ/ОФР одного типа в файле могут повторяться (ОСВ по счёту, расшифровка, прочий — один на тип); предупреждения и нарушения — document_issue. v5.20: период и счёт ОСВ уточняются аналитиком на месте, распознанные — в original_values (is_modified, modified_by/at).	→ stored_file, legal_entity, app_user; ← osv_entry, financial_statement_meta, document_issue, consolidation_document, ex_snapshot_item	ТЗ 6.2, 5.1, 8.2; макет (чек-лист, «Подтвердить данные»)
recognition_job	Одна попытка распознать/распарсить файл. Единственная точка обмена с NATS (outbox/inbox, дедуп по result_msg_id, DLQ). Хранит сервис и версию, одну ссылку на нормализованный JSON-результат в S3 (v5.13), метрики, и схему группировок шапки ОСВ по листам (group_schema jsonb, v5.13 — вместо osv_group_schema). v5.19: statements_version — версия копии общего кода нормализации, которой посчитан результат форм.	→ stored_file, s3_object; ← osv_entry, financial_statement_meta	ТЗ 6.2, 6.10; DECISION-4

Часть 05 — Разобранные ОСВ

Сущность	Что это	Ключевые связи	Откуда
osv_entry	Строка ОСВ: документ (счёт + период), владелец, тип строки по схеме шапки (group_type, v5.13), уровень и родитель (parent_entry_id — открыт вопрос, замечание 2), код счёта и резолв в план счетов, сырое имя/ИНН контрагента, резолв в ЮЛ и способ сопоставления (counterparty_match_kind, v5.16), шесть сумм, тип данных (БУ/валюта/кол-во), «подакцизный» для 90-го. Ручные правки: is_modified, original_values, modified_by. Признак ГСК/ГК/Внешний не хранится — выводится из периметра версии; способ сопоставления контрагента хранится (NULL ⇔ контрагент не сопоставлен).	→ document, recognition_job, legal_entity ×2, chart_of_account	ТЗ 6.2/6.5, Прил. 2; «Парсинг ОСВ»

Часть 06 — Распознанные формы ББ/ОФР

Сущность	Что это	Ключевые связи	Откуда
financial_statement_meta	Шапка распознанной формы (1:1 с document BALANCE/INCOME): ИНН и наименование как в документе, отчётная дата, единица измерения, реквизиты. Ревью формы (reviewed_by/at) и акцепт КА непройденных логических проверок с комментарием. Подтверждение документа — document.confirmed_by. v5.19: form_variant (полная / упрощённая — набор соотношений §7), needs_review_fields, header_source (сырой текст и уверенность полей шапки), правка наименования (organization_name_original_value, organization_name_modified); результат проверок §7 и предупреждения хранятся в document_issue как пришли от сервиса, ядро пересчитывает их только после правок.	→ document, recognition_job, app_user; ← column, line	ТЗ 6.2/6.3; FNR01; макет
financial_statement_column	Колонки-периоды формы с датой — нужны для межформенной проверки (1370 на начало года) и гудвилла. v5.19: period_kind (абсолютная / относительная подпись бланка / без даты), label_confidence.	→ meta; ← value	ТЗ 6.3 п.7, 6.7
financial_statement_line	Строка формы как в источнике: код (или его сырой текст) и наименование как распознано. v5.19: все строки источника — с кодом (ok, повторы кода тоже) и без (unreadable, missing, detail — расшифровка под родителем parent_row_index); порядок row_index (NULL ⇔ строка создана правкой аналитика), положение source_ref, needs_review неуверенного кода, подтверждение кода is_confirmed. Раскладка экрана — по коду «как на бумаге».	→ meta; ← value, document_issue.line_ids	ТЗ 6.2, Прил. 2
financial_statement_value	Число в ячейке (строка × колонка): сумма, уверенность, is_recognized, ручная правка с исходным значением. v5.19: подсветка — только needs_review (хранится: уверенность, is_recognized и §7 сведены сервисом, ядро пересчитывает после правок); source_text — сырой текст источника; is_confirmed / confirmed_by/at — подтверждено без правки. (v5.13 этот флаг убирала как производный.)	→ line, column, app_user	ТЗ 6.2, Прил. 2
document_issue	v5.19, новая. Предупреждение или нарушение §7 документа (у формы; у ОСВ — предупреждения листа): вид (warning / relation / soft), код и уровень (error / info), сообщение, привязка к строкам (line_ids), колонке (column_id или column_index) и полю шапки, источник (service / core); для нарушения — соотношение, codes, expected, actual. Экран показывает их у места.	→ document, financial_statement_column	change unified-statement-normalization (design, шаг 8)

Часть 07 — Консолидация

Сущность	Что это	Ключевые связи	Откуда
consolidation	Логическая консолидация: ГК + отчётный период. ГСК фиксируется/создаётся при верификации по фактическому периметру. Уникальна по (ГК, год, квартал). v5.18: файлы, загруженные в консолидацию, — stored_file.consolidation_id (основа рабочего стола, общего для версий периода; полный состав — context/05-domain-rules.md §9.5 п. 11).	→ company_group, related_group; ← consolidation_version, stored_file	ТЗ 6.10, 7.2
consolidation_version	Версия консолидации: номер, статус, сценарий, подход, гудвилл, инициатор и его офис (маршрут), кто утвердил / верифицировал, решение УОБ, отклонения от Методики, версия правил элиминации, ссылка на предыдущую. После VERIFIED — read-only.	→ consolidation, app_user, regional_office, self; ← всё в частях 07–08	ТЗ 5.1, 6.4, 6.10; макет
consolidation_status_history	Каждый переход статуса: из → в, кто, когда, комментарий (обязателен при возврате).	→ consolidation_version, app_user	ТЗ 6.10, 8.2
consolidation_lock	«Взять в работу»: кто редактирует версию, перехват с причиной (v5.16: без истечения по времени, OQ-119). Из макета — ANL-036.	→ consolidation_version, app_user	макет
consolidation_member	Периметр версии — зафиксированный список ЮЛ; is_head_entity для гудвилла.	→ consolidation_version, legal_entity	ТЗ 6.1, 6.10
consolidation_document	v5.13: какие документы (не файлы) участвуют в версии. Чек-лист = required_document_rule × периметр − consolidation_document. Переиспользование одного документа в нескольких версиях/периодах, монозаёмщики из ЕХ.	→ consolidation_version, document	ТЗ Прил. 2; ЕХ 7

Не хранятся (DECISION-5), считаются запросом по версии: сводная ОСВ, признак контрагента ГСК/ГК/Внешний, пары ВГО, шахматка, результирующая таблица ВГО.

Часть 08 — Корректировки, гудвилл, результат КФО

Сущность	Что это	Ключевые связи	Откуда
correction	Ручная корректировка ВГО: пара (правило + компания 1 + компания 2 — естественный ключ), ББ/ОФР, строки и суммы по Дт и Кт, дочерние строки для распределения, причина, обязательный комментарий, статус, номер версии (история — в аудите). КФО = свод − Σ корректировок.	→ consolidation_version, elimination_rule, legal_entity ×2, chart_of_account ×2, self	ТЗ 6.4, 6.8, Прил. 9
goodwill	Строка расчёта гудвилла: головная × дочерняя, доля владения, ФВ по 58.01, УК (1310) и добавочный капитал (1350 — вопрос методологам), гудвилл, «включить в КФО», комментарий.	→ consolidation_version, legal_entity ×2, app_user	ТЗ 6.7, Прил. 3 п.2, Прил. 8
kfo_result	Шапка результата КФО: когда посчитан, заморожен ли, ЧА и ВБ, выручка, прибыль, расхождения, пороги, обоснование, итог гудвилла.	→ consolidation_version (1:1); ← kfo_result_line	ТЗ 6.4, 6.8, Прил. 10
kfo_result_line	Строка консолидированного ББ/ОФР по коду ФСБУ 4/2023: сумма → авто-элиминация → корректировки → гудвилл → итог; «в т.ч. ВГО», источник, расхождение, комментарий.	→ kfo_result; ← kfo_result_line_company	ТЗ 6.4, Прил. 10; макет
kfo_result_line_company	Разрез строки КФО по компаниям периметра: сумма и доля.	→ kfo_result_line, legal_entity	ЕХ 6.6; макет
client_kfo_line	Сценарий «подтверждение КФО клиента»: по строке — значение и ВГО от клиента (ручной ввод), значение и ВГО банка, расхождение, причина.	→ consolidation_version, app_user	ТЗ 5.1, 6.10; макет

Часть 09 — Комментарии, аудит, Единое хранилище

Сущность	Что это	Ключевые связи	Откуда
comment	Полиморфный комментарий к объекту (документу, ячейке шахматки по ключу пары, строке КФО).	→ app_user; object_type + object_id без FK	ТЗ 6.3/6.4; макет
audit_event	Журнал действий (append-only): кто, когда, действие, раздел, объект, версия консолидации, before/after, результат, IP/браузер. Покрывает историю правок распознанных данных, корректировок, выгрузок, импорта справочников, входов, изменений матрицы прав (v5.13), подтверждения документов, изменений ЮЛ и пользователей (v5.14: LEGAL_ENTITY_CHANGE, USER_CHANGE).	→ app_user, consolidation_version	ТЗ 8.2, Прил. 2; макет
ex_snapshot	Срез ЕХ: одна ГСК на одну отчётную дату, версия, статус (актуальный/архив), когда и кем верифицирован и записан. Самодостаточен — на консолидацию ссылается только данными.	→ related_group, company_group, app_user, self; ← member, item	ЕХ ТЗ 6.2, 6.4, 5.3
ex_snapshot_member	Периметр среза на дату: ЮЛ с ИНН и наименованием на момент верификации.	→ ex_snapshot, legal_entity	ЕХ ТЗ 6.3
ex_snapshot_item	Содержимое среза. Два вида: исходный документ → ссылка на document (v5.13; скачать — через его файл) и всё производное → payload jsonb.	→ ex_snapshot, document, legal_entity	ЕХ ТЗ 5.2, 6.7

---

Как читать модель по сценарию «сформировать КФО»

1. Справочники (01–03): ГК → ЮЛ → ГСК/ГСЗ; план счетов; правила элиминации; что обязательно загрузить.
2. Создание консолидации (07): consolidation от ГК + период → consolidation_version → consolidation_member (периметр).
3. Загрузка (04): stored_file + s3_object → recognition_job (queued → NATS → сервис → результат в S3 → done) → ядро создаёт document на каждый ББ / ОФР / ОСВ по счёту, найденный в файле.
4. Разбор (05–06): ОСВ → osv_entry; ББ/ОФР → financial_statement_meta/column/line/value. Аналитик проверяет, правит, подтверждает документ; логические проверки — на лету; сопоставляет контрагентов (→ osv_entry.counterparty_id, legal_entity_alias). Чек-лист закрывается по document CONFIRMED.
5. Консолидация (вычисляется): сводная ОСВ, пары ВГО, шахматка — из osv_entry × периметр × правила. Аналитик вносит correction, заполняет goodwill, при сценарии подтверждения — client_kfo_line. Результат — kfo_result(_line).
6. Согласование (07): consolidation_status_history по маршруту; блокировка consolidation_lock. Что можно — решает role_permission + policy-слой по статусу/ЗО.
7. Верификация → ЕХ (09): ex_snapshot + member + item (документы по ссылке, остальное — payload). Версия → read-only. Всё это время — audit_event.

Открытые вопросы после v5.14

• Замечание 2 (osv_entry.parent_entry_id, какие строки ОСВ хранить) — отложено; затрагивает и аналитику «Парсинг ОСВ» п.11.
• Замена по-документно (одна ОСВ из файла с пятью) — сейчас не предусмотрена, замена файлом целиком. Если понадобится — superseded_by переезжает в document.
• Статус document.RECOGNIZED (ручная проверка не требуется по порогу) — подтвердить с аналитиками, нужен ли, или все документы проходят через NEEDS_CHECK → CONFIRMED.