Files
mtusi2026lab6/openspec/changes/archive/2026-10-01-postgres-storage/proposal.md
T
ricoromaandClaude Opus 5.5 9cc6c0c7a6 chore: port lab 5 solution into the lab 6 skeleton
Source: mtusi2026lab5-safronov, solution/bvt2301-safronov, 046ec9e.
Contracts, public tests and evidence of lab 5 are not carried over.
The compose project, image and CI prefix are renamed to lab6; the first
broker start defect is recorded in KNOWN_ISSUES.md; PLAN.md outlines the
OpenSpec changes of lab 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:46:56 +03:00

6.9 KiB
Raw Blame History

Proposal

Why

Лаба 2 требует, чтобы подтверждённые данные переживали перезапуск, а источником истины был PostgreSQL (README.md, уровень «3»). Сейчас пользователи, чаты и сообщения живут в MemoryStore одного процесса и пропадают при рестарте. Это первый шаг перехода на лабу 2. Хранилище меняется отдельно от аутентификации: API остаётся прежним (X-User-Id), и перенесённые из лабы 1 student-tests проверяют замену без правок тестов поведения.

What Changes

  • BREAKING (для оператора): стенд запускается только вместе с PostgreSQL. Compose поднимает postgres, одноразовый сервис миграций и api; данные лежат в именованном volume.
  • MemoryStore удаляется. Repo работают через AsyncSession (SQLAlchemy async, драйвер asyncpg), сервисы управляют транзакциями. Уникальность username держит ограничение БД, создание чата с участниками — одна транзакция.
  • Схема версионируется alembic: users, chats, chat_members (с позицией участника), messages; первичные и внешние ключи, уникальный username, индекс истории (chat_id, created_at, id). env.py — асинхронный шаблон alembic, URL берётся из настроек.
  • Миграции применяются до старта API: в docker — отдельный сервис того же образа, в консоли make run_dev сам поднимает БД и накатывает миграции. Добавляются цели start_db, stop_db, upgrade, revision, wipe_data.
  • Секция настроек [database]: адрес, учётные данные, пул, таймауты. Значения для консоли и для docker приходят из одного .env без переключения конфига комментариями. В compose нет литералов адреса и порта Postgres, кроме адреса публикации 127.0.0.1.
  • /health/ready проверяет Postgres. Потеря связи с БД на бизнес-запросе даёт 503 unavailable, а после возврата БД сервис работает без перезапуска.
  • BREAKING (для защиты): рестарт контейнеров больше не стирает состояние. Прежний X-User-Id после рестарта стенда получает 200. Появляется scripts/restart.sh: перезапуск API и Postgres с сохранением volume.
  • Образ содержит migrations/ и alembic.ini.
  • make test_isolated: тесты образа на временной базе test_<db> в том же Postgres. Команда собирает образ, создаёт базу, накатывает на неё миграции сервисом миграций compose, поднимает отдельный контейнер API из определения сервиса compose с подменой только имени базы, прогоняет публичный smoke и student-tests, затем удаляет контейнер и базу. Одна команда проверяет код, образ и связку compose, а рабочая база не копит данные тестов.
  • BREAKING (для оператора): цель make run_no_compose удаляется: без PostgreSQL один контейнер API запросы не обслуживает, а сборку образа проверяет make run_docker.

Вне этого change: пароли, Basic → Bearer и сессии (session-auth), Redis/Valkey, проверки отказов уровня «4», доработка bench/.

Capabilities

New Capabilities

  • db-migrations: версионируемая схема, миграции с нуля и повторный запуск без дублей, применение миграций до старта API в docker и в консоли.

Modified Capabilities

  • data-storage: хранение в PostgreSQL вместо памяти процесса, сохранность после рестарта, целостность в БД, транзакция составной операции, недоступность БД → 503, ограниченный пул и таймауты.
  • health: readiness проверяет доступность PostgreSQL.
  • container-run: стенд compose из api, postgres и миграций; данные переживают рестарт; порты Postgres из .env; удаление данных — отдельной явной командой; запуска одного контейнера без compose (make run_no_compose) больше нет.
  • container-image: образ собирается с тегом лабы 2 и содержит миграции.
  • service-configuration: параметры подключения к PostgreSQL; консоль и docker без правки файлов и без литералов в compose.
  • student-tests: прогон образа на временной базе, которая удаляется после прогона.

Impact

  • Код: src/infra/db/ (engine, модели), src/core/repos/*, src/core/services/*, src/api/dependencies.py, src/api/routers/health.py, src/main.py (lifespan), src/config/settings.py; удаляется src/infra/memory.py.
  • Новые файлы: alembic.ini, migrations/, scripts/restart.sh, student-tests/run_isolated.py.
  • Зависимости: sqlalchemy[asyncio], asyncpg, alembic в основной группе; uv.lock.
  • Инфраструктура: docker-compose.yml, Dockerfile, .env.example, config_example.toml, Makefile.
  • Тесты: тесты поведения в student-tests/ не меняются; записи исключений в spec_coverage.py следуют за дельтами data-storage и health.
  • Документы: AGENTS.md (переходное состояние, карта кода), .claude/rules/ (settings, infra, run-modes, docker), скилл run-mtusi-messenger, REPORT.md (архитектура, запуск, доказательства хранения), evidence/.