Files
mtusi2026lab3/AGENTS.md
T
ricoromaandClaude Opus 5.5 ce89eba22d docs: record the clean clone check of ebf080a
Repeat the REPORT.md "Запуск из чистого clone" sequence from a real git
clone of the final strict-id-validation code on the default ports: env
setup, stand, no-cache build, check, validate, smoke, instances on two
Python versions, persistence, failover of each replica and kill, own
tests, fault checks and the isolated run. All steps exit 0. The clone ran
as compose project mtusi-lab3-cleancheck while the working stand was
only stopped, because removing its volume was refused by the agent's
auto mode; the previous checks ran as mtusi-lab3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 13:32:33 +03:00

69 KiB
Raw Blame History

MTUSI Messenger

REST API мессенджера (пользователи, чаты, история сообщений). Этот код переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — лаба 3 (lab.json): балансировщик, ≥2 взаимозаменяемые API-реплики, общие сессии, обязательный Idempotency-Key на отправке сообщения и X-Instance-Id в ответах (README.md, COURSE.md, переход 2 → 3). Код перенесён из лабы 2 (репозиторий mtusi2026lab2-safronov, ветка solution/bvt2301-safronov, commit c6ad34d): PostgreSQL как источник истины, вход по Basic → Bearer-сессия, Valkey — кэш карточек чатов, трек 2 лабы 2 (план запроса и восстановление) в bench/. Change instance-id-idempotency добавил X-Instance-Id и Idempotency-Key, replicas-lb — HAProxy перед двумя репликами API, лимиты, scripts/stop-one.sh, graceful-failover — обоснованная и замеренная цепочка таймаутов, стенд bench/ на HAProxy + N реплик и профиль failover, rolling-update — поочерёдная замена реплик с дренажём через runtime API HAProxy (make rolling_update), expand-миграция и профиль rollout, scaling-bench — серии трека 1 «Цена масштабирования» (make bench_scaling: открытая модель, поиск R*, сэмплер, графики, насыщение пула и PostgreSQL управляемыми опытами) и ответ 503 на отказ PostgreSQL «too many clients», scaling-improvement — пул PostgreSQL 10 + 0 без переполнения (улучшение трека 1: профиль SERIES=db4, «до/после» с A/A, засчитано с оговоркой), profile-resources — CPU и память каждого компонента по окнам профилей failover и rollout (сэмплер scan, bench/resources.py, метки resources; добавлен после закрытия лабы, код приложения не трогает), fix-known-issues — исправление пяти записей KNOWN_ISSUES.md перед переносом: ранний обработчик SIGTERM до импорта приложения (src/infra/early_stop.py, docker stop стартующей реплики — 0,06 с вместо 10 с и SIGKILL), поток событий Docker в профиле failover, init: true у PostgreSQL стенда отказов и проверка его журнала, swapouts_delta при нуле, доказательства исключений сверки покрытия на стенде лабы 3 (команды драйвера cache-check, auth-storage; сверка падает на ссылке на отсутствующий файл), strict-id-validation — по рецензии PR: изменённый клиентом курсор — 400 вместо 500 (поля курсора проверяются по отдельности, незнакомые игнорируются — формат открыт для совместимых правок при поочерёдной замене), UUID на входе (chat_id, member_ids) — только запись 8-4-4-4-12 (UuidIn). Лаба 3 закрыта: все девять changes лабы 3 (девятый — strict-id-validation), как и changes перехода на lab2, — в openspec/changes/archive/, спеки синхронизированы, активных changes нет; KNOWN_ISSUES.md без открытых записей, REPORT.md заполнен, чистый clone проверен на итоговом коде ebf080a (evidence/tests/clean-clone-final.md). Дальше — перенос в лабу 4 (раздел «Переход в следующую лабу»). Рабочий план лабы (PLAN.md) удалён, его решения — в REPORT.md и design архивных changes; последняя версия — git show 063eedb:PLAN.md. Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey).

Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные тесты и REPORT.md пишем мы.

Обязательные правила

  • Контракт и skeleton не менять: contracts/, tests/, scripts/ (кроме своих scripts/restart.sh и scripts/stop-one.sh по образцам restart.example.sh и stop-one.example.sh), lab.json, README.md, COURSE.md, CONTRIBUTING.md, MAINTAINERS.md, .github/, compose.example.yaml, infra/README.md, цели check / validate / test / load / test-persistence / test-failover в Makefile. Если публичный тест упал, чиним приложение, а не тест. Если в контракте противоречие — сказать пользователю (это вопрос преподавателю), не выбирать трактовку самому. Ответ преподавателя записать в «Согласования с преподавателем».

  • Git не трогать без явной просьбы: никаких commit, push, checkout, reset, stash. Смотреть можно (git status, git diff, git log). Замер или evidence для отчёта снимается с закоммиченного кода, но коммит — только после подтверждения пользователя: показать изменения, предложить сообщение, ждать ок (.claude/rules/bench.md, «Измеренное состояние — commit»).

  • Перед завершением задачи с кодом — make lint. Правки API проверять на запущенном сервере (make run_dev или контейнер, затем make test и make student_test), а не «на глаз».

  • Тесты пишем, но только black-box по HTTP в student-tests/ (.claude/rules/student-tests.md). В bp_proxies тесты были запрещены, здесь они часть рубрики уровня 4.

  • Упавший тест — сначала разбор, потом правка. Воспроизвести падение, прочитать вывод и назвать причину: дефект приложения, ошибка в самом тесте или стенд (чужой сервис на порту, старый образ, не тот BASE_URL). Только после этого что-то менять, а в итоге задачи сказать, в чём была причина.

  • Если тест упал, чинится код, а не тест. Упавший тест из student-tests/ правится только в крайнем случае:

    • поведение меняется намеренно: так записано в дельте спека OpenSpec change или в контракте новой лабы. Тест правится вместе со спеком;
    • тест ошибочен сам: противоречит спеку или контракту либо зависит от случайного (порядок тестов, время, чужие данные на стенде). В итоге задачи назвать, чему именно он противоречит.

    «Тест красный» — не причина его править. Нельзя ослаблять проверку, подгонять ожидание под фактический ответ, ставить skip / xfail или удалять тест, чтобы прогон позеленел. Дефект приложения вне текущей задачи записывается в KNOWN_ISSUES.md (правило ниже), а тест остаётся как есть. Если причина неясна или правка теста спорная — остановиться и спросить.

  • Лаба 2: источник истины — PostgreSQL, SQLite его не заменяет. Пользователи, чаты, участники, сообщения и ещё действующие сессии переживают рестарт API и хранилищ без удаления volumes. Basic — только на POST /auth/sessions, остальное — Bearer; X-User-Id доступа не даёт; пароли — только через password KDF (auth.md). Valkey — на «4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey — обход кэша, а не ошибка (infra.md). Всё это сохраняется в лабе 3.

  • Лаба 3: ≥2 взаимозаменяемые реплики api за HAProxy — единственной публичной точкой входа; порты реплик наружу не публикуются, sticky session нет. В памяти процесса нет ничего, от чего зависит корректность: сессии, данные и ключи идемпотентности — в Postgres, Valkey — общий кэш неизменяемых карточек. В каждом ответе API — X-Instance-Id. POST сообщения требует Idempotency-Key; ключ и сообщение пишутся в одной транзакции (api-contract.md, service-layer.md). Миграции — однократно, отдельным сервисом, не репликами, и только расширяют схему: старые реплики работают на новой (migrations.md). Новый код доходит до реплик без простоя через make rolling_update. Стенд и отказы — balancer.md. В каждом процессе uvicorn по-прежнему один worker: масштабирование — числом реплик.

  • .env, config.toml, секреты, токены и реальные данные не попадают ни в git, ни в образ. В evidence/ и REPORT.md — только обезличенные выводы команд.

  • Найденный попутно дефект не чинить без просьбы: записать в KNOWN_ISSUES.md (завести при первой находке) с путём и предложением правки.

  • OpenSpec: если команде /opsx:* подходит больше одного изменения (change) — несколько активных в openspec/changes/, имя совпало частично, из контекста подходят несколько, — не выполнять её для всех подряд и не выбирать самому. Спросить, для какого изменения запустить: варианты — каждое по имени, последним — «все». То же при нескольких подходящих спеках (capability).

