# ADR-0016. Веб-касса: устройства, ключи смен, кассиры

- Статус: принято; реализовано на этапе 6 — ✅ 6f-1 (подготовка Runtime API, ADR-0009), ✅ 6f-2 (устройства и ключи
  смен), ✅ 6f-3 (кассиры и смены), ✅ 6f-4 (оболочка кассы `/till`), ✅ 6f-5 (кабинет «Веб-касса»), ✅ 6f-6a (приложение
  кассы: привязка, смена, покупка с начислением), ✅ 6f-6b: ✅ 6f-6b-1 (списание баллов и регистрация участника),
  ✅ 6f-6b-2 (возвраты и итоги смены), ✅ 6f-6b-3a (работа без связи), ✅ 6f-6b-3b (камера). Настройки кассы (предел
  суммы чека) и отчёты по кассирам — вместе с антифродом кассы и этапом 8.1. Поправка 7a-1b: регистрация без кода по
  настройке программы
- Дата: 2026-10-05

## Контекст

Точке без своей кассовой интеграции нужна касса в браузере: планшет или ноутбук у кассира, который находит участника,
начисляет и списывает баллы, оформляет возвраты. Веб-касса работает на том же публичном Runtime API, что и интеграции
(ADR-0006): у неё нет своих путей в домен. Но браузер на кассе — недоверенная среда: кассир может открыть инструменты
разработчика, вкладку могут оставить открытой, ключ из страницы можно скопировать. Ключ кассы-интеграции живёт годами
на сервере; ключ веб-кассы так жить не может.

## Решение

### Устройства

- Менеджер мерчанта делает **одноразовый код привязки** для веб-кассы (касса вида `web_cashier`) и программы:
  10 символов Crockford base32 (`XXXXX-XXXXX`, 50 бит), действует 10 минут. Хранится только HMAC кода с ключом
  приложения, поэтому копия базы код не выдаёт. Код вводят как удобно: строчными, с пробелами и дефисами, «O» вместо
  нуля, «I» или «L» вместо единицы и кириллические буквы, похожие на латинские (А, В, С, Е, Н, К, М, О, Р, Т, Х, У).
- Браузер, погасивший код, становится **устройством** (`terminal_devices`) и получает токен
  `ltd_<префикс>.<секрет>` (`ltd_test_…` в песочнице): хранится SHA-256 секрета с маркером окружения, как у ключей
  касс. Код гасится один раз, даже если его погашают одновременно (строка кода блокируется до конца погашения), и
  только пока веб-касса работает и всё ещё веб-касса, программа активна и мерчант открыт; у приостановленного мерчанта
  привязка работает (ADR-0015).
- Код и устройство находятся до того, как известен тенант, узкими SECURITY DEFINER-функциями: `device_pairing_candidates`
  отдаёт код со статусом мерчанта, `terminal_device_candidates` — устройство со статусами мерчанта и кассы; обе — только
  точное совпадение. Ответ про устройство кэшируется на минуту простыми значениями (кэш не восстанавливает объекты,
  `cache.serializable_classes`).
- Токен живёт в **cookie устройства** `__Host-loyal_till` (на локальном http — `loyal_till`): HttpOnly,
  SameSite=Strict, на весь хост, 180 дней (`DeviceCookie::make`). Фреймворк её не шифрует: Runtime API читает cookie
  вне группы middleware `web` такой, какой её хранит браузер. Скрипт страницы её не видит.
- Оболочка кассы ставит cookie заново в каждом ответе устройству, поэтому она живёт 180 дней с последнего
  использования; устройство, которое не видели 180 дней, перестаёт работать и на сервере.
- Устройство отзывают (`TerminalDevices::revoke`): сразу — ответ кэша забывается, а отметка об отзыве держится дольше
  кэша, так что и проверка, прочитавшая устройство до отзыва, его не вернёт; вместе с устройством перестают работать
  все его ключи смен. Устройства закрытого мерчанта и отключённой кассы не работают, как и их ключи; смена этих статусов
  доходит до проверки в течение минуты.

### Ключи смен

- Когда кассир открывает или разблокирует смену, касса получает **ключ смены** — ключ Runtime API с
  `purpose = till_shift`: на кассу и программу устройства, со скоупами кассы (`receipts`, `members`, `balances`; кодов
  приложения у кассы не бывает, ADR-0009) и сроком не больше 12 часов.
- Ключ смены **привязан к устройству**: `api.key` принимает его только вместе с токеном того же устройства в cookie
  (401 `unauthenticated` без cookie, с чужим или отозванным устройством). Ключ, унесённый скриптом со страницы (XSS),
  без cookie не работает, а cookie скрипту недоступна. Кто откроет инструменты разработчика на самом устройстве,
  скопирует и ключ, и cookie — тогда остаются срок ключа, отзыв устройства и PIN кассира.
- У веб-кассы нет своего ключа: обычный ключ для кассы вида `web_cashier` не выпускается, а выпущенные раньше отозваны
  миграцией и не проходят проверку.
- Ключ выпускается под блокировкой строки устройства: отзыв устройства либо дожидается выпуска и отзывает новый ключ
  тоже, либо проходит раньше, и ключ не выпускается. Назначение ключа и его устройство не меняются никогда (триггер
  неизменяемых колонок), а ключ с устройством, но не смены, и ключ смены без устройства база не примет. Откат миграции
  сначала отзывает ключи смен: без устройства они работали бы как обычные.
- Ключи смен не показываются в «Ключах касс» и в консоли: они живут несколько часов и уходят вместе с устройством.
  «Готовность к запуску» считает программу обслуженной, если у работающей веб-кассы есть работающее устройство.

### Кассиры и смены (модуль `till`)

- **Кассир** — не учётная запись сотрудника, а имя с PIN-кодом у мерчанта (`till_cashiers`), для всех точек или одной;
  хранится только хеш PIN-кода (Argon2id), обратно PIN не выдаётся. PIN — от 4 до 8 цифр, не одна и та же цифра (1111)
  и не цифры по порядку (1234, 9876): их пробуют первыми. Имена кассиров у мерчанта не повторяются. Отключённый кассир
  не открывает смен, его открытые смены закрываются, а их ключи перестают работать.
