HR Automation Bot — это корпоративное решение для автоматизации HR-коммуникаций и работы с запросами сотрудников через удобный Telegram-бот. В проект входит:
- Асинхронный сервер на FastAPI (backend + OpenAPI + API)
- Веб-админка (на базе SQLAdmin/Jinja2) для управления пользователями, контентом, HR-запросами
- Телеграм-бот для сотрудников завода с авторизацией, интерактивными меню, заявками HR
- Единая интеграция: все части разворачиваются и обновляются в рамках одного монорепозитория
- Единая административная панель для управления сотрудниками, деревом контента, картинками, заявками HR
- Импорт пользователей из Excel-файлов через админку
- Интеграция с Telegram-ботом
- Гибкое дерево информации (узлы, кнопки, изображения) с быстрым обновлением контента
- Открытое API с документацией OpenAPI/Swagger
- Полная докеризация: быстрый запуск, обновление и деплой на сервер через Docker Compose
- Автоматический деплой через GitHub Actions: тесты, сборка, публикация Docker-образов и автозагрузка на сервер
- Авторизация сотрудников по Telegram ID
- Быстрые заявки HR, просмотр и отслеживание их статусов
- Навигация по информационному дереву (разделы, инструкции, документы)
- Интерактивные меню, кастомные кнопки
Типовой сценарий
- Сотрудник запускает бота и проходит авторизацию.
- Получает меню с возможными действиями.
- Может создать и отслеживать свой HR-запрос (вопрос, отпуск, пропуск и пр.).
- Получает ответы HR прямо в Telegram.
- Управление всеми пользователями (роли, Telegram ID, статус, доступ)
- Импорт сотрудников из Excel (шаблон в интерфейсе)
- Редактирование дерева информации (узлы, кнопки, вложенность, изображения)
- Просмотр и обработка HR-заявок (отправка ответов в Telegram)
OpenAPI/Swagger
Основные эндпоинты:
- /api/v1/login/ — логин (JWT)
- /api/v1/logout/ — логаут
- /api/v1/auth/telegram — Telegram-авторизация
- /api/v1/nodes/root — корневой узел
- /api/v1/nodes/{id} — конкретный узел
- /api/v1/hr-request — создать HR-запрос
- /api/v1/hr-requests — HR-запросы пользователя
- /api/v1/import-users/upload — импорт пользователей
infra/ # Dockerfile, docker-compose, .env
backend/ # Dockerfile backend
bot/ # Dockerfile Telegram-бота
data/ # fixtures и тестовые данные
src/
app/ # FastAPI-приложение (backend + админка)
admin/ # SQLAdmin-панель
api/ # API endpoints (включая OpenAPI-спеку)
endpoints/ # Конкретные реализации эндпоинтов
core/ # Конфиги, инициализация, база
models/ # SQLAlchemy-модели
schemas/ # Pydantic-схемы
services/ # Бизнес-логика
static/ # css/js/images для админки
scripts/ # Скрипты для загрузки данных
main.py # Точка входа backend
bot/ # Исходники Telegram-бота
handlers.py # Обработчики команд и сообщений
keyboards.py # Кастомные клавиатуры
callbacks.py # Обработчик колбэков
backend_client.py # Взаимодействие с backend API
config.py # Конфигурация бота
constants.py # Константы для бота
main.py # Точка входа бота
services.py # Вспомогательные сервисы бота
render.py # Обработка и отображение узлов
alembic/ # Миграции базы данных
versions/ # Файлы миграций
node_images/ # Изображения для информационных узлов
templates/ # Jinja2-шаблоны для админки (SQLAdmin)
requirements-admin.txt # Зависимости для админки/бэкенда
requirements-bot.txt # Зависимости для бота
requirements-dev.txt # Dev-зависимости
requirements_style.txt # Стиль/линтеры
ruff.toml # Конфиг линтера ruff
README.md # Документация
git clone repo
cd hr_bot_zavod/infra
cp .env.example .env # или создайте свой .env по примеру ниже
docker-compose up -d- Backend: http://localhost:8000
- Swagger UI: http://localhost:8000/docs
- Админка: http://localhost:8000/admin
- Сервер с Linux (Ubuntu 22.04+ рекомендуется)
- Docker и Docker Compose установлены - инструкция
- Выделенный домен с SSL (рекомендуется настроить через nginx/reverse-proxy)
- Созданы секреты и переменные окружения для деплоя
mkdir -p /opt/lavka
cd /opt/lavka
# Скопируйте docker-compose.production.yml в /opt/lavka/docker-compose.yml
# Добавьте .env (пример ниже)docker compose pull
docker compose up -d
docker compose exec backend alembic -c src/alembic.ini upgrade headdocker compose exec backend python -m src.app.scripts.load_data- Backend: https://ваш_домен/
- Swagger: https://ваш_домен/docs
- Админка: https://ваш_домен/admin
docker-compose down- Запуск тестов, миграций и сборка Docker-образов на CI
- Публикация образов на Docker Hub
- Копирование и запуск обновлённых контейнеров на сервере по SSH
- Загрузка новых данных при обновлении
on:
push:
branches: [ main ]
jobs:
# ... (тесты и сборка)
deploy:
steps:
- copy docker-compose.yml на сервер через ssh
- docker compose pull && docker compose down && docker compose up -d
- docker compose exec backend python -m src.app.scripts.load_data- Доступ по SSH (через ключ), настроенные переменные окружения и Actions.
# --- Настройки базы данных ---
POSTGRES_USER=your_db_user
POSTGRES_PASSWORD=your_db_password
POSTGRES_DB=your_db_name
POSTGRES_SERVER=db
POSTGRES_PORT=5432
# --- Настройки backend ---
SECRET=your_secret_key
first_superuser_login=your_admin_login
first_superuser_password=your_admin_password
first_superuser_full_name=Your Admin Name
root_node_name=StartNode
root_node_text=Welcome to the bot!
# --- Telegram-бот ---
BOT_TOKEN=ваш_токен_бота
BACKEND_URL=http://backend:8000 # URL backend для бота
STACK_LIMIT=20 # Глубина истории в дереве
STOP_WORDS=["word1","word2","word3"] # Доп. слова для фильтрации запросов от пользователей
# --- Docker репозиторий для сборки контейнеров ---
DOCKER_REPO=docker_repo_name- Проверьте, что все сервисы docker-compose работают (docker compose ps)
- Убедитесь, что все переменные .env корректны и заданы
- Миграции и начальные данные выполняются только изнутри контейнера backend
- Для импорта пользователей используйте шаблон Excel из админки
Если нужна помощь по настройке или развитию бота, обратитесь к администрации проекта или откройте issue в репозитории.