Спроектируйте каталог интеграций, который масштабируется от 3 до 30 интеграций: простая модель данных, понятные статусы, управление правами и интерфейс прогресса настройки.
Люди открывают каталог интеграций по одной простой причине: чтобы подключить инструменты и чтобы они работали, не требуя внимания каждый день. Если экран заставляет пользователя угадывать, что подключено, что сломалось или куда нажать дальше, доверие падает быстро.
При 3 интеграциях простая сетка логотипов может сработать. При 30 всё рушится: пользователи перестают сканировать список, растут обращения в поддержку, а кнопка «Connect» превращается в ловушку, потому что каждая интеграция может быть в своём состоянии.
Каждая карточка (или строка) интеграции должна одним взглядом отвечать на три вопроса:
Большая часть путаницы возникает на краевых случаях, которые постоянно встречаются в реальных командах. Кто‑то подключил Google личной учёткой вместо корпоративной. Токен Stripe истёк и синхронизация биллинга остановилась. Slack‑рабочее пространство подключено, но не был выдан нужный scope для канала, поэтому настройка «наполовину» завершена, хотя UI выглядит нормально.
Хороший экран делает такие ситуации очевидными. Вместо просто «Connected» показывайте «Connected (needs permission)» или «Connected to: [email protected]», и ставьте следующее действие прямо на карточку. Это убирает догадки и помогает списку оставаться читаемым по мере роста.
Самый простой способ масштабировать каталог интеграций — разделить:
Это остаётся понятным при 3 интеграциях и хорошо работает при 30.
Integration — запись в каталоге. Глобальная, не привязана к рабочему пространству.
Install — означает, что рабочее пространство включило эту интеграцию (например: «Slack включён для Workspace A»).
Connection — реальный внешний аккаунт или учётные данные (например: «Slack workspace X через OAuth» или «Stripe account Y через API key»). Один Install может иметь много Connections.
Минимальный набор полей, который обычно хорошо масштабируется:
Храните видимую пользователю конфигурацию (выбранный канал, псевдоним webhook URL, включённые события) в Install или Connection как обычные данные. Секреты (OAuth refresh tokens, API keys, signing secrets) храните только в хранилище секретов или в зашифрованных полях с жёстким контролем доступа.
Не кладите секреты, полные коды авторизации или сырые webhook‑пейлоады в логи. Если нужно логировать — логируйте ссылки (connection_id) и безопасную метаинформацию (HTTP статус, код ошибки).
Чтобы оставаться гибкими для OAuth, API keys и webhooks, держите auth‑специфичные поля внутри Connection (метаданные токена vs отпечаток ключа vs статус проверки webhook). Состояние, видимое UI (включено и прогресс настройки), держите на Install.
Люди открывают каталог интеграций, чтобы быстро ответить на три вопроса: работает ли это, насколько завершена настройка и что мне делать дальше. Если слова статусов расплывчаты, обращения в поддержку растут, а доверие падает.
Начните с небольшого набора статусов, который можно поддерживать годами:
Предпочитайте вычисляемые статусы сохранённым ярлыкам. Сохранённые метки дрейфуют: кто‑то исправил ошибку, а бейдж остаётся красным. Вычисляемый статус рассчитывается по фактам, которые вы уже отслеживаете — валидны ли токены, выполнены ли обязательные шаги, остановил ли интеграцию админ. Если вы что-то и сохраняете, сохраняйте базовые факты (последний успешный синк, код последней ошибки), а не итоговую метку.
Прогресс настройки лучше показывать как короткий чеклист с чётким разделением на обязательные и опциональные шаги. Моделируйте это как определения шагов (статические, для каждой интеграции) плюс результаты шагов (для каждого install).
Пример: у Slack обязательные шаги могут быть «Authorize workspace» и «Select channels», а опциональный — «Enable message previews». UI может показывать «2 из 3 обязательных шагов выполнено», при этом не блокируя опциональные шаги.
Несколько подключений под одной интеграцией могут превратить каталог в хаос, если вы не спланируете это. Держите одну карточку на интеграцию, показывайте количество подключений и честно агрегируйте статус. Если какое‑то подключение сломалось, показывайте «Needs attention» с подсказкой вроде «1 из 4 workspaces требует реаутентификации». Обзор остаётся чистым, но отражает реальность.
Права интеграций становятся запутанными, когда всё сваливается в один переключатель. Яснее разделять:
Начните с лёгкой проверки ролей, которая действует везде. Для многих приложений достаточно трёх ролей: Admin, Manager и Member. Админы могут всё. Менеджеры — настраивать большинство интеграций для своей команды. Участники могут пользоваться уже включёнными интеграциями, но не менять настройки.
Добавляйте флаги по‑интеграциям только там, где они действительно нужны. Большинство интеграций (календарь, чат) могут следовать дефолтным правилам ролей. Чувствительные интеграции (платежи, зарплата, экспорт данных) должны требовать дополнительной проверки, например «Payments admin» или «Billing manager». Храните это простым булевым флагом на install, а не новой системой ролей.
Читабельная матрица прав может выглядеть так:
Аудит не обязан быть тяжёлым, но он должен быть. Логируйте достаточно, чтобы быстро ответить на вопросы поддержки и безопасности: кто подключил, когда менялись учётные данные и кто отключал. Панель «Activity» на странице деталей с 5–20 недавними событиями обычно достаточна.
Пример: Stripe может быть виден всем, но только админы (или пользователи с флагом «Billing manager») могут подключать его, ротировать ключи или отключать выплаты. Slack может позволять менеджерам подключать, а участники будут получать уведомления, когда интеграция включена.
При 3 интеграциях можно показывать всё. При 30 каталог должен быстро ответить на вопрос: «Какие работают и что мне делать дальше?» Самый чистый подход — отделить сканирование от действий.
Держите представление каталога сфокусированным на быстрых решениях. Более тяжёлые контролы выносите на страницу деталей за кнопкой «Manage».
В списке показывайте только то, что поддерживает следующий клик:
Анатомия карточки важна, потому что формирует «мышечную память». Основное действие всегда должно означать «следующий шаг» в зависимости от состояния: Connect для нового, Continue setup для частично настроенного, Reconnect при просроченной авторизации и Manage, когда всё в порядке. Избегайте двух одинаково заметных кнопок на каждой карточке — это делает страницу шумной.
Примеры:
Пустые состояния должны направлять пользователя, не перегружая инструкциями:
Так страница остаётся спокойной при 30 интеграциях, потому что каждая карточка отвечает: что это, всё ли в порядке, и что делать дальше.
Список каталога направляет к нужной интеграции. Страница деталей — место, где решают: настроить, исправить или отключить. Держите структуру страницы согласованной для всех интеграций, даже если бэкенд‑работа различается.
Начните с компактного обзора: имя интеграции, однострочное описание и ясные статус‑ярлыки (Connected, Needs attention, Disabled). Добавьте маленькую строку «Setup progress», чтобы пользователь видел, близок он к завершению или только в начале.
Простой мастер работает хорошо: 3–6 шагов, по одному экрану на шаг, с кнопкой «Back» на каждом шаге. Называйте шаги простым языком (Connect account, Choose workspace, Pick data to sync, Confirm). Если в шаге есть опциональные настройки — явно помечайте их как optional.
Если настройку можно приостановить, скажите об этом: «Вы можете закончить позже. Мы сохраним ваши выборы.» Это уменьшает страх уйти со страницы.
Показывайте Connections в виде небольшой таблицы: имя аккаунта, кто подключил, дата создания и последнее синхронное событие.
По «next sync» избегайте обещаний, которые вы не можете гарантировать. Используйте формулировки, которые вы можете поддержать, например «Next sync: scheduled soon» или «Next sync: within the next hour», в зависимости от реальных возможностей системы.
Опасные действия держите подальше от основного пути. Ставьте основные действия вверху (Continue setup, Reconnect). Disable и Disconnect — в отдельной секции «Danger zone» внизу с кратким объяснением последствий. Если есть роли — укажите это одной фразой (например, «Только админы могут отключать»).
Добавьте небольшой лог активности: недавние события (connected, token refreshed, sync failed), таймстемпы и краткое сообщение об ошибке, которое пользователь может скопировать в тикет поддержки.
Добавление интеграции проще, когда вы относитесь к ней как к мини‑продукту. Нужны список в каталоге, способ подключения, место для хранения подключения и понятные исходы для успеха или ошибки.
Добавьте интеграцию в каталог, чтобы она появлялась в списке ещё до первого подключения. Укажите понятное имя, короткое описание, иконку и одну–две категории (Messaging, Payments). Напишите ожидания от настройки простыми словами, например «Connect an account» и «Choose a workspace». Здесь же определите, что потребуется позже (OAuth scopes, обязательные поля, поддерживаемые фичи).
Выберите самый простой способ подключения, соответствующий провайдеру:
Когда пользователь завершил поток, создайте Connection, привязанную к рабочему пространству или аккаунту, а не только к пользователю. Храните учётные данные безопасно (шифруйте на диске и не показывайте полный секрет повторно). Сохраните базу, полезную для поддержки: ID аккаунта у провайдера, время создания, кто подключил и какие права были выданы.
Запустите простой тест сразу (для Stripe: получить данные аккаунта). Если всё прошло — покажите Connected и отметьте прогресс как завершённый. Если частично прошло (подключено, но нет прав) — пометьте Needs attention и укажите точный шаг для исправления.
Показывайте одно понятное сообщение, одно рекомендованное действие и безопасный план действий. Например: «Не удалось связаться со Stripe. Проверьте API key или попробуйте снова.» Держите каталог полезным даже при сломанной интеграции.
Если вы строите на Koder.ai (koder.ai), сначала в Planning Mode можно черново описать каталог, поток настройки и правила статусов, а затем генерировать UI и бэкенд по этому плану.
Интеграции ломаются по банальным причинам. Если каталог не может объяснить эти причины ясно, пользователи винят ваше приложение, а поддержка остаётся без данных.
Группируйте ошибки по корзинам, соответствующим реальным исправлениям: истёк логин, недостающие права, проблема у провайдера или rate limit. Внутренние коды ошибок храните детальными, но пользователям показывайте короткую понятную метку.
Сообщение об ошибке должно отвечать: что произошло, что сделать пользователю и что система попробует сделать сама. Пример: «Slack connection expired. Reconnect to continue syncing. We’ll retry automatically once you reconnect.» Это спокойнее и полезнее, чем выкладывать сырую ошибку API.
Автоповторы только для случаев, которые пользователь не может исправить самостоятельно. Простые правила:
Статусы устаревают, если их не обновлять. Добавьте лёгкую задачу проверки здоровья, которая периодически подтверждает, что токены ещё работают, последний синк прошёл и бейдж каталога соответствует реальному состоянию.
Храните небольшую историю событий по каждому install. Не нужны полные логи — достаточно «хлебных крошек»: таймстемп, событие ("token refreshed", "sync failed"), короткая причина и кто это вызвал (пользователь или система). Добавьте поле заметок только для внутреннего пользования, чтобы поддержка могла записать, что и почему изменила.
Каталог быстро превращается в беспорядок, когда появляется больше приложений. Цель проста: помочь людям найти нужное за секунды и заметить проблемы, не открывая каждую карточку.
Начните с простого поиска по имени интеграции и категории. Большинство пользователей вводит то, что они уже знают («Slack», «Stripe»), поэтому совпадение по имени важнее сложного ранжирования. Поиск по категории помогает, когда они знают задачу (payments, messaging).
Фильтры должны отражать реальные намерения. Три обычно покрывают большинство сценариев:
Для организации списка выберите один основной критерий и придерживайтесь его. Группировка по категориям работает хорошо при большом количестве (CRM, Payments, Messaging). Популярность полезна, но только если она отражает вашу базу пользователей, а не маркетинг. Практический default: сначала показывайте самые используемые, затем группируйте остальное по категориям.
Нужно также продумать, кто что видит. Если интеграция за фичей или тарифом, либо скрывайте её для большинства, либо показывайте отключённой с короткой причиной вроде «Business plan». Не заполняйте страницу серыми карточками — это создаёт ощущение сломанности.
Поддерживайте быструю работу: разделяйте загрузку списка и деталей. Пагинация или виртуализация помогут не рендерить 30 тяжёлых карточек сразу; детали подгружайте лениво при открытии интеграции. Каталог может показывать сводные поля (Slack: Connected, Google: Needs attention, Stripe: Not set up), а страница деталей подтягивает полную историю подключений.
Представьте командное приложение Pinework. У него две роли: Admin и Member. Админы могут подключать инструменты и менять настройки. Участники пользуются подключёнными инструментами, но не добавляют и не удаляют их.
В каталоге Pinework каждая карточка показывает понятный ярлык (Connected, Needs setup, Error), короткую строку «что делает» и прогресс настройки вроде «2 из 3 шагов». Люди видят, что работает, а что ждёт без лишних кликов.
Slack используют для уведомлений. Админ открывает Slack и видит: Status: Connected, Setup: «3 of 3 steps». Участники тоже видят Slack, но основное действие им недоступно и вместо него написано «Ask an Admin to manage». Если Slack отключится, участники увидят, что сломалось, но не смогут переподключить.
Google используется для календарей. Pinework поддерживает несколько подключений, поэтому карточка Google показывает: Status: Connected (2 accounts). Под ней коротко перечислены «Marketing Calendar» и «Support Calendar». Данные могут быть в порядке, а страница деталей показывает два отдельных подключения, чтобы админ мог отозвать только одно.
Stripe отвечает за биллинг. Частая частичная настройка: аккаунт подключён, но webhooks не настроены. Карточка показывает: Status: Needs setup, Progress: «2 of 3 steps», с предупреждением «Payments may not sync». В деталях явный список оставшихся шагов:
Это избегает ситуации «кажется подключено, но ничего не работает».
Каталог интеграций обычно ломается, когда приложение растёт от нескольких интеграций до десятков. Проблемы редко «технические» — чаще это мелкие ошибки в маркировке и моделировании, которые ежедневно сбивают пользователей с толку.
Одна распространённая проблема — путаница между «installed» и «connected». Installed обычно означает «доступно в рабочем пространстве», connected — есть реальные учётные данные и данные текут. Когда эти понятия смешивают, пользователь нажимает на интеграцию, которая выглядит готовой, и натыкается на мёртвую точку.
Ещё одна ошибка — изобретение слишком многих состояний. Команды начинают с простого бейджа, затем добавляют крайние случаи: pending, verifying, partial, paused, degraded, blocked, expiring и т. д. Со временем эти ярлыки расходятся с реальностью. Держите небольшой набор, завязанный на проверках, которые вы действительно можете запускать.
Скрытые права тоже создают проблемы. Кто‑то подключил аккаунт, а потом выясняется, что интеграция получила больше доступа, чем ожидалось. Делайте scope очевидным перед финальным шагом «Connect» и показывайте его снова на странице деталей для аудита.
Многие приложения нуждаются в нескольких подключениях: два Slack‑пространства, несколько аккаунтов Stripe или общий Google‑аккаунт плюс личные аккаунты. Если жёстко привязывать «одна интеграция = одно подключение», потом придётся изобретать уродливые обходные пути.
Планируйте:
Держите список лёгким. Когда вы набиваете его логами, маппингами полей и длинными описаниями, сканирование замедляется. Используйте список для имени, короткого описания и прогресса. История и продвинутые настройки — на странице деталей.
Масштабируемый каталог интеграций сводится к простой модели и честному UI. Если пользователь может быстро ответить на три вопроса, система кажется предсказуемой: что подключено, что сломано и что делать дальше.
Чеклист перед релизом:
Дальше выберите три интеграции, которые вы хорошо знаете, и промоделируйте их end‑to‑end: чат‑инструмент (OAuth), Google‑тип подключения (OAuth со scopes) и платежный инструмент (API key + webhooks). Если ваша модель выражает все три без костылей, она обычно масштабируется до 30.
Считайте каталог не маркетинговой страницей, а панелью управления. Каждая карточка должна быстро показывать, для чего нужна интеграция, работает ли она сейчас, и какое одно действие нужно выполнить дальше. Если пользователю приходится кликать, чтобы узнать «подключено ли это?», каталог будет казаться ненадёжным по мере роста.
Правило простое: карточка должна отвечать на «что это», «здорово ли это» и «что теперь». Обычно это имя и короткое назначение, статус с недавним временем (последний синк или проверка) и одна основная кнопка, меняющаяся в зависимости от состояния. Всё остальное — за кнопкой «Manage», чтобы просмотр был быстрым.
Чтобы отделить то, что вы предлагаете, от того, что включено у конкретного рабочего пространства, используйте три сущности: глобальная запись в каталоге (Integration), включение в рабочем пространстве (Install) и реальные учётные данные или токен (Connection). Это предотвращает путаницу между «установлено» и «подключено».
Реальные команды часто нуждаются в нескольких внешних аккаунтах у одного провайдера. Например, разные Google-календаря для маркетинга и поддержки, или несколько аккаунтов Stripe. Модель с несколькими Connection под одним Install оставляет список чистым и даёт админам возможность управлять каждым аккаунтом отдельно в деталях.
Используйте небольшой набор меток, которые реально поддерживать: Not set up, In progress, Connected, Needs attention, Disabled. Выводите метку не из сохранённого статуса, а вычисляйте её по фактам: валидны ли токены, выполнены ли обязательные шаги, когда был последний успешный синк. Это предотвращает «застревание» красных бейджей после исправления проблемы.
Делайте прогресс настройки коротким чеклистом из обязательных и опциональных шагов. Храните определения шагов для интеграции и результаты по Install, чтобы UI мог показать «2 из 3 обязательных шагов выполнено». Всегда показывайте следующий обязательный шаг, не заставляя пользователя копаться в настройках.
Начните с простого правила ролей и добавляйте дополнительные проверки только для чувствительных интеграций. Обычно достаточно Admin, Manager и Member: админы — всё, менеджеры — настраивают большинство интеграций, участники — пользуются ими, но не меняют настройки. Для платежей или расчётов добавьте единственный флаг (например, «Billing manager»), а не целую новую роль.
Конфигурацию, видимую пользователю (выбранный канал, псевдоним webhook, включённые события), храните в Install или Connection как обычные поля. Секреты (refresh tokens, API-ключи, signing secrets) держите в хранилище секретов или в зашифрованных полях с жёстким доступом. Никогда не логируйте сырые секреты или полные webhook-пейлоады — логируйте ссылки (connection_id) и безопасную метаинформацию (HTTP-статус, код ошибки).
Сообщение об ошибке должно отвечать трём вещам: что случилось, что должен сделать пользователь и что система сделает сама. Повторы делайте только для проблем, которые пользователь не может исправить (аутсейдж провайдера, сетевая ошибка, rate limit). Для истёкшей авторизации или недостающих прав прекратите автоповторы и предложите «Reconnect» или «Fix permissions» как основное действие.
Поиск держите простым: сначала совпадение по имени провайдера, затем по категории. Фильтры должны отражать реальные намерения: Connected, Needs attention, Not set up. Если вы используете Koder.ai, сначала спроектируйте поля каталога, правила статусов и шаги настройки в Planning Mode — это поможет сгенерировать согласованную UI и backend по мере роста числа интеграций.
