Микросервис коммуникаций (ecos-ecom)
ecos-ecom (ECommunications) — микросервис обработки входящей электронной почты и интеграции коммуникаций с объектами Citeck. Он создаёт лиды CRM и заявки Service Desk из писем, добавляет почтовые активности к документам и обрабатывает ответы на задачи согласования договоров.
Дополнительно микросервис предоставляет операции объединения лидов и сделок CRM, а также фоновую синхронизацию источников обращений с Яндекс Метрикой. Идентификатор приложения в API платформы — ecom.
Назначение и основные возможности
Возможность |
Результат обработки |
|---|---|
Входящая почта CRM |
Создание лида по письму или заполненной форме сайта; добавление письма к существующей записи по идентификатору из темы. |
Входящая почта Service Desk |
Создание заявки от найденного заказчика и инициатора либо добавление комментария к существующей заявке. Сохранение вложений и встроенных изображений. |
Почтовые активности |
Добавление активности «Письмо» к объекту, определённому по метке в теме письма и настройкам типа данных. |
Ответы по согласованию договоров |
Завершение доступной отправителю задачи с указанным вердиктом, добавление комментария и обновление содержимого документа из вложения. |
Объединение записей CRM |
Перенос данных и связанных записей из одного лида или сделки в основную запись. |
Источники обращений CRM |
Определение источника обращения лида по идентификатору посетителя Яндекс Метрики. |
Отправка уведомлений платформы описана в разделе Уведомления.
Примечание
В текущей реализации Telegram-маршруты заказа пропусков и соответствующие зависимости отключены в исходном коде. Наличие настройки telegram-oap-authtoken само по себе не включает чат-бота.
Принцип работы
Микросервис реализован как Spring Boot-приложение. Для чтения почты и маршрутизации сообщений используется Apache Camel, для работы с объектами платформы — Records API.
Почтовые маршруты выполняют следующие действия:
Опрашивают настроенный почтовый ящик по IMAP или IMAPS.
Извлекают отправителя, тему, дату, тело письма и вложения.
Определяют сценарий обработки: создание записи, ответ на существующую заявку, почтовая активность или результат согласования.
Создают или изменяют записи в
ecos-model, сохраняют файлы через API контента платформы, при необходимости завершают задачу процесса.
Обработка писем CRM и почтовых активностей выполняется в системном контексте. Для Service Desk создание заявки и комментария выполняется от имени найденного пользователя. Ответ на согласование также обрабатывается от имени отправителя, определённого по email: учитываются доступные ему задачи и вердикты.
Подключение микросервиса
Запустите приложение ecom в лаунчере Citeck или включите ecos-ecom в используемую конфигурацию развёртывания платформы.
В базовое окружение входят ZooKeeper, RabbitMQ, ecos-registry и ecos-model. Для работы конкретных сценариев должны быть развёрнуты соответствующие модули и их артефакты:
CRM — типы лидов и сделок, справочники источников и категорий обращений;
Service Desk — тип заявки, заказчики, пользователи и настройки обработки заявок;
ecos-process — выполнение задач согласования и работа со связанными процессами;
файловое хранилище платформы — сохранение вложений.
Порт HTTP по умолчанию — 8686 (свойство server.port). При обращении к операциям микросервиса через Records API используется имя приложения ecom.
Настройка почтовых ящиков
Почтовые подключения задаются в журнале «Конфигурация ECOS» настройками приложения ecom:
Идентификатор |
Назначение |
|---|---|
|
Ящик для обработки писем CRM. |
|
Ящик для создания заявок Service Desk и получения ответов по ним. |
|
Ящик для добавления писем в активности объектов. |
|
Ящик для ответов на задачи согласования договоров в формате Sm Contract. |
По умолчанию все четыре настройки имеют значение disabled — соответствующие маршруты не запускаются.
Для включения маршрута укажите URI подключения. Например:
imaps://imap.example.org?username=support@example.org&password=CHANGE_ME&delete=false&unseen=true&delay=30000
Параметры примера:
Параметр |
Назначение |
|---|---|
|
Учётные данные почтового ящика. |
|
Обработанные письма остаются в ящике и помечаются прочитанными. |
|
Обрабатываются непрочитанные письма. |
|
Интервал опроса ящика в миллисекундах; в примере — 30 секунд. |
Важно
После изменения URI, в том числе при переключении между disabled и рабочим подключением, перезапустите ecom. Изменение настройки не пересоздаёт уже настроенный Camel-маршрут автоматически.
Для сценариев CRM и общих почтовых активностей рекомендуется использовать разные почтовые ящики. Подробные настройки модулей приведены в разделах CRM, почтовых активностей и Service Desk.
Сценарии обработки почты
CRM
Маршрут CRM различает обращения с форм сайта, обычные письма и письма с идентификатором существующей записи.
Форма сайта. По теме и служебным данным определяется вид обращения. Из тела извлекаются компания, контактные данные, количество пользователей, страница обращения и идентификаторы аналитики. При наличии компании выполняется поиск контрагента по полному наименованию.
Обычное письмо. Создаётся лид с контактными данными отправителя. Название определяется именем отправителя, при его отсутствии — адресом email. Тема включается в описание вместе с текстом письма.
Письмо с номером. По шаблону
mail.lead.pattern.dealNumberиз темы извлекается номер и ищется существующий лид по атрибутуnumber. По умолчанию шаблон распознаёт текст послеСделка #. Письмо добавляется как активность к найденной записи.
Новые лиды создаются в рабочем пространстве crm-workspace со статусом new. Письма с вложениями дополнительно сохраняются как почтовые активности с файлами. Ответы и пересылки без найденного номера обрабатываются как обычные письма, чтобы процитированные данные формы не подменяли данные отправителя.
Service Desk
Для нового письма микросервис определяет заказчика по домену отправителя и ищет пользователя по email среди пользователей и групп заказчика. Если совпадение не найдено, может использоваться заказчик из настройки app/service-desk$default-client, при условии что его домен подходит отправителю. Если заказчик или пользователь не определены, письмо пропускается.
В заявку сохраняются тема, обработанное тело письма, автор, инициатор, заказчик, дата письма и вложения. Приоритет по умолчанию — «Средний». Если тема содержит тег из настройки app/service-desk$critical-tags, устанавливается «Срочный» приоритет. Теги перечисляются через запятую, проверка выполняется без учёта регистра.
Ответ распознаётся по точному префиксу темы Re: (SD-, например Re: (SD-123) Ошибка при входе. По номеру в скобках находится заявка, к которой добавляется комментарий. Поиск заказчика и отправителя выполняется и для ответов. Если заявка не найдена, ответ пропускается.
Для тела письма сохраняется поддерживаемое форматирование. Вложения добавляются к документам заявки и комментарию, а ссылки cid:... на встроенные изображения заменяются ссылками на сохранённые файлы. Подробно см. Создание заявки из письма.
Почтовые активности
Маршрут mail-inbox-activity ищет в конце темы метку вида (alias: value). Например, для типа с alias deal и поиском по номеру можно использовать тему Обсуждение предложения (deal: 123).
Тип объекта определяется по параметру alias аспекта «Имеет активности», а атрибут поиска — по параметру searchAtt. Найденному объекту добавляется запись типа email-activity с датой и телом письма; вложения сохраняются в документах объекта и включаются в активность.
Письмо без подходящей метки или типа с указанным alias пропускается. Если объект по метке не найден, обработчик сообщает об ошибке поиска записи.
Согласование договоров (Sm Contract)
Маршрут mail-inbox-sm-contract обрабатывает специально сформированные ответы на задачи. Тема содержит три части, разделённые символом #:
идентификатор_документа#ключ_задачи#идентификатор_вердикта
Отправитель определяется по email пользователя Citeck. Для него ищется активная задача документа с указанным ключом и проверяется доступность вердикта. После успешного завершения задачи добавляется комментарий из предусмотренного шаблоном блока письма. Если приложен файл, первое вложение используется для обновления содержимого документа.
Объединение лидов и сделок
Микросервис предоставляет операции Records API:
Источник операции |
Назначение |
|---|---|
|
Объединить лиды. |
|
Объединить сделки. |
В атрибутах запроса передаются mergeFrom — ссылка на исходную запись и mergeIn — ссылка на основную запись. Объединение записи с самой собой и пустая целевая ссылка не допускаются.
Пустые поддерживаемые поля основной записи заполняются данными исходной. Переносятся комментарии, активности и поручения; в основную запись добавляется комментарий с результатом объединения. Для лидов дополнительно объединяются контакты, для сделок — связи с заказами и платежами. После объединения исходная запись удаляется.
Пользовательские действия объединения описаны в разделе CRM.
Синхронизация с Яндекс Метрикой
Фоновое задание LeadSyncRequestSourceJob заполняет requestSource у лидов, для которых источник ещё не указан, но заполнен ym_client_id.
Для работы необходим endpoint yandex-metrika-api с URL API Метрики и секретом с OAuth-токеном. По идентификатору посетителя определяется первый источник перехода, затем выбирается соответствующая запись справочника источников обращений CRM.
Если полученный источник отсутствует в справочнике, используется other. Если источник не удалось определить за четыре попытки, устанавливается unknown. При отсутствии настроенного endpoint или его учётных данных задание завершает текущий запуск без синхронизации.
Параметры приложения
Помимо конфигураций почтовых ящиков, в application.yml используются следующие свойства:
Свойство |
Назначение и значение по умолчанию |
|---|---|
|
HTTP-порт приложения: |
|
Темы обращений с сайта: консультация, демонстрация, запрос стоимости и другие категории. |
|
Регулярные выражения для извлечения данных из писем CRM и номера существующей записи. |
|
Шаблон метки |
|
Расписание синхронизации источников с Метрикой: |
|
Глубина поиска визитов в Метрике в годах до даты получения обращения: |
Разработка и диагностика
Исходный код приложения расположен в репозитории ecos-ecom. Точка входа — ru.citeck.ecos.ecom.EComApplication. Версия JDK задаётся файлом .java-version; в проверенной реализации используется JDK 25.
Запуск для разработки из каталога репозитория:
./mvnw spring-boot:run
Запуск тестов:
./mvnw clean test
В Windows используется mvnw.cmd. Параметры почтовых ящиков и доступ к инфраструктуре задаются в окружении развёрнутой платформы.
При диагностике обработки писем проверьте:
значение нужного
mail-inbox-*и перезапуск приложения после его изменения;доступность почтового сервера и корректность учётных данных;
для Service Desk — домен заказчика, email пользователя и формат темы ответа;
для активностей — alias типа,
searchAttи наличие искомой записи;для Метрики — endpoint, OAuth-токен и идентификатор
ym_client_idу лида.
В логах обработчиков фиксируются причины пропуска письма, отсутствие пользователя или записи, а также ошибки сохранения вложений. Для подробной диагностики можно включить уровень DEBUG для пакета ru.citeck.ecos.ecom.