Это README шаблона, из которого создаётся репозиторий вашей команды. Контракт openapi.yaml и открытые тесты — в самом репозитории.
Домашнее задание: Сервис бронирования жилья
🎯 Цель задания
Вам предстоит в командах спроектировать схему БД в PostgreSQL и реализовать REST API-сервис, имитирующий упрощенный Airbnb.
API должен строго соответствовать контракту, описанному в файле openapi.yaml.
Решение проверяется автоматически: сначала тесты на корректность, затем нагрузка на поиск. Чем быстрее работает поиск, тем выше балл.
👥 Команды и репозиторий
Всё делается на сайте https://hw2.catshop.tech:
- Войдите с логином и паролем от catshop из первого домашнего задания. Если их у вас нет, получите в боте @itmo_db_bot.
- Укажите свой логин на GitHub.
- Вступите в команду из списка или создайте новую. В команде 3–4 человека, больше 4 нельзя.
- Сразу после создания команды в организации
ITMO-TASKSпоявится приватный репозиторийdb-hw2-airbnb-<команда>— копия этого шаблона. Каждому участнику придёт приглашение в этот репозиторий на GitHub: его нужно принять (ссылка есть на странице команды). Кто выйдет из команды, потеряет доступ к её репозиторию.
Кто не вступит в команду до дедлайна формирования команд, будет распределён случайно.
🧩 Что нужно сделать
1. Спроектировать схему БД в PostgreSQL
Обязательные сущности:
- User (гость/хозяин, уникальный email)
- Property (объекты размещения)
- Booking (бронирования)
- Review (отзывы)
- Payment (платежи)
Рекомендации — отдельно они не оцениваются (баллы ставятся за корректность и скорость), но хорошая схема помогает и тому и другому:
- Первичные и внешние ключи
- UNIQUE, CHECK
- Индексы для фильтрации и производительности
- Нормализация (минимум 3НФ), допускается обоснованная денормализация
Версия PostgreSQL: 16
Docker-образ: postgres:16-alpine
2. Реализовать REST API по контракту
Ваш веб-сервис:
- может быть на любом языке и фреймворке;
- должен строго соответствовать
openapi.yaml: пути, поля, коды ответов. Общие правила (коды ошибок, семантика дат) описаны в начале файла, вinfo.description; - слушает порт 8080.
Особенно важен эндпоинт:
GET /properties/search
По нему меряется производительность решения. Зарегистрируйте его в своём фреймворке раньше GET /properties/{id}, иначе многие фреймворки (FastAPI, Express и др.) отправят search в обработчик {id} как id.
3. Собрать сервис в Docker-образ
В корне репозитория должен быть ваш Dockerfile. Образ содержит только ваш сервис, без базы данных.
При проверке рядом с вашим сервисом запускается пустой postgres:16-alpine, а сервис получает такие переменные окружения:
| Переменная | Значение |
|---|---|
DB_HOST |
db |
DB_PORT |
5432 |
POSTGRES_USER |
app |
POSTGRES_PASSWORD |
app |
POSTGRES_DB |
app_db |
DATABASE_URL |
postgres://app:app@db:5432/app_db |
Важно:
- База при старте пустая. Таблицы, индексы и всё остальное ваше приложение создаёт само при запуске (миграции).
- Ваш
docker-compose.ymlпроверка не использует, толькоDockerfile. Всё, что нужно сервису, должно быть в образе или в переменных выше. - Сервис должен начать отвечать на запросы не позже чем через 90 секунд после старта.
- Наполнение базы при проверке (2000 пользователей, 1500 объектов, 15 000 бронирований через ваш API) должно уложиться в 10 минут.
DATABASE_URLдан в форматеpostgres://. Некоторым драйверам (SQLAlchemy, JDBC) нужен другой формат — соберите строку подключения изDB_HOST,DB_PORTи остальных переменных.
docker-compose.yml в шаблоне нужен для локального запуска: он поднимает базу и ваш сервис так же, как это делает проверка.
🧪 Тесты
Тесты бывают двух видов:
- Открытые — в папке
tests/: сквозной сценарий и простой поиск. Это минимальная проверка, что сервис вообще работает. - Закрытые — их запускает только проверяющая система. Они проверяют правила из
openapi.yaml: коды ошибок, пересечения бронирований, переходы статусов, фильтры, сортировку и пагинацию поиска. Все эти правила явно описаны в контракте — читайте его внимательно, а не только открытые тесты.
Если закрытый тест упал, на странице команды будет видно описание каждого упавшего теста: какое правило нарушено.
Запуск открытых тестов локально:
docker compose up -d --build
pip install -r tests/requirements.txt
pytest -q tests
Если сервис доступен не на http://localhost:8080, укажите адрес в переменной API_BASE_URL.
Свои тесты добавлять можно и полезно. Но проверка всегда запускает собственную копию открытых тестов, поэтому менять их бессмысленно.
🚀 CI и Docker-образ
При каждом push в ветку main GitHub Actions:
- поднимает сервис через
docker composeи прогоняет тесты; - если все открытые тесты прошли — публикует этот же образ в GitHub Container Registry:
ghcr.io/itmo-tasks/db-hw2-airbnb-<команда>:<коммит>.
Пока в репозитории нет Dockerfile, CI ничего не делает. Коммиты, где менялись только .md-файлы, CI не запускают. Если тесты упали, в логе запуска видно и вывод pytest, и логи вашего сервиса.
📊 Проверка и балл
На странице команды на https://hw2.catshop.tech видно последний коммит в main, для которого CI опубликовал образ (коммиты только с .md образа не собирают — для них берётся предыдущий коммит с образом). Кнопка «Отправить на проверку» отправляет именно его. Ссылку на образ вводить не нужно.
Проверки идут по очереди, по одной: одна проверка занимает несколько минут, поэтому ближе к дедлайну очередь растёт — не откладывайте сдачу на последний вечер. У команды в очереди может быть только одна заявка. Пока её проверка не началась, заявку можно отозвать или заменить более свежим коммитом — место в очереди сохраняется. Заявка, поставленная до дедлайна, засчитывается, даже если проверка закончится после него. Один и тот же коммит повторно отправить нельзя — для новой проверки нужен новый коммит (если проверка сорвалась по вине проверяющей системы, её повторят автоматически).
Как проходит проверка:
- Образ вашего коммита запускается рядом с пустым
postgres:16-alpine. Сервис и база вместе получают 2 ядра процессора, памяти — по 1,5 GB каждому. - Прогоняются все тесты, открытые и закрытые. Каждый пройденный тест приносит свою долю баллов за корректность.
- Если прошли все тесты, база наполняется через ваш API: 2000 пользователей, 1500 объектов, 15 000 бронирований (половина подтверждается). На это даётся 10 минут. Если хотя бы один тест упал или ваш сервис принял меньше 99 % данных, нагрузка не меряется.
- После прогрева трижды запускается нагрузка: 20 виртуальных пользователей в течение 30 секунд шлют
GET /properties/searchс разными фильтрами, датами, сортировками и страницами. Данные и последовательность запросов одинаковые для всех команд. Каждый ответ сверяется с правильным: состав и порядок страницы иmeta.total. p95— 95-й перцентиль времени ответа под нагрузкой. В зачёт идёт медиана трёх замеров.
Формула балла
score = 50 × (пройдено тестов / всего тестов) + 50 × 200 / (p95 + 200)
p95 — в миллисекундах.
- Первая часть — за корректность: все тесты, открытые и закрытые, весят одинаково.
- Вторая — за скорость: при
p95= 0 мс это 50 баллов, при 200 мс — 25, при 600 мс — 12,5. - Скорость меряется, только если прошли все тесты; иначе за неё 0. Быстрый, но неправильный сервис баллов за скорость не получает.
- Если под нагрузкой больше 2 % запросов завершаются ошибкой или больше 5 % ответов неправильные (не совпадают с ожидаемыми), за скорость тоже 0.
В зачёт идёт лучший результат команды до дедлайна. Лидерборд — на https://hw2.catshop.tech.
⏱ Сетка дедлайнов
| Дата | Событие | Комментарий |
|---|---|---|
| будет объявлена | Формирование команд | Не успевшие будут распределены случайно |
| будет объявлена | Сдача проекта | До дедлайна команда преподавателей постарается давать советы по архитектуре схемы базы данных для улучшения скора |
📁 Что должно быть в репозитории
README.md— ваша документация: краткое описание архитектуры и схемы данныхopenapi.yaml— контракт API (не изменять)Dockerfiledocker-compose.yml- Исходный код приложения
- SQL-миграции / скрипты создания базы
- ER-диаграмма (Entity-Relationship-диаграмма — опционально, но желательно)
🙌 Удачи!
Работа оценивается автоматически, но качественная архитектура, корректная схема данных и любовь к проекту поставят вас на 1 место в лидерборде.