Source: mtusi2026lab4-safronov, solution/bvt2301-safronov, 2546deb. Contracts, public tests and evidence of lab 4 are not carried over. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
18 KiB
18 KiB
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. Зависимости и настройки
- 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"без ошибок. - 1.2 Секция
Databaseвsrc/config/settings.py: адрес, учётные данные, пул и таймауты из таблицы решения 5,urlчерезURL.create. Проверка: без.envиconfig.tomlSettingsзагружается на дефолтах; парольp@ss%wordдаёт рабочий URL, аurl.render_as_string(hide_password=True)его не показывает. - 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. Модели и миграции
- 2.1
src/infra/db/:Base(created_at,to_dict()), моделиusers,chats,chat_members,messagesс ограничениями и индексами из решения 3; фабрика engine иasync_sessionmaker(решение 5). Проверка:Base.metadata.sorted_tables— четыре таблицы; у всех ограничений есть имена. - 2.2
alembic.iniи асинхронныйmigrations/env.py(решение 8): URL изsettings.database.url, логи черезsrc/infra/logger.py, логгерalembicнаINFO. Проверка: при запущенном Postgresuv run alembic currentпечатает JSON-строки, пароля в выводе нет. - 2.3 Первая ревизия: autogenerate, затем руками
CHECKи проверка имён ограничений;downgradeзеркалитupgrade. Проверка: на пустом volumemake upgradeсоздаёт таблицы (\d+вpsql),alembic downgrade baseи сноваupgrade headпроходят, повторныйmake upgradeничего не меняет.
3. Compose, образ, Makefile
- 3.1 Выбрать тег Postgres 18.x с патч-версией и digest индекса
(
docker buildx imagetools inspect), точку монтирования volume взять изConfig.Volumesобраза (решение 9). Проверка: тег, digest и путь записаны вdocker-compose.yml, путь совпадает с метаданными. - 3.2
docker-compose.yml:name:, якорьx-app-env, сервисыpostgres(PGPORT, алиас,pg_isready, volumepostgres_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. - 3.3
Dockerfile:COPY migrations alembic.iniв runtime, комментарий — лаба 2. Проверка: образ из контекста чистого clone (docker.md) собирается; в/appестьmigrations/иalembic.ini,alembic --helpработает,uvне найден. - 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пусто. - 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
- 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всей выборки. - 4.2 Сервисы на
db_session, commit в сервисе, создание чата — одна транзакция (решение 4); удалитьMemoryStore,get_storeиsrc/infra/memory.py. Проверка:grep -rn MemoryStore srcпусто,make lintчистый. - 4.3 Engine и фабрика сессий — глобалы
src/infra/db/session.py(решение 5),dispose()в lifespansrc/main.py;dependencies.py:get_db_session, фабрики сервисов;get_current_userпо-прежнему поX-User-Id. Проверка:make run_devподнимается до/health/ready200; по SIGTERM в журнале «Stopped API» и «Finished server process»; пароля в журнале нет.
5. Недоступность БД и readiness
- 5.1 Определить классы исключений: API запущен, Postgres
остановлен (
docker compose stop postgres), затем приостановлен (docker compose pause postgres); записать исключения из traceback для отказа в соединении, клиентского таймаута и таймаута пула. Проверка: список внесён в решение 6design.md. - 5.2 Перехват в
get_db_session(решение 6): откат,warning,ServiceUnavailable. Проверка: сценарии «БД остановлена» и «БД вернулась» (data-storage) — 503unavailableбез деталей, послеdocker compose start postgresзапросы проходят без рестарта API; вывод вevidence/storage/db-unavailable.md. - 5.3
/health/ready:SELECT 1с таймаутом через engine. Проверка: при остановленном Postgres/health/ready— 503 не позже таймаута,/health/live— 200. - 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. Рестарт стенда
- 6.1
scripts/restart.shпо решению 10, исполняемый бит в git. Проверка:git ls-files -s scripts/restart.sh— режим100755; скрипт укладывается в 90 с; по журналу записано, прогоняет лиupсервисmigrateзаново. - 6.2 Сценарий «Рестарт hook-ом» (
container-run) и «Прежний пользователь после рестарта» (data-storage): пользователь, чат сmember_idsв порядке[bob, alice], сообщения;StartedAtдо и послеscripts/restart.sh. Проверка: после рестарта тот жеX-User-Idполучает 200, история и порядок участников прежние; вывод вevidence/storage/restart.md.
7. Проверки стенда
- 7.1 Сценарий «Консоль и контейнер» (
student-tests):make student_testпротивmake run_devи противmake run_docker. Проверка: в обоих прогонах прошли все тесты, кромеtest_security_scheme_in_openapi(переход контракта, design, Goals). Evidence набора против контейнера снимаетsession-auth. - 7.2 Миграции с нуля и повторно (
db-migrations):make wipe_data,make run_docker, журналmigrate; затем повторный прогон миграций при данных в базе. Проверка:migrateзавершился с кодом 0 раньше старта API; число строк во всех таблицах до и после повтора одинаково; вывод вevidence/migrations/from-zero-and-rerun.md. - 7.3 Сценарий «Другой порт Postgres»:
POSTGRES_PORT=5544,POSTGRES_OUT_PORT=5545в.env, compose не правится. Проверка:make run_dockerдоходит до/health/ready200,make run_devподключается к127.0.0.1:5545;.envвозвращён; вывод вevidence/storage/postgres-port.md. - 7.4 Сценарий «Консоль, затем docker» (
service-configuration) и «down сохраняет данные» (container-run). Проверка: данные, созданные черезmake run_dev, видны послеmake run_dockerи послеmake down+make run_docker, файлы конфигурации не менялись. - 7.5 Сценарий «Адрес публикации» (
container-run). Проверка:docker portдля API и Postgres стенда показывает127.0.0.1, а не0.0.0.0. - 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. - 7.7 Перенести дельты в основные спеки (
/opsx:sync) и в том же шаге обновитьstudent-tests/spec_coverage.py: тексты исключений «Прежний пользователь после рестарта» и «Хранилище не готово», исключения для «Сбой при добавлении участников», «БД остановлена», «БД вернулась», «Соединения исчерпаны» со ссылками на evidence и changefailure-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. Документы и инструменты
- 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пусто. - 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 <цель>). - 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. - 8.4
REPORT.md: запуск из чистого clone (make run_docker,make run_dev, остановка,make wipe_data), проверки (make test_isolated;make student_testпротив любого стенда); архитектура — схема, транзакционные границы, источник истины, семантика при конкурентных вставках, ограничение часов, соответствие переменных.env.exampleskeleton; строки доказательств уровня «3» по хранению со ссылками наevidence/. Проверка: у каждой строки есть команда, наблюдение и путь к файлу. - 8.5 Финальная проверка:
make lint,make check,openspec validate postgres-storage --strict,graphify update .. Проверка: все команды без ошибок.
9. Доработки по /opsx:verify
- 9.1
hide_parameters=Trueв engine (решение 5), строка вinfra.md. Проверка:messagesподACCESS EXCLUSIVEвpsql,POSTсообщения получает 503 поstatement_timeout(SQLSTATE57014), а вwarningжурнала вместо параметров —[SQL parameters hidden due to hide_parameters=True]и нет текста сообщения; вывод вevidence/storage/statement-timeout.md. - 9.2 Сценарий «Ошибка миграции» (
db-migrations):migrateс несуществующей базой через override-файл compose вне репозитория. Проверка:migrateExited с ненулевым кодом,apiне запущен, ошибка в журналеmigrate, пароля в выводе нет; стенд возвращёнmake run_docker; вывод вevidence/migrations/migration-error.md. - 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/ready200 и видит данные, созданные в консоли; после проверки volume clone удалён и рабочий стенд поднят заново; вывод вevidence/storage/fresh-clone.md. - 9.4 Переснять
evidence/storage/restart.mdсdocker compose psдо и после hook (решение 10,docker.md,scripts/restart.sh). - 9.5 Текст: design — «79 из 80»,
$(PYTHON)в решении 12 и причина; docstringengine.py; комментарий.dockerignore;REPORT.md— исход commit на таймауте в «Ограничениях»;AGENTS.md— отложенные сценарии в «Переходном состоянии» с changes, где они закрываются. Проверка:openspec validate postgres-storage --strict.