# ADR-0009. Кассовый протокол: резерв, подтверждение, отмена, возвраты

- Статус: принято (этап 4b)
- Дата: 2026-10-05

## Контекст

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

## Решение

- **Три шага.** `POST /receipts:calculate` считает без изменений (сколько угодно раз).
  `POST /receipts` регистрирует чек и **резервирует** всё, что обещано кассе: баллы (холд в леджере),
  бюджеты и лимиты акций (`CampaignUsage::record`), промокоды (`PromoCodes::reserve`); чек получает статус
  `reserved`. `POST /receipts/{id}:confirm` после печати **проводит** холд и начисляет баллы (с активацией
  и сгоранием по правилам снапшота), принимает фискальные признаки (ФН, ФД, ФП). Флаг `confirm: true`
  делает регистрацию и подтверждение одним шагом (интернет-магазин, касса без двухфазного протокола).
- **Пересчёт на сервере.** При регистрации чек всегда считается заново по снапшоту момента покупки;
  числа кассы не принимаются на веру. Сохраняются снапшот и полный результат расчёта.
- **Естественный ключ** — (касса, бизнес-дата, номер чека): повторная регистрация того же чека — 409
  `receipt_exists` с id существующего. Точные повторы запроса обрабатывает HTTP-идемпотентность (4.5).
- **Отмена.** `:cancel` резерва возвращает баллы, бюджеты, использования и промокоды (`cancelled`);
  `:cancel` подтверждённого чека без возвратов — аннулирование целиком (`voided`): начисленное
  сторнируется, списанное восстанавливается. Подтверждать и отменять может только касса, создавшая чек.
- **Истечение резерва.** Резерв живёт `processing.reservation_minutes` (30 минут); после этого
  подтверждение — 409 `reservation_expired`, а `receipts:expire-reservations` (ежеминутно, системная роль
  находит, работа — от имени тенанта) отменяет чек. Холд в леджере живёт на 10 минут дольше, чтобы его
  освобождала команда чеков, а не леджер.
- **Возвраты** — по исходному чеку с любой кассы программы, частичные, по количеству строк (в тысячных).
  Возвращается доля сохранённых эффектов строки: начисленные баллы сторнируются по политике программы
  для потраченных баллов, списанные — восстанавливаются (в исходные партии или в новую), бюджеты акций —
  возвращаются. Доли накопительные: `⌊x × возвращено_всего / количество⌋ − ⌊x × возвращено_ранее /
  количество⌋`, поэтому последний возврат отдаёт ровно остаток, и сумма всех возвратов равна исходному
  эффекту. Номер чека возврата делает возврат идемпотентным. Промокоды и использования акций
  освобождаются, когда чек возвращён полностью.
- **Покупатель.** Идентификация по телефону, карте, коду из приложения, внешнему id или id участника.
  Замороженный участник копит, но не тратит; заблокированный — ни то, ни другое. Анонимный покупатель
  ничего не получает, но расчёт показывает, сколько он получил бы как участник.
- **Время.** Покупка не может быть позже серверного времени больше чем на 5 минут и старше 7 дней —
  более старые чеки догружаются офлайн-пакетом (этап 4c).

## Дополнение (этап 4c)

- **Подтверждение списания.** Политика программы `redemption.confirmation` (часть снапшота правил):
  `none`, `weak_identifiers` (по умолчанию), `always`. Код приложения (короткоживущий, доказывает владение
  телефоном) — сильный идентификатор; телефон, карта, внешний id и всё, что введено вручную, — слабые.
  Касса узнаёт о необходимости кода из расчёта (`redemption_confirmation_required`), запрашивает код
  `POST /receipts:send-redemption-code` на число баллов расчёта (код привязан к кассе и этим баллам),
  проверяет его `POST /verifications/{id}:verify` и регистрирует чек с `redemption_confirmation`.
  Проверка кода — отдельный вызов вне транзакции: иначе откат неудачной регистрации стирал бы и счётчик
  попыток, и перебор кода стал бы бесконечным. Регистрация только потребляет подтверждённый код.
- **Антифрод.** Списание приостанавливается на 24 часа после смены телефона и после 10 чеков со
  списанием за сутки (настройки `processing.antifraud`); причина видна в объяснении расчёта.
- **Офлайн-пакеты.** `POST /receipts:batch` принимает до 100 чеков, проданных без связи (до 30 дней),
  и ставит задачу в очередь `offline`; `GET /receipt-batches/{id}` отдаёт результат по каждому чеку
  (`created`, `exists`, `failed` с проблемой). Офлайн-чек только начисляет баллы — по правилам момента
  покупки без скидочных акций, которых касса не могла применить; списание и промокоды офлайн запрещены.

## Дополнение (этап 6f)

