sfera-new/docs/business-processes/ANALYTICS_STATISTICS_SYSTEM.md

СИСТЕМА СТАТИСТИКИ И АНАЛИТИКИ SFERA

🎯 ОБЗОР СИСТЕМЫ

Система статистики и аналитики SFERA обеспечивает полную отчетность и бизнес-аналитику для всех типов организаций. Включает статистику продаж, рекламы, производительности фулфилмента и экономические показатели с AI-прогнозированием.

📊 АРХИТЕКТУРА АНАЛИТИЧЕСКОЙ СИСТЕМЫ

Основные компоненты:

• SellerStatisticsDashboard - статистика селлеров (продажи + реклама)
• FulfillmentStatisticsDashboard - производительность фулфилмента
• Economics Modules - экономические показатели по типам организаций
• Система многоуровневого кэширования - оптимизация производительности
• AI-аналитика - прогнозы и рекомендации

📈 1. СТАТИСТИКА СЕЛЛЕРА (SellerStatisticsDashboard)

1.1 Архитектура компонента

Основано на коде: src/components/seller-statistics/seller-statistics-dashboard.tsx

const SellerStatisticsDashboard = React.memo(() => {
  // Управление периодами
  const [selectedPeriod, setSelectedPeriod] = useState('week')
  const [useCustomDates, setUseCustomDates] = useState(false)
  const [startDate, setStartDate] = useState('')
  const [endDate, setEndDate] = useState('')

  // Управление вкладками
  const [activeTab, setActiveTab] = useState('sales')

  // Многоуровневое кэширование
  const [salesCache, setSalesCache] = useState<Map<string, any>>(new Map())
  const [advertisingCache, setAdvertisingCache] = useState<Map<string, any>>(new Map())
})

1.2 Система вкладок

3 основных раздела статистики:

Вкладка	Компонент	Иконка	Описание
sales	SalesTab	BarChart3	Статистика продаж товаров
advertising	AdvertisingTab	TrendingUp	Рекламная статистика
other	-	PieChart	Прочая статистика (в разработке)

1.3 Система многоуровневого кэширования

3-уровневая архитектура кэша:

Уровень 1: Локальный кэш (Map)

// Кэш для данных разных периодов и табов
const [salesCache, setSalesCache] = useState<Map<string, any>>(new Map())
const [advertisingCache, setAdvertisingCache] = useState<Map<string, any>>(new Map())

// Создание ключа кэша
const getCacheKey = useCallback(() => {
  if (useCustomDates && startDate && endDate) {
    return `custom_${startDate}_${endDate}`
  }
  return selectedPeriod
}, [useCustomDates, startDate, endDate, selectedPeriod])

Уровень 2: GraphQL Cache (Apollo)

// Запрос кэша из БД
const { data: cacheData, refetch: refetchCache } = useQuery(GET_SELLER_STATS_CACHE, {
  variables: {
    period: useCustomDates ? 'custom' : selectedPeriod,
    dateFrom: useCustomDates ? startDate : undefined,
    dateTo: useCustomDates ? endDate : undefined,
  },
  skip: !user?.organization,
  fetchPolicy: 'cache-first',
  errorPolicy: 'ignore',
})

Уровень 3: Database Cache (Мутации)

const [saveCache] = useMutation(SAVE_SELLER_STATS_CACHE)

// Сохранение в БД кэш
const saveToCacheDB = useCallback(
  async (type: 'sales' | 'advertising', data: any) => {
    const expiresAt = new Date()
    expiresAt.setHours(expiresAt.getHours() + 24) // 24 часа жизни

    const input: any = {
      period: useCustomDates ? 'custom' : selectedPeriod,
      dateFrom: useCustomDates ? startDate : null,
      dateTo: useCustomDates ? endDate : null,
      expiresAt: expiresAt.toISOString(),
    }

    if (type === 'sales') {
      input.productsData = JSON.stringify(data)
      input.productsTotalSales = data.totalSales || 0
      input.productsTotalOrders = data.totalOrders || 0
      input.productsCount = data.productsCount || 0
    } else {
      input.advertisingData = JSON.stringify(data)
      input.advertisingTotalCost = data.totalCost || 0
      input.advertisingTotalViews = data.totalViews || 0
      input.advertisingTotalClicks = data.totalClicks || 0
    }

    await saveCache({ variables: { input } })
  },
  [
    /* deps */
  ],
)