- **Смена** (`till_shifts`) — работа кассира на устройстве. PIN кассира открывает смену и даёт устройству ключ смены
  (на 12 часов); на устройстве не больше одной открытой смены — новая закрывает прежнюю и её ключ. Блокировка отзывает
  ключ, разблокировка PIN-кодом кассира смены даёт новый и отзывает прежний; закрытие отзывает ключ. Отзыв устройства
  закрывает его открытую смену. Кассир работает только на устройствах своей точки, если она у него указана. Смены
  открываются и у приостановленного мерчанта; если программа устройства в архиве или устройство и касса только что
  перестали работать, ключ не выдаётся (`till_unavailable`).
- **Неверные PIN-коды** считаются у кассира: пять подряд блокируют его на 15 минут, верный PIN сбрасывает счёт. Отдельно
  они считаются у устройства, у каких бы кассиров их ни пробовали: после 20 неверных в окне 15 минут, которое начинается
  с первого из них, ввод PIN на устройстве останавливается до конца окна.
- **Счётчики не теряются.** PIN проверяется в транзакции смены, а исключение об отказе выбрасывается уже после её
  фиксации, поэтому смену открывают и разблокируют только вне транзакции вызывающего: её откат стёр бы счётчики
  (`Shifts` проверяет это сам).
- **Порядок блокировок.** Всё, что меняет смену устройства, и отзыв устройства сначала берут блокировку устройства
  (`TerminalDevices::LOCK_PREFIX`), поэтому одновременные открытия на одном устройстве идут по очереди; строки затем
  блокируются в одном порядке — кассир, смена, ключи, — так что касса и кабинет ждут друг друга, но не взаимно.
- Устройство, смена и ключ живут в тенанте устройства; реквизиты смены (устройство, кассир, касса, программа, время
  открытия) не меняются. Отзыв ключа действует сразу и внутри транзакции: отметка об отзыве переживает ответ кэша,
  прочитанный до фиксации.

### Оболочка кассы (`/till`)

- Оболочка — страница приложения кассы и её точки входа в группе middleware `web` (сеанс, защита от CSRF: запросы
  приложения приходят с того же источника, `Sec-Fetch-Site: same-origin`, или несут `X-XSRF-TOKEN`):
  `GET /till`, `GET /till/manifest.webmanifest`, `GET /till/sw.js`, `POST /till/pair`, `GET /till/device`,
  `POST /till/shifts`, `POST /till/shifts/current:lock`, `:unlock` и `:close`, `GET /till/shifts/current` (6f-6b-2).
  С участниками и чеками касса работает
  через Runtime API с ключом смены. Ошибки точек входа — `application/problem+json`, что бы ни просил запрос (отказ проверки CSRF и
  неизвестный метод — тоже): неверный ввод — 422, а не перенаправление, которое сохранило бы ввод в сеансе (PIN-код и
  код привязки в сеансе не сохраняются и тогда).
- **Привязка.** `POST /till/pair` с `pairing_code` (не больше 10 попыток в минуту с адреса) погашает код и ставит
  cookie устройства; ответ — то же, что `GET /till/device`, токена в нём нет. Неподошедший код — 422
  `till_pairing_invalid`, без объяснения причины. Если ответ собрать не удалось, новое устройство сразу отзывается: его
  токен до браузера не дошёл.
- **Сеанс сотрудника.** Привязка завершает сеанс сотрудника на хосте оболочки (`device_paired`, в журнале
  безопасности сотрудника — выход) и начинает сеанс браузера заново: кассой пользуются кассиры, и они не должны
  действовать от имени менеджера, который её привязал. Сеанс кабинета на другом хосте (оболочка на `TILL_DOMAIN`)
  хранится в cookie того хоста, и оболочка до него не дотягивается. Поэтому кабинет «Веб-касса» (6f-5) делает «этот
  браузер кассой» сам: завершает свой сеанс и только потом открывает оболочку с кодом во фрагменте адреса (`#…`),
  который не уходит на сервер и не попадает в сеанс как адрес страницы.
- **Прежнее устройство.** Устройство, которым браузер был до этого, отзывается вместе со своей сменой: браузер — одно
  устройство, и токен прежнего устройства из браузера ушёл. В журнал его мерчанта (это может быть и другой мерчант)
  пишется `till.unpair`.
- **Устройство.** Остальные точки входа отвечают только браузеру с cookie работающего устройства (иначе 401
  `till_device_required`), в тенанте устройства, не больше 60 запросов в минуту с устройства. `GET /till/device` —
  устройство, мерчант, касса, точка, программа (с валютой, поясом и тем, подтверждает ли она телефон кодом,
  `confirms_phone`), кассиры, которые могут работать на устройстве (с
  временем, до которого кассир заблокирован), и открытая смена — без ключа: после перезагрузки страницы касса снова
  спрашивает PIN. Токен, за которым нет работающего устройства, стоит один поиск по префиксу с ответом в кэше — как
  ключ Runtime API. Лимита по адресу нет: за общим адресом точки он остановил бы и работающие кассы, пока отозванная
  продолжает стучаться; поток запросов ограничивают на входе (веб-сервер), а приложение кассы после 401 перестаёт
  обращаться.
- **Смены.** `POST /till/shifts` (`cashier_id`, `pin` — строкой) и `:unlock` (`pin`) отвечают сменой и ключом смены
  (`key.token`, `key.expires_at`), `:lock` — сменой, `:close` и `GET /till/shifts/current` — сменой и её итогами
  (`summary`, см. «Возвраты и итоги смены»); без открытой смены — 409 `till_shift_required`. Ответы не кэшируются.
- **Журнал аудита.** Привязка и каждое изменение смены, отказы тоже (неверный PIN, блокировка), — в журнале аудита
  мерчанта, канал `web_till`: действует устройство (`till_device`), объекты — устройство, кассир и смена (отказ
  изменить открытую смену называет её, отказ открыть — кассира, которого просили). Из ввода сохраняется только
  `cashier_id` открытия смены, и только если это идентификатор: ни PIN-код, ни код привязки в журнал не попадают.
  Привязка, ответ на которую собрать не удалось, тоже записывается — с ошибкой и уже отозванным устройством. Не пишутся чтения, запросы браузеров без работающего устройства (401),
  неподошедшие коды привязки (мерчант не известен) и запросы сверх лимитов. Отказов одного устройства пишется не больше
  30 за 15 минут: дальше о них один раз за эти 15 минут сообщается в лог ошибок — журнал, который нельзя чистить, не
  забить.