Согласования с преподавателем

Договорённости, которых нет в skeleton. Каждую упомянуть в REPORT.md и перенести в следующую лабу вместе с этим файлом, если она ещё действует.

Дата Договорённость Где учтено
2026-09-26 Лабы можно делать на FastAPI, несмотря на расхождения с контрактом (лишний 422, другой порядок кодов ошибок). Публичный smoke при этом должен проходить .claude/rules/api-contract.md, раздел «FastAPI»
2026-09-29 Конфиг через pydantic-settings: окружение → .env → config.toml → дефолты. config.toml не в git и не в образе, монтируется read-only при запуске. Это подходит под «конфигурация приходит из окружения» (README лабы 1, п. 3) и п. 6 Dockerfile.example. Требование «только env» — упрощение курса, config.toml можно использовать .claude/rules/settings.md, .claude/rules/docker.md

Задание и контракт: важные файлы

Файл Что в нём
README.md задание лабы: рубрика 3/4/5, сценарий и вопросы защиты, что приложить к PR
COURSE.md карта семи лаб, три объявленных перехода API (1→2, 2→3, 4→5), правила честных измерений
contracts/openapi.json нормативный OpenAPI 3.1: пути, схемы, коды ответов
contracts/README.md нормативная семантика: формат ошибок, валидация, пагинация, Basic → Bearer-сессии, TTL и отзыв, с lab3 — Idempotency-Key и X-Instance-Id; разделы lab4+ — на будущее
contracts/examples.json, infrastructure.json примеры тел (проверяет make validate); роли инфраструктуры лабы: api ×2+ без локального состояния, postgres, load_balancer; Redis/Valkey — необязательно; внутренние порты реплик в обход LB не публикуются
lab.json номер лабы (3); по нему tests/client.py выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer; с лабы 3 — идемпотентность)
tests/smoke.py, tests/client.py публичный сквозной сценарий make test; что он проверяет и чего нет — tests/README.md
tests/resilience.py make test-persistence: данные и прежний токен после restart hook; make test-failover: ≥2 реплики, запись во время остановки одной, повтор с тем же ключом, без дублей
tests/load.py closed-loop нагрузка POST сообщений (make load); для трека 5 одного его мало
scripts/check_contract.py, scripts/validate_openapi.py make check / make validate
scripts/restart.example.sh образец restart hook; свой — scripts/restart.sh: перезапуск API и всех хранилищ без удаления volumes
scripts/stop-one.example.sh образец failover hook; свой — scripts/stop-one.sh: остановить одну API-реплику по TARGET_INSTANCE_ID и оставить её остановленной
compose.example.yaml список ролей с пустым services, не стенд; свой стенд — свой compose-файл
infra/README.md куда класть конфигурации сервисов и что сопоставить в REPORT.md
REPORT.md отчёт: запуск из чистого clone, архитектура, доказательства по каждому критерию, эксперименты, ИИ и источники
evidence/ сохранённые выводы проверок и измерений (что можно класть — evidence/README.md)
CONTRIBUTING.md fork/PR, имя ветки, что переносить в следующую лабу
.github/pull_request_template.md шаблон PR; CI workflows/contracts.yml проверяет только контракт, приложение не запускает
Dockerfile.example опорные шаги Dockerfile, не рабочий файл
.env.example шаблон .env; «логические» имена skeleton (lab2 и новые lab3 API_REPLICAS, IDEMPOTENCY_TTL_SECONDS) перечислены в шапке, их соответствие — в REPORT.md (settings.md)
examples/requests.http ручные запросы для HTTP-клиента IDE

Где лежат инструкции

