Skip to content

USER_GUIDE.md

Latest commit

 

History

History
233 lines (142 loc) · 14.5 KB

USER_GUIDE.md

File metadata and controls

233 lines (142 loc) · 14.5 KB

TJudge - руководство пользователя

TJudge - турнирная платформа для соревнований по теории игр. Участники загружают программы-стратегии, программы играют друг против друга в нескольких играх, а система считает рейтинг ELO и ведёт таблицы лидеров.

1. Введение

Доступ к сервису: главная страница - https://<ваш-домен> (локально: http://localhost:8080).

Кратко, как всё устроено:

  • Регистрируетесь и создаёте либо присоединяетесь к команде.
  • Команда участвует в турнире.
  • Для каждой игры в турнире загружаете программу-стратегию (один код - одна игра).
  • Система запускает матчи программ между командами, считает результат и обновляет рейтинг.
  • Текущее положение видно в таблице лидеров турнира и в кросс-игровом рейтинге.

2. Регистрация и вход

Регистрация

  1. Откройте /login и нажмите «Регистрация» (или сразу перейдите на /register).
  2. Заполните:
    • Имя пользователя - латиница, без пробелов, уникальное.
    • Email - используется для уведомлений.
    • Пароль - минимум 8 символов.
  3. Нажмите «Зарегистрироваться».

После регистрации вы сразу авторизованы.

Вход

На странице /login введите имя пользователя и пароль, нажмите auth.login(). Сессия JWT хранится в localStorage и продлевается, пока вы пользуетесь сайтом (до 24 часов по умолчанию, до 7 дней с refresh-токеном).

Выход

Через меню профиля (верхний правый угол). Токен попадает в blacklist немедленно.

Профиль

Страница /profile - смена имени, email, пароля.

3. Команды

Команды - единица участия в турнире. В турнире от команды играет один набор программ (одна программа на игру).

Создание команды

  1. Откройте турнир, нажмите «Создать команду».
  2. Введите название. Система выдаст invite-код и ссылку-приглашение.
  3. Отправьте ссылку товарищам. Они войдут в команду, перейдя по ней.

Максимальный размер команды задаётся админом турнира (обычно 1-5 человек).

Присоединиться по коду

На странице турнира: «Вступить в команду» -> ввести код.

Покинуть команду

Страница команды (/teams/:id) -> «Покинуть». Лидер команды покинуть не может - сначала передайте лидерство или распустите команду.

Роль лидера

Создатель команды становится лидером. Лидер может:

  • Исключать участников.
  • Переименовывать команду.
  • Удалять команду (если турнир ещё не начался).

4. Турниры

Список турниров

/tournaments показывает активные и завершённые турниры. У каждого турнира отображается название, статус (ожидание, идёт, завершён) и число участников.

Страница турнира

/tournaments/:id содержит:

  • Описание и правила.
  • Список игр, которые включены в турнир.
  • Кнопка «Присоединиться» (видна, если турнир принимает участников).
  • Таблица лидеров - общий кросс-игровой рейтинг.
  • Вкладка по каждой игре: отдельная таблица и список матчей.

Жизненный цикл турнира

  1. Админ создаёт турнир, указывает описание и добавляет игры.
  2. Команды регистрируются и загружают программы.
  3. Админ запускает турнир - команды больше не принимаются.
  4. Планировщик формирует пары round-robin, матчи уходят в очередь воркерам.
  5. По мере готовности результатов рейтинг обновляется в реальном времени (WebSocket).
  6. После прохождения всех запланированных раундов турнир помечается как завершённый.

5. Программы-стратегии

Общее

  • Один файл или архив.
  • Язык любой, главное - исполняемость внутри изолированного Docker-контейнера tjudge-cli.
  • Лимиты по умолчанию: 512 МБ памяти, 60 секунд на матч, сеть отключена.
  • Интерфейс ввода-вывода описан в правилах каждой игры (stdin/stdout текстом).

Загрузка

Со страницы своей команды в турнире (/tournaments/:id/my-team):

  1. Выберите игру.
  2. Загрузите файл или архив.
  3. Укажите язык (или «auto»), точку входа, если нужна.
  4. Нажмите «Загрузить».

Сервер выполняет первичные проверки (размер, формат, базовый статический анализ) и отправляет программу в очередь на компиляцию/подготовку.

Версии

Для каждой команды в каждой игре хранятся все загруженные версии. Актуальная - последняя успешно скомпилированная. Старые версии остаются в истории, их можно скачать.

Ошибки

Если компиляция или первый тестовый запуск падает, статус программы - error. Детали видны на странице программы (/programs/:id). Типичные причины:

  • Синтаксическая ошибка.
  • Программа не читает stdin или не печатает ответ в stdout.
  • Превышены лимиты по памяти или времени.
  • Попытка сетевого доступа (запрещена).