- **Политика страницы.** У страницы нет своих скриптов и стилей; её CSP разрешает скрипты, стили, соединения и прочее
  только со своего хоста (картинки — ещё `data:` и `blob:`; изображение камеры идёт через `srcObject`, политике не
  подвластное) и ничего встроенного, а камеру —
  только своему хосту (сканирование кода участника). Заголовки безопасности есть и на отказах проверки устройства и
  лимитов. Приложение собирается в `public/till-app`, а не в `public/till`: каталог с таким именем веб-сервер отдал бы
  вместо страницы.
- **Хост.** С `TILL_DOMAIN` оболочка отвечает только на этом хосте, и браузер хранит её cookie отдельно от кабинетов.
  Без него оболочка не отвечает на хосте консоли: при `CONSOLE_DOMAIN` — только на хосте `APP_URL`, рядом с
  кабинетами, локально — на любом. Runtime API отвечает на любом хосте, поэтому вызовы кассы остаются на её хосте.
  `TILL_DOMAIN` — только имя хоста, и не хост консоли: иначе оболочка не отвечает нигде.

### Кабинет «Веб-касса»

- В кабинете мерчанта группа «Веб-касса»: «Устройства», «Кассиры», «Смены». Видят их все в мерчанте (право
  `settings.view`), никогда — PIN-код, токен устройства или ключ смены. Привязку устройств, кассиров и закрытие смен
  меняет право `till.manage` — чувствительное: с недавно подтверждённым вторым фактором, никогда через доступ поддержки.
  Устройство отзывают с правом `keys.revoke`: это учётные данные, и приостановленный мерчант тоже может сразу остановить
  потерянный планшет. Больше ничего приостановленный мерчант здесь не меняет: отключить кассира или закрыть смену —
  изменения, а не защита; уволенного кассира у приостановленного мерчанта останавливает отзыв устройства.
- **Привязка.** Код делается для работающей веб-кассы и активной программы и показывается один раз, в ответе на само
  действие: вместе со ссылкой на страницу кассы с кодом во фрагменте адреса (`/till#code=…`, строится от `APP_URL`, как
  ссылки в письмах, а со своим хостом кассы — на нём) и QR-кодом этой ссылки — камера планшета открывает кассу сразу с
  кодом. Код не попадает ни в состояние страницы, ни в сеанс, ни в журнал: там только касса, программа и id кода.
- **«Сделать этот браузер кассой».** Менеджер привязывает браузер, в котором работает: кабинет делает код, пишет
  запись в журнал, завершает сеанс менеджера в этом браузере так же, как привязка в оболочке (`device_paired`, выход —
  в журнале безопасности), и открывает страницу кассы с кодом во фрагменте адреса, который сервер не видит и сеанс не
  хранит. Так это работает и со своим хостом кассы (`TILL_DOMAIN`), до cookie которого кабинет не дотягивается.
- **Ссылка, QR-код и «этот браузер» работают через приложение кассы.** Приложение читает код из фрагмента адреса,
  сразу убирает его из адреса и истории (`history.replaceState`), погашает через `POST /till/pair` и нигде его не
  хранит.
- **Кассиры.** Добавляются с именем, PIN-кодом и точкой (или для всех точек), переименовываются, получают новый PIN-код
  (он снимает блокировку), отключаются (их открытые смены закрываются) и включаются. PIN-код вводится в форме (от 4 до 8
  цифр проверяется у поля, остальные правила — модулем кассы) и хранится только хешем; в журнал не пишутся ни PIN-код,
  ни имя.
- **Списки.** «Смены» — все открытые смены, как бы давно они ни открылись (на устройстве одна открытая смена), и
  закрытые за последние 30 дней, не больше 500, новые сверху: кассир, устройство, касса, идёт ли смена, заблокирована
  или закрыта и почему. «Устройства» не показывают отозванные больше 30 дней назад.
- **Закрытие смены из кабинета.** `Shifts::closeShift` закрывает открытую смену под блокировкой устройства, в общем
  порядке блокировок, с причиной `closed_in_cabinet` («Закрыта в кабинете»): её ключ перестаёт работать сразу.
- **Отложено.** Итоги смен по кассирам (чеки, начисления, списания) — с отчётами по кассирам (этап 8.1): чеки хранят
  кассира, которого присылает касса. Настройки веб-кассы (например, предел суммы чека) — вместе с антифродом кассы.

### Приложение кассы (6f-6a)

- **Сборка.** `frontend/till` — TypeScript без зависимостей и без сборщика: компилятор TypeScript из SDK
  (`sdk/typescript/node_modules`, только стираемый синтаксис), модули ES как есть. `composer till:build` (Node 22)
  компилирует приложение и модули SDK, которые оно импортирует, и кладёт их со стилями и иконками манифеста в папку
  сборки `public/till-app/<версия>` (не в git); версия — хеш её файлов и страницы, которая их загружает. Рядом —
  `build.json` с версией, по которому оболочка подставляет папку в страницу и иконки в манифест, и service worker этой
  сборки; прежние сборки удаляются после того, как новая заняла место. `composer check` и задание CI `till-app`
  собирают приложение и запускают его тесты (`node --test`); при развёртывании приложение собирается той же командой.
- **Runtime API через SDK.** Касса — обычный клиент Runtime API: `RuntimeClient` из SDK с ключом смены
  (`dangerouslyAllowBrowser`), адрес API — источник страницы, не больше одного повтора запроса и без долгих пауз по
  `Retry-After`. SDK в браузере cookie не отправляет, а ключ смены без cookie устройства не работает, поэтому касса
  передаёт SDK свой `fetch`, который отправляет cookie на свой же источник; перенаправлениям SDK не следует, так что
  cookie никуда больше не уходит. Ключ SDK отправляет только по HTTPS или по `http://` на саму машину (`localhost`,
  `127.0.0.1`, `[::1]`), поэтому по другому адресу касса сразу говорит, что не работает, — до привязки и PIN-кода.
