arm-ka-docs/openspec/changes/archive/2026-10-06-slice-2b-statement-parser/specs/recognition-contract/spec.md

Spec Delta: recognition-contract

MODIFIED Requirements

Requirement: Файл результата

Файл результата SHALL соответствовать docs/contracts/recognition-result.schema.json v1.2: один файл (stored_file) → один job_id → массив documents из osvDocument и/или statementDocument; денежные значения — строки ^-?\d+(\.\d{1,2})?$; confidence — 0–100. Пустой массив documents допустим только при status = error. У строки osvDocument.rows[] SHALL быть необязательное поле extra — объект «заголовок колонки → строка или null» для колонок внутри таблицы, не сопоставленных с шестью суммами и ИНН (§1.2 «не терять»). У шапки osvDocument.header SHALL быть необязательные period_start, period_end (дата или null — границы периода по шапке; для квартала и года — первое и последнее число, для диапазона месяцев — его границы) и is_from_year_start (boolean или null; is_cumulative не переопределяется). statementDocument.document_type SHALL допускать DISCLOSURE (расшифровка или иная форма 0710xxx: документ без columns и lines). У statementDocument SHALL быть необязательный объект checks: relations_failed и soft_relations_failed — массивы {column_index, relation, expected, actual} (нарушенные соотношения §7 по колонке; expected/actual — money), duplicate_line_codes — массив строк; отсутствие объекта означает «не проверялось», пустые массивы — «проверено, сошлось». Потребители, не знающие новых полей и значений, игнорируют их (MINOR). Производитель v1.2 пишет schema_version = "1.2"; файлы v1.0 и v1.1 остаются валидными.

Scenario: Результат валидируется примерами

• WHEN CI сервиса запускает тесты контракта
• THEN все файлы docs/contracts/examples/result-*.json проходят схему файла результата, а все request-*.json / result-message-*.json — схемы сообщений

Scenario: Лишняя колонка сохранена

• WHEN в ОСВ между ИНН и суммами есть колонка «КПП»
• THEN у строк контрагентов extra = {"КПП": "<значение>"}, файл проходит схему v1.2 и схему v1.0 (поле игнорируется)

Scenario: Форма из Excel с проверками

• WHEN tabular-parser разобрал книгу с балансом на двух листах, ОФР и пояснениями (examples/result-statement-excel.json)
• THEN файл проходит схему v1.2: BALANCE с locator из двух имён листов и checks с нарушением в soft_relations_failed, INCOME с пустыми массивами checks, DISCLOSURE без columns/lines; тот же файл без checks и с document_type = OTHER вместо DISCLOSURE проходит схему v1.1

Scenario: Границы периода ОСВ

• WHEN в шапке ОСВ период «Октябрь 2024 г. – Сентябрь 2025 г.»
• THEN period_start = "2024-10-01", period_end = "2025-09-30", is_from_year_start = false; файл проходит схему v1.2, а потребитель v1.1 читает его без ошибок