1.4 Проверка и загрузка кэша

Алгоритм работы с кэшем:

// Загрузка из кэша БД при изменении периода
useEffect(() => {
  if (cacheData?.getSellerStatsCache?.success && cacheData.getSellerStatsCache.cache) {
    const cache = cacheData.getSellerStatsCache.cache

    // Проверка истечения кэша (24 часа)
    const expiresAt = new Date(cache.expiresAt)
    const now = new Date()

    if (expiresAt > now) {
      // Кэш актуален, загружаем данные
      if (cache.productsData) {
        setSalesCache(new Map(salesCache.set(cacheKey, JSON.parse(cache.productsData))))
      }
      if (cache.advertisingData) {
        setAdvertisingCache(new Map(advertisingCache.set(cacheKey, JSON.parse(cache.advertisingData))))
      }
    }
  }
}, [cacheData, selectedPeriod, useCustomDates, startDate, endDate])

1.5 Периоды анализа

Поддерживаемые временные периоды:

Период	Ключ	Описание
Неделя	week	Последние 7 дней
Месяц	month	Последние 30 дней
Квартал	quarter	Последние 90 дней
Год	year	Последние 365 дней
Пользовательский	custom	Произвольный диапазон дат

1.6 Передача данных в компоненты

Паттерн передачи кэш-функций:

<SalesTab
  selectedPeriod={selectedPeriod}
  useCustomDates={useCustomDates}
  startDate={startDate}
  endDate={endDate}
  // Передача функций для работы с кэшем
  getCachedData={useCallback(() => getCachedData('sales'), [getCachedData])}
  setCachedData={useCallback((data) => {
    setCachedData('sales', data)
    saveToCacheDB('sales', data)
  }, [setCachedData, saveToCacheDB])}
  isLoadingData={isLoadingData}
  setIsLoadingData={setIsLoadingData}
/>

🏭 2. СТАТИСТИКА ФУЛФИЛМЕНТА (FulfillmentStatisticsDashboard)

2.1 Архитектура компонента

Основано на коде: src/components/fulfillment-statistics/fulfillment-statistics-dashboard.tsx

export function FulfillmentStatisticsDashboard() {
  // Состояния для свертывания блоков
  const [expandedSections, setExpandedSections] = useState({
    allTime: true,
    marketplaces: true,
    analytics: false,
    performance: false,
    warehouseMetrics: true,
    smartRecommendations: true,
    quickActions: true,
  })
}

2.2 Блочная структура дашборда

6 основных блоков статистики:

2.2.1 Накопленная статистика (allTime)

const statisticsData = {
  totalProducts: 0, // Обработано товаров
  totalDefects: 0, // Выявлено брака
  totalSupplies: 0, // Поставок получено
  totalRevenue: 0, // Общий доход
  totalOrders: 0, // Выполнено заказов
}

Компоненты блока:

• StatsCard "Обработано товаров" (иконка Archive, cyan)
• StatsCard "Выявлено брака" (иконка AlertTriangle, red, с трендом)
• StatsCard "Поставок получено" (иконка Clock, orange)
• StatsCard "Общий доход" (иконка DollarSign, green, с трендом)
• StatsCard "Выполнено заказов" (иконка Package, purple, с трендом)
• StatsCard "Удовлетворенность клиентов" (иконка Users, blue, рейтинг /5.0)

2.2.2 Отгрузка на площадки (marketplaces)

const marketplaceStats = {
  sentToWildberries: 0, // Отправлено на WB
  sentToOzon: 0, // Отправлено на Ozon
  sentToOthers: 0, // Другие маркетплейсы
}

Компоненты блока:

• 3 StatsCard для площадок (WB фиолетовый, Ozon синий, Другие зеленый)
• Диаграмма распределения (PieChart с процентами)
• Тренды роста (прогресс-бары с процентами роста)

2.2.3 Аналитика производительности (performance)

