Architecture

🏗 Architecture & Integrations

docs/architecture/integrations.md

🔌 Потоки данных (Data Streams / Integrations)

Обзор

Раздел "Потоки данных" (Data Streams / Integrations) — это UI-интерфейс для управления всеми "Щупальцами" SprosOS. Каждый коннектор — это независимый канал сбора сигналов из внешнего источника.

Концепция "Гибридного коннектора"

Реальность: не все API маркетплейсов предоставляют полный доступ к данным без Premium-подписки (пример: отзывы Ozon).

Гибридная модель (Hybrid Connector) — коннектор, использующий комбинацию методов сбора данных:

┌─────────────────────────────────────────────┐
│             Гибридный коннектор              │
│                 (Ozon)                       │
│                                             │
│  ┌─────────────────┐  ┌──────────────────┐  │
│  │ API-канал       │  │ Web-канал         │  │
│  │ (Premium)       │  │ (Без подписки)    │  │
│  │                 │  │                   │  │
│  │ ✅ Каталог      │  │ ⬜ Сбор отзывов   │  │
│  │ ✅ Цены/остатки  │  │     (браузер)    │  │
│  │ ✅ Заказы       │  │ ⬜ Вопросы        │  │
│  │ ⬜ Отзывы *     │  │     (браузер)    │  │
│  └─────────────────┘  └──────────────────┘  │
│                                             │
│         * Требует Premium-подписки           │
│           Fallback: CSV-импорт или парсинг   │
└─────────────────────────────────────────────┘

Уровни доступа

Уровень	Описание	Пример
Full API	Полный доступ ко всем данным через API	Ozon Premium, WB API
Partial API	API доступен, но часть данных заблокирована	Ozon Base (есть каталог, нет отзывов)
Web Scraping	Данные только через парсинг публичных страниц	Avito, Telegram
File Import	Только ручная загрузка CSV/Excel	Любой источник как fallback

Стратегия fallback

1. Попытка API (если ключ есть)
2. Если API не даёт отзывы → Web Scraping (браузер)  
3. Если Web Scraping заблокирован → Ручной импорт CSV

Статусы для UI

Статус	Цвет	Описание
`active`	🟢 Зелёный	Коннектор работает, данные поступают
`error`	🔴 Красный	Коннектор сломан (ключ истёк, API недоступен)
`partial`	🟡 Жёлтый	Работает частично (напр., каталог есть, отзывов нет)
`not_configured`	⚪ Серый	Не настроен, ключи не введены

Canonical Entity: DataStream

from pydantic import BaseModel
from datetime import datetime
from typing import Optional
from enum import Enum


class ConnectorType(str, Enum):
    api = "api"               # Полноценное API
    web_scraping = "web_scraping"  # Парсинг
    file = "file"             # CSV/Excel импорт
    hybrid = "hybrid"         # Комбинированный


class ConnectorStatus(str, Enum):
    active = "active"
    error = "error"
    partial = "partial"
    not_configured = "not_configured"


class DataStream(BaseModel):
    """Каноническое представление потока данных в системе."""
    id: str
    name: str                          # Человеческое название
    type: ConnectorType                # Тип подключения
    status: ConnectorStatus            # Текущий статус
    value_provided: str                # Что даёт (от пользователя)
    requirements: str                  # Что требует
    last_sync: Optional[datetime]      # Последняя успешная синхронизация
    icon: Optional[str] = None         # Иконка/логотип (URL или emoji)

Приоритизированный список коннекторов

#	Коннектор	Тип	Статус	Что даёт	Требует
1	Ozon	`hybrid`	`partial`	Каталог (API) + отзывы (Premium/CSV)	Client ID, API Key, ЛК доступ
2	CSV/Excel Import	`file`	`not_configured`	Универсальный импорт любых таблиц	Файл в формате CSV/XLSX
3	Wildberries	`api`	`not_configured`	Каталог, отзывы, цены	API-ключ продавца
4	Яндекс.Маркет	`api`	`not_configured`	Отзывы, рейтинги, вопросы	API-ключ продавца
5	Avito	`web_scraping`	`not_configured`	Объявления, отзывы, статистика	ЛК доступ
6	Telegram Bots	`hybrid`	`not_configured`	Сбор обратной связи, отзывы	Telegram Bot Token

Макет UI-страницы (концепт)

┌──────────────────────────────────────────────┐
│  ⚙️ Потоки данных                  [Добавить] │
├──────────────────────────────────────────────┤
│                                              │
│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐    │
│  │Ozon  │  │CSV   │  │WB    │  │Я.Мар.│    │
│  │🟡    │  │⚪    │  │⚪    │  │⚪    │    │
│  │partial│  │not...│  │not...│  │not...│    │
│  │[Настр]│  │[Настр]│  │[Настр]│  │[Настр]│    │
│  └──────┘  └──────┘  └──────┘  └──────┘    │
│                                              │
│  ┌──────┐  ┌──────┐                          │
│  │Avito │  │Tele  │                          │
│  │⚪    │  │gram │                          │
│  │     │  │⚪    │                          │
│  │[Настр]│  │[Настр]│                          │
│  └──────┘  └──────┘                          │
│                                              │
└──────────────────────────────────────────────┘