- **Ключ смены — только в памяти страницы.** После перезагрузки касса снова спрашивает PIN: разблокировка выдаёт новый
  ключ и отзывает прежний. Одна вкладка браузера работает кассой (Web Locks): вторая говорит, что касса открыта в
  другой, — иначе каждая разблокировка останавливала бы ключ соседней вкладки.
- **PIN-код** вводится кнопками на экране или цифрами клавиатуры, без поля ввода: браузер не предлагает запомнить его
  как пароль на общем планшете.
- **Блокировка.** 10 минут без касаний и нажатий блокируют смену, как и кнопка «Заблокировать». Таймеры спящего
  планшета стоят, поэтому время простоя проверяется ещё при первом касании, когда страница снова видна или вернулась
  из истории и раз в 30 секунд: проснувшийся планшет открывает экран PIN-кода, а не смену. Запрос, который уже идёт,
  блокировка дожидается. Закрытие смены — с подтверждением; другой кассир открывает свою смену, и прежняя закрывается
  (список кассиров касса перед этим читает заново).
- **Экран — по состоянию устройства** (`GET /till/device`): привязка, выбор кассира (заблокированный — с временем, до
  которого), PIN, работа. Отказ, который говорит, что состояние изменилось в другом месте (401 оболочки — устройство
  отозвано; 409 `till_shift_required` — смену закрыли в кабинете; 404 `cashier_not_found`; 401 Runtime API — ключ больше
  не действует), забывает ключ и перечитывает устройство; если и оно отвечает 401, касса больше не обращается к серверу,
  пока её не привяжут заново (что она хранит на устройстве — см. «Работа без связи»). Без связи касса говорит об этом; не загрузившийся экран повторяется кнопкой «Повторить».
- **Ссылка с кодом в браузере, который уже касса,** не привязывает его молча: касса называет себя и спрашивает,
  привязать ли браузер заново (её устройство будет отозвано, смена закрыта), а код держит только в памяти. Код,
  который не получил ответа, остаётся в форме привязки.
- **Покупка.** Участник — по телефону, номеру карты или коду из приложения: вид выбирает кассир, а сканер-клавиатура —
  каждый символ нажатием, быстро, с Enter — читает карту (только цифры) или QR-код приложения (`loyal:<код>`), что бы ни
  было выбрано; вставленный, набранный или оставшийся в поле текст сканом не считается и помечается как ручной ввод
  (`manual_entry`, ADR-0009). Расчёт и чек называют найденного участника по `id` (код приложения живёт две минуты, а
  покупка может длиться дольше) с признаком ручного ввода того, по чему его нашли; при списании баллов — кодом из
  приложения, если его отсканировали (см. «Списание баллов»). Покупка — одна строка на сумму
  (`PURCHASE`, количество 1000) с кассиром смены (`cashier`). «Рассчитать» показывает сумму к оплате и начисление;
  «Провести чек» регистрирует чек и сразу подтверждает его (`confirm: true`). Другая сумма или другой участник отменяют
  расчёт, и ответ, пришедший после такой правки, не показывается.
- **Номер чека.** `<6 знаков устройства>-<10 знаков Crockford base32>`: секунда (30 бит) и 20 случайных бит из
  `crypto.getRandomValues`, без счётчика в браузере, поэтому очистка хранилища не повторит номер. Бизнес-день — дата в
  поясе точки (или программы), собранная из частей даты; ключ идемпотентности — `receipt:<касса>:<день>:<номер>`.
- **Чек без ответа не проводится дважды.** Пока ответа нет, каждый повтор регистрации отправляет ровно тот же запрос с
  тем же ключом. Если ответа нет (сеть, таймаут, 5xx) или отказ пришёл раньше, чем API посмотрел на чек
  (401, 403, 429), чек мог пройти: касса держит его на экране («ждёт ответа сервера»), другого участника и другую сумму
  не берёт, отменяет его только с подтверждением и не теряет при блокировке, закрытии смены и смене ключа — его
  повторяет следующая смена. Ключи идемпотентности хранятся по ключу API, поэтому повтор под новым ключом смены
  получает 409 `receipt_exists`: касса находит свой чек по номеру и бизнес-дате (`GET /receipts`) и считает его
  проведённым. Отказ после того, как API посмотрел на чек (400, 404, 409, 422), значит, что этот запрос ничего не
  зарегистрировал, и следующая попытка строит запрос заново. Но попытка без ответа могла ещё идти на сервере и
  записать чек позже, поэтому её номер закрепляется: касса ищет по нему чек при каждом отказе, а следующий запрос —
  даже другой покупки — идёт под тем же номером с новым ключом идемпотентности (`…:<номер>:<n>`). Тогда из двух
  запросов зарегистрируется один, а второй получит `receipt_exists`; если под номером нашёлся чек на другую сумму или
  другого участника, касса говорит, что прошёл он, а эту покупку просит провести ещё раз (с новым номером). Номер
  освобождается, когда его чек найден, когда под ним зарегистрирована покупка или когда кончился его бизнес-день.
  `receipt_exists` на первой попытке, без закреплённого номера, — чужой чек: касса не ищет его и берёт новый номер.
  Другая сумма или другой участник после отказа отменяют расчёт. Если устройство отозвали, пока чек ждал ответа, касса
  называет его номер. Если чек прошёл не так, как был рассчитан (другая сумма к оплате или другое списание: правила
  или баланс изменились), касса говорит об этом: верен чек.
- **Service worker** (`/till/sw.js`; его отдаёт оболочка с `Service-Worker-Allowed: /till`, чтобы он держал саму
  страницу `/till`, а не только `/till-app`) — один на сборку: хранит страницу, манифест и файлы своей сборки.
  Страница и манифест берутся сначала из сети, так что новая сборка доходит до кассы сразу; без сети, при ответе 5xx
  или если сеть молчит дольше 4 секунд — сохранённая копия. Файлы сборки не меняются (их папка — её версия), поэтому
  берутся сначала из сохранённых, и страница не смешивает файлы двух сборок. Ответы API и точек входа оболочки он не
  трогает. Без service worker (не HTTPS) касса работает, пока есть сеть.
- **Локальная проверка.** `php artisan db:seed --class=LocalTillSeeder` (только локально) делает в демо-мерчанте
  программу с опубликованными правилами и документами, точку с веб-кассой, кассира и участника с баллами и печатает
  ссылку привязки с новым кодом — так же, как кабинет: от `APP_URL` или на своём хосте кассы.
- **Дальше.** Работа без связи — 6f-6b-3a, камера — 6f-6b-3b (ниже).

### Списание баллов и регистрация участника (6f-6b-1)

- **Списание баллов.** Когда покупка рассчитана для найденного участника, касса показывает, сколько баллов можно
  списать (`max_redeemable_points`), и списывает столько, сколько введёт кассир, или все («Списать все» —
  `redeem_maximum`). Правила могут разрешить меньше, чем просили: касса говорит, сколько спишется, и дальше —
  подтверждение и чек — работает с этим числом (`redeem_points`), а не с «максимумом», который к моменту чека мог
  измениться. «Без списания» возвращает расчёт без баллов.
- **Подтверждение списания.** Где программа его требует (`redemption_confirmation_required`, по умолчанию — для
  слабых идентификаторов, ADR-0009), касса отправляет участнику код на ровно эти баллы
  (`receipts:send-redemption-code`), кассир вводит код, который назвал клиент (`verifications/{id}:verify`, неверный —
  с числом оставшихся попыток), и «Провести чек» становится доступным; чек несёт `redemption_confirmation`. Код
  отправляется на ровно эти баллы; запрос кода без ответа повторяется под тем же ключом — второй SMS он не отправит.
  Код из приложения — сильный идентификатор: если его отсканировали, а программа просит код только для слабых
  идентификаторов (так по умолчанию), расчёт и чек со списанием называют участника им, и SMS не нужна; истёкший за
  время покупки код касса просит отсканировать снова. Где код нужен всегда, участник называется по `id`, как и без
  списания. У участника без телефона списание с кодом недоступно. Если подтверждение перестало действовать (истекло
  или баллы пересчитались), касса просит рассчитать покупку заново.
- **Регистрация участника.** Если по телефону никого не нашли, касса предлагает зарегистрировать этот номер; есть и
  кнопка «Новый участник» (перед отправкой кода касса проверяет, нет ли уже участника с этим телефоном, и тогда
  продолжает с ним без SMS). Касса загружает действующие документы программы (новая операция Runtime API
  `GET /api/v1/consent-documents`, скоуп `members`: последняя опубликованная версия каждого вида с текстом),
  показывает их тексты и отмечает принятые: без правил программы и согласия на обработку персональных данных
  регистрации нет, рекламные согласия — по желанию клиента. Телефон подтверждается кодом (`members:send-code`, затем
  проверка кода): согласие даёт владелец номера, а не тот, кто его набрал. Это проверяет и сервер: касса вида
  `web_cashier` регистрирует только с подтверждённым кодом и принятыми правилами программы, иначе 422
  `validation_failed` (остальные кассы и сайты — по правилам программы, как раньше); исключение — программа, которая
  регистрирует без кода (см. «Поправка 7a-1b»). Регистрация
  (`POST /members`) несёт принятые виды документов, имя и код приглашения, если их дали, и кассира смены;
  подтверждённый код повторно не проверяется. Перед новой регистрацией касса читает документы ещё раз: если вышла
  новая редакция, показывает её и просит отметить согласия снова — записывается та редакция, которую видел клиент.
  Повтор регистрации без ответа — тот же запрос с тем же ключом, и поля, из которых он собран, пока закрыты; после
  отказа запрос собирается заново из полей, а истёкший код отправляется заново. Если участник с этим телефоном уже
  есть (409 `member_already_exists`), касса находит его по телефону и продолжает покупку с ним; его согласия не
  меняются. Локально коды не отправляются, а пишутся в `storage/logs/laravel.log`.

### Возвраты и итоги смены (6f-6b-2)

- **Возврат — по покупкам участника, а не по номеру.** Веб-касса не печатает чеков: у клиента на руках чек кассы
  магазина, номера чека лояльности у него нет. Поэтому кассир находит участника (как для покупки), открывает «Возврат
  покупки» и выбирает покупку из списка — новая операция Runtime API `GET /api/v1/members/{member}/receipts`
  (курсорная пагинация, не больше 50 на странице): проведённые чеки участника в программе ключа, в том числе с
  возвратами и аннулированные, любых касс программы, новые сверху по времени покупки. Покупки — история участника, как
  и история баллов, поэтому операция требует обоих скоупов, `receipts` и `balances` (у ключа смены есть оба). Чек без
  участника не возвращается на кассе: баллов у него нет. Выбранная покупка перечитывается (`GET /receipts/{id}`):
  возврат на другой кассе за это время учитывается.
- **Сколько вернуть.** API возвращает строки по количеству; чтобы касса знала, сколько осталось, строка чека в ответах
  API теперь несёт своё количество (`quantity`, в тысячных, как в запросе; в расчёте — из запроса). «Вернуть всё»
  возвращает остаток каждой строки. Покупка из одной строки — а так касса проводит каждую свою покупку — возвращается и
  частью: кассир вводит, сколько стоят возвращаемые товары, касса берёт количество строки (тысячные доли), товары
  которого стоят ближе всего к этой сумме (из двух одинаково близких — дешевле), но не весь остаток за меньшую сумму —
  иначе вернулась бы вся покупка, а с ней и бонусы, которые она дала, — и не товары, которые ничего не стоят. Доли
  касса считает так же, как API (от начала строки, с округлением вниз, целыми числами). Перед возвратом касса
  спрашивает подтверждение со стоимостью товаров и с тем, сколько вернуть клиенту деньгами: долей того, что он заплатил
  деньгами (`payable` строки, после скидок программы и оплаты баллами), — чтобы магазин не вернул деньгами то, что было
  оплачено баллами. Чек из нескольких позиций (с другой кассы) здесь возвращается только целиком. После возврата касса
  говорит, сколько начисленных баллов списано, сколько баллов, которыми платили, вернулось клиенту и сколько вернуть ему
  деньгами.
