arm-core/openspec/changes/slice-3b-statements-api/proposal.md

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).