Files
mtusi2026lab2/openspec/changes/forward-lab4-sqlalchemy-foundation/design.md
T

3.9 KiB

Context

Основа берётся только из snapshot ЛР4 d7478726a8 относительно d2744bc. Рабочее дерево ЛР5 исходно чистое, HEAD 64d5c67. ЛР5 содержит собственные задания, варианты и outbox; их нельзя заменить синхронным upload ЛР4.

Goals / Non-Goals

Перенос инфраструктуры и исправлений без начала грейдов. Новые измерения и REPORT выполняются отдельными этапами. Исторические файлы contracts/tests/README/COURSE/REPORT/evidence не изменяются.

Decisions

  • Применить трёхсторонний перенос по общему исходнику, вручную разрешить пересечения. Прямое копирование src откатило бы queued/processing и потеряло worker.
  • Общая платформа Database/UoW использует SQLAlchemy 2.0.45 async_sessionmaker, DeclarativeBase и expire_on_commit=False; identity/messaging наследуют исправленные адаптеры ЛР4. Новые таблицы attachments/jobs/outbox/variants получают ORM-модели и Core-запросы. Порты остаются в application, сборка в ioc и entrypoint.
  • Захват lease, fencing, retry, аудит и outbox остаются в одной сессии UoW. FOR UPDATE SKIP LOCKED обслуживают частичные индексы jobs_lease_idx/outbox_pending_idx. Результат фиксируется до FastStream manual ack; publisher confirm не равен ack. Потеря confirm даёт повтор, повтор защищён ключом эффекта и lease_token.
  • Сохранить ревизии ЛР5 0004_jobs/0005_failed_registry, карантин ЛР4 добавить после них. При adoption воспроизвести ожидаемую старую схему во временной схеме в savepoint, сравнить каталог и SHA256 журнала, затем stamp. Автоматического reset нет.
  • Сверка ЛР4 сохраняется для legacy-префикса attachments/. Очисткой staging и новыми вариантами владеет pipeline ЛР5; перенос не расширяет полномочия уборки.
  • Docker image включает Alembic; migrate выполняет alembic upgrade head. Секреты только *_FILE, non-root, API без брокера, только LB 18085 и дополнительные порты 25000–25999.

Risks / Trade-offs

  • Несовместимость тестов ready/queued → адаптировать собственные тесты к текущему API, публичные не менять.
  • Регрессия транзакций → проверить rollback, одновременные claim, fencing, retry и outbox существующими тестами.
  • Дрейф legacy-схемы → отказ adoption вместо угадывания версии, тесты populated migration и повторного запуска.
  • Сверка ограничена legacy-префиксом; pipeline владеет staging/originals/variants. Это ограничение передачи основы фиксируется для отдельного отчёта.

Migration Plan

make check/lint/student-test, затем make up и make test на собственном project mtusi2026lab5. При ошибке миграция откатывает текущую транзакцию; прежние volumes сохраняются. Стенд остановить без удаления volumes. Перенос кода закоммитить, OpenSpec синхронизировать и архивировать.