tg_zayavka/README.md

Telegram IT Ticket Bot

Бот создает IT-заявки по логике из блок-схемы: сотрудник выбирает направление, тему проблемы, получает короткую инструкцию, а если проблема не решена, бот собирает детали и сохраняет заявку в SQLite.

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

1. Создайте бота в Telegram через BotFather и получите токен.
2. Скопируйте настройки:

cp .env.example .env

3. Заполните .env:

BOT_TOKEN=ваш_токен
ADMIN_DEPARTMENTS=7350810301:IT;123456789:HR,Финансы
DATABASE_PATH=/app/data/tickets.db
SLA_MINUTES=60

ADMIN_DEPARTMENTS задает права администраторов по отделам:

telegram_id:Отдел
telegram_id:Отдел1,Отдел2

Пример: 7350810301:IT значит, что этот админ видит и управляет только заявками отдела IT.

4. Запустите:

docker compose up --build -d

5. Откройте Telegram и напишите боту /start.

Команды

/start - главное меню сотрудника.

/admin - панель администратора: сводка по статусам и фильтры заявок.

/find <номер> - открыть конкретную заявку по номеру (только для администраторов).

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

В разделе «Мои заявки» по активной заявке доступна кнопка «💬 Добавить комментарий»: текст попадает в историю заявки и приходит уведомлением исполнителю (а если заявку ещё не взяли — всем администраторам отдела). Внутренние заметки администраторов сотруднику не показываются.

Проверка дубликатов. Если перед созданием у сотрудника уже есть открытая заявка по той же теме, бот не плодит дубль, а предлагает выбор: «Дополнить заявку #N» (введённое описание и вложение уходят комментарием к существующей заявке и уведомлением исполнителю) или «Создать новую заявку». Если старая заявка к этому моменту уже закрыта, бот просто создаёт новую.

Чат с поддержкой. По активной заявке есть кнопка «💬 Чат с поддержкой» — это живое общение, а не комментарии: сотрудник просто пишет сообщения, они идут исполнителю (или администраторам отдела), «❌ Завершить чат» выходит из режима. Отдельная кнопка «💬 Добавить комментарий» остаётся для заметок к заявке.

Закрыть свою заявку. По активной заявке сотрудник может нажать «✅ Вопрос решён, закрыть» (с подтверждением) — если проблема решилась сама. Исполнителю уходит уведомление; при необходимости администратор может переоткрыть заявку.

Скриншот запрашивается только для темы «Ошибка программы». Для остальных тем шаг вложения пропускается. Шаг «удобное время визита» убран.

Панель администратора

/admin открывает дашборд со счётчиками (открытые, новые, в работе, ожидание, отложенные, просроченные) и кнопками-фильтрами, а также поиском по номеру и архивом. Из карточки заявки доступны действия по всему жизненному циклу:

• Взять в работу / Перехватить / Вернуть в работу — назначение на себя.
• Назначить — передать заявку другому администратору отдела.
• Закрыть — со своим текстом решения (а не фиксированным «Выполнено»).
• Отклонить — с указанием причины.
• В ожидание — статус «ждём ответа заявителя» с уведомлением сотрудника.
• Отложить — с выбором причины из готового списка «быстрых ответов» (ждём запчасти, согласуем время и т.д.) или своей причины; причина уходит заявителю и пишется в историю.
• Переоткрыть — вернуть закрытую/отклонённую заявку в работу.
• Приоритет — низкий / средний / высокий / критичный.
• Заметка — внутренний комментарий (не виден заявителю).
• Чат — живая переписка с заявителем. Исполнитель пишет сообщения (текст/фото), заявитель получает их и, нажав «💬 Ответить», входит в чат и просто пишет в ответ — без оформления «комментариев». Сообщения с обеих сторон попадают в историю заявки как переписка. «Закрыть чат» / «Завершить чат» завершает режим у каждой стороны.
• История — полный журнал изменений по заявке.

Статусы: Новая, В работе, Ожидание ответа, Отложена, Закрыта, Отклонена. Новые заявки создаются с приоритетом «средний»; приоритет меняет администратор.

SLA и эскалация

Дедлайн считается от времени создания плюс SLA_MINUTES. Просроченные заявки помечаются 🔴 в списках и карточке. Фоновая задача раз в минуту находит просроченные заявки и один раз отправляет администраторам отдела уведомление об эскалации.

Данные

SQLite-база хранится в ./data/tickets.db, каталог подключен в контейнер как volume. При запуске на старой базе схема мигрирует автоматически (добавляются поля приоритета, SLA и таблицы истории/пользователей) — данные не теряются.

Таблицы:

• tickets — заявки (статус, приоритет, исполнитель, время создания, SLA-флаг).
• ticket_events — журнал событий и комментарии по каждой заявке.
• users — имена пользователей/администраторов (для отображения исполнителя).

Что удобно добавить перед интеграцией с сайтом

• Авторизацию по телефону, корпоративному ID или коду.
• Экспорт заявок и истории в API будущего сайта.
• Настраиваемый SLA и приоритет на уровне отдела/темы.
• Отчёты и выгрузку статистики по исполнителям.