Design

Context

См. proposal.md, Why и What Changes. Это ретроспективная фиксация перехода, затронувшего два репозитория. Текущий arm-core больше не содержит встроенного api/arm_statements/, но его Python-импорты остаются прежними. Дистрибутив называется pylib-ai-arm-statements; запись с подчёркиваниями в requirements обозначает тот же нормализованный идентификатор Python-пакета.

На момент оформления обнаружены остатки прежней схемы: api/pytest.ini содержит arm_statements/tests, Ruff считает arm_statements first-party, mypy содержит overrides старого пакета. В Makefile из lint исчез не только аргумент arm_statements, но и весь вызов mypy. Эти факты фиксируются для проверки при apply, без изменения кода сейчас.

Основные спецификации ещё содержат формулировки «копия пакета» и sync-statements --check; дельты этого change уточняют источник библиотеки. Документирование перехода не означает, что дельты уже синхронизированы или change архивирован.

Goals / Non-Goals

Goals: воспроизводимая установка кода и ресурсов, сохранение имени импорта, определение версии установленного пакета, документирование сделанного и оставшихся проверок.

Non-Goals: менять алгоритмы §7/§11 общих правил, DTO, обязательность версии, БД и денежные единицы. Decimal и существующие единицы формы сохраняются. Документы в ../docs и выпуск внешней библиотеки не изменяются этим локальным workflow.

Decisions

Разделить имя дистрибутива и Python-модуля

pylib-ai-arm-statements устанавливается как arm_statements. Это сохраняет адаптер StatementsEngine, доменную сборку StoredForm и тесты. Выполненная ранее замена импортов на pylib_ai_arm_statements отменена вместе с временным override follow_untyped_imports; она не является итогом задачи.

Альтернатива — переименовать все импорты — отвергнута пользователем и не нужна для подключения дистрибутива.

Использовать окружение backend и явную переустановку

STATEMENTS_DIR ?= ../pylib_ai_arm_statements; uv venv --python 3.11 --allow-existing создаёт или использует окружение; uv pip install --python ... --reinstall-package pylib-ai-arm-statements ... переустанавливает библиотеку. Обычная установка выбрана вместо editable: установленное дерево должно содержать весь необходимый код и YAML. Переустановка нужна и при неизменившемся номере локальной версии.

make venv фильтрует только основные requirements по ^(raisa_|pylib_ai), dev-файл обрабатывается прежним фильтром ^-r. Текущий Makefile также устанавливает локальную библиотеку после requirements. Это уточняет первоначальное описание двух отдельных команд: make install остаётся доступным для обновления без полного запуска venv.

Включать YAML в дистрибутив

В ../pylib_ai_arm_statements/MANIFEST.in исправлены два пути на arm_statements и arm_statements/rules. Имеющийся include_package_data = True позволяет включать ресурсы. Ручное копирование YAML в site-packages не использовалось: оно не исправляет последующие установки. make install успешно переустановил исправленный пакет; загрузка правил проверена тестами движка.

Сохранить маркер и добавить fallback на метаданные

В библиотеке arm_statements/version.py стандартный непустой VERSION имеет приоритет. При отсутствующем/пустом стандартном файле вызываются метаданные pylib-ai-arm-statements. При PackageNotFoundError возвращается None. Явно переданный отсутствующий/пустой файл сохраняет старое поведение None.

Альтернатива — ослабить валидацию RecognitionResultV2 — отвергнута: для форм версия остаётся обязательной. Искусственный VERSION в site-packages также не решает поставку пакета.

Уточнить документацию и границы изменений

В arm-core обновлены README, CLAUDE.md, комментарии api/src/models/files.py, api/src/contract/result_v2.py, api/src/api/dependencies/files.py, описание api/contracts/recognition-result.schema.json, комментарии конфигурации и dev requirements. В историческом плане и архивных change добавлены пометки о прежней схеме. Конкретные заголовки/сценарии доменных требований сохранены в дельтах.

В рабочем дереве также наблюдаются удаление встроенной копии, pin 0.1.1, отключение statements-check и изменения Makefile пользователем. Они относятся к контексту перехода; изменения .env.test и test_config.py, случайные HTML/PDF/XML и служебные файлы не входят в этот change.

Risks / Trade-offs

[Локальная переустановка меняет содержимое без нового номера версии] → удобна для разработки; опубликованные артефакты требуют уникальных версий. Равенство номера не доказывает равенство исходников.
[Другие сервисы ещё передают хеш копии вместо версии дистрибутива] → существующий STATEMENTS_VERSION_MISMATCH остаётся информационным; согласование выпуска выносится в отдельный change общих docs.
[Ошибки пакета исправлены в соседнем репозитории] → нужен отдельный коммит/поставка библиотеки; один коммит arm-core не включает эти файлы.
[Потеря проверки типов при удалении встроенного пакета] → отдельно проверить конфигурацию и восстановить проверку исходников arm-core при apply; анализировать библиотеку её собственными средствами.
[Устаревшая pytest testpath и first-party-настройки] → проверить и убрать привязки к удалённому дереву в рамках завершения перехода.
[Полный прогон не подтверждён] → повторить интеграционный тест с доступной инфраструктурой. Предыдущий запуск завис и был остановлен; успех не заявляется.

Migration Plan

Сделано: исправлена и переустановлена локальная библиотека; проверены версия 0.1.1 и 11 тестов tests/test_statements_engine.py. Ранее 24 профильных теста проходили на промежуточном варианте с другими импортами; этот результат не считается проверкой окончательного состояния.

Осталось: проверки собранного дистрибутива и граничных вариантов VERSION, согласование pytest/Ruff/mypy, повтор теста test_intake_statements_version_mismatch, общий прогон подходящих проверок, отдельные коммиты по репозиториям. Сценарий поставки проверяется на установленном пакете; регрессия нормализации — на существующих реальных фикстурах, без введения искусственных форм ради упаковки.

Для отката установки используется предыдущий исправный дистрибутив в окружении backend. Возвращать синхронизируемую копию исходников ради частичного отката не требуется; миграций БД нет. Для возврата к схеме до перехода нужен согласованный откат зависимости и удаления копии отдельным изменением.

10 KiB Raw Blame History Unescape Escape