41 lines
7.8 KiB
Markdown
41 lines
7.8 KiB
Markdown
# 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
|
||
|
||
1. **Установка локального пакета через uv.** `STATEMENTS_DIR` задаёт источник. `make venv` фильтрует `^(raisa_|pylib_ai)` при установке requirements и затем ставит пакет из пути; `make install` создаёт окружение при необходимости и выполняет переустановку через `--reinstall-package`. Так изменения исходников попадают в окружение после явной команды. Editable-установка не выбрана, чтобы поведение совпадало с установкой пакета в образ; копирование и публикация в PyPI исключены выбранным способом поставки.
|
||
2. **Версия зависимости и версия результата.** `requirements.txt` фиксирует ожидаемую `0.1.1`, runtime использует `statements_version()`. Тест приложения сравнивает версию с метаданными установленного дистрибутива вместо чтения удалённого пути. Отсутствие версии остаётся ошибкой старта, текст предлагает `make install`. Структура контракта не меняется. Фильтрация requirements означает, что версия локального источника отдельно сверяется при приёмке: сама запись `==0.1.1` не ограничивает установку из пути.
|
||
3. **Разделение проверок библиотеки и сервиса.** Удаляются копия, её `testpaths`, аргумент mypy и `statements-check` из `check-full`. Ruff считает `arm_statements` сторонним импортом. Для пакета без `py.typed` mypy получает адресный `follow_untyped_imports = true`, чтобы использовать существующие аннотации вместо общего подавления ошибок. Проверки адаптера, результата и golden остаются в шлюзе; тесты самой библиотеки принадлежат библиотеке.
|
||
4. **Docker build context `statements`.** Make передаёт путь через `--build-context`; Dockerfile исключает raisa_* из requirements, временно монтирует контекст через RUN --mount и устанавливает библиотеку вместе с requirements одним вызовом pip с проверкой закреплённой версии. Исходники не монтируются при запуске. Расширение основного контекста до всего workspace не выбрано: оно привязывает сборку к структуре соседних проектов.
|
||
5. **Документация и общие контракты.** 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
|
||
|
||
1. Предоставить библиотеку `0.1.1`, проверить тесты версии и контракта; существующие задачи ниже служат сверкой уже выполненных правок.
|
||
2. Выполнить `make venv`, затем `make install`; проверить импорт из site-packages, словари и метаданные.
|
||
3. Проверить lint, тесты сервиса и golden при наличии реальных данных; собрать и проверить образ.
|
||
4. После отдельного review/apply синхронизировать delta и архивировать change. В текущем propose основные спеки не менять.
|
||
|
||
Откат: восстановить предыдущую ревизию сервиса с копией нормализатора и пересоздать окружение/образ из её зависимостей. Миграций БД нет.
|
||
|
||
Из предыдущего прогона: lint и Docker прошли; 896 тестов прошли, 25 пропущены, один тест эмулятора `.PDF` → `.pdf.done` упал. Это результат прежней проверки, а не валидация данного предложения; исправление эмулятора вынесено за рамки change.
|