Ошибка онлайн-кассы не отображается менеджеру заказа: как вернуть контроль

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

Сопоставьте order ID, fiscal task ID и внешний operation ID. Проверьте базу, очередь и ответ провайдера, а затем сравните их с полями, которые читает админка. Не нажимайте повтор до проверки исходной операции.

Что проверить в первую очередь

Для ситуации «фискализация завершилась ошибкой, но менеджер видит заказ как успешный» сначала зафиксируйте один воспроизводимый пример: время, идентификатор объекта, пользователя или операции, входные данные, версию приложения и фактический результат. Отдельно запишите ожидаемое поведение: админка показывает отдельный статус чека, понятную категорию ошибки, число попыток и безопасное действие без раскрытия секретных данных. Не меняйте сразу несколько настроек: один контролируемый шаг должен подтверждать или исключать одну гипотезу.

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

• Проверьте отдельные fiscal status и updated_at.
• Посмотрите DLQ и возраст pending-задачи.
• Уточните роль менеджера и доступ к диагностике.
• Проверьте безопасное отображение кода без токенов и персональных данных.

Почему возникает проблема

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

Разбирайте события по хронологии и ищите первую точку расхождения с бизнес-правилом. Учитывайте повтор запроса, задержку события, параллельное выполнение и восстановление после временного отказа: именно в этих условиях проявляются ошибки согласованности и идемпотентности.

• Админка отображает только order.status.
• Worker пишет ошибку в лог, но не в доменную запись.
• Кеш карточки не инвалидируется.
• Неопределённый timeout ошибочно превращается в success.

Пошаговая диагностика

Создайте безопасный тестовый сценарий, который не затрагивает реальные списания, рассылки и клиентские данные. Назначьте операции единый correlation ID и проследите его через запрос, бизнес-логику, базу, очередь и внешние интеграции. Для каждого этапа сохраните вход, результат, код ответа, длительность и версию записи.

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

• Сравните событие worker и запись fiscal task.
• Запросите операцию у кассы по исходному ID.
• Проверьте serializer ответа админки.
• Найдите закрытые заказы без фискальных реквизитов.

Как сделать фискализацию наблюдаемой

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

Надёжная реализация хранит бизнес-состояние явно. У каждого значимого действия есть стабильный идентификатор, владелец, версия правила и проверяемый переход статуса. Повторная доставка события не создаёт второе действие, а запоздавший ответ не возвращает объект в невозможное состояние.

• Хранятся pending, processing, done, retryable и failed.
• Ошибка нормализуется в код, сообщение и безопасное действие.
• Retry использует тот же idempotency key.
• Просроченные задачи попадают в рабочую очередь.

Как исправить проблему

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

Для существующих записей сформируйте dry-run: объект, старое значение, предлагаемое новое значение и основание. Обновление должно быть идемпотентным, ограниченным точной выборкой и создавать отчёт. Любой временный обход ограничьте сроком, пользователями и областью действия.

• Добавьте fiscal status и историю попыток в API админки.
• Сохраняйте нормализованную ошибку вместе с внешним ID.
• Инвалидируйте кеш после каждого перехода.
• Разрешите повтор только после сверки неопределённого результата.

Безопасный порядок внедрения

• Сохраните конфигурацию, связанные записи и необходимые журналы; отдельно проверьте реальное восстановление резервной копии.
• Воспроизведите проблему на тестовом объекте и сохраните результат до изменения для последующего сравнения.
• Внесите минимальное изменение под контролем версий, опишите причину, ожидаемый эффект и точный откат.
• Проверьте нормальный сценарий, ошибочный ввод, повтор запроса, параллельную операцию и временный отказ зависимости.
• Выпустите изменение на ограниченную долю трафика или один процесс, если архитектура это позволяет.
• После стабильного наблюдения исправьте исторические данные отдельным контролируемым запуском.

Как проверить результат

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

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

• Ошибка данных видна менеджеру сразу.
• Timeout не приводит к дублирующему чеку.
• После исправления реквизитов retry завершает ту же задачу.
• Роль без права не видит чувствительные детали.

Типичные ошибки при исправлении

• Показывать сырое тело провайдера с секретами.
• Создавать новую fiscal task при каждом клике.
• Считать заказ завершённым доказательством чека.
• Удалять ошибочные задачи из очереди.

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

Как предотвратить повторение

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

Мониторьте полный пользовательский путь, а не только доступность серверов. Техническая метрика должна быть связана с бизнес-результатом: заказ завершён, доступ выдан, файл восстановлен, событие обработано один раз, данные изолированы. Уведомление должно содержать контекст для первого решения.

• Возраст fiscal pending и failed.
• Заказы без реквизитов чека.
• Число повторов по категориям ошибок.
• Расхождение реестра кассы и локальной базы.

Что подготовить для технического разбора

• Описание ожидаемого и фактического поведения с точной последовательностью действий.
• Время возникновения, идентификатор тестового объекта и версии затронутых компонентов.
• Обезличенные журналы до и после ошибки с единым correlation ID.
• Список последних изменений, выполненных проверок и условий исчезновения симптома.
• Безопасный доступ к тестовой среде либо минимальный пример без паролей, токенов и персональных данных.

Частые вопросы

Можно ли показывать полный ответ кассы?

Лучше нормализовать его и скрыть секреты и персональные данные.

Когда разрешать повтор?

После определения, что исходная операция не создала документ или допускает идемпотентный retry.

Нужен ли отдельный экран?

Достаточно ясного блока в заказе и общей очереди проблемных чеков.

Когда нужна помощь специалиста

Если менеджеры не видят ошибки кассы, я могу проверить модель статусов, worker, API админки и retry. Для оценки нужны обезличенный order ID, ответ кассы и схема текущих статусов.