Я.HR

Административная платформа - бот и веб админ-панель для управления пользователями и сообщениями, снижающая нагрузку на HR отдел.

📚 Оглавление

• 📌 Цели проекта
• 🧑‍💼 Роли пользователей
• 📦 Технологии
  • 🧠 Backend
  • 🤖 Telegram-бот
  • 🔐 Безопасность и аутентификация
  • 🖥️ Админ-панель
  • 💾 Хранение и кэш
• 🧪 Разработка и инструменты
• 🚀 Запуск проекта
  • ⚙️ Ruff и стилистика
  • 🐳 PostgreSQL и Redis в Docker
  • 🧬 Миграции
  • 🧪 Аудит и зависимости
• 🖥️ Запуск Docker Compose локально
• 🖥️ Деплой через Docker Compose
• ⚙️ CI/CD GitHub Actions

---

Цели проекта

• 📥 Быстрый доступ к HR-информации через Telegram-бота
• ⚙️ Управление контентом и пользователями через Web-интерфейс
• 🌐 Поддержка WebApps в Telegram для запуска админки прямо в боте
• 👥 Роли: Пользователь, HR-менеджер, Администратор

---

Роли пользователей

Роль	Возможности
user	Получает информацию от бота
manager	Управляет сообщениями
admin	Управляет пользователями, сообщениями, ролями, настройками

---

Технологии

Backend

Технология	Назначение
	Backend фреймворк
	ORM
	PostgreSQL драйвер
	Миграции
	Конфигурации

Telegram-бот

Технология	Назначение
	Асинхронный Telegram-бот
	Встраиваемая админка

Безопасность и аутентификация

Технология	Назначение
	Хеширование паролей
	Аутентификация

Админ-панель

Технология	Назначение
	UI для админки

Хранение и кэш

Технология	Назначение
	Кэш и сессии
	Хранение файлов

---

Разработка и инструменты

• Uvicorn — ASGI сервер
• Ruff — линтер и автоформаттер
• Pre-commit — хуки
• Pip-audit — проверка уязвимостей
• Pip-chill — заморозка зависимостей

---

Запуск проекта для разработки со стилизатором Ruff

Основное

1. Базовая версия Python - 3.11.
2. В файле requirements_style.txt находятся зависимости для стилистики.
3. В каталоге src находится базовая структура проекта
4. В файле src/requirements.txt прописываются базовые зависимости.
5. В каталоге infra находятся настроечные файлы проекта. Здесь же размещать файлы для docker compose.

Стилистика

Для стилизации кода используется пакеты Ruff и Pre-commit

Проверка стилистики кода осуществляется командой

ruff check

Если одновременно надо пофиксить то, что можно поиксить автоматически, то добавляем параметр --fix

ruff check --fix

Что бы стилистика автоматически проверялась и поправлялась при комитах надо добавить hook pre-commit к git

pre-commit install

Инструкция по запуску PostgreSQL и Redis в Docker

1. Настройка переменных окружения

   • Перейдите в директорию infra/
   • Создайте файл .env на основе примера:

     cp .env.example .env

   • Отредактируйте .env, указав свои настройки (логин, пароль, имя БД, токен)
   • Создайте в .env JWT_SECRET_KEY для верификации jwt токена:

   echo "JWT_SECRET_KEY=$(python -c 'import secrets; print(secrets.token_urlsafe(32))')" >> .env

2. Запуск базы данных

   • Выполните команду:

     docker compose -f docker-compose.yml up -d

   • Проверить работу контейнера:

     docker ps

3. Работа с базой данных

   • Для управления таблицами используйте любой DB-Viewer (DBeaver, TablePlus, pgAdmin)
   • Параметры подключения:
     • Хост: localhost
     • Порт: 5432
     • Данные для входа возьмите из файла .env

4. Остановка базы данных

   docker compose -f docker-compose.yml down

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

• Проверьте, что порт 5432 не занят
• Убедитесь, что значения в .env корректны
• Проверьте логи контейнера: docker logs <имя_контейнера>

Проверка уязвимостей

pip-audit -r src/requirements.txt

Пример успешного результата:

No known vulnerabilities found

Если есть уязвимости, инструмент предложит обновить версии пакетов.

Генерация компактного requirements.txt

pip-chill > src/requirements.txt

Запуск приложений

FastAPI (веб-админка)

python -m uvicorn src.api.run_fastapi:app --reload

Telegram бот

python -m src.bot.main

Миграции

Создание новой миграции

alembic revision --autogenerate -m "описание изменений"

Применение миграций

alembic upgrade head

Откат миграции

alembic downgrade -1

Запуск локально Docker Compose

Для проверки работоспособности проекта перед отправкой на удалённый сервер реализован локальный запуск

• для этого перейдите в директорию infra/
• заполните .env.pre-production по образцу .env.pre-production.example
• Выполните команду:

docker compose -f docker-compose.pre-production.yml up -d

Для остановки

docker compose -f docker-compose.pre-production.yml down

Деплой Docker-Compos

Для сборки собственных образов необходимо иметь аккаунт на https://hub.docker.com/ Сборка собственных образов и отправка на dockerhub. Из корневой директории проекта необходимо выполнить команды:

docker build -f infra/backend.Dockerfile -t you_docker_name/hr-backend:latest .
docker push you_docker_name/hr-backend:latest

docker build -f infra/bot.Dockerfile -t you_docker_name/hr-bot:latest .
docker push you_docker_name/hr-bot:latest

docker build -f infra/gateway.Dockerfile -t you_docker_name/hr-gateway:latest .
docker push you_docker_name/hr-gateway:latest

Измените названия образов на собственные в docker-compose.production.yml и можно его отправить на ваш удалённый сервер любым удобным образом. В директории с docker-compose.production.yml необходимо создать .env.production по образцу infra/.env.production

Настройка CI/CD через Action GitHub

Необходимо в репозитории проекта перейти

Settings -> Security -> Secrets and variable -> Actions -> Secrets и создать Secrets

POSTGRES_USER                   # имя пользователя PostgreSQL
POSTGRES_PASSWORD               # пароль пользователя
POSTGRES_DB                     # название базы данных
POSTGRES_SERVER                 # хост БД
POSTGRES_PORT                   # порт PostgreSQL
REDIS_SERVER                    # хост Redis
DOMAIN_NAME                     # ваш домен (например `https://example.com`)
BOT_NAME                        # имя бота
BOT_TOKEN                       # токен от @BotFather
ADMIN_NAME                      # логин админа
ADMIN_PASSWORD                  # пароль админа
ADMIN_TELEGRAM_ID               # ваш ID в Telegram
TEST                            # режим тестирования (`1` или `0`)
JWT_ALGORITHM                   # алгоритм подписи
JWT_ACCESS_TOKEN_EXPIRE_MINUTES # срок жизни токена
JWT_SECRET_KEY                  # секретный ключ (сгенерируйте случайную строку)
DOCKERHUB_USERNAME              # логин в DockerHub
DOCKERHUB_PASSWORD              # токен для DockerHub

CI/CD триггеры

Запуск деплоя

• При любом push в ветку develop
• При закрытии (merge/close) Pull Request в ветки develop и main

Не запускается при

• Прямых push в main (деплой в main только через PR)
• Push и PR в другие ветки, кроме develop и main
• Открытии и редактировании PR (только закрытие)