https://github.com/vladelo777/support-fastapi-module
Система поддержки пользователей с тикетами, WebSocket-чатом, email-интеграцией, вложениями, таймерами SLA и базой знаний. Разрабатывается поэтапно на FastAPI + PostgreSQL + SQLAlchemy.
https://github.com/vladelo777/support-fastapi-module
fastapi python
Last synced: 12 months ago
JSON representation
Система поддержки пользователей с тикетами, WebSocket-чатом, email-интеграцией, вложениями, таймерами SLA и базой знаний. Разрабатывается поэтапно на FastAPI + PostgreSQL + SQLAlchemy.
- Host: GitHub
- URL: https://github.com/vladelo777/support-fastapi-module
- Owner: vladelo777
- Created: 2025-06-18T18:00:17.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-26T12:14:54.000Z (12 months ago)
- Last Synced: 2025-06-26T13:20:50.738Z (12 months ago)
- Topics: fastapi, python
- Language: Python
- Homepage:
- Size: 69.3 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# 🛠️ FastAPI Support System
Система поддержки пользователей с тикетами, WebSocket-чатом, email-интеграцией, вложениями, таймерами SLA и базой
знаний. Разрабатывается поэтапно на FastAPI + PostgreSQL + SQLAlchemy.
**Автор:** Владислав Лахтионов
**Telegram:** @vladelo
---
## ✅ Этап 1. Базовая архитектура и тикеты
### 📦 Основные сущности:
- **Ticket**
- `id`, `title`, `description`, `status`, `priority`, `category`, `queue_id`, `client_id`, `agent_id`,
`frt_deadline: datetime`, `ttr_deadline`, `created_ad`, `updated_ad`
- **Message**
- `id`, `ticket_id`, `author_id`, `content`, `is_from_agent`, `created_ad`
- **Note**
- `id`, `ticket_id`, `author_id`, `content`, `created_ad`
- **Queue**
- `id`, `name`, `description`
- **User**
- `id`, `email`, `name`, `role` (`agent` / `client`)
> ❗️ **ВРЕМЕННО**
> Пока микросервис с `User` еще не готов, используется локальная (временная) база данных с пользователями — **клиентами** и **агентами**.
> В дальнейшем будет настроена связь между микросервисами, и данные о пользователях будут поступать оттуда.
### 🔧 Реализация:
- SQLAlchemy-модели + Alembic миграции
- CRUD-эндпоинты на FastAPI:
- `/tickets/`
- `/messages/`
- `/notes/`
- `/queues/`
- `/attachments/`
- Статусы тикетов:
- `Открыт`, `В работе`, `Ожидает клиента`, `Закрыт`
- Приоритеты:
- `Низкий`, `Средний`, `Высокий`, `Срочный`
- Swagger UI: [`/docs`](http://localhost:8000/docs)
---
## ✅ Этап 2. WebSocket и Email-обработка
### 📲 WebSocket-чат
- **Эндпоинт:** `/ws/support`
- Клиент и агент подключаются через WebSocket к этому адресу
- При подключении клиент **обязательно сначала отправляет JSON с данными для создания тикета**
- Формат первого сообщения для создания тикета (JSON):
```json
{
"title": "Заголовок тикета",
"description": "Описание проблемы",
"status": "OPEN",
"priority": "MEDIUM",
"category": "Категория тикета",
"queue_id": 1,
"client_id": 123
}
- После создания тикета сервер возвращает клиенту JSON с ticket_id:
```json
{
"ticket_id": 42
}
- Далее клиент может отправлять сообщения в чат в формате JSON:
```json
{
"ticket_id": 42,
"author_id": 123,
"is_from_agent": false,
"content": "Текст сообщения"
}
### 📧 Email-интеграция:
- 📥 Подключение к почтовому ящику через IMAP Yandex
- ⏱ Чтение новых писем с интервалом в 30 секунд через BackgroundTasks FastAPI
- 🆕 Автоматическое создание тикета:
- Заголовок письма → заголовок тикета
- Тело письма → описание тикета
- Все такие тикеты автоматически попадают в очередь "Письма из почты"
- Привязка к "гостевому" пользователю (например, `client_id=1`)
### ⚙️ Маршрутизация тикетов:
- Фиксированная очередь по темам:
- Техническая поддержка
- Биллинг
- Логистика
- Общие вопросы
- Вопросы с почты
---
## ✅ Этап 3. Вложения и таймеры
### 📂 Вложения (Attachments)
Система теперь поддерживает прикрепление файлов к сообщениям и заметкам:
- **Новая модель `Attachment`:**
- `id`: уникальный идентификатор
- `filename`: оригинальное имя файла
- `content_type`: MIME-тип (например, `image/png`, `application/pdf`)
- `message_id`: привязка к сообщению (если применимо)
- `note_id`: привязка к заметке (если применимо)
- **Функциональность:**
- Файлы сохраняются в директорию `uploads/`
- Доступ к файлам осуществляется через `GET /attachments/message/{message_id}` или `GET/attachments/note/{note_id}`
- При удалении `Message` или `Note` — вложения удаляются из базы
### ⏱️ SLA Таймеры: FRT и TTR
Система отслеживает и контролирует сроки обработки тикетов согласно SLA:
- **Что такое FRT и TTR:**
- **FRT (First Response Time)** – максимальное время до первого ответа от агента
- **TTR (Time to Resolution)** – максимальное время на полное решение (закрытие тикета)
- **Реализация:**
- У тикета добавлены поля:
- `frt_deadline: datetime`
- `ttr_deadline: datetime`
- Дедлайны рассчитываются на основе приоритета тикета:
- `Низкий`, `Средний`, `Высокий`, `Срочный` → разные значения SLA
- **Фоновые задачи:**
- Фоновая задача каждую минуту проверяет состояние всех открытых тикетов
- Ведётся логирование:
- Предупреждение за 1 час до истечения
- В тикетах со статусами `В работе`, `Ожидает клиента` отслеживается только TTR
- Тикеты со статусом `Закрыт` не учитываются
- Если все тикеты в норме — логируется 1 строка:
`✅ Все дедлайны соблюдены для всех тикетов`
- **Пример логов:**
```
[2025-06-25 14:20:00] [🧾 Ticket #7 | Сбои на сайте] 🚨 FRT скоро истечёт (осталось: 32 мин)
```
---
## ⏳ Этап 4. База знаний, бот и перевод на агента
### 📚 База знаний:
- Модель `Article`: `title`, `content`, `media_links`
- Полнотекстовый поиск: PostgreSQL `pg_trgm` или `sqlalchemy-searchable`
### 🤖 Бот:
- Обработка фраз:
- “статус заказа” → “Номер заказа, пожалуйста?”
- Если нет ответа — перевод на живого агента
### 👤 Перевод на агента:
- Сообщение “Хочу поговорить с человеком”
- `ticket.agent_id` назначается вручную или автоматически
- WebSocket-уведомление назначенному агенту
---
## 🏁 План разработки
| Этап | Название | Примерный срок | Реальный срок |
|------|--------------------------------------|----------------|---------------|
| 1 | Архитектура + тикеты | 11 июня | 13 июня ✅ |
| 2 | WebSocket + Email | 18 июня | 24 июня ✅ |
| 3 | Вложения + FRT/TTR | 25 июня | 25 июня ✅ |
| 4 | База знаний + бот + перевод к агенту | 2 июля | В процессе ⏳ |
---
## 🚀 Технологии
- **FastAPI** – REST API + WebSocket
- **SQLAlchemy + Alembic** – ORM и миграции
- **PostgreSQL** – хранилище данных
- **BackgroundTasks FastAPI** – фоновая обработка
- **IMAP Yandex** – email-интеграция
---
## 🧪 Запуск проекта
```bash
# Установка зависимостей
pip install -r requirements.txt
# Применение миграций
alembic upgrade head
# Запуск сервера
uvicorn app.main:app --reload