👉 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, а именно - настройка адреса на ней? Разберемся далее 👇

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

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

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

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

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


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


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


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

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

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

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

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

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


#ИнтеграцииGA
Продолжение 👇

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

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

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

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

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

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

Часть полей структурированного адреса может остаться незаполненной.

3. Пользователь проверяет структурированный адрес.

Если необходимо, то он вносит правки в него.
При внесении правок строка с полным адресом должна обновляться при завершении редактирования каждого поля - снятия с него выделения.

Выбор региона/области из справочник: поведение аналогично полю выбора страны.
В выпадающем списке отображаются только регионы страны.

Выбор города из справочник: поведение аналогично полю выбора страны.
В выпадающем списке отображаются только города региона.
Если регион не выбран, то поиск ведется среди всех городов и при выборе города регион должен быть заполнен автоматически.

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

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

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

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

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


P.S. И конечно можно еще поработать над альтернативными сценариямии обработкой ошибок! Их будет больше! Можно сразу предлагать в комментариях


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

🚀 Открыта предзапись на Интеграции 🎓

Интеграции - один из самых востребованных навыков для системных аналитиков. Каждая третья вакансия на hh.ru требует знаний и опыта в интеграциях, особенно в ведущих ИТ-компаниях рынка и в продуктовых компаниях.

В программе Интеграции систем мы на практике разбираем все детали проектирования: от анализа API-документации до создания структуры требований и постановок задач на разработчиков.

🗓 Старт предобучения: 25 сентября 2024

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

🎁 До 19 сентября: дополнительное обучение по БД в подарок + самые выгодные условия.

Хотите узнать больше? Пишите @getanalyst или заполняйте анкету предзаписи на сайте. Мы поможем оценить ваши текущие навыки, пришлем дополнительную информацию и ответим на все вопросы!

🧐 Каким способом делать вызов API DaData? 🧐

В приложении курьерской службы #ShipEasyGA для структурирования адресов должен использоваться внешний сервис DaData. Его надо вызывать по API.


Как делать эти вызовы?

1 (👌) Использовать слой Backend ShipEasyGA, который будет обращаться к API DaData.

2 (👍) Напрямую вызывать API DaData с Frontend-ов.


Голосуем реакцией 👌/👍 под постом. Пишем в комментарии какой вариант выглядит лучше и почему.

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

😰 Осторожно - мошенники 😰

Коллеги, привет! Хочу поделиться двумя схемами, которыми сейчас пользуются мошенники для удаленщиков и ИТ-специалистов.


🎭 Утечка персональных данных с предыдущего места работы

Несколько месяцев назад мне написал «бывший руководитель» в TG, без номера, как новый контакт.

Разговор начался с “как дела”, а потом он сообщил, что произошла утечка моих перс данных.

Я начала переживать. Спасибо, что сказали. Но.. Почему мне об этом пишет руководитель, вместо отдела кадров?

Хотела перевести на английский и показать подруге. Вставляю текст в Google Translate. И... (смотрите скрин)

После моего вопроса “руководителю” контакт самоудалился 💨 А я успела снять скрин, чтобы задать вопрос в HR.

Позже узнала, что не одна я такое получала. Другие люди, другие компании - аналогичная история.

Что хотели? Не знаю.


🎭 “Вы приняты на работу! Мы отправим вам чек на 2000$ для покупки оборудования”

Тут больше про США, история знакомого программиста.

1. Вам проводят онлайн собеседование.

2. Через 1-2 дня дают оффер. Вы радуетесь.

3. Работодатель сразу предлагает прислать вам чек на ~2000$, чтобы вы положили его на свой банковский аккаунт и купили оборудование для работы.

P.S.
Здесь есть чеки, которые можно класть на счет в банке.
Деньги на баланс зачисляются сразу, НО! Если чек был недействителен, то это будет обнаружено только через 1-2 рабочих дня. И получается, что сначала вам на баланс придёт +2000$, а потом их с вас спишут и наложат штраф за фальшивый чек (без комментариев на эту тему, сама в шоке).

4. Вы кладете чек на свой банковский счет, а далее:
- Вам говорят, что дали лишние 1000$ и просят вернуть онлайн-переводом
- Вы идете на “специальный сайт” покупать оборудование

Знакомый сразу понял, что тут нечисто. Полез в гугл искать больше информации про компанию и “is it normal for a company to send you a check to buy equipment”


Этот пост - напоминание о безопасности в Интернете.
Будьте аккуратны. Не доверяйте незнакомцам 🙏

Делитесь под постом, с какими попытками обмана встречались вы 👇

🧐 Каким способом делать вызов API DaData - через Бэк или через Фронт? 🧐 Разбираем ответ на вопрос.

Большинство голосов у нас в сторону варианта “через Бэк” (Backend). Это правильный лучший вариант. Хотя и напрямую “через Фронт” тоже можно делать интеграции.


👌 Использование 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) могут быть уместны только в очень простых сценариях, но они увеличивают риски безопасности и сложности в управлении.

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

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

2️⃣ главных вопроса в задачах на Интеграции от Системного Аналитика 🔽

Когда вы получили задачу на интеграцию, то должны задать 2 вопроса разработчикам внешней системы или заказчикам:

📌 Как получить API-документацию?

Без API-документации нет ясности как вообще можно взаимодействовать с внешней системой. Нет понимания даже команд, которые есть в ней.

