Мы с вами уже описали сценарий создания онлайн-заказа с последующей синхронизацией данных с бэкендом PetStore. Но он был описан без технических деталей.

Чтобы перейти к описанию технических деталей, необходимо понять, какие методы API PetStore нам потребуются для синхронизации данных.

Как я думаю, когда решаю задачу поиска методов, связанных с заказом:


1. Нужно создавать заказ.

Вижу в документации раздел store Access to Petstore orders (Доступ к заказам зоомагазина).

Метод создания POST. Из этого раздела явно подходит единственный - POST /store/order
(Place an order for a pet - Оформить заказ на домашнее животное)

Внутри метода смотрю, какие параметры данных нужны к передаче - тело запроса к body.
И встречаю ограничение со стороны API, а также новые требования к своему API.
Это тело запроса для создания заказа:
{
"id": 0,
"petId": 0,
"quantity": 0,
"shipDate": "2023-09-04T07:47:04.444Z",
"status": "placed",
"complete": true
}

Проблемы с параметрами: id, petId+quantity.


2. Решение проблемы id.

Чтобы понять, что это за id, который мне надо будет передавать, иду в самый низ документации Swagger. Там всегда есть описание объектов.

Плохая документация - есть тип данных для id (integer($int64)), но нет описания откуда его брать или как генерировать.

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

Дополнительно уточняю какие номера заказов уже заняты кассами, чтобы начать нумерацию не с 1, и не пересечься с кассовыми номерами заказов.


Продолжение 👇

3. Решение проблемы petId+quantity.

На стороне PetCo я могу сделать заказ сразу нескольких позиций (много животных и товаров в одном заказе), а на стороне API PetStore я не вижу массив в методе создания заказа. Я вижу возможность указывать только одно id животного petId в одном заказе и его количество quantity.

Например, можно одним запросом в API PetStore заказать 4 одинаковых морских свинки. А 4 морских свинки и 1 золотую рыбку уже нельзя.

Поэтому со стороны PetCo для создания одного заказа на несколько позиций мне нужно будет вызвать метод создания заказа в API PetStore несколько раз (на 4 разных позиции, вида животных, будет 4 вызова API). В БД PetCo придется установить связь между одним заказом внутри и неколькими связанными заказами во внешней системе.

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



Теперь кажется, что можно переходить к дополнению Use Case техническими деталями методами, данными, встроенными алгоритмами обработки и сопоставления данных. Но перед этим я рекомендую провести тестирование методов API. Так мы и поступим 😉

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

📅 Интеграции: пошаговый план работы на проекте
6 сентября, 19:00 МСК

Вариант 1:
1. Быть подписаным на канал @getanalyst на YouTube.
2. Поставить лайк на видео про требования.
3. Оставить комментарий под него 😄😂 или любой другой.

Вариант 2:
1. Быть подписаным на @getanalyst в Instagram (*запрещено в РФ).
2. Поставить лайк на видео про требования.
3. Поделиться им в своих Stories и прислать скрин в директ.

Итоги подведем в прямом эфире, так что будьте готовы стать полноценным участником практики 😉 До встречи!

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

Для интеграции с Backend-ом системы PetStore мы будем использовать REST API. API-документация PetStore опубликована через инструмент Swagger. И можно было бы ограничиться тем, чтобы проверить API в нем, но для понимания я хочу показать, что его также можно протестировать через Postman.

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

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

В видео-уроке:
1. Подход к тестированию в Postman.
2. Принцип тестирования PetStore в Swagger.
Проверяю метод, который необходим нам для сценария синхронизации заказов: POST /store/order (Place an order for a pet), и связанные с ним 💻

🟢 Изучили API-документацию. Методы API протестировали через Postman. Теперь можно детализировать Use Cases.

В приложенном файле представлен сценарий синхронизации заказа с внешней системой, дополненный алгоритмами и описанием взаимодействия между компонентами системы (приложение пользователя + бэкенд PetCo + бэкенд внешней системы PetStore).


Сейчас в нём:

1. Не хватает маппинга данных - сопоставления данных между системами и БД.
2. Можно добавить UML-диаграмму, чтобы показать сценарий работы.
3. Можно добавить еще альтернативные сценарии. Они есть.


Этот шаблон - часть описания требований к интеграциям систем 🙌

❗️Уже через 3 часа❗️

Практический вебинар с Екатериной Ананьевой!

📹 Интеграции: пошаговый план работы на проекте
⏰ 19:00 - 21:00 Мск

Ссылку на прямой эфир пришлем в канал за 15 минут до начала.

Вау. Вау. Вау! Это было круто и мы хотим это повторить!

Коллеги, вчера прошел практический вебинар
🧩 Интеграции: пошаговый план работы на проекте
и он был похож на что-то необыкновенное!

Я очень хочу поблагодарить коллег, кто был онлайн и работал со мной в пряом эфире, задавал вопросы через микрофон. Давайте все поставим ❤️ Катерине и Тиму в благодарность за активность!


О важном 👇