Четыре уровня, не дублировать их друг в друге:

  • AGENTS.md (этот файл): инварианты, команды, карта кода. CLAUDE.md импортирует его.

  • .claude/rules/*.md: правила по слоям. Подгружаются автоматически, когда открыт файл из paths: во фронтматтере. Проект пишется с нуля, а при создании файла через Write правило само не подгрузится. Поэтому перед созданием первого файла слоя его правило нужно прочитать руками.

    Файл Действует на
    api-contract.md src/api/**, src/core/**, src/schemas/**, student-tests/**: что требует контракт и где FastAPI по умолчанию его нарушает
    api-layer.md src/api/**, src/main.py: роутеры, зависимости, middlewares, обработчики ошибок
    service-layer.md src/core/services/**
    repo-layer.md src/core/repos/**
    dto.md src/schemas/**
    infra.md src/infra/**: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиенты
    auth.md src/**/session.py, сервис пользователей, dependencies.py, errors.py, идентификация в student-tests/: пароль и KDF, разбор Basic, токен, срок и отзыв сессии
    logging.md сервисы, API, инфраструктура, src/main.py: где и как логировать, чего в логах быть не должно
    settings.md src/config/**, .env.example, config_example.toml: источники настроек, что куда класть
    run-modes.md точки входа, Makefile, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERM
    docker.md Dockerfile, docker-compose.yml, .dockerignore, scripts/restart.sh, infra/**: мультистейдж, non-root, пины, healthcheck, стенд compose, volumes, restart hook
    balancer.md docker-compose.yml, infra/haproxy/**, scripts/stop-one.sh, scripts/rolling-update.sh: реплики за HAProxy, проверки и цепочка таймаутов, повторы LB, failover hook, поочерёдная замена, лимиты и пулы (с лабы 3)
    student-tests.md student-tests/**: обязательные проверки уровня 4, black-box по HTTP, особый стенд
    bench.md bench/**: нагрузочный стенд на Postgres (проект compose mtusi-bench), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состояний
    migrations.md migrations/**, alembic.ini, src/infra/db/models/**: схема до запросов, ограничения, индексы, повторный запуск миграций
  • openspec/ (схема spec-driven, язык артефактов — русский, см. openspec/config.yaml): что система делает и зачем. specs/<capability>/spec.md — текущее поведение, changes/<change>/ — предложения (proposal.md, design.md, tasks.md, дельты спеков), changes/archive/ — внедрённые. Крупную работу ведут командами /opsx:propose → /opsx:apply → /opsx:verify → /opsx:archive (ещё explore, update, sync). Команды в .claude/commands/opsx/ ставит openspec update, руками их не править. Спеки не пересказывают контракт и правила: в tasks.md ссылаться на contracts/ и .claude/rules/, а не копировать их.

  • Граф кода (graphify-out/, CLI graphify; локальный, не в git и не в образе, состав — .graphifyignore): для вопросов о структуре и связях — где используется, кто вызывает, что затронет правка. Команды: graphify query "<вопрос>", graphify path "A" "B", graphify explain "X", graphify affected "X". Граф — подсказка, а не источник правды: до обновления он отстаёт от кода.

    • Перед правкой — Read файла, как без графа: иначе правило слоя из .claude/rules/ не подгрузится. Граф этого не заменяет.
    • Граф строится без LLM: код — по AST, markdown — по структуре (разделы становятся узлами). Раздел правила или спеки связан (references, INFERRED) с символами кода, упомянутыми в его тексте в обратных кавычках. Полной карты «правило → код» в графе нет — она в таблице выше и в paths: правил.
    • query ищет узлы по подстроке метки. В запрос — имена символов кода ("ChatService ChatNotFound chat"), а не пересказ вопроса: тогда в ответе и код, и разделы правил и спек.
    • В граф не попадают .json / .yaml / .yml (contracts/openapi.json, docker-compose.yml), Dockerfile, Makefile и шаблоны конфигов: их CLI не разбирает. По ним — grep.
    • Только CLI graphify update .. Не запускать скилл /graphify и graphify extract: семантический разбор документов через LLM стоит сотни тысяч токенов, а следующий graphify update . всё равно заменяет его структурным. Не запускать graphify install, graphify claude install, graphify hook install и graphify watch: первые два пишут секцию в CLAUDE.md и PreToolUse-хук на Read, остальные пересобирают граф без спроса.

Окружение и команды

  • Python 3.12 (.python-version), зависимости через uv (uv sync, uv run ...), lock в uv.lock. ruff глобальный (/opt/homebrew/bin/ruff, им же пользуется PyCharm), в проекте он в extra dev.
  • Конфиг: .env (то, что читают compose и контейнеры зависимостей) + config.toml (то, что читает только приложение). Читает их src/config/settings.py (pydantic-settings), все поля — в секциях. Приоритет: окружение > .env > config.toml > дефолты. Параметры приложения в .env пишутся в формате настроек (APP__PORT), без секции — только то, что приложение не читает (APP_OUT_PORT). config.toml в образ не копируется, а монтируется на старте. Режим APP__RUN_MODE (console / docker) в .env не хранится. Подробно — settings.md, docker.md и run-modes.md.
  • Точка входа: python -m src (src/__main__.py → src/main.py), порт 8080.
  • make test ходит на http://localhost:8080. Если там отвечает чужой сервис, smoke упадёт с 404 на /health/live вместо ошибки соединения. Проверить, кто занял порт: lsof -nP -iTCP:8080 -sTCP:LISTEN, docker ps.
  • Стенд — проект compose mtusi-lab3 со своей базой. После make rolling_update реплики называются api-N с растущим номером (compose нумерует новые контейнеры сервиса по возрастанию): штатные цели с ними работают, make down + make run_docker снова дают api-1, api-2 (balancer.md).
  • make instances и публичные проверки skeleton запускаются системным python3 (3.9+ на macOS), без uv: драйвер скилла — только stdlib и синтаксис 3.9.
  • graphify (граф кода, «Где лежат инструкции») — вне проекта, в uv tool, версия закреплена:
    • CLI: uv tool install --python 3.12 'graphifyy==0.9.72'. Без --python 3.12 uv берёт free-threaded 3.14t, и установка падает на сборке tree-sitter-rust.
    • Сборка и обновление — одна команда graphify update . в корне: без LLM и токенов, около секунды, работает и в чистом clone. Граф обновляется вручную, после заметной работы (новый слой, закрыт change). Попутно update кладёт копию прошлого графа в graphify-out/<дата>/ и называет кластеры по центральному узлу.
Команда Что делает
make check офлайн-проверка структуры skeleton, JSON и синтаксиса Python-проверок
make validate PYTHON=.venv/bin/python полная валидация OpenAPI и примеров (валидатор стоит в dev-группе uv)
make test [BASE_URL=...] публичный smoke против запущенного сервера
make load нагрузка из tests/load.py; параметры — tests/README.md
make test-persistence ACTION_SCRIPT=scripts/restart.sh сохранность: создаёт данные и сессию, вызывает restart hook, проверяет те же данные прежним токеном (tests/README.md)
make test-failover ACTION_SCRIPT=scripts/stop-one.sh отказ одной API-реплики через LB: 15 с записи параллельно hook, восстановление записи ≤10 с, без дублей (tests/README.md). STOP_MODE=kill — без graceful, STOP_ONE_LOG=<файл> — какой TARGET_INSTANCE_ID и контейнер остановлен. Между прогонами — make replicas
make run_dev make upgrade (Postgres из compose и миграции) и make start_cache, затем APP__RUN_MODE=console uv run python -m src: 127.0.0.1:8080, reload
make lint ruff format + ruff check --fix, дважды: так нужно из-за COM812; tests/ и scripts/ skeleton исключены в [tool.ruff]
make env_setup .env.example → .env со случайными POSTGRES_PASSWORD и VALKEY_PASSWORD, config_example.toml → config.toml; существующие файлы не перезаписывает (новые строки шаблона переносятся руками)
make run_docker make env_setup (только недостающие файлы) + docker compose build + up -d: postgres, valkey → migrate → api × API_REPLICAS (2) → haproxy на 127.0.0.1:APP_OUT_PORT; config.toml, infra/valkey/valkey.conf и infra/haproxy/haproxy.cfg монтируются read-only. Реплики с изменённым образом пересоздаются все разом; без простоя — make rolling_update
make stop / make down остановить / удалить контейнеры compose; volume с данными остаётся
make logs журнал всех реплик API, каждая строка — JSON (--no-log-prefix), реплика — поле instance_id
make replicas [API_REPLICAS=N] вернуть остановленные реплики (те же ID) и выставить их число, ждать healthy (balancer.md)
make instances вход одним синтетическим пользователем, 12 × GET /users/me через LB: X-Instance-Id каждого ответа и итог по репликам
make lb_stats слоты HAProxy: адрес, состояние проверки (DRAIN, MAINT при замене), запросы, повторы, перенаправления (CSV статистики изнутри контейнера LB)
make rolling_update [COMMIT=...] [MIGRATE=0] поочерёдная замена реплик без простоя (scripts/rolling-update.sh, balancer.md): сборка из рабочего дерева (или файлов COMMIT через git archive), миграции один раз, затем по одной — новая healthy и UP в LB, старая drain → запросов в полёте 0 → maint → stop → rm → слот ready. Нужен штатный стенд (make replicas) без слотов LB в ручном drain / maint (иначе код 2 и команда set server … state ready); сбой и Ctrl+C — API_REPLICAS готовых реплик, повтор доводит; MIGRATE=0 — откат на прежний образ (после него docker compose up без сборки не запускать: migrate прежнего образа упадёт на новой ревизии)
make start_db / make stop_db Postgres стенда: up -d --wait postgres / stop postgres
make start_cache / make stop_cache Valkey стенда: up -d --wait valkey / stop valkey; volume нет, кэш после рестарта пуст
make upgrade start_db + uv run alembic upgrade head с хоста (127.0.0.1:POSTGRES_OUT_PORT)
make revision upgrade + alembic revision --autogenerate, сообщение спрашивает read -p
make wipe_data down -v — удалить данные стенда (и кэш); только после ввода yes
make test_isolated [KEEP_TEST_DB=1] образ на временной базе test_<db> с Valkey стенда (ключи разделены именем базы): сборка, миграции, отдельный контейнер API на TEST_APP_PORT, make test + make student_test EXPECT_REPLICAS=1 (тесты реплик пропускаются с причиной), уборка при любом исходе (student-tests.md)
make student_test [BASE_URL=...] [EXPECT_REPLICAS=...] собственные тесты student-tests/ (pytest) против запущенного сервера, кроме проверок отказов (-m 'not fault'); EXPECT_REPLICAS (по умолчанию API_REPLICAS) — сколько реплик за BASE_URL, против одного процесса — 1; сервер недоступен — код 2 и одна строка с адресом
make failure_checks [FAULT_ARGS=...] проверки отказов (pytest -m fault, ~60 с) на отдельном стенде: проект <рабочий>-failures со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook student-tests/fault_hook.py; после тестов — журнал PostgreSQL стенда: сводка (crash markers, «too many clients», «administrator command») и ненулевой код при признаках аварийного перезапуска; стенд и его volume удаляются при любом исходе, рабочий не трогается (student-tests.md)
make bench [BENCH_LABEL=...] полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по bench_quick) на своём проекте compose mtusi-bench (HAProxy и одна реплика API, Postgres, Valkey с лимитами, без портов хоста и без .env рабочего стенда; k6 ходит через LB); на каждый размер — свежий стенд, VACUUM (ANALYZE), планы запроса истории (auto_explain) по уровням чатов с вариантами индекса и запроса, в конце — пробы стоимости записи по вариантам. Результаты в evidence/bench/<метка>/, занятая метка — отказ. Перед запуском — подготовка хоста (bench.md)
make bench_quick самопроверка стенда на 1k / 5k / 10k и 3 500 фоновых сообщений (~3 мин), метка quick-<время>, в git не идёт
make bench_restore [RESTORE_LABEL=...] трек 2, восстановление (~20 мин, метка restore по умолчанию): тот же стенд и данные, без матрицы прогонов; на каждый размер — pg_dump во время записи через HTTP, активность после backup, pg_restore -j в новый контейнер Postgres на новом volume, сверка обеих баз построчно, переключение API, проверки через HTTP до и после FLUSHALL; время dump / restore / RTO и потерянные сообщения — в summary.md
make bench_restore_quick то же на 1k / 5k / 10k (~1,5 мин), метка quick-restore-<время>, в git не идёт; сценарий защиты трека 2
make bench_failover [FAILOVER_LABEL=...] уровень 4, отказ реплик под нагрузкой (~6 мин, метка baseline по умолчанию): стенд mtusi-bench с HAProxy и двумя репликами с лимитами рабочего стенда, k6 — 100 записей с ключом и 100 чтений в секунду; каждая реплика в режимах stop, kill, pause с возвратом. Посекундная шкала, время исключения из LB и восстановления, сверка записей после повтора с тем же ключом, CPU и память каждого компонента по окнам фазы (сэмплер scan, resources.csv, samples.csv; CPU на запрос — только до действия) — evidence/failover/<метка>/. Перед запуском — проверка хоста (bench.md): питание, давление памяти, Swapouts без роста; сумма лимитов на пике больше CPU ВМ — код 2
make bench_failover_quick то же короче, режимы stop и kill (~2 мин), с ресурсами, метка quick-failover-<время>, в git не идёт
make bench_rollout [ROLLOUT_LABEL=...] уровень 4, поочерёдная замена под нагрузкой (~3 мин, метка baseline по умолчанию): стенд mtusi-bench как у bench_failover, реплики на образе прежнего commit (Profile.rollout_from, git archive), та же нагрузка; посреди неё scripts/rolling-update.sh меняет их на образ текущего checkout. Посекундная шкала с ответами старых и новых реплик, шаги по репликам, контейнеры, образы и ревизия до и после, сверка записей, CPU и память каждой старой и новой реплики, миграции и остальных компонентов по окнам до / подготовка / замена / после (CPU на запрос — до и после) — evidence/rollout/<метка>/. Перед запуском — проверка хоста (bench.md)
make bench_rollout_quick то же с короткими окнами (~2 мин), с ресурсами, метка quick-rollout-<время>, в git не идёт
make bench_scaling SERIES=a|b|pool|ab|db|db4 [SCALING_LABEL=...] [RESUME=1] уровень 5, трек 1: серия на стенде mtusi-bench (метка scaling-<серия> по умолчанию). a — бюджет 4 CPU: 1 × 4, 2 × 2, 4 × 1 (~50 мин); b — 1…6 реплик по 1 CPU (~100 мин); pool — 4 реплики при max_connections 100 и 50 (~35 мин); ab — 1 × 1 и 6 × 1 для «до/после» и A/A (~35 мин); db — 1, 2, 4 реплики при PostgreSQL 0,5 CPU и контроль 4 × 1 при 2 CPU (~50 мин); db4 — только 4 × 1 при 0,5 и 2 CPU (~25 мин, «до/после» scaling-improvement); db_quick — самопроверка серии db (~4 мин, метка quick-*). Ячейка — конфигурация × повтор (3), свежий стенд; открытая модель 70/20/10, фиксированные 250 и 500/с и поиск R* по SLO; сэмплер контейнеров, ВМ, LB и PostgreSQL. RESUME=1 — продолжить прерванную метку на том же commit. Перед запуском — проверка хоста, рабочий стенд — make stop; метку коммитить до следующей серии (bench.md)
make bench_scaling_quick самопроверка серий: 1 × 1 и 2 × 1 при max_connections 50, короткие окна (~4 мин), метка quick-scaling-<время>, в git не идёт
make bench_plots LABELS="..." [PLOTS=scaling] графики SVG и сводка серий трека 1 из меток: R* от числа реплик, p95 от интенсивности, CPU по компонентам, эффективность и точка насыщения — evidence/plots/<PLOTS>/
make bench_ab BEFORE=... AFTER=... REAPPLY=<commit> [SERIES=...] «до» и «после» одного изменения подряд (два прогона bench): bench для BEFORE, commit доказательств, git revert commit отката REAPPLY, bench для AFTER; с SERIES — серия трека 1 вместо матрицы (make bench_scaling). Нужно чистое рабочее дерево; сама делает два коммита
make bench_compare BEFORE=... AFTER=... [AA=...] [CHANGE=...] дельта двух меток make bench по ячейкам матрицы, у серий трека 1 — по общим конфигурациям (R*, задержки на фиксированных уровнях, CPU на запрос) и таблица PostgreSQL на R* и первой нарушившей ступени (CPU на запрос, новые сессии, соединения); CHANGE — change в шапке сравнения серий (по умолчанию scaling-bench); метки с разной методикой не сравнивает (в том числе метку без LB с меткой стенда на LB и серию с матрицей); с AA (метка того же кода, что BEFORE) отделяет эффект от шума. Результат в evidence/compare/<до>__<после>.md

Разовая подмена внешнего порта — аргументом make: make run_docker APP_OUT_PORT=8090, затем make test BASE_URL=http://localhost:8090. Префикс окружения (APP_OUT_PORT=8090 make ...) не работает: Makefile подключает .env (run-modes.md, Troubleshooting).

Карта кода

Файлы домена называются одинаково во всех слоях (user, chat, message, session, idempotency и т.д.).

src/
  __main__.py                # python -m src: early_stop.install() до импорта приложения → main.main()
  main.py                    # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
  config/settings.py         # Settings (pydantic-settings), экземпляр settings; [app] instance_id (пусто → hostname) и keep_alive_seconds, [database] pool_size 10 и max_overflow 0 (постоянный пул без переполнения), idle_in_transaction_timeout_ms, [idempotency] ttl_seconds
  api/
    routers/health.py        # /health/live, /health/ready: вне версии, без идентификации
    routers/v1/<domain>.py   # ручки под /api/v1, сборка в routers/v1/__init__.py; Idempotency-Key — параметр POST сообщения (message.py)
    schemas/<domain>.py      # pydantic-модели запросов и ответов = схемы контракта; common.py — UuidIn: UUID от клиента (путь, тело) только в записи 8-4-4-4-12
    dependencies.py          # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
    errors.py                # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта; у 500 — X-Request-Id и X-Instance-Id
    middlewares/             # X-Request-Id, X-Instance-Id и access-лог
  core/
    repos/<domain>.py        # атомарный доступ к хранилищу, модульные функции
    repos/idempotency.py     # ключ идемпотентности: захват ON CONFLICT DO UPDATE WHERE просрочен, чтение сохранённого результата
    repos/chat_cache.py      # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
    services/<domain>.py     # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем; отправка — ключ и сообщение одной транзакцией
    exceptions/<domain>.py   # доменные исключения, реэкспорт в __init__.py
  infra/
    early_stop.py            # ранний обработчик SIGTERM/SIGINT (только stdlib): до старта сервера — запись «Stopped API before startup» и выход 0; disarm() — первая строка lifespan
    logger.py                # structlog, get_logger(), contextvar-ы request_id / user_id, instance_id в каждой записи
    password.py              # Argon2id в потоке со своим лимитом, фиктивный хэш для неизвестного username
    db/engine.py             # фабрики engine и сессий, BoundedCloseConnection, ping
    db/session.py            # глобалы engine и session_factory процесса API
    db/errors.py             # is_db_unavailable: какие ошибки драйвера — 503
    db/models/               # модели SQLAlchemy (Base с created_at и to_dict); idempotency.py — ключи, FK на сообщение отложен до commit
    cache/client.py          # create_cache (redis-py: повтор только на обрыв, блокирующий пул), Cache: срок на команду, отказ — промах и пропуск
    cache/instance.py        # глобал cache процесса API
  schemas/
    dataclasses/<domain>.py  # DTO между repo → service → api
    enums/<domain>.py        # StrEnum доменов, RunModeEnum
  utils/
    constants.py             # лимиты контракта, размер страницы, префиксы путей
    utc.py                   # utcnow() (aware UTC), формат RFC 3339 с Z
    cursor.py                # непрозрачный keyset-курсор: кодирование и разбор; поля проверяются по отдельности, незнакомые игнорируются, смена формата — новая CURSOR_VERSION
student-tests/               # black-box тесты по HTTP (уровень 4): make student_test
  conftest.py                # BASE_URL, EXPECT_REPLICAS и фикстура replicas (пропуск против одного процесса), проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
  api_client.py              # Api поверх httpx; Actor.headers() — единственное место идентификации; post_message/send_message — с Idempotency-Key
  contract.py                # тела по схемам contracts/openapi.json, форматы id и created_at, X-Instance-Id, assert_error, assert_errors (статусы всех вариантов запроса разом), assert_replicas
  test_idempotency.py        # спек idempotency: ключ, повтор, 409, область, порядок кодов, повтор через другую реплику (гонка — test_race.py, отказы — test_failures.py)
  test_load_balancing.py     # спек load-balancing (вне сверки покрытия): одна сессия на разных репликах, запись видна через другую реплику
  spec_coverage.py           # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия; missing_evidence — файл evidence по ссылке исключения должен быть в репозитории
  test_rubric.py, test_race.py  # обязательные сценарии и гонки уровня 4
  test_<capability>.py       # сценарии основных спеков, маркер @pytest.mark.spec
  test_failures.py           # проверки отказов (маркер fault): только make failure_checks
  run_isolated.py            # make test_isolated: образ на временной базе test_<db> (stdlib)
  run_failures.py            # make failure_checks: стенд <рабочий>-failures, два API, pytest -m fault, журнал PostgreSQL стенда (сводка, признаки аварии — ненулевой код), уборка (stdlib)
  fault_hook.py              # hook стенда отказов: stop/start/pause/unpause, кэш, триггеры сбоя участников и сообщений, заполнение слотов max_connections, счётчик сессий PostgreSQL db-sessions (stdlib)
  failures.compose.yml       # override стенда отказов: без публикации портов (Postgres, Valkey, LB), healthcheck PostgreSQL — на служебную базу postgres (не добавляет сессий в базу приложения), init: true у PostgreSQL (сирот psql из fill-connections подбирает init, а не postmaster)
bench/                       # нагрузочный стенд на HAProxy + N реплик API + Postgres + Valkey: make bench / bench_quick / bench_restore / bench_failover / bench_rollout / bench_scaling
  run.py                     # оркестратор: стенд compose, реплики и готовность по LB, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, фазы профиля failover (события цели — поток docker events по контейнеру, а не буфер демона), профиль rollout (образ прежнего commit через git archive, scripts/rolling-update.sh против проекта стенда, поток событий Docker с exec_start), ресурсы профилей failover и rollout (Profile.sample_resources: сэмплер scan, карта контейнеров по меткам compose, окна, бюджет на пике, сторож), серии трека 1 (профили scaling_*, ячейки на свежем стенде, ступени k6 и поиск R*, сэмплер, продолжение RESUME, блокировка bench/.bench.lock), метрики (сумма по репликам), runs.csv / phases.csv / searches.csv / samples.csv / summary.md / meta.json
  scaling.py                 # серии трека 1 без docker: лестница и автомат поиска R*, разбор итога k6 и строк сэмплера, агрегаты окна, вердикт SLO и брака генератора, признаки узкого места (THRESHOLDS), предельный CPU на запрос, сводка серии; --selftest
  plots.py                   # make bench_plots: SVG на stdlib (R* от числа реплик, p95 от интенсивности, CPU по компонентам) и сводка с точкой насыщения; render_series — графики в каталоге метки
  sampler.sh                 # сэмплер (только в контейнере mtusi-bench-sampler на образе PostgreSQL, --cgroupns host): режим list (серии) — cpu.stat, память и PSI заданных контейнеров, /proc/stat и PSI ВМ, статистика HAProxy, psql \watch по pg_stat_activity / database / wal / io; режим scan (failover, rollout) — обход cgroup всех контейнеров и /proc/stat, без сети, psql и LB
  resources.py               # ресурсы профилей failover и rollout без docker: интервалы контейнеров (сброс при новой cgroup, заморозка, новые контейнеры с момента запуска), окна, CPU / троттлинг / память по компонентам и ВМ, CPU на запрос в установившихся окнах, resources.csv / samples.csv, разделы summary.md; --selftest
  failover.py                # профиль failover без docker: строки k6 о запросах, статистика и журнал HAProxy, события Docker, посекундная шкала, величины фазы, summary.md
  rollout.py                 # профиль rollout без docker: строки скрипта замены, события контейнеров проекта, состояния слотов LB (UP, drain, maint, ready), шаги по репликам, шкала со старыми и новыми ответами, окна до / во время / после, summary.md
  bench.compose.yml          # override стенда mtusi-bench: имена, BENCH_API_REPLICAS реплик api без container_name, haproxy с лимитами BENCH_LB_*, лимиты BENCH_* (deploy.resources), без портов и config.toml, auto_explain
  bench.env                  # подстановки compose стенда вместо .env рабочего стенда (без паролей)
  k6/                        # сценарии k6 (через LB http://haproxy:8080): prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления), failover (постоянная интенсивность записи и чтения, строка на запрос) и retry (повтор неуспешных записей с тем же ключом), mixed (ступень серии трека 1: ramping-arrival-rate 70/20/10, тег окна, распределение по X-Instance-Id, досрочный выход); lib.js — Bearer, messageHeaders (новый или заданный Idempotency-Key) и хелперы
  compare.py                 # make bench_compare: дельта двух меток (ячейки матрицы или общие конфигурации серий), уровень шума, эффект или шум; отказ при разной методике, в том числе метке без LB и серии против матрицы
  ab.py                      # make bench_ab: прогоны «до» и «после» одного изменения подряд, с --series — серии трека 1
migrations/, alembic.ini     # ревизии alembic, async env.py; применяет одноразовый сервис compose
infra/                       # конфигурации сервисов стенда; README.md — skeleton
  valkey/valkey.conf         # лимит памяти и LRU, persistence выключен
  haproxy/haproxy.cfg        # LB рабочего стенда и bench/: реплики через DNS Docker (8 слотов), проверки /health/ready (inter, fastinter, формулы обнаружения), цепочка таймаутов, http-reuse never (простаивающее соединение закрывает LB), повтор только на conn-failure, ответы LB в формате контракта, мониторинг :8404, runtime API на 127.0.0.1:9999 внутри контейнера (drain / maint / ready при замене)
scripts/restart.sh           # restart hook для make test-persistence, по restart.example.sh: LB, все реплики api, postgres, valkey
scripts/stop-one.sh          # failover hook для make test-failover: TARGET_INSTANCE_ID → реплика api этого проекта, STOP_MODE stop или kill, STOP_ONE_LOG
scripts/rolling-update.sh    # make rolling_update: предусловия (в том числе слоты LB без ручного состояния), сборка (или COMMIT через git archive), миграции один раз в контейнере сервиса migrate, по одной: новая UP в LB → старая drain → maint → stop (код выхода в строке) → rm → слот ready; trap при сбое и Ctrl+C; тот же скрипт — профиль rollout стенда bench/
Dockerfile                   # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
docker-compose.yml           # проект mtusi-lab3: postgres, valkey, migrate, api × API_REPLICAS без портов, haproxy — единственный порт API; адреса и порты из .env, volume postgres_data, лимиты у всех, окружение по сервисам
.dockerignore
config_example.toml, .env.example
evidence/storage/            # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone; connection-cost.md — цена нового соединения и пинга
evidence/migrations/         # миграции с нуля и повторно, ошибка миграции
evidence/auth/               # passwords-and-tokens.md — driver.py auth-storage на стенде лабы 3: Argon2id в users, SHA-256 токена в sessions, ни токена, ни пароля в pg_dump (исключения сверки покрытия)
evidence/cache/              # hits.md — make test_isolated + driver.py cache-check на стенде лабы 3: одно чтение chats на 50 через LB, TTL, ключи двух баз (исключения сверки покрытия)
evidence/tests/              # выводы make test_isolated, make student_test (через LB) и make failure_checks для REPORT.md; profile-resources-checks.md — проверки сэмплера, быстрые профили, сторож, хост и сравнение меток resources с baseline; fix-known-issues-checks.md — сверка событий поток/буфер, красный и зелёный failure_checks, консоль, сверка ссылок исключений, регрессия; strict-id-validation-checks.md — красный и зелёный прогоны курсора и UUID на входе, пересмотр проверки курсора, замена реплик, клон во временном проекте
evidence/idempotency/        # повтор, 409, гонка, таблица ключей, X-Instance-Id
evidence/replicas/           # стенд с LB: порты, лимиты и их цена для Argon2id, окружение, распределение, ответы LB (нет реплик, зависшая, без PostgreSQL), test-persistence, чистый clone на нестандартных портах
evidence/failover/           # make test-failover для каждой реплики (stop и kill), отказы stop-one.sh; замер обнаружения, keep-alive, зависшая реплика и ключ; stop-at-start.md — docker stop стартующей реплики «до/после» раннего обработчика и ветка сбоя rolling-update.sh
evidence/failover/<метка>/   # результаты make bench_failover: паспорт, phases.csv, посекундная timeline.csv, summary.md, итоги k6 и журнал LB по фазам; с change profile-resources (метка resources и новые) — resources.csv (фаза × окно × компонент) и samples.csv (посекундно от действия)
evidence/rollout/            # совместимость старого образа с новой схемой, make rolling_update и жизненный цикл стенда после замены, отказы скрипта (Ctrl+C, слоты, lock_timeout миграции)
evidence/rollout/<метка>/    # результаты make bench_rollout: паспорт с контейнерами, образами и ревизией до и после, rollout.csv, replicas.csv, timeline.csv, summary.md, строки скрипта, журнал LB; с change profile-resources (метка resources и новые) — resources.csv (окно × компонент) и samples.csv (посекундно от начала замены)
evidence/bench/<метка>/      # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
evidence/bench/scaling-*/    # серии трека 1 (a, b, pool, A/A scaling-aa, db — насыщение PostgreSQL; db4 — «до/после» пула без переполнения: scaling-db-aa*, -before*, -nooverflow*, окончательные — с суффиксом 2): паспорт с планом, бюджетом и лимитами по конфигурациям, runs.csv (строка на ступень), searches.csv (строка на ячейку), samples.csv (посекундно в окнах), summary.md, p95-by-rate.svg, cpu-by-component.svg, итоги k6 ступеней и журналы 5xx
evidence/plots/scaling/      # make bench_plots по сериям a и b: графики SVG и summary.md (R*, эффективность, точка насыщения, цена запроса, память)
evidence/plots/scaling-db/   # make bench_plots по серии db: R* по лимитам PostgreSQL и раздел «Насыщение PostgreSQL»
evidence/compare/            # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md              # найденные попутно дефекты, не исправленные без просьбы

