exchanger/docs/REFERENCE_ANALYSIS.md

Анализ визуальных референсов Exchanger

Дата анализа: 2026-08-20.

Статус материалов

Каталог references/ содержит локальные концептуальные материалы и добавлен в .gitignore. Эти файлы используются для понимания продукта и не предназначены для приложения или production-сборки. Сам .gitignore не управляет экспортом Godot, поэтому будущий export preset должен явно исключить references/. Перед использованием конкретных логотипов, персонажей, шрифтов и иллюстраций необходимо подтвердить права и получить исходники подходящего качества.

Проанализированы:

• семь макетов интерфейса размером 720×1280;
• один рендер корпуса размером 904×1280;
• видео интерфейса H.264 размером 1080×1920, 50 FPS, длительностью 32,16 секунды, без звуковой дорожки.

Физический аппарат

Референс показывает высокий напольный разменник с портретным экраном:

• корпус с сильно скруглёнными углами и зелёной рамой;
• установка на четырёх колёсах;
• вертикальный экран на передней панели с подсвеченной рамкой;
• справа от экрана сверху вниз расположены купюроприёмник, платёжный терминал/NFC, монетоприёмник и дополнительный сервисный элемент;
• ниже экрана расположен подсвеченный лоток выдачи жетонов с подписью «Жетоны здесь!»;
• на лицевой панели размещено название «Размен»;
• оформление корпуса продолжает космическую тему интерфейса: звёзды, НЛО, зелёный инопланетянин, луч, корова и монеты;
• боковая панель содержит вертикальную надпись «Размен жетонов».

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

Визуальный язык интерфейса

• Целевая ориентация — портретная 9:16.
• Основной референсный viewport — 1080×1920; макеты также представлены в 720×1280.
• Стиль — яркий пиксель-арт с космическим фоном.
• Основные цвета: тёмно-синий фон, салатовый/зелёный акцент, белые панели и тёмно-синий текст.
• Панели имеют белое тело, зелёную строку-заголовок и скруглённые углы.
• Основные кнопки — крупные зелёные плашки с синим текстом.
• В верхней части присутствуют цена жетона, персонажи и короткие реплики.
• В нижней части постоянно видны бренд/логотип и телефон технической поддержки.
• Инопланетянин и НЛО выполняют роль маскота, подсказки и отображения результата.
• Фоновая композиция статична. Движение создают отдельные спрайты НЛО, луча и персонажей, которые не перекрывают функциональные панели.

Текущая космическая тема проекта является техническим прототипом. На Этапе 2 её следует адаптировать к портретной пиксельной композиции, не копируя неподтверждённые референсные ассеты напрямую. Фоновая картинка должна оставаться статичной; шейдеры, частицы и фоновое видео для неё не нужны. Промо-ролик — отдельный UI-компонент домашнего экрана.

Домашний экран

На домашнем экране одновременно отображаются:

• цена одного жетона; в референсе — 10 рублей;
• бинарное состояние запаса: «много жетонов» или «мало жетонов», без числового остатка;
• выбор способа оплаты: наличные или безналичные;
• крупное действие «Выдать»;
• промо-блок;
• логотип и телефон технической поддержки;
• тематические персонажи и короткая реплика клиента/маскота.

Референс не использует отдельный пустой стартовый экран с кнопкой «Начать». Домашний экран сразу показывает состояние автомата и доступные способы оплаты. Существующий StartScreen следует преобразовать в HomeScreen или заменить им при внедрении навигации.

Ветка оплаты наличными

Экран «Оплата наличными» содержит:

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

Контроллер должен передавать приложению события о принятой сумме и, вероятно, текущее состояние приёмников. Правила сдачи, минимальной суммы и отмены необходимо согласовать отдельно.

Ветка оплаты картой

Референс показывает несколько последовательных состояний:

