🤖 Бот-Вопросник

Телеграм-бот для организации системы вопросов и ответов в корпоративной среде с поддержкой форумов, таймеров активности и статистики.

📋 Оглавление

• Описание
• Возможности
• Требования
• Установка и запуск
• Настройка окружения
• Структура проекта
• Использование
• База данных

🎯 Описание

Бот-Вопросник — это корпоративное решение для автоматизации процесса обработки вопросов сотрудников. Бот создает форумные топики для каждого вопроса, отслеживает активность диалогов, предоставляет статистику и поддерживает систему ролей.

✨ Возможности

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

• 📝 Создание вопросов с автоматическим созданием топиков
• 🔗 Прикрепление ссылок на регламенты
• 🔄 Возврат закрытых вопросов в работу
• ⭐ Оценка качества помощи
• 📊 Просмотр личной статистики

👨‍💼 Для старших/дежурных:

• 💬 Взятие вопросов в работу
• ⏰ Автоматическое отслеживание бездействия
• 🎯 Оценка самостоятельности специалистов
• 🔓 Переоткрытие вопросов
• 🚀 Освобождение вопросов

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

• 📈 Выгрузка статистики в Excel
• 🎭 Смена ролей пользователей
• ⚙️ Управление настройками бота

🤖 Автоматические функции:

• ⏲️ Таймеры бездействия с предупреждениями
• 🗑️ Автоматическое удаление старых вопросов
• 📱 Уведомления о премиум-эмодзи
• 🔄 Автоматическое закрытие неактивных диалогов

🛠 Требования

• Python 3.13+
• Docker и Docker Compose
• Microsoft SQL Server
• Microsoft ODBC Driver 18 for SQL Server

🚀 Установка и запуск

1. Клонирование репозитория

git clone <repository-url>
cd questioner-bot

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

Скопируйте файл примера и настройте его:

cp .env.dist .env

Отредактируйте файл .env согласно инструкции по настройке.

3. Запуск через Docker Compose

# Сборка и запуск
docker-compose up --build

# Запуск в фоновом режиме
docker-compose up -d

# Просмотр логов
docker-compose logs -f bot

4. Остановка

docker-compose down

⚙️ Настройка окружения

Создайте файл .env на основе .env.dist и заполните следующие параметры:

🔑 Основные настройки

# Токен бота от @BotFather
BOT_TOKEN=123456:Your-TokEn_ExaMple

# Направление работы (НТП или НЦК)
DIVISION=НТП

# Использование Redis (пока не реализовано)
USE_REDIS=False

🎛 Настройки функциональности

# ID форума в Telegram для создания топиков
FORUM_ID=1234567890

# Запрашивать ссылку на регламент перед отправкой вопроса
ASK_CLEVER_LINK=True

# Автоматическое удаление старых вопросов
REMOVE_OLD_QUESTIONS=True
REMOVE_OLD_QUESTIONS_DAYS=60

# Система таймеров бездействия
ACTIVITY_STATUS=True
ACTIVITY_WARN_MINUTES=5    # Предупреждение о бездействии
ACTIVITY_CLOSE_MINUTES=10  # Автозакрытие при бездействии

🗄️ База данных

# Параметры подключения к SQL Server
DB_HOST=your-sql-server.com
DB_USER=your_username
DB_PASS=your_password

# Имя основной базы данных
DB_MAIN_NAME=STPMain

💾 Redis (опционально)

# Настройки Redis для кеширования
REDIS_HOST=redis_cache
REDIS_PORT=6379
REDIS_DB=1
REDIS_PASSWORD=your_redis_password

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

questioner-bot/
├── bot.py                          # Точка входа приложения
├── docker-compose.yml              # Конфигурация Docker Compose
├── Dockerfile                      # Образ Docker
├── pyproject.toml                  # Зависимости Python
├── uv.lock                         # Lockfile для uv
├── alembic.ini                     # Конфигурация миграций
├── .env.dist                       # Пример переменных окружения
├── infrastructure/                 # Инфраструктурный слой
│   ├── database/                   # Работа с базой данных
│   │   ├── models/                 # Модели SQLAlchemy
│   │   │   ├── base.py
│   │   │   ├── user.py             # Модель пользователя
│   │   │   └── question.py         # Модель вопроса
│   │   ├── repo/                   # Репозитории для работы с данными
│   │   │   ├── base.py
│   │   │   ├── users.py            # Операции с пользователями
│   │   │   ├── questions.py        # Операции с вопросами
│   │   │   └── requests.py         # Объединение репозиториев
│   │   └── setup.py                # Настройка подключения к БД
│   └── migrations/                 # Миграции базы данных
└── tgbot/                          # Телеграм-бот
    ├── config.py                   # Конфигурация приложения
    ├── handlers/                   # Обработчики событий
    │   ├── admin/                  # Админские функции
    │   │   ├── main.py             # Основные админ-команды
    │   │   └── stats_extract.py    # Выгрузка статистики
    │   ├── user/                   # Пользовательские функции
    │   │   ├── main.py             # Основные команды
    │   │   ├── active_question.py  # Работа с активными вопросами
    │   │   └── return_question.py  # Возврат вопросов
    │   └── group/                  # Групповые функции
    │       ├── main.py             # Обработка топиков
    │       └── cmds.py             # Команды в топиках
    ├── keyboards/                  # Inline клавиатуры
    │   ├── admin/                  # Админские клавиатуры
    │   └── user/                   # Пользовательские клавиатуры
    ├── filters/                    # Фильтры для обработчиков
    ├── middlewares/                # Промежуточное ПО
    ├── services/                   # Сервисы
    │   ├── broadcaster.py          # Рассылка сообщений
    │   ├── logger.py               # Настройка логирования
    │   └── scheduler.py            # Планировщик задач
    └── misc/                       # Вспомогательные модули
        ├── states.py               # FSM состояния
        ├── dicts.py                # Словари и константы
        └── helpers.py              # Вспомогательные функции

📖 Использование

👤 Для сотрудников

1. Запуск бота: /start
2. Создание вопроса: Нажать "🤔 Задать вопрос"
3. Отправка текста: Написать вопрос одним сообщением
4. Прикрепление регламента: Добавить ссылку на clever (если требуется)
5. Ожидание ответа: Вопрос появится в форуме
6. Общение: Переписка идет через бот
7. Закрытие: Нажать "✅ Закрыть вопрос" или команда /end
8. Оценка: Оценить качество помощи

👨‍💼 Для старших

1. Взятие в работу: Написать любое сообщение в топике
2. Общение: Переписка через топики транслируется специалисту
3. Закрытие: Команда /end или кнопка "✅ Закрыть вопрос"
4. Оценка: Оценить самостоятельность специалиста
5. Освобождение: Команда /release для передачи другому старшему

🔧 Для администраторов

1. Админ-панель: /start → админские кнопки
2. Статистика: "📥 Выгрузка статистики" → выбор периода
3. Смена роли: "👶🏻 Стать спецом" для тестирования

🗃️ База данных

В боте используется две базы:

1. question_repo - БД QuestionerBot
2. main_repo - БД STPMain или STPMainTemp

Команды:

1. Генерация миграции: alembic revision --autogenerate -m "Create tables" --sql
2. Применение миграций: alembic upgrade head