--- 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. Установка зависимостей ```bash python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt ``` #### 1.2. Запуск сервера ```bash 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` Возвращает список участников: ```json [ { "id": 1, "name": "Иван", "tickets": 2, "pass_point": false, "first_tea_after_pass": false } ] ``` #### POST `/api/participants` Body: ```json { "name": "Иван" } ``` - Создаёт участника c `tickets = 1`. - `409 Conflict` при дубликате имени. - Валидация пустого имени (422 от Pydantic). #### DELETE `/api/participants/{id}` - Удаляет участника. - `404 Not Found`, если не найден. #### POST `/api/spin` Body: ```json { "present": ["Иван", "Мурад"] } ``` Response: ```json { "winner": "Иван", "pool": ["Иван", "Мурад"], "present": ["Иван", "Мурад"], "reason": null } ``` Если пул пуст или никого нет — `winner = null`, поле `reason` содержит текстовую причину. #### GET `/api/history` Возвращает список записей истории (новые сверху). JSON-поля `present` и `snapshot` декодируются на бэкенде и приходят как нормальные структуры. ```json [ { "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 сам поднимет сервер, используя: ```python app = FastAPI(...) ``` В `main.py` уже определена переменная `app`, поэтому ничего менять не нужно. Переменная окружения `PORT` обрабатывается в блоке: ```python 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), но локально он позволяет запускать приложение одной командой: ```bash 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