1. Я проводила этот вебинар с целью напомнить о старте потока по проектированию Интеграциий систем, но уже в понедельник мы поняли, что этот вебинар не нужен. Поток закрыт.
Почему я провела его ни смотря на перегрузку, с учетом конференции в понедельник и большого объема задач по текущим проектам?
Я обещала. Я сделала. И я счастлива, что еще один практический кейс у вас в копилке ❤️

2. Что будет в этот раз с повтором, и еще раз про то, почему я не публикую записи.
Коллеги, когда я создала GetAnalyst, я публиковала записи. Кому это было нужно? Никому. Откладывали на потом и никто не смотрел. Потом. Потом. Никогда. И зачем?
Я понимаю, что есть удобство по времени и среда 19Мск не всегда всем удобна. Но....
Благодаря текущему подходу с повторами вы онлайн и вы работаете в эфире. Вы задаете вопросы и я отвечаю сразу.
Про повтор: ждем сообщения от команды GetAnalyst здесь, на почте и на странице регистрации.


Я люблю GetAnalyst. Я хочу развивать наше сообщество. Но давайте хотя бы на минутку задумаемся.... Как много времени я дарю вам?

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

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

Всем крутого дня! Вернусь скоро с маппингом по сценарию с платежами 😊

Ставишь задачу разработчику, понимаешь, что она на интеграции, но не понимаешь что он делает? 🥲 Или уже ни раз задумывался, что без понимания деталей технического проектирования стоишь на месте в карьере и не чувствуешь развития? Работа с интеграциями – действительно сложная задача. Но решение любой сложной задачи всегда есть! ❤️

Не давайте трудностям с техническими навыками стать препятствием на вашем пути! 🌟

📅 Интеграции: пошаговый план работы на проекте
🔗 ЗАРЕГИСТРИРОВАТЬСЯ
*до 14 сентября 23:59Мск,
*посети повтор вебинара в удобное время.

Что предстоит узнать:
🌐 Основы работы с задачами на интеграции.
📝 Разработка требований к интеграционному сценарию с нуля.
🛠 Практика применения ключевых инструментов в реальных задачах: Confluence, Swagger, Postman.
⚠️ Ошибки, которые легко избежать, зная их заранее!

Регистрируйтесь, и получайте проект в копилку! 🚀

В среду обещала показать маппинг данных для дополнения нашей постановки задачи по интеграциям, чтобы вы на все 100% знали что должно быть итогом проектирования. Но прежде чем его делать, мне нужно спроектировать базу данных и интеграционный API-метод PetCo по созданию заказа.

Начну с проектирования модели БД. Так как только после ее разработки я смогу сделать API-метод для бэкенда PetCo. Смотреть буду только часть, связанную с оплатой заказа.
На основании требований к бизнес-процессу, который мы описали на практическом вебинаре.

Дублирую сценарий сюда 👇


Роли (бизнесовые)
Пользователь мобильного приложения или веб-приложения

Приложения и сервисы (компоненты системы - здесь интеграции)
Мобильное приложение / веб-приложения
Backend PetCo
Backend PetStore (кассовый)
Raif Pay - платежная система

Предусловие
Заказ сформирован и синхронизирован с PetStore.
Пользователь инициирует оплату заказа - нажимает кнопку оплаты.
Не обязательно, что пользователь авторизован, но мы обязаны до начала оплаты получить его контактные данные (email обязателен), и выбрать способ доставки.

Входные данные
+ ID заказа в системе PetCo.
+ Общая сумма по заказу к оплате.
+ В комментарий заказа Raif Pay - Состав заказа для каждого товара.
+ Реквизиты карты
+ срок жизни заказа.

Результат (основной)
Заказ оплачен. Зафиксировано время оплаты и изменен статус заказа в системах:
- PetCo.
- PetStore.
- Raif Pay.
Клиенту направлен email и отображен успешный экран платежа в приложении.

Основной сценарий
1. После перехода к оплате мобильное / веб- приложение передает информацию об оплате в Backend PetСo.Вызывается интеграционный метод PetCoPOST /order/{orderId}/payment - создать платеж в PetCo.

Продолжение 👇

2. Backend PetСo передает информацию о платеже в Raif Pay. Уточнить метод API Raif API (он готовы, его встраиваем в АПИ PetCo)

3. В Raif Pay пользователь вводит данные карты, получает СМС (необязательно, зависит от банка) и вводит код из нее.Raif Pay проводит списание денежных средств со счета и фиксирует успешную оплату. Пользователь получает сообщение от Raif Pay об успешной оплате.

4. Raif Pay передает информацию об успешной оплате в backend PetCo.

5. Backend PetCo меняет статус заказа в своей основной БД.

6. Backend PetCo:
- передает информацию об успешной оплате в мобильное / веб- приложение.
- синхронизирует статус заказа в Backend PetStore.

7. Пользователь получает подтверждение о том, что заказ оплачен:
- на email,
- на экране приложения.



Теперь можно переходить к сущностям БД 👇

Исходя из описанного нами сценария оплаты заказа, можно выделить следующие сущности (таблицы) для базы данных PetCo:

Пользователь (user)
- ID пользователя
- Email
- Контактные данные (адрес, номер телефона и т.д., если есть)
- История заказов

