- carry the lab 3 solution over from mtusi2026lab3-safronov (solution/bvt2301-safronov, ce89eba): src, migrations, student-tests, bench, openspec, .claude, infra/haproxy and infra/valkey, own scripts, Dockerfile, compose, pyproject and uv lock - merge Makefile, .gitignore and .dockerignore (the lab 3 versions only add lines to the skeleton, which is the same in lab 4) and .env.example (lab 4 skeleton names listed in the header) - rename the compose project to mtusi-lab4 and the image to :lab4 so the stand does not reuse the lab 3 containers and volumes - update AGENTS.md for lab 4: current lab, origin commit, contract and test files of the new skeleton Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
100 lines
6.9 KiB
Markdown
100 lines
6.9 KiB
Markdown
# 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/`.
|