Files
mtusi2026lab2/AGENTS.md
T
2026-10-02 05:17:41 +03:00

42 KiB
Raw Blame History

MTUSI Messenger

REST API мессенджера (пользователи, чаты, история сообщений). Этот код переносится через все семь лабораторных курса и на каждой обрастает инфраструктурой. Текущая работа — лаба 2 (lab.json): PostgreSQL как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или Valkey (выбран Valkey — кэш карточек чатов). Код перенесён из лабы 1, переход на lab2 идёт через changes OpenSpec (раздел «Переходное состояние»). Стек: 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 по образцу 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). Valkey — на «4», кэш карточки чата: источник истины — PostgreSQL, отказ Valkey — обход кэша, а не ошибка (infra.md). 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), вход и Bearer-сессии — change session-auth, кэш Valkey — change membership-cache, автоматические проверки отказов — change failure-checks, нагрузочный стенд на PostgreSQL с планами запроса — change bench-postgres, трек 2 часть 1 (индексы и запросы на чатах разного размера, стоимость записи) — change track2-query-plans. Этот файл и .claude/rules/ описывают целевое состояние лабы 2, поэтому в остальном код с ними пока расходится:

  • в track2-backup-restore — FLUSHALL Valkey после восстановления базы: иначе в кэше останутся карточки чатов, созданных после снятия backup (design change membership-cache, Risks);
  • в REPORT.md нет трека «5» №2, часть 2: backup с восстановлением (track2-backup-restore). Уровень 4 и часть 1 трека в отчёте заполнены целиком.

Правила лабы 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, кэш 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/**: нагрузочный стенд на 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.
  • 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 и миграции) и 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; config.toml и infra/valkey/valkey.conf монтируются 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 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, уборка при любом исходе (student-tests.md)
make student_test [BASE_URL=...] собственные тесты student-tests/ (pytest) против запущенного сервера, кроме проверок отказов (-m 'not fault'); сервер недоступен — код 2 и одна строка с адресом
make failure_checks [FAULT_ARGS=...] проверки отказов (pytest -m fault, ~45 с) на отдельном стенде: проект <рабочий>-failures со своими Postgres и Valkey, обычный и «тесный» API (срок 2 с, пул 1), hook student-tests/fault_hook.py; стенд и его volume удаляются при любом исходе, рабочий не трогается (student-tests.md)
make bench [BENCH_LABEL=...] полная матрица 10k / 100k / 500k читаемого чата плюс 100 000 сообщений в 1 110 фоновых чатах разного размера (~35 мин, оценка по bench_quick) на своём проекте compose mtusi-bench (API, Postgres, Valkey с лимитами, без портов хоста и без .env рабочего стенда); на каждый размер — свежий стенд, 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_ab BEFORE=... AFTER=... REAPPLY=<commit> «до» и «после» одного изменения подряд (два прогона bench): bench для BEFORE, commit доказательств, git revert commit отката REAPPLY, bench для 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          # сессия БД, фабрики сервисов (с кэшем), разбор Basic, текущая сессия по Bearer, пагинация
    errors.py                # доменное исключение → статус + code (+ WWW-Authenticate), формат ошибки контракта
    middlewares/             # X-Request-Id и access-лог; с лабы 3 — X-Instance-Id
  core/
    repos/<domain>.py        # атомарный доступ к хранилищу, модульные функции
    repos/chat_cache.py      # карточка чата в Valkey: ключ с именем базы, JSON ↔ ChatFullDTO
    services/<domain>.py     # <Domain>Service: логика, проверки доступа, id и время, логи; чаты и сообщения — с кэшем
    exceptions/<domain>.py   # доменные исключения, реэкспорт в __init__.py
  infra/
    logger.py                # structlog, get_logger(), contextvar-ы request_id / user_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)
    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-курсор: кодирование и разбор
student-tests/               # black-box тесты по HTTP (уровень 4): make student_test
  conftest.py                # BASE_URL, проверка доступности, фикстуры alice/bob/eve/chat и stand/tight_api, сбор маркеров spec, стоп без hook
  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
  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, уборка (stdlib)
  fault_hook.py              # hook стенда отказов: stop/start/pause/unpause, кэш, триггер сбоя участников (stdlib)
  failures.compose.yml       # override стенда отказов: без публикации портов
bench/                       # нагрузочный стенд на API + Postgres + Valkey: make bench / make bench_quick
  run.py                     # оркестратор: стенд compose, фоновые чаты и расписание наполнения, матрица, обслуживание БД, планы и варианты, пробы записи, backup и восстановление во второе хранилище со сверкой, метрики, runs.csv / summary.md / meta.json
  bench.compose.yml          # override стенда mtusi-bench: имена, лимиты BENCH_*, без портов и config.toml, auto_explain
  bench.env                  # подстановки compose стенда вместо .env рабочего стенда (без паролей)
  k6/                        # сценарии k6: prepare (вход по Basic, фоновые чаты), prefill (по расписанию), cursors, plan_cursors (страницы плана фоновых чатов), explain, read, tail, write, after_backup и restore_check (этап восстановления); lib.js — Bearer и хелперы
  compare.py                 # make bench_compare: дельта двух меток, уровень шума, эффект или шум
  ab.py                      # make bench_ab: прогоны «до» и «после» одного изменения подряд
migrations/, alembic.ini     # ревизии alembic, async env.py; применяет одноразовый сервис compose
infra/                       # конфигурации сервисов стенда; README.md — skeleton
  valkey/valkey.conf         # лимит памяти и LRU, persistence выключен
scripts/restart.sh           # restart hook для make test-persistence, по restart.example.sh: api, postgres, valkey
Dockerfile                   # builder (uv sync --locked) → runtime: .venv + src + миграции, UID 10001, healthcheck
docker-compose.yml           # postgres, valkey, migrate, api; адреса и порты из .env, volume postgres_data
.dockerignore
config_example.toml, .env.example
evidence/storage/            # отказы БД, пул, statement_timeout, рестарт, порты Postgres, свежий clone
evidence/migrations/         # миграции с нуля и повторно, ошибка миграции
evidence/auth/               # пароли и токены в БД, срок сессии, TTL из конфига
evidence/cache/              # попадания в кэш, отказ Valkey, FLUSHALL и рестарт
evidence/tests/              # выводы make test_isolated, make student_test и make failure_checks для REPORT.md
evidence/bench/<метка>/      # результаты make bench / bench_restore: паспорт, прогоны, наполнение, сводка (планы, стоимость записи, восстановление), планы explain-<размер>.txt, сырые итоги k6
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-сессия; 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/, Dockerfile, docker-compose.yml, infra/valkey/ (без infra/README.md skeleton), 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, включая использование ИИ.