Helpdesk — Self-hosted система поддержки клиентов

Система поддержки с веб-чатом, базой знаний и интеграцией с Telegram. Клиенты общаются через веб-виджет или Telegram-бот, операторы отвечают через операторский интерфейс или напрямую из Telegram-группы с топиками.

---

Функциональность

Тикеты и чат

• Клиент создаёт обращение через виджет или пишет боту в Telegram
• Оператор отвечает через операторский интерфейс или прямо в Telegram-топике
• Три вида отображения списка тикетов: строки, карточки, сплит (список + чат рядом)
• Внутренние заметки операторов (не видны клиенту)
• Теги на тикетах с цветовой маркировкой
• История закрытых обращений в виджете
• Вложения (фото, файлы) в обоих направлениях

Операторы и компании

• Роли: admin и operator
• Привязка операторов к конкретным компаниям (оператор видит только свои тикеты)
• При создании топика в Telegram — @упоминание операторов нужной компании
• Рабочие часы и часовой пояс для каждого оператора
• Автоответ клиенту вне рабочих часов (в виджете и в Telegram)
• Статус онлайн/офлайн (переключается вручную в сайдбаре)
• Двухфакторная аутентификация (TOTP) для операторов

База знаний

• Статьи с Markdown-редактором
• Видимость: публичная (все клиенты), ограниченная (по компаниям), приватная (только операторы)
• Три вида отображения: строки, карточки, сплит (список + редактор рядом)
• Привязка статей к тикетам

Быстрые ответы

• Шаблоны фраз для операторов
• Вызов через / прямо в поле ответа — автодополнение с поиском

Оценка качества поддержки

• После закрытия тикета клиенту предлагается поставить оценку (1–5 звёзд)
• В виджете: форма со звёздами и необязательным комментарием
• В Telegram: инлайн-кнопки прямо в чате с ботом
• Оценка отображается в карточке тикета; обновляется в реальном времени

Аналитика

• Тикеты по дням (создано / закрыто) — график
• Сводка: всего, открыто, в работе, закрыто, среднее время закрытия, средний рейтинг
• Статистика по операторам: количество тикетов, закрыто, рейтинг, среднее время
• Распределение по приоритетам
• Фильтр по периоду: 7 / 14 / 30 / 90 дней
• Экспорт в CSV (открывается в Excel без кракозябр)

Уведомления

• Push-уведомления в браузере (Web Push)
• Уведомления в Telegram при новых тикетах и сообщениях
• Звуковые уведомления в операторском интерфейсе
• WebSocket для обновлений в реальном времени

Портал самообслуживания

• Отдельный портал для клиентов с публичными статьями базы знаний
• Авторизация через Telegram Mini App

---

Стек технологий

Компонент	Технология
Backend	FastAPI (Python 3.12) + aiogram 3.x
База данных	PostgreSQL 16 (внешний сервер)
Кэш	Redis 7
Хранилище файлов	MinIO
Frontend	React 18 + Vite + TailwindCSS
Reverse proxy	Caddy (внешний сервер)
Деплой	Docker Compose

---

Требования к инфраструктуре

• ВМ 1 (Docker) — запускает backend, фронтенды, Redis, MinIO
• ВМ 2 (PostgreSQL) — внешний сервер PostgreSQL 16
• ВМ 3 (Caddy) — reverse proxy, SSL-терминация

Все три роли можно объединить на одном сервере — это не обязательное разделение.

---

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

helpdesk/
├── backend/                # FastAPI приложение
│   ├── app/
│   │   ├── api/            # Эндпоинты (tickets, operators, clients, analytics, ...)
│   │   ├── bot/            # Telegram бот (aiogram 3)
│   │   ├── models/         # SQLAlchemy модели
│   │   ├── schemas/        # Pydantic схемы
│   │   ├── services/       # Бизнес-логика (tickets, work_hours, attachments, ...)
│   │   ├── auth.py         # JWT авторизация
│   │   ├── websocket.py    # WebSocket менеджер
│   │   └── main.py         # Точка входа
│   ├── alembic/            # Миграции БД (0001–0018)
│   ├── create_admin.py     # Скрипт создания администратора
│   └── requirements.txt
├── frontend/
│   ├── admin/              # Операторский интерфейс (порт 3000)
│   ├── widget/             # Клиентский виджет (порт 3001)
│   └── portal/             # Портал самообслуживания (порт 3002)
├── docker-compose.yml
├── Caddyfile               # Для внешней ВМ с Caddy
└── .env.example

