Публикация была переведена автоматически. Исходный язык: Русский
У каждого стартапа или зрелого ИТ-бизнеса рано или поздно возникает момент, когда простая идея — «Сделать крутую CRM для корпоративного сектора» — превращается в многостраничный, противоречивый и откровенно непонятный документ под названием «Техническое задание». Мы привыкли думать, что ТЗ — это один раз написанный контракт, но на деле это живой инженерный объект. Как разработчик, которому часто приходится разбирать этот «код на естественном языке», я утверждаю: качественное, понятное программисту ТЗ не рождается с первой попытки. Оно выстраивается через серию жестких логических итераций.
Ниже я разберу наш недавний опыт разработки спецификаций для сущностей Client (B2C/B2B) и Lead (B2C/B2B) в рамках крупной BSS-экосистемы. Минимизируем упоминание конкретных брендов (Клиент — крупный оператор связи РК), и максимизируем разбор методов, которыми мы заставили спецификацию «говорить» на языке разработчиков.
Описательный пользовательский интерфейс (Скриншоты и макеты)
Самая распространенная ошибка менеджеров продукта — считать, что набор макетов интерфейса с текстовым описанием элементов является достаточным ТЗ. Наш первый запрос выглядел именно так: «Опишите элементы интерфейса на скриншотах».
Метод: Мы перевели визуальный язык в текстовый: выделили Навигационную панель, Шапку (Header) и Рабочую зону. Описали виджеты и вкладки: «Баланс», «Действующие продукты», «Спецпредложения».
Критика Разработчика (Temperature = 0.1): С точки зрения UI/UX — отлично. С точки зрения Backend и БД — пустой звук. Фраза «Отображает категорию» не говорит мне, является ли это поле строкой (String), числом (Integer), или ссылкой на внешнюю таблицу (Foreign Key). Если я спроектирую БД на основе этого описания, мы получим логические несостыковки на этапе интеграции.
Чтобы заставить бэкенд работать, нам пришлось перевести описательный UI на язык структур данных. Мы взяли макетные JSON-объекты для сущностей client и lead, наполненные тестовыми данными.
Метод: Мы «наложили» эти JSON-структуры на описанные ранее визуальные блоки. Появились четкие маппинги: поле «ФИО» — это client.fio, «Номер телефона» — contact.value. Появилась ясность в хранении истории лидов (history[]).
Критика Разработчика (Missing Edge Cases): Стало лучше, но JSON макетных данных обманчив. В нем residentStatus равен true, но разработчик должен знать, как обрабатывать false. Кроме того, JSON макета часто содержит логические баги, которые разработчик должен выявить ДО написания кода.
Современный B2B/B2C-интерфейс редко живет автономно. На этом этапе мы столкнулись с интеграционной сложностью: подключение Nexign (Биллинг), Camunda (Бизнес-процессы), Astrum (Скоринг), SAO (Тикетинг) и Avaya (Телефония).
Рисунок 1: Усложнение архитектуры интеграции. Сравнение простых UI макетов и комплексных JSON-структур с [NEW] полями от внешних систем.
Метод: Мы ввели тег [NEW] для полей, добавленных из внешних документов (Nexign, Camunda). Появились критические атрибуты для B2B: «Смена ответственного» (Nexign ID), «результат скоринга Аструм», «проверка IMEI» (Ceir), «Кодовое слово» (Verify Avaya).
Критика Разработчика (Logic Discrepancies): Появилась логическая несостыковка типов: «Boolean/Enum Type Ambiguity». Неясно, как хранить: Boolean (true/false) или Enum (строковый список статусов)? Также не описано, как Lead конвертируется в Client при статусе «Успешный». Описали кнопку «Согласовать скидку» через Camunda, но не описали JSON Payload для вызова этого процесса.
На заключительном этапе, при введении ограничений строго логического анализа (Temperature=0), мы перешли от описаний полей к описанию REST API методов.
Метод: Мы создали спецификацию OpenAPI YAML/JSON для эндпоинтов /api/v1/b2c-clients/{id} и /api/v1/b2c-leads/{id}.
Мы жестко закрепили типы: String (бин 12 симв.), Boolean (true/false), Integer (ID, UnitId), Instant/OffsetDateTime (createdDate ISO-8601).
Мы добавили [NEW] теги и для API, например, specialOffers.compatibility is Compatible (Аструм).
Критика Разработчика (Оценка 7/10): Это лучшая из четырех итераций. Теперь я могу спроектировать БД на основе спецификации OpenAPI. Однако, для «10/10» нам все еще не хватает:
- Описания эндпоинтов для CRUD-операций (Создание лида, Обновление комментария).
- Схемы обработки ошибок (400, 403, 404, 500).
- Развернутого описания State Machine (Диаграмма состояний), регламентирующего, из какого статуса в какой можно переходить и когда срабатывают триггеры на создание карточки клиента B2B.
- Матрицы Ролевого Доступа (RBAC).
Не бойтесь писать ТЗ, которые программисты критикуют. Слишком часто спецификации — это просто спекуляция, пока разработчики не скажут: «Я не могу это реализовать, я не понимаю типы данных». ТЗ становится инженерным продуктом только тогда, когда оно описывает:
- Не только «что на экране», но и «какая это структура данных»;
- Не только «есть интеграция», но и «какой Payload мы отправляем и ждем ли Webhook».
В нашем B2C/B2B проекте мы прошли через 4 жесткие логические итерации, последовательно усложняя архитектуру и устраняя несостыковки. Это нормальный процесс. Главное — использовать инженерный подход к понятности для программиста.
У каждого стартапа или зрелого ИТ-бизнеса рано или поздно возникает момент, когда простая идея — «Сделать крутую CRM для корпоративного сектора» — превращается в многостраничный, противоречивый и откровенно непонятный документ под названием «Техническое задание». Мы привыкли думать, что ТЗ — это один раз написанный контракт, но на деле это живой инженерный объект. Как разработчик, которому часто приходится разбирать этот «код на естественном языке», я утверждаю: качественное, понятное программисту ТЗ не рождается с первой попытки. Оно выстраивается через серию жестких логических итераций.
Ниже я разберу наш недавний опыт разработки спецификаций для сущностей Client (B2C/B2B) и Lead (B2C/B2B) в рамках крупной BSS-экосистемы. Минимизируем упоминание конкретных брендов (Клиент — крупный оператор связи РК), и максимизируем разбор методов, которыми мы заставили спецификацию «говорить» на языке разработчиков.
Описательный пользовательский интерфейс (Скриншоты и макеты)
Самая распространенная ошибка менеджеров продукта — считать, что набор макетов интерфейса с текстовым описанием элементов является достаточным ТЗ. Наш первый запрос выглядел именно так: «Опишите элементы интерфейса на скриншотах».
Метод: Мы перевели визуальный язык в текстовый: выделили Навигационную панель, Шапку (Header) и Рабочую зону. Описали виджеты и вкладки: «Баланс», «Действующие продукты», «Спецпредложения».
Критика Разработчика (Temperature = 0.1): С точки зрения UI/UX — отлично. С точки зрения Backend и БД — пустой звук. Фраза «Отображает категорию» не говорит мне, является ли это поле строкой (String), числом (Integer), или ссылкой на внешнюю таблицу (Foreign Key). Если я спроектирую БД на основе этого описания, мы получим логические несостыковки на этапе интеграции.
Чтобы заставить бэкенд работать, нам пришлось перевести описательный UI на язык структур данных. Мы взяли макетные JSON-объекты для сущностей client и lead, наполненные тестовыми данными.
Метод: Мы «наложили» эти JSON-структуры на описанные ранее визуальные блоки. Появились четкие маппинги: поле «ФИО» — это client.fio, «Номер телефона» — contact.value. Появилась ясность в хранении истории лидов (history[]).
Критика Разработчика (Missing Edge Cases): Стало лучше, но JSON макетных данных обманчив. В нем residentStatus равен true, но разработчик должен знать, как обрабатывать false. Кроме того, JSON макета часто содержит логические баги, которые разработчик должен выявить ДО написания кода.
Современный B2B/B2C-интерфейс редко живет автономно. На этом этапе мы столкнулись с интеграционной сложностью: подключение Nexign (Биллинг), Camunda (Бизнес-процессы), Astrum (Скоринг), SAO (Тикетинг) и Avaya (Телефония).
Рисунок 1: Усложнение архитектуры интеграции. Сравнение простых UI макетов и комплексных JSON-структур с [NEW] полями от внешних систем.
Метод: Мы ввели тег [NEW] для полей, добавленных из внешних документов (Nexign, Camunda). Появились критические атрибуты для B2B: «Смена ответственного» (Nexign ID), «результат скоринга Аструм», «проверка IMEI» (Ceir), «Кодовое слово» (Verify Avaya).
Критика Разработчика (Logic Discrepancies): Появилась логическая несостыковка типов: «Boolean/Enum Type Ambiguity». Неясно, как хранить: Boolean (true/false) или Enum (строковый список статусов)? Также не описано, как Lead конвертируется в Client при статусе «Успешный». Описали кнопку «Согласовать скидку» через Camunda, но не описали JSON Payload для вызова этого процесса.
На заключительном этапе, при введении ограничений строго логического анализа (Temperature=0), мы перешли от описаний полей к описанию REST API методов.
Метод: Мы создали спецификацию OpenAPI YAML/JSON для эндпоинтов /api/v1/b2c-clients/{id} и /api/v1/b2c-leads/{id}.
Мы жестко закрепили типы: String (бин 12 симв.), Boolean (true/false), Integer (ID, UnitId), Instant/OffsetDateTime (createdDate ISO-8601).
Мы добавили [NEW] теги и для API, например, specialOffers.compatibility is Compatible (Аструм).
Критика Разработчика (Оценка 7/10): Это лучшая из четырех итераций. Теперь я могу спроектировать БД на основе спецификации OpenAPI. Однако, для «10/10» нам все еще не хватает:
- Описания эндпоинтов для CRUD-операций (Создание лида, Обновление комментария).
- Схемы обработки ошибок (400, 403, 404, 500).
- Развернутого описания State Machine (Диаграмма состояний), регламентирующего, из какого статуса в какой можно переходить и когда срабатывают триггеры на создание карточки клиента B2B.
- Матрицы Ролевого Доступа (RBAC).
Не бойтесь писать ТЗ, которые программисты критикуют. Слишком часто спецификации — это просто спекуляция, пока разработчики не скажут: «Я не могу это реализовать, я не понимаю типы данных». ТЗ становится инженерным продуктом только тогда, когда оно описывает:
- Не только «что на экране», но и «какая это структура данных»;
- Не только «есть интеграция», но и «какой Payload мы отправляем и ждем ли Webhook».
В нашем B2C/B2B проекте мы прошли через 4 жесткие логические итерации, последовательно усложняя архитектуру и устраняя несостыковки. Это нормальный процесс. Главное — использовать инженерный подход к понятности для программиста.
Поделиться
