Aspro.Cloud после первого релиза: письма, комментарии и наблюдаемость

После первого импорта начинается настоящая работа

Базовая интеграция с Aspro.Cloud уже умела импортировать задачи, комментарии и время. Но сразу после первого рабочего сценария стали заметны более прикладные требования: кому отправлять уведомления, как диагностировать ответы API и как не потерять уже сохранённые комментарии, если внешняя система на минуту вернёт пустой список.

Именно такие детали обычно превращают «интеграция работает» в «интеграции можно доверять».

Уведомления должны зависеть от интеграции, а не от кода

Для каждой внешней CRM теперь можно хранить собственный notification_email в настройках интеграции. При импорте новой задачи или нового комментария приложение отправляет письмо на этот адрес и параллельно создаёт database-уведомления внутри Filament.

Ключевой момент здесь в afterCommit. Письма и UI-уведомления запускаются только после успешной транзакции, чтобы не рассказывать о задаче или комментарии, которые потом откатились из-за ошибки.

Нужна не только синхронизация, но и наблюдаемость

В адаптере появился снимок последних API-ответов: endpoint, query, статус, preview тела и число извлечённых записей. Это помогает быстро понять, проблема в сети, в формате ответа или в конкретном payload.

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

Комментарии нельзя терять из-за временно пустого ответа

Один из неприятных сценариев для любой внешней системы: API на конкретном вызове вернул пустой массив, хотя комментарии у задачи реально существуют. Если на такой ответ агрессивно синхронизировать удаление, локальная история просто исчезнет.

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

HTML из CRM должен оставаться читаемым и безопасным

Письма с внешними описаниями и комментариями теперь проходят через отдельный whitelist-рендер. Он убирает script, style, inline-обработчики, опасные URL-схемы и лишние атрибуты, но сохраняет нормальную базовую структуру вроде абзацев, списков, ссылок и выделения.

Это важнее, чем просто экранировать всё подряд. Полностью «плоский» текст ухудшает читаемость, а сырое HTML-содержимое опасно и в письме, и в UI.

Практический результат

Интеграция с Aspro.Cloud стала заметно взрослее именно в пограничных случаях. Уведомления привязаны к конкретной CRM, диагностика показывает последнюю реальную попытку синка, а комментарии и письма переживают неидеальные внешние данные без потери безопасности и истории.