Концепт «Поток»

От приёма события до подтверждённого действия: обмен виден на каждом шаге.

Концепт-проект: «Поток» — вымышленная компания. Результатов работы здесь нет: только решения и гипотезы.

О заказчике

• Сценарий: Заказ проходит через CRM, учётную систему и доставку
• Пользователь: Оператор интеграций и ответственный за данные
• Первая версия: Один маршрут заказа, очередь, журнал и разбор исключений
• Граница: Не создаём универсальную платформу для всех возможных API
• Данные: Заказы, идентификаторы и статусы на иллюстрациях вымышлены

Задача

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

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

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

Риски исходного процесса

Повтор создаёт вторую операцию

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

Новая редакция перезаписана старой

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

Ошибка исчезает из поля зрения

После ограниченного числа попыток событие попадает в отдельную очередь исключений. У него есть причина, назначенный ответственный и разрешённый следующий шаг.

Доступ к повтору слишком широк

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

Решение

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

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

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

Как устроен продукт

1. Карта маршрута. Источники, получатели и этапы обработки одного заказа. Зачем: Сотрудник видит путь данных и не смешивает приём запроса с завершением операции.
2. Журнал событий. Ключ действия, источник, редакция, состояние и связанный объект. Зачем: Повтор, задержку и порядок изменений можно проверить без поиска по разным системам.
3. Очередь исключений. Ошибки с причиной, владельцем и разрешёнными вариантами решения. Зачем: Техническая проблема превращается в управляемую задачу, а не исчезает после уведомления.
4. Сравнение редакций. Разница полей и правила источника для каждого значения. Зачем: Оператор решает конкретный конфликт, не перезаписывая карточку целиком.
5. Проверка результата. Ссылка на объект получателя и подтверждение применённой операции. Зачем: Зелёный статус означает проверенный бизнес-результат, а не только успешный HTTP-ответ.
6. История решений. Кто исправил данные, запустил повтор и проверил итог. Зачем: Восстановление остаётся объяснимым при смене оператора и разборе инцидента.

Что помогает пройти сценарий

Повтор с сохранённым результатом

Оператор запускает действие только после проверки исхода предыдущей попытки. Система использует тот же ключ операции; неизвестный результат не превращается в разрешение создать новый документ.

Владелец поля

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

Причина и следующий шаг

Сообщение об ошибке объясняет, нужен ли повтор, исправление данных или работа администратора. Если повтор опасен, кнопка недоступна и показано основание ограничения.

Корреляция объектов

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

Ключевые сценарии

Повторить без дубля

Потерян ответ системы учёта, но документ мог быть создан.

На входе: Событие создания документа завершилось тайм-аутом; оператор получил уведомление.

1. Открыть ключ операции и историю попыток.
2. Проверить наличие документа у получателя.
3. Вернуть найденный результат либо повторить с прежним ключом.
4. Сохранить подтверждение и ссылку на документ.

На выходе: Одному действию соответствует один проверенный документ.

Если что-то пошло не так: Если API не позволяет проверить исход, событие остаётся на ручной сверке; новый ключ автоматически не выдаётся.

Критерий приёмки: Повторный запрос не создаёт второй документ, а неопределённый исход виден оператору.

Разрешить конфликт адреса

Редакции CRM и учётной системы относятся к разным моментам.

На входе: После подготовки отправления пришло старое изменение адреса клиента.

1. Сравнить редакции и происхождение значений.
2. Проверить владельца адреса и состояние отгрузки.
3. Выбрать разрешённую коррекцию с основанием.
4. Отдельно подтвердить изменение в системе доставки.

На выходе: Исправлена конкретная редакция, решение и автор доступны в журнале.

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

Критерий приёмки: Старое событие не перезаписывает новый адрес, а решение не затрагивает финансовые поля.

Вернуть маршрут после сбоя

Внешний сервис был недоступен, накопились отложенные события.

На входе: Адаптер снова отвечает; очередь содержит повторы и операции по разным заказам.

1. Проверить работоспособность адаптера и права на восстановление.
2. Выделить безопасные события для ограниченной обработки.
3. Обработать их с сохранёнными ключами и контролем порядка.
4. Сверить результаты; спорные записи оставить в исключениях.

На выходе: Обмен возобновлён контролируемо, у каждой операции есть подтверждённый итог.

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

Критерий приёмки: Повтор и смена порядка воспроизводятся в испытании без дублей и потери новых редакций.

Роли пользователей

Оператор интеграций

Разобрать событие и безопасно возобновить обработку

Что уже выполнено и какое действие можно повторить?

Владелец данных

Разрешить конфликт редакций в своей области

Какой источник является правильным именно для этого поля?

Менеджер

Понять статус своего заказа без доступа к техническим секретам

Документ действительно создан или запрос только принят?

Администратор

Управлять адаптерами, правами и наблюдаемостью

Почему очередь растёт и какие маршруты сейчас затронуты?

Как устроено технически

Контракт и версии

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

Устойчивый журнал

События сначала сохраняются, затем передаются обработчикам. Для собственной системы применяется журнал исходящих операций; для внешних API способ фиксации определяется их контрактом. Гарантии не объявляются без проверки.

Адаптеры и ключи

Каждый адаптер переводит событие в конкретный API и проверяет результат. Идемпотентность реализуется через поддерживаемые ключи либо реестр и сверку объектов; одна очередь сама по себе не устраняет дубли.

Отказы и восстановление

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

Защита и наблюдаемость

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

Что входит в разработку

• Один согласованный маршрут заказа
• Реестр событий и ключей операций
• Адаптеры конкретных тестовых API
• Раздельные состояния приёма и применения
• Ограниченные повторные попытки
• Очередь исключений с владельцем
• Сравнение редакций и правила полей
• Ролевой доступ и аудит действий
• Сверка результата и эксплуатационные уведомления

План реализации

1. Карта данных: описываем сущности, владельцев полей и допустимые переходы. На примерах заказов фиксируем, что именно считается применением операции и как проверяется результат.
2. Контракт событий: согласуем идентификаторы, редакции, подписи и обработку повторов. Пробуем реальные ограничения API в тестовых средах до проектирования универсального коннектора.
3. Один маршрут: подключаем создание заказа, документ и передачу в доставку. Добавляем устойчивый журнал, очередь исключений и проверку результата операции.
4. Испытания отказов: воспроизводим задержку, повтор, смену порядка событий и потерю ответа. Оператор проходит сценарий восстановления с журналом своих решений.
5. Пилот и эксплуатация: сравниваем объекты между системами, назначаем ответственных за ошибки и пределы повторов. Новый маршрут включаем после проверки наблюдаемости и отката.

Что замеряем после запуска

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

Стек

TypeScript, Node.js, PostgreSQL, Очередь сообщений, REST API, OpenTelemetry.

Все кейсы · Услуга · Калькулятор стоимости

Визуализация продукта

Изображения созданы с помощью ИИ для демонстрационного проекта. Организации, люди и параметры вымышлены; это не скриншоты работающего клиентского продукта.