63 lines
10 KiB
Markdown
63 lines
10 KiB
Markdown
# 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`; `make venv` создаёт или использует окружение (uv, `--allow-existing`), `make install` переустанавливает библиотеку (`--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. Возвращать синхронизируемую копию исходников ради частичного отката не требуется; миграций БД нет. Для возврата к схеме до перехода нужен согласованный откат зависимости и удаления копии отдельным изменением.
|