Начните ТЗ с границ интеграции и проверяемого результата
Чтобы составить ТЗ на интеграцию двух корпоративных систем, сначала зафиксируйте не технологии, а бизнес-задачу, участников обмена, данные, правила обработки и критерии приемки. Хорошее техническое задание позволяет разработчику реализовать интеграцию без устных уточнений, а заказчику — проверить результат по заранее согласованным условиям.
Минимальная структура документа должна отвечать на вопросы:
- какие системы участвуют в интеграции;
- какой процесс автоматизируется;
- какие данные передаются и в каком направлении;
- когда и при каких условиях выполняется обмен;
- как проверяется корректность работы;
- кто отвечает за согласование и эксплуатацию.
Не начинайте ТЗ с описания API, форматов сообщений или названий полей. Сначала определите бизнес-сценарий и ожидаемый результат, иначе технические детали могут описывать не ту задачу.
1. Опишите участников и назначение интеграции
В первом разделе ТЗ укажите исходные данные проекта. Необходимо однозначно определить системы, между которыми выполняется обмен.
Пример структуры раздела:
- Система-источник: приложение, в котором создаются или изменяются данные.
- Система-получатель: приложение, куда передаются данные.
- Владелец процесса: подразделение или роль, отвечающая за бизнес-результат.
- Цель интеграции: какое действие должно стать автоматическим.
Формулировка цели должна быть проверяемой. Например, вместо «синхронизировать клиентов» лучше указать: «обеспечить передачу сведений о новых клиентах из системы A в систему B после выполнения условия создания записи».
2. Зафиксируйте сценарии обмена данными
Каждый сценарий описывайте отдельно. Один сценарий должен отвечать на вопрос: что происходит от момента появления события до получения результата.
Для каждого сценария укажите:
- событие, запускающее обмен;
- источник данных;
- проверки перед отправкой;
- состав передаваемых данных;
- действие системы-получателя;
- результат успешного выполнения;
- варианты ошибок.
Например:
| Элемент | Описание |
|---|---|
| Событие | Создание новой записи в системе-источнике |
| Данные | Идентификатор, название, статус, дата изменения |
| Результат | Запись создана или обновлена в системе-получателе |
| Ошибка | Фиксация причины отказа и возможность повторной обработки |
3. Составьте перечень передаваемых данных
Описание полей является одной из самых важных частей ТЗ. Для каждого значения укажите назначение и правила обработки.
| Поле | Описание | Обязательность | Правило обработки |
|---|---|---|---|
| external_id | Внешний идентификатор объекта | Указывается при необходимости | Используется для сопоставления записей |
| status | Текущее состояние объекта | Определяется бизнес-правилами | Передается по согласованным значениям |
| updated_at | Дата изменения | Зависит от сценария | Используется для определения актуальности данных |
Не ограничивайтесь названием поля. Нужно описать:
- тип данных;
- допустимые значения;
- условия обязательности;
- источник значения;
- правила преобразования.
4. Опишите архитектуру взаимодействия
В ТЗ достаточно зафиксировать логическую схему интеграции. Конкретная реализация может уточняться после анализа технических возможностей систем.
Укажите:
- направление обмена: одностороннее или двустороннее;
- способ запуска обмена: по событию, расписанию или запросу;
- участников процесса обработки;
- требования к журналированию операций;
- необходимость повторной обработки ошибок.
Если формат обмена уже определен, добавьте пример структуры данных. Например:
{
"id": "12345",
"name": "Example",
"status": "active"
}Пример должен показывать структуру сообщения, а не заменять описание правил обработки.
5. Добавьте требования к ошибкам и контролю
Интеграция должна быть описана не только для успешного сценария. В ТЗ необходимо определить ожидаемое поведение при проблемах.
Опишите:
- какие ошибки считаются критическими;
- как фиксируется факт ошибки;
- кто получает информацию о проблеме;
- можно ли повторить обработку данных;
- как определяется успешное завершение операции.
Пример формулировки требования:
«При невозможности обработки сообщения система должна сохранить информацию об ошибке с указанием причины и идентификатора исходного объекта для последующего анализа».
6. Определите нефункциональные требования
Кроме логики обмена, ТЗ должно содержать ограничения по эксплуатации. Они помогают избежать разного понимания результата.
В этот раздел можно включить:
- требования к доступности интеграции;
- ограничения по времени обработки;
- требования к безопасности доступа;
- требования к хранению журналов;
- ограничения по объему данных.
Указывайте только согласованные требования. Если конкретные значения пока неизвестны, это нужно обозначить как вопрос для согласования, а не заполнять предположением.
7. Опишите порядок тестирования и приемки
Критерии приемки должны быть сформулированы так, чтобы результат можно было проверить.
Добавьте в ТЗ:
- перечень тестовых сценариев;
- ожидаемый результат каждого сценария;
- условия успешного завершения проверки;
- ответственных за подтверждение результата.
Пример таблицы приемки:
| Сценарий | Действие | Ожидаемый результат |
|---|---|---|
| Создание объекта | Создать запись в системе-источнике | Объект появляется в системе-получателе |
| Изменение данных | Изменить согласованное поле | Изменение передается согласно правилам |
| Ошибка обработки | Передать некорректные данные | Ошибка фиксируется согласно требованиям |
8. Используйте готовый шаблон структуры ТЗ
Для большинства интеграционных проектов подойдет следующий каркас документа:
1. Общая информация
- цель интеграции;
- участники;
- область применения.
2. Описание процессов
- бизнес-сценарии;
- события;
- результаты.
3. Требования к обмену данными
- объекты;
- поля;
- правила преобразования.
4. Технические требования
- схема взаимодействия;
- ограничения;
- требования безопасности.
5. Обработка ошибок
- типы ошибок;
- журналирование;
- повторная обработка.
6. Тестирование и приемка
- сценарии проверки;
- критерии успешного выполнения.
7. Ответственные лица
- заказчик;
- исполнитель;
- согласующие.Чек-лист перед передачей ТЗ в разработку
- Цель интеграции сформулирована через ожидаемый результат.
- Системы-участники и их роли указаны.
- Все основные сценарии обмена описаны отдельно.
- Состав данных содержит правила обработки, а не только названия полей.
- Ошибки и порядок их обработки зафиксированы.
- Критерии приемки позволяют проверить готовый результат.
- Неопределенные требования отмечены как вопросы согласования.
Такое ТЗ становится рабочим документом между владельцами процесса, аналитиками и разработчиками: оно фиксирует ожидаемое поведение интеграции и позволяет принять результат по понятным условиям.