Товар (product)
- ID товара
- Наименование товара
- Объем (если применимо, например, 200 мл)
- Цена
- Количество на складе

Заказ (order)
- ID заказа
- ID пользователя (внешний ключ к таблице Пользователь)
- Дата и время создания заказа
- Общая сумма заказа
- Статус заказа (например, создан, оплачен, отменен и т.д.)
- Срок жизни заказа
- Комментарий

Заказанный товар (ordered_product)
- ID заказанного товара
- ID заказа (внешний ключ к таблице Заказ)
- ID товара (внешний ключ к таблице Товар)
- Количество заказанного товара
- Цена товара на момент заказа (если цена может меняться со временем)

Платеж (Payment)
- ID платежа в PetCo
- Ссылка на страницу платежа
- ID заказа (внешний ключ к таблице Заказ)
- Дата и время платежа
- Статус платежа (например, в обработке, успешный, отклоненный)
- Платежная система (пока только Raif Pay)
- Сообщение/код ответа от платежной системы
- Способ оплаты (СБП, карта)


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

К посту на всякий случай прикрепила картинку с напоминанием об уровнях представления модели БД. Я описала список таблиц на логическом уровне проектирования.

Первый шаг в сторону описания маппинга данных сделан 😉

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

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

13 сентября нас ждет первый практический вебинар, все напоминания уже заготовлены в нашем чате 😉

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

Собираем силы, отдыхаем в выходные и... до встречи оналайн!

Маппинг - сопоставление данных. Что и с чем сопоставлять? 🔑

Есть несколько компонентов системы PetCo, которые участвуют в сценарии оплаты заказа:
✔️ Мобильное приложение / веб-приложения,
✔️ Backend PetCo,
✔️ Backend PetStore (кассовый),
✔️ Raif Pay - платежная система.

Данные, которые надо сопоставлять (маппить) для постановок задач:
🟠 Мобильное приложение / веб-приложения:
на UI.
🟠 Backend PetCo:
в БД сервера,
и в интеграционном методе API, к которому обращаются мобильное или веб-приложение:
🟠 Backend PetStore (кассовый)
в API внешней системы PetStore, БД для нас закрыта.
🟠 Raif Pay - платежная система:
в API внешней системы Raif Pay, БД для нас закрыта.

Когда и в каких случаях рекомендуется описывать маппинг:
🟢 Для задачи на мобильное или веб-приложение:
Маппинг между API PetCo и UI.
🟢 Для задачи на интеграционный API PetCo c Raif Pay:
Маппинг между API PetCo, БД PetCo и API Raif Pay.
🟢 Для задачи на интеграционный API PetCo c PetStore (смена статуса заказа в PetStore на оплаченный:
Маппинг между API PetCo, БД PetCo и API PetStore.

Это три отдельные таблицы маппинга данных, для трех разных постановок задач в рамках интеграции систем. Теперь надо пример 👇

Проектирование интеграционного метода для получения статуса заказа через RaifPay 💻

🧩 Для получения статуса заказа после его создания подходит метод GET https://pay-test.raif.ru/api/payment/v1/orders/{orderId}, который возвращает полную информацию о заказе по идентификатору.

🧩 GET https://pay-test.raif.ru/api/payment/v1/orders/{orderId}
path Parameters:
+ orderId
header Parameters:
+ Authorization (Bearer secretKey)

Ответ (успешный):
{
"amount": 12500.5,
"comment": "Покупка кота",
"status": {
"value": "NEW",
"date": "2019-08-24T14:15:22+03:00"
},
"expirationDate": "2019-08-24T14:15:22+03:00"
}




Мобильному и веб-приложению не рекомендуется обращаться напрямую к API Raif Pay, т.к. запрос подписывается секретным ключом Bearer secretKey - общий для всех запросов ото всех пользователей в Raif Pay. Хранить его в мобильном приложении или получать с сервера для использования в запросах к RaifPay с клиента опасно. Есть риск его утери и использования в целях мошенничества.
С целью безопасности, интеграция систем PetCo и Raif Pay реализуется через бэкенд-приложение PetCo.



🟢 Для реализации этой интеграции необходимо разработать интеграционный API-метод в PetCo.

На вход методу предаются: id заказа в PetCo, авторизация пользователя PetCo (при наличии).
Результат вызова метода: сведения об актуальном статусе заказа в Raif Pay, получаемые в систему PetCo. Если статус в Raif Pay обновляется, то его необходимо синхронизировать с PetCo и перезаписать в БД PetCo. Вернуть пользователю API PetCo актуальный статус.

🟢 Дизайн метода REST API предлагается сделать так:
GET ..../order/{orderId}
path Parameters:
+ orderId
header:
+ Authorization (при наличии)

Ответ (успешный):
{
"id": "id в PetCo",
"number": 23245,
"externalId": "...",
"userId": "...",
"amount": 12500.5,
"comment": "Покупка кота",
"status": "NEW",
"date": "2019-08-24T14:15:22+03:00",
"expirationDate": "2019-08-24T14:15:22+03:00",
"products":
[ { "id": ...., "name": ... }, { "id": ...., "name": ... } ]
}