Kahoot Interactive Test

Интерактивная викторина на FastAPI и WebSocket: экран ведущего, экран игроков, мониторинг комнат и защищённый React/TypeScript-редактор тестов.

Быстрый запуск на macOS

1. Один раз откройте setup.command — он создаст виртуальное окружение и установит зависимости.
2. Откройте start.command.
3. Терминал покажет ссылки ведущего, игрока и редактора.
4. Для временной ссылки через интернет оставьте сервер открытым и запустите share.command во втором окне Терминала.

То же самое из Терминала:

./setup.command
./start.command
# в отдельном окне, если нужен интернет-доступ
./share.command

Обычный ручной запуск:

source venv/bin/activate
python -m uvicorn main:app --host 0.0.0.0 --port 8000

Второй администратор / редактор вопросов

Редактор доступен по адресу /editor.html#КЛЮЧ. Полная защищённая ссылка владельца печатается при запуске start.command. Для помощников создавайте персональные ссылки через кнопку «Команда».

Редактор умеет:

• просматривать все тесты, вопросы и правильные ответы;
• создавать, переименовывать и удалять тесты;
• добавлять, менять, дублировать, перемещать и удалять вопросы;
• работать с выбором ответа, текстом, числами, Wordle, опросами и кроссвордами;
• сохранять изменения без перезапуска сервера;
• выдавать отдельные роли владельца, редактора и наблюдателя;
• отзывать персональный доступ без смены главного ключа;
• показывать владельцу журнал изменений.

Изменения записываются в data/quizzes.json. Перед каждой записью создаётся data/quizzes.backup.json. Уже запущенная игровая комната использует собственную копию вопросов, поэтому правки редактора применяются со следующей созданной комнаты.

Ключ создаётся автоматически в data/editor_token.txt. Можно задать собственный ключ через QUIZ_EDITOR_TOKEN в файле .env (скопируйте .env.example в .env). Не отправляйте ссылку редактора игрокам.

Главный ключ всегда имеет роль владельца. В меню «Команда» владелец создаёт отдельную одноразово показываемую ссылку для каждого помощника. В базе data/access.sqlite3 хранится только SHA-256-хэш ключа, поэтому исходную ссылку нельзя восстановить из файла.

Архитектура 2.0

• main.py — совместимый игровой движок и WebSocket-протокол;
• quiz_app/ — модульные production-сервисы безопасности и доступа;
• frontend/ — Quiz Studio на React 19, TypeScript 7 и Vite 8;
• static/studio/ — оптимизированная production-сборка редактора;
• data/quizzes.json — совместимое хранилище вопросов с атомарной записью;
• data/access.sqlite3 — транзакционное хранилище ролей и журнала действий.

Проверка перед публикацией:

venv/bin/python -m pytest -q
cd frontend && npm run build

Для мониторинга хостинга доступны /health/live и /health/ready.

Контейнер и постоянный хостинг

Локальная production-проверка через Docker:

docker compose up --build

Готовые Dockerfile и railway.json подходят для Railway. На хостинге подключите постоянный volume к /app/data и задайте секрет QUIZ_EDITOR_TOKEN. Приложение намеренно запускается одним worker: активные игровые комнаты используют WebSocket-состояние процесса; это сохраняет корректный порядок игровых событий. Горизонтальное масштабирование следует включать только после подключения общего Redis room-state/pub-sub слоя.

Как дать доступ по ссылке

В одной Wi‑Fi сети используйте сетевой адрес, который показывает start.command. Для доступа через интернет запустите share.command: он поднимет установленный ngrok и напечатает готовые публичные ссылки. Они работают, пока открыты оба окна Терминала. Для постоянной ссылки приложение нужно разместить на сервере.

Страницы

• /host.html — ведущий;
• /player.html — игрок;
• /admin.html#КЛЮЧ — защищённое управление активной комнатой;
• /editor.html#КЛЮЧ — управление тестами и вопросами;
• /api/quizzes — публичный список тестов без правильных ответов.