arm-ka-docs/openspec/changes/document-statements-library-contract/specs/statement-normalization/spec.md

ADDED Requirements

Requirement: Библиотека общего кода arm_statements

Общий код нормализации ББ/ОФР SHALL жить в репозитории RSHB/pylib_ai_arm_statements Python-библиотекой: дистрибутив pylib-ai-arm-statements, импорт — arm_statements, свои тесты, конфиг линтеров и make check. Библиотека SHALL содержать: типы шага 1 (FormCandidate, Cell; сериализуемые в json dataclass-ы), шаги 2–8, общие разборы текста (двойники, даты, суммы, коды), словари — проверок §7 statement_checks.yaml (полный и упрощённый наборы), периодов statement_periods.yaml, заголовков форм и ОКУД, подписей колонок («Код», «Наименование», исключения), букв-двойников, единиц измерения statement_units.yaml (написания и коды ОКЕИ), упорядоченные перечни кодов форм по редакциям (66n, fsbu4) и вариантам (full, simplified) без наименований — байтовая копия docs/contracts/statement-code-orders.yaml как arm_statements/rules/statement_code_orders.yaml, диапазоны кодов — и загрузчик словарей. Словари SHALL входить в дистрибутив данными пакета (wheel и sdist), установленная библиотека читает их без исходного репозитория. Словаря «код → наименование» в библиотеке MUST NOT быть (Р-3). Библиотека SHALL владеть своими типами входа и выхода; конвертацию выхода в модель контракта делает потребитель. Golden-тесты — внутри библиотеки на синтетических и обезличенных данных; тесты на реальных фикстурах остаются в сервисах и соседние репозитории не читают. Зависимости библиотеки — только те, что есть в зеркале банка (сейчас PyYAML), Python — 3.11 (версия платформы).

В tabular-parser, scan-gateway и arm-core библиотека SHALL подключаться зависимостью и импортироваться по имени arm_statements; поставку, версию и порядок её подъёма задаёт требование «Поставка библиотеки потребителям».

Scenario: Наименований в библиотеке нет

• WHEN ревьюер ищет в библиотеке соответствие «код → наименование»
• THEN его нет: в перечне кодов только коды, наименования строк — словарь ядра

Scenario: Словари в установленном пакете

• WHEN wheel библиотеки установлен в чистое окружение без исходного репозитория
• THEN import arm_statements и загрузка стандартных правил работают, все YAML-словари на месте

Requirement: Поставка библиотеки потребителям

Версия библиотеки SHALL быть семантической (MAJOR.MINOR.PATCH), записываться в файл VERSION корня репозитория библиотеки и помечаться тегом v<версия> на коммите выпуска; опубликованная версия MUST NOT пересобираться с другим содержимым. Публикацию в Nexus выполняет платформа (CI в Gitea нет).

Потребители (arm-core, tabular-parser, scan-gateway) SHALL держать в api/requirements.txt строку pylib_ai_arm_statements==<версия>; копии исходников библиотеки в потребителях MUST NOT быть. На платформе библиотека ставится из Nexus по этой строке. Вне банка make venv SHALL пропускать строки pylib_ai* (как raisa_*) и ставить библиотеку из локального checkout STATEMENTS_DIR (по умолчанию ../pylib_ai_arm_statements); make install переустанавливает её без пересоздания окружения. Обе цели SHALL сначала сверять checkout (цель statements-version): VERSION checkout не равен версии из requirements.txt или checkout нет — ошибка; checkout не на теге v<версия> — предупреждение (правка библиотеки до выпуска). STATEMENTS_TAG по умолчанию — v<версия> из requirements.txt. make docker-build SHALL передавать checkout библиотеки контекстом сборки statements и отказывать, если HEAD checkout не совпадает с тегом STATEMENTS_TAG. ruff и mypy потребителя библиотеку не проверяют (она проверяется своим make check), arm_statements в конфиге ruff потребителя — сторонний пакет.

Маркер версии в результате (service.statements_version) и версия ядра для STATEMENTS_VERSION_MISMATCH SHALL браться из метаданных установленного дистрибутива (importlib.metadata). У заданий, посчитанных до перехода, в recognition_job.statements_version остаётся хэш коммита копии; расхождение с версией ядра даёт STATEMENTS_VERSION_MISMATCH (info) — это ожидаемо и не исправляется (решение владельца 26.10.2026).

Порядок правки перечня кодов: PR в docs (contracts/statement-code-orders.yaml) → PR в библиотеку (байтовая копия yaml) и новая версия → подъём версии в потребителях «сначала ядро». Пока цепочка не дошла до библиотеки, statements-orders-check в docs предупреждает, но не краснеет. Подъём версии в потребителях выкладывается одной поставкой ядра и обоих сервисов.

Scenario: Версия общего кода в результате

• WHEN сервис собирает результат с установленной библиотекой версии 0.1.1
• THEN в результате service.statements_version = "0.1.1"

Scenario: Сборка образа не с того коммита

• WHEN в ../pylib_ai_arm_statements checkout стоит на коммите после тега v0.1.1, а STATEMENTS_TAG = v0.1.1
• THEN make docker-build завершается ошибкой «HEAD библиотеки не совпадает с v0.1.1», образ не собирается

Scenario: Checkout библиотеки другой версии

• WHEN в api/requirements.txt сервиса pylib_ai_arm_statements==0.1.2, а в ../pylib_ai_arm_statements VERSION = 0.1.1
• THEN make venv и make install завершаются ошибкой с обеими версиями, библиотека не ставится

Scenario: Задание до перехода

• WHEN аналитик правит форму, посчитанную сервисом с копией (statements_version — хэш коммита), а у ядра установлена библиотека 0.1.1
• THEN пересчёт пишет STATEMENTS_VERSION_MISMATCH (info), на статус и подтверждение это не влияет

Scenario: Перечень кодов в docs новее библиотеки

• WHEN в docs в statement-code-orders.yaml добавлен код, а библиотека ещё не выпущена с ним
• THEN make -C docs check печатает предупреждение statements-orders-check и называет файл, код возврата 0

REMOVED Requirements

Requirement: Пакет общего кода arm_statements и его копии

Reason: копии пакета в сервисах заменены установленной библиотекой (AURORA-1677), репозиторий arm-statements архивирован, код перенесён в RSHB/pylib_ai_arm_statements. Migration: требования «Библиотека общего кода arm_statements» и «Поставка библиотеки потребителям».

Requirement: sync-statements — копии пакета в потребителях

Reason: копии api/arm_statements/ в сервисах заменены установленной библиотекой (AURORA-1677); раскладывать и сверять нечего, скрипт docs/scripts/sync-statements.sh и цели sync-statements, statements-check, test-sync-statements удалены. Migration: поставка и версия — требование «Поставка библиотеки потребителям»; сверка перечня кодов docs с библиотекой — цель statements-orders-check в make -C docs check; сверка словаря имён ядра с перечнем — тест ядра test_name_dictionary_codes_in_code_orders.