Files
mtusi2026lab6/openspec/changes/archive/2026-10-01-postgres-storage/tasks.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

243 lines
18 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.
# Tasks
Как строить — `design.md` (дальше «решение N»), что должно получиться —
дельты в `specs/`. Перед первым файлом слоя прочитать его правило:
`migrations.md` (модели, `migrations/`, `alembic.ini`), `repo-layer.md`,
`service-layer.md`, `infra.md`, `settings.md`, `docker.md`,
`run-modes.md`. Нужен запущенный Docker и свободные порты 8080 и 5433.
Состояние кода, по которому снимается доказательство для отчёта,
коммитится перед замером (`bench.md`, «Измеренное состояние —
commit»).
## 1. Зависимости и настройки
- [x] 1.1 `uv add "sqlalchemy[asyncio]>=2.1,<2.2" asyncpg alembic` в
основную группу; описание в `pyproject.toml` — лаба 2 (решение 2).
Проверка: `uv lock --check` проходит, `uv run python -c "import
sqlalchemy, asyncpg, alembic, greenlet"` без ошибок.
- [x] 1.2 Секция `Database` в `src/config/settings.py`: адрес,
учётные данные, пул и таймауты из таблицы решения 5, `url` через
`URL.create`. Проверка: без `.env` и `config.toml` `Settings`
загружается на дефолтах; пароль `p@ss%word` даёт рабочий URL, а
`url.render_as_string(hide_password=True)` его не показывает.
- [x] 1.3 `.env.example` по схеме решения 7 (пустой
`POSTGRES_PASSWORD`) и `TEST_APP_PORT=18088` (решение 12),
`config_example.toml` — пул и таймауты `[database]`, `make env_setup`
подставляет случайный пароль при создании `.env`. Проверка: после
`make env_setup` в свежем каталоге `POSTGRES_PASSWORD` непустой,
повторный `make env_setup` его не меняет; `uv run python -c "from
src.config import settings; print(settings.database.host,
settings.database.port)"` печатает `127.0.0.1 5433`.
## 2. Модели и миграции
- [x] 2.1 `src/infra/db/`: `Base` (`created_at`, `to_dict()`), модели
`users`, `chats`, `chat_members`, `messages` с ограничениями и
индексами из решения 3; фабрика engine и `async_sessionmaker`
(решение 5). Проверка: `Base.metadata.sorted_tables` — четыре
таблицы; у всех ограничений есть имена.
- [x] 2.2 `alembic.ini` и асинхронный `migrations/env.py` (решение 8):
URL из `settings.database.url`, логи через `src/infra/logger.py`,
логгер `alembic` на `INFO`. Проверка: при запущенном Postgres
`uv run alembic current` печатает JSON-строки, пароля в выводе нет.
- [x] 2.3 Первая ревизия: autogenerate, затем руками `CHECK` и
проверка имён ограничений; `downgrade` зеркалит `upgrade`.
Проверка: на пустом volume `make upgrade` создаёт таблицы (`\d+` в
`psql`), `alembic downgrade base` и снова `upgrade head` проходят,
повторный `make upgrade` ничего не меняет.
## 3. Compose, образ, Makefile
- [x] 3.1 Выбрать тег Postgres 18.x с патч-версией и digest индекса
(`docker buildx imagetools inspect`), точку монтирования volume
взять из `Config.Volumes` образа (решение 9). Проверка: тег, digest
и путь записаны в `docker-compose.yml`, путь совпадает с метаданными.
- [x] 3.2 `docker-compose.yml`: `name:`, якорь `x-app-env`, сервисы
`postgres` (`PGPORT`, алиас, `pg_isready`, volume `postgres_data`,
публикация `127.0.0.1`), `migrate`, `api` с `depends_on` (решения 7,
8, 9). Проверка: `docker compose --env-file .env config --quiet`
проходит; в `environment` и `ports` нет адреса и порта Postgres
литералами, кроме `127.0.0.1`.
- [x] 3.3 `Dockerfile`: `COPY migrations alembic.ini` в runtime,
комментарий — лаба 2. Проверка: образ из контекста чистого clone
(`docker.md`) собирается; в `/app` есть `migrations/` и
`alembic.ini`, `alembic --help` работает, `uv` не найден.
- [x] 3.4 `Makefile`: `start_db` (`up -d --wait postgres`), `stop_db`,
`upgrade`, `revision` (зависит от `upgrade`, `read -p`), `run_dev`
(`start_db`, `upgrade`, сервис), `wipe_data` с подтверждением;
`down` без `-v`; удалить `run_no_compose`, `DOCKER_IMAGE` и
`DOCKER_CONTAINER` (решение 9). Проверка: `make -n` для каждой цели
печатает ожидаемые команды; `make wipe_data` без подтверждения ничего
не удаляет; `grep -n run_no_compose Makefile` пусто.
- [x] 3.5 `student-tests/run_isolated.py` (stdlib: `docker compose
build`, `exec psql`, `run` для `migrate` и `api`, ожидание готовности,
уборка в `finally`) и цель `test_isolated: env_setup start_db` по
решению 12; `KEEP_TEST_DB` передаётся из аргумента make. Проверка:
`make -n test_isolated` печатает запуск скрипта; `uv run pytest
--collect-only` не собирает `run_isolated.py`; `make lint` чистый.
## 4. Repo, сервисы, API
- [x] 4.1 Repo `user`, `chat`, `message` на `AsyncSession` (решения 3,
4): `ON CONFLICT`, `array_agg(... ORDER BY position)`, keyset через
`tuple_` для истории и списка чатов. Проверка: на запущенном стенде
`EXPLAIN` запросов истории и списка чатов с `SET enable_seqscan =
off` использует индексы `(chat_id, created_at, id)` и
`(user_id, created_at, chat_id)` без `Sort` всей выборки.
- [x] 4.2 Сервисы на `db_session`, commit в сервисе, создание чата —
одна транзакция (решение 4); удалить `MemoryStore`, `get_store` и
`src/infra/memory.py`. Проверка: `grep -rn MemoryStore src` пусто,
`make lint` чистый.
- [x] 4.3 Engine и фабрика сессий — глобалы `src/infra/db/session.py`
(решение 5), `dispose()` в lifespan `src/main.py`;
`dependencies.py`: `get_db_session`, фабрики сервисов;
`get_current_user` по-прежнему по `X-User-Id`. Проверка: `make
run_dev` поднимается до `/health/ready` 200; по SIGTERM в журнале
«Stopped API» и «Finished server process»; пароля в журнале нет.
## 5. Недоступность БД и readiness
- [x] 5.1 Определить классы исключений: API запущен, Postgres
остановлен (`docker compose stop postgres`), затем приостановлен
(`docker compose pause postgres`); записать исключения из traceback
для отказа в соединении, клиентского таймаута и таймаута пула.
Проверка: список внесён в решение 6 `design.md`.
- [x] 5.2 Перехват в `get_db_session` (решение 6): откат, `warning`,
`ServiceUnavailable`. Проверка: сценарии «БД остановлена» и «БД
вернулась» (`data-storage`) — 503 `unavailable` без деталей, после
`docker compose start postgres` запросы проходят без рестарта API;
вывод в `evidence/storage/db-unavailable.md`.
- [x] 5.3 `/health/ready`: `SELECT 1` с таймаутом через engine.
Проверка: при остановленном Postgres `/health/ready` — 503 не позже
таймаута, `/health/live` — 200.
- [x] 5.4 Сценарий «Соединения исчерпаны»: `DATABASE__POOL_SIZE=1`,
`DATABASE__MAX_OVERFLOW=0`, `DATABASE__POOL_TIMEOUT_SECONDS=1`,
Postgres на паузе, два одновременных запроса. Проверка: второй
получает 503 примерно через 1 с, первый — 503 после
`request_timeout_seconds` и закрытия соединения (6 + 2 с); вывод в
`evidence/storage/pool-timeout.md`.
## 6. Рестарт стенда
- [x] 6.1 `scripts/restart.sh` по решению 10, исполняемый бит в git.
Проверка: `git ls-files -s scripts/restart.sh` — режим `100755`;
скрипт укладывается в 90 с; по журналу записано, прогоняет ли `up`
сервис `migrate` заново.
- [x] 6.2 Сценарий «Рестарт hook-ом» (`container-run`) и «Прежний
пользователь после рестарта» (`data-storage`): пользователь, чат с
`member_ids` в порядке `[bob, alice]`, сообщения; `StartedAt` до и
после `scripts/restart.sh`. Проверка: после рестарта тот же
`X-User-Id` получает 200, история и порядок участников прежние;
вывод в `evidence/storage/restart.md`.
## 7. Проверки стенда
- [x] 7.1 Сценарий «Консоль и контейнер» (`student-tests`): `make
student_test` против `make run_dev` и против `make run_docker`.
Проверка: в обоих прогонах прошли все тесты, кроме
`test_security_scheme_in_openapi` (переход контракта, design, Goals).
Evidence набора против контейнера снимает `session-auth`.
- [x] 7.2 Миграции с нуля и повторно (`db-migrations`): `make
wipe_data`, `make run_docker`, журнал `migrate`; затем повторный
прогон миграций при данных в базе. Проверка: `migrate` завершился
с кодом 0 раньше старта API; число строк во всех таблицах до и после
повтора одинаково; вывод в `evidence/migrations/from-zero-and-rerun.md`.
- [x] 7.3 Сценарий «Другой порт Postgres»: `POSTGRES_PORT=5544`,
`POSTGRES_OUT_PORT=5545` в `.env`, compose не правится. Проверка:
`make run_docker` доходит до `/health/ready` 200, `make run_dev`
подключается к `127.0.0.1:5545`; `.env` возвращён; вывод в
`evidence/storage/postgres-port.md`.
- [x] 7.4 Сценарий «Консоль, затем docker» (`service-configuration`) и
«down сохраняет данные» (`container-run`). Проверка: данные,
созданные через `make run_dev`, видны после `make run_docker` и после
`make down` + `make run_docker`, файлы конфигурации не менялись.
- [x] 7.5 Сценарий «Адрес публикации» (`container-run`). Проверка:
`docker port` для API и Postgres стенда показывает `127.0.0.1`, а не
`0.0.0.0`.
- [x] 7.6 Механика «Прогон на временной базе» (`student-tests`) при
запущенном рабочем стенде с данными: обычный прогон (до
`session-auth` он заканчивается падением smoke — это сценарий
«Упавшие тесты»); остановка тестового контейнера во время прогона;
Ctrl+C; хвост после `kill -9` скрипта; `KEEP_TEST_DB=1`. Проверка: в
каждом случае код выхода, наличие базы `test_<db>` (`\l` в `psql`) и
тестового контейнера (`docker ps -a`) соответствуют сценарию; число
строк рабочей базы до и после одинаково, рабочий API отвечает; после
разбора `KEEP_TEST_DB` база удалена руками; вывод в
`evidence/tests/test-isolated-mechanics.md`. Сценарий «Успешный
прогон» и evidence набора против контейнера — задача `session-auth`.
- [x] 7.7 Перенести дельты в основные спеки (`/opsx:sync`) и в том же
шаге обновить `student-tests/spec_coverage.py`: тексты исключений
«Прежний пользователь после рестарта» и «Хранилище не готово»,
исключения для «Сбой при добавлении участников», «БД остановлена»,
«БД вернулась», «Соединения исчерпаны» со ссылками на evidence и
change `failure-checks`; тест сценария «Порядок участников» в
`test_data_storage.py`. Purpose основного спека `container-run`
переписать руками: в нём «голый `docker run` из README (`make
run_no_compose`)», а дельта Purpose не меняет. Проверка: `make
student_test` против стенда — прошли все тесты, кроме
`test_security_scheme_in_openapi`, в том числе `test_coverage.py`;
`grep -rn run_no_compose openspec/specs` пусто.
## 8. Документы и инструменты
- [x] 8.1 Правила по решениям 11 и 12: `settings.md`, `infra.md`,
`run-modes.md` (плюс `test_isolated`), `docker.md`, `student-tests.md`
(обычный прогон и evidence — `make test_isolated`, против любого
стенда — `make student_test`). Проверка: `grep -n "POSTGRES_VOLUME\|решает
design change" .claude/rules` — только там, где решение ещё не
принято (`membership-cache`); `grep -rn run_no_compose .claude`
пусто.
- [x] 8.2 `AGENTS.md`: «Переходное состояние» без закрытых пунктов и с
известным падением `test_security_scheme_in_openapi` до
`session-auth`,
карта кода, команды `start_db`, `stop_db`, `upgrade`, `revision`,
`wipe_data`, `test_isolated`, без `run_no_compose`. Проверка: каждая команда из
таблицы есть в `Makefile` (`make -n <цель>`).
- [x] 8.3 Скилл `run-mtusi-messenger`: `driver.py start` перед
сервером выполняет `make upgrade`; `SKILL.md` без «рестарт = пустое
состояние» и `MemoryStore`. Проверка: `python3
.claude/skills/run-mtusi-messenger/driver.py all` — `start` сам
поднимает Postgres, `flow` без провалов, падают только smoke lab2 и
`test_security_scheme_in_openapi` (до `session-auth`, design, Goals),
затем `stop`.
- [x] 8.4 `REPORT.md`: запуск из чистого clone (`make run_docker`,
`make run_dev`, остановка, `make wipe_data`), проверки (`make
test_isolated`; `make student_test` против любого стенда);
архитектура — схема, транзакционные границы,
источник истины, семантика при конкурентных вставках, ограничение
часов, соответствие переменных `.env.example` skeleton; строки
доказательств уровня «3» по хранению со ссылками на `evidence/`.
Проверка: у каждой строки есть команда, наблюдение и путь к файлу.
- [x] 8.5 Финальная проверка: `make lint`, `make check`,
`openspec validate postgres-storage --strict`, `graphify update .`.
Проверка: все команды без ошибок.
## 9. Доработки по `/opsx:verify`
- [x] 9.1 `hide_parameters=True` в engine (решение 5), строка в
`infra.md`. Проверка: `messages` под `ACCESS EXCLUSIVE` в `psql`,
`POST` сообщения получает 503 по `statement_timeout` (SQLSTATE
`57014`), а в `warning` журнала вместо параметров —
`[SQL parameters hidden due to hide_parameters=True]` и нет текста
сообщения; вывод в `evidence/storage/statement-timeout.md`.
- [x] 9.2 Сценарий «Ошибка миграции» (`db-migrations`): `migrate` с
несуществующей базой через override-файл compose вне репозитория.
Проверка: `migrate` Exited с ненулевым кодом, `api` не запущен,
ошибка в журнале `migrate`, пароля в выводе нет; стенд возвращён
`make run_docker`; вывод в `evidence/migrations/migration-error.md`.
- [x] 9.3 Свежий `git clone` после commit: `make env_setup`,
`make run_dev` (сценарий «Консольный запуск с нуля», `db-migrations`),
затем `make run_docker` на тех же данных («Консоль, затем docker»,
`service-configuration`), `make down` и снова `make run_docker` («down
сохраняет данные», `container-run`). Проверка: каждый запуск доходит
до `/health/ready` 200 и видит данные, созданные в консоли; после
проверки volume clone удалён и рабочий стенд поднят заново; вывод в
`evidence/storage/fresh-clone.md`.
- [x] 9.4 Переснять `evidence/storage/restart.md` с `docker compose ps`
до и после hook (решение 10, `docker.md`, `scripts/restart.sh`).
- [x] 9.5 Текст: design — «79 из 80», `$(PYTHON)` в решении 12 и
причина; docstring `engine.py`; комментарий `.dockerignore`;
`REPORT.md` — исход commit на таймауте в «Ограничениях»; `AGENTS.md`
— отложенные сценарии в «Переходном состоянии» с changes, где они
закрываются. Проверка: `openspec validate postgres-storage --strict`.