Design

Context

Мотивация — в proposal.md. Основная спека пока требует копию api/arm_statements/ и её VERSION; delta заменяет эти требования. Рабочее дерево уже содержит установку локальной библиотеки по примеру ../arm-core, удаление копии и сопутствующие настройки. Этот change документирует решение; новый код в ходе propose не меняется.

Дистрибутив называется pylib_ai_arm_statements (каноническое имя pip — pylib-ai-arm-statements), импорт остаётся arm_statements. Версия источника — 0.1.1. Внешний пакет предоставляет default_rules() и statements_version(); при установке версия может читаться из метаданных дистрибутива.

Goals / Non-Goals

Goals: единый источник нормализации, явная локальная установка и переустановка, автономный Docker-образ, сохранение границы адаптера и контракта.

Non-Goals: изменения схем, бизнес-алгоритмов §11/§11.1/§11.9, числовых типов и единиц измерения. Суммы и единицы по-прежнему обрабатывает библиотека; собственные таблицы и ORM не вводятся.

Decisions

Установка локального пакета через uv. STATEMENTS_DIR задаёт источник. make venv фильтрует ^(raisa_|pylib_ai) при установке requirements и затем ставит пакет из пути; make install создаёт окружение при необходимости и выполняет переустановку через --reinstall-package. Так изменения исходников попадают в окружение после явной команды. Editable-установка не выбрана, чтобы поведение совпадало с установкой пакета в образ; копирование и публикация в PyPI исключены выбранным способом поставки.
Версия зависимости и версия результата. requirements.txt фиксирует ожидаемую 0.1.1, runtime использует statements_version(). Тест приложения сравнивает версию с метаданными установленного дистрибутива вместо чтения удалённого пути. Отсутствие версии остаётся ошибкой старта, текст предлагает make install. Структура контракта не меняется. Фильтрация requirements означает, что версия локального источника отдельно сверяется при приёмке: сама запись ==0.1.1 не ограничивает установку из пути.
Разделение проверок библиотеки и сервиса. Удаляются копия, её testpaths, аргумент mypy и statements-check из check-full. Ruff считает arm_statements сторонним импортом. Для пакета без py.typed mypy получает адресный follow_untyped_imports = true, чтобы использовать существующие аннотации вместо общего подавления ошибок. Проверки адаптера, результата и golden остаются в шлюзе; тесты самой библиотеки принадлежат библиотеке.
Docker build context statements. Make передаёт путь через --build-context; Dockerfile исключает raisa_* из requirements, временно монтирует контекст через RUN --mount и устанавливает библиотеку вместе с requirements одним вызовом pip с проверкой закреплённой версии. Исходники не монтируются при запуске. Расширение основного контекста до всего workspace не выбрано: оно привязывает сборку к структуре соседних проектов.
Документация и общие контракты. README, CLAUDE и сообщения шлюза описывают библиотеку. Основные спеки обновятся при отдельном sync/archive, исторические change'и сохраняются. Общие JSON Schema остаются побайтовой копией источника; историческое описание коммита копии внутри схемы требует отдельного согласованного изменения в docs, если будет обновляться.

Risks / Trade-offs

[В локальном пути другая версия] → перед приёмкой сверить метаданные с 0.1.1; для обновления версии менять источник и requirements согласованно.
[Библиотека не поставляет правила или метаданные] → проверить default_rules(), версию и нормализацию после установки и внутри образа.
[Соседний каталог отсутствует в worktree/CI] → предоставить checkout и передать STATEMENTS_DIR; завершаться ошибкой без fallback в PyPI.
[Docker требует поддержки дополнительных контекстов BuildKit] → использовать make docker-build с BuildKit/buildx.
[Реальные фикстуры недоступны] → отмечать golden как пропущенные, повторить с ../fixtures/ocr перед утверждением эквивалентности. В текущем workspace каталога нет.

Migration Plan

Предоставить библиотеку 0.1.1, проверить тесты версии и контракта; существующие задачи ниже служат сверкой уже выполненных правок.
Выполнить make venv, затем make install; проверить импорт из site-packages, словари и метаданные.
Проверить lint, тесты сервиса и golden при наличии реальных данных; собрать и проверить образ.
После отдельного review/apply синхронизировать delta и архивировать change. В текущем propose основные спеки не менять.

Откат: восстановить предыдущую ревизию сервиса с копией нормализатора и пересоздать окружение/образ из её зависимостей. Миграций БД нет.

Из предыдущего прогона: lint и Docker прошли; 896 тестов прошли, 25 пропущены, один тест эмулятора .PDF → .pdf.done упал. Это результат прежней проверки, а не валидация данного предложения; исправление эмулятора вынесено за рамки change.

7.8 KiB Raw Blame History Unescape Escape