Files
mtusi2026lab2/AGENTS.md
T
ricoromaandClaude Opus 5.5 2d0a7c83e9 feat: finish postgres-storage change
- 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>
2026-10-01 16:20:49 +03:00

38 KiB
Raw Blame History

MTUSI Messenger

REST API мессенджера (пользователи, чаты, история сообщений). Этот код переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — лаба 2 (lab.json): PostgreSQL как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или Valkey. Код перенесён из лабы 1, переход на lab2 идёт через changes OpenSpec (раздел «Переходное состояние»). Стек: Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog (JSON в stdout).

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

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

  • Контракт и skeleton не менять: contracts/, tests/, scripts/ (кроме своего scripts/restart.sh по образцу restart.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 в 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). Redis или Valkey (одно из двух) — на «4», с описанной ролью. uvicorn с одним worker: реплики — лаба 3.

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

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

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

Переходное состояние

Код перенесён из лабы 1 (commit 7b775a2), хранилище уже переведено на PostgreSQL (change postgres-storage). Этот файл и .claude/rules/ описывают целевое состояние лабы 2, поэтому в остальном код с ними пока расходится:

  • get_current_user читает X-User-Id, регистрации с паролем, входа и logout нет — change session-auth. До него публичный smoke лабы 2 не проходит, а test_security_scheme_in_openapi падает: он сверяет схему devUser с контрактом lab2, где её нет. make test_isolated поэтому ещё не зелёный;
  • student-tests/ идентифицируются X-User-Id, bench/ поднимает стенд без Postgres, inproc.py ссылается на удалённый MemoryStore (bench.md);
  • openspec/specs/ identification и users описывают поведение лабы 1;
  • REPORT.md заполнен только по хранению.

Правила лабы 1 — git show 7b775a2:.claude/rules/<файл>. Закрытый пункт убрать отсюда, закрытый переход — удалить раздел.

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

