HR Notification Bot 🤖

Система автоматизации внутренних HR-уведомлений с поддержкой Telegram и REST API.

Курсовой проект для РЭУ им. Г.В. Плеханова Тема: "Автоматизация внутренней системы для информирования сотрудников и взаимодействия с HR"

---

🎯 Описание проекта

HR Notification Bot - это комплексная система для автоматизации информирования сотрудников компании. Система состоит из двух компонентов:

1. Telegram Бот - интерактивный интерфейс для сотрудников
2. REST API - программный интерфейс для интеграции с корпоративными системами

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

✅ Массовая рассылка уведомлений всем сотрудникам ✅ Персонализированные сообщения конкретным пользователям ✅ Управление новостями компании ✅ Система ролей (администраторы HR / сотрудники) ✅ REST API для интеграции с внешними системами ✅ Красивый интерфейс с кнопками в Telegram

---

📋 Функционал

Telegram Бот

Для всех сотрудников:

• /start - Начало работы с ботом (показывает кнопки меню)
• /help - Список всех команд
• /news - Просмотр последних новостей от HR
• /company - Список всех сотрудников компании

Для HR-администраторов:

• /add_news <текст> - Добавить новость в систему
• /broadcast <текст> - Массовая рассылка всем сотрудникам
• /send <username> <текст> - Личное сообщение конкретному сотруднику

REST API

Метод	Endpoint	Описание
GET	/api/health	Проверка работоспособности API
GET	/api/users	Получить список всех пользователей
POST	/api/news	Добавить новость
POST	/api/broadcast	Массовая рассылка всем сотрудникам
POST	/api/send	Отправить сообщение конкретному пользователю

---

🚀 Быстрый старт

1. Установка зависимостей

# Клонировать репозиторий
git clone <repository-url>
cd HR

# Создать виртуальное окружение
python3 -m venv venv

# Активировать виртуальное окружение
source venv/bin/activate  # для macOS/Linux
# или
venv\Scripts\activate  # для Windows

# Установить зависимости
pip install -r requirements.txt

2. Создание Telegram бота

1. Откройте Telegram и найдите @BotFather
2. Отправьте команду /newbot
3. Введите имя бота (например: HR Helper)
4. Введите username бота (должен заканчиваться на bot)
5. BotFather пришлет вам токен

3. Настройка конфигурации

# Скопируйте пример конфига
cp config.example.py config.py

# Откройте config.py и вставьте ваш токен от BotFather
nano config.py

4. Настройка пользователей

Откройте database.py и замените тестовые chat_id на реальные:

test_users = [
    (YOUR_CHAT_ID, 'your_username', 'Your Name', 1),  # Администратор
]

Чтобы узнать свой chat_id, напишите боту @userinfobot в Telegram.

5. Запуск системы

Для Windows (проще всего): Двойной клик по файлу start.bat - он автоматически установит зависимости и запустит систему!

Для macOS/Linux или вручную:

python main.py

Вы должны увидеть:

============================================================
  HR NOTIFICATION BOT - Система HR-уведомлений
============================================================

🌐 Запуск REST API на http://localhost:5001
🤖 Запуск Telegram бота...
✅ Telegram бот запущен и готов к работе!

Готово! Система запущена и работает:

• Telegram бот доступен в мессенджере
• REST API доступен по адресу http://localhost:5001

---

📡 Примеры использования API

Проверка работоспособности

curl http://localhost:5001/api/health

Ответ:

{
  "status": "ok",
  "message": "HR Notification Bot API is running",
  "version": "1.0.0"
}

Получение списка пользователей

curl http://localhost:5001/api/users

Добавление новости

curl -X POST http://localhost:5001/api/news \
  -H "Content-Type: application/json" \
  -d '{"text": "Завтра выходной день!"}'

Массовая рассылка

curl -X POST http://localhost:5001/api/broadcast \
  -H "Content-Type: application/json" \
  -d '{"message": "Внимание всем! Важное объявление от HR"}'

Личное сообщение

curl -X POST http://localhost:5001/api/send \
  -H "Content-Type: application/json" \
  -d '{"username": "mark", "message": "Напоминаю про встречу в 15:00"}'

---

🎬 Демонстрация проекта

Подробная инструкция по демонстрации проекта преподавателю находится в файле DEMO.md.

Она включает:

• Пошаговый сценарий демонстрации
• Примеры запросов для Postman
• Ответы на возможные вопросы
• Технические детали проекта

---

🏗️ Архитектура проекта

HR/
├── main.py              # Точка входа - запуск бота и API
├── bot.py               # Логика Telegram бота
├── api.py               # REST API эндпоинты (Flask)
├── database.py          # Работа с базой данных (SQLite)
├── config.py            # Конфигурация (токен бота)
├── requirements.txt     # Зависимости Python
├── database.db          # База данных SQLite (создается автоматически)
├── README.md            # Документация
└── DEMO.md              # Инструкция по демонстрации

Технологии:

• Python 3 - язык программирования
• python-telegram-bot 20.7 - библиотека для работы с Telegram Bot API
• Flask 3.0.0 - микрофреймворк для создания REST API
• SQLite - встроенная реляционная база данных

---

💾 База данных

Таблица users

Поле	Тип	Описание
id	INTEGER	Автоинкремент (PK)
chat_id	INTEGER	Telegram chat_id (уникальный)
username	TEXT	Username пользователя
full_name	TEXT	Полное имя пользователя
is_admin	INTEGER	Флаг администратора (0/1)
created_at	TEXT	Дата регистрации

Таблица news

Поле	Тип	Описание
id	INTEGER	Автоинкремент (PK)
text	TEXT	Текст новости
created_at	TEXT	Дата создания

---

🔒 Безопасность

• Система ролей: только администраторы могут отправлять массовые рассылки
• Валидация входных данных в API
• Хранение токена бота в отдельном конфигурационном файле (не в Git)
• SQLite защита от SQL-инъекций через параметризованные запросы

Рекомендации для production:

• Использовать HTTPS для API
• Добавить API-ключи для авторизации запросов
• Использовать PostgreSQL вместо SQLite
• Добавить логирование всех действий
• Настроить rate limiting для API

---

📊 Применение в реальной компании

Эта система может использоваться для:

1. Оперативного информирования:

   • Изменения в графике работы
   • Экстренные объявления
   • Напоминания о важных событиях

2. Автоматизации HR-процессов:

   • Приветствие новых сотрудников
   • Напоминания о дедлайнах
   • Уведомления о корпоративных событиях

3. Интеграции с корпоративными системами:

   • 1C может автоматически отправлять уведомления через API
   • Корпоративный портал может публиковать новости
   • CRM может информировать сотрудников о важных событиях

---

🎓 Образовательная ценность

Проект демонстрирует:

• ✅ Работу с Telegram Bot API
• ✅ Создание REST API на Flask
• ✅ Работу с базами данных (SQLite)
• ✅ Многопоточность (одновременная работа бота и API)
• ✅ Архитектуру современных веб-приложений
• ✅ Интеграцию различных систем
• ✅ Практическое применение для автоматизации бизнес-процессов

---

📞 Поддержка

При возникновении вопросов или проблем:

1. Проверьте DEMO.md - там есть ответы на частые вопросы
2. Убедитесь что токен бота правильно указан в config.py
3. Проверьте что в database.py указаны реальные chat_id

---

Готово к использованию! 🚀