HR Personnel Tracker — Telegram Mini App & Bot

Сучасна система контролю присутності та переміщень співробітників у реальному часі через Telegram.

Взаємодія відбувається як через Telegram Mini App (інтерфейс додатка), так і за допомогою швидких текстових команд безпосередньо у чаті.

---

🚀 Основні можливості

1. Для співробітників

• Швидкі текстові команди у чаті — зміна статусу без відкриття будь-яких додатків за 1 секунду:
  • 🟢 /in (/прийшов, /тут) — початок робочого дня.
  • 🚗 /away (/виїзд, /поїхав) — виїзд у справах по місту.
  • ↩️ /back (/повернувся, /назад) — повернення з виїзду в офіс.
  • 🏠 /out (/додому, /пішов) — завершення зміни.
• Telegram Mini App (інтерфейс) — запуск в один клік:
  • Великі тактильні кнопки з Haptic Feedback.
  • Персональний таймлайн подій за поточний день.
  • Автоматична адаптація кольорів під тему Telegram (темна/світла).

2. Для керівника та команди

• Швидкий звіт у чаті (/status) — виводить список усіх співробітників, які зараз на роботі (в офісі чи на виїзді) із часом початку активності.
• Інтерактивний Дашборд (Mini App):
  • Загальна статистика (кількість людей в офісі, на виїзді, поза роботою).
  • Кольорові статуси з ефектом світіння (🟢 зелений — в офісі, 🟡 жовтий — у місті, ⚫ сірий — пішов додому).
  • Auto-refresh кожні 30 секунд (оновлення в реальному часі).
  • Клік на картку працівника відкриває детальну хронологію (таймлайн) його переміщень за день.

---

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

• Backend: Python (FastAPI + Uvicorn).
• Bot Engine: aiogram v3 (сучасний асинхронний фреймворк для Telegram-ботів).
• Database: SQLite (sqlite3 з активованим режимом WAL та потокобезпечним блокуванням).
• Frontend: Vanilla HTML5 + CSS3 + JS (SPA — Single Page Application).
• Mini App SDK: @telegram-apps/sdk (офіційний скрипт валідації та роботи з клієнтом).
• Security: Валідація initData на бекенді через HMAC-SHA256 (захист від підміни Telegram ID).

---

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

HR/
├── public/
│   ├── index.html           # Головна сторінка SPA (Employee + Dashboard)
│   ├── style.css            # Стилі з підтримкою темних тем та анімацій
│   └── app.js               # Клієнтська логіка та роутинг
├── src/
│   ├── server.py            # Запуск сервера FastAPI + Telegram Bot
│   ├── bot.py               # Логіка команд та клавіатур бота (aiogram)
│   ├── api.py               # Ендпоінти REST API (FastAPI)
│   ├── database.py          # Операції з SQLite
│   └── auth.py              # Валідація Telegram-сесій
├── data/
│   └── hr.db                # База даних SQLite (створюється автоматично)
├── .env                     # Конфігурація (ігнорується git)
├── requirements.txt         # Залежності Python
├── package.json             # npm-скрипти для зручності запуску
└── README.md

---

🔧 Встановлення та запуск (локально)

1. Створення віртуального оточення та встановлення залежностей

cd /Users/max/Work/HR

# Створення віртуального оточення
python3 -m venv venv

# Активація (для macOS/Linux)
source venv/bin/activate

# Встановлення залежностей
pip install -r requirements.txt

2. Налаштування .env

Створіть файл .env у корені проекту (можна скопіювати з .env.example):

BOT_TOKEN=8680508168:AAGWK-zNZqvQ_A1qETrmJM_iIBwoccHxFxc
WEBAPP_URL=https://your-ngrok-subdomain.ngrok-free.dev
APP_SHORT_NAME=staff
PORT=3000

3. Локальний запуск із тунелем ngrok

Для роботи Mini App у Telegram обов'язково потрібен HTTPS.

1. Запустіть локальний сервер. Це можна зробити двома способами:
   • Через Python безпосередньо:

     ./venv/bin/python -u -m src.server

   • Через npm-скрипт:

     npm run dev

2. В іншому вікні терміналу запустіть тунель ngrok:

   ngrok http 3000

3. Скопіюйте отриманий https://... URL від ngrok та вставте його у змінну WEBAPP_URL у файлі .env. Перезапустіть сервер.

---

🤖 Налаштування бота в @BotFather

Для коректної роботи Mini App в один клік без спливаючих вікон:

1. Створення Mini App:
   • Напишіть /newapp у @BotFather.
   • Оберіть вашого бота (@red_cross_staff_bot).
   • Введіть назву додатка (наприклад, Red Cross HR) та опис.
   • Надішліть іконку-зображення.
   • Введіть URL додатка — ваш HTTPS URL від ngrok (наприклад, https://xxxx.ngrok-free.dev/).
   • Вкажіть коротке ім'я (short name): staff (має збігатися з APP_SHORT_NAME в .env).
2. Вимкнення приватності для груп:
   • Напишіть /mybots → оберіть вашого бота → Bot Settings → Group Privacy → Turn off.
   • Це дозволить боту зчитувати команди /in, /out та інші безпосередньо у груповому чаті.
3. Налаштування нативних кнопок:
   • Напишіть /mybots → оберіть вашого бота → Bot Settings → Menu Button → вкажіть назву 📋 Відмітитися та URL додатка (https://xxxx.ngrok-free.dev/).
4. Реєстрація команд швидкого меню:
   • /mybots → ваш бот → Edit Bot → Edit Commands → вставте список команд:

     start - Відкрити меню управління
     status - Показати хто зараз на роботі
     dashboard - Відкрити веб-панель контролю
     

---

🔒 Безпека та бізнес-логіка

• Авторизація: Усі HTTP-запити до REST API підписуються хешем initData від Telegram. Бекенд валідує його через секретний ключ бота, перевіряючи час життя сесії (1 година). Сторонній доступ до даних без Telegram-клієнта неможливий.
• Валідація переходів (State Machine):
  • Користувач не може зареєструвати виїзд (field_trip), якщо він не відмітився на місці (in_office).
  • Не можна закінчити зміну (checkout), не прийшовши на роботу.
  • Бот надає лише валідні варіанти статусів на основі поточної позиції.