Сначала договориться о событиях

Интеграционный контракт должен описывать не только поля, но и жизненный цикл. Нужно определить, какое событие означает подтверждённую продажу, какие события меняют или отменяют её и в какой момент QR CTRL создаёт цифровое право.

Чем точнее описана семантика событий, тем меньше логики приходится угадывать по косвенным признакам вроде статуса заказа или времени последнего изменения.

Стоит явно зафиксировать источник истины для каждого события. Например, только POS подтверждает продажу, а только QR CTRL определяет текущее состояние цифрового права. Тогда при расхождении систем понятно, какую запись восстанавливать и откуда.

Идентификаторы должны быть стабильными

Для сквозной трассировки нужны стабильные идентификаторы заказа или позиции, ресторана, права и операции. Они должны сохраняться при повторной доставке сообщения и позволять однозначно находить исходное событие.

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

Идентификаторы лучше считать частью контракта так же, как формат полей. Их нельзя незаметно менять при обновлении POS или переносе точки, если они участвуют в дедупликации и исторической сверке.

Повтор события не должен повторять бизнес-действие

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

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

Идемпотентность нужна в обе стороны. POS может повторно сообщить о продаже, а станция — повторно отправить результат операции после таймаута. Каждый тип события должен иметь собственный ключ, позволяющий отличить повтор от нового действия.

Состояние права лучше хранить явно

Право должно иметь собственный жизненный цикл, а не вычисляться каждый раз из набора несвязанных таблиц. Активность, срок, исчерпание лимита и отзыв должны приводить к однозначному состоянию или проверяемому набору признаков.

Это упрощает поддержку: в спорной ситуации можно увидеть, в каком состоянии находилось право и какое правило сработало.

Что делать при временных отказах

Нужно заранее различить ошибки, при которых запрос можно безопасно повторить, и бизнес-отказы, которые повтором не исправятся. Таймаут интеграции и просроченное право — разные события и должны обрабатываться по-разному.

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

Для каждой внешней зависимости полезно определить таймаут и поведение после него. Бесконечное ожидание хуже явного отказа: оно блокирует гостевой сценарий и усложняет диагностику. При этом решение о временном офлайн-режиме принимается отдельно и зависит от требований заказчика.

Журнал и корреляция событий

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

Логи должны фиксировать время, результат и причину ошибки без хранения лишних чувствительных данных. Цель — диагностика, а не копирование содержимого всех систем в один журнал.

Для поддержки удобно использовать единый идентификатор корреляции, который проходит через запросы между компонентами. Тогда поиск одной операции не требует сравнивать временные метки вручную.

Что проверить на приёмке интеграции

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

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

Набор приёмочных тестов лучше автоматизировать настолько, насколько позволяет контур. При масштабировании на десятки ресторанов повторяемость проверки становится частью качества платформы, а не разовой задачей команды внедрения.

Самая дорогая ошибка — два источника истины

Проблемы начинаются, когда POS считает право активным, QR CTRL — уже отменённым, а локальная станция продолжает жить по старому состоянию. Тогда каждый компонент по-своему «прав», но восстановить реальную картину почти невозможно.

Поэтому заранее нужно определить владельца каждого состояния. POS владеет фактом продажи и возврата. QR CTRL — состоянием права на розлив. Станция не должна самостоятельно придумывать бизнес-правила: она выполняет решение и сообщает результат.

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

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