⭐️ Интеграционный Use Case: разбираемся на примере интеграции с #KudaGoAPI и #DashaMailAPI ⭐️

Интеграционный Use Case отличается от обычного тем, что он содержит технические детали:
+ вызовы API,
+ сохранение данных в БД,
+ обмен данными между микросервисами через брокеры,
+ и другие.

То есть всё то, что помогает понять, как "перетекают" данные в ходе работы системы.

Разбираемся подробнее на примере для #CityGA, где у нас UI в процессе работы вообще отсутствует 😱


📌 Use Case:
+ Автоматическая рассылка событий по расписанию

👉 Приложения и системы:
+ Backend CityGA
+ Kafka Broker

👉 Внешние системы:
+ KudaGo API
+ DashaMail API

👉 Предусловия:
+ Для каждого города задан часовой пояс
+ В CityGA сохранены предпочтения пользователей по категориям и выбран город
+ В DashaMail заранее созданы адресные списки под каждую группу категорий
+ В Kafka создан топики notifications.email.events для получения сообщений о необходимости запуска рассылки


👉 Основной сценарий:

1. Для каждого поддерживаемого города в системе еженедельно, по средам, в 10:00 его часового пояса, срабатывает планировщик задач в Backend.

2. Backend рассчитывает окно предстоящей недели - с чт по ср.
Пример:
Сегодня 17 сентября 2025 (ср).
Плановое окно для выбора новых мероприятий:
18.09.2025 00:00 → .24.09.2025 23:59:59 (GMT+3).
Для KudaGo это Unix-секунды:
actual_since=1758178800,
actual_until=1758783599.


3. Выполняется первичный запрос по событиям в выбранном городе на указанный период, без фильтра по категориям, в API KudaGo:

GET /public-api/v1.4/events

+ Получаем до 10 записей за один запрос от KudaGo
+ Использовать порядок сортировки favorites_count при получении данных от KudaGo
+ Исключать события «всегда доступно»/«без времени» - фильтрация на стороне CityGA

3.1. Сформировать сообщение в топик Kafka notifications.email.events для отправки рассылки, со списком из 10 полученных событий от KudaGo и с id листа подписчиков на город, у которых не настроены фильтры по категориям.


4. Далее повторять запрос по событиям в выбранном городе на указанный период, через API KudaGo, с фильтрами по категориям.

GET /public-api/v1.4/events

Например:
+ у одной группы пользователей в избранном только бизнес-события, выполнить запрос только с фильтром по этой категории на 10 записей;
+ у другой группы пользователей в избранном бизнес-события и детские мероприятия, выполнить запрос только с фильтром по этим двум категориям на 10 записей;
и т.д.

4.1. По каждому уникальному набору фильтров формировать сообщение в топик Kafka notifications.email.events для отправки рассылки, со списком из 10 полученных событий от KudaGo и с id листа подписчиков.

Повторять 4 и 4.1 для всех уникальных наборов категорий у пользователей в городе.

-------

5. Сервис Уведомлений последовательно читает сообщения из брокера Kafka.

5.1. После считывания очередного сообщения Сервис Уведомлений формирует HTML шаблон письма для рассылки.

5.2. Сервис Уведомлений вызывает API DashaMail для создания и отправки рассылки, передавая на вход созданный HTML-шаблон, id листа контактов из DashaMail и другие параметры (см. маппинг), метод:

campaigns.create

5.3. Сервис Уведомлений логирует вызов метода внешней системы.

-------


👉 Альтернативные сценарии и дополнительные детали
Всё будет, но не сейчас.
Оформим в Confluence 😎


Это первый подход к описанию логики работы системы.
Use Case ещё будет доработан.


📌 Вопросы,которые остаются после первого подхода к написанию интеграционного Use Case:
А. Есть ли у вас предложения по улучшению логики работы (алгоритма)?
Б. Должны ли мы что-то в процессе работы сохранить в БД?
В. Дейстительно ли метод campaigns.create сразу создает и отправляет рассылку? Нужны дополнительные действия?
Г. Можем ли мы фильтровать события «всегда доступно»/«без времени» на стороне KudaGo?
Д. Откуда мы получаем комбинации категорий?

