Download README.md from pyrowoon/Tea_room: direct link, hf CLI and curl.
- Browser
- Download file 10.8 kB
-
https://huggingface.co/spaces/pyrowoon/Tea_room/resolve/main/README.md
- Command line
-
hf download hf://spaces/pyrowoon/Tea_room/README.md
-
curl -L -o README.md https://huggingface.co/spaces/pyrowoon/Tea_room/resolve/main/README.md
title: Tea Room
emoji: ☕️
colorFrom: gray
colorTo: indigo
sdk: docker
pinned: false
Рандомайзер мойщика чайника
Production-ready веб-приложение для честного выбора человека, который моет чайник после чаепития.
- Backend: FastAPI
- Frontend: чистый HTML/CSS/JS
- БД: SQLite (
/app/data/teapot.db) - Деплой: Hugging Face Spaces (тип FastAPI)
1. Локальный запуск
1.1. Установка зависимостей
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
1.2. Запуск сервера
uvicorn main:app --reload --host 0.0.0.0 --port 8000
Приложение будет доступно по адресу http://127.0.0.1:8000/.
- Главная:
http://127.0.0.1:8000/— выбор присутствующих и розыгрыш - Админка:
http://127.0.0.1:8000/admin— управление участниками и просмотр истории - API-документация (Swagger):
http://127.0.0.1:8000/docs
При первом запуске автоматически создаётся база данных по пути /app/data/teapot.db
(локально это будет подпуть внутри проекта, т.к. код сам создаёт нужную директорию).
2. Структура проекта
main.py— FastAPI-приложение, инициализация БД, Pydantic-модели, бизнес-логикаspin, API-роуты и раздача статики.requirements.txt— зависимости Python.README.md— данная инструкция.static/index.html— главная страница (выбор присутствующих и запуск розыгрыша).static/admin.html— админка (CRUD участников + просмотр истории).static/styles.css— общий адаптивный дизайн для обеих страниц.static/app.js— фронтенд-логика (работа с API черезfetch).
3. Бизнес-логика spin
Алгоритм реализован строго по описанию и выполняется в одной транзакции SQLite:
- Шаг 1 — подготовка (для каждого присутствующего):
- Если
first_tea_after_pass = true→tickets += 1,first_tea_after_pass = false. - Если
pass_point = true→ исключаем из текущего розыгрыша,pass_point = false,first_tea_after_pass = true.
- Если
- Шаг 2 — формирование пула:
- В пул попадают только присутствующие с
tickets > 0и безpass_point. - Если пул пуст → сохраняются изменения шага 1, создаётся запись в
history, возвращаетсяwinner = nullиreason.
- В пул попадают только присутствующие с
- Шаг 3 — взвешенный выбор:
- Случайный выбор победителя с весом
tickets.
- Случайный выбор победителя с весом
- Шаг 4 — обновление после выбора:
- Победитель:
tickets = 1,pass_point = true. - Остальные в пуле:
tickets += 1.
- Победитель:
- Шаг 5 — история:
- В таблицу
historyсохраняются:date(ISO 8601, UTC),present(JSON-массив присутствующих имён),winner(nullable),snapshot(JSON всех участников после розыгрыша).
- В таблицу
Если в процессе шага 1–5 происходит ошибка — транзакция откатывается.
4. Контракты API
GET /api/participants
Возвращает список участников:
[
{
"id": 1,
"name": "Иван",
"tickets": 2,
"pass_point": false,
"first_tea_after_pass": false
}
]
POST /api/participants
Body:
{ "name": "Иван" }
- Создаёт участника c
tickets = 1. 409 Conflictпри дубликате имени.- Валидация пустого имени (422 от Pydantic).
DELETE /api/participants/{id}
- Удаляет участника.
404 Not Found, если не найден.
POST /api/spin
Body:
{ "present": ["Иван", "Мурад"] }
Response:
{
"winner": "Иван",
"pool": ["Иван", "Мурад"],
"present": ["Иван", "Мурад"],
"reason": null
}
Если пул пуст или никого нет — winner = null, поле reason содержит текстовую причину.
GET /api/history
Возвращает список записей истории (новые сверху).
JSON-поля present и snapshot декодируются на бэкенде и приходят как нормальные структуры.
[
{
"id": 1,
"date": "2026-03-03T12:34:56.789000",
"present": ["Иван", "Мурад"],
"winner": "Иван",
"snapshot": [
{
"id": 1,
"name": "Иван",
"tickets": 1,
"pass_point": true,
"first_tea_after_pass": false
}
]
}
]
CORS: включён, разрешено всё (*).
5. Фронтенд и UX
/ (главная)
- Таблица участников с колонками:
- Имя
- Билеты
- Pass-point
- Первый чай после pass
- Переключатель «Присутствует» (checkbox)
- Кнопка «Выбрать присутствующих»:
- Считает отмеченные чекбоксы и показывает список выбранных в информационном баннере.
- Кнопка «Провести розыгрыш»:
- Отправляет
present(имена отмеченных участников) наPOST /api/spin. - Показывает:
- имя победителя и пул (
pool), либо - причину, если розыгрыш не состоялся (
reason).
- имя победителя и пул (
- Отправляет
Все вызовы идут через fetch без перезагрузки страницы.
/admin
- Форма добавления участника (по имени).
- Таблица участников с кнопкой «Удалить» для каждого.
- Таблица истории розыгрышей:
- ID, дата, присутствующие, победитель, компактный снимок состояния (имя, билеты, pass).
6. Деплой на Hugging Face Spaces
6.1. Создание Space
- Зайдите в свой аккаунт Hugging Face.
- Нажмите New Space.
- Заполните:
- Space name — любое имя (например,
teapot-randomizer). - License / Visibility — по желанию.
- Space SDK — выберите FastAPI.
- Space name — любое имя (например,
- Создайте Space.
6.2. Загрузка кода
В корень Space загрузите файлы:
main.pyrequirements.txtREADME.md(опционально)- директорию
static/целиком:static/index.htmlstatic/admin.htmlstatic/styles.cssstatic/app.js
Структура в репозитории Space должна быть такой же, как локально.
6.3. Настройки запуска
Для Spaces с SDK FastAPI Hugging Face сам поднимет сервер, используя:
app = FastAPI(...)
В main.py уже определена переменная app, поэтому ничего менять не нужно.
Переменная окружения PORT обрабатывается в блоке:
if __name__ == "__main__":
import uvicorn
port = int(os.environ.get("PORT", 8000))
uvicorn.run("main:app", host="0.0.0.0", port=port, reload=True)
На Hugging Face этот блок обычно не используется (сервер запускается самим Space),
но локально он позволяет запускать приложение одной командой:
python main.py
6.4. Работа БД на Hugging Face
- Путь к БД жёстко задан как
/app/data/teapot.db. - При старте:
- автоматически создаётся директория
/app/data(если её нет), - создаются таблицы
participantsиhistory(если их нет).
- автоматически создаётся директория
- Все данные хранятся в этом файле SQLite.
После успешного деплоя:
- Откройте Space — должна открыться главная страница
index.html. - Перейдите на
/adminдля добавления участников и проверки истории.
7. Проверка критериев готовности
- Алгоритм:
- Реализован согласно заданным шагам 1–5.
- Взвешенный случайный выбор по
tickets. - Все шаги выполняются в одной транзакции.
- История:
- Сохраняются дата,
present,winner(nullable),snapshot. - JSON-поля декодируются при
GET /api/history.
- Сохраняются дата,
- UI:
- Все действия доступны из браузера (без Postman):
- добавление/удаление участников,
- выбор присутствующих,
- запуск розыгрыша,
- просмотр истории.
- Все действия доступны из браузера (без Postman):
- Работа локально:
- Запуск через
uvicorn main:app --reloadилиpython main.py.
- Запуск через
- Работа на Hugging Face:
- Соответствует требованиям FastAPI Spaces.
- Порт берётся из
PORT. - Нет жёстких
localhost-путей, статика раздаётся черезStaticFiles.
- Логика:
- Обработаны сценарии пустого пула.
- Учитываются флаги
pass_pointиfirst_tea_after_pass.
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference