evening_detective_server/docs/GAME_PACKAGE.md

# Пакет игры, версия 1 — ED-029, этап 4

Пакет — самостоятельный ZIP для одной игры до старта. Сборка получает готовый
снимок данных и файлы; чтение не обращается к сети, БД или хранилищу приложения.
Реализация: `internal/services/game_package_service`.

## Контракт

| Запись | Содержание |
| --- | --- |
| `manifest.json` | `version=1`, случайный `package_id` (32 hex-символа), `created_at` в UTC, `source_server`, исходный `game_id`, массив `files` |
| `game.json` | Объект `Data`: `game`, `scenario`, `teams`, `tickets`, `playlists`, необязательный `screen_plan`, `map` |
| `files/<sha256>.<extension>` | Медиа с именем по SHA-256 содержимого; одинаковые байты хранятся один раз |

Каждая запись `files` манифеста описывает путь, размер распакованных байтов,
MIME и SHA-256 в нижнем регистре. В перечень входит `game.json`, сам манифест
не входит. Все остальные ZIP-записи должны быть заявлены и использованы
ссылками из данных игры. Вложенные архивы и каталоги не используются.

Полный перечень JSON-полей задан типами в `model.go`; неизвестные поля и
неподдерживаемые версии при чтении отклоняются. Время записывается как RFC3339,
`token_hash` — как стандартный Base64 от исходных 32 байтов SHA-256.
Структура истории используется существующая — `storytelling.Story`;
поля шагов экранов совпадают с `game_screen_plans_repo.Step`.

### Переносимые данные

- Игра: исходные ID, название, описание, место, запланированное время, статус,
  формат `online`/`offline`, ссылки на сценарий и плейлист. Допускается только
  `draft`, без `started_at`, `ended_at` и игрового прогресса.
- Сценарий: описание, обложка, полная история с правильными ответами, статус,
  даты, исходный ID автора и назначенный плейлист.
- Все команды игры, включая неподтверждённые и отменённые: ID, неизменённый
  пароль QR, название, статус, email капитана, число участников, данные
  подтверждения участия, исходный ID создателя, ID доставки регистрации и дата
  создания. Эти данные нужны для сохранения связей и защиты от повторной регистрации.
- Активные и использованные билеты: ID, исходный хеш токена, статус, даты,
  исходный ID пользователя, использовавшего билет. `used_by` может отсутствовать,
  например после удаления пользователя; статус и `used_at` сохраняются.
- Оба назначенных плейлиста — игры и сценария, если они различаются; треки с
  исходными ID, именами и позициями. План экранов с выбранным шагом; карта команд
  и единственный стол организатора `organizer_desk/1`.

`game.playlist_id` — выбранный для переноса плейлист игры. При подготовке снимка
экспортёр должен учесть назначение в `game_music_states.playlist_id`: существующий
интерфейс выбора музыки сохраняет его именно там. При отсутствии такого назначения
используется `games.playlist_id`, затем default сценария. Текущая позиция,
состояние проигрывания и сессии экранов в пакет не включаются.

ID пользователей — ссылки на исходный сервер, а не существующих пользователей
площадки. Импортёр обязан обработать их отдельно; кодек не создаёт аккаунты.
ID игры, команд, сценария, билетов, плейлистов и треков также относятся к исходному
серверу. Кодек их не перенумеровывает. Импорт должен сохранить значения ID команд
и пароль, используемые в уже напечатанных ссылках `/team-story/<id>?password=...`,
а также хеши токенов билетов. Конфликты с локальными ID решаются на этапе 6.

Почтовые задания, токены подтверждения участия, аккаунты, пароли пользователей,
JWT/refresh-токены, действия, полученные улики, ответы команд и результаты не
входят в формат. Подключённые экраны и их позиции на карте при сборке исключаются;
на площадке экраны подключаются заново. Состояние проигрывания музыки не переносится.

### Медиа

Собираются все файловые ссылки: обложка, фон, аудио вступления, видео заключения,
изображения мест, файлы улик и треки плейлистов. Данные проверяются по сигнатуре
содержимого; поддерживаются PDF, JPEG, PNG, GIF, WebP, MP3, Ogg, WAV, MP4 и WebM.
Ссылки внутри копии `Data` заменяются на пути `files/...`; входные данные не меняются.

Относительное имя и полный URL с настроенным префиксом хранилища открываются
через переданный источник локальных файлов. Остальные HTTP/HTTPS-ссылки
скачиваются при сборке. Один URL скачивается один раз; одинаковое содержимое
разных URL хранится один раз. Файл по недоступной ссылке, пустой файл или ответ
без поддерживаемой сигнатуры завершают сборку ошибкой.

Внешний клиент не использует системный proxy. Адреса проверяются перед
соединением и после перенаправлений; соединение идёт к проверенному IP без
повторного DNS-разрешения. Частные, локальные и служебные сети запрещены.
HTTPS использует штатную проверку сертификатов. До пяти перенаправлений,
до 120 секунд на файл; отмена контекста прерывает операцию.

## Использование и временные файлы

```go
service := game_package_service.NewGamePackageService(fileDomain)

openLocal := func(ctx context.Context, name string) (io.ReadCloser, error) {
    file, err := fileStorage.Get(ctx, name)
    if err != nil {
        return nil, err
    }
    return io.NopCloser(bytes.NewReader(file.Data)), nil
}

err := service.Pack(ctx, snapshot, openLocal, destination)
// На ошибке destination нужно отбросить, включая ошибку записи результата.

bundle, err := service.Unpack(ctx, sourceReaderAt, archiveSize, tempParent)
if err != nil {
    return err
}
defer os.RemoveAll(bundle.Dir)
// bundle.Files: путь внутри ZIP → проверенный временный файл с расширением.
```

`Snapshot.SourceServer` содержит исходный адрес онлайн-сервера.
`Snapshot.HasProgress` заполняется экспортёром по наличию действий, полученных
улик и ответов. Кодек не читает БД, поэтому достоверность снимка и этого признака
обеспечивает экспортёр этапа 5. `Data` не имеет полей для игрового прогресса.

`Pack` сначала собирает ZIP в приватном временном каталоге, затем копирует его
в `destination`. Ошибка получения файлов не выдаёт частичный пакет. Ошибка
записи или отмена во время выдачи может оставить часть ZIP в destination;
вызывающий код обязан её удалить. Все внутренние файлы `Pack` удаляются при
завершении операции. Адаптер существующего `IFileStorage.Get` держит в памяти
один объект; потоковый источник может возвращать reader без этого буфера.

`Unpack` создаёт отдельный каталог внутри `tempParent` (или системного временного
каталога при пустой строке), с правами `0700`, файлы — `0600`. Файлы создаются со
случайными именами, независимо от путей ZIP. При любой ошибке собственный каталог
удаляется. После успеха очистка `bundle.Dir` обязательна для вызывающего кода.
Временные файлы и пакеты нельзя хранить в Git: они содержат ответы сценария,
пароли QR и email капитанов.

## Лимиты и проверки

| Ограничение | Предел |
| --- | --- |
| Размер ZIP | 1 ГиБ |
| Общий распакованный размер, включая JSON | 1 ГиБ |
| Один медиафайл | 64 МиБ |
| Каждый JSON и каталог ZIP | 8 МиБ |
| Количество ZIP-записей, включая JSON | 4096 |

Обработка медиа использует ограниченные буферы и временные файлы, не загружает
весь пакет в память. Перед `zip.NewReader` проверяется каталог, чтобы количество
записей нельзя было скрыть ложным заголовком. ZIP64 и многотомные ZIP не поддерживаются.
При чтении отклоняются опасные пути, симлинки, каталоги, дубли ZIP/манифеста,
незаявленные и неиспользуемые файлы, отсутствие файлов, несовпадение размеров,
MIME и SHA-256, некорректные связи данных и состояние начатой игры.

Ошибки проверяются через `errors.Is`: `ErrInvalidPackage`,
`ErrUnsupportedVersion`, `ErrLimitExceeded`, `ErrMediaUnavailable`,
`ErrUnsafeURL`; отмена сохраняет `context.Canceled`/`context.DeadlineExceeded`.
Кодек не содержит транспортных handlers; экспортёр переводит ошибки в безопасные
сообщения API.

SHA-256 защищает от повреждения, но не подтверждает автора пакета. Подпись и
шифрование не реализованы. Кодек не блокирует игру и не делает импорт. Импортёр этапа 6 использует его
проверенный результат; повторные импорты и сохранность QR описаны ниже.

Проверка: `go test ./internal/services/game_package_service -count=1` и полный
`go test ./...`. Тесты покрывают сохранение данных, автономное чтение, загрузку
медиа, дедупликацию, потоковую обработку, отмену, очистку, лимиты и повреждённые пакеты.

## Экспорт со статусом офлайн-режима: этап 5

Только для тестовых игр до реализации возврата результатов. Импорт реализован
на этапе 6; интерфейс передачи, отмена и возврат результатов остаются следующими этапами.

### API

Все три маршрута требуют `Authorization: Bearer <JWT>` и одну из ролей `admin`,
`developer`, `organizer`. `author` и `user` не имеют доступа. В `APP_MODE=venue`
экспорт запрещён, worker не запускается и закрытый bucket не инициализируется.

| Метод и маршрут | Результат |
| --- | --- |
| `POST /api/games/{ID}/export` | Запуск фоновой подготовки; повторный запрос в `preparing`/`ready` возвращает ту же попытку. Тело: `{}`. |
| `GET /api/games/{ID}/export` | Последняя попытка: состояние, ID, готовый пакет либо безопасная причина ошибки. |
| `GET /api/games/{ID}/export/download` | Потоковый ZIP готовой попытки; `Content-Length`, `Content-Disposition`, `Cache-Control: no-store`, `X-Content-Type-Options: nosniff`. |

Первые два маршрута возвращают `{"export":{"ID":"...","state":"preparing"}}`.
В `ready` добавляются `packageID` из фактического манифеста, `size` (int64 в
protobuf JSON представлен строкой), `sha256`. В `failed` — безопасный `failure`.
Снимок, инициатор, владелец worker и ключ RustFS наружу не передаются.
`Game.export` в обычных ответах игры содержит те же сведения для будущего UI.

Ошибки доступа: HTTP 401/403; отсутствие попытки — 404; начатая игра, прогресс,
режим `venue` и ещё не готовый ZIP — HTTP 400
(`FailedPrecondition`). Неизвестные ошибки дают безопасный HTTP 500.
Скачивание реализовано отдельным HTTP-handler с штатной JWT-проверкой; ZIP не
проходит через gRPC `HttpBody` или публичный `/api/files`.

### Снимок и статус офлайн-режима

Начало экспорта блокирует строку игры в короткой транзакции. Проверяются `draft`,
отсутствие `started_at`, `ended_at`, действий, улик и ответов команд. Запланированное
`start_at` переносится. Одним SQL-снимком сохраняются игра, общий сценарий, все
команды и билеты, карта, план экранов, выбранный плейлист игры и default сценария.
`game_music_states.playlist_id` имеет приоритет над `games.playlist_id`.

Частичный уникальный индекс допускает одну попытку `preparing`/`ready` на игру.
Экспорт не запрещает изменения игры и связанных данных: команды, регистрация,
билеты, прогресс, оценки, музыка, экраны и карта продолжают работать штатно.
Почтовые workers продолжают обработку. Функций и триггеров БД нет.

В списке игр и на странице управления `preparing` отображается как подготовка
офлайн-пакета, `ready` — как «Игра в офлайн-режиме». Это информационный статус,
а не подтверждение импорта пакета на площадке. Поля `status` и `format` игры
не меняются. При `failed` отметка офлайн-режима исчезает.

ZIP собирается из сохранённого снимка. Изменения после начала экспорта не
попадают в этот пакет, повторное скачивание отдаёт прежнюю версию. Общие сценарии
и плейлисты остаются редактируемыми; недоступное или удалённое медиа приводит
к ошибке сборки. Отдельный интерфейс запуска/скачивания остаётся этапом 7.

### Worker и хранение

Очередь и снимки находятся в PostgreSQL (`game_exports`), отдельного брокера нет.
Worker проверяет задания каждые 5 секунд. После захвата попытки аренда длится
2 минуты, heartbeat обновляет её каждые 30 секунд. Общая подготовка, включая
ожидание в очереди, ограничена 30 минутами с момента запуска. Потеря владения
отменяет подготовку; `ready` публикуется только после полной загрузки ZIP и
повторной проверки ID попытки, владельца, аренды и срока подготовки в БД.

ZIP собирается во временном каталоге `0700` с файлами `0600` и потоково
загружается в отдельный закрытый bucket `<S3_BUCKET>-game-exports` в текущем
RustFS с текущими учётными данными. Новые переменные окружения и изменения
production-конфигурации не нужны. Временные файлы удаляются после работы;
maintenance очищает оставшиеся каталоги терминальных попыток и неполные объекты
после перезапуска. Данные для очистки сохраняются даже после удаления игры,
независимо от её текущего наличия.

Ошибка сборки или истёкшая аренда переводит попытку в `failed`. Повторный POST создаёт новую попытку и новый снимок. Worker старой
попытки не может опубликовать результат или изменить новую попытку. Неоднозначный
ответ БД после публикации не приводит к удалению готового ZIP: удаление допустимо
только после подтверждённого `failed`. Очистка повторяется до окончания возможной
работы старого worker.

Готовый пакет хранится до реализации возврата результатов. Повторное скачивание
отдаёт те же байты; закрытие соединения не меняет `ready`.

### Проверка

`TEST_DATABASE_URL` включает PostgreSQL-проверки в изолированных схемах через
реальные миграции и публичные методы репозиториев/сервисов. `go test ./...`
проверяет снимок, конкурентный запуск, возможность изменений после экспорта, истечение
аренды/timeout, запрет устаревшей публикации, ошибку/повторный запуск, очистку,
права и режим `venue`.

Для отдельного тестового RustFS дополнительно задаются `TEST_S3_ENDPOINT`,
`TEST_S3_USER`, `TEST_S3_PASSWORD` и запускается
`go test ./internal/services/game_export_service -run TestExportRustFS -count=1 -v`.
Тест создаёт отдельный bucket, проверяет кодек, SHA-256, анонимный отказ, потоковую
выдачу/обрыв и повторное создание клиента, затем удаляет свои объекты и bucket.
Необязательный `TEST_S3_RESTART_MARKER` позволяет внешнему тестовому harness
перезапустить изолированный RustFS: после появления marker нужно дождаться health
и создать `<marker>.continue` в течение трёх минут. Это не production-проверка.


## Локальный импорт: этап 6

### API

`POST /api/games/import` принимает ZIP непосредственно в теле запроса с
`Content-Type: application/zip` и `Authorization: Bearer <JWT>`. Multipart и
Base64 не используются. Разрешены роли `admin`, `developer`, `organizer`;
операция доступна только в `APP_MODE=venue`.

Ответ HTTP 200: `{"gameID":100,"packageID":"…","repeated":false}`.
Повтор того же пакета возвращает `repeated:true` и прежние идентификаторы,
не перезаписывая локальные изменения. Повтор после удаления игры также
возвращает прежний результат и не восстанавливает удалённую игру.

Ошибки: 401/403 — авторизация/роль; 400 — неподходящий режим, повреждённый
пакет, версия или данные; 409 — конфликт ID, изменённые байты под прежним ID
пакета, другой пакет той же игры или ещё выполняющийся импорт; 413 — лимит
размера; 499/504 — отмена/timeout; 500 — безопасная внутренняя ошибка.
Ответы имеют `Cache-Control: no-store`.

Маршрут описан в protobuf как `ImportGame(HttpBody) → GameImportRsp`, но
HTTP-поток обслуживает отдельный handler перед grpc-gateway: ZIP размером до
1 ГиБ не проходит через gRPC-буфер. Прямой gRPC-вызов использует тот же сервис,
однако ограничен существующим лимитом сообщений. В обоих конфигурациях прокси
venue только `/api/games/import` получает лимит 1 ГиБ, отключённую буферизацию
request body и timeout 30 минут; другие маршруты сохраняют прежние лимиты.

### Перенос и конфликты

