# Обзор интеграции с Exchange

Документ описывает Exchange как платформенный интеграционный контур: компоненты, точки настройки, обмен данными и границы между `calendar`, `mail`, `system`, `integrations`. Для инцидентов по конкретному пользователю — [Exchange — диагностика синхронизации пользователя](https://help.1forma.ru/domains/calendar/runbook-exchange-user-sync.md). Внутри: зоны ответственности, API управления и рабочие вызовы, конфигурация EWS, сквозная синхронизация календаря, служебные таблицы, фоновые задания, риски и порядок обращения в поддержку.

## Границы ответственности и точки входа API

Exchange-контур разбит на зоны ответственности между доменами:

| Зона | Что покрывает |
|---|---|
| `calendar` | бизнес-операции по событиям, режимы синхронизации пользователя, обработка ошибок EWS |
| `mail` | почтовые ящики Exchange (EWS/IMAP провайдеры), синхронизация папок/писем |
| `system` / `integrations` | сервисные учётные данные, флаги и политики интеграции |
| `platform/backend` | SignalR, инфраструктура заданий, очереди |

Ключевой принцип: Exchange не является единым монолитным модулем; это набор связанных подсистем.

**Admin API (управление и диагностика)**

| Метод | Маршрут | Назначение |
|---|---|---|
| GET | `/api/admin/exchange/subscriptions` | Список активных подписок Exchange |
| GET | `/api/admin/users/{userId:int}/service/settings` | Текущие сервисные/Exchange-настройки пользователя |
| POST | `/api/admin/users/{userId:int}/exchange/reset-fails` | Сброс счётчика неудачных попыток синхронизации |
| POST | `/api/admin/users/{userId:int}/exchange/update-sync-mode` | Смена режима Exchange для пользователя |

**API календаря (рабочие вызовы)**

| Метод | Маршрут | Назначение |
|---|---|---|
| POST | `/api/calendar/events` | Получение событий (агрегированный листинг) |
| POST | `/api/calendar/create` | Создание события |
| POST | `/api/calendar/update` | Обновление события |
| POST | `/api/calendar/delete` | Удаление события |
| POST | `/api/calendar/messages/unread/count` | Счётчик непрочитанных календарных сообщений |

## Конфигурация Exchange

**1. Сервис ExchangeWebService**

Главная форма настройки: `ews-service-settings` (`dbo.EwsServiceSettings`).

Критичные параметры:
- `Url`, `Login`, `Password`, `Domain`;
- `UseImpersonalization`;
- `UseSIDForImpersonalization`;
- параметры видимости чужих календарей/занятости.

**2. Общие настройки приложения**

Используются для глобальных политик синхронизации:
- режимы синхронизации с Exchange;
- лимиты повторов;
- флаги Exchange-подписок/поведения при ошибках.

**3. Пользовательские сервисные настройки**

Уровень пользователя определяет, будет ли синхронизация идти и в каком режиме:
- `Disabled`;
- `Sync`;
- `Direct`.

## Синхронизация календаря, таблицы и фоновые задания

Сквозная цепочка синхронизации календаря:

1. Пользователь/процесс меняет событие календаря (1Ф или Exchange).
2. `CalendarManager` и Exchange-провайдер выполняют операцию синхронизации.
3. При ошибках EWS срабатывает обработка исключений и увеличивается счётчик ошибок.
4. Если превышен лимит, режим пользователя может быть отключён.
5. Интерфейс получает состояние опросом (pull) (`calendar/*`, `service/settings`) и сигналами передачи.

| Объект | Назначение |
|---|---|
| `EwsServiceSettings` | Конфигурация подключения к Exchange |
| `EwsFolders` | Кэш папок Exchange по пользователям |
| `EwsFolderPermissions` | Кэш прав доступа к папкам/календарям |
| `UsersMessageCountCache` | Кэш счётчиков сообщений/состояний |
| `UserInfoExtValues` (`Sync.Exchange.*`) | Служебные флаги/состояния пользователя |
| `ExchangeSyncLog`, `ExchangeExportEvents` | Технические логи и экспортные события Exchange-контура |

Ключевые задания:
- `EnableDoSyncWithExchangeJob` — повторное включение синхронизации для пользователей, отключённых из-за Exchange-ошибок;
- `LazyUpdatableCachesUpdateJob` — обновление отложенных кэшей (включая Exchange-права/папки);
- связанные почтовые задания (`EmailJobSyncFolders`, `EmailJobReceive`) для mail-контура.

## Типовые архитектурные риски

Частые архитектурные риски Exchange-контура и где их искать:

| Риск | Где проявляется | Что проверять первым |
|---|---|---|
| Ошибки прав/имперсонализации | calendar + service settings | `UseImpersonalization`, SID/email, права сервисного аккаунта |
| Локальный счётчик ошибок у пользователя | user service settings | `syncWithExchangeFailedAttempts` vs лимит повторов |
| Деградация подписок | admin exchange subscriptions | `/api/admin/exchange/subscriptions`, состояние подключения |
| Подписки не запускаются совсем, логов нет | `Settings.DefaultEwsServiceId = NULL` + нет AD-профилей, привязанных к EWS | `SELECT DefaultEwsServiceId FROM Settings`; см. [Провайдер Exchange (EWS)](https://help.1forma.ru/domains/calendar/provider-ews.md), раздел «Как определяется список EWS-сервисов» |
| Рассинхрон кэша папок/прав | calendar/mail | `EwsFolders`, `EwsFolderPermissions`, задание обновления кэшей |
| Разная конфигурация между `system` и user-уровнем | system + user profile | фактический `ewsMode`, глобальные ключи и сервисные параметры |

## Когда обращаться в поддержку 1Ф и связанные документы

Обращаться в поддержку 1Ф (серверная часть) нужно, если:
1. API управления режимом/сбросом fail не меняет фактическое состояние пользователя.
2. Подписки Exchange стабильно не активируются после проверки учётных данных/URL.
3. Наблюдается массовая деградация (не один пользователь), особенно вместе с ошибками сети/инфраструктуры.

Проверить настройки администрирования нужно, если:
1. неверно настроены сервисные параметры Exchange;
2. права impersonation/delegate не соответствуют выбранному режиму;
3. применены конфликтующие ключи общих настроек.

**Связанные документы:**

- [Exchange — диагностика синхронизации пользователя](https://help.1forma.ru/domains/calendar/runbook-exchange-user-sync.md)
- [Провайдер Exchange (EWS)](https://help.1forma.ru/domains/calendar/provider-ews.md)
- [Календарь — администрирование](https://help.1forma.ru/domains/calendar/admin.md)
- [Интеграции — администрирование](https://help.1forma.ru/domains/integrations/admin.md)