arm-core/openspec/specs/osv-result-mapping/spec.md

osv-result-mapping Specification

Purpose

Маппинг файла результата распознавания (recognition-result.schema.json v1.x, osvDocument) в document и osv_entry отдельным фоновым циклом (§1.3, §1.5, §3 п. 4, §9.3); резолв счетов и контрагентов; проверки шапки; статус документа.

Requirements

Requirement: Цикл маппинга отделён от inbox

Фоновая задача ядра SHALL с периодом MAPPING_POLL_SECONDS (5) выбирать одно задание со status ∈ {done, needs_check}, чей файл имеет status = PROCESSING и current_recognition_job_id = это задание (FOR UPDATE SKIP LOCKED), проверять, что result_s3_object относится к бакету хранилища и его ключ начинается с results/{file_id}/{job_id}/ (OQ-70), читать объект из S3 вне транзакции, валидировать RecognitionResult v1.x и в одной транзакции создать документы и строки (листы ОСВ и формы ББ/ОФР), записать recognition_job.group_schema, перевести файл в PROCESSED и выполнить автозамену. Результат без документов SHALL давать неповторяемую ошибку маппинга «в результате нет документов»; результат с формами, но без ОСВ, ошибкой MUST NOT быть. Inbox MUST NOT читать файл результата и MUST NOT создавать документы.

Scenario: Результат смапплен

• WHEN в S3 лежит результат парсера для rb/2024-FY/ОСВ_66 за 2024.xls, задание done, файл PROCESSING
• THEN не позднее чем через MAPPING_POLL_SECONDS + время маппинга файл — PROCESSED, создан один document (OSV, osv_account_code = "66", period_year = 2024, period_quarter = Q4, is_cumulative = true, locator = sheet:Лист_1), osv_entry — все строки результата кроме TOTAL, group_schema задания содержит [{"locator": "sheet:Лист_1", "groups": [...]}]

Scenario: Ключ результата вне папки задания

• WHEN result_s3_object.key = results/<другой file_id>/.../result.json
• THEN файл — ERROR с ошибкой маппинга, документы не созданы, повтор не выполняется

Scenario: Сбой маппинга с повтором

• WHEN вставка строк падает по ошибке БД
• THEN транзакция откачена, metrics.mapping_attempts = 1, файл остаётся PROCESSING; на третьей неудаче — ERROR с metrics.mapping_error

Scenario: Повторный маппинг идемпотентен

• WHEN маппинг прерван после частичной вставки (имитация) и выполнен снова
• THEN у файла ровно один набор документов и строк, дублей по (document_id, row_number) нет

Scenario: Файл только с формами

• WHEN смаплен golden-снимок mezheninovskaya/2025-Q3/1_Форма1_бух_09 (одна форма BALANCE, ОСВ нет)
• THEN файл PROCESSED, создан документ BALANCE, ошибки «нет документов ОСВ» нет

Scenario: Пустой результат

• WHEN результат без документов (documents = []): контракт v1.x такого результата не допускает — его останавливает проверка схемы, а прямой вызов map_file даёт MappingFatal
• THEN файл ERROR, причина в metrics.mapping_error (при проверке схемы — ошибка схемы, в map_file — «в результате нет документов»), повтор не выполняется

Requirement: Документ по листу ОСВ

На каждый osvDocument ядро SHALL создать document с document_type = OSV, osv_account_code = нормализованный код из шапки (60.1 → 60.01, 58.03, буквенные сегменты как есть), period_year, period_quarter, is_cumulative по шапке, locator, legal_entity_id владельца файла. Второй лист того же файла с тем же счётом MUST NOT создавать документ: в metrics.mapping_warnings пишется предупреждение, первый документ получает NEEDS_CHECK.

Scenario: Два листа одного счёта

• WHEN результат содержит два osvDocument со счётом 60
• THEN один document, статус NEEDS_CHECK, предупреждение называет оба locator

Requirement: Строки ОСВ

Ядро SHALL сохранить все строки osvDocument.rows кроме group_type = TOTAL (OQ-01) как osv_entry: row_number, level, row_value, group_type, group_name, data_type (включая NU), шесть сумм без изменений, counterparty_name/counterparty_inn как в результате, parent_entry_id по parent_row_number, account_code (как в результате), account_root (первый сегмент, None если он не цифровой — ASSUMPTION(OQ-103)), account_id (точное совпадение нормализованного кода с chart_of_account.code, иначе NULL), owner_legal_entity_id, recognition_job_id, is_modified = false.

Scenario: Дерево и счета

