Паспорт интеграции — обязательная документация
Директивный
Правило
Заголовок раздела «Правило»У каждой интеграции (HTTP-сервис, обмен, регламентная выгрузка во внешнюю систему) есть паспорт — одна страница в базе знаний команды, и она обновляется в той же задаче, что и код. Новая интеграция без паспорта не считается сданной; минорная правка без обновления паспорта — тоже.
Минимальный состав паспорта:
| Раздел | Что фиксируем |
|---|---|
| Назначение | Что и зачем передаётся, бизнес-владелец процесса |
| Стороны и контакты | Техвладельцы с обеих сторон: кого будить при сбое |
| Схема потока | Кто инициирует, направление, частота/расписание, объёмы |
| Точки входа | URL сервисов, имена планов обмена и регламентных заданий |
| Контракт | Форматы и версии, примеры запроса/ответа, ссылка на схему |
| Аутентификация | Способ (JWT, Basic, токен), техпользователь, где лежит секрет |
| Поведение при ошибках | Ретраи, идемпотентность, события ЖР, куда смотрит мониторинг |
| Ограничения | Таймауты, лимиты размера тела, окна обслуживания, WAF |
Интеграция — единственный вид доработки, у которого больше одного хозяина: код живёт в двух системах, а знание о том, как они договорились, — в голове того, кто это писал. Через год этот человек в отпуске, интеграция падает, и дежурный реверс-инжинирит контракт по журналу регистрации в три часа ночи. Паспорт превращает этот процесс в чтение одной страницы: где вход, чем аутентифицируется, что считается ошибкой и кому звонить. Он же — единственный способ узнать, кого уведомлять перед изменением контракта.
Когда не применять
Заголовок раздела «Когда не применять»Исключение одно: одноразовая миграционная выгрузка, живущая меньше одной задачи, — её достаточно описать в самой задаче (что, куда, чем аутентифицировалась). Всё, что переживает задачу, получает паспорт.