simplevote

Imported from xtrueman/simplevote (AGENTS.md). Install upstream with npx skills add xtrueman/simplevote. Copyright stays with the author.

SimpleVote - Система голосования за выступающих

Описание проекта

SimpleVote - это веб-приложение для голосования за выступающих на мероприятиях. Система предназначена для оценки выступлений участниками мероприятия с использованием мобильных устройств.

Технологический стек

• Frontend (текущая версия): HTML, CSS, JavaScript (vanilla)
• Backend: Python FastAPI + Uvicorn
• API Documentation: Swagger UI (/docs) и ReDoc (/redoc)
• Хранилище: In-memory (глобальные переменные)

Основная механика

Выступающие

• Каждый выступающий имеет порядковый номер
• Номер выступающего отображается крупно вверху страницы
• При переходе к следующему выступающему номер увеличивается на единицу
• Переход осуществляется кнопкой "Далее"

Система оценки

• Оценка осуществляется по 5-звёздочной шкале (от 1 до 5 звёзд)
• Визуальный выбор количества звёзд кликом
• При выборе оценки выбранные звёзды "вспыхивают" с эффектом гало (анимация 0.6 секунды)
• После анимации отображается выбранное количество звёзд золотым цветом

Множественное голосование

• Счётчик голосующих: "Голосующий №X"
• Начальное значение: "Голосующий №1"
• Кнопка "Голосовать ещё" позволяет передать устройство другому человеку
• При нажатии "Голосовать ещё":
  • Номер голосующего увеличивается (+1)
  • Звёзды сбрасываются
  • Кнопки блокируются до нового голосования
• При переходе к следующему выступающему (кнопка "Далее"):
  • Счётчик голосующих сбрасывается на "Голосующий №1"

Управление состоянием кнопок

Кнопка "Голосовать ещё"

• Расположена слева внизу
• Заблокирована до первого голосования
• Разблокируется после выбора оценки
• Блокируется после собственного нажатия (до нового голосования)
• Стиль заблокированной кнопки: светло-серый цвет, сниженная прозрачность, курсор "not-allowed"

Кнопка "Далее"

• Расположена справа внизу
• Заблокирована до первого голосования
• Разблокируется после выбора оценки
• Блокируется после перехода к следующему выступающему
• Блокируется после нажатия "Голосовать ещё"
• Стиль заблокированной кнопки: серый цвет, сниженная прозрачность, курсор "not-allowed"

Дизайн и UX

• Мобильная оптимизация: интерфейс адаптирован для мобильных устройств
• Градиентный фон: фиолетово-синий градиент (от #667eea до #764ba2)
• Крупные элементы: удобное взаимодействие на сенсорных экранах
• Анимации:
  • Вспышка звёзд при выборе оценки (увеличение, яркость, эффект гало)
  • Hover-эффекты на кнопках (поднятие, изменение цвета, тень)
  • Плавные переходы для всех интерактивных элементов

Принципы работы

1. Честность: система рассчитана на честность участников (отсутствие жёсткой защиты от повторного голосования)
2. Простота: минималистичный интерфейс без лишних элементов
3. Доступность: возможность голосовать с одного устройства нескольким людям

Текущее состояние

Реализовано

• ✅ Одностраничный HTML-прототип
• ✅ Визуальная система оценки звёздами
• ✅ Эффект вспышки при выборе оценки
• ✅ Счётчик выступающих
• ✅ Счётчик голосующих
• ✅ Логика блокировки/разблокировки кнопок
• ✅ Мобильная адаптация
• ✅ FastAPI backend с 4 endpoints
• ✅ SPA с polling каждые 500ms
• ✅ Админ-панель для управления
• ✅ Swagger/ReDoc документация API
• ✅ Автоматическое отображение результатов

Не реализовано

• ❌ Персистентное хранилище (база данных)
• ❌ Аутентификация администратора
• ❌ Экспорт результатов

Структура файлов

simplevote/
├── app.py              # FastAPI backend
├── index.html          # Пользовательский интерфейс (SPA)
├── admin.html          # Админ-панель
├── test_api.py         # Тестовый скрипт API
├── requirements.txt    # Python зависимости
├── AGENTS.md           # Документация проекта
├── description.md      # Описание
└── README.md           # Инструкции

Планы развития

1. Подключение базы данных (SQLite/PostgreSQL)
2. Аутентификация администратора
3. Возможность создания нескольких мероприятий
4. Настройка количества выступающих
5. Экспорт результатов (CSV/Excel)

Глобальные переменные хранилища (Python)

• voting_status - текущий статус голосования
• current_person_num - номер текущего участника
• current_description - описание текущего участника
• persons - словарь с данными о персонах и их голосах

API Endpoints

Все endpoints доступны через Swagger UI: http://localhost:8000/docs

GET /status

• Описание: Получить текущий статус голосования
• Tag: Голосование

POST /vote

• Описание: Отправить голос за участника
• Параметры: personnum (>0), rating (1-5)
• Tag: Голосование

POST /setcurrentperson

• Описание: Установить текущего участника (админ)
• Параметры: description (имя или "VOTING_FINISHED")
• Tag: Администрирование

GET /getresults

• Описание: Получить результаты голосования
• Tag: Результаты

Переменные состояния (JavaScript)

• currentState - текущее состояние SPA (WAITING, VOTING, NEXT_PARTICIPANT, RESULTS)
• currentPersonNum - номер текущего участника
• currentDescription - описание текущего участника
• selectedRating - выбранная оценка (0-5)
• voterCount - номер текущего голосующего
• pollingTimer - таймер для polling