evidence/ перенесён без содержимого лабы 2 (оно осталось в репозитории mtusi2026lab2-safronov). Каталоги выше появляются заново по мере changes.

Архитектура в двух словах

  • Поток однонаправленный. Роутер (зависимости, модели API) → сервис (логика, проверки доступа, id и время, логи) → repo (одна атомарная операция над хранилищем, отдаёт DTO) → PostgreSQL через AsyncSession (src/infra/db/). Подробности — в правилах слоёв.
  • Отличия от bp_proxies. Из core/ вынесены инфраструктура (src/infra/: логгер, хранилища, клиенты), утилиты (src/utils/), настройки (src/config/ вместо src/data/) и HTTP-модели (src/api/schemas/ вместо schemas/pydantic/). В core/ остались доменные слои: repos, services, exceptions. Бота, loader и контроллера нет; фоновая работа появится в лабе 5 отдельным worker.
  • Ошибки: сервис бросает доменное исключение. src/api/errors.py одной таблицей переводит его в статус и code и отдаёт тело {"error": {...}} с request_id. HTTPException в сервисах и ручках не используется.
  • Конкурентность: все ручки и зависимости — async def, один event loop, один worker в процессе, процессов — API_REPLICAS за HAProxy. Атомарность и защиту от гонок, в том числе между репликами, дают транзакции и ограничения Postgres (уникальность, ON CONFLICT), транзакцией управляет сервис. Повтор POST сообщения через другую реплику находит тот же ключ идемпотентности в Postgres. На лабе 1 ту же роль играло отсутствие await внутри repo-функции над MemoryStore. KDF пароля — в потоке, чтобы не останавливать event loop.
  • Request id генерирует middleware. Тот же id уходит в заголовок X-Request-Id, в request_id тела ошибки и в каждую строку лога.

