{"id":29040262,"url":"https://github.com/vladelo777/support-fastapi-module","last_synced_at":"2025-06-26T14:05:46.135Z","repository":{"id":301357269,"uuid":"1004495625","full_name":"vladelo777/Support-FastAPI-module","owner":"vladelo777","description":"Система поддержки пользователей с тикетами, WebSocket-чатом, email-интеграцией, вложениями, таймерами SLA и базой знаний. Разрабатывается поэтапно на FastAPI + PostgreSQL + SQLAlchemy.","archived":false,"fork":false,"pushed_at":"2025-06-26T12:14:54.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-26T13:20:50.738Z","etag":null,"topics":["fastapi","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vladelo777.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-18T18:00:17.000Z","updated_at":"2025-06-26T12:14:58.000Z","dependencies_parsed_at":"2025-06-26T13:32:46.274Z","dependency_job_id":null,"html_url":"https://github.com/vladelo777/Support-FastAPI-module","commit_stats":null,"previous_names":["vladelo777/support-fastapi-module"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vladelo777/Support-FastAPI-module","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladelo777%2FSupport-FastAPI-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladelo777%2FSupport-FastAPI-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladelo777%2FSupport-FastAPI-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladelo777%2FSupport-FastAPI-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vladelo777","download_url":"https://codeload.github.com/vladelo777/Support-FastAPI-module/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vladelo777%2FSupport-FastAPI-module/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262081079,"owners_count":23255658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","python"],"created_at":"2025-06-26T14:03:15.707Z","updated_at":"2025-06-26T14:05:46.120Z","avatar_url":"https://github.com/vladelo777.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🛠️ FastAPI Support System\n\nСистема поддержки пользователей с тикетами, WebSocket-чатом, email-интеграцией, вложениями, таймерами SLA и базой\nзнаний. Разрабатывается поэтапно на FastAPI + PostgreSQL + SQLAlchemy.\n\n**Автор:** Владислав Лахтионов\n\n**Telegram:** @vladelo\n\n---\n\n## ✅ Этап 1. Базовая архитектура и тикеты\n\n### 📦 Основные сущности:\n\n- **Ticket**\n    - `id`, `title`, `description`, `status`, `priority`, `category`, `queue_id`, `client_id`, `agent_id`,\n      `frt_deadline: datetime`, `ttr_deadline`, `created_ad`, `updated_ad`\n- **Message**\n    - `id`, `ticket_id`, `author_id`, `content`, `is_from_agent`, `created_ad`\n- **Note**\n    - `id`, `ticket_id`, `author_id`, `content`, `created_ad`\n- **Queue**\n    - `id`, `name`, `description`\n- **User**\n    - `id`, `email`, `name`, `role` (`agent` / `client`)\n\n\u003e ❗️ **ВРЕМЕННО**  \n\u003e Пока микросервис с `User` еще не готов, используется локальная (временная) база данных с пользователями — **клиентами** и **агентами**.  \n\u003e В дальнейшем будет настроена связь между микросервисами, и данные о пользователях будут поступать оттуда.\n\n### 🔧 Реализация:\n\n- SQLAlchemy-модели + Alembic миграции\n- CRUD-эндпоинты на FastAPI:\n    - `/tickets/`\n    - `/messages/`\n    - `/notes/`\n    - `/queues/`\n    - `/attachments/`\n- Статусы тикетов:\n    - `Открыт`, `В работе`, `Ожидает клиента`, `Закрыт`\n- Приоритеты:\n    - `Низкий`, `Средний`, `Высокий`, `Срочный`\n- Swagger UI: [`/docs`](http://localhost:8000/docs)\n\n---\n\n## ✅ Этап 2. WebSocket и Email-обработка\n\n### 📲 WebSocket-чат\n\n- **Эндпоинт:** `/ws/support`\n- Клиент и агент подключаются через WebSocket к этому адресу\n- При подключении клиент **обязательно сначала отправляет JSON с данными для создания тикета**\n- Формат первого сообщения для создания тикета (JSON):\n\n  ```json\n  {\n    \"title\": \"Заголовок тикета\",\n    \"description\": \"Описание проблемы\",\n    \"status\": \"OPEN\",\n    \"priority\": \"MEDIUM\",\n    \"category\": \"Категория тикета\",\n    \"queue_id\": 1,\n    \"client_id\": 123\n  }\n\n- После создания тикета сервер возвращает клиенту JSON с ticket_id:\n\n  ```json\n  {\n    \"ticket_id\": 42\n  }\n\n- Далее клиент может отправлять сообщения в чат в формате JSON:\n\n  ```json\n  {\n    \"ticket_id\": 42,\n    \"author_id\": 123,\n    \"is_from_agent\": false,\n    \"content\": \"Текст сообщения\"\n  }\n\n### 📧 Email-интеграция:\n\n- 📥 Подключение к почтовому ящику через IMAP Yandex\n- ⏱ Чтение новых писем с интервалом в 30 секунд через BackgroundTasks FastAPI\n- 🆕 Автоматическое создание тикета:\n    - Заголовок письма → заголовок тикета\n    - Тело письма → описание тикета\n    - Все такие тикеты автоматически попадают в очередь \"Письма из почты\"\n    - Привязка к \"гостевому\" пользователю (например, `client_id=1`)\n\n### ⚙️ Маршрутизация тикетов:\n\n- Фиксированная очередь по темам:\n    - Техническая поддержка\n    - Биллинг\n    - Логистика\n    - Общие вопросы\n    - Вопросы с почты\n\n---\n\n## ✅ Этап 3. Вложения и таймеры\n\n### 📂 Вложения (Attachments)\n\nСистема теперь поддерживает прикрепление файлов к сообщениям и заметкам:\n\n- **Новая модель `Attachment`:**\n    - `id`: уникальный идентификатор\n    - `filename`: оригинальное имя файла\n    - `content_type`: MIME-тип (например, `image/png`, `application/pdf`)\n    - `message_id`: привязка к сообщению (если применимо)\n    - `note_id`: привязка к заметке (если применимо)\n\n- **Функциональность:**\n    - Файлы сохраняются в директорию `uploads/`\n    - Доступ к файлам осуществляется через `GET /attachments/message/{message_id}` или `GET/attachments/note/{note_id}`\n    - При удалении `Message` или `Note` — вложения удаляются из базы\n\n### ⏱️ SLA Таймеры: FRT и TTR\n\nСистема отслеживает и контролирует сроки обработки тикетов согласно SLA:\n\n- **Что такое FRT и TTR:**\n    - **FRT (First Response Time)** – максимальное время до первого ответа от агента\n    - **TTR (Time to Resolution)** – максимальное время на полное решение (закрытие тикета)\n\n- **Реализация:**\n    - У тикета добавлены поля:\n        - `frt_deadline: datetime`\n        - `ttr_deadline: datetime`\n    - Дедлайны рассчитываются на основе приоритета тикета:\n        - `Низкий`, `Средний`, `Высокий`, `Срочный` → разные значения SLA\n\n- **Фоновые задачи:**\n    - Фоновая задача каждую минуту проверяет состояние всех открытых тикетов\n    - Ведётся логирование:\n        - Предупреждение за 1 час до истечения\n        - В тикетах со статусами `В работе`, `Ожидает клиента` отслеживается только TTR\n        - Тикеты со статусом `Закрыт` не учитываются\n        - Если все тикеты в норме — логируется 1 строка:  \n          `✅ Все дедлайны соблюдены для всех тикетов`\n\n- **Пример логов:**\n  ```\n  [2025-06-25 14:20:00] [🧾 Ticket #7 | Сбои на сайте] 🚨 FRT скоро истечёт (осталось: 32 мин)\n  ```\n\n---\n\n## ⏳ Этап 4. База знаний, бот и перевод на агента\n\n### 📚 База знаний:\n\n- Модель `Article`: `title`, `content`, `media_links`\n- Полнотекстовый поиск: PostgreSQL `pg_trgm` или `sqlalchemy-searchable`\n\n### 🤖 Бот:\n\n- Обработка фраз:\n    - “статус заказа” → “Номер заказа, пожалуйста?”\n- Если нет ответа — перевод на живого агента\n\n### 👤 Перевод на агента:\n\n- Сообщение “Хочу поговорить с человеком”\n- `ticket.agent_id` назначается вручную или автоматически\n- WebSocket-уведомление назначенному агенту\n\n---\n\n## 🏁 План разработки\n\n| Этап | Название                             | Примерный срок | Реальный срок |\n|------|--------------------------------------|----------------|---------------|\n| 1    | Архитектура + тикеты                 | 11 июня        | 13 июня ✅     |\n| 2    | WebSocket + Email                    | 18 июня        | 24 июня ✅     |\n| 3    | Вложения + FRT/TTR                   | 25 июня        | 25 июня ✅     |\n| 4    | База знаний + бот + перевод к агенту | 2 июля         | В процессе ⏳  |\n\n---\n\n## 🚀 Технологии\n\n- **FastAPI** – REST API + WebSocket\n- **SQLAlchemy + Alembic** – ORM и миграции\n- **PostgreSQL** – хранилище данных\n- **BackgroundTasks FastAPI** – фоновая обработка\n- **IMAP Yandex** – email-интеграция\n\n---\n\n## 🧪 Запуск проекта\n\n```bash\n# Установка зависимостей\npip install -r requirements.txt\n\n# Применение миграций\nalembic upgrade head\n\n# Запуск сервера\nuvicorn app.main:app --reload","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladelo777%2Fsupport-fastapi-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvladelo777%2Fsupport-fastapi-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvladelo777%2Fsupport-fastapi-module/lists"}