arm-ka-docs/openspec/changes/unified-statement-normalization/design.md

# Единый алгоритм нормализации ББ/ОФР (scan-gateway и tabular-parser) — дизайн

Issue: arm-ka-docs#116. Статус: черновик, идёт разбор текущего процесса по шагам (brainstorming 17.10.2026).

## Цель

Нормализация результата распознавания форм ББ/ОФР в scan-gateway (PDF → ИС Сканирование) и в tabular-parser
(Excel) должна идти по одному алгоритму и отдавать единообразный результат, чтобы arm-core обрабатывал оба источника
одним кодом. Повод — старые ошибки распознавания (AURORA-1406, 1462, 1511, 1517, 1519, 1522, 1523, 1524, 1634):
разбор конвейера показал, что это не отдельные баги, а свойство конвейера (issue #116).

## Как работает сейчас

Процесс разбит на шаги, общие для обоих сервисов:

- **Шаг 0** — загрузка файла и доставка его до сервиса распознавания;
- **Шаг 1** — подготовка данных: разбор (ИС Сканирование) или чтение (парсер) сырых данных и базовая разметка —
  какие в файле формы, какого типа, где их шапка и таблица;
- **Шаг 2 и дальше** — дальнейшая обработка (раскладка колонок, строки, значения, проверки, статус) — ещё не описаны.

### Шаг 0. Загрузка и доставка до сервиса

Общая часть (arm-core):

1. Пользователь загружает файл в карточку ЮЛ или в консолидацию (`primary_files.upload_one`): тип файла — по расширению
   и сигнатуре (`domain/file_types.py`), дедуп по `(ЮЛ, sha256)`, файл — в S3, запись `stored_file` и
   `recognition_job` со статусом `queued`. Конвейер задания: Excel (xls / xlsx / xlsb) → `tabular`, PDF / PNG / JPG →
   `image`.
2. Публикатор outbox (`recognition_exchange.publish_pending`) собирает запрос `recognition-request` — `job_id`,
   `file_id`, `pipeline`, `file_type`, `original_name`, ссылка на файл в S3, `reply_deadline`, `attempt` — и публикует
   его в subject конвейера: `tabular` → `files.tabular_uploaded`, `image` → `files.img_uploaded` (имена задаются
   окружением). Срок ответа по умолчанию: OCR — 20 мин, парсер — 5 мин. Нет ack 30 с — повторная публикация, после трёх
   повторов задание уходит в `dlq`, файл — `ERROR`.

В сервисе (одинаково в scan-gateway и tabular-parser):

3. Запрос проверяется: JSON-объект, MAJOR версии контракта 1, `pipeline` свой (scan-gateway — только `image`), схема.
   Невалидный — `SCHEMA_MISMATCH` без ack. Повтор `job_id`, который уже в работе или обработан, — только повторный ack,
   второй обработки нет.
4. Ack `processing` публикуется до чтения S3; задание ставится в очередь сервиса.
5. Исходный файл читается из S3; не прочитан — `FILE_READ_ERROR`. scan-gateway дополнительно: бакет должен быть его
   единственным бакетом; если `reply_deadline` истёк до отправки — `TIMEOUT`.

**Итог шага 0:** у сервиса есть байты исходного файла и запрос (`file_type`, `original_name`, `reply_deadline`).

### Шаг 1. Подготовка данных

#### 1.1 Разбор и чтение сырых данных

**scan-gateway** (`core/worker.py`, `gateway/`) — разбор делает ИС Сканирование, не мы:

1. Файл пишется во «Входящие» горячей папки как `<job_id>.<ext>` (расширение — из `original_name`, нижний регистр; нет
   расширения — `RECOGNITION_FAILED`). Горячая папка недоступна — `RECOGNITION_FAILED`.
2. ИС распознаёт файл и кладёт в «Исходящие» `<job_id>/` **один или несколько json** — по одному на распознанный
   комплект отчётности.
3. Шлюз опрашивает каталог каждые `SCAN_POLL_SECONDS` (5 с). Набор готов, когда в нём есть `*.json` и имена и размеры
   не менялись `SCAN_SETTLE_SECONDS` (2 с). Срок ожидания — `min(reply_deadline, запись во «Входящие» +
   SCAN_TIMEOUT_SECONDS)` (1200 с); не дождались — `TIMEOUT`.
4. Склейка (`gateway/merge.merge_answers`): каждый json разбирается независимо, по возрастанию имени →
   `{job_id, files: [{name, response, parse_error}]}`; json, который не разобрался, получает `parse_error`. Склейка
   сохраняется в S3 как `raw/{job_id}.json` **до** нормализации (не сохранилась — `UNKNOWN_ERROR`). Затем, только при
   `SCAN_CLEANUP=true`, горячая папка очищается.

Что внутри одного json ИС (по реальным ответам `fixtures/ocr/*.json`, §11):

- корень `{file_uid, error {code, message}, data_ocr}`; успех — `error.code == ""`, ошибка — непустой код
  (`INVALID_DOCUMENT`, `RECOGNITION_FAILED`, …), тогда таблиц нет;
- `data_ocr`: поля шапки `label`, `organization`, `inn`, `units`, `date` — каждое `{form_name, confidence}`, сырой
  OCR-текст; **шапка одна на json**;
- `data_ocr.table_structure[]` — таблицы форм, каждая `{label {form_name, confidence}, rows[]}`; строка — `{row_index,
  cells[]}`, ячейка — `{column_index, value, confidence}` (сырой текст, уверенность 0–100; `column_index` не обязательно
  подряд).

Наблюдается: json с таблицами содержит **ББ и ОФР одного периода** под общей шапкой (`aep_3`, `aep_6`, `БО 1 кв 2025`,
`Бухгалтерская отчетность 1 кв.25`). **Допущение владельца (17.10.2026):** если в файле отчётность за несколько
периодов, ИС отдаёт её разными json; образца нет — проверить на первом таком файле.

**tabular-parser** (`parser/book.py`, `parser/readers/`) — чтение делает сам парсер:

1. Размер файла больше `PARSE_MAX_BYTES` (50 МБ) — `UNSUPPORTED_FORMAT`. Отсчёт `PARSE_TIMEOUT_SECONDS` (120 с) — от
   начала разбора.
2. Формат определяется **по сигнатуре байтов**, а не по `file_type` запроса: OLE2 → XLS, zip с `xl/workbook.bin` → XLSB,
   иной zip → XLSX, прочее — `UNSUPPORTED_FORMAT`. Несовпадение с `file_type` — предупреждение. До чтения проверяются
   лимиты: распакованный размер zip, площадь объединённых ячеек.
3. Книга читается в листы `Sheet`: только непустые ячейки (текст, значение, числовой формат), объединённые диапазоны,
   уровни группировки строк, габариты. Библиотека чтения упала — `UNREADABLE`. У xlsb стили и группировка не читаются —
   предупреждение.

#### 1.2 Базовая разметка

**scan-gateway** (`normalizer/ocr/__init__.py`, `header.py`) — разметку уже сделала ИС, шлюз её только принимает:

1. json набора обходятся по порядку. Ошибочный json (`parse_error`, непустой `error.code`, корень не объект) —
   предупреждение `<имя>: <код>: <сообщение>`, json пропускается. Все json ошибочны — `error` с кодом первого.
2. Шапка json — из полей `data_ocr`: ИНН — только цифры, организация, дата (замена букв-двойников + разбор даты),
   единицы; у каждого поля — уверенность ИС. Предупреждения уровня файла: «ИНН не распознан», «ИНН распознан
   неуверенно», «дата отчёта не разобрана». **Шапка общая для всех таблиц json.**
3. Каждая таблица `table_structure[i]` — кандидат в документ формы. Тип — по `label` (`rules/statement_labels.yaml`);
   уточнение типа по кодам строк сейчас делается позже, в шаге 2 (после разбора строк).

**tabular-parser** (`parser/detect.py`, `parser/statements/detect.py`, `header.py`) — разметку делает парсер, всё по
содержимому (§12 п. 1, п. 6):

1. Вид каждого листа: признак ведомости в первых 30 строках — **ОСВ** (дальше свой путь, в этом change не
   рассматривается); иначе заголовок формы или ОКУД — **форма**; маркер «Форма … с.2», шапка «Код» с периодами или
   колонка кодов — **продолжение**; лист с 1–2 кодами сразу после листа формы — тоже продолжение; остальное —
   **прочее** (предупреждение «нет признаков ОСВ или формы»).
2. Формы на листе (`find_forms`): строки с заголовком («Бухгалтерский баланс», «Отчет о финансовых результатах», «…о
   прибылях и убытках») или ОКУД — кандидаты; кандидаты без строк с кодами между ними сливаются, заголовок после кодов
   открывает новую форму (две формы на одном листе). Тип — по ОКУД (0710001 → `BALANCE`, 0710002 → `INCOME`, прочие
   0710xxx и «Пояснения…» → `DISCLOSURE`); заголовок и ОКУД противоречат — тип по ОКУД и предупреждение. Результат —
   блок формы: тип, `form_name`, `okud`, границы строк.
3. Шапка — **своя у каждой формы**, ищется в границах её блока: организация, ИНН (без ИНН аудитора), ОКПО, ОКОПФ, ОКФС,
   единицы, дата отчёта, адрес; найденное поле — уверенность 100, не найденное — `null`; предупреждения «в шапке не
   найдена организация», «в шапке не найдена единица измерения».
4. Листы-продолжения присоединяются к последней открытой форме — но решение требует раскладки колонок (совпадает ли
   число колонок сумм), поэтому фактически выполняется в шаге 2.

**Итог шага 1:** у обоих сервисов есть список кандидатов в документы форм — тип, шапка и сырые строки таблицы.

#### Различия на выходе шага 1

| | scan-gateway | tabular-parser |
|---|---|---|
| Кто размечает | ИС Сканирование | парсер, по содержимому |
| Единица разметки | json (комплект одного периода) → таблицы | книга → листы → блоки форм |
| Шапка | одна на json, общая для его таблиц | своя у каждой формы |
| Тип формы | `label` таблицы (уточнение по кодам — в шаге 2) | ОКУД, иначе заголовок |
| Уверенность | у каждого поля шапки и каждой ячейки, 0–100 | нет (найдено — 100) |
| Многостраничная форма | одна таблица = одна форма, склейки нет | листы-продолжения присоединяются (в шаге 2) |
| Ячейка | сырой OCR-текст | текст, значение и числовой формат |