API-документация может быть передана вам в виде ссылке на Postman-коллекцию, Swagger-коллекцию, сайт разработчика, PDF- или Word-документ.

Увы, до сих пор остается грустной правдой, что некоторые API не имеют документации и для интеграции тебе в email присылают curl-ы (примеры вызовов) нужных запросов, а дальше сами разбирайтесь. Всякое бывает 😔


📌 Как получить тестовые и боевые доступы для проверки API?

Без этого системному аналитику никуда не сдвинуться. Работа будет на ощупь 🤲

Если API-документация есть, то это прекрасно! Но часто, даже в крупных компаниях, бывают несовпадения документации и реальности. Не всегда все ошибки описаны в документации 🙁

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


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

1. Оглавление
2. Авторизация и аутентификация
3. Тестовые доступы, если еще не получили
4. Рекомендации по использованию API
5. Список методов, необходимых для реализации ваших интеграционных сценариев
6. Общие требования к обработке ошибок

Подробнее про исследование API внешних систем расскажу в следующих постах 😎

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

🧑‍🔬 Исследование API внешней системы: инструкция 🧑‍🔬

Исследование API внешней системы - основной шаг при работе с задачами интеграцию систем.

Поэтому, как только API-документация или её подобие получены, можно начинать аналитику по задаче. До этого задачу стартовать практически нереально.

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

----------------------

Инструкция по исследованию API:

◽️1. Оглавление
Найти разделы, в которых потенциально есть информация по следующим пунктам из этой инструкции.

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

◽️3. Тестовые доступы, если еще не получили
Нужны для проверки как реально работает API через Postman или другой инструмент, и насколько API соответствует документации.

◽️4. Рекомендации по использованию
Примеры сценариев использования. Это не всегда есть в API-документации. Но если есть, то считайте, что задача почти готова. Предложенный сценарий интеграции надо адаптировать под бизнес-процессы текущего проекта.

◽️5. Список методов, необходимых для реализации ваших интеграционных сценариев
На этапе знакомства с документацией сильно вчитываться не надо. Главное понять, что методов для реализации бизнес-процессов текущего проекта достаточно.

◽️6. Общие требования к обработке ошибок
Коды ответов, структура сообщений, сценарии.

----------------------

Эта инструкция поможет вам понять, что вы получили достаточно информации для работы с задачей на интеграцию с внешней системой 🙌

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

🧑‍🔬 Исследование API: пример для DaData 🧑‍🔬

В предыдущем посте опубликовала инструкцию по исследованию API-документации. Теперь хочу показать как она работает на практике для проекта #ShipEasyGA.

----------

◽️1. Оглавление
В онлайн-документации DaData сначала показывается общий справочник всех API. В нем нам могут подойти:

🟢 Разбор адреса из строки («стандартизация»)
🟢 Автодополнение при вводе («подсказки»)
🟢 Геокодирование для определения координат адреса, если их не будет в основном API по стандартизации адресов.

Внутри документации по отдельным API есть собственное содержание, под заголовком:
+ Как вызвать
+ Что в ответе
+ Коды качества
+ Примеры
+ Ограничения
+ Стоимость

Так устроено оглавление в DaData. Еще пример подобной структуры: Авито.


◽️2. Авторизация и аутентификация, ограничения

На всех страницах API-документации 🟢, в разделе “Как вызвать”, вы найдете стандарте стандартную фразу:

Чтобы вызвать метод, и подтвердите почту.

Часто бывает отдельный раздел “Аутентификация”, “Начало работы” как в Авито, или подобный, где описаны эти требования.

Также обращаю внимание на разделы “Ограничения” и “Стоимость”. Через них можем понять, что API платный, и у нас есть расходы на работу системы, которые нужно согласовывать с бизнесом.

Для платных API всегда важно подумать над алгоритмом работы: про минимизацию количества вызовов за счет хранения части данных у нас (кэширование).


◽️3. Тестовые доступы

Для DaData тестовый доступ отсутствует. Если хочешь пользоваться API, то только боевая площадка.

В таком случае рекомендуется завести два аккаунта: для тестирования и боевой. Но это не всегда удобно. Смотреть по ситуации.


◽️4. Рекомендации по использованию

Смотрим раздел “Как вызвать” в документации DaData, где нам предлагают примеры запросов и ответов. Это максимум, который можем найти для DaData.

Но некоторые системы, особенно платежные, предлагают готовый сценарий интеграции. Посмотрите на пример документации от СберПэй. Осталось адаптировать предложенное под нашу систему.


◽️5. Список методов, необходимых для реализации ваших интеграционных сценариев

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


◽️6. Общие требования к обработке ошибок

В DaData дают “Коды ответа на запрос” на отдельных страницах документации 🟢, но не всегда.

В СберПэй подробно расписаны примеры ошибок на каждый запрос.

В некоторых API-документациях есть отдельный раздел в оглавлении с описанием типовых ошибок в API.

А иногда это вообще опускают и не делают. Всякое бывает 😁

----------


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

👉 Далее перехожу к тестированию API-методов, выделенных в п.5.
Тестирование помогает понять, как работает API и убедиться, что все соответствует документации.
Это нужно, чтобы после передачи задачи в разработку программисты не сталкивались с проблемами неработоспособности внешних систем и задача не вставала.

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