- **Выпуск кода приложения — отдельный скоуп `presentation_codes`.** Код приложения — сильный идентификатор: участник
  показывает его на кассе, и при политике `weak_identifiers` (по умолчанию) или `none` касса списывает баллы без кода
  подтверждения. Ключ со скоупом `members` мог выпустить такой код любому участнику, найденному по телефону, — и касса
  с таким ключом списывала бы чужие баллы без SMS. Теперь код выпускает только ключ со скоупом `presentation_codes`, а
  его получают только ключи касс вида `ecommerce`, `mobile_app` и `integration` (`ApiScope::SERVER_TERMINALS`)
  — серверы сайта, приложения и интеграций — и никогда вместе с `receipts`: ключ, который сам выпускает коды и проводит
  чеки, был бы той же кассой. Для `pos` и `web_cashier` и вместе с `receipts` выпуск ключа отклоняется; вид кассы не
  меняется. Новые ключи по умолчанию получают `receipts`, `members`, `balances` (`ApiScope::defaults()`),
  `presentation_codes` — только если его назвать. Миграция дала скоуп ключам с `members` и без `receipts` только у касс
  этих трёх видов: остальные его теряют, и мерчанту, у которого приложение выпускало коды с ключом кассы или с ключом,
  проводящим чеки, нужен отдельный ключ кассы вида «Мобильное приложение». Повторный запуск миграции после отката даёт
  право только ключам, которым его давал прежний код, и никогда — кассе или ключу с `receipts`. Версия ключа кэша
  сменилась вместе с миграцией: если миграции выполняются до переключения на новый код, новое право действует сразу,
  без минуты кэша. Кто держит и ключ с `presentation_codes`, и ключ с `receipts`, может платить без кода
  подтверждения — поэтому первый остаётся на сервере приложения, а не на кассе.
- **Подбор кода приложения.** Код — 8 цифр и действует до своего срока (по умолчанию 2 минуты) на любой кассе
  программы. Разные коды, которые ни к кому не подошли, считаются по кассе в окне 10 минут: касса, у которой их
  набралось `processing.antifraud.presentation_code_misses` (по умолчанию 20), до конца окна получает на любой код 429
  `presentation_code_throttled` (поиск, расчёт, регистрация, код для списания); телефоны, карты и другие кассы
  работают. Подошедший код ничего не стоит, а повтор того же неподошедшего кода считается один раз — касса, которая
  пересчитывает корзину с истёкшим кодом, не блокируется. Счёт идёт до поиска, поэтому одновременные запросы не
  проскакивают лимит. Без счёта касса проверяла бы десятки тысяч кодов в час, со счётом — не больше 120, и подбор
  становится непрактичным. Офлайн-чек не принимает код приложения вовсе: к загрузке код истёк, а пакет из сотни чеков
  иначе проверял бы сотню кодов за раз.
- **Покупки участника и возвраты (6f-6b-2, ADR-0016).** `GET /members/{member}/receipts` — проведённые чеки участника в
  программе ключа (с возвратами и аннулированные тоже) любых касс программы, новые сверху, курсорная пагинация; скоупы
  `receipts` и `balances`: покупки — история участника, как история баллов. Так касса находит чек для возврата, когда
  номера у клиента нет (веб-касса чеков не печатает). Строка чека в ответах несёт `quantity` — сколько осталось вернуть,
  касса считает как `quantity − returned_quantity`. Возврат принимает `cashier` и запоминает кассу, которая его
  оформила (`receipt_returns.terminal_id`). На номер возврата, который у чека уже есть, API отвечает 201
  зарегистрированным под ним возвратом, даже если строки запроса другие: клиент отличает такой ответ по `lines` и
  `returned_at`. Имя кассира (`cashier`) без управляющих символов — иначе 422.
- **Чек кассы по номеру.** `GET /receipts?number=&business_date=` находит чек этой кассы и программы ключа по
  естественному ключу (номер уникален у кассы в пределах бизнес-даты): возврат по бумажному чеку, проверка, дошёл ли
  чек после обрыва связи. Ответ — список из одного чека или пустой, чтобы тот же адрес мог позже отдавать и другие
  выборки; чеки других касс по номеру не находятся.
- **Лимит кодов подтверждения на кассу.** Код, запрошенный ключом кассы, считается в лимит его кассы
  (`verification.limits.terminal_per_hour`, по умолчанию 30 в час; коды для регистрации и для списания — вместе), а не
  адреса: сервер мерчанта запрашивает коды для всех своих касс с одного адреса, и общий лимит адреса останавливал бы их
  всех. Лимит адреса остаётся для запросов без кассы — сейчас таких нет, они появятся у виджетов участника (6.5).
  Лимит считается на кассу, а не на ключ: ключи смены веб-кассы меняются при каждой разблокировке, и лимит на ключ
  обходился бы блокировкой.

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

- Напечатанный чек всегда обеспечен: гонки за баллы, бюджеты и промокоды проигрывает регистрация
  (409, касса считает заново до печати), а не подтверждение.
- Возврат никогда не пересчитывает чек по текущим правилам и не зависит от того, какие акции действуют
  сейчас.
- Незавершённые резервы не удерживают баллы и бюджеты дольше отведённого времени.