- **Возврат без ответа не проводится дважды** — по тем же правилам, что чек. Номер возврата делается как номер чека,
  ключ идемпотентности — `return:<чек>:<номер>`. Без ответа (сеть, 5xx, 401, 403, 429) касса держит возврат на экране и
  повторяет ровно тот же запрос с тем же ключом, в том числе после блокировки и под новым ключом смены: на номер,
  который у чека уже есть, API отвечает зарегистрированным под ним возвратом. Продажа ждёт, пока возврат не повторят
  или не отменят с подтверждением. Номер возврата без ответа закрепляется за чеком: следующий возврат этого чека, даже
  на другую сумму, идёт под ним с новым ключом (`…:<номер>:<n>`). Ответ — возврат этого запроса, только если совпадают
  его время (`returned_at`) и строки; иначе это прошедший возврат без ответа: касса называет его время и что он сделал,
  а новый возврат предлагает оформить, только если клиент возвращает ещё товары. Номер освобождается, когда под ним
  пришёл возврат; перезагрузку страницы он переживает (6f-6b-3a), а новая привязка о нём забывает (и о возврате без
  ответа тоже — диалог «Привязать заново?» об этом предупреждает). Отказ после того, как API посмотрел на возврат (400, 404, 409, 422),
  значит, что этот запрос ничего не вернул: касса перечитывает покупку и показывает, что от неё осталось.
- **Чек и возврат помнят устройство.** Ключ смены принадлежит устройству (`api_keys.device_id`), и Runtime API
  записывает это устройство в чек, зарегистрированный им онлайн (`receipts.device_id`, неизменяемо), и в возврат
  вместе с кассой, которая его оформила, и кассиром (`receipt_returns.terminal_id`, `device_id`, `cashier`; поле
  `cashier` есть теперь и в теле возврата Runtime API). У устройства не больше одной открытой смены, поэтому чеки и
  возвраты устройства между открытием и закрытием смены — это чеки и возвраты смены. Офлайн-пакет запоминает
  устройство своего ключа (6f-6b-3a); чек, проданный без связи, попадает в итоги смены, в которую его зарегистрировали. Кассир в чеке и возврате — то, что прислала касса (у веб-кассы — кассир смены): для отчётов
  по кассирам (8.1) его надо брать из смены ключа, а не из тела запроса. Имя кассира в чеках, возвратах, офлайн-чеках и
  регистрациях Runtime API теперь не принимает управляющих символов (422 `validation_failed`): PostgreSQL не хранит
  NUL и не принимает текст не в UTF-8.
- **Итоги смены.** `GET /till/shifts/current` оболочки отдаёт открытую смену устройства с итогами на сейчас,
  `POST /till/shifts/current:close` — закрытую смену с итогами за всю смену (новый контракт
  `Processing\Contracts\ReceiptStats::ofDevice`, по времени регистрации): действующие чеки (проведённые, в том числе
  с возвратами; не резервы, не отменённые и не аннулированные) — их число, сколько из них с участником, сумма до скидок
  программы, скидки, сколько оплачено баллами; баллы по типам — начислено, оплачено, а при возвратах списано
  начисленных и возвращено клиентам; число возвратов. Итогов заблокированной смены оболочка не отдаёт (`summary:
  null`) ни на чтение, ни при закрытии: cookie устройства есть у любого у прилавка, а цифры смены ждут PIN-кода её
  кассира. Итоги, которые не удалось посчитать при закрытии, тоже `null` (ошибка уходит в лог): смена уже закрыта.
  Касса показывает итоги по кнопке «Итоги смены» и после закрытия смены — на экране выбора кассира, пока не выбран
  следующий (итоги сохраняются до того, как касса перечитает устройство, поэтому сбой этого чтения их не теряет).
  Итоги смен по кассирам в кабинете и отчёты по кассирам — этап 8.1.
- **Кэш браузера.** Запросы кассы к Runtime API не пользуются кэшем браузера (`cache: 'no-store'`): покупки участников
  и чеки не остаются на общем планшете.

### Работа без связи (6f-6b-3a)

- **Когда.** Касса считает, что связи нет, когда её запрос к Runtime API или к оболочке остался без ответа (в том числе
  когда прокси ответил 502–504 без сервера) и когда браузер говорит, что сеть пропала (`offline`); любой ответ сервера,
  отказ тоже, или событие `online` возвращают обычный режим. Без связи касса работает только в открытой смене: PIN-код
  проверяет сервер, поэтому заблокированная касса без связи не откроется (экран PIN-кода об этом говорит). Режим не
  отключает обычных действий: «Найти» и «Рассчитать» пробуют сервер, а рядом с ними появляется «Записать без связи».
- **Что записывается.** Только покупка участника и только с начислением: без списания баллов и без скидок акций
  (пакет не даёт ни того, ни другого), без регистрации и возвратов. Участник — тот, кого называет поле участника, если
  в нём что-то есть (кассир ввёл или отсканировал телефон или карту следующего клиента; скан остаётся сканом и после
  поиска без ответа), иначе найденный до обрыва связи (по `id`). Кода из приложения без связи нет (он истечёт раньше,
  чем чек уйдёт на сервер), покупки без участника тоже. Чек получает номер так же, как онлайн, — или номер,
  закреплённый чеком без ответа (тот номер переходит к записанному чеку: из двух чеков под ним API зарегистрирует один),
  бизнес-день и время продажи. Касса показывает участника только маской.
- **Очередь на устройстве.** Записанные чеки ждут в локальном хранилище браузера (`localStorage`, а не IndexedDB:
  объём мал, запись синхронна и атомарна, в тестах нужна только заглушка) под идентификатором устройства, вместе с
  закреплёнными номерами чека и возвратов и с чеком или возвратом в пути: их касса сохраняет до того, как запрос уйдёт,
  поэтому страница, закрытая посреди запроса, их не теряет. Запрос пакета без ответа живёт только в памяти: после
  перезагрузки пакет собирается заново, и API всё равно зарегистрирует каждый чек один раз — по номеру. Что не читается
  как сохранённое самой кассой (испорчено, другой версии, изменено руками), касса пропускает. Чек и идентификатор
  участника хранятся не дольше 72 часов по часам устройства (и время продажи на 72 часа впереди часов — тоже не время
  продажи): что старше, касса удаляет при загрузке страницы, когда страница снова видна, раз в полминуты — на любом
  экране, в том числе когда устройство не работает, — и перед каждой отправкой, и говорит, сколько удалено. Браузер
  просят не очищать хранилище под нагрузкой (`navigator.storage.persist()`); если он ничего не сохраняет, касса
  предупреждает, что чеки пропадут при обновлении страницы. Что сохранила более новая версия кассы, эта не читает и не
  перезаписывает. Перед закрытием смены касса говорит, сколько чеков ждут отправки: они уйдут в следующей смене этого
  устройства.