Соглашения по коду

  • ruff: 79 символов, py312, набор правил в pyproject.toml (isort, bugbear, comprehensions, unused-arguments, pyupgrade, simplify, quotes). Кавычки как в файле (quote-style preserve), trailing comma обязательна.
  • Типизация везде: X | None, list[...], UUID и datetime вместо строк. Методы сервисов keyword-only (*,); repo и сервисы вызываются только именованными аргументами.
  • Комментарии и докстринги короткие, на русском. Сообщения логов и тексты ошибок API (error.message) — на английском.
  • Константы (лимиты контракта, размер страницы, пути) — в src/utils/constants.py, не литералами в коде.
  • Время только через utcnow() из src/utils/utc.py: aware UTC. В bp_proxies был naive UTC, здесь контракт требует ...Z, а с лабы 2 — timestamptz.
  • Коммиты (когда попросят): английский, conventional style (feat: ..., fix: ..., refactor: ...).

Дорожная карта лаб

Каждая лаба — отдельный skeleton-репозиторий; переходы API — COURSE.md нового skeleton. Что меняется в коде:

Лаба Что появляется Где в коде
1 in-memory API, Dockerfile infra/memory.py, X-User-Id в get_current_user
2 PostgreSQL, Basic → Bearer-сессия; Valkey на «4» infra/db/, migrations/, repo на AsyncSession; password при регистрации (KDF); get_current_user на Bearer; SESSION_TTL_SECONDS; кэш карточки чата — infra/cache/, repos/chat_cache.py
3 балансировщик, ≥2 реплики, идемпотентность middleware X-Instance-Id; Idempotency-Key на POST сообщения; никакого состояния в памяти процесса
4 приватный S3, вложения клиент в infra/, домен attachment
5 брокер, worker, превью отдельная точка входа worker; загрузка отвечает 202
6 OTel Collector, Grafana телеметрия в infra/
7 Argon2id, TLS/mTLS, OpenBao HTTPS, секреты из OpenBao

