Интеграция 1С с локальным мессенджером on-premise: опыт развёртывания на мини-ПК

Продолжение статьи: DevOps для 1С на практике: как я развернул домашний сервер за 14 дней и 32 часа

Репозиторий проекта: github.com/VladimirProgrammist1C/1c-home-server
Расширение интеграции: ВЧ_ИнтеграцияСVoceChat

Введение

В предыдущей статье мы разобрали, как поднять изолированную среду для 1С на мини-ПК: PostgreSQL в Docker, мониторинг, бэкапы, безопасный доступ через Tailscale. Но техническая часть — это только фундамент. Вторая половина задачи — бизнес-логика.

Зачем это нужно? На собеседованиях 1С-разработчиков часто спрашивают: «Есть ли опыт интеграции с внешними системами через REST/SOAP? Как обрабатываете ошибки и таймауты?». Если коммерческого опыта пока нет, его можно смоделировать самостоятельно — на учебном проекте.

В этом проекте я реализовал интеграцию 1С:ЗУП 3.1 с VoceChat — мессенджером, развёрнутым on-premise (как в крупных организациях). Данные не покидают периметр, нет зависимости от облачных блокировок, полный контроль над инфраструктурой. И да, всё это работает на обычном мини-ПК (Geekom A9 Max), реализовано силами одного человека, без бюджета на лицензии.

Что вы получите: готовое решение можно адаптировать под любой локальный мессенджер и особенности вашей организации. Отработаете навыки: асинхронные очереди, HTTP-запросы, обработка ошибок, документирование.

Цель статьи — показать, как спроектировать и реализовать отказоустойчивую интеграцию «по-взрослому», но в домашних условиях. С ТЗ, архитектурными решениями, асинхронной очередью и готовым кодом.

🔝 К содержанию

📋 Содержание

1. Бизнес-кейс: от идеи до требований
2. Архитектурные решения
3. Техническая реализация
4. Сценарии тестирования
5. Журнал уведомлений: контроль и управление
6. Фоновая миграция исторических данных
7. Быстрая настройка
8. Результаты и метрики
9. Что можно улучшить (Roadmap)
10. Исходный код и документация
11. Об авторе

Бизнес-кейс: от идеи до требований

🎯 Проблема

При приёме нового сотрудника кадровик проводит документ «Приём на работу» в 1С:ЗУП. Без автоматического уведомления системные администраторы узнают об этом с задержкой: в лучшем случае 30–60 минут (через почту), в худшем — несколько недель, если заявка «потеряется» в потоке писем или устных поручений. В результате новый сотрудник не получает доступы к 1С, почте, корпоративным ресурсам, что тормозит его адаптацию и создаёт простои.

📋 Целевое состояние

🟡 Технические требования

• Совместимость: Не изменять типовые объекты ЗУП 3.1. Обновление конфигурации от вендора не должно ломать интеграцию.
• Безопасность: Ключи API не хранить в открытом коде. Маскировать в интерфейсе.
• Производительность: Задержка проведения документа ≤ 200 мс.
• Отказоустойчивость: При недоступности мессенджера задача не теряется, а повторяется автоматически (до 3 попыток).

🔝 Наверх

Архитектурные решения

🔴 Отклонённые варианты

Изначально рассматривался вариант добавления кнопки [Отправить в чат] на форму документа «Приём на работу». Этот вариант был отвергнут:

• Кнопка на форме «Приём на работу» требует ручного действия (человеческий фактор), блокирует проведение документа синхронным HTTP-запросом, а при обновлении ЗУП типовая форма может измениться, что приведёт к ошибкам совместимости.

🟢 Принятая архитектура: Producer-Consumer

Глобальный переключатель в настройках оказался предпочтительнее реквизита формы. Он централизован, безопасен для обновлений и позволяет одним кликом отключить интеграцию на время массовой загрузки или тестов, не меняя интерфейсы документов.

Ключевые принципы:

1. Асинхронность: Проведение документа не ждёт ответа сервера мессенджера. Задача просто ставится в очередь.
2. Защита от дублей: Уведомление формируется только при первом проведении документа (Источник.ЭтоНовый() И Не Источник.Проведен).
3. Изоляция: Вся логика инкапсулирована в расширении. Типовая конфигурация остаётся чистой.