const performanceStats = {
  avgProcessingTime: 0, // Среднее время обработки (часы)
  defectRate: 0, // Уровень брака (%)
  returnRate: 0, // Уровень возвратов (%)
  customerSatisfaction: 0, // Рейтинг качества (/5.0)
}

2.2.4 AI-аналитика и прогнозы (analytics)

Статичные прогнозы (пока без данных):

• Прогноз роста (Target, зеленый): "Ожидается увеличение объемов на 23% в следующем квартале"
• Оптимизация (Activity, синий): "Возможно снижение времени обработки на 18% при автоматизации"
• Сезонность (Calendar, оранжевый): "Пиковые нагрузки ожидаются в ноябре-декабре (+45%)"

2.2.5 Ключевые метрики склада (warehouseMetrics)

const warehouseStats = {
  efficiency: 0, // Эффективность (%)
  turnover: 0, // Оборачиваемость (x)
  utilizationRate: 0, // Загрузка склада (%)
}

2.2.6 Умные рекомендации склада (smartRecommendations)

3 типа рекомендаций:

• Оптимизация (Target, желтый): "Рекомендуется увеличить запас расходников на 15%"
• Прогноз (Activity, синий): "Ожидается рост возвратов на 12% в следующем месяце"
• Тренд (BarChart3, фиолетовый): "Эффективность обработки товаров выросла на 8%"

2.3 Система управления блоками

Компонент заголовка секции:

const SectionHeader = ({
  title,
  section,
  badge,
  color = 'text-white',
}: {
  title: string
  section: keyof typeof expandedSections
  badge?: number | string
  color?: string
}) => (
  <div className="flex items-center justify-between mb-4">
    <div className="flex items-center space-x-3">
      <h2 className={`text-lg font-semibold ${color}`}>{title}</h2>
      {badge && (
        <span className="px-2 py-1 bg-blue-500/20 text-blue-300 text-xs rounded-full font-medium">
          {badge}
        </span>
      )}
    </div>
    <Button
      variant="ghost"
      size="sm"
      onClick={() => toggleSection(section)}
      className="text-white/60 hover:text-white hover:bg-white/10 p-1 h-8 w-8"
    >
      {expandedSections[section] ? <ChevronUp /> : <ChevronDown />}
    </Button>
  </div>
)

2.4 Компоненты статистики

StatsCard и StatsGrid из UI библиотеки:

// Использование
<StatsGrid>
  <StatsCard
    title="Обработано товаров"
    value={formatNumber(statisticsData.totalProducts)}
    icon={Archive}
    iconColor="text-cyan-400"
    iconBg="bg-cyan-500/20"
    subtitle="Общий объем"
  />
</StatsGrid>

// С трендом
<StatsCard
  title="Выявлено брака"
  value={formatNumber(statisticsData.totalDefects)}
  icon={AlertTriangle}
  iconColor="text-red-400"
  iconBg="bg-red-500/20"
  trend={{
    value: Math.abs(statisticsData.defectsTrend),
    isPositive: statisticsData.defectsTrend < 0,
  }}
  subtitle="Всего единиц"
/>

💰 3. ЭКОНОМИЧЕСКИЕ МОДУЛИ (Economics System)

3.1 Архитектура Economics модулей

Основано на коде: src/components/economics/

// 5 специализированных модулей по типам организаций
├── economics-page-wrapper.tsx      // Роутер по типу организации
├── fulfillment-economics-page.tsx  // Экономика фулфилмента
├── logist-economics-page.tsx       // Экономика логистики
├── seller-economics-page.tsx       // Экономика селлера
└── wholesale-economics-page.tsx    // Экономика оптовых поставщиков

3.2 Роутер по типам организаций

EconomicsPageWrapper - главный компонент:

// Определение типа организации пользователя
const organizationType = user?.organization?.type

// Маршрутизация к соответствующему модулю
switch (organizationType) {
  case 'FULFILLMENT':
    return <FulfillmentEconomicsPage />
  case 'LOGIST':
    return <LogistEconomicsPage />
  case 'SELLER':
    return <SellerEconomicsPage />
  case 'WHOLESALE':
    return <WholesaleEconomicsPage />
  default:
    return <DefaultEconomicsPage />
}

