evening_detective_frontend/docs/MXW01_PRINTING.md

Печать чеков команды на MXW01

Печать работает только на локальной площадке (APP_MODE=venue). На вкладке «Команды» выберите «Печать чека» → проверьте предпросмотр → нажмите «Печатать». Firefox и Chrome используют один серверный API; Web Bluetooth и настройки браузера не нужны. Сервер берёт название и пароль команды из базы, а адрес QR — из APP_BASE_URL площадки.

Настройка площадки на Linux

1. Сервер venue и MXW01 должны находиться рядом на одном Linux-компьютере с включённым Bluetooth. Установите термобумагу и включите принтер.
2. В локальном venue/.env задайте MXW01_ADDRESS=<Bluetooth MAC принтера>. Адрес текущего MXW01 уже настроен локально; .env не включается в Git.
3. Соберите комплект существующей командой make build, затем запустите make venue. Служба receipt_printer запускается из того же Go-образа.
4. Если приложение телефона подключено к принтеру, закройте его.

Служба печати использует прямое Bluetooth LE-соединение. Её контейнер работает с network_mode: host и NET_RAW, без privileged, доступа к базе и TCP-порта. API передаёт растровые данные через закрытый Unix-сокет в общем Docker-volume. Остальные контейнеры сохраняют существующую сеть. Python, Bleak и BlueZ D-Bus для печати не нужны.

Без MXW01_ADDRESS игра продолжает работать; при попытке печати сервер сообщает, что принтер не настроен. На публичном сервере кнопки печати нет, и API её запрещает.

Поведение и проверка

• За один запрос печатается один чек шириной 384 пикселя. Одновременный запрос получает сообщение «принтер занят»; постоянной очереди нет.
• Сервер проверяет бумагу и состояние MXW01, затем ждёт подтверждение завершения и проверяет контрольную сумму изображения. Общий таймаут — 110 секунд.
• Длинное название переносится. Неподдерживаемые символы, слишком длинная ссылка или чек выше 1024 пикселей отклоняются до печати.
• После разрыва связи или таймаута сначала проверьте бумажный чек: он мог уже выйти. Автоматической повторной печати нет. После устранения проблемы повторите печать вручную; спящий принтер разбудите кнопкой.
• Перед игрой напечатайте две разные команды, проверьте названия и отсканируйте QR телефоном в Wi-Fi площадки. Ссылка должна открывать напечатанную команду.

Чек содержит ссылку доступа команды; передавайте его участникам этой команды. PNG-предпросмотр требует авторизации и отдаётся с Cache-Control: no-store.

Протокол проверен на текущем MXW01: фактический ответ состояния содержит 10 байт, а ответ завершения — подтверждение и две копии CRC изображения. Источник описания формата: измерения протокола MXW01.