Files
2026-10-30 12:32:42 +03:00

139 lines
18 KiB
YAML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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»."