Проект на Интеграцию: приложение курьерской службы ShipEasyGA

О проекте:

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

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

Требования:

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

Структурирование адреса - это разделение строки на отдельные поля:
✔️ индекс
✔️ страна
✔️ регион / область / др
✔️ город / поселок / др
✔️ улица
✔️ дом
✔️ корпус
✔️ квартира

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

Есть возможность делать доставку “от” и “до” специальных пунктов обслуживания клиентов ShipEasyGA.

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

Сценарии:

1А. Пользователь может ввести адрес в одну строку. В этом случае приложение ShipEasyGA должно автоматически структурировать адрес и предлагать проверить и исправить его, при необходимости.

1B. В мобильном приложении предлагать заполнить адрес отправления по текущим геокоординатам пользователя, автоматически.  

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

Дополнительно:

Исследовать возможности подключения Искусственного Интеллекта, чтобы сделать виртуального помощника на форме оформления заказа.  
Буду последовательно разбирать решение задач в канале весь сентябрь: исследование и тестирование API, интеграционный Use Case, UML, анализ БД и маппинг данных 🍁

Use Case: обычный и технический сценарии работы системы

Use Case - это сценарий использования системы.  

Его можно описывать на верхнем уровне, не вдаваясь в технические подробности. То есть просто описать процесс работы пользователя с интерфейсом (UI).

Пример обычного Use Case (интеграций во внешние системы нет):

1. Пользователь через главное меню заходит в просмотр информации о своем профиле и переходит к его настройке.  

2. Пользователь может поменять фамилию, имя или дату рождения.  

3. Пользователь сохраняет изменения.  

4. Перед сохранением система проверяет корректность введенных данных: - дата рождения в формате ДД.ММ.ГГГГ - фамилия / имя содержит только русские или английские буквы, а также пробелы, до 128 символов.  

5. Если проверки пройдены успешно, система сохраняет результат и пользователь возвращается на экран просмотра информации о профиле.

А можно дополнять Use Case вызовами API-методов, обращениями к таблицам БД. Тогда он становится более техническим и более похожим на результат работы системного аналитика.

Пример более технического Use Case (интеграций во внешние системы нет, только Frontend-Backend):

1. Пользователь через главное меню заходит в просмотр информации о своем профиле и переходит к его настройке.
Данные получают методом GET /api/v1/profile.
Запрос подписан авторизацией пользователя.  

2. Пользователь может поменять фамилию, имя или дату рождения.  

3. Пользователь сохраняет изменения.  

4. Перед сохранением на UI проверяется корректность введенных данных: - дата рождения в формате ДД.ММ.ГГГГ - фамилия / имя содержит только русские или английские буквы, а также пробелы, до 128 символов.  

5. Если проверки пройдены успешно, система выполняет запрос к серверу для сохранения данных: PUT /api/v1/profile/update
Запрос подписан авторизацией пользователя.

6. Сервер принимает данные и повторно проверяет корректность введенных данных, а также, что дата рождения пользователя не ранее 1900 года.

7. Если проверки пройдены успешно, то сервер сохраняет результаты в БД, в таблице user и возвращает успешный ответ на UI.

8. Пользователь возвращается на экран просмотра информации о своём профиле.

Если мы работаем с задачами на интеграции, важно показать как взаимодействуют Frontend и Backend, наш сервер и внешние системы по API. Упоминание методов API в таких интеграционных Use Case просто необходимы, чтобы передать полноценную постановку задачи на разработчика.

Но прежде чем описывать интеграционные Use Case, всегда важно понять, как будет вести себя наш UI. И как он вообще будет выглядеть. С этого я начинаю работу с любой задачей, не только на интеграции.

Как будет работать форма заказа курьерской службы ShipEasyGA, а именно - настройка адреса на ней? Разберемся далее 👇

Пример Use Case без технических деталей - начало работы с задачей на интеграцию

В проекте ShipEasyGA нужно подключить внешнюю систему DaData (т.е. сделать интеграцию), которая будет помогать структурировать “а-бы как” введенные адреса по отдельным полям ввода.

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

Поэтому изначально Use Case для работы с адресами будет выглядеть так:

Пользователи и системы:

+ Пользователь
+ Веб-приложение / iOS / Android

Предусловие:

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

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

1. Выбор страны:

1.1. Пользователь должен выбрать страну из справочника. По умолчанию выбрана “Россия”.  

1.2. Для выбора страны пользователь нажимает на поле ввода.  Отображается выпадающий список стран по алфавиту. Россия всегда вверху списка, если не введено ни одной буквы. В списке одновременно отображаются 5 записей, доступна прокрутка.  

1.3. Пользователь может начать ввод букв по одной в поле ввода.  При вводе каждой буквы список стран фильтруется и отображаются только те, в название которых входит введенная пользователем строка (поиск по вхождению подстроки в строку).  

1.4. После выбора страны из списка значение в поле обновляется. Если пользователь не выбрал страну из списка и снимает выделение с поля, то оставить в нем введенные буквы, подсветить его “красным” и сделать снизу подсказку “Страна не выбрана”. Поля ввода адреса блокировать до выбора страны из справочника.

2. Пользователь вводит Полный адрес.

2.1. При вводе 10 и более символов отображается выпадающий список с подсказками адреса.  🧩 Подсказки берутся из внешней системы DaData.  

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

2.3. Пользователь может выбрать адрес из списка подсказок. В этом случае остальные поля ввода для адреса (город, улица, дом, корпус, квартира, индекс) будут заполнены автоматически на основе выбранной подсказки.  

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

4. Пользователь продолжает ввод остальных полей на форме для Отправителя и Получателя.

5. По завершении ввода пользователь оформляет заказ курьерской службы.

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

Технических деталей с вызовом API-метолов в этом Use Case нет. Хотя он детально описывает работу экрана.  

А значит нам еще есть над чем работать, чтобы сделать постановку задачу на интеграцию нашего приложения ShipEasyGA с DaData для структурирования адресов.

Использование Backend ShipEasyGA для вызова API DaData

В данном варианте все клиентские приложения (iOS, Android, Web) взаимодействуют с внешним API DaData через Backend.  

1. Клиент отправляет запрос Backend

2. Backend принимает запрос и перенаправляет его на API DaData, подставляя в него секретные ключи (пароли, токены и тп)  

✅ Безопасность
✅ Централизованная логика и обработка ошибок
✅ Кэширование и оптимизация
❌ Дополнительная нагрузка на Backend
❌ Увеличение времени отклика  

Большинство крупных систем (например, банковские приложения, e-commerce платформы) используют именно этот подход для работы с внешними сервисами. Это связано с тем, что он обеспечивает максимальный контроль и безопасность.

Прямой вызов API DaData с Frontend

В данном варианте все клиентские приложения (iOS, Android, Web) взаимодействуют с внешним API DaData без слоя-посредника.  

Клиент отправляет запрос Backend на API DaData, подставляя в него секретные ключи (пароли, токены и тп).  

❌ Безопасность
❌ Централизованная логика и обработка ошибок
❌ Кэширование и оптимизация
✅ Меньшая нагрузка на backend
✅ Меньшая задержка  

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

Заключение:

Для системы ShipEasyGA более оптимальным решением будет использование Backend для взаимодействия с DaData (вариант 1). Это обеспечит большую безопасность и централизованную обработку логики.  

Прямые вызовы с Frontend (вариант 2) могут быть уместны только в очень простых сценариях, но они увеличивают риски безопасности и сложности в управлении.

Подробнее и с пояснениями по каждому пункт разобрала вопрос в мини-книге.