- keep engine and session factory in src/infra/db/session.py - sync delta specs into openspec/specs, add db-migrations spec - update rules, AGENTS.md and run skill for lab 2 storage - fill REPORT.md for the storage part Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
214 lines
16 KiB
Markdown
214 lines
16 KiB
Markdown
# 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 .`.
|
||
Проверка: все команды без ошибок.
|