# Интеграции: бизнес-логика

Домен интеграций объединяет внешние контуры платформы: обмен с 1С, ЭДО, почтовые/календарные провайдеры, шину сообщений и другие подключаемые сервисы. Цель домена — обеспечить предсказуемый двусторонний обмен данными между 1Формой и внешними системами без нарушения согласованности внутренних бизнес-процессов. Документ описывает основные направления, бизнес-правила, сценарии, зависимости и операционные риски. Аудитория — инженеры поддержки и разработчики, настраивающие и сопровождающие интеграции.

## Основные направления

**1. 1С-интеграция**

- Конфигурация обмена и сценарии-конструкторы.
- Очередь событий 1С.
- Обработка входящих событий в реальном времени.

Обмен с 1С работает только в полной сборке. В сертифицируемой сборке (1F Certificate Edition, профиль `UniForm.Barebone`) он изъят: настройка конфигурации, приём событий и разбор очереди обмена недоступны, а маршруты обмена отвечают `404`.

**2. ЭДО и внешние документы**

- Отправка/обработка документов через Diadoc/SBIS.
- Хранение связей и статусов документов.

**3. Интеграционная очередь и шина**

- Универсальная обработка событий по правилам обработки потоков.
- Повторные попытки и диагностика ошибок в `MessageQueue`.

**4. Сервисные интеграции**

- Exchange, auth providers, внешние API-коннекторы.

**5. Веб-аналитика (Matomo)**

Интеграция с Matomo (v2.256+) предоставляет аналитику использования системы. Требует настройки администратором (см. [Интеграции — администрирование](https://help.1forma.ru/domains/integrations/admin.md), § Matomo).

**Что отслеживается:**

- Типы посещений: прямые переходы, переходы с сайтов, из поиска, рекламных кампаний.
- Действия: загрузки файлов, переходы по ссылкам, длительность сессий.
- Цели и конверсии.
- Идентификаторы пользователей (связь действий между сессиями и устройствами).

**Инструменты:**

- Автоматические PDF/HTML-отчёты по email.
- Визуализации: круговые и столбчатые диаграммы, облака тегов.
- Экспорт: CSV, XML, PHP, Excel, JSON; REST API.
- Мобильные приложения Matomo (iOS / Android).

**Представления:** обзор посещений, журнал посещений, карта в реальном времени, география, устройства и ПО.

## Бизнес-правила и основные сценарии

Неподдерживаемый для исходящей конвертации тип дополнительного параметра не обрывает отправку события в 1С: реквизит пропускается с сервисным комментарием в задаче и записью в журнале синхронизации, остальные реквизиты уезжают. Событие, в котором после пропуска не осталось ни одного передаваемого реквизита, отправляется в 1С с пустым составом: событие создания задачи создаёт документ в 1С, а GUID из ответа записывается в задачу. Не отправляется только событие изменения задачи без изменённого реквизита. Перечень неподдерживаемых типов выводится из конвертера, а не задаётся отдельным списком, поэтому новый неподдерживаемый тип подхватывается без ручной правки. То же правило действует во входящем направлении: неподдерживаемый реквизит ответа пропускается, остальные разбираются, а ответ целиком из неподдерживаемых реквизитов существующую задачу не меняет и новую не создаёт.

Бизнес-правила домена интеграций:

1. Любая интеграция должна иметь валидную конфигурацию и учётные данные.
2. Асинхронные процессы управляются политикой обработки потока (повтор / остановка / ошибка).
3. Ошибка во внешнем сервисе не должна скрыто менять внутреннее состояние как «успех».
4. Для критичных сценариев нужен операционный журнал с контекстом события.
5. Сбой необязательной части операции не отменяет уже выполненную работу: ошибка коннекторов, действий после изменения или пересчёта тегов и смарт-доступа откатывается отдельно, попадает в список некритичных ошибок и фиксируется в журнале синхронизации, а сохранение данных задачи завершается.
6. Состав интеграционных контуров зависит от сборки платформы: в сертифицируемой сборке часть контуров изъята, и недоступность такой интеграции — свойство поставки, а не сбой площадки.

Основные сценарии:

- Сохранение и валидация конфигурации интеграции.
- Приём и обработка входящего внешнего события.
- Фоновая обработка очереди и восстановление после ошибок.

Зависимости домена: `tasks`, `ext-params`, `users-and-groups`, `calendar`, `mail`, `contracts`.

Операционные риски:

- Неверное сопоставление (mapping) пользователей/объектов.
- Зависания очередей при `ActionOnError = Stop`.
- Ошибки сетевого доступа и истёкшие учётные данные.
- Синхронный внешний вызов из каскада «После смены ДП» выполняется с открытой транзакцией, поэтому свежие данные задачи не видны встречным запросам до её коммита. У виртуальных документов вызов 1С на переходе отложен до коммита, поэтому при недоступности 1С отправка остаётся в очереди и повторяется заданием.
- Частичный сбой при обработке события 1С не виден пользователю: данные задачи сохраняются, а сведения об ошибке остаются в списке некритичных ошибок и в журнале синхронизации.

При инцидентах проверять:

1. Сборку площадки — полная или сертифицируемая (`UniForm.Barebone`). В сертифицируемой сборке обмен с 1С изъят, поэтому «интеграция не работает» закрывается этой проверкой.
2. Логи интеграционного сервиса (1С/ЭДО).
3. Состояние `MessageQueue`, `MessageQueueLog`, `MessageFlows`.
4. Актуальность конфигурации и доступность внешнего сервиса.