После исправления загрузите новую версию.

6. Лидерборд и ELO

ELO

У каждой программы свой рейтинг для каждой игры. Старт - 1500. После матча оба рейтинга корректируются по классической формуле ELO: победитель растёт, проигравший падает, ничья сдвигает слабо. K-фактор задан в конфиге игры.

Таблицы

  • Кросс-игровой лидерборд турнира: сумма или взвешенная сумма ELO по играм.
  • Лидерборд конкретной игры в турнире: только рейтинг этой игры.
  • Глобальный рейтинг (вне турниров): опционально, см. главную страницу.

Обновление в реальном времени

Страница турнира подписывается на WebSocket /api/v1/ws/tournaments/:id и сразу показывает новые результаты. Авторизация не требуется для чтения публичных лидербордов, но требуется для WebSocket-подключения.

7. Встроенные игры

7.1 Дилемма заключённого (dilemma)

Два игрока одновременно выбирают: сотрудничать (C) или предать (D). Повторяется N раундов.

Выплаты за раунд:

Я \ Оппонент C D
C 3, 3 0, 5
D 5, 0 1, 1

Программа читает историю раундов со stdin и отвечает C или D. Побеждает программа с большей суммой очков.

7.2 Перетягивание каната (tug_of_war)

Две команды выставляют силы на флаг. Чьё суммарное усилие больше - тот сдвинул канат. Общий ресурс усилий ограничен, распределяется по раундам стратегически.

7.3 Дилемма путешественника (travelers_dilemma)

Двое независимо объявляют цену от 2 до 100. Оба получают меньшую из двух объявленных цен. Тот, кто назвал меньшее число, получает бонус, кто большее - штраф. Равновесие по Нэшу - 2, но оптимальная игра сложнее.

7.4 Общественное благо (public_goods)

N игроков решают, сколько вложить в общее благо. Общая сумма умножается на множитель и делится поровну между всеми независимо от вклада. Классическая задача о безбилетниках.

7.5 Аукцион двойной цены (dollar_auction)

Аукцион, в котором второй по величине ставщик тоже платит свою ставку (но ничего не получает). Простой, если остановиться, но участники легко «попадают в ловушку».

Точные параметры (число раундов, множители, лимиты) задаёт админ при добавлении игры в турнир.

8. Админская панель

Доступ: роль admin (назначается через CLI make admin EMAIL=...). Интерфейс - /admin.

Основные возможности:

  • Управление турнирами: создание, добавление игр, запуск, завершение, удаление.
  • Ручной перезапуск пачки матчей (run-matches, run-game-matches, retry-matches).
  • Завершение/сброс раунда по игре внутри турнира.
  • Включение авто-раунда: система сама запускает следующий раунд, когда пулл матчей исчерпан.
  • Массовая загрузка программ команд по zip-архиву (скачивание в админ-интерфейсе).
  • Управление командами: дисквалификация, восстановление, удаление.
  • Управление играми: добавление, редактирование, удаление (кроме встроенных).
  • Просмотр audit-лога: /admin -> «Audit».
  • Очередь матчей: статистика, очистка, удаление невалидных записей.

Все админские действия пишутся в audit_log с привязкой к admin-пользователю.

9. API

Сервер документируется через Swagger: /swagger/ (требует admin-токен). Полный справочник - docs/API_GUIDE.md.

Ключевые группы:

  • /api/v1/auth/* - регистрация, вход, refresh, профиль.
  • /api/v1/tournaments/* - CRUD и управление турнирами.
  • /api/v1/teams/* - команды.
  • /api/v1/programs/* - загрузка и скачивание программ.
  • /api/v1/games/* - метаданные игр.
  • /api/v1/matches/* - матчи и очередь.
  • /api/v1/ws/tournaments/:id - real-time обновления лидерборда.

Авторизация: Authorization: Bearer <JWT>.

10. Частые вопросы

Почему моя программа попадает в статус error?

Смотрите детали на странице программы. Типичные причины перечислены в §5. Для воспроизведения локально можно запустить tjudge-cli в Docker с теми же лимитами.

Как часто обновляется рейтинг?

Сразу после обработки матча воркером. Если страница открыта, обновление приходит через WebSocket. Если WebSocket отключён, используйте ручной refresh.

Можно ли загрузить новую версию во время идущего турнира?

Да, пока раунд по этой игре не стартовал. Если раунд уже начат, новые версии попадут в следующий раунд.

Как скачать все программы команды?

Админ: на странице турнира -> programs/download-zip. Обычный участник - через свою страницу команды.

Куда писать, если нашёл баг?

GitHub issues репозитория. Приложите request-id из ответа сервера (заголовок X-Request-ID) - оператор найдёт контекст в логах.