Tea_room / README.md
Мурад Гаджимагомедов
update readme
9409feb
|
Raw History Blame Contribute Delete
10.8 kB
metadata
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. Шаг 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. Шаг 2 — формирование пула:
    • В пул попадают только присутствующие с tickets > 0 и без pass_point.
    • Если пул пуст → сохраняются изменения шага 1, создаётся запись в history, возвращается winner = null и reason.
  3. Шаг 3 — взвешенный выбор:
    • Случайный выбор победителя с весом tickets.
  4. Шаг 4 — обновление после выбора:
    • Победитель: tickets = 1, pass_point = true.
    • Остальные в пуле: tickets += 1.
  5. Шаг 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

  1. Зайдите в свой аккаунт Hugging Face.
  2. Нажмите New Space.
  3. Заполните:
    • Space name — любое имя (например, teapot-randomizer).
    • License / Visibility — по желанию.
    • Space SDK — выберите FastAPI.
  4. Создайте Space.

6.2. Загрузка кода

В корень Space загрузите файлы:

  • main.py
  • requirements.txt
  • README.md (опционально)
  • директорию static/ целиком:
    • static/index.html
    • static/admin.html
    • static/styles.css
    • static/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):
      • добавление/удаление участников,
      • выбор присутствующих,
      • запуск розыгрыша,
      • просмотр истории.
  • Работа локально:
    • Запуск через 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