dd454983e6
proposal, design (D-1…D-14, решения без обсуждения №1–10), дельты osv-result-mapping (маппинг форм, статус), statement-checks (новая: §7, межформенная, акцепт), documents-api (форма, правка, акцепт, подтверждение, комментарии, исходный файл), consolidations-api (CSV чек-листа), directories-api (documents_count), users-admin (справочник имён). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012vJkmBGKKqMoEMzvsXG3y2
74 lines
8.0 KiB
Markdown
74 lines
8.0 KiB
Markdown
# 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).
|