🔝 Наверх

Техническая реализация

📦 Структура расширения (фрагмент)

На скриншоте показаны только ключевые объекты метаданных. Полная структура включает также подсистемы, роли, общие команды и формы.

Основные компоненты:

🔄 Механизм повторных попыток

Логика ретраев инкапсулирована в общем модуле ВЧ_ОбработчикиСобытий. Регламентное задание вызывает процедуру Обработать(), которая:

1. Читает лимит попыток из константы ВЧ_МаксимальноеКоличествоПопыток
2. Выбирает задачи со статусом Ожидает отправки через виртуальную таблицу СрезПоследних()
3. Фильтрует записи по условию ПопыткиОтправки < МаксПопыток
4. Для каждой задачи извлекает текст из ХранилищеЗначения и отправляет через ВЧ_ИнтеграцияСервер
5. Обновляет статус через процедуру ОбновитьСтатусЗадачи()

// Общий модуль ВЧ_ОбработчикиСобытий
&НаСервере
Процедура Обработать() Экспорт
    
    МаксПопыток = ПолучитьМаксимальноеКоличествоПопыток();
    ОчередьСообщений = ПолучитьОчередьСообщений(МаксПопыток);
    
    Для Каждого ЭлементОчереди Из ОчередьСообщений Цикл
        ОбработатьЭлементОчереди(ЭлементОчереди);
    КонецЦикла;
    
КонецПроцедуры

&НаСервере
Функция ПолучитьМаксимальноеКоличествоПопыток()
    
    МаксПопыток = Константы.ВЧ_МаксимальноеКоличествоПопыток.Получить();
    Возврат Макс(МаксПопыток, 1);
    
КонецФункции

&НаСервере
Функция ПолучитьОчередьСообщений(Знач МаксПопыток)
    
    Запрос = СоздатьЗапросОчередиСообщений();
    Запрос.УстановитьПараметр("СтатусОжидает", Перечисления.ВЧ_СтатусыУведомлений.Ожидает);
    Запрос.УстановитьПараметр("ТекущаяДата", ТекущаяДатаСеанса());
    Запрос.УстановитьПараметр("МаксПопыток", МаксПопыток);
    
    Возврат Запрос.Выполнить().Выгрузить();
    
КонецФункции

&НаСервере
Функция СоздатьЗапросОчередиСообщений()
    
    Запрос = Новый Запрос;
    Запрос.Текст = "
    |ВЫБРАТЬ
    |   Очередь.ИДСообщения КАК ИДСообщения,
    |   Очередь.Период КАК Период,
    |   Очередь.ДокументОснование КАК ДокументОснование,
    |   Очередь.ТекстСообщения КАК ТекстСообщения,
    |   Очередь.IDКанала КАК IDКанала,
    |   Очередь.ПопыткиОтправки КАК ПопыткиОтправки
    |ИЗ
    |   РегистрСведений.ВЧ_ОчередьУведомлений.СрезПоследних(
    |           &ТекущаяДата, 
    |           Статус = &СтатусОжидает
    |				И ПопыткиОтправки < &МаксПопыток) КАК Очередь
    |УПОРЯДОЧИТЬ ПО
    |   Очередь.Период ВОЗР";
    
    Возврат Запрос;
    
КонецФункции

&НаСервере
Процедура ОбработатьЭлементОчереди(Знач Элемент)
    
    Попытка
        Результат = ОтправитьУведомление(Элемент);
        ОбновитьСтатусЗадачи(Элемент.ИДСообщения, Элемент.Период, Результат);
    Исключение
        ТекстОшибки = ОписаниеОшибки();
        ЗаписатьОшибкуВЖурнал("Ошибка отправки уведомления: " + ТекстОшибки, Элемент.ДокументОснование);
        ОбновитьСтатусЗадачи(Элемент.ИДСообщения, Элемент.Период, СоздатьРезультатОшибки(ТекстОшибки));
    КонецПопытки;
    
КонецПроцедуры

Ключевые особенности:

• Использование СрезПоследних() для работы с периодическим регистром
• Разделение логики на мелкие функции (принцип единственной ответственности)
• Обработка исключений с логированием в журнал регистрации
• Транзакционное обновление статуса через НаборЗаписей

