forked from mtusi2026/mtusi2026lab2
139 lines
18 KiB
YAML
139 lines
18 KiB
YAML
schema: spec-driven
|
||
|
||
context: |
|
||
# Лабораторная 2 «PostgreSQL, сессии и Redis/Valkey» — контекст проекта
|
||
|
||
## Что это
|
||
Skeleton лабораторной 2 курса «Мессенджер под нагрузкой» (МТУСИ, 7 независимых лаб) и решение
|
||
в ветке `solution/bpi2303-kostylev`, построенное переносом решения лабы 1. Skeleton содержит
|
||
задание (`README.md`), нормативный контракт (`contracts/`, версия 1.2.0) и публичные black-box
|
||
проверки (`tests/`). Целевая оценка — «5»: весь уровень 4 плюс трек 2 «План запроса и восстановление».
|
||
|
||
## Границы (менять нельзя)
|
||
In scope лабы 2: состояние в PostgreSQL (пользователи, чаты, участники, сообщения, сессии),
|
||
версионируемые миграции, регистрация с паролем (Argon2id), вход `Basic` только на
|
||
`POST /api/v1/auth/sessions`, непрозрачный `Bearer` с абсолютным TTL и отзывом
|
||
`DELETE /api/v1/auth/sessions/current`, `X-User-Id` игнорируется. Данные и действующие сессии
|
||
переживают рестарт API и хранилищ с сохранёнными volumes. На «4» — Valkey с конкретной ролью.
|
||
Обязательный минимум lab1 (`/health/*`, users, chats, messages, keyset-пагинация) сохраняется
|
||
с объявленным переходом на новую аутентификацию.
|
||
|
||
Out of scope (не проектировать, не закладывать «на будущее»): несколько API-реплик за
|
||
балансировщиком, `X-Instance-Id` и `Idempotency-Key` (лаба 3); вложения и S3 (лаба 4); worker,
|
||
брокер и обработка изображений (лаба 5); OTel и Grafana (лаба 6); TLS, mTLS и OpenBao (лаба 7);
|
||
Web UI, WebSocket, редактирование и удаление сообщений, изменение состава участников, публичный
|
||
поиск пользователей, Kubernetes, Swarm, репликация и HA PostgreSQL.
|
||
|
||
## Стек
|
||
Python 3.14 (аннотации вычисляются лениво по PEP 649, `TYPE_CHECKING` и
|
||
`from __future__ import annotations` не используются), FastAPI, gunicorn с несколькими
|
||
`UvicornWorker` (пакет `uvicorn-worker`), dishka (DI), pydantic v2 + pydantic-settings, structlog,
|
||
asyncpg (параметризованный SQL без ORM), redis-py (`redis.asyncio`) для Valkey, argon2-cffi,
|
||
pytest + pytest-asyncio + httpx. Зависимости — uv и `uv.lock`; ruff и ty обязательны на `src/`
|
||
и `student-tests/`; `scripts/*.py` держат синтаксис Python 3.9.
|
||
|
||
Инфраструктура — Docker Compose: `postgres` (17.x-alpine по digest, именованный volume),
|
||
`valkey` (8.x-alpine по digest, AOF на volume), одноразовый `migrate` на образе приложения,
|
||
`api` (non-root, healthcheck по готовности, `SIGTERM` ≤10 с). Секреты — compose secrets из
|
||
gitignored `secrets/`, приложение читает их через `*_FILE`.
|
||
|
||
## Архитектура
|
||
Монолит с двумя доменными зонами по книге Персиваля и Грегори
|
||
(`openspec/notes/architecture-patterns-python.md`):
|
||
|
||
main.py сборка приложения: собирает вклады зон в один процесс
|
||
migrate.py одноразовая точка входа: применяет SQL-миграции под advisory lock
|
||
identity/ пользователи, пароли и сессии: ошибки, события, команды, значения, порты,
|
||
адаптеры PostgreSQL/Valkey/Argon2 и весь свой HTTP-слой, включая аутентификацию
|
||
messaging/ чаты и история: ошибки, события, команды, агрегат Chat, курсор, адаптеры
|
||
PostgreSQL и весь свой HTTP-слой
|
||
shared/ только платформа: domain / application / infrastructure (часы, id, журнал,
|
||
пул PostgreSQL, UoW-база) и entrypoints/ (конвейер, health, ошибки, настройки)
|
||
|
||
Стрелки указывают внутрь: `domain/` не импортирует инфраструктуру, `application/` зависит только
|
||
от портов, адаптеры подключаются в `ioc.py` зоны. Ядро `shared/` не импортирует веб-фреймворк.
|
||
Зоны не импортируют друг друга; общая точка — схема БД: внешние ключи между таблицами зон
|
||
допустимы как ограничение целостности, но SQL одной зоны не читает таблицы другой.
|
||
PostgreSQL — источник истины для всего, включая сессии; Valkey — только кэш, его потеря не
|
||
теряет данные и не открывает доступ.
|
||
|
||
## Источники норм
|
||
- `contracts/README.md` — нормативная семантика API; приоритетнее интуиции и поведения библиотек.
|
||
- `contracts/openapi.json` — OpenAPI 3.1.0, обязательный минимум.
|
||
- `contracts/infrastructure.json`, `infra/README.md` — роли инфраструктуры и что о них отчитать.
|
||
- `README.md` — рубрика уровней «3» / «4» / «5».
|
||
- `COURSE.md` — карта курса и объявленные переходы API между лабами.
|
||
- `openspec/notes/architecture-patterns-python.md` — словарь паттернов и их компромиссов.
|
||
|
||
При расхождении артефакта с `contracts/` источником считается `contracts/`.
|
||
Подгонка контракта или публичных тестов под реализацию решением не является.
|
||
|
||
rules:
|
||
proposal:
|
||
- "Пиши на русском; идентификаторы, поля, коды ошибок и имена файлов — в оригинальном виде."
|
||
- "Держи в пределах 400 слов: Why / What changes / Impact без воды."
|
||
- "Указывай, какой уровень рубрики закрывает изменение: «3», «4» или заявленный трек «5»."
|
||
- "Обязательна секция «Non-goals» со ссылкой на Out of scope; не тащи в лабу 2 возможности лаб 3–7."
|
||
- "Связывай изменение с конкретным пунктом рубрики `README.md` и строкой таблицы доказательств `REPORT.md`."
|
||
- "Если изменение трогает `contracts/`, `tests/`, `README.md` или `COURSE.md` — это запрещено, оформляй как вопрос преподавателю."
|
||
specs:
|
||
- "Имя capability начинается с префикса лабы, в которой требование введено: `lab<N>-<имя>`, например `lab1-messenger-history`. Номер берётся из `lab.json`."
|
||
- "Префикс означает происхождение, а не срок действия: требование с `lab1-` продолжает действовать в лабах 2–7, пока его явно не изменит новая дельта."
|
||
- "Требование существующей capability правится дельтой к ней же, под её исходным префиксом; новый префикс заводится только для по-настоящему нового поведения."
|
||
- "Дельта-спека описывает только наблюдаемое поведение, не реализацию."
|
||
- "Требования о границах доменных зон формулируй как наблюдаемые: через поведение API или через проверяемый граф зависимостей модулей."
|
||
- "Формулируй требования как `### Requirement:` плюс `#### Scenario:` в форме WHEN/THEN на русском."
|
||
- "Для API-требований фиксируй метод, путь, коды ответов, заголовки и форму тела ошибки."
|
||
- "Каждое требование трассируется на пункт `contracts/README.md` или на критерий рубрики `README.md`."
|
||
- "Сценарии обязаны покрывать негативные пути: malformed JSON, лишние поля, чужой чат (404, не 403), пустой текст, дубль username, cursor от другого чата, limit вне 1–100, неверный пароль, истёкший и отозванный токен, Basic на бизнес-endpoint, недоступная зависимость."
|
||
- "Не вводи в контракт поля и коды, которых нет в `contracts/openapi.json`."
|
||
design:
|
||
- "Создавай, если изменение затрагивает границы доменных зон, слои, агрегаты, конкурентность, формат курсора, поведение при сигналах или конфигурацию контейнера."
|
||
- "Для каждого введённого паттерна отвечай по формуле книги: что за это получаем и чего это стоит."
|
||
- "Явно называй порт, его адаптеры и точку сборки; проверяй правило зависимостей: домен не импортирует инфраструктуру."
|
||
- "Указывай, к какой доменной зоне относится изменение; если оно задевает обе — объясняй, каким событием или внешним ключом схемы они связаны, и называй цену этой связи."
|
||
- "Всё, что кладётся в `shared/`, обосновывай отдельно: туда попадает только платформа и механизм связи, но не доменные понятия."
|
||
- "Ошибки, события и команды принадлежат зоне; в `shared/` живут лишь их базовые типы, без кодов контракта."
|
||
- "Фиксируй границы согласованности и способ защиты состояния от гонок; объясняй выбранную семантику времени и сортировки."
|
||
- "Секреты, токены и реальные данные в артефакт не попадают — только плейсхолдеры и имена переменных окружения."
|
||
- "Отмечай, что требуется от контейнера: пользователь, закрепление версий, healthcheck, обработка SIGTERM, переменные окружения."
|
||
- "Для каждого хранилища называй источник истины, границы транзакций, политику expiry и инвалидации, поведение при недоступности (503 или обход кэша) и что переживает рестарт."
|
||
- "SQL описывай вместе с индексом, который его обслуживает, и ожидаемым планом; схему, ограничения и индексы фиксируй до запросов."
|
||
tasks:
|
||
- "Задачи — атомарные шаги не длиннее 2 часов, в порядке исполнения."
|
||
- "Группируй по слоям и артефактам: схема и миграции, доменные зоны, приложение, инфраструктура, точка входа, стенд, тесты, измерения, отчёт."
|
||
- "Одна задача не пересекает границу доменной зоны; связь зон (событие или внешний ключ схемы) оформляется отдельной задачей."
|
||
- "Первой в цепочке идёт задача уровня «3», задачи уровня «4» и трека «5» — после неё."
|
||
- "Каждая группа завершается задачей проверки: какой командой убедиться, что критерий рубрики выполнен."
|
||
- "Не создавай задач, меняющих `contracts/`, `tests/`, `README.md`, `COURSE.md` или рубрику."
|
||
|
||
operations:
|
||
apply:
|
||
guidance:
|
||
- "Соблюдай правило зависимостей: адаптер добавляется за существующим портом, а не импортом инфраструктуры в домен."
|
||
- "Новый код кладётся в свою доменную зону вместе со своими ошибками, событиями, командами и HTTP-фасадом."
|
||
- "`shared/` пополняется только платформой и механизмом связи; доменное понятие туда не попадает никогда."
|
||
- "Коды контракта и HTTP-статусы объявляет зона в своём `entrypoints/errors.py`; платформа только применяет реестр."
|
||
- "Роутер, провайдер DI, журнал, отображение ошибок и настройки зоны лежат в её `entrypoints/` и `config.py`."
|
||
- "Ядро `shared/` (domain, application, infrastructure) не импортирует веб-фреймворк: транспорт живёт только в `shared/entrypoints/` и в `entrypoints/` зон."
|
||
- "Отдельного каталога точек входа на верхнем уровне не заводи: общее кладётся в `shared/`, доменное — в зону, сборка — в `main.py`."
|
||
- "Зоны не импортируют модули друг друга, включая объявления событий, — это проверяется тестом; в БД связь зон — только внешний ключ, SQL зоны читает лишь свои таблицы."
|
||
- "Пиши под Python 3.14 с ленивыми аннотациями: без `TYPE_CHECKING` и без `from __future__ import annotations`."
|
||
- "Логирование — только через порт `Logger`; второй логгер в приложении не заводится, сообщения сервера и библиотек идут через тот же поток."
|
||
- "Код приложения — в `src/`, собственные тесты — в `student-tests/`, обезличенные доказательства — в `evidence/`."
|
||
- "Перед коммитом прогоняй `make lint`, `make student-test` и `make check`."
|
||
- "SQL только параметризованный (`$1`, `$2`); значения из запроса никогда не склеиваются в текст запроса."
|
||
- "Ошибка зависимости (PostgreSQL, Valkey) превращается в `503 unavailable` за ограниченное время; отказ кэша обходится и никогда не превращается в анонимный доступ."
|
||
- "Схема меняется только новым файлом миграции; применённую миграцию не редактируют."
|
||
- "Публичный `make test` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh` запускаются против поднятого стенда (`make up`); сами тесты стенд не стартуют."
|
||
- "Каждый заявленный критерий рубрики подтверждай командой и наблюдаемым результатом в `REPORT.md`; PASS без команды доказательством не считается."
|
||
- "Отмечай выполнение в `tasks.md`; резюме держи кратким."
|
||
archive:
|
||
guidance:
|
||
- "Имя архивной папки начинается с даты архивации в формате `ГГГГ-ММ-ДД`, а не с даты создания change."
|
||
- "В `.openspec.yaml` архивной папки проставь `archived: <дата архивации>` и `lab: <номер из lab.json>` — по ним видно, когда и в какой лабе изменение закрыто."
|
||
- "Перед архивацией сверься с рубрикой `README.md`: какой уровень закрывает изменение и каким файлом доказательства."
|
||
- "Убедись, что `make check`, `make lint`, `make student-test`, `make test` и `make test-persistence ACTION_SCRIPT=scripts/restart.sh` против стенда проходят."
|
||
- "Сохранившиеся дальше требования должны попасть в `openspec/specs/`, иначе исчезнут вместе с архивом."
|
||
- "Зафиксируй, что именно демонстрируется в сценарии защиты и какие измерения приложены к треку «5»."
|