Speller

Speller — микросервис проверки орфографии. Используется в интерфейсах Webim для подсветки ошибок и выдачи вариантов исправления. Поддерживаются русский и английский языки. Возможна работа с внешним провайдером орфографии по настройке аккаунта. Сервис не хранит пользовательские данные и не изменяет тексты автоматически.

Функции

Сервис обладает следующими функциями:

проверка слов и фраз на орфографические ошибки;
предложения корректных вариантов замены;
учёт аккаунтных словарей: разрешённых (spelling_dict) и запрещённых (forbidden_spelling_dict) слов;
использование внешнего провайдера орфографии по настройкам аккаунта совместно со встроенными словарями Webim; при этом слова, присутствующие в spelling_dict, считаются корректными и вообще не отправляются во внешний спеллер;
публикация метрик для мониторинга.

Настройки аккаунта

Работа Speller зависит от ряда параметров account config.

Основные параметры:

Параметр	Назначение
`disable_spell_check`	Полностью отключает проверку орфографии для аккаунта. При `true` обращения к сервису не выполняются из интерфейсов.
`spell_check_force`	Принудительно включает проверку орфографии для аккаунта. При `true` проверка выполняется для всех операторов, оператор не может отключить её в интерфейсе.
`server_dicts_spell_check`	Включает использование и управление аккаунтными словарями (`spelling_dict`, `forbidden_spelling_dict`, `candidate_spelling_dict`) при проверке текста. При `false` раздел управления словарями в интерфейсе аккаунта недоступен.
`spelling_dict`	JSON-словарь корректных слов. Слова из этого словаря считаются написанными правильно и не подлежат исправлению; сервис не отправляет их во внешний спеллер.
`forbidden_spelling_dict`	JSON-словарь запрещённых слов. Слова из этого словаря всегда считаются некорректными и не могут быть добавлены в список корректных слов. При этом они отправляются во внешний спеллер, и по ним предлагаются варианты исправления.
`candidate_spelling_dict`	JSON-словарь слов-кандидатов, ожидающих подтверждения администратором в интерфейсе управления словарём.

Подробное описание этих параметров и работы словаря приведено в статье «Настройка проверки орфографии и словаря».

Сетевые требования

Сервис доступен по HTTP на порту 8000/tcp. Все клиентские запросы обрабатываются на этом же порту. Номер порта задаётся переменной окружения API_WEB_PORT (значение по умолчанию — 8000).

Метрики Prometheus доступны по пути /metrics на HTTP-порте сервиса.

Для hosted-клиентов необходимо открыть следующие порты для узла со Speller. Указаны значения по умолчанию; актуальные порты следует уточнять по .env файла сервиса.

Направление	Назначение	Порт/протокол	Примечание
Входящие	HTTP-API Speller	`API_WEB_PORT` (по умолчанию 8000/tcp)	Для балансировщика/прокси и доступа к `/metrics`.
Исходящие	Бэкенд Webim	443/tcp	Загрузка настроек аккаунта, проверка сессии операторов и другие запросы к основному бэкенду.
Исходящие	Кэш (Redis)	порт, указанный в `REDIS_CACHE_LOCATION`	Доступ к Redis, используемому сервисом Speller.
Исходящие	Внешний провайдер орфографии (опционально)	443/tcp	Используется при включении соответствующей опции в редакторе настроек аккаунта.

Переменные окружения

Работа микросервиса Speller настраивается через файл .env. Ниже перечислены основные параметры, влияющие на сеть и взаимодействие с бэкендом.

Переменная	Назначение
`REDIS_CACHE_LOCATION`	Строка подключения к Redis (host, порт, номер базы), используемому для кэша сервиса. Например: `redis://redis:6379/1`.
`API_WEB_PORT`	Порт HTTP-API Speller, в том числе endpoint `/metrics`.
`SENTRY_DSN`	DSN для отправки логов и ошибок в Sentry.
`SENTRY_ENV`	Имя окружения (environment) для Sentry.
`ACCOUNT_NAME`	Имя аккаунта Webim, от имени которого выполняются запросы к бэкенду.
`ROOT_URL_FORMAT`	Шаблон базового URL для обращения к бэкенду Webim. Например: `https://{account_name}.webim.ru`; вместо `{account_name}` сервис подставит имя аккаунта.
`ASPELL_DIR`	Путь к системным словарям `aspell` на сервере.
`REQUEST_TIMEOUT`	Тайм-аут в секундах для HTTP-запросов Speller к бэкенду Webim и внешним провайдерам (проверка сессии оператора, загрузка настроек аккаунта, запросы к внешнему спеллеру). По умолчанию имеет значение `10`.

Масштабирование и отказоустойчивость

Сервис имеет stateless-архитектуру, горизонтально масштабируется за балансировщиком L7. При масштабировании требуется общий кэш (Redis) для всех экземпляров.

Рекомендуемая схема масштабирования:

Подготовить общий Redis.
Запустить несколько экземпляров Speller.
Распределять трафик через балансировщик/ingress.
Подключить сбор метрик с /metrics и алертинг.

Логирование и мониторинг

Логи приложения пишутся в стандартный вывод процесса и включают: запуск/останов, параметры окружения запуска, обработанные запросы, ошибки сети и кэша, таймауты. Технические метрики доступны на /metrics и могут быть собраны Prometheus.

Speller обеспечивает проверку орфографии и подсказки исправлений в Webim. Для корректной работы требуется доступ по HTTP на порту 8000, подключение к кэшу и (при необходимости) к внешнему провайдеру орфографии. Сервис масштабируется горизонтально и публикует метрики и логи для оперативного контроля.