• WHEN смапплен результат rb/2024-FY/ОСВ_66 за 2024.xls
• THEN строк osv_entry = строк результата − 1 (TOTAL); у «Юг-Финанс / ПЕКАРНЯ СЧАСТЛИВОЧНАЯ» parent_entry_id указывает на строку 66.03, account_code = "66.03", account_root = "66", account_id = строка плана счетов 66.03

Scenario: Все golden-снимки парсера

• WHEN в БД маппятся все ../fixtures/golden/expected_osv_parse/** (82 результата, маркер fixtures)
• THEN для каждого: число строк = rows без TOTAL, у каждой строки уровня > 0 есть родитель, суммы равны снимку, account_id заполнен у всех строк-счетов, код которых есть в плане счетов seed

Requirement: Резолв контрагента

Для строк group_type = COUNTERPARTY с data_type ∈ {BU, SUM} ядро SHALL искать counterparty_id по §3 п. 4: по counterparty_inn в legal_entity.inn; иначе по точному counterparty_name в legal_entity.name; иначе по normalize_alias(counterparty_name) среди нормализованных имён ЮЛ и legal_entity_alias.normalized_alias; больше одного кандидата на шаге → NULL. Резолв SHALL выполняться по всему справочнику без фильтра видимости. Вместе с counterparty_id SHALL записываться counterparty_match_kind: INN, NAME или ALIAS по шагу, на котором нашёлся единственный кандидат (нормализованное имя ЮЛ и алиас — оба ALIAS); при NULL — NULL.

Scenario: По ИНН, по алиасу, неоднозначно

• WHEN в справочнике есть ЮЛ с ИНН 3528052718, ЮЛ с алиасом русский бисквит, и два ЮЛ с одинаковым нормализованным именем альфа
• THEN строка с ИНН 3528052718 → это ЮЛ, counterparty_match_kind = INN; строка «Русский бисквит» без ИНН → ЮЛ по алиасу, ALIAS; строка «ООО Альфа» → counterparty_id = NULL, counterparty_match_kind = NULL

Scenario: Алиас приоритетнее ЮЛ-тёзки

• WHEN в справочнике есть ЮЛ «ООО Гамма Сервис» и другое ЮЛ с алиасом гамма сервис, строка — «Гамма Сервис» без ИНН
• THEN counterparty_id — владелец алиаса, counterparty_match_kind = ALIAS; тот же результат при дорезолве свода на чтение

Requirement: Проверки шапки и статус документа

counterparty_check SHALL быть MATCH, если ИНН шапки равен ИНН владельца, или (без ИНН) нормализованное имя шапки совпадает с нормализованным именем или алиасом владельца; MISMATCH иначе; UNKNOWN при пустой шапке. period_check SHALL быть UNKNOWN до появления версии консолидации (Срез 4). Для period_quarter ∈ {Q2, Q3, Q4} с is_cumulative = false ядро SHALL сверить сальдо на начало корневой строки с документом Q1 того же года, ЮЛ и счёта (файл не SUPERSEDED) и при совпадении (±0.01) установить is_cumulative = true с предупреждением (ASSUMPTION(OQ-02)). Статус документа при маппинге SHALL быть RECOGNIZED, если задание done, checks без нарушений, counterparty_check ≠ MISMATCH и нет предупреждений маппинга; иначе NEEDS_CHECK (OQ-05). Документ RECOGNIZED в той же транзакции SHALL подтверждаться автоматически (требование «Автоподтверждение чистого документа»).

Scenario: Шапка другой организации

• WHEN файл загружен для ЮЛ «Пекарня Счастливочная», а в шапке АО "Русский бисквит"
• THEN counterparty_check = MISMATCH, status = NEEDS_CHECK

Scenario: Нарастающая по данным

• WHEN у ЮЛ есть документ ОСВ 60 за 2024 Q1 (opening_* корня = X) и маппится ОСВ 60 «за 3 квартал 2024» с opening_* корня = X
• THEN is_cumulative = true, предупреждение «нарастающая по данным Q1»

Scenario: Чистый результат

• WHEN задание done, шапка совпадает с владельцем, нарушений нет
• THEN после маппинга status = CONFIRMED (автоподтверждение), counterparty_check = MATCH, period_check = UNKNOWN

Requirement: Документ NEEDS_CHECK переводит версию в корректировку

После фиксации документов файла и автоподтверждения чистых документов цикл маппинга SHALL для каждой версии в DOCUMENTS_PROCESSING, в периметр которой входит ЮЛ файла, проверить документы файла: если среди них есть документ NEEDS_CHECK, подходящий версии по периоду (правила привязки documents-api), версия SHALL перейти в DATA_CORRECTION с changed_by = stored_file.uploaded_by в той же транзакции маппинга (версии блокируются FOR UPDATE по id после файла). Если uploaded_by NULL, переход SHALL пропускаться с записью в лог. Привязка consolidation_document для документа NEEDS_CHECK при маппинге MUST NOT создаваться (привязку при маппинге создаёт только автоподтверждение).

Scenario: Предупреждение маппинга двигает статус

• WHEN версия 2024 Q3 в DOCUMENTS_PROCESSING; смапплен файл ЮЛ периметра с ОСВ 62 за 2024 Q3 в NEEDS_CHECK
• THEN версия в DATA_CORRECTION, запись истории с changed_by = загрузивший; consolidation_document нет

Scenario: Документ RECOGNIZED

• WHEN версия 2024 Q3 в DOCUMENTS_PROCESSING; смапплен файл с единственным чистым документом за 2024 Q3
• THEN документ CONFIRMED и привязан; переход версии в DATA_CORRECTION записан автоподтверждением (комментарий «автоподтверждение документа …»), этот хук второго перехода не делает

Scenario: Документ не подходит версии

• WHEN версия 2024 Q3 в DOCUMENTS_PROCESSING; смапплен файл с единственным документом NEEDS_CHECK за 2025 Q1
• THEN статус версии не изменился

Requirement: Документ формы ББ/ОФР

Каждый statementDocument с document_type ∈ {BALANCE, INCOME} SHALL давать document (osv_account_code = NULL, is_cumulative = NULL, locator из результата, period_check = UNKNOWN) и financial_statement_meta 1:1. Дата периода — header.report_date, при её отсутствии — самая поздняя columns[].period_date; period_year — год даты, period_quarter — квартал, если дата — последний день марта, июня, сентября или декабря, иначе NULL с предупреждением; reporting_date — эта дата. Шапка: inn, inn_original_value = header.inn, inn_confidence, inn_verified = (inn_confidence = 100); organization_name; report_date = header.report_date, report_date_original_value = header.report_date_text; units = units_original_value = header.units; okud, okpo, okopf, okfs, okei, address — как пришли (шапка 1.x — по полям 1.x); statement_type — balance/income. Колонки — по columns[], is_current = true у колонки с самой поздней period_date. Строки — по lines[] с исходниками кода и названия; повтор кода сохраняется как отдельная строка (Р-4), порядок строк — row_index (с 0). Значение SHALL создаваться на каждую пару «строка × колонка»: из результата — amount, string_value, confidence, is_recognized; отсутствующая ячейка — пустая запись с needs_review = false; is_modified = false, original_amount = NULL. Сохранение результата — требование «Хранение результата формы v2.0 (DBML v5.19)». Нарушения checks результата 2.0 — в document_issue; для 1.x §7 считает ядро при приёме (требование «Формы результата 1.x — §7 при приёме»). counterparty_check — тем же правилом, что у листа ОСВ (ИНН шапки, иначе имя или алиас владельца).

Scenario: Форма из Excel

• WHEN смаплен golden-снимок mezheninovskaya/2025-Q3/1_Форма1_бух_09
• THEN документ BALANCE, period_year = 2025, period_quarter = Q3, reporting_date = 2025-09-30; у financial_statement_meta 37 строк и по значению на каждую пару строка × колонка

Scenario: Книга с двумя формами

• WHEN смаплен golden-снимок книги НПЗ npz/2025-Q3/…НОВОРОССИЙСКИЙ ПРОКАТНЫЙ ЗАВОД
• THEN у файла документы BALANCE (132 строки) и INCOME (43 строки), оба за 2025 Q3

Scenario: Форма из OCR без даты отчёта

• WHEN смаплен эталон нормализатора ocr/expected_normalize/aep_6 (дата отчёта null, колонки баланса 2025-06-30, 2024-12-31, 2023-12-31)
• THEN документ BALANCE за 2025 Q2, is_current — у колонки 2025-06-30, report_date в шапке NULL, inn NULL

Scenario: Дата не конец квартала

• WHEN дата отчёта формы — 2025-10-31
• THEN period_year = 2025, period_quarter = NULL, предупреждение маппинга, документ NEEDS_CHECK

Requirement: Повтор формы в файле и прочие документы

Каждый BALANCE / INCOME результата SHALL давать отдельный document с собственным file_ordinal; вторая форма того же типа в файле хранится (Р-10). Формы одного типа и одной пары period_year, period_quarter получают предупреждение маппинга «в файле есть другая форма <тип> за тот же период», документ — NEEDS_CHECK, автоподтверждения нет (Р-18). Документы DISCLOSURE и OTHER результата SHALL давать по одному document каждого типа на файл (file_ordinal — индекс первого такого документа в documents[]) без данных (locator — все locator этого типа через запятую, статус при маппинге RECOGNIZED, затем автоподтверждение → CONFIRMED). Форма BALANCE/INCOME без строк SHALL создаваться с шапкой и колонками (если колонки есть в результате).

Scenario: Расшифровки

• WHEN смаплен синтетический снимок st06_header_variants (форма INCOME и пять DISCLOSURE)
• THEN у файла два документа: INCOME и один DISCLOSURE с пятью locator через запятую; DISCLOSURE — CONFIRMED

Scenario: Форма без колонки кодов

• WHEN смаплен синтетический снимок st03_no_codes (BALANCE, строк 0)
• THEN документ BALANCE NEEDS_CHECK с шапкой, строк нет (колонок в снимке тоже нет — создаются те, что есть в результате)

Scenario: Две формы одного типа и периода

• WHEN результат содержит два BALANCE с одной парой period_year, period_quarter
• THEN создаются два документа с разными file_ordinal, оба NEEDS_CHECK с предупреждением маппинга; ни один не автоподтверждается

Requirement: Статус документа формы

Документ BALANCE/INCOME, принятый по результату 1.x, SHALL быть RECOGNIZED, только если одновременно: задание done; нет записей document_issue вида relation без акцепта (§7, посчитанный ядром при приёме, statement-checks); counterparty_check ≠ MISMATCH; period_year и period_quarter определены; ни у одного значения нет needs_review = true (при приёме 1.x needs_review = НЕ values_ok); нет предупреждений маппинга по документу; в файле нет второй формы того же типа и периода (Р-18); есть хотя бы одна строка. Иначе NEEDS_CHECK. Для результата 2.0 условие — требование «Условие RECOGNIZED при приёме 2.0». Статус SHALL пересчитываться при маппинге, после правки формы и после акцепта, кроме документа CONFIRMED. Документ RECOGNIZED после маппинга SHALL подтверждаться автоматически (требование «Автоподтверждение чистого документа»); RECOGNIZED, полученный пересчётом после правки или акцепта, — только вручную. Документ формы NEEDS_CHECK SHALL участвовать в переходе версии в DATA_CORRECTION наравне с ОСВ (требование «Документ NEEDS_CHECK переводит версию в корректировку»).

Scenario: Чистая форма Excel

• WHEN смаплен mezheninovskaya/2025-Q3/1_Форма2_бух_09 (ОФР, done, соотношения сходятся, ИНН шапки = ИНН владельца файла)
• THEN документ INCOME CONFIRMED (автоподтверждение)

Scenario: Форма OCR

• WHEN смаплен эталон ocr/expected_normalize/aep_3 (уверенность значений < 100, ИНН шапки ≠ ИНН владельца)
• THEN документ BALANCE NEEDS_CHECK, counterparty_check = MISMATCH

Scenario: Форма двигает версию

• WHEN версия ГК 2025 Q3 в DOCUMENTS_PROCESSING, в периметре ЮЛ файла; смаплена форма BALANCE за 2025 Q3 в NEEDS_CHECK
• THEN версия в DATA_CORRECTION, привязки consolidation_document нет

Scenario: Чистая после правки — вручную

• WHEN форма NEEDS_CHECK исправлена аналитиком (PATCH …/statement) и пересчёт дал RECOGNIZED
• THEN документ остаётся RECOGNIZED до POST …/confirm

Requirement: Автоподтверждение чистого документа

В транзакции маппинга после автозамены прежних версий файла и до перехода версий по NEEDS_CHECK цикл маппинга SHALL перевести каждый документ файла, получивший при маппинге статус RECOGNIZED, в CONFIRMED (ТЗ 03_9 п. 4, 10_10; решение владельца 08.10.2026, OQ-157): confirmed_by = NULL, confirmed_at = now; у формы BALANCE/INCOME — financial_statement_meta.reviewed_by = NULL, reviewed_at = now; audit_event(DOCUMENT_CONFIRM, PRIMARY_DOCUMENTS, object_type = document) с user_id = NULL, before_value.status = RECOGNIZED, after_value.status = CONFIRMED и description = «автоподтверждение: без замечаний». Форма BALANCE/INCOME с шапкой SHALL подтверждаться автоматически, только если выполнены условия ручного подтверждения (period_year и period_quarter определены, нет непройденных неакцептованных жёстких проверок §7); иначе она MUST оставаться RECOGNIZED без ошибки. Документы NEEDS_CHECK MUST NOT подтверждаться автоматически.

Автоподтверждённый документ SHALL привязываться к версиям так же, как при ручном подтверждении (documents-api «Подтверждение документа»: все подходящие версии «в работе», замена привязки того же ключа R-1), и каждая версия, получившая привязку, из INITIATED или DOCUMENTS_PROCESSING SHALL переходить в DATA_CORRECTION с changed_by = stored_file.uploaded_by и comment = «автоподтверждение документа <document_type> <osv_account_code>» (счёт — только у ОСВ). Если uploaded_by NULL, привязка SHALL создаваться, а переход — пропускаться с записью в лог. Пересчёт статуса формы после правки или акцепта MUST NOT подтверждать документ автоматически.

Scenario: Чистая ОСВ сразу «Загружен»

• WHEN смаплен результат fixtures/osv/rb/2025-Q1/ОСВ сч 60 за 1 кв 2025 год.xlsx для ЮЛ АО «Русский бисквит» (задание done, шапка совпадает с владельцем, нарушений и предупреждений нет)
• THEN документ OSV 60 — CONFIRMED, confirmed_by NULL, confirmed_at заполнен; есть audit_event(DOCUMENT_CONFIRM) с user_id NULL и описанием «автоподтверждение: без замечаний»

Scenario: Привязка и переход версии

• WHEN версия ГК «Русский Бисквит» 2025 Q1 в INITIATED, РБ в периметре; смаплен чистый результат ОСВ 60 РБ за 2025 Q1, файл загрузил ka_go
• THEN consolidation_document(version, document) создан; версия в DATA_CORRECTION; запись истории INITIATED → DATA_CORRECTION с changed_by = ka_go и комментарием «автоподтверждение документа OSV 60»

Scenario: Документ с замечанием ждёт аналитика

• WHEN файл ОСВ загружен для ЮЛ «Пекарня Счастливочная», а в шапке АО "Русский бисквит"
• THEN документ NEEDS_CHECK, confirmed_at пуст, события DOCUMENT_CONFIRM нет, привязки нет

Scenario: Чистая форма Excel

• WHEN смаплен statements-xlsx/mezheninovskaya/2025-Q3/1_Форма2_бух_09 (ОФР, done, соотношения сходятся, период определён)
• THEN документ INCOME CONFIRMED, reviewed_by NULL, reviewed_at заполнен

Scenario: Форма OCR не подтверждается сама

• WHEN смаплен эталон ocr/expected_normalize/БО 1 кв 2025 (уверенность значений < 100, дата отчёта не разобрана)
• THEN документы BALANCE и INCOME — NEEDS_CHECK, не CONFIRMED

Scenario: Файл без загрузившего

• WHEN версия в INITIATED, ЮЛ в периметре; смаплен чистый результат файла с uploaded_by NULL
• THEN документ CONFIRMED и привязан к версии; версия осталась INITIATED; в логе — строка о пропуске перехода

Scenario: Автозамена чистой версией файла

• WHEN документ ОСВ 60 РБ за 2025 Q1 из файла A привязан к версии 2025 Q1; загружен и смаплен файл B того же ключа (чистый), A заменён автозаменой
• THEN привязка документа A снята, документ B CONFIRMED и привязан к версии

Requirement: Хранение результата формы v2.0 (DBML v5.19)

Маппер результата 2.0 SHALL писать документ формы как пришёл: строки, коды и значения не сливаются и не дедуплицируются (повтор кода — отдельные строки), каждая строка результата — financial_statement_line (row_index, source_ref = ref, line_status, line_code, line_code_original_value = line_code результата, line_code_text, line_code_confidence, line_name, line_name_confidence, parent_row_index — row_index строки с ref = parent_ref, needs_review, is_confirmed = false); каждая пара «строка × колонка» — одна financial_statement_value (amount, string_value, source_text = values[].text, confidence, is_recognized, needs_review; значения, которого нет в результате, — пустая запись с needs_review = false); колонки — financial_statement_column с period_kind, label_confidence; шапка — financial_statement_meta с form_variant, needs_review_fields и header_source (раздел «Шапка формы»); предупреждения и нарушения документа — document_issue (источник service); версия общего кода — recognition_job.statements_version. Единственные случаи, когда элемент результата не записывается, — нарушение уникальности ключей хранения, и каждый из них MUST фиксироваться document_issue MAPPING_WARNING (info, источник core): значение с column_index вне колонок формы; повтор column_index колонки — остаётся первая колонка, остальные пропускаются; повтор row_index или ref у строк — остаётся первая строка, остальные пропускаются; detail с parent_ref, которого нет, хранится с parent_row_index = null. Уникальность (meta_id, line_code) снята; (meta_id, source_ref) уникален там, где source_ref не null. Каждый BALANCE / INCOME результата SHALL становиться отдельным document; вторая форма того же типа в файле хранится (Р-10); ОСВ по счёту, DISCLOSURE и OTHER — по-прежнему один документ на тип (и счёт) на файл. Каждый создаваемый document (ОСВ, формы, DISCLOSURE, OTHER) при приёме результата любого MAJOR (мапперы 1.x и 2.0) SHALL получать file_ordinal = индекс документа в documents[] результата (с 0); документ, который не создаётся (второй лист ОСВ с тем же счётом, второй DISCLOSURE), номер не занимает, но и не сдвигает остальные — номера уникальны в файле и могут идти с пропусками.

Scenario: Книга из двух ОСВ

• WHEN результат содержит две ОСВ по счетам 60 и 62 (documents[0], documents[1]), принятый маппером 1.x или 2.0
• THEN два документа с file_ordinal 0 и 1; уникальность (stored_file_id, file_ordinal) не нарушена, файл не ERROR

Scenario: PDF с ББ и ОФР по 1.x

• WHEN результат 1.2 содержит BALANCE и INCOME
• THEN документы с file_ordinal 0 и 1

Scenario: Повтор кода сохраняется

• WHEN в результате две строки ok с кодом 2410 (пустая и с (649))
• THEN в БД две строки 2410 с разными row_index и source_ref, обе со своими значениями

Scenario: Форма 2.0 хранится как пришла

• WHEN результат 2.0 содержит две строки с кодом 1230 и строку без кода (ref с parent_ref)
• THEN создано три строки с их row_index, source_ref и parent_row_index; повтор кода не сливается

Scenario: Строка без кода

• WHEN в результате строка unreadable с line_code_text = "ИЧ,250" и суммой
• THEN строка хранится с line_code = null, line_code_original_value = null, line_status = unreadable, line_code_text = "ИЧ,250" и row_index из результата

Scenario: Два баланса одного периода в одном файле

• WHEN результат содержит два BALANCE с одной парой period_year, period_quarter (лист-продолжение другого типа или двойная печать)
• THEN создаются два документа с разными file_ordinal; ни один не автоподтверждается (Р-18)

Scenario: Два баланса разных периодов в одном файле

• WHEN результат содержит BALANCE на 30.09.2025 и BALANCE на 31.12.2024
• THEN два документа с разными file_ordinal; каждый получает статус по своим условиям, правило Р-18 их не касается

Scenario: Повтор column_index колонки

• WHEN в columns[] результата два элемента с column_index = 1
• THEN сохраняется первая колонка, вторая пропускается, у документа MAPPING_WARNING

Scenario: Повтор ref строки

• WHEN в результате две строки с одним ref
• THEN сохраняется первая, вторая пропускается с MAPPING_WARNING; приём не падает

Requirement: Признак строки, созданной правкой

Строка формы SHALL считаться созданной правкой аналитика (шаблонной, origin = template) тогда и только тогда, когда row_index IS NULL. Маппер 1.x и маппер 2.0 SHALL всегда писать row_index (у 1.x — по порядку строк результата с 0), поэтому у строки из источника он не null. line_code_original_value SHALL хранить код строки из результата как пришёл (null у unreadable / missing / detail и у строк, созданных правкой) и правками кода MUST NOT меняться. Признак line_code_original_value IS NULL для origin MUST NOT использоваться.

Scenario: Строка источника без кода — не шаблонная

• WHEN у строки unreadable из результата line_code_original_value = null и row_index = 7
• THEN origin = source; правила шаблонных строк (удаление без сумм, 409) к ней не применяются

Scenario: Назначение одного кода двум строкам источника

• WHEN аналитик назначил код 1250 строке unreadable (row_index = 7, без сумм), а затем тот же код — строке missing (row_index = 2) с суммой
• THEN обе строки ok с кодом 1250, ни одна не удалена, 409 нет (повтор кода законен, Р-4)

Requirement: Шапка формы — сырой текст и уверенность

Маппер 2.0 SHALL писать в financial_statement_meta.header_source объект {"<поле>": {"text": <поле>_text, "confidence": <поле>_confidence}} для всех полей шапки результата (organization_name, inn, report_date, units, okud, okpo, okopf, okfs, okei, address); разобранные значения — в одноимённые колонки; *_original_value — как прежде: inn_original_value = inn, report_date_original_value = report_date_text, units_original_value = units_text; organization_name_original_value = organization_name, inn_confidence = inn_confidence. header_source и *_original_value правками MUST NOT меняться. Маппер 1.x заполняет header_source из полей шапки 1.x. StatementOut.header.source SHALL отдавать header_source.

Scenario: Подсказка у поля шапки

• WHEN в результате organization_name_text = "ООО «Ромашкa»", organization_name_confidence = 67
• THEN header_source.organization_name = {"text": "ООО «Ромашкa»", "confidence": 67}; экран показывает их в подсказке у поля

Requirement: Условие RECOGNIZED при приёме 2.0

При приёме 2.0 статус документа формы SHALL быть RECOGNIZED ⇔ document.status = done и он согласован с содержимым документа ∧ в metrics.warnings файла нет предупреждений уровня error ∧ counterparty_check ≠ MISMATCH ∧ период — конец квартала (period_year и period_quarter определены) ∧ у каждой строки ok с неуверенным кодом (line_code_confidence < 100) распознанное наименование совпало со справочным по коду ∧ в файле нет второй формы того же типа и периода (та же пара period_year, period_quarter; формы без квартала не считаются); иначе NEEDS_CHECK. Согласованность: ядро SHALL вызывать общую функцию статуса пакета (statement-normalization, «Шаг 8 — статус документа и конверта») по входу, собранному из результата: layout_found — lines[] непуст, has_organization_or_inn и period_known — по шапке и колонкам результата, строки и значения с их needs_review (значения detail функция не учитывает), число checks.relations_failed, accepted = false, уровни warnings[] документа. done согласован, если функция тоже даёт done; иначе ядро считает документ needs_check и пишет document_issue RESULT_STATUS_INCONSISTENT (info, источник core). Это вызов той же функции, а не пересчёт §7 и needs_review. Статус конверта и needs_check соседнего документа в условие MUST NOT входить (Р-19). Проверки §7, needs_review и предупреждения сервиса при загрузке MUST NOT пересчитываться.

Совпадение наименований: обе строки приводятся к нижнему регистру, ё → е, всё, кроме букв и цифр, — пробел, пробелы схлопываются, крайние пробелы обрезаются (strip); совпало, если строки равны, или более короткая (не короче 5 символов) входит в более длинную, или отношение сходства difflib.SequenceMatcher ≥ 0,8; сравнение — с любым справочным именем кода (у кода может быть несколько имён — синонимы и законные повторы, Р-20) в любой редакции словаря ядра. Если хотя бы одно из сравниваемых имён начинается с «итого по разделу», сравниваются номера раздела: номер — начальная часть первого слова после фразы из букв i, v, x (латиница; кириллические «і», «х» приводятся к ним), остальное в слове отбрасывается («v1» → V, «v» → V); совпало ⇔ номера равны; номер не выделен хотя бы у одного имени — совпадение только при равенстве строк целиком. Кода нет в словаре имён или наименование пусто — не совпало. Несовпадение — document_issue NAME_MISMATCH (info, источник core, строка). RECOGNIZED SHALL, как и прежде, автоподтверждаться (OQ-157).

Scenario: Ячейка соседнего документа

• WHEN ББ done, ОФР того же файла needs_check, предупреждений файла уровня error нет, ИНН совпал, период — 30.09.2025
• THEN ББ RECOGNIZED и автоподтверждается, ОФР — NEEDS_CHECK

Scenario: Потерянный json

• WHEN все документы done, но в metrics.warnings файла JSON_FAILED (или TABLE_PARSE_ERROR) уровня error
• THEN все документы формы файла NEEDS_CHECK

Scenario: Подмена неуверенного кода на соседа

• WHEN строка с кодом 1120 (уверенность 50) и наименованием «Нематериальные активы»
• THEN наименование не совпало со справочным «Результаты исследований и разработок», документ NEEDS_CHECK, NAME_MISMATCH у строки

Scenario: Законный повтор с другим именем

• WHEN строка 1220 (уверенность 50) с наименованием «НДС, начисленный по отгрузке», а в словаре имён fsbu4 у 1220 есть это имя вторым
• THEN наименование совпало, NAME_MISMATCH нет

Scenario: Подмена итога раздела

• WHEN строка с кодом 1200 (уверенность 50) и наименованием «Итого по разделу I»
• THEN номер раздела I не равен II у справочного «Итого по разделу II», NAME_MISMATCH

Scenario: Хвост OCR после номера раздела (Счастливочная, РБ)

• WHEN строка 1500 (уверенность 56, разлепленная) с наименованием «Итого по разделу V1», или строка с наименованием «Итого по разделу V /»
• THEN номер раздела V равен номеру справочного «Итого по разделу V», наименование совпало, NAME_MISMATCH нет

Scenario: Сервис прислал done при неразобранной строке без значений

• WHEN документ пришёл done, но в нём строка unreadable без значений
• THEN функция статуса даёт needs_check (не все строки ok / detail), документ NEEDS_CHECK, RESULT_STATUS_INCONSISTENT; автоподтверждения нет

Scenario: Сервис ошибся со статусом

• WHEN документ пришёл done, но в нём строка unreadable с суммой
• THEN документ NEEDS_CHECK, RESULT_STATUS_INCONSISTENT у документа; автоподтверждения нет

Scenario: Период не конец квартала

• WHEN документ done с датой отчёта 15.08.2025
• THEN квартал не определён, документ NEEDS_CHECK (как в D-6) и не автоподтверждается; ручное подтверждение — 409 PERIOD_REQUIRED, пока аналитик не поправит дату отчёта

Requirement: Формы результата 1.x — §7 при приёме

Для формы, принятой по результату 1.x (окно перехода после выкладки ядра; checks контракта 2.0 у неё нет), ядро SHALL один раз при приёме посчитать §7 точкой входа пакета для пересчёта (statement-normalization; вариант формы — по структуре кодов, как у 2.0) по суммам результата и записать нарушения в document_issue (источник core, виды relation / soft, как в требовании о document_issue) и form_variant в financial_statement_meta; собственного пересчёта §7 ядро MUST NOT выполнять. Условие D-6 «проверки сошлись» для 1.x SHALL браться из этого расчёта; needs_review значения при приёме 1.x = НЕ values_ok (values_ok — is_recognized не false и confidence равна 100 или пуста), needs_review строки — false. Предупреждения маппера 1.x по документу (повтор кода, значение вне колонок) — document_issue MAPPING_WARNING (info, источник core); строки metrics.warnings результата 1.x — в recognition_job.metrics.warnings структурами {code: "LEGACY_WARNING", severity: "info", message}. После правки такая форма пересчитывается общим кодом, как форма 2.0; MAPPING_WARNING и LEGACY_WARNING статус не держат. Формы, существовавшие в БД до миграции v5.19, §7 не пересчитываются (требования «Миграция DBML v5.19» и «Очистка форм перед выкладкой»).

Scenario: Полярность needs_review при приёме 1.x

• WHEN в результате 1.2 у значения confidence = 100, is_recognized = true, у другого — confidence = 80
• THEN у первого needs_review = false, у второго — true

Scenario: Форма 1.x с нарушением

• WHEN результат 1.2 содержит ББ с несошедшимся 1600 = 1700
• THEN у формы запись document_issue relation RELATION_FAILED с codes = ["1600", "1700"] (источник core), документ NEEDS_CHECK; POST …/confirm без акцепта — 409 CHECKS_NOT_PASSED

Scenario: 1.x-документ после PATCH

• WHEN форма принята по результату 1.2, аналитик правит сумму 1230 так, что 1200 = 1210 + … + 1260 сходится
• THEN ядро пересчитывает §7 и статус общим кодом, запись relation по 1200 заменена (её больше нет), статус пересчитан; STATEMENTS_VERSION_MISMATCH не пишется (у задания 1.x версии нет)

Requirement: Проверки ядра при приёме результата 2.0

При приёме результата 2.0 ядро SHALL писать в document_issue формы предупреждения и checks результата (источник service) и проверки ядра (источник core): CODE_NOT_IN_DICTIONARY и CODE_NOT_IN_EDITION (редакция — edition точки входа пакета, а не по дате; одна запись на код документа, line_ids — все строки ok кода; только для кодов из ровно четырёх цифр — пятизначные подстроки Excel не проверяются; запись не пишется, если пакет не определил редакцию), NAME_MISMATCH, RESULT_STATUS_INCONSISTENT (согласованность done — вызовом engine.contract_document_status пакета) и STATEMENTS_VERSION_MISMATCH (при отличии statements_version задания от версии копии ядра; у 1.x не пишется). Проверки §7, needs_review и предупреждения сервиса MUST NOT пересчитываться при загрузке. Статус документа формы — по требованию «Условие RECOGNIZED при приёме 2.0».

Scenario: Пятизначный код не даёт info

• WHEN в ББ строка с кодом 12301 (подстрока Excel), которого нет в словаре
• THEN CODE_NOT_IN_DICTIONARY и CODE_NOT_IN_EDITION для него не пишутся

Scenario: Четырёхзначный код вне перечня

• WHEN в ББ строка 1120 на бланке fsbu4, где такого кода нет
• THEN запись CODE_NOT_IN_EDITION (info, core) с line_ids строк ok этого кода

Scenario: Версия копии отличается

• WHEN результат 2.0 принят с statements_version, отличной от версии копии ядра
• THEN запись STATEMENTS_VERSION_MISMATCH (info, core) уже при приёме

Requirement: Ведомость ОСВ по контракту 2.0

Для листа ОСВ результата 2.0 ядро SHALL создавать документ ОСВ по osvDocument, предупреждения листа (osvDocument.warnings, OSV_*) писать в document_issue (вид warning, источник service), а статус документа определять по требованию «Предупреждения файла и ОСВ в API, статус ОСВ при приёме 2.0». Статус ОСВ MUST NOT зависеть от статуса соседнего документа книги и от статуса конверта.

Scenario: ОСВ в книге с ОФР, требующим проверки

• WHEN книга из ОСВ (status = done, контрольные суммы сошлись) и ОФР (needs_check)
• THEN документ ОСВ RECOGNIZED, документ ОФР NEEDS_CHECK