|
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
10.8 kB
| 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 | |