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

100 lines
6.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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/`.