Импорт сохраняет ID игры, команд и билетов, пароли QR, хеши билетов, их
статусы/даты, подтверждения участия, email капитанов и ID доставки регистрации.
Занятый локальный ID игры/команды/билета или хеш билета приводят к отказу,
не затрагивая существующие записи. Конфликты проверяются до загрузки медиа и
повторно в транзакции публикации.

Сценарий, оба плейлиста и треки создаются отдельными копиями с новыми локальными
ID. Все назначения перепривязываются; сценарий принадлежит импортирующему
пользователю. `creator_id` команд и `used_by` билетов остаются NULL: совпадение
числового ID не связывает аккаунты двух серверов. Исходные связи и соответствия
ID сохраняются в закрытых метаданных `game_imports` для будущего возврата.

Формат и статус игры сохраняются. План экранов и карта переносятся без подключённых
устройств; воспроизведение музыки начинает со штатного состояния покоя.
Медиа загружаются в локальный RustFS потоково под отдельными именами попытки,
с заменой всех ссылок. Одинаковое медиа сценария используется повторно; треки
с одинаковыми байтами получают разные имена, если этого требует существующее
ограничение уникальности `playlist_tracks.filename`.

### Атомарность и восстановление

ZIP и распаковка находятся в приватном временном каталоге с правами 0700/0600.
Вся обработка ограничена 30 минутами. До загрузки файлов в БД фиксируются
ID попытки, исходный сервер, ID пакета, SHA-256 всего ZIP, оригинальный снимок,
манифест и ключи будущих объектов. Частичные уникальные индексы разрешают одну
активную попытку на ID пакета и исходный ID игры, включая завершённые импорты.

После загрузки всех файлов одна транзакция создаёт сценарий, плейлисты,
треки, игру, команды, билеты, план, карту и состояние `ready` со связями ID.
На время публикации вставки/изменения games/teams/tickets блокируются для
повторной проверки конфликтов и безопасного продвижения последовательностей.
Последовательности могут оставить пропуски после rollback; исходные ID
повторно не выдаются. При ошибке ни одна часть новой игры не видна.

Heartbeat каждые 30 секунд продлевает аренду на 2 минуты; истёкшая попытка
не может публиковать данные. Recovery проверяет БД каждые 5 секунд, переводит
прерванные попытки в `failed` и повторяет очистку их объектов, в том числе после
перезапуска и позднего завершения старой загрузки. Неоднозначный результат
commit не разрешает удаление: очистка допустима только для подтверждённого
`failed`. Ключи успешного импорта никогда не используются для этой очистки.
Временные каталоги прерванных запросов удаляются после 32 минут и проверки
отсутствия активной попытки. Ошибка допускает новую попытку с отдельными ключами.

### Проверка

`TEST_DATABASE_URL` включает проверки с реальными миграциями в отдельных схемах:

```sh
go test ./internal/repos/game_imports_repo ./internal/services/game_import_service ./internal/app -count=1
go test -race ./internal/repos/game_imports_repo ./internal/services/game_import_service -count=1
```

Проверяются сохранность данных/QR/билетов, локальные ID копий и исходные связи,
последовательности, повтор с локальными изменениями, изменённый ZIP под прежним
ID, конфликты до/после загрузки, конкурентный импорт, rollback всех записей,
ошибки загрузки/очистки, отмена, аренда/timeout и неопределённый ответ commit.
HTTP-тесты проверяют роли, ошибки, MIME, лимиты и отсутствие внутренних деталей.

Для изолированного RustFS дополнительно задать `TEST_S3_ENDPOINT`, `TEST_S3_USER`,
`TEST_S3_PASSWORD` и запустить `go test ./internal/services/game_import_service
-run TestImportRustFSHTTPAndRestart -count=1 -v`. Smoke проверяет настоящий HTTP
handler, файлы в отдельном bucket и повтор импорта. Необязательный
`TEST_S3_RESTART_MARKER` позволяет внешнему harness перезапустить только тестовый
RustFS и создать `<marker>.continue` в течение минуты. Bucket, файлы и тестовая
схема удаляются после проверки. Проверка без WAN проводится в отдельной Docker-сети
с `internal: true`; рабочая площадка и production для этого не изменяются.

Интерфейс передачи остаётся этапом 7; полный билетный и игровой прогон — этапом 8.
До готовности возврата результатов используются только тестовые игры.