123 lines
8.3 KiB
Markdown
123 lines
8.3 KiB
Markdown
# Telegram IT Ticket Bot
|
||
|
||
Бот создает IT-заявки по логике из блок-схемы: сотрудник выбирает направление, тему проблемы, получает короткую инструкцию, а если проблема не решена, бот собирает детали и сохраняет заявку в SQLite.
|
||
|
||
## Быстрый старт
|
||
|
||
1. Создайте бота в Telegram через BotFather и получите токен.
|
||
2. Скопируйте настройки:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
3. Заполните `.env`:
|
||
|
||
```env
|
||
BOT_TOKEN=ваш_токен
|
||
ADMIN_DEPARTMENTS=7350810301:IT;123456789:HR,Финансы
|
||
DATABASE_PATH=/app/data/tickets.db
|
||
SLA_MINUTES=60
|
||
```
|
||
|
||
`ADMIN_DEPARTMENTS` задает права администраторов по отделам:
|
||
|
||
```env
|
||
telegram_id:Отдел
|
||
telegram_id:Отдел1,Отдел2
|
||
```
|
||
|
||
Пример: `7350810301:IT` значит, что этот админ видит и управляет только заявками отдела `IT`.
|
||
|
||
4. Запустите:
|
||
|
||
```bash
|
||
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 и приоритет на уровне отдела/темы.
|
||
- Отчёты и выгрузку статистики по исполнителям.
|