Tea_room / README.md
Мурад Гаджимагомедов
update readme
9409feb
|
Raw History Blame Contribute Delete
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