- **Устройство больше не работает.** Оболочка различает два ответа 401. `till_device_revoked` — устройство отозвано
  или не использовалось 180 дней и не заработает никогда: ответ несёт `Clear-Site-Data: "storage"`, касса сама тоже
  стирает всё, что хранила, и называет, сколько чеков без связи пропало (баллы за них не начислены, если сервер их не
  принял). `till_device_required` — браузер не привязан или касса сейчас не работает (мерчант закрыт, касса отключена):
  хранилище остаётся, и чеки уйдут, когда устройство снова заработает; новая привязка их удалит, поэтому, пока они
  есть, касса спрашивает, прежде чем привязать браузер — по ссылке или кодом в форме (у работающего устройства об этом
  говорит диалог «Привязать заново?»; ссылка, на которую сервер не ответил, оставляет этот диалог, а не форму). Ссылка в
  браузере отозванного устройства привязывает его сразу и говорит, сколько чеков пропало. Запрос без cookie или с
  cookie, которая не принадлежит никакому устройству, мог прийти откуда угодно и ничего не стирает.
- **Проверка кассиром.** Чеки, которые касса прочла из хранилища после перезагрузки, сами не уходят: никто не вводил
  PIN-код для этой страницы, когда их записывали. Это касается и чеков, уже отправленных в пакете: касса читает его
  результат, но если чек придётся отправить снова (пакета API не знает, под своим номером чек уходит заново), он ждёт
  кассира. В открытой смене касса говорит, сколько чеков ждут проверки; в списке «Очередь» их можно убрать, а
  «Отправить проверенные» отправляет. Чек, который ждал проверки, мог пройти до перезагрузки, поэтому, когда его
  убирают, его номер закрепляется за следующим чеком (если чек сегодняшний и другой номер не закреплён). Без открытой
  смены (PIN-код, выбор кассира) касса показывает только числа: список, как и итоги смены, ждёт PIN-кода.
- **Отправка.** Пока у кассы есть ключ смены, очередь уходит пакетами по 100 чеков (`receipts:batch`) — сразу после
  записи, после открытия и разблокировки смены, при возвращении связи, когда страница снова видна, раз в полминуты и
  по кнопке «Отправить сейчас». Запрос пакета без ответа повторяется как был (те же чеки, тот же ключ идемпотентности,
  `batch:<случайный>`); если чек из него за это время ушёл (истёк), запрос собирается заново. Результаты касса читает
  (`receipt-batches/{id}`) с паузами 2, 4, 8, 15 и 30 секунд, пока пакет не обработан. `created` — чек уходит из
  очереди. `exists` — под номером уже есть чек: касса читает его и убирает свой, если совпадают номер, время продажи,
  сумма и участник (по `id` или по цифрам маски телефона). Чек под унаследованным номером уходит и тогда, когда под ним
  та же покупка, проданная раньше по полной цене (сумма и участник: попытка без ответа всё-таки прошла), а под другой
  покупкой — снова отправляется под своим номером. Конфликт — всё остальное: под номером чужой чек; или под
  унаследованным номером прошёл чек, оставшийся без ответа, а касса не может сама решить, та ли это покупка (участник по
  карте — её API не показывает) или та покупка была оплачена иначе (баллами, со скидкой) — тогда кассир видит, что тот
  чек прошёл, с его суммой и временем. `failed` — отказ с причиной. Чек, которого нет в результатах завершённого
  пакета, снова уходит в очередь. Конфликты и отказы остаются в очереди, пока кассир их не уберёт, — баллы за них не
  начислены (ручные корректировки — этап 6g); телефон или карту такой чек больше не хранит, только маску. Отказ всему
  пакету (400, 422) — отказ только тем чекам, которые назвала проверка (`receipts.<N>.…`), остальные уходят сразу снова;
  если не назван ни один — отказ всем. Ключ, ушедший с другими чеками (`idempotency_key_reused`), сразу меняется на
  новый; пакет, которого API не знает (404), уходит заново. Ключ смены, которым касса больше не пользуется (смена
  заблокирована или закрыта, браузер привязан заново), ничего не отправляет — и повтор запроса в SDK тоже.
- **После перезагрузки.** Чек в пути или без ответа, который только начислял баллы по рассчитанным ценам, касса ставит
  в очередь под его номером (на проверку кассиром): API зарегистрирует его один раз, прошла та попытка или нет. Чек со
  списанием баллов или со скидкой акции в пакет не берётся: его номер остаётся закреплённым, и касса скажет при
  следующей покупке сегодня, если тот чек прошёл. Возврат в пути или без ответа закрепляет свой номер за чеком покупки.
  Обо всём этом касса говорит на экране выбора кассира или PIN-кода, пока смена не откроется. Чек без ответа, который
  только начислял баллы без скидок, кассир может поставить в очередь и сам — кнопкой «Записать в очередь без связи».