Это то, что сейчас точно упущено в Use Case.

Рассуждайте, пробуйте отвечать на мои вопросы и задавайте свои в комментариях 🙌 Будем улучшать его вместе!


#ИнтеграцииGA

⭐️ Шаблон задачи на Интеграцию для Confluence:
📌 Пример интеграции Kafka + Backend + БД + Внешняя система ⭐️

В этом месяце мы разбираем интеграционный процесс в системе #CityGA:

автоматическая рассылка мероприятий для города, получаемых из #KudaGoAPI, с отправкой email пользователям через #DashaMailAPI.

Прежде чем поставить задачу на интеграцию, мы:
✅ Описали архитектуру в C4
✅ Изучили API-документацию внешних систем
✅ Выполнили исследовательское тестирование API в Postman
✅ Сделали черновой Use Case по процессу
✅ Показали процесс на UML-диаграмме


❗️ Несмотря на то, что в Use Case рассылка email и сбор данных были объединены, на самом деле это два разных процесса и две разных задачи на разработку.

Почему?
Kafka используется, чтобы вынести отправку email в отдельный асинхронный поток. Основная джоба перебирает связки город + категории и готовит данные, а затем отправляет их в Kafka. Уже после этого сервис уведомлений независимо обрабатывает события (сообщения) и рассылает письма.

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



⭐️ Подготовила для вас заполненный шаблон постановки задачи на интеграцию с внешней системой KudaGo и внутренней интеграцией с Kafka.

Внутри:
▫️ общее описание процесса
▫️ схема архитектуры в C4 — только часть, относящаяся к автоматизации этого процесса
▫️ детальный технический Use Case с альтернативными сценариями
▫️ пример JSON-сообщения для Kafka
▫️ UML Sequence для описанного Use Case с исходным кодом для PlantUML
▫️ маппинги данных: БД–Kafka–API KudaGo
▫️ требования к логированию.



🔖 Cохраняйте образец требований на интеграцию в личный архив. Примеры всегда полезны 😉

#ИнтеграцииGA

🧩 Маппинг в интеграциях - что это и зачем 🧩

Маппинг - это процесс сопоставления полей (данных) из одной системы с соответствующими полями в другой системе.
Это нужно, так как разные системы могут описывать один и тот же объект данных по-разному.

➡️ Этот процесс всегда необходим в задачах на интеграции.



Маппинг описывают в виде таблицы.
Допустимо делать и в виде структурированного списка, но по опыту - таблицы удобнее.

➡️ В таблице с маппингом делают несколько основных колонок:

▫️ название параметра на разговорном языке;
▫️ описание, требования к валидации, ФЛК (форматно-логический контроль) и преобразованиям, если это необходимо;
▫️ названия параметра в API каждой системы (например, поле из JSON, поле из xml или другого формата сообщения, query из URL и др);
▫️ название параметра в БД системы, если она есть в описании Use Case.
▫️ типы данных в каждой системе / БД.

Допустима вариативность с колонками.
Их может быть больше, а может быть и меньше.


Для задачи #CityGA в примере постановки задачи есть два маппинга:

👉 1. БД CityGA - API KudaGo
При запросе данных из KudaGo необходимо брать часть параметров из БД и подставлять в #KudaGoAPI.

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

👉 2. БД CityGA - API KudaGo - Kafka (json)
🖼 На картинке к посту показала наглядно
После получения ответа от #KudaGoAPI, формируется сообщение для Kafka, на основе которого сервис уведомлений затем будет делать рассылку.

Видно, что данные в JSON-ответе от #KudaGoAPI расходятся с JSON-сообщением для Kafka. Часть данных в сообщении Kafka из БД CityGA.

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



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

Это обязательная часть требований в задачах на интеграции 🙌

#ИнтеграцииGA