3.3 Специализация по типам

Каждый тип организации имеет свои экономические показатели:

Фулфилмент (fulfillment-economics-page.tsx)

• Выручка от обработки товаров
• Затраты на персонал и оборудование
• Статистика по клиентам (селлерам)
• Эффективность операций

Логистика (logist-economics-page.tsx)

• Доходы от перевозок
• Затраты на топливо и транспорт
• Загрузка автопарка
• Маржинальность маршрутов

Селлер (seller-economics-page.tsx)

• Валовая выручка от продаж
• Затраты на товары и услуги
• ROI по товарным группам
• Прибыльность каналов продаж

Оптовик (wholesale-economics-page.tsx)

• Объемы оптовых продаж
• Маржинальность поставок
• Оборачиваемость товарных остатков
• Эффективность закупок

📊 4. СИСТЕМА ФОРМАТИРОВАНИЯ И ОТОБРАЖЕНИЯ

4.1 Стандартные функции форматирования

Извлечено из компонентов:

// Форматирование чисел
const formatNumber = (num: number) => {
  return num.toLocaleString('ru-RU')
}

// Форматирование валюты
const formatCurrency = (num: number) => {
  return new Intl.NumberFormat('ru-RU', {
    style: 'currency',
    currency: 'RUB',
    minimumFractionDigits: 0,
    maximumFractionDigits: 0,
  }).format(num)
}

// Форматирование процентов
const formatPercent = (num: number) => {
  return `${num.toFixed(1)}%`
}

4.2 Цветовая система трендов

Стандартизированная палитра:

/* Положительные тренды */
.trend-positive {
  color: #4ade80; /* text-green-400 */
}

/* Отрицательные тренды */
.trend-negative {
  color: #f87171; /* text-red-400 */
}

/* Нейтральные показатели */
.trend-neutral {
  color: #94a3b8; /* text-slate-400 */
}

4.3 Система иконок

Стандартные иконки по категориям:

Категория	Иконки	Цвет
Финансы	DollarSign, TrendingUp, PieChart	Зеленый
Товары	Package, Archive, ShoppingBag	Синий
Производительность	Activity, Zap, Target	Фиолетовый
Предупреждения	AlertTriangle, XCircle	Красный
Время	Clock, Calendar	Оранжевый
Пользователи	Users, User	Cyan

🔄 5. ИНТЕГРАЦИЯ С ДРУГИМИ СИСТЕМАМИ

5.1 Источники данных

Статистика собирается из:

• GraphQL API - основные бизнес-данные
• Внешние API - данные маркетплейсов (WB, Ozon)
• Система событий - клики, просмотры, действия пользователей
• Складские системы - движение товаров, остатки
• Логистические данные - статусы доставок, времена

5.2 Real-time обновления

Потенциальные источники live-данных:

• WebSocket соединения для критических метрик
• GraphQL Subscriptions для обновлений статусов
• Polling для менее критичных показателей

5.3 Система уведомлений

Интеграция с Toast системой:

import { toast } from 'sonner'

// Успешное обновление данных
toast.success(`Загружено из кэша: ${cachedData.length} товаров`)

// Ошибка загрузки
toast.error('Ошибка при загрузке данных из API')

// Информационные сообщения
toast.info('Данные обновляются в фоновом режиме')

🎨 6. UI/UX ПАТТЕРНЫ

6.1 Glass Morphism дизайн

Базовые стили:

.glass-card {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(20px);
  border: 1px solid rgba(255, 255, 255, 0.2);
  border-radius: 12px;
}

.glass-secondary {
  background: rgba(255, 255, 255, 0.05);
  backdrop-filter: blur(10px);
  border: 1px solid rgba(255, 255, 255, 0.1);
}

6.2 Адаптивные сетки

Responsive layouts:

// Статистические карточки
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6">

// Диаграммы и детали
<div className="grid grid-cols-1 lg:grid-cols-2 gap-4">

// Компактные элементы
<div className="grid grid-cols-2 md:grid-cols-4 gap-4">

