# Видеоконференции — Администрирование

Администрирование видеоконференций в 1Форме: механизмы настройки (автоадминистрирование, API администрирования), ключевые параметры сервиса ВКС (Jitsi), телефонии и комнат, типичные ошибки и их диагностика. Для администраторов платформы и специалистов поддержки. Иерархия приоритетов настроек комнаты (глобальные → категория → индивидуальные) описана в [иерархии настроек ВКС](https://help.1forma.ru/domains/conferences/settings-hierarchy.md).

## Механизмы администрирования конференций

Администрирование конференций использует две группы механизмов: автоадминистрирование (3 формы) и API администрирования (мониторинг комнат).

Формы автоадминистрирования:

| Alias формы | Название | Таблица БД | Папка |
|-------------|----------|-----------|-------|
| `vks-service-settings` | Сервис ВКС | dbo.JitsiServiceSettings | Подключения |
| `telephony-settings` | Настройки IP Телефонии | dbo.TelephonySettings | Служебное |
| `telephony-actions-packs` | Настройки событий IP Телефонии | dbo.TelephonyActionsPacks | Служебное |

Маршруты API администрирования:

| Маршрут | Методы | Назначение |
|---------|--------|------------|
| `/api/admin/conference/rooms` | GET | Мониторинг статуса конференц-комнат |

## Настройка сервиса ВКС (JitsiServiceSettings)

Сервис ВКС настраивается через автоадминку в форме `vks-service-settings` и хранится в таблице `dbo.JitsiServiceSettings`. 19 полей определяют подключение к Jitsi и параметры интеграции:

| Группа полей | Что контролирует |
|-------------|------------------|
| Домен, секрет, URL | Подключение к серверу Jitsi |
| QueueId, MessageFlowId | Очереди для пост-обработки (транскрипты, видео) |
| Настройки записи | Автоматическая запись и транскрибация |
| Параметры комнат | Lobby, пароли, ограничения по умолчанию |

Форма имеет 2 зависимости между полями (условная видимость параметров). Значения используются при генерации токенов, создании комнат и обработке webhook-событий.

### Смарт-фильтры модератора, лобби и дополнительные параметры

Смарт-скрипты и смарт-фильтры контролируют доступ к комнатам ВКС и права участника в комнате:

| Поле | Тип | Контракт | Описание |
|------|-----|----------|----------|
| `CheckIsModeratorSmartScriptId` | int? FK → SmartScripts | TSQL/Lua → `bool` | `true` — пользователь является модератором комнаты. Заменяет устаревший `IsModeratorSmartFilterId` (SmartFilter). |
| `CheckSecurityBypassSmartScriptId` | int? FK → SmartScripts | TSQL/Lua → `bool` | `true` — авторизованный пользователь **пропускается в комнату без ожидания** в лобби. Отличается от модераторства: bypass не даёт прав управления, только мгновенный вход. |
| `CheckDialOutSmartFilterId` / `CheckDialOutSmartScriptId` | int? FK → SmartExpressions / SmartScripts | смарт-фильтр или TSQL/Lua → `bool` | `true` — пользователю разрешено приглашать участников по телефону и SIP из комнаты. Признак вычисляется при выдаче токена, в проверку передаются пользователь и комната. Если задан смарт-фильтр, смарт-скрипт не вычисляется. |

⚠️ **Пустое значение** `CheckSecurityBypassSmartScriptId` интерпретируется как `true` — система не запрашивает у модератора подтверждение для авторизованных пользователей. Не распространяется на гостей (неавторизованных).

⚠️ **Пустые значения полей dial-out** интерпретируются как `true`: если не настроены ни смарт-фильтр, ни смарт-скрипт, приглашение по телефону и SIP разрешено всем участникам. Чтобы ограничить его, настройте смарт-фильтр или смарт-скрипт, возвращающий `false` для тех, кому исходящие звонки не положены.

В форме настройки сервиса ВКС (`/spa/administration/services`) оба поля используют контрол выбора смарт-скриптов (`smart-script`): при выборе скрипта отображается его название, а клик по полю открывает редактор смарт-скриптов по адресу `/spa/administration/smart-script?id={SmartScriptId}`.

Пять дополнительных параметров в поле `ExtInfo` (JSON):

| Ключ | Назначение |
|------|------------|
| `externalModuleKey` | Ключ для доступа к API модуля ВКС |
| `roomCreationKey` | Ключ аутентификации Outlook-плагина при генерации временной комнаты |
| `recordHost` | Адрес хоста ссылок на записи ВКС |
| `recordsApiKey` | Ключ аутентификации для приёма событий записи ВКС |
| `internalModuleKey` | Внутренний ключ модуля |

⚠️ **Критичное предупреждение:** при смене `roomCreationKey` все пользователи должны **заново скачать плагин Outlook** — старый плагин не сможет создавать временные комнаты.

### Дефолтные настройки комнат и URL-шаблон

По умолчанию персональные комнаты (`user{id}`) создаются с: запись разрешена и авто-старт, транскрибация разрешена и авто-старт, лобби отключено.

Комнаты, создаваемые из плагина Outlook (при планировании встречи), также наследуют дефолтные настройки записи и транскрибации из `ConferenceDefaultUserRoomSettings`. Настройка лобби (`HasLobby`) этим путём из дефолтов не применяется.

![Меню конференции: «Начать запись», «Транскрибирование», «Настройки безопасности» и роль модератора в списке участников](https://help.1forma.ru/help-images/conferences/conferentions_start-10.png)

Начиная с v2.267 дефолты можно изменить через Admin API (требуются права God):

- `GET /api/admin/conference/default-user-room-settings` — получить текущие значения
- `POST /api/admin/conference/default-user-room-settings` — обновить значения

Настройки хранятся в `SettingsCustom` под ключом `ConferenceDefaultUserRoomSettings` (JSON, 5 полей):

```json
{
  "IsRecordingAllowed": true,
  "IsRecordingOnByDefault": true,
  "IsTranscribationAllowed": true,
  "IsTranscribationOnByDefault": true,
  "HasLobby": false
}
```

**Приоритет применения:**

1. Индивидуальные настройки комнаты (`ConferenceRooms`)
2. Настройки категории (`Subcategories` — только для task-комнат)
3. Дефолтные из `SettingsCustom.ConferenceDefaultUserRoomSettings`
4. Системные значения по умолчанию (запись/транскрибация разрешены и авто-старт, лобби выключено)

При невалидном JSON применяются системные значения по умолчанию, ошибка пишется в лог. Ключ создаётся автоматически при первом обращении.

Шаблон автоматически генерируемой ссылки на ВКС-комнату — `CustomSetting ConferenceRoomUrlTemplate`. Default: `https://{origin}/{room}`, где:

| Плейсхолдер | Значение |
|-------------|----------|
| `{origin}` | `Services.Conference.Domain` (адрес ВКС-сервиса) |
| `{room}` | Сгенерированный ID комнаты |

Пример переопределения (при использовании reverse-proxy с префиксом):
```
https://{host}/conference/?room={room}
```

Шаблон используется при формировании ссылок-приглашений в задачах и письмах.

### HTML-подпись приглашения ВКС

Подпись, которая должна вставляться при добавлении ссылки на конференцию в событие календаря, задаётся настройкой площадки `CustomSetting VksInviteSignatureHtml` — HTML-разметкой. Значение применяется на клиенте: когда в поле «Место встречи» события распознана ссылка на конференцию, подпись в описании события собирается из этого шаблона вместо стандартного текста. Подстановка работает в трёх точках — просмотр и редактирование встречи, создание встречи и карточка уведомления о встрече. Если настройка не заполнена, используется прежний текст по умолчанию.

Место ссылки в шаблоне обозначается маркером `{{link}}`. Маркер распознаётся независимо от регистра и лишних пробелов, в том числе с неразрывными пробелами и разорванный форматированием, а также когда он вставлен как адрес гиперссылки — тогда к адресу можно дописать путь или параметры, и хвост сохранится. Если маркера в шаблоне нет, под текстом подписи добавляется стандартная строка со ссылкой, чтобы участник не остался без неё. Сам литерал маркера в описание события не попадает ни при каком варианте шаблона.

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

Изменение вступает в силу без перезапуска сервера, но конфигурация площадки кешируется браузером: после сохранения шаблона новый текст появится со второго обновления страницы. Ранее созданные события не меняются — описание хранит готовый текст, собранный в момент создания или пересборки встречи. Встречи, созданные из плагина Outlook, остаются на стандартной подписи: у плагина свой шаблон.

Адрес конференции, который попадает в подпись, берётся из поля «Место проведения» встречи, а его правит пользователь, поэтому доверенным он не считается: ссылка собирается программно, адрес проставляется атрибутом готового элемента, а не склейкой текста. Кавычка или угловая скобка внутри адреса атрибут не разрывает. Само описание события при отрисовке проходит санитизацию, так что речь о корректности разметки, а не о закрытии уязвимости.

Редактировать подпись можно в администрировании, на странице «HTML-шаблон подписи ВКС»: разметка правится в визуальном редакторе, кнопка «Сбросить к умолчанию» возвращает стандартный вариант, а в незаполненном поле показан образец шаблона по умолчанию.

Управление — административными методами:

- `GET /api/admin/conference/invite-signature` — получить текущий шаблон
- `POST /api/admin/conference/invite-signature` — сохранить шаблон

Сохранение записывает значение в `SettingsCustom` и запускает пересборку файла настроек приложения; ключ входит в список отслеживаемых, поэтому изменение применяется без перезапуска сервера. Пустое значение сбрасывает подпись к варианту по умолчанию.

## Настройки телефонии, событий и комнат

Настройки IP-телефонии задаются через автоадминку в форме `telephony-settings` и хранятся в таблице `dbo.TelephonySettings`. 12 полей: URL сервера, учётные данные, параметры интеграции с телефонией. Определяет доступность звонка по клику (click-to-call) и обработку телефонных событий.

События телефонии настраиваются через автоадминку в форме `telephony-actions-packs` и хранятся в таблице `dbo.TelephonyActionsPacks`. 5 полей: привязка событий телефонии к действиям в системе. Определяет автоматические действия при входящих/исходящих звонках.

Настройки конкретной комнаты задаются через API `/api/conference/room/{roomId}/settings` и хранятся в таблице `dbo.ConferenceRooms`. Параметры: lobby, password, recording, transcribation. Задаются пользователем, но влияют на поведение через ту же конфигурационную таблицу.

## Типичные ошибки настройки конференций

Типичные проблемы с настройкой конференций и способы их диагностики:

| Симптом | Причина | Где проверить | SQL-диагностика |
|---------|---------|---------------|-----------------|
| Пользователь не может войти в комнату | Неверный домен/секрет Jitsi | Форма `vks-service-settings` | `select * from dbo.JitsiServiceSettings` |
| История участников пустая | Webhook-события не приходят или не обрабатываются | `dbo.ConferenceRoomsHistory`, `dbo.ConferenceRoomsUsers` | `select * from dbo.ConferenceRoomsHistory where RoomId = {roomId}; select * from dbo.ConferenceRoomsUsers where RoomId = {roomId}` |
| Транскрипт/видео не появились в задаче | Неверные QueueId/MessageFlowId или ошибка в пост-обработке | Форма `vks-service-settings` → поля очередей | `select QueueId, MessageFlowId from dbo.JitsiServiceSettings` |
| Настройки комнаты не применяются | Клиент использует устаревшие данные (кэш) | `dbo.ConferenceRooms` | `select * from dbo.ConferenceRooms where Id = {roomId}` |
| Телефония недоступна | Неверные настройки подключения | Форма `telephony-settings` | `select * from dbo.TelephonySettings` |

## Новый интерфейс ВКС: переключатель площадки

Настройка хранится в общих настройках приложения: в административной форме это поле «Новый интерфейс видеоконференций» в секции основных настроек, по умолчанию выключенное. Значение настройки попадает в статический файл конфигурации интерфейса, откуда его читает и веб-версия, и обёртка страницы конференции: при включённом значении обёртка не рисует родной тулбар видеосервиса и отдаёт панель управления приложению. Диагностика — значение поля «Новый интерфейс видеоконференций» в общих настройках приложения.

Панель управления и панель участников конференции может рисовать само приложение вместо родной панели видеосервиса Jitsi. Режим общий для всей площадки и для всех входов в конференцию — задача, чат, календарь, профиль, баннер вызова, десктопное приложение, прямая ссылка. Ручные параметры в адресе не требуются.

| Что | Значение |
|---|---|
| Хранение | настройка портала, ключ `EnableVksCustomToolbar` |
| Что получает клиент | ключ `VksCustomToolbarEnabled` статического файла конфигурации интерфейса |
| Значение по умолчанию | выключено: ключ отсутствует или `false` — во всех входах родная панель видеосервиса |

Настройка не входит в три уровня настроек ВКС (сервис → категория → комната) и пользователем не меняется: это выбор интерфейса для всей площадки, а не параметр комнаты.

⚠️ Переключение действует только на той сборке, где есть и серверная, и клиентская часть доработки. На более старой сборке настройки в конфигурации нет, и конференция всегда открывается с родной панелью. Отладочные переключатели на клиенте — ключ в локальном хранилище браузера и параметр адреса — сильнее настройки площадки, поэтому у отдельного пользователя интерфейс может отличаться от площадочного.