Как описать сервис для выгрузки портфеля сделок с входными и выходными данными

Что проверяют

Умеете ли вы превратить «нужна выгрузка» в спецификацию, по которой разработчик напишет сервис без десятка уточнений. Смотрят, начинаете ли вы с потребителей и сценариев, а не с API Gateway, и помните ли про объёмы, ошибки и доступы. Следом обычно спрашивают: «А если в портфеле миллион сделок?».

Как отвечать

Идите от назначения к контракту:

• назначение: кто выгружает (интерфейс, отчётность, смежная система), зачем и как часто. От этого зависят формат, объём и требования к скорости;
• вход: идентификатор портфеля или клиента, дата среза, период, типы и статусы сделок, валюта, формат файла. Для каждого параметра тип, обязательность, допустимые значения, валидация и значение по умолчанию;
• выход: таблица полей с типом, форматом, обязательностью и системой-источником. Даты в ISO 8601, суммы десятичной строкой с кодом валюты по ISO 4217, а не float. Оговорите, по какой дате фильтруется сделка: дата заключения и дата расчётов расходятся;
• ошибки: 400 на невалидные параметры, 403 без прав, 404 на неизвестный портфель и единый формат тела ошибки;
• объём: большой портфель выгружают асинхронно. Запрос возвращает 202 Accepted и идентификатор задачи, клиент опрашивает статус, файл лежит в хранилище по временной ссылке. Синхронному варианту нужна курсорная пагинация;
• нефункциональные требования: время ответа, частота запросов, согласованность данных на дату среза, аудит того, кто и что выгружал.

Оформляется это контрактом в OpenAPI с примерами запроса и ответа и диаграммой последовательности: клиент, сервис выгрузки, учётная система, хранилище файлов. Покажите, что знаете, откуда приходит каждое поле: в такой задаче это главная ценность аналитика.

Где спотыкаются

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

Не думают про объём и проектируют синхронный запрос, который на крупном портфеле упирается в таймаут.

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