up

docs/MXW01_PRINTING.md

@@ -0,0 +1,47 @@
+# Печать чеков команды на 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](https://github.com/eliorpom-cmd/print-on-my-desk/blob/main/docs/09-protocol.md).