From e92840fe7dc413822f9635328412d517bc749981 Mon Sep 17 00:00:00 2001 From: Andrey Epifancev Date: Sat, 17 Oct 2026 15:05:31 +0400 Subject: [PATCH] =?UTF-8?q?docs(#116):=20=D1=86=D0=B5=D0=BB=D0=B5=D0=B2?= =?UTF-8?q?=D0=B0=D1=8F=20=D0=BA=D0=B0=D1=80=D1=82=D0=B8=D0=BD=D0=B0=20?= =?UTF-8?q?=D0=BF=D0=BE=20=D1=88=D0=B0=D0=B3=D0=B0=D0=BC=201=E2=80=939=20?= =?UTF-8?q?=E2=80=94=20=D0=B5=D0=B4=D0=B8=D0=BD=D1=8B=D0=B9=20=D0=B2=D1=8B?= =?UTF-8?q?=D1=85=D0=BE=D0=B4=20=D0=BA=D0=B0=D0=B6=D0=B4=D0=BE=D0=B3=D0=BE?= =?UTF-8?q?=20=D1=88=D0=B0=D0=B3=D0=B0=20=D0=B8=20=D1=80=D0=B5=D1=88=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D1=81=D1=82=D1=80=D0=BE?= =?UTF-8?q?=D0=BA=D0=B0=D0=BC=20=D1=80=D0=B0=D0=B7=D0=BB=D0=B8=D1=87=D0=B8?= =?UTF-8?q?=D0=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5.1 --- .../unified-statement-normalization/design.md | 201 ++++++++++++++++-- 1 file changed, 187 insertions(+), 14 deletions(-) diff --git a/openspec/changes/unified-statement-normalization/design.md b/openspec/changes/unified-statement-normalization/design.md index 5bad7ee..28dadd3 100644 --- a/openspec/changes/unified-statement-normalization/design.md +++ b/openspec/changes/unified-statement-normalization/design.md @@ -1,6 +1,7 @@ # Единый алгоритм нормализации ББ/ОФР (scan-gateway и tabular-parser) — дизайн -Issue: arm-ka-docs#116. Статус: черновик, идёт разбор текущего процесса по шагам (brainstorming 17.10.2026). +Issue: arm-ka-docs#116. Статус: черновик; текущая цепочка описана, целевая картина по шагам 1–9 — предложение, ждёт +решений владельца Р-1…Р-6 (brainstorming 17.10.2026). ## Цель @@ -314,19 +315,191 @@ sheet:,`. `DISCLOSURE` и форма без колонки кодов — ## Целевая картина -### Шаг 1 — решения владельца по различиям (17.10.2026) +Каждый шаг ниже: **вход = выход предыдущего шага**, единый выход для обоих сервисов, таблица «различие → к чему +приводим → что меняется в scan-gateway → что меняется в tabular-parser». Решения владельца помечены датой; остальное — +предложение (17.10.2026), решения, которые нужны от владельца, собраны в конце (Р-1…Р-6). Имена полей — рабочие, +уточняются при написании спеки. -1. **Кто размечает** — различие остаётся: у шлюза разметку делает ИС, у парсера — сам парсер. Это природа источников. -2. **Единица разметки** — на выходе шага 1 у обоих сервисов **одинаковый контракт**. Форма контракта (json или - промежуточные объекты в коде сервиса) — решается отдельно. -3. **Шапка** — у **каждой таблицы своя**. Шлюз отдаёт шапку json каждой его таблице. -4. **Тип формы** — определяется **единым подходом** в обоих сервисах (правило — открытый вопрос). -5. **Уверенность** — есть и у парсера, всегда 100: формат один, значение у Excel-пути постоянное. -6. **Многостраничная форма** — парсер **склеивает листы-продолжения в шаге 1**; на выходе шага 1 одна форма — одна - таблица, как у ИС. -7. **Ячейка** — **один общий формат** для обоих сервисов (состав — открытый вопрос). +Принципы, из которых выведены решения по строкам: -Открытые вопросы шага 1: форма контракта (п. 2), правило типа формы (п. 4), формат ячейки (п. 7), как парсеру склеивать -продолжения до шага 2 (п. 6: сейчас склейка опирается на раскладку колонок). +1. **Один выход на шаг.** Код, зависящий от источника, живёт только в шаге 1 (адаптеры «json ИС → кандидат», «лист + Excel → кандидат»). Шаги 2–8 — общий код с общими словарями (форма общего кода — Р-1). +2. **Ничего не выбрасывать молча.** Строка, колонка или ячейка, которую не удалось истолковать, идёт дальше со + статусом, а не превращается в счётчик; пользователь её видит и исправляет. +3. **Качество — структурно и с привязкой к месту:** уверенность ячейки (от источника), `is_recognized` (разбор числа), + статус строки, нарушения §7 по ячейкам, предупреждения с уровнем и привязкой. Статус документа сервис выводит из + них сам; ядро не пересчитывает. +4. **Один словарь — одно место:** строки форм, проверки §7, периоды, заголовки форм, диапазоны кодов. -Шаги 2–8 целевой картины — по ходу brainstorming, по той же схеме: решение по каждой строке таблицы различий. +### Шаг 1 — Подготовка данных + +**Решения владельца (17.10.2026):** 1) кто размечает — различие остаётся; 2) на выходе одинаковый контракт; +3) шапка своя у каждой таблицы; 4) тип формы — единый подход; 5) уверенность есть и у парсера, всегда 100; +6) парсер склеивает продолжения в шаге 1; 7) ячейка — один формат. + +**Вход:** байты файла (шаг 0). + +**Единый выход:** список кандидатов в форму на файл, `FormCandidate`: + +- `source` — `ocr` | `excel`; +- `locator` — откуда взят (имя json и номер таблицы / имена листов); +- `type_hint` — `BALANCE` | `INCOME` | `DISCLOSURE` | `null`, по единому правилу (п. 4); +- `evidence` — ОКУД и заголовок как ячейки (для сверки с кодами в шаге 6); +- `header` — поля `header` контракта (`organization_name`, `inn`, `report_date`, `units`, `okud`, `okpo`, `okopf`, + `okfs`, `address`), каждое — ячейка или `null`; +- `rows` — плотная сетка строк × ячеек; все страницы и листы формы уже в одной сетке; пустая позиция — `null`; +- `warnings` — предупреждения шага (формат — шаг 8). + +Ячейка `Cell` одна для шапки и таблицы: `text` (как показывает источник), `value` (число или дата, если источник их +знает; у OCR — `null`), `confidence` 0–100 (у Excel — 100), `ref` (позиция в источнике для сообщений: `row_index` / +`column_index` у OCR, адрес A1 у Excel). + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Кто размечает | остаётся, фиксируется полем `source` | — | — | +| 2 | Единица разметки | файл → список кандидатов; шаги 2–8 работают только с кандидатом (Р-1 — форма общего кода) | адаптер «таблица json → кандидат» | адаптер «блок формы на листе → кандидат» | +| 3 | Шапка | у каждого кандидата своя; поля = поля `header` контракта, каждое — `Cell`; разбор текста поля (ИНН → цифры, дата → `date`, единицы → словарь) — общий код по `text` | шапку json копирует в каждую свою таблицу | добавляет сырой текст и уверенность 100 | +| 4 | Тип формы | одно правило: ОКУД → заголовок по одному словарю → `null`; окончательно — по кодам строк в шаге 6, у обоих | `label` таблицы становится заголовком; `statement_labels.yaml` уходит в общий словарь | добавляет сверку по кодам (шаг 6) | +| 5 | Уверенность | поле `Cell.confidence`; Excel всегда 100 | — | добавляет поле | +| 6 | Многостраничная форма | одна форма = одна сетка на выходе шага 1; строки продолжения дописываются в конец сетки по маркеру «Форма … с.2» или по позиции листа; проверка «число колонок сумм совпало» из склейки уходит (повторная шапка внутри сетки — правило шага 2, общее для обоих: у OCR она и так внутри таблицы); тип из маркера сверяется с `type_hint`, расхождение — отдельный кандидат + предупреждение | — | склейка переезжает до раскладки; `join_blocker` остаётся только по типу | +| 7 | Ячейка | один формат `Cell`; Excel: `text` — как показывает числовой формат, `value` — число по формату (tp#42; формат не разобран — сырое значение + предупреждение); OCR: `text` сырой, `value` `null`, `confidence` от ИС | обёртка над `value` + `confidence` ИС | отображаемый текст и значение считаются здесь, а не в шаге 4 | + +### Шаг 2 — Раскладка таблицы + +**Вход:** `FormCandidate` (сетка, `type_hint`). + +**Единый выход:** `TableLayout` — столбец кода, столбец наименования, колонки значений `[{col, label, period_end}]`, +роль каждой строки сетки (`header` | `numbering` | `data`), сегменты (участки сетки между повторными шапками, у +каждого своя раскладка колонок). + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Что считается кодом при поиске столбца | одно правило: 4–5 цифр (допускается `.0`), первые четыре — в диапазонах словаря кодов всех форм (`type_hint` неизвестен — объединение диапазонов); столбец с наибольшим числом кодов, кодов ≥ 3, доля среди непустых ≥ порога; нет — «колонка кодов не найдена» | `int(text)` → правило словаря (закрывает AURORA-1517 вместе с п. 5) | диапазон формы → объединение; `relaxed` для одиноких продолжений не нужен (они склеены в шаге 1) | +| 2 | Повторная шапка внутри таблицы | одно правило: строка внутри сетки с признаком шапки («Код» / та же сигнатура) открывает новый сегмент; у сегмента своя раскладка (позиции колонок могут сдвинуться); колонки значений сегментов сопоставляются по порядку; число не совпало — предупреждение, значения по позиции | как сейчас, через общее правило | добавляет: бывший «лист-продолжение со своей раскладкой» становится сегментом | +| 3 | Дата колонки | один словарь периодов (`statement_periods.yaml`) → `period_end`; перед разбором — очистка двойников OCR (общий шаг, у Excel не срабатывает) | `parse_date` «размером с дату» → словарь | добавляет очистку двойников (no-op) | +| 4 | Без шапки | одно правило: строка заголовка не найдена → колонки значений = столбцы правее кода, где в строках с кодами стоят числа; `label` пустая, `period_end` `null`; одно предупреждение «строка заголовка не найдена» | синтез шапки уходит (он эквивалентен) | добавляет предупреждение | +| 5 | Строка нумерации «1 2 3 4 5» | одно правило `is_numbering_row` → роль `numbering`, в данные не попадает | добавляет (AURORA-1517) | как сейчас | +| 6 | Подпись без периода | одно правило: подпись — период по словарю → колонка с датой; подпись из словаря исключений («Изменение», «Отклонение», «%», «Темп», «Доля») → пропуск с предупреждением info; иначе, если в столбце есть числа в строках с кодами — колонка без даты + предупреждение (Р-6); иначе пропуск | добавляет словарь исключений | перестаёт молча пропускать неизвестные числовые колонки | + +### Шаг 3 — Отбор строк данных + +**Вход:** `FormCandidate` + `TableLayout`. + +**Единый выход:** `RawLine[]` — по строке на каждую строку сетки с ролью `data`, у которой есть код или хотя бы одно +число: `ref`, ячейка кода, `code_status` (`ok` | `unreadable` — код есть, но не разобран | `missing` — кода нет, суммы +есть | `duplicate` — код уже встречался), ячейка наименования, ячейки значений по колонкам раскладки. Строка без кода +и без чисел (заголовок раздела «АКТИВ», «в том числе:») — не строка. Счётчиков отброшенных нет — есть статусы. + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Код-мусор | статус `unreadable`, строка сохраняется с сырым текстом кода (AURORA-1462: «ИЧ,250» видна, аналитик назначает 1250) | счётчик → статус | отличает «нет кода» от «не разобран» | +| 2 | Склейка двух строк в одну | одно правило: ячейка кода содержит N кодов через перевод строки и ячейки значений — N частей → N строк (OQ-156); у Excel не срабатывает | как сейчас, через общее правило | правило общее, no-op | +| 3 | Повтор кода | статус `duplicate` у второй и последующих строк; строки сохраняются; текстовое предупреждение и `checks.duplicate_line_codes` уходят; что показывать и как считать — ядро (Р-4) | «оставлена первая» → обе строки | `duplicates` → статус | +| 4 | Отброшенная строка | строки не отбрасываются: `unreadable` / `missing` / `duplicate` идут дальше со статусом (AURORA-1634, 1462, 1406); ядро не достраивает вместо них пустую шаблонную строку молча | счётчики → статусы | счётчики → статусы | + +### Шаг 4 — Значения ячеек + +**Вход:** ячейки значений `RawLine` по колонкам раскладки (`Cell` или `null`). + +**Единый выход:** `StatementValue {column_index, amount, string_value, confidence, is_recognized}` — как в контракте, +с одним смыслом полей у обоих. + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Предобработка текста | у ячейки после шага 1 либо есть `value`, либо только `text`. `value` есть → `amount = value` (2 знака), `is_recognized = true`. `value` нет → один `parse_amount(text)` для обоих: двойники, разделители тысяч, скобки → минус, прочерк → `null`; Excel-ячейки «число текстом» идут тем же путём | `parse_amount` переезжает в общий код | `to_money` заменяется общим `parse_amount` | +| 2 | Смысл `is_recognized` | один: текст разобран как число без выброшенных и исправленных символов; `confidence` — отдельно, от источника; экран подсвечивает по любому из двух (как сейчас) | отвязывает от `confidence` | как сейчас | +| 3 | «42831 1» | в `parse_amount` пробел допустим только как разделитель тысяч (группы ровно по три цифры); иначе `amount` — лучшая догадка (цифры подряд), `is_recognized = false`, `string_value` — сырой текст (AURORA-1511, 1519) | меняется через общий код | то же правило, у Excel почти не срабатывает | +| 4 | Единицы | одно правило: единицы «тыс. руб.» и дробных ≥ 10 % → предупреждение документа | добавляет | как сейчас | +| 5 | Пустая ячейка | одно правило: позиции нет, текст пуст или прочерк → `amount = null`, `string_value = null`, `is_recognized = true`, `confidence` ячейки (нет ячейки — 100). Потерянную OCR-ячейку ловят проверки §7 (Р-2) | «ячейки нет → 0, не распознано» уходит | как сейчас | + +### Шаг 5 — Код, наименование, редакция + +**Вход:** `RawLine` (статус, ячейки кода и наименования) + `StatementValue[]`. + +**Единый выход:** `StatementLine {line_status, line_code, line_code_text, line_code_confidence, line_name, +line_name_confidence, values}`: `line_code` — разобранный код (4–5 цифр) или `null` при `unreadable` / `missing`; +`line_code_text` — сырой текст ячейки кода; `line_status` = `code_status` шага 3. + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Источник наименования | одно правило: наименование — из файла, с уверенностью источника; справочник наименование не подменяет. Справочное имя по коду и редакции добавляет ядро из своего (единственного) словаря, экран показывает справочное, файловое — рядом (Р-3; AURORA-1406, 1522) | имя из `statement_lines.yaml` → имя из OCR | как сейчас | +| 2 | Редакция (66н / ФСБУ 4) | в сервисах не определяется; редакция — свойство словаря строк (по дате отчёта), используется в шаге 7 (проверка «код не из редакции формы») и в ядре при достройке шаблонных строк | `_choose_edition` уходит | — | +| 3 | Справочник строк | один словарь строк (в общем коде, Р-1); копия в шлюзе удаляется | удаляет `api/rules/statement_lines.yaml` | — | +| 4 | Уверенность кода | от источника (ИС / 100), без срезания до 99 по справочнику; «не в справочнике» — предупреждение к строке в шаге 7 | убирает `min(conf, 99)` | как сейчас | + +### Шаг 6 — Сборка документа + +**Вход:** `FormCandidate` (`type_hint`, `evidence`, `header`) + `TableLayout` + `StatementLine[]`. + +**Единый выход:** `StatementDocument {document_type, locator, header, columns, lines}` без `checks`. + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Тип формы | одно правило: большинство кодов 1xxx → `BALANCE`, 2xxx → `INCOME`; совпало с `type_hint` или `type_hint` `null` — тип по кодам; противоречит — тип по кодам + предупреждение; кодов нет — `type_hint`; без колонки кодов: `type_hint` есть → документ без строк (`DISCLOSURE` — `done`, иначе `needs_check`), `type_hint` нет → не документ, предупреждение info | как сейчас, через общее правило | добавляет сверку с кодами | +| 2 | Склейка страниц | решена в шаге 1, различия нет | — | — | +| 3 | `locator` | одна грамматика «пары `ключ:значение` через `;`», набор ключей по источнику: `json:<имя>;table:` / `sheet:[,]` | — | — | + +Шапка документа — поля `header` кандидата как есть (`text` → `*_text`, `value` → поле, `confidence` → `*_confidence`). + +### Шаг 7 — Самопроверки + +**Вход:** `StatementDocument`. + +**Единый выход:** `StatementChecks` у обоих: `relations_failed[]`, `soft_relations_failed[]` (каждое нарушение — с +кодами слагаемых и `column_index`, чтобы экран подсветил ячейки), `line_warnings[]` (код не из редакции формы по дате +отчёта, код не в словаре). `duplicate_line_codes` уходит в `line_status`. + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Проверки только у парсера; словарь §7 в двух копиях; ядро результат не читает | проверки — общий код с одним словарём `statement_checks.yaml` у обоих сервисов; для OCR нарушение §7 — главный признак неверно прочитанной цифры; ядро читает `checks` из результата и пересчитывает тем же кодом только после правок аналитика (PATCH) | добавляет шаг | `run_statement_checks` → общий код | + +### Шаг 8 — Статус и предупреждения + +**Вход:** `StatementDocument` + `StatementChecks` + предупреждения шагов 1–7. + +**Единый выход:** у каждого документа `status` (`done` | `needs_check`) и `warnings[]`; у файла `metrics.warnings[]`; +статус конверта — агрегат. Предупреждение — структура `{code, severity: error | info, message, line_ref?, +column_index?}`, а не строка. + +| № | Различие | Приводим к | scan-gateway | tabular-parser | +|---|---|---|---|---| +| 1 | Критерий `done` | один критерий из самого результата: раскладка найдена ∧ (организация или ИНН) ∧ дата отчёта ∧ все строки `ok` ∧ все значения `is_recognized` ∧ `confidence` всех ячеек ≥ порога (Р-5) ∧ жёсткие проверки §7 сошлись ∧ нет предупреждений уровня `error`. Excel выполняет условия уверенности автоматически | «ничего не выброшено и уверенность 100» → общий критерий | `_is_ok` → общий критерий; добавляются строки и значения | +| 2 | Влияние предупреждений | по уровню: `error` → `needs_check`, `info` — не влияет; у обоих одинаково | «любое → `needs_check`» уходит | предупреждения начинают влиять | +| 3 | Статус документа | в контракте: `document.status`; конверт `done` ⇔ все документы `done` ∧ нет предупреждений файла уровня `error`; иначе `needs_check`; документов нет — `error` (как сейчас) | добавляет | внутренний `ok` → в контракт | +| 4 | Формат предупреждений | структура (см. выше) вместо строк `: table:: …` / `sheet=<имя> …`; место — в `locator` документа, а не в тексте | меняет | меняет | +| 5 | Привязка | к документу, строке (`line_ref`) или ячейке (`line_ref` + `column_index`); экран показывает у места | меняет | меняет | + +### Шаг 9 — Результат + +Одинаково, как сейчас; контракт `recognition-result.schema.json` → **v1.3**: `line_status`, `line_code` nullable, +`line_code_text`; `document.status`; `document.warnings[]` и `metrics.warnings[]` структурные; `checks` обязателен для +`BALANCE` / `INCOME` у обоих конвейеров, нарушения с кодами слагаемых; `line_warnings`. + +### Что уходит из ядра + +- `build_statement`: повторная дедупликация колонок, кодов и значений (контракт гарантирует уникальность колонок; + повторы строк приходят со статусом `duplicate`). +- `statement_status` (D-6): `RECOGNIZED` ⇔ `document.status = done` ∧ ИНН ≠ `MISMATCH` (единственное знание ядра); + остальные признаки D-6 не пересчитываются. +- §7 при загрузке: `checks` берутся из результата; пересчёт общим кодом — только после PATCH. +- Словарь строк и словарь §7: единственный экземпляр в общем коде (Р-1); копии ядра и шлюза удаляются. +- Достройка шаблонных строк: по тому же словарю; строки `missing` / `unreadable` / `duplicate` показываются как + пришли, с подсветкой. +- Экран: подсветка ячеек по `confidence`, `is_recognized` и нарушениям §7 (по кодам слагаемых и колонке); строк — по + `line_status`; предупреждения документа — с привязкой к месту. + +### Решения, которые нужны от владельца + +- **Р-1** (шаг 1, п. 2) — форма общего кода: общий Python-пакет с dataclass-ами (сериализуемыми в json — golden-файлы + выхода шага 1 в fixtures), шагами 2–8 и словарями, который подключают оба сервиса и ядро (рекомендация); запасной + вариант, если платформа не даст ставить пакет из git или зеркала, — копия по скрипту, как `sync-web.sh`. +- **Р-2** (шаг 4, п. 5) — отсутствующая OCR-ячейка под колонкой: чистый `null` (предложение; потерю ловит §7) или + подсветка «не распознано», как сейчас (больше ложных подсветок, AURORA-1524). +- **Р-3** (шаг 5, п. 1) — наименование: из файла в сервисах, справочное — в ядре (= решение № 2 по спринту 2, + AURORA-1406 / 1522; договорённость ДБД «из справочника» выполняется на экране). +- **Р-4** (шаг 3, п. 3) — повторы кодов: сервисы отдают обе строки со статусом; показ обеих и сумма по договорённости + ДБД (AURORA-1431) — в ядре и на экране. +- **Р-5** (шаг 8, п. 1) — порог уверенности для `done` (= решение № 7 по спринту 2, AURORA-1519 / 1524); предложение — + 100, как сейчас. +- **Р-6** (шаг 2, п. 6) — неизвестная числовая колонка без периода: оставлять без даты с предупреждением (`needs_check`) + или пропускать, как парсер сейчас.