Telegram-бот для HR-отдела: учет сотрудников, кадровые изменения, уведомления и отчеты. Google Sheets — основная база данных: все изменения сразу видны в таблице.

Стек: Python 3.11+ · aiogram 3 · gspread

---

✨ Функционал

Раздел	Возможности
👥 Сотрудники	Список крупными кнопками (2 в ряд), пагинация; фильтры: все / работают / уволены / испытательный срок / по отделам / по филиалам
👤 Карточка	Все данные + автоподсчет стажа и статуса; редактирование любого поля
➕ Добавление	Пошаговый мастер с выбором из справочников, «Нет руководителя», предпросмотром; ID выдается автоматически (EMP-0001)
🔍 Поиск	Мгновенный поиск по ФИО, должности, отделу
🔄 Перевод	Изменение должности/отдела/руководителя с подтверждением и записью в историю
📤 Увольнение	Причина, дата, комментарий → статус в таблице + лист «Уволенные»
📜 История	Полный журнал кадровых изменений по каждому сотруднику
🔔 Уведомления	Дни рождения (за 3 дня и в день), годовщины работы, окончание испытательного срока, новые сотрудники — с защитой от повторов
☀️ Дайджест	Ежедневная сводка по всем событиям в заданное время
📊 Отчеты	HR-отчет за день / неделю / месяц / прошлый месяц
⚙️ Настройки	Пользователи и роли, время дайджеста, вкл/выкл уведомлений, часовой пояс, справочники

🔐 Роли и доступ

Роль	Права
👑 Администратор	Всё + управление пользователями
🧑‍💼 HR	Всё, кроме панели пользователей
👔 Руководитель	Просмотр сотрудников, поиск, карточки

Защита от ошибок: нельзя поменять свою роль, нельзя удалить или понизить последнего администратора.

📖 Как пользоваться

1. Найдите бота в Telegram и отправьте /start
2. Если вас еще нет в системе — доступ выдает администратор (бот подскажет ваш Telegram ID)
3. Главное меню:
   • 👥 Сотрудники — фильтр → список → карточка
   • ➕ Добавить — мастер из 10 шагов, на любом шаге можно вернуться или отменить
   • 🔍 Поиск — введите ФИО или должность
   • 🎉 События — ближайшие дни рождения и годовщины
   • 📊 Отчет — статистика приемов/переводов/увольнений
   • ⚙ Настройки — только для HR и админов
4. В карточке сотрудника: ✏ Редактировать, 🔄 Перевод, 📤 Уволить, 📜 История

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

pip install -r requirements.txt

# 1. Создайте бота у @BotFather -> получите BOT_TOKEN
# 2. Google Cloud: включите Sheets API -> сервисный аккаунт -> JSON-ключ
# 3. Скопируйте .env.example в .env и заполните
# 4. Дайте сервисному аккаунту доступ Editor к вашей таблице

python main.py

Переменные .env:

Переменная	Описание
BOT_TOKEN	токен от @BotFather
SPREADSHEET_ID	ID таблицы Google Sheets
GOOGLE_CREDENTIALS_FILE	путь к JSON-ключу сервисного аккаунта
ADMIN_IDS	Telegram ID админов через запятую (добавляются при старте)
TIMEZONE	пояс по умолчанию, например Europe/Moscow
DEFAULT_DIGEST_TIME	время дайджеста ЧЧ:ММ

📊 Структура таблицы

Бот работает с одной Google-таблицей и сам создает все листы при первом запуске — достаточно расшарить таблицу сервисному аккаунту с правом редактирования. Заполнять вручную не нужно, но структура такая:

Лист	Колонки
Сотрудники	ID, ФИО, Телефон, Пол, Отдел, Должность, Филиал, Руководитель, Дата рождения, Дата приема, Дата окончания испытательного срока, Дата увольнения, Статус, Комментарий, Дата создания записи, Кто внес запись
История	ID сотрудника, ФИО, Дата изменения, Тип изменения, Старое значение, Новое значение, Комментарий, Кто внес изменение
Увольнения	ID, ФИО, Должность, Отдел, Филиал, Дата приема, Дата увольнения, Причина увольнения, Комментарий, Кто оформил увольнение
События	Дата отправки, Тип события, Ключ события, ID сотрудника, ФИО, Описание, Кому отправлено, Время отправки
Справочники	Отделы, Должности, Филиалы, Руководители, Причины увольнения
Пользователи	Telegram ID, Имя, Роль (admin / hr / manager), Уведомления, Дата добавления, Кем добавлен
Настройки	Ключ, Значение

Даты — в формате ДД.ММ.ГГГГ. Уведомления (ДР/годовщины/испытательный срок) считаются по данным листа «Сотрудники»; лист «События» — служебный журнал от повторных рассылок.

🧪 Тесты

pytest tests              # 32 юнит-теста (без сети)
python scripts/e2e_check.py    # 73 сквозных сценария через реальный диспетчер
python scripts/check_setup.py  # диагностика окружения

📁 Структура

main.py                  # входная точка
bot/handlers/            # обработчики: сотрудники, переводы, настройки...
bot/services/            # Google Sheets, авторизация, уведомления, бэкапы
bot/keyboards.py         # все клавиатуры
scripts/                 # seed демо-данных, e2e, диагностика
tests/                   # юнит-тесты + фейки без сети

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

• Секреты только в .env (не коммитится) и JSON-ключе сервисного аккаунта
• Ежедневные JSON-бэкапы всех листов в backups/
• Ротация логов в logs/