🔝 Наверх

Сценарии тестирования

Для проверки работоспособности и отказоустойчивости решения были разработаны 7 тестовых сценариев. Все они успешно пройдены на тестовом контуре:

Дополнительно: Все события интеграции логируются в журнал регистрации с именем ВЧ_Интеграция с уровнями Информация, Предупреждение и Ошибка — это упрощает диагностику при сбоях в production.

🔝 Наверх

Журнал уведомлений: контроль и управление

Для визуального контроля процесса отправки реализована обработка ВЧ_ЖурналУведомлений:

• Фильтры: по периоду, статусу («Ожидает отправки»/«В обработке»/«Отправлено»/«Ошибка отправки»), документу «Приём на работу», сотруднику.
• Действия:
  • Повторить отправку — сбрасывает статус на «Ожидает отправки» и счётчик попыток (для администраторов).
  • Удалить — удаляет записи из истории (с подтверждением, только администраторам).
  • Перейти к документу — открывает документ «Приём на работу» из записи журнала.
• Безопасность: через ролевую модель — кадровик видит только свои документы, администратор имеет полный доступ (роль ВЧ_АдминистраторИнтеграции).

🔝 Наверх

Фоновая миграция исторических данных

При добавлении ресурса Сотрудник в регистр ВЧ_ОчередьУведомлений (версия расширения ≥ 2.1.0) старые записи остались с пустым значением. Чтобы не ломать фильтры и аналитику, реализована фоновая обработка ВЧ_ПерезаполнениеСотрудникаВРегистреУведомлений:

• Пакетная обработка (по 100 записей за транзакцию) — не блокирует работу пользователей.
• Прогресс и логирование в журнал регистрации (событие ВЧ_ЗаполнениеСотрудников).
• Запускается от имени администратора интеграции.

Это пример «взрослого» подхода к работе с историческими данными: миграция выполняется фоном, с контролем прогресса и возможностью отката, без влияния на основную работу системы.

🔝 Наверх

Быстрая настройка

1. Установить расширение build/ВЧ_ИнтеграцияСVoceChat_v2.1.0.cfe через Конфигуратор.
2. В режиме Предприятия открыть форму ВЧ_НастройкиИнтеграции.
3. Включить переключатель ВЧ_ИспользоватьИнтеграцию (поля станут активными).
4. Заполнить URL, Порт, BotAPIKey и ID канала.
5. Для проверки связи перейти в подсистему Интеграция с мессенджером → Тестирование отправки и нажать Выполнить тест.

🔝 Наверх

Результаты и метрики

Все 7 сценариев тестирования (TC-01...TC-07) прошли успешно. Ошибки корректно логируются в журнал регистрации с уровнями Информация, Предупреждение и Ошибка.

🔝 Наверх

Что можно улучшить (Roadmap)

• v3.0.0: Уведомления по другим кадровым событиям:
  • Кадровый перевод (смена подразделения/должности → изменение прав доступа)
  • Увольнение (отзыв доступов сотрудника)
  • Отпуск (временное делегирование прав другому сотруднику)
• v4.0.0: Расширение функционала журнала:
  • Шаблоны сообщений для разных типов событий
  • История изменений статуса с комментариями
  • Экспорт статистики отправки (Excel/PDF)
• v5.0.0: Уведомления из других конфигураций:
  • УТ: уведомления менеджерам по контрагентам
  • БП: уведомления бухгалтерам о новых документах
  • УНФ: уведомления о заказах клиентов

🔝 Наверх

Исходный код и документация

Проект полностью открыт. Вы можете склонировать репозиторий, адаптировать интеграцию под любой локальный мессенджер и использовать в своих задачах.

Об авторе

Владимир Бессонов
🔗 GitHub | 📄 Лицензия: MIT

💡 Не ждите «идеального» коммерческого проекта, чтобы прокачать навыки интеграции. Домашний сервер + открытая задача + публичное репо = портфолио, которое работает на вас.

Есть вопросы по реализации? Пишите в комментариях или создавайте Issue на GitHub — с радостью помогу! 🚀

🔝 Наверх