Что скрывается за кнопкой отправки СМС

Сегодня я хочу разобрать небольшую доработку и на ее фоне показать, чем занимается системный аналитик. Мы пройдемся от кнопки в карточке клиента до контракта, ошибок и выхода в прод.

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

Меня всегда смущала фраза «системный аналитик — мост между бизнесом и разработкой». Для первого знакомства с профессией она годится. Но что делать, если готового ответа нет, а на входе только просьба «добавьте кнопку»? Здесь, по моему мнению, и начинается наша работа, которую словом «мост» уже трудно описать.

Сначала выясняем цель

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

Следом появляются условия. В каком сценарии обслуживания разрешена отправка? Нужна ли отдельная роль? Можно ли отправить сообщение повторно? Что именно оператор должен увидеть после нажатия?

Ответы на эти вопросы чрезвычайно трудно вывести из макета. Их нужно обсудить с владельцем процесса и записать так, чтобы разработчик и тестировщик поняли их одинаково.

Проверяем, как система работает сейчас

Такс, с целью разобрались. Теперь нужно найти то, что уже существует. Для решения зададимся вопросами: Есть ли сервис отправки СМС? Кто хранит шаблоны? Откуда берется номер клиента? Где искать историю отправок и как поддержка разбирает неудачные попытки?

Обычно нет одного документа со всеми ответами (А как бы хотелось. Ну честно). Приходится сопоставлять документацию, API‑контракты, конфиги, логи и данные. В этом месте особенно легко принять старое поведение за требование: «раз сейчас работает так, значит и здесь сделаем так же».

Расставляем границы ответственности

Теперь решаем, какой компонент за что отвечает. Интерфейс показывает доступность действия и блокирует повторный клик, но сервер все равно проверяет права: одной скрытой кнопки для защиты тут будет недостаточно. Сервис отправки определяет получателя по доверенным данным, проверяет шаблон и сохраняет запрос. Компонент, который общается с СМС‑провайдером, возвращает результат отправки. Если между ними есть очередь, надо договориться, кто хранит состояние запроса и кто меняет его после обработки.

Тут я бы специально остановился на результате.

У интерфейса, сервиса и провайдера могут быть разные представления об успехе. Для интерфейса успешный HTTP‑ответ означает, что запрос приняли. Для оператора «СМС отправлено» может означать, что сообщение ушло провайдеру. А доставка до телефона — это еще одно событие, если провайдер вообще сообщает о ней. Все эти значения нужно будет донести до реализации, а то каждый компонент назовет «успехом» свое.

Описываем контракт и состояния

Ниже условный фрагмент контракта. Клиент передает идентификатор получателя и шаблона, а вот сервер проверяет, доступен ли этот получатель оператору и допустимы ли параметры сообщения.

POST /api/v1/notifications/sms
Idempotency-Key: "ххх"
X-Correlation-Id: хххх-хххх

{
"recipientId": "client-123",
"templateId": "service-link",
"parameters": {"url": "https://example.org/help"},
"handlingId": "handling-456"
}

202 Accepted
{"requestId": "sms-789", "status": "PENDING"}

Ответ 202 Accepted здесь означает только то, что запрос принят в обработку и он не доказывает, что провайдер получил сообщение или что клиенту его доставили. А значит после ответа интерфейс показывает «Запрос принят», а дальнейшее состояние получает по requestId.

Заметь, тут нужно отдельно согласовать, что показывать, если сведений о доставке нет: «передано провайдеру» будет логичнее, чем «доставлено».

Есть правда и вопрос дублей. Заблокировать кнопку на фронте полезно, но это не спасет, если соединение оборвалось после отправки запроса: оператор же не знает, принял его сервер или нет. В примере для повторной попытки используется ключ идемпотентности тот же что и тогда, а сервер должен распознать повтор того же действия и вернуть результат исходного запроса, и не отправлять вторую СМС. Что хотел бы еще отметить — это то что срок хранения ключа и поведение при том же ключе с другим телом запроса тоже входят в контракт.

И вот что‑то такое у нас уже вырисовывается… Мне чет уже страшно!

Продумываем ошибки

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

Какие ошибки можно показать сразу?

При каких запрос остается в обработке?

Когда оператору безопасно повторить действие?

Для каждого состояния нужен понятный текст в интерфейсе и след в диагностике. По requestId или correlationId поддержка должна увидеть, на каком шаге остановилась отправка, без доступа к содержимому персонального сообщения. Иначе оператор говорит «кнопка не работает», но команде приходится после релиза восстанавливать картину по косвенным признакам (И ведь эти киборги справятся, но давай без таких приколов).

Проверяем и выпускаем

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

Отдельно проверил бы расхождение статусов: что видит оператор сразу после 202, после отказа провайдера, при задержке обработки.

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

Что по итогу получилось?

На входе была просьба добавить кнопку.

На выходе появился проверяемый сценарий: права, данные, контракт, статусы и ошибки.

И вот поэтому мне ближе формулировка «системный аналитик — это инженер изменений системы»: он заранее выясняет, как новая функция встанет в систему и что случится при сбое.