.

README.md

@@ -0,0 +1,122 @@
+# 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 и приоритет на уровне отдела/темы.
+- Отчёты и выгрузку статистики по исполнителям.