6.3 Состояния загрузки

Паттерны для loading states:

// Скелетоны для статистики
{loading ? (
  <div className="animate-pulse space-y-4">
    <div className="h-8 bg-white/10 rounded"></div>
    <div className="h-32 bg-white/10 rounded"></div>
  </div>
) : (
  <StatsContent />
)}

// Спиннеры для асинхронных операций
{isLoadingData && (
  <div className="flex items-center justify-center">
    <div className="animate-spin rounded-full h-8 w-8 border-2 border-white border-t-transparent"></div>
  </div>
)}

📈 7. ПРОИЗВОДИТЕЛЬНОСТЬ И ОПТИМИЗАЦИЯ

7.1 Мемоизация компонентов

// Мемоизация главного компонента
const SellerStatisticsDashboard = React.memo(() => {
  // компонент
})

// Мемоизация callback'ов
const getCachedData = useCallback(() => getCachedData('sales'), [getCachedData])
const setCachedData = useCallback(
  (data) => {
    setCachedData('sales', data)
    saveToCacheDB('sales', data)
  },
  [setCachedData, saveToCacheDB],
)

7.2 Оптимизация запросов

Стратегии кэширования Apollo:

// Cache-first для часто используемых данных
fetchPolicy: 'cache-first'

// Cache-and-network для критичных данных
fetchPolicy: 'cache-and-network'

// Игнорирование ошибок для вторичных данных
errorPolicy: 'ignore'

7.3 Ленивая загрузка

Потенциальные оптимизации:

• Lazy loading тяжелых диаграмм
• Виртуализация больших списков
• Code splitting по модулям статистики

🔒 8. БЕЗОПАСНОСТЬ И ДОСТУП

8.1 Проверка прав доступа

// Проверка организации пользователя
skip: !user?.organization

// Фильтрация данных по принадлежности
const userOrganizationData = allData.filter((item) => item.organizationId === user?.organization?.id)

8.2 Валидация данных

Проверки входящих данных:

// Проверка существования кэша
if (cacheData?.getSellerStatsCache?.success && cacheData.getSellerStatsCache.cache) {
  // Проверка времени жизни
  const expiresAt = new Date(cache.expiresAt)
  const now = new Date()

  if (expiresAt > now) {
    // Данные актуальны
  }
}

8.3 Обработка ошибок

// Graceful fallback при ошибках кэша
try {
  const parsedData = typeof cacheData.data === 'string' ? JSON.parse(cacheData.data) : cacheData.data
} catch (error) {
  console.error('Error parsing cache data:', error)
  // Fallback к загрузке из API
  loadDataFromAPI()
}

📊 9. МЕТРИКИ И KPI

9.1 Ключевые показатели эффективности

Автоматически отслеживаемые метрики:

Для селлеров:

• Общие продажи (totalSales)
• Количество заказов (totalOrders)
• Средний чек (averageOrderValue)
• Конверсия (conversionRate)

Для фулфилмента:

• Производительность обработки
• Уровень брака (defectRate)
• Время выполнения заказов
• Удовлетворенность клиентов

Для всех типов:

• ROI по периодам
• Темпы роста (growth rates)
• Сезонные тренды
• Прогнозируемые показатели

9.2 Система алертов

Потенциальные триггеры:

• Превышение уровня брака
• Снижение производительности
• Критические изменения в трендах
• Аномальные паттерны в данных

📊 10. ДОПОЛНИТЕЛЬНЫЕ СТАТИСТИЧЕСКИЕ КОМПОНЕНТЫ

10.1 Статистика поставок (SuppliesStatistics)

Основано на коде: src/components/supplies/supplies-statistics.tsx

Структура компонента:

interface StatisticCardProps {
  title: string
  value: string | number
  icon: React.ReactNode
  trend?: {
    value: number
    isPositive: boolean
  }
  loading?: boolean
}

function StatisticCard({ title, value, icon, trend, loading }: StatisticCardProps)

Стандартные иконки для статистики поставок:

• Package - общие данные по товарам
• TrendingUp - тренды роста
• DollarSign - финансовые показатели
• Truck - логистические данные
• AlertTriangle - предупреждения и проблемы
• BarChart - аналитические данные
• ShoppingCart - данные о заказах
• Undo2 - возвраты

