# 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_` (`\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 .`. Проверка: все команды без ошибок.