КЛЕВЕР объединяет несколько корпоративных сервисов в одном диалоге. Пользователь получает меню из пунктов‑цифр, выбирает нужный сервис и работает в его «режиме»; цифра 0 возвращает в главное меню, 9 — на уровень назад.

Ключевые принципы работы:

Единая точка входа. Все сервисы доступны из одного меню бота; в каждом — свои подпункты.
Меню на цифрах. Навигация цифрами и клавишами‑цифрами (1…9), что удобно на мобильных устройствах.
Живая сессия. Каждому пользователю ведётся своё состояние диалога; при длительном бездействии сессия автоматически сбрасывается в главное меню.
Меню под пользователя. Состав главного меню зависит от пользователя: например, раздел «Столовая» показывается только сотрудникам заводов, где он работает (определяется по организационным подразделениям AD).
Наблюдаемость. Собирается статистика использования (по модулям и действиям), ведётся логирование, контролируются ошибки и расход памяти; критические сбои дублируются на служебную почту.
Защита от спама и посторонних. Глобальные фильтры на входе: сообщения от других ботов игнорируются (анти‑цикл), а доступ к модулям ограничен корпоративными пользователями (whitelist).

Платформа: Python, asyncio, официальный SDK trueconf (WebSocket, версия 1.5.2 — совместимость с TrueConf Server 5.5.6). Код модульный — каждый сервис вынесен в отдельный модуль со своим роутером, что позволяет добавлять, отключать и развивать сценарии независимо.

Возможности (модули)

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

1️⃣ Личный кабинет

Подробное описание модуля (файлы, логика, источники данных): docs/lk.md

Cервис «самообслуживание» в чате: карточка сотрудника (компания, отдел, должность, стаж) и доступ к основным кадровым данным.

Расчётный лист — за выбранный месяц, защищён 2FA; текстовая разбивка + PDF.
Отпуска, больничные, командировки, награды, переводы — справки по соответствующим сведениям.
Табель учёта рабочего времени — недельный разбор и итоги за месяц.
Справки — заказ кадровых справок нескольких типов (2‑НДФЛ, удержания, средний заработок, пособия, исполнительные листы, копия трудовой книжки) с автоматической отправкой заявки в отдел кадров.

2️⃣ Столовая

Подробное описание модуля (файлы, логика, разведение по заводам): docs/cafe.md

Меню и заказы столовой АО ХК Сибцем: дни с доступным заказом, блюда с порциями ½/🥡, корзина, оформление заказа, история заказов с отменой. Для сотрудников АО «Ангарскцемент» — просмотр меню буфета на текущий день (завтрак/обед). Раздел виден только сотрудникам этих заводов; в тестовом режиме — объединённый экран с двумя блоками.

3️⃣ Расшифровка совещаний

Подробное описание модуля (файлы, логика, лимиты): docs/transcription.md

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

4️⃣ Service Desk

Создание и работа с заявками техподдержки: создание заявки по описанию проблемы, привязка к категории и исполнителю.

5️⃣ Изменение фотографии профиля

Подробное описание модуля (файлы, логика, проверки, модерация): docs/photo.md

Самостоятельная смена фотографии профиля: загрузка снимка в чат, автоматический кроп вокруг лица, превью для подтверждения, проверка качества (CV + ИИ на стороне корпоративного сайта), модерация и публикация в Active Directory. Модуль всегда показывает текущий статус (на модерации / отклонено с причиной / опубликовано). Поддерживается заглушка (PHOTO_STUB_MODE) — при недоступности сервера файлов пользователь получает сообщение о временной недоступности и ссылку на веб‑сервис смены фото.

6️⃣ Поиск по регламентам

Интеллектуальный поиск (RAG) по корпоративным регламентам: вопрос в чате — ответ со ссылкой на источник.

7️⃣ Инструкции по самостоятельной настройке

Подробное описание модуля (файлы, логика, проверка доступа, ServiceDesk): docs/instruct.md

Библиотека инструкций по самостоятельной настройке корпоративных сервисов (TrueConf и корпоративная почта на мобильном устройстве). Модуль проверяет реальное состояние пользователя (есть ли доступ, не создана ли уже заявка), присылает готовый файл‑инструкцию и при необходимости автоматически создаёт заявку в ServiceDesk. Включается флагом ENABLE_INSTRUCT (по умолчанию выключено).

Как устроен сервис (кратко)

Слой	Что делает
Ядро	Подключение к TrueConf, диспетчер событий, главное меню (динамическое, под пользователя), маршрутизация между модулями
Глобальные фильтры	Анти‑спам: игнорирование входящих от ботов; whitelist корпоративных пользователей до всех роутеров
Модули	Отдельные роутеры сервисов (ЛК, столовая, транскрипция, ServiceDesk, фото, поиск, инструкции)
Состояние	Хранение состояния диалога по пользователю, таймауты, возврат в меню; у каждого модуля — свой список состояний (entry‑guard роутера)
Конфигурация	Единый эталонный `config/config.py` (флаги модулей, лимиты, режимы); для каждого бота ключи дописываются скриптом `sync_config.py` без перезаписи файла бота; секреты выносятся в хранилище (passwork)
Интеграции	Active Directory (данные сотрудника, OU заводов), MS SQL (кадровые данные), веб‑ЛК Сибцем и Cart-API (столовая), API распознавания речи, ServiceDesk, SMTP (уведомления)
Надёжность	Мониторинг RAM и статистики, логирование (общий журнал + отдельные логи модулей), авто‑уведомления об ошибках с защитой от дублей

Каждый модуль — отдельная директория с файлом handlers.py (логика) и общими служебными пакетами utils/ (тексты, меню, состояние, статистика, AD-поиск). Это позволяет менять тексты, поведение и пороговые значения, не трогая остальной код.

Развёртывание: Docker; один репозиторий — единый код всех ботов (prod / beta / klever), различия — только в локальных config/config.py.

Документация

Статья	Содержимое
Личный кабинет	Состав модуля, файлы, логика работы, 2FA, SQL-таблицы
Столовая	Заказы ХК и буфет Ангарска, разведение по заводам, API, экраны
Расшифровка совещаний	Приём файла, лимиты, внешний API, уведомления об ошибках
Изменение фото профиля	Приём и кроп, превью, проверки, модерация, размещение в AD
Инструкции по настройке сервисов	Сценарии TrueConf/почта, проверка 2FA, авто-заявка в ServiceDesk
Обновления КЛЕВЕР	Хронология всех изменений проекта по датам

README.md Unescape Escape

КЛЕВЕР

О сервисе