- **Сервер.** Пакет запоминает устройство ключа смены, которым загружен (`receipt_batches.device_id`), и его чеки
  регистрируются для этого устройства — они попадают в итоги смены, в которую их приняли (по времени регистрации).
  Когда пакет обработан, из сохранённых в нём чеков удаляются идентификаторы участников (ADR-0008), у пакетов,
  обработанных раньше, — миграцией; результаты называют чеки по номерам. Чек, на котором обработка падает не из-за
  базы данных, получает отказ `internal_error` (ошибка уходит в лог), остальные чеки пакета обрабатываются; потерянное
  соединение или конфликт сеансов прерывают попытку целиком. Задание пакета пробует три раза (паузы 10 и 60 секунд);
  пакет, на котором оно сдалось, всё равно завершается, но без потерь: в результатах только чеки, зарегистрированные
  под своими номерами (`exists`), остальные касса отправит снова — каждый зарегистрируется один раз. Первый, кто
  завершил пакет, и определяет его результат. Пакет, который никакое задание не завершило (задание не поставилось в
  очередь, обработчик пропал, задание из старой версии), `receipts:finish-batches` (раз в пять минут) через системную
  роль передаёт заданию снова через 15 минут и завершает так же через сутки; «Состояние системы» сообщает о пакетах,
  не обработанных за час (`processing.batches`). При выкладке обработчики очереди перезапускаются после миграций, как
  всегда: пакеты, завершённые старыми обработчиками, сохранили бы участников. Время чека и возврата (`purchased_at`,
  `returned_at`) Runtime API проверяет строго — существующие дата и время суток, смещение до ±14:00, до шести знаков
  долей секунды, — и так же описывает его спецификация. Отпечаток запроса у ключа идемпотентности — HMAC на ключе
  приложения (тело может содержать телефон); отпечатки на ключах до ротации (`APP_PREVIOUS_KEYS`) и сохранённые раньше
  простым хэшем принимаются, пока их ключи хранятся.

### Камера (6f-6b-3b)

- **Где.** Камера планшета читает карту участника и QR-код его приложения (`loyal:` и код) там, где браузер умеет
  читать коды с камеры (`BarcodeDetector`: Chrome на Android, ChromeOS и macOS). Где не умеет — в Safari и любом
  браузере iPhone и iPad, в Firefox, в Chrome на Windows и Linux, — кнопки «Камера» нет, и остаются сканер-клавиатура и
  ручной ввод. Касса проверяет это сама при загрузке и берёт только те форматы, которые браузер знает: QR-код и
  штрихкоды карт (EAN-13/8, Code 128/39/93, Codabar, ITF, UPC-A/E); если ни одного нет, кассир узнаёт об этом при первой
  попытке.
- **Как.** «Камера» рядом с «Найти» показывает изображение с задней камеры, если она есть (`facingMode: environment`,
  1280×720 — штрихи карты должны различаться; без звука), на месте формы участника и смотрит на него раз в 150 мс,
  пока не прочтёт код. Камера ищет покупателя у кассы: найденный раньше участник, набранный текст и расчёт для них
  уходят с экрана, а записать покупку без связи, пока камера ищет, нельзя; курсор ни в какое поле не встаёт —
  клавиатура закрыла бы изображение. Прочитанное — скан, как у сканера: `loyal:` и восемь цифр — код приложения, цифры —
  карта, что бы ни было выбрано, и отметки ручного ввода нет (`manual_entry: false`); дальше — обычный поиск участника,
  а без связи — запись покупки, где скан остаётся сканом, и при повторном «Найти» тоже.
- **Когда камера гаснет.** Как только код прочитан, кассир нажал «Отменить», касса начала другое действие с сервером
  (расчёт, поиск, итоги смены), сменился экран (блокировка, смена закрыта, устройство отозвано) или страница скрыта
  (планшет уснул, открыто другое приложение): касса останавливает поток в сам момент отмены, чего бы чтение ни ждало
  (запуска изображения, распознавания кадра), и индикатор камеры гаснет. Код, прочитанный после остановки, никого не
  ищет. Изображение не покидает планшет: его читает браузер, на сервер уходит только прочитанный идентификатор — как и
  при вводе вручную.
- **Отказ.** Если доступа к камере нет (браузер или кассир его не дали), камеры нет или она занята другим приложением
  (в том числе другое приложение забрало её посреди чтения), браузер не читает нужных кодов или не может прочитать
  уже показанное изображение, или оно не запустилось, касса говорит об этом, гасит камеру и ставит курсор в поле для
  ручного ввода. Разрешение камеры даёт заголовок `Permissions-Policy: camera=(self)` страницы кассы (6f-4); поток
  показывается через `srcObject`, которому CSP не нужна (`media-src` у кассы — только `'self'`).

## Поправка 7a-1b. Регистрация без кода

Коды уходят через SMS-аккаунт мерчанта (ADR-0020). Мерчант без него может переключить у программы «Регистрацию на
кассе» на «Регистрировать без кода» (`programs.confirms_phone`, по умолчанию — с кодом; кабинет, «Программы»). Это
ослабляет доказательство согласия, поэтому переключает право `till.manage`: со свежим вторым фактором, никогда через
доступ поддержки; выбор пишется в журнал аудита (`programs.update`).

- Касса узнаёт настройку из ответа `GET /till/device` (`program.confirms_phone`) и читает его заново, открывая каждую
  регистрацию. Если код не ушёл (`code_delivery_unavailable`), а мерчант тем временем разрешил регистрацию без кода,
  касса переходит к ней; если регистрацию без кода отклонили, а мерчант снова включил код, — к отправке кода.
- Без кода касса просит сверить номер с клиентом; перед регистрацией она, как и с кодом, ищет участника с этим
  телефоном и продолжает с найденным. Записываются только правила программы и согласие на обработку персональных
  данных — без рекламных согласий и без кода приглашения: ни то, ни другое не подтверждено владельцем номера, а награду
  за приглашение можно было бы накручивать выдуманными номерами.
- Сервер для кассы вида `web_cashier` без кода требует имя кассира (`cashier`), правила программы и только обязательные
  согласия, отказывает в коде приглашения (422 `validation_failed`). В доказательство согласия, как и всегда,
  записываются касса, кассир и адрес, а теперь и ключ (смены), и устройство кассы.

## Последствия

- Касса на планшете не хранит долгоживущих секретов, доступных скрипту: токен устройства — в HttpOnly-cookie, ключ
  смены — только в памяти страницы, и он работает только вместе с cookie.
- Злонамеренный кассир по-прежнему управляет своим устройством: защита — короткие ключи, привязанные к устройству,
  код подтверждения для любого идентификатора, который касса может ввести сама (ADR-0009), лимиты по кассе, смены
  кассиров в кабинете и отчёты по кассирам (этап 8.1).
- Потеря cookie (очистка браузера) требует новой привязки: менеджер делает новый код, старое устройство отзывает.
- Чеки, проданные без связи, до 72 часов лежат на общем планшете с телефоном или картой участника (касса показывает их
  маской); очистка данных браузера за это время теряет их, и баллы за них не начисляются.
