game-marathon/docs/game-types.md

Система типов игр

Обзор

В системе существует два типа игр, определяющих логику выдачи заданий:

Тип	Значение	Описание
Челленджи	challenges	При спине выдаётся один случайный челлендж из списка
Прохождение	playthrough	Нужно пройти игру целиком, челленджи становятся бонусными

---

Модели данных

Game

game_type: str              # "challenges" | "playthrough"
playthrough_points: int?    # Очки за прохождение (только для playthrough)
playthrough_description: str?   # Описание задания
playthrough_proof_type: str?    # Тип пруфа: screenshot/video/steam
playthrough_proof_hint: str?    # Подсказка для пруфа

Assignment

challenge_id: int?      # ID челленджа (для challenges)
game_id: int?           # ID игры (для playthrough)
is_playthrough: bool    # True если это прохождение

BonusAssignment

main_assignment_id: int     # Ссылка на основное задание (playthrough)
challenge_id: int           # ID бонусного челленджа
status: str                 # "pending" | "completed"
proof_path: str?            # Путь к файлу пруфа
proof_url: str?             # URL пруфа
proof_comment: str?         # Комментарий со ссылкой
points_earned: int          # Заработанные очки

---

Логика спина

Тип "Челленджи" (challenges)

1. Выбрать случайную игру из доступных
2. Отфильтровать уже выполненные челленджи этой игры
3. Выбрать случайный невыполненный челлендж
4. Создать Assignment с challenge_id

Игра исключается из спина, если все её челленджи выполнены.

Тип "Прохождение" (playthrough)

1. Выбрать случайную игру из доступных
2. Создать Assignment с game_id и is_playthrough=True
3. Создать BonusAssignment для каждого челленджа игры
4. События (Jackpot, Golden Hour и т.д.) ИГНОРИРУЮТСЯ

Игра исключается из спина, если есть Assignment со статусом COMPLETED или DROPPED.

---

Завершение заданий

Челлендж (challenges)

POST /marathons/{id}/complete-assignment

1. Загрузить пруф (файл или комментарий)
2. Начисляются очки челленджа × модификатор события
3. Увеличивается серия участника
4. Статус → COMPLETED

Прохождение (playthrough)

POST /marathons/{id}/complete-assignment

1. Загрузить пруф прохождения
2. Начисляются очки за прохождение (playthrough_points)
3. Бонусные очки добавляются из completed BonusAssignments
4. Увеличивается серия участника
5. Все pending BonusAssignments удаляются (больше нельзя выполнить)
6. Статус → COMPLETED

Бонусный челлендж

POST /marathons/{id}/assignments/{assignment_id}/bonus/{challenge_id}/complete

1. Доступно только пока основное задание ACTIVE
2. Загрузить пруф бонусного челленджа
3. BonusAssignment.status → COMPLETED
4. Очки накапливаются в BonusAssignment.points_earned
5. Очки НЕ добавляются сразу — добавятся при завершении основного задания

Исключение: Если main assignment уже COMPLETED (перепрохождение после диспута), очки добавляются сразу.

---

Фильтрация игр для спина

Функция get_available_games_for_participant

for game in approved_games:
    if game.game_type == "playthrough":
        # Исключить если есть COMPLETED или DROPPED assignment
        if has_finished_playthrough(participant, game):
            continue
    else:  # challenges
        # Исключить если ВСЕ челленджи выполнены
        if all_challenges_completed(participant, game):
            continue

    available.append(game)

---

Система очков

Челлендж

base_points = challenge.points
modifier = event_modifier (если есть активное событие)
total = base_points × modifier

Прохождение

base_points = game.playthrough_points
bonus_points = sum(bonus.points_earned for bonus in completed_bonuses)
total = base_points + bonus_points

События НЕ влияют на очки за прохождение.

---

Дроп задания

Челлендж

• Штраф в очках (зависит от настроек марафона)
• Серия обнуляется
• Игра остаётся доступной (можно получить другой челлендж)

Прохождение

• Штраф в очках
• Серия обнуляется
• Игра исключается из спина навсегда
• Все BonusAssignments удаляются

---

Диспуты

Оспаривание прохождения

Если диспут признан недействительным:

1. Assignment → RETURNED
2. Вычитаются все очки (прохождение + бонусы)
3. Серия обнуляется
4. Все BonusAssignments сбрасываются в PENDING

Оспаривание бонуса

Если диспут признан недействительным:

1. BonusAssignment → PENDING
2. Вычитаются очки бонуса
3. Proof данные очищаются
4. Можно попробовать выполнить заново

---

API эндпоинты

Метод	Путь	Описание
POST	/marathons/{id}/spin	Крутить колесо
POST	/marathons/{id}/complete-assignment	Завершить основное задание
POST	/marathons/{id}/assignments/{id}/bonus/{challenge_id}/complete	Завершить бонус
GET	/marathons/{id}/available-games	Список доступных игр
GET	/marathons/{id}/available-games-count	Количество доступных игр

---

Схема работы

┌─────────────────────────────────────────────────────────────────┐
│                           СПИН                                  │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
    ┌─────────────────┐             ┌─────────────────┐
    │   PLAYTHROUGH   │             │   CHALLENGES    │
    └─────────────────┘             └─────────────────┘
              │                               │
              ▼                               ▼
    ┌─────────────────┐             ┌─────────────────┐
    │  Assignment     │             │  Assignment     │
    │  game_id = X    │             │  challenge_id   │
    │  is_playthrough │             │  = X            │
    └─────────────────┘             └─────────────────┘
              │                               │
              ▼                               │
    ┌─────────────────┐                       │
    │ BonusAssignment │                       │
    │ × N (по числу   │                       │
    │   челленджей)   │                       │
    └─────────────────┘                       │
              │                               │
              ├───────────────────────────────┤
              ▼                               ▼
    ┌─────────────────────────────────────────────────┐
    │                   COMPLETE                       │
    │  • Загрузка пруфа                               │
    │  • Начисление очков                             │
    │  • Увеличение серии                             │
    └─────────────────────────────────────────────────┘