---

Деплой

1. Подготовка PostgreSQL (ВМ 2)

CREATE DATABASE helpdesk;
CREATE USER helpdesk WITH PASSWORD 'ваш_пароль';
GRANT ALL PRIVILEGES ON DATABASE helpdesk TO helpdesk;
-- PostgreSQL 15+:
ALTER DATABASE helpdesk OWNER TO helpdesk;

Разрешите подключение с IP ВМ с Docker в pg_hba.conf:

host    helpdesk    helpdesk    <IP_DOCKER_VM>/32    scram-sha-256

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

cd helpdesk
cp .env.example .env
nano .env

Обязательно заполните:

• DATABASE_URL — подключение к PostgreSQL
• JWT_SECRET — случайная строка минимум 32 символа
• MINIO_ROOT_USER, MINIO_ROOT_PASSWORD — учётные данные MinIO
• TELEGRAM_BOT_TOKEN, TELEGRAM_GROUP_ID — для Telegram интеграции

3. Запуск

cd helpdesk
docker compose up -d --build

Контейнер backend при старте автоматически выполняет миграции Alembic.

4. Создание первого администратора

docker compose exec backend python create_admin.py

5. Настройка Caddy (ВМ 3)

Скопируйте Caddyfile на ВМ с Caddy, замените <IP_DOCKER_VM> на реальный IP:

helpdesk-admin.example.com {
    reverse_proxy <IP_DOCKER_VM>:3000
}

helpdesk.example.com {
    reverse_proxy <IP_DOCKER_VM>:3001
}

helpdesk-portal.example.com {
    reverse_proxy <IP_DOCKER_VM>:3002
}

helpdesk-api.example.com {
    reverse_proxy <IP_DOCKER_VM>:8000
}

caddy reload

---

Настройка Telegram бота

1. Создайте бота через @BotFather, получите токен
2. Создайте Telegram группу, включите режим Супергруппа и Топики (Forum)
3. Добавьте бота в группу как администратора с правами:
   • Управление сообщениями
   • Управление топиками
4. Получите ID группы (можно через @userinfobot)
5. Укажите TELEGRAM_BOT_TOKEN и TELEGRAM_GROUP_ID в .env

Связь оператора с Telegram аккаунтом

Чтобы ответы из Telegram привязывались к конкретному оператору:

1. Операторы → выберите оператора → укажите Telegram ID
2. Telegram ID (числовой) можно узнать через @userinfobot

---

Порты

Сервис	Порт
Backend (FastAPI)	8000
Admin frontend	3000
Widget frontend	3001
Portal frontend	3002
MinIO API	9000
MinIO Console	9001

---

Роли пользователей

Роль	Возможности
admin	Всё + управление операторами, клиентами, настройками, аналитика
operator	Тикеты, база знаний, быстрые ответы, аналитика
client	Создание тикетов, переписка, история обращений, оценка поддержки

---

Управление операторами

Настройка	Где
Рабочие часы и автоответ	Профиль оператора или Операторы (для admin)
Привязка к компаниям	Операторы → редактировать
Статус онлайн/офлайн	Сайдбар (переключатель внизу)
Telegram ID	Операторы → редактировать
2FA (TOTP)	Профиль → Двухфакторная аутентификация

---

API документация

После запуска доступна по адресу: http://localhost:8000/docs

---

Обновление

git pull
docker compose down
docker compose up -d --build

Миграции применяются автоматически при старте backend.

---

Устранение неполадок

Backend не стартует — ошибка подключения к БД:

docker compose logs backend
# Проверьте DATABASE_URL в .env

MinIO недоступен:

docker compose logs minio
# Консоль MinIO: http://<IP_DOCKER_VM>:9001

Telegram бот не создаёт топики:

• Убедитесь, что группа — супергруппа с топиками
• Бот должен быть администратором с правом управления топиками
• Проверьте TELEGRAM_GROUP_ID (должен быть отрицательным числом, например -1001234567890)

Аналитика не показывает данные:

• Убедитесь, что все миграции применены: docker compose exec backend alembic upgrade head