Переход в следующую лабу

По CONTRIBUTING.md: fork нового skeleton, ветка solution/<group>-<surname>, затем перенести своё.

  • Переносить: src/, student-tests/, migrations/, alembic.ini, Dockerfile, docker-compose.yml, infra/valkey/, infra/haproxy/ (без infra/README.md skeleton), свои scripts/restart.sh, scripts/stop-one.sh и scripts/rolling-update.sh (без примеров и проверок skeleton в scripts/), pyproject.toml, uv.lock, .python-version, config_example.toml, AGENTS.md, CLAUDE.md, .claude/, openspec/, .graphifyignore, bench/, KNOWN_ISSUES.md.
  • Сливать, а не копировать поверх: Makefile, .env.example, .gitignore, .dockerignore. Берём версию нового skeleton (в ней новые цели и проверки) и дописываем свои секции.
  • Не копировать: .git, .env, config.toml, volumes, README.md, COURSE.md, tests/, contracts/, lab.json, REPORT.md, evidence/ (доказательства остаются в репозитории своей лабы), graphify-out/ (граф собирается заново).
  • Доказательства исключений сверки покрытия снять заново на стенде новой лабы, иначе make student_test красный (test_exclusion_evidence_exists называет сценарий и путь): make test_isolated, затем driver.py --port <LB> cache-check --require-test-keys → evidence/cache/hits.md; driver.py --port <LB> auth-storage → evidence/auth/passwords-and-tokens.md; make test-persistence ACTION_SCRIPT=scripts/restart.sh → evidence/replicas/test-persistence.md (или путь, который назовёт исключение); повтор отправки с ключом после docker compose up -d --force-recreate api → evidence/idempotency/replay-after-restart.md (student-tests.md). Файлы evidence/ лабы 3 в новую лабу не копировать, даже эти четыре: сверка проверяет только наличие файла и с копией останется зелёной без пересъёмки.
  • Сначала прочитать переходы API в COURSE.md и contracts/README.md нового skeleton, потом править код. Обновить этот файл: номер лабы, таблицу важных файлов, новые правила.

Ветки и PR

Git — только по просьбе. Когда просят, порядок такой:

  • Работа идёт в ветке solution/bvt2301-safronov от ветки skeleton.
  • PR — в исходный репозиторий преподавателя. Заголовок ЛР N — Группа — Фамилия — на 3/4/5, тело — по .github/pull_request_template.md. Перед PR выполнить make check, make test на собранном из чистого clone образе и заполнить REPORT.md, включая использование ИИ.