1. Выбор одной из предустановленных сумм: 10, 50, 100, 150, 200, 300, 400 или 500 рублей.
2. Кнопку «Другая сумма».
3. Цифровую клавиатуру для ввода произвольной суммы, отмену, очистку/ноль и подтверждение.
4. Экран ожидания с инструкцией приложить карту к платёжному терминалу.
5. Экран результата оплаты.

В видео показан отрицательный результат «Оплата не прошла» с грустным маскотом. Успешный результат и подтверждённая выдача в референсах не показаны, поэтому их визуальная композиция должна быть спроектирована отдельно в том же стиле.

Бонусы и расчёт жетонов

На макетах присутствует пример «100 жетонов + 50 жетонов в подарок». Это требует отдельной конфигурируемой модели:

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

Датчик хоппера не сообщает точный остаток, поэтому приложение не может проверять выбранный пакет против количества жетонов внутри. Состояние Low предупреждает о малом уровне, но не блокирует оплату; отсутствие подтверждённого сигнала (Unknown) блокирует её до диагностики.

Числа из референса считаются примерами до подтверждения владельцем продукта.

Промо-блок

Домашний экран содержит отдельную область для промо-ролика. Планируемый компонент должен:

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

Наблюдаемая последовательность видео

Приблизительная временная последовательность 32-секундного ролика:

• 0–13 секунд — домашний экран, анимация НЛО/луча и промо-области;
• 14–18 секунд — экран оплаты наличными;
• 19–20 секунд — возврат на домашний экран;
• около 21 секунды — короткий фоновой переход с НЛО;
• около 22 секунд — выбор суммы оплаты картой;
• около 23 секунд — ввод произвольной суммы;
• 24–27 секунд — ожидание прикладывания карты;
• 28–32 секунды — ошибка оплаты с анимированным маскотом.

Переходы преимущественно быстрые и не должны задерживать пользователя. Фоновая анимация сохраняет визуальную непрерывность между экранами.

Требуемые данные конфигурации

На основании референсов в конфигурацию необходимо добавить:

• ориентацию и целевой viewport;
• название/бренд автомата;
• телефон техподдержки;
• цену жетона;
• предустановленные суммы оплаты картой;
• минимальную, максимальную и кратную сумму;
• бонусные правила;
• начальное бинарное состояние Enough/Low для mock-режима;
• включённые способы оплаты;
• тексты подсказок;
• плейлист промо-роликов и fallback-постер;
• параметры показа логотипа и брендовых элементов.

Требуемые события контроллера

Протокол оборудования должен позволять получить или инициировать:

• состояние запаса «много/мало»; при отсутствии сигнала приложение использует техническое состояние Unknown;
• принятую наличную сумму и обновление баланса;
• состояние купюро- и монетоприёмника;
• начало карточной оплаты на выбранную сумму;
• успешный, отклонённый и отменённый результат оплаты;
• начало выдачи, прогресс и подтверждённое количество выданных жетонов;
• аппаратные ошибки и состояние связи.

Подтверждённая аппаратная разводка

IN8 — сервисная кнопка, IN1 и IN4 — active-low датчики уровня первого и второго хопперов, IN24 и IN25 — датчики выдачи первого и второго хопперов. Оба канала работают: первый использует 30X, второй — 40X. Выдача и пересчёт подтверждаются строками платы, поэтому физические входы не создают двойной программный учёт.

Неподтверждённые вопросы

• Фактическое разрешение и физический размер экрана.
• Является ли цена 10 рублей рабочей или демонстрационной.
• Финальные правила бонусных жетонов.
• Возможность возврата наличных и выдачи сдачи.
• Точная роль кнопки «Выдать» на домашнем экране.
• Формат взаимодействия с банковским терминалом через контроллер.
• Финальные бренд, логотип, персонаж, телефон и права на референсные ассеты.
• Требования к форматам промо-роликов, плейлисту и звуку.
• Визуальный сценарий успешной оплаты и частичной выдачи.