Битрикс24 Модуль Бот контроля присутствия сотрудников в Bitrix24 v1.0.0

Ключевые возможности​

• Геолокационный контроль: Автоматическая проверка нахождения сотрудника в офисе по GPS-координатам
• Интеграция с Bitrix24: Полная интеграция с чатами и пользователями Bitrix24
• Автоматический учет времени: Фиксация времени прихода, ухода и опозданий
• Умная отчетность: Автоматическое формирование отчетов о нарушениях
• Безопасная аутентификация: OAuth 2.0 авторизация через Bitrix24
• Административный интерфейс: Управление графиками и настройками в Bitrix24

Технологический стек​

Backend ( Node.js)​

• Express.js: Веб-фреймворк для создания API и обработки запросов
• Axios: HTTP-клиент для взаимодействия с Bitrix24 REST API
• PostgreSQL: Реляционная база данных для хранения отметок времени
• JWT/JsonWebToken: Аутентификация и авторизация запросов
• Node-cron: Планировщик задач для генерации отчетов
• Dotenv: Управление переменными окружения
• CORS: Middleware для обработки кросс-доменных запросов

Frontend (Bitrix24)​

• Bitrix24 REST API: Интеграция с платформой Bitrix24
• Bitrix24 Chat API: Взаимодействие с чат-интерфейсом
• OAuth 2.0: Протокол авторизации для безопасного доступа
• JavaScript/TypeScript: Клиентская логика чат-бота

DevOps & Infrastructure​

• Render.com/Heroku: Платформа для развертывания и хостинга
• Docker: Контейнеризация приложения (опционально)
• Git: Система контроля версий
• PM2: Менеджер процессов Node.js

Архитектура системы​

graph TD
    A[Мобильное приложение Bitrix24] -->|Нажатие кнопки| B[Чат-бот Bitrix24]
    B -->|Запрос геолокации| C[GPS устройства]
    C -->|Координаты| B
    B -->|REST API запрос| D[Внешний сервер]
    D -->|Валидация| E[(База данных)]
    D -->|Отчет| F[Email руководителя]
    D -->|Ответ| B
    B -->|Сообщение| A
    G[Cron-скрипт] -->|Ежедневная проверка| E
    G -->|Генерация отчетов| F

Алгоритм работы бота​

1. Вход в систему: Сотрудник открывает мобильное приложение Bitrix24
2. Выбор действия: Открывает чат-бот "Отметиться на работе"
3. Запрос геоданных: Бот запрашивает GPS-координаты с разрешения пользователя
4. Передача данных: Отправка данных на сервер обработки
5. Валидация: Проверка геолокации и временных рамок
6. Сохранение: Запись результата в базу данных
7. Отчетность: Ежедневная генерация отчетов о нарушениях
8. Администрирование: Управление через интерфейс Bitrix24

Быстрый старт (Установка и запуск)​

Предварительные требования​

• Node.js версии 16.x или выше
• PostgreSQL версии 12.x или выше
• Аккаунт Bitrix24 с доступом к REST API
• Git для управления версиями
• Доступ к серверу для развертывания (Render.com, Heroku, VPS)

Инструкция по запуску​

git clone https://github.com/your-organization/bitrix24-attendance-bot.git
cd bitrix24-attendance-bot

PORT=3000
DATABASE_URL=postgresql://username:password@localhost:5432/attendance_db
BITRIX24_CLIENT_ID=your_client_id
BITRIX24_CLIENT_SECRET=your_client_secret
BITRIX24_DOMAIN=yourcompany.bitrix24.com
JWT_SECRET=your_jwt_secret_key
OFFICE_LATITUDE=55.7558
OFFICE_LONGITUDE=37.6173
ALLOWED_RADIUS=50
ALLOWED_DELAY_MINUTES=15
REPORT_EMAIL=manager@company.com

Доступ к приложению​

Использование​

1. Откройте мобильное приложение Bitrix24
2. Найдите чат-бот "Отметиться на работе"
3. Нажмите "Пришёл" или "Ушёл"
4. Разрешите доступ к геолокации
5. Получите подтверждение отметки

1. Откройте Bitrix24 в веб-браузере
2. Перейдите в раздел "Учет рабочего времени"
3. Просматривайте журнал отметок
4. Настраивайте графики работы
5. Получайте ежедневные отчеты на email

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

1. Обработка геолокации​

• Endpoint: POST /api/attendance/mark

{
  "user_id": 123,
  "event_type": "arrival",
  "latitude": 55.7558,
  "longitude": 37.6173,
  "timestamp": "2024-01-15T09:00:00Z",
  "access_token": "bitrix24_access_token"
}