Договорённости, которых нет в 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+ — на будущее
contracts/examples.json, infrastructure.json примеры тел (проверяет make validate); роли инфраструктуры лабы: api, postgres, Redis/Valkey на «4»
lab.json номер лабы; по нему tests/client.py выбирает профиль (с лабы 2 — Basic при входе, дальше Bearer)
tests/smoke.py, tests/client.py публичный сквозной сценарий make test; что он проверяет и чего нет — tests/README.md
tests/resilience.py make test-persistence: данные и прежний токен после restart hook
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
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 перечислены в шапке, их соответствие — в 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, Redis/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
    student-tests.md student-tests/**: обязательные проверки уровня 4, black-box по HTTP, особый стенд
    bench.md bench/**: нагрузочный стенд из лабы 1 и его доработка под Postgres, что не меняется между метками замеров, диагностика и сравнение меток, коммиты измеренных состояний
    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.
  • 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 run_dev make upgrade (Postgres из compose и миграции), затем 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, config_example.toml → config.toml; существующие файлы не перезаписывает
make run_docker make env_setup (только недостающие файлы) + docker compose build + up -d: postgres → migrate → api; config.toml монтируется read-only
make stop / make down остановить / удалить контейнеры compose; volume с данными остаётся
make logs журнал API, каждая строка — JSON (--no-log-prefix)
make start_db / make stop_db Postgres стенда: up -d --wait postgres / stop postgres
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>: сборка, миграции, отдельный контейнер API на TEST_APP_PORT, make test + make student_test, уборка при любом исходе (student-tests.md)
make student_test [BASE_URL=...] собственные тесты student-tests/ (pytest) против запущенного сервера; сервер недоступен — код 2 и одна строка с адресом
make bench [BENCH_LABEL=...] полная матрица (~18 мин на лабе 1) на своём стенде mtusi-bench-* без портов хоста; результаты в evidence/bench/<метка>/, занятая метка — отказ. Перед запуском — подготовка хоста. Цели bench* под Postgres ещё не доработаны (.claude/rules/bench.md)
make bench_quick самопроверка стенда на малых размерах (~1,5 мин), метка quick-<время>, в git не идёт
make bench_inproc [BENCH_LABEL=...] куда уходит время одного запроса (~2 мин): приложение вызывается внутри процесса в образе стенда, без сервера и сети; заодно сверяет формат времени с эталоном. Результат в evidence/profile/<метка>.txt, занятая метка — отказ. Объясняет, но не меряет пропускную способность
make bench_ab BEFORE=... AFTER=... REAPPLY=<commit> «до» и «после» одного изменения подряд (~40 мин): bench и bench_inproc для BEFORE, commit доказательств, git revert commit отката REAPPLY, то же для AFTER. Нужно чистое рабочее дерево; сама делает два коммита
make bench_compare BEFORE=... AFTER=... [AA=...] дельта двух меток make bench по ячейкам матрицы; метки с разной методикой не сравнивает; с 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 и т.д.).

src/
  __main__.py                # python -m src → main.main()
  main.py                    # FastAPI app: lifespan, middlewares, обработчики ошибок, uvicorn.run
  config/settings.py         # Settings (pydantic-settings), экземпляр settings
  api/
    routers/health.py        # /health/live, /health/ready: вне версии, без идентификации
    routers/v1/<domain>.py   # ручки под /api/v1, сборка в routers/v1/__init__.py
    schemas/<domain>.py      # pydantic-модели запросов и ответов = схемы контракта
    dependencies.py          # текущий пользователь, фабрики сервисов, параметры пагинации
    errors.py                # доменное исключение → статус + code, формат ошибки контракта
    middlewares/             # X-Request-Id и access-лог; с лабы 3 — X-Instance-Id
  core/
    repos/<domain>.py        # атомарный доступ к хранилищу, модульные функции
    services/<domain>.py     # <Domain>Service: логика, проверки доступа, id и время, логи
    exceptions/<domain>.py   # доменные исключения, реэкспорт в __init__.py
  infra/
    logger.py                # structlog, get_logger(), contextvar-ы request_id / user_id
    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)
  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-курсор: кодирование и разбор
student-tests/               # black-box тесты по HTTP (уровень 4): make student_test
  conftest.py                # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat, сбор маркеров spec
  api_client.py              # Api поверх httpx; Actor.headers() — единственное место идентификации
  contract.py                # тела по схемам contracts/openapi.json, форматы id и created_at, assert_error
  spec_coverage.py           # исключения (сценарии, которые не проверить по HTTP) и сверка покрытия
  test_rubric.py, test_race.py  # обязательные сценарии и гонки уровня 4
  test_<capability>.py       # сценарии основных спеков, маркер @pytest.mark.spec
  run_isolated.py            # make test_isolated: образ на временной базе test_<db> (stdlib)
bench/                       # нагрузочный стенд из лабы 1 (под Postgres не доработан): make bench / make bench_quick
  run.py                     # оркестратор: стенд, матрица, метрики, runs.csv / summary.md / meta.json
  k6/                        # сценарии k6: prepare, prefill, cursors, read, tail, write; lib.js — общие хелперы
  inproc.py                  # make bench_inproc: разложение времени запроса внутри процесса, сверка формата времени
  compare.py                 # make bench_compare: дельта двух меток, уровень шума, эффект или шум
  ab.py                      # make bench_ab: прогоны «до» и «после» одного изменения подряд
migrations/, alembic.ini     # ревизии alembic, async env.py; применяет одноразовый сервис compose
infra/                       # конфигурации сервисов стенда (Postgres, Redis/Valkey); README.md — skeleton
scripts/restart.sh           # restart hook для make test-persistence, по restart.example.sh
Dockerfile                   # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
docker-compose.yml           # postgres, migrate, api; адреса и порты из .env, volume postgres_data
.dockerignore
config_example.toml, .env.example
evidence/storage/            # отказы БД, пул, рестарт, порты Postgres
evidence/migrations/         # миграции с нуля и повторно
evidence/tests/              # выводы make test_isolated и make student_test для REPORT.md
evidence/bench/<метка>/      # результаты make bench: паспорт, прогоны, наполнение, сводка, сырые итоги k6
evidence/profile/<метка>.txt # результаты make bench_inproc
evidence/compare/            # таблицы make bench_compare: <до>__<после>.md
KNOWN_ISSUES.md              # найденные попутно дефекты, не исправленные без просьбы

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

  • Поток однонаправленный. Роутер (зависимости, модели 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. Атомарность и защиту от гонок дают транзакции и ограничения Postgres (уникальность, ON CONFLICT), транзакцией управляет сервис. На лабе 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-сессия; Redis/Valkey на «4» infra/db/, migrations/, repo на AsyncSession; password при регистрации (KDF); get_current_user на Bearer; SESSION_TTL_SECONDS
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/, Dockerfile, docker-compose.yml, 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/ (граф собирается заново).
  • Сначала прочитать переходы 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, включая использование ИИ.