Платформа для проведения игр: городские квесты и музыкальные вечеринки «Угадай мелодию». Игры бывают одиночные и командные, с регистрацией и без.
В квестах пользователи создают команды, капитан подаёт заявку, после одобрения команда проходит задания вместе (ответы может отправлять любой участник). Организатор создаёт и модерирует свои игры, администратор - все игры и роли пользователей. После завершения организатор публикует результаты, и участникам открывается итоговая таблица со статистикой.
У игры есть вид (kind) и формат (format):
-
Квест (
quest, онлайн) - всё описанное выше. -
Угадай мелодию (
guess_song, оффлайн) - вечеринка в одном помещении: ведущий собирает игру в редакторе (/admin/music) - ищет песни или грузит файлы, раскладывает по блокам, выбирает отрезок и при желании оставляет себе подсказку («кавер, оригинал - такой-то», «фильм „Шрек"»). Играют по пульту (/admin/music/host/:id): экран-проектор показывает QR, эквалайзер и ответы, телефоны работают баззерами. Кто первым нажал - отвечает.Играть можно соло или столами, с регистрацией или без: в режиме «команда без регистрации» гость просто выбирает свой стол из списка или заводит новый. Realtime на Socket.IO. В каталоге квестов
/gamesне показывается. Подробнее - в docs/ARCHITECTURE.md и docs/API.md.
- Участник (
user) - редактирует профиль, состоит в команде, играет. - Капитан (
team_captain) - создаёт команду, управляет составом, подаёт заявки от команды; роль выдаётся автоматически при создании команды. - Организатор (
organizer) - создаёт игры, модерирует только свои: заявки, задания, логи, публикация результатов. У игры может быть несколько организаторов: создатель добавляет соорганизаторов на вкладке «Организаторы», и они правят игру наравне с ним. Организаторы видны в информации о квесте. - Администратор (
admin) - модерирует все игры, назначает роли (вкладка «Пользователи» в админке).
- Backend: Node.js, Express, TypeScript, MongoDB, Mongoose, JWT, bcryptjs, Swagger.
- Frontend: React 18, TypeScript, Vite, TailwindCSS, Zustand, React Router, Axios.
- DevOps: Docker Compose.
- Создайте локальный
.envиз примера:
cp .env.example .envНа Windows PowerShell:
Copy-Item .env.example .env- Запустите проект:
docker compose up -d --build- Откройте:
- Frontend: http://localhost:5173
- Backend: http://localhost:5000
- Swagger: http://localhost:5000/api-docs
- Зарегистрируйте пользователя на http://localhost:5173/signup.
- Назначьте ему роль
adminв MongoDB:
docker exec quest-mongodb mongosh -u "$MONGO_INITDB_ROOT_USERNAME" -p "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin questВ mongosh:
db.users.updateOne(
{ username: "your-email@example.com" },
{ $set: { roles: ["user", "admin"] } }
)После изменения роли выйдите и войдите заново, чтобы обновился JWT.
- Организатор (или админ) открывает
/admin, создаёт квест с датой начала и окончания и добавляет задания через шестерёнку. - Пользователь создаёт команду на
/teamsи добавляет участников по никнейму. - Капитан открывает
/games, выбирает предстоящий квест и подаёт заявку от команды до времени старта. - Организатор одобряет заявку на
/admin. - Когда квест активен, любой участник команды открывает
/my-applsи входит в игру; ответы может отправлять каждый, при верном ответе вся команда переходит дальше. - Во время игры организатор видит технический прогресс и логи команд; участникам результаты других команд не видны.
- После окончания квеста организатор публикует результаты, и участникам на
/games/:gameId/resultsоткрывается итоговая таблица: маршрут команд по заданиям, кто отвечал, время на задание, итоговое время и место.
- Даты вводятся в локальном часовом поясе браузера и сохраняются в MongoDB как UTC.
- Подать заявку можно только до
dateofstart. - Войти в игру можно только при approved-заявке и в интервале
[dateofstart, dateofend). - После
dateofendполучение задания и отправка ответа блокируются для незавершённых прохождений. - Завершённый прогресс остаётся доступен после
dateofend, чтобы показать результат.
| Путь | Доступ | Назначение |
|---|---|---|
/ |
все | Главная |
/login |
гости | Вход |
/signup |
гости | Регистрация |
/games |
все | Каталог: мои активные, предстоящие, завершённые |
/games/:id |
все | Детали квеста и подача заявки |
/my-appls |
auth | Заявки моих команд и вход в игру |
/profile |
auth | Редактирование своего профиля |
/teams |
auth | Мои команды и создание команды |
/teams/:teamId |
auth | Состав команды, управление (капитан), выход |
/game/:gameId/play/:gameApplId |
auth | Прохождение квеста командой |
/games/:gameId/results |
auth | Результаты и статистика игры (после публикации; модераторам - всегда), логи для модераторов |
/admin |
admin, organizer | Квесты (организатор - только свои), заявки, результаты, организаторы; назначение ролей - только admin |
/admin/game/:gameId/tasks |
admin, organizer | Задания квеста |
/admin/music |
admin, organizer | Редактор игр «Угадай мелодию» |
/admin/music/host/:gameId |
admin, organizer | Пульт ведущего: ход игры, счёт, участники |
/m/screen/:gameId |
все | Экран-проектор: QR, эквалайзер, ответы |
/m/play?code= |
все | Телефон-баззер игрока |
/join |
все | Вход в игру по коду |
- GETTING_STARTED.md - пошаговый запуск и ручная проверка.
- docs/API.md - REST API.
- docs/ARCHITECTURE.md - структура и модели.
- docs/DEPLOYMENT.md - Docker, env, backup.
- docs/ROADMAP.md - этапы развития (модульность, облако+станция, права по видам игр).
- tests/README.md - сквозные тесты: что покрывают и как запускать.
- backend/README.md - backend.
- frontend/README.md - frontend.
docker compose ps
docker compose logs -f backend
docker compose logs -f frontend
docker compose down
docker compose up -d --buildBackend пишет структурированный журнал подключений, действий ведущего, баззеров, переходов песен и ошибок аудио проектора. Последние события видны в Docker:
docker compose logs -f backendПолный журнал сохраняется между пересозданиями контейнера в дневных файлах
logs/guess-song-YYYY-MM-DD.jsonl. По умолчанию файлы старше 30 дней
удаляются; срок меняется через MUSIC_LOG_RETENTION_DAYS в .env.
Сквозные проверки идут против запущенного стека - поднимите его и запускайте из корня:
NODE_PATH=frontend/node_modules node tests/music-flow-test.cjsЧто покрывает каждый файл - в tests/README.md.
Не коммитьте .env, .env.local, node_modules, dist, build, coverage и логи. Коммитьте только .env.example.