# Proposal: Срез 3b — формы ББ/ОФР в ядре и API до сводной ОСВ

**Срез:** 3b — вторая половина Среза 3 «ББ/ОФР: scan-gateway, маппинг форм, логические проверки, подтверждение
документа» (`../docs/context/09-delivery-plan.md`). **Репозиторий:** arm-core. **Issue:** RSHB/arm-core#36.
**Соседние:** Срез 3a (scan-gateway, `statementDocument` из OCR, закрыт 07.10.2026), Срез 2b (tabular-parser, формы из
Excel, контракт v1.2). Документация — bounded-PR в docs (§7, §9.5, OQ, `03-architecture.md`, `09-delivery-plan.md`), без
сквозного change: контракт и DBML не меняются. Объём по решению владельца 07.10.2026: **весь API пути пользователя до
сводной ОСВ включительно**; UI делает другой разработчик по этим спекам.

## Why

Оба сервиса распознавания отдают формы ББ/ОФР (`statementDocument` контракта v1.2), а ядро их игнорирует: документы
`BALANCE`/`INCOME` не создаются, `financial_statement_*` пусты, а файл, где есть только формы (выгрузка ББ/ОФР из 1С,
скан PDF), падает в `ERROR` с «в результате нет документов ОСВ». Поэтому столбцы «Бух. баланс» и «ОФР» чек-листа никогда
не закрываются, экрана «Проверка распознавания» нечем кормить, а консолидация не может стартовать по правилам
`required_document_rule`. Сверка пользовательского пути (`10-user-journey.md`, пути 1–2 и шаг 3.1) с API нашла и
мелкие дыры: нет отдачи исходного файла, комментариев к документу, имён пользователей для не-админов, числа документов
у ЮЛ и CSV чек-листа.

## What Changes

- **Маппинг форм** (`osv-result-mapping`): в той же транзакции `map_file` после листов ОСВ каждый `statementDocument`
  `BALANCE`/`INCOME` становится `document` + `financial_statement_meta` + `financial_statement_column` +
  `financial_statement_line` + `financial_statement_value` (значение на каждую пару «строка × колонка»); период — по дате
  отчёта, без неё — по самой поздней дате колонок; `counterparty_check` — как у ОСВ; `DISCLOSURE`/`OTHER` — один документ
  на тип на файл без данных. Файл без ОСВ, но с формами — не ошибка; ошибка — только пустой результат.
- **Проверки §7** (новая спека `statement-checks`): чистые функции `domain/statement_checks.py` — перенос проверок
  tabular-parser (допуск ±1, округление 0,001 %, `abs_terms`, подстроки) со словарём `api/rules/statement_checks.yaml`;
  межформенная `1370 − 1370(начало года) = 2400` — мягкая. Результат не хранится; акцепт непройденных жёстких проверок
  с комментарием — `checks_accepted_*`.
- **API формы** (`documents-api`): `GET /documents/{id}/statement` (шапка с исходниками и признаками правки, редакция
  формы, колонки, строки со значениями, проверки), `PATCH /documents/{id}/statement` (значения и ИНН / дата отчёта /
  единицы; исходники сохраняются, `audit_event(RECOGNIZED_DATA_EDIT)`, пересчёт проверок и статуса, сброс акцепта),
  `POST /documents/{id}/statement/checks/accept`. Подтверждённая форма — только для чтения (решение владельца).
- **Подтверждение ББ/ОФР**: дополнительно требует пройденных или акцептованных жёстких проверок и определённого периода;
  пишет `financial_statement_meta.reviewed_by/at`. Привязка к версиям и переходы статуса версии — без изменений.
- **Мелкие дыры**: `GET /files/{id}/content` (поток исходного файла из S3 через ядро), комментарии
  `POST/GET /documents/{id}/comments` (таблица `comment`) и `comments_count` в карточке документа,
  `GET /users/brief?ids=` для любого аутентифицированного пользователя, `documents_count` в списке ЮЛ,
  `GET …/checklist?format=csv`.

## Таблицы DBML v5.16

Пишутся: `document` (типы `BALANCE`, `INCOME`, `DISCLOSURE`, `OTHER`), `financial_statement_meta`,
`financial_statement_column`, `financial_statement_line`, `financial_statement_value`, `comment`, `audit_event`.
Читаются: `stored_file`, `s3_object`, `recognition_job`, `legal_entity`, `legal_entity_alias`, `app_user`,
`consolidation_*`, `required_document_rule`. Новых таблиц, колонок и значений enum нет; миграции нет.

## Параграфы `05-domain-rules.md`

§7 (логические проверки, акцепт), §9.3 (статус документа), §9.5 (маппинг, подтверждение), §11 и §11.1 (форма из OCR),
§12 (форма из Excel; п. 5 — повтор кода, п. 7 — самопроверка), §2 и §3 п. 1 (период и привязка к версии). Правила,
которых в `05` нет и которые вводит этот change (будут дописаны в §7 и §9.5 bounded-PR docs): период ББ/ОФР по самой
поздней дате колонок при пустой дате отчёта; межформенная проверка мягкая; правка формы только до подтверждения;
условия подтверждения ББ/ОФР.

## Допущения по открытым вопросам

- ASSUMPTION(OQ-12, OQ-146): формулы §7 одни для редакций `66n` и `fsbu4`; варианты ФСБУ 4/2023 для 2400 — мягкие.
- ASSUMPTION(OQ-23): `DISCLOSURE` только хранится — документ без данных.
- ASSUMPTION(OQ-36, OQ-141, OQ-149): строки без кода не хранятся (их нет в результате).
- ASSUMPTION(OQ-77): вторая форма того же типа в файле не создаётся; первая — `NEEDS_CHECK` с предупреждением.
- ASSUMPTION(OQ-140): страницы формы из разных файлов не склеиваются.
- ASSUMPTION(OQ-145): редакцию формы ядро определяет само по дате отчёта; контракт не меняется.

## Non-goals

- UI (экраны делает другой разработчик).
- Правка строк ОСВ, добавление и удаление строк формы, правка кода и названия строки.
- Отмена подтверждения документа (исправление — новым файлом через автозамену).
- Шахматка, корректировки, КФО, ЕХ, журнал действий, «Добавить версию» (Срезы 5–7).
- Изменение контракта и DBML; хранение результатов проверок; разбор расшифровок.
- Заполнение редакции `fsbu4` и словарей по редакциям (OQ-146).