{
  "success": true,
  "message": "Отметка успешно зафиксирована",
  "status": "on_time",
  "distance_from_office": 25.3
}

2. Получение статистики​

• Endpoint: GET /api/attendance/stats/:user_id

• start_date: Начальная дата (YYYY-MM-DD)
• end_date: Конечная дата (YYYY-MM-DD)

{
  "user_id": 123,
  "period": "2024-01-01 - 2024-01-15",
  "total_work_days": 11,
  "on_time_arrivals": 9,
  "late_arrivals": 2,
  "early_departures": 1,
  "absent_days": 0,
  "average_arrival_time": "09:05"
}

3. Генерация отчетов​

• Endpoint: POST /api/reports/generate

{
  "report_type": "daily",
  "date": "2024-01-15",
  "department_id": 5
}

{
  "report_id": "report_20240115",
  "status": "generated",
  "download_url": "/api/reports/download/report_20240115.pdf",
  "summary": {
    "total_employees": 45,
    "violations": 3,
    "absent_today": 2
  }
}

Настройка в Bitrix24​

• Зайдите в настройки Bitrix24
• Раздел "Приложения" → "Добавить приложение"
• Выберите тип "Вебхук" или "Чат-бот"

• Укажите URL вашего сервера
• Получите Client ID и Client Secret
  • user - доступ к информации о пользователях
  • im - доступ к чатам
  • department - доступ к структуре компании

• Раздел "Чат-боты" → "Создать бота"
• Укажите название: "Отметиться на работе"
• Настройте команды: "пришел", "ушел"
• Привяжите к вашему приложению

• В настройках приложения добавьте вебхуки:
  
  • Для просмотра ссылки Вы должны войти или зарегистрироваться.
    - для обработки событий
  • Настройте события: OnImMessageAdd, OnImCommandAdd

• Создайте кастомное приложение в Bitrix24
• Настройте интерфейс для просмотра статистики
• Добавьте настройки геозоны и графиков работы

Структура проекта​

bitrix24-attendance-bot/
├── src/
│   ├── controllers/
│   │   ├── attendance.controller.js    # Обработка отметок
│   │   ├── report.controller.js        # Генерация отчетов
│   │   └── user.controller.js          # Управление пользователями
│   ├── models/
│   │   ├── user.model.js              # Модель пользователя
│   │   ├── attendance.model.js        # Модель отметок
│   │   ├── geozone.model.js           # Модель геозоны
│   │   └── report.model.js            # Модель отчетов
│   ├── services/
│   │   ├── bitrix24.service.js        # Сервис Bitrix24 API
│   │   ├── geolocation.service.js     # Сервис геолокации
│   │   ├── report.service.js          # Сервис отчетов
│   │   └── notification.service.js    # Сервис уведомлений
│   ├── middleware/
│   │   ├── auth.middleware.js         # Аутентификация
│   │   ├── validation.middleware.js   # Валидация данных
│   │   └── error.middleware.js        # Обработка ошибок
│   ├── routes/
│   │   ├── attendance.routes.js       # Маршруты отметок
│   │   ├── report.routes.js           # Маршруты отчетов
│   │   ├── user.routes.js             # Маршруты пользователей
│   │   └── webhook.routes.js          # Маршруты вебхуков
│   ├── utils/
│   │   ├── validators.js              # Валидаторы данных
│   │   ├── helpers.js                 # Вспомогательные функции
│   │   ├── constants.js               # Константы проекта
│   │   └── cron.js                    # Планировщик задач
│   └── app.js                         # Основной файл приложения
├── config/
│   ├── database.js                    # Конфигурация БД
│   ├── bitrix24.js                    # Конфигурация Bitrix24
│   └── constants.js                   # Общие константы
├── migrations/                        # Миграции базы данных
├── scripts/                           # Вспомогательные скрипты
│   ├── deploy.sh                      # Скрипт деплоя
│   └── backup.sh                      # Скрипт резервного копирования
├── tests/                             # Тесты
│   ├── unit/                          # Юнит-тесты
│   └── integration/                   # Интеграционные тесты
├── docs/                              # Документация
│   ├── api.md                         # API документация
│   └── setup.md                       # Инструкция по настройке
├── .env.example                       # Пример переменных окружения
├── package.json                       # Зависимости проекта
├── docker-compose.yml                 # Конфигурация Docker
├── Dockerfile                         # Docker конфигурация
└── README.md                          # Документация проекта