41 KiB
MTUSI Messenger
REST API мессенджера (пользователи, чаты, история сообщений). Этот код
переносится через все семь лабораторных курса и на каждой обрастает
инфраструктурой. Текущая работа — лаба 2 (lab.json): PostgreSQL
как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или
Valkey (выбран Valkey — кэш карточек чатов), на «5» — трек 2 (план
запроса и восстановление). Код перенесён из лабы 1 (commit 7b775a2,
её правила — git show 7b775a2:.claude/rules/<файл>). Переход на lab2
завершён changes OpenSpec, они в openspec/changes/archive/. Стек:
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).
Согласования с преподавателем
Договорённости, которых нет в 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.mdsrc/api/**,src/core/**,src/schemas/**,student-tests/**: что требует контракт и где FastAPI по умолчанию его нарушаетapi-layer.mdsrc/api/**,src/main.py: роутеры, зависимости, middlewares, обработчики ошибокservice-layer.mdsrc/core/services/**repo-layer.mdsrc/core/repos/**dto.mdsrc/schemas/**infra.mdsrc/infra/**: логгер, PostgreSQL (engine, пул, таймауты), readiness, кэш Valkey (повтор только на обрыв, срок на команду, обход при отказе) и другие клиентыauth.mdsrc/**/session.py, сервис пользователей,dependencies.py,errors.py, идентификация вstudent-tests/: пароль и KDF, разбор Basic, токен, срок и отзыв сессииlogging.mdсервисы, API, инфраструктура, src/main.py: где и как логировать, чего в логах быть не должноsettings.mdsrc/config/**,.env.example,config_example.toml: источники настроек, что куда кластьrun-modes.mdточки входа, Makefile, compose, шаблоны конфигов: console и docker, uvicorn, SIGTERMdocker.mdDockerfile,docker-compose.yml,.dockerignore,scripts/restart.sh,infra/**: мультистейдж, non-root, пины, healthcheck, стенд compose, volumes, restart hookstudent-tests.mdstudent-tests/**: обязательные проверки уровня 4, black-box по HTTP, особый стендbench.mdbench/**: нагрузочный стенд на Postgres (проект composemtusi-bench), что не меняется между метками замеров, граница чёрного ящика и планы запроса, сравнение меток, коммиты измеренных состоянийmigrations.mdmigrations/**,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, остальные пересобирают граф без спроса.
- Перед правкой — Read файла, как без графа: иначе правило слоя из
Окружение и команды
- Python 3.12 (
.python-version), зависимости через uv (uv sync,uv run ...), lock вuv.lock. ruff глобальный (/opt/homebrew/bin/ruff, им же пользуется PyCharm), в проекте он в extradev. - Конфиг:
.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.12uv берёт free-threaded 3.14t, и установка падает на сборкеtree-sitter-rust. - Сборка и обновление — одна команда
graphify update .в корне: без LLM и токенов, около секунды, работает и в чистом clone. Граф обновляется вручную, после заметной работы (новый слой, закрыт change). Попутноupdateкладёт копию прошлого графа вgraphify-out/<дата>/и называет кластеры по центральному узлу.
- CLI:
| Команда | Что делает |
|---|---|
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.mdskeleton),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, включая использование ИИ.