Функции форматирования:

import { formatCurrency } from '@/lib/utils'

// Используется для единообразного отображения денежных сумм
const formattedValue = formatCurrency(totalAmount)

Loading состояния:

// Скелетон для карточек статистики
{loading ? (
  <Card className="bg-white/5 backdrop-blur border-white/10 p-4">
    <div className="animate-pulse">
      <div className="h-3 bg-white/10 rounded w-24 mb-2"></div>
      <div className="h-6 bg-white/10 rounded w-32"></div>
    </div>
  </Card>
) : (
  <StatisticCard {...props} />
)}

10.2 Статистика склада (WarehouseStatistics)

Основано на коде: src/components/warehouse/warehouse-statistics.tsx

Интерфейс товара для статистики:

interface Product {
  id: string
  name: string
  article: string
  type: 'PRODUCT' | 'CONSUMABLE' // Тип: товар или расходник
  quantity: number // Основное количество
  ordered?: number // Заказано
  inTransit?: number // В пути
  stock?: number // На складе
  sold?: number // Продано
  isActive: boolean // Активность товара
}

interface WarehouseStatisticsProps {
  products: Product[]
}

Логика разделения товаров:

export function WarehouseStatistics({ products }: WarehouseStatisticsProps) {
  // Разделение товаров по типам
  const goods = products.filter((p) => p.type === 'PRODUCT') // Товары
  const consumables = products.filter((p) => p.type === 'CONSUMABLE') // Расходники

  // Расчет статистик
  const totalProducts = products.length
  const activeProducts = products.filter((p) => p.isActive).length
  const inactiveProducts = products.filter((p) => !p.isActive).length
}

Стандартные иконки для складской статистики:

• Package - общие товары
• ShoppingCart - товары для продажи (PRODUCT)
• Truck - расходники (CONSUMABLE)
• CheckCircle - активные товары
• AlertTriangle - неактивные/проблемные товары
• TrendingUp - положительные тренды
• TrendingDown - отрицательные тренды

Debug logging:

console.warn('📊 STATISTICS DEBUG:', {
  productsCount: products.length,
  products,
})

10.3 Блоки рекламной статистики

Обнаружено в: src/components/seller-statistics/advertising-tab/blocks/

EmptyStateBlock

// Блок для отображения пустого состояния рекламной статистики
// Показывается когда нет данных о рекламных кампаниях

ErrorDisplayBlock

// Блок для отображения ошибок при загрузке рекламных данных
// Обрабатывает различные типы ошибок API

Модульная структура рекламных блоков:

advertising-tab/
├── blocks/
│   ├── EmptyStateBlock.tsx      // Пустое состояние
│   └── ErrorDisplayBlock.tsx    // Отображение ошибок
├── hooks/                       // Специфичные хуки
├── types/                       // Типы рекламных данных
└── index.tsx                    // Главный компонент

10.4 Интеграция со статистическими модулями

Использование в основных дашбордах:

• SuppliesStatistics используется в модулях поставок для отображения KPI
• WarehouseStatistics интегрирован в WarehouseDashboard для общей статистики склада
• Advertising blocks обеспечивают надежность рекламной статистики

Общие паттерны:

• Единообразные loading состояния с анимацией пульса
• Стандартизированная цветовая схема иконок
• Консистентное использование Glass Morphism стилей
• Debug логи для отслеживания производительности

🎯 ЗАКЛЮЧЕНИЕ

Система статистики и аналитики SFERA представляет собой комплексное решение для бизнес-аналитики с многоуровневым кэшированием, AI-прогнозированием и специализацией по типам организаций.

Ключевые преимущества:

• Многоуровневое кэширование - быстрая отработка повторных запросов
• Специализация по ролям - каждый тип организации видит релевантные метрики
• AI-аналитика - прогнозы и рекомендации для принятия решений
• Модульная архитектура - легкое добавление новых типов статистики
• Оптимизированная производительность - мемоизация и ленивая загрузка
• Glass Morphism UI - современный и привлекательный интерфейс