diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..6325dbd --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,454 @@ +# ROI24 v2 — Автономная система принятия решений для бизнеса + +> **Позиционирование:** AI-финансовый директор. Не дашборд, а система которая находит, анализирует и закрывает утечки денег в вашем бизнесе 24/7. + +--- + +## 1. Концепция: Замкнутый цикл принятия решений + +Большинство B2B-инструментов работают в **open-loop** режиме: данные → инсайты → человек решает. +ROI24 v2 работает в **closed-loop** режиме: данные → инсайты → действие через API. + +```mermaid +flowchart TB + subgraph DATA_SOURCES ["📡 Источники данных"] + A1[1С / ERP] + A2[CRM-система] + A3[Рекламные кабинеты] + A4[Банки / Платежи] + A5[Call-tracking] + A6[Сайт / Аналитика] + end + + subgraph PROCESSING ["⚙️ Обработка и анализ"] + B1[Rule Engine
Пороги, бенчмарки, корреляции] + B2[ML Pipeline
Анализ звонков, NLP, классификация] + B3[Аномалии & Прогнозы
Поиск отклонений, LLM-инсайты] + end + + subgraph ACTIONS ["🎯 Экшены (API Actions)"] + C1[Авто-оптимизация рекламы
Снижение ставок, паузы, бюджеты] + C2[CRM-триггеры
Напоминания, задачи, скоринг] + C3[Уведомления
Telegram / Slack / Email] + C4[Финансовые операции
Авто-платежи, лимиты] + end + + subgraph VALUE ["💰 Бизнес-результат"] + D1[Экономия бюджета рекламы 15-30%] + D2[Рост конверсии звонков 20-40%] + D3[Прозрачность финансов в реальном времени] + D4[Прогнозирование прибыли] + end + + DATA_SOURCES --> B1 + DATA_SOURCES --> B2 + DATA_SOURCES --> B3 + + B1 --> C1 + B1 --> C2 + B1 --> C3 + B2 --> C2 + B2 --> C3 + B3 --> C1 + B3 --> C3 + B3 --> C4 + + C1 --> D1 + C2 --> D2 + C3 --> D3 + C4 --> D4 + + D1 -.feedback.-> B3 + D2 -.feedback.-> B2 + D3 -.feedback.-> B1 + D4 -.feedback.-> B3 + + style DATA_SOURCES fill:#1e293b,stroke:#64748b,color:#e2e8f0 + style PROCESSING fill:#0f172a,stroke:#3b82f6,color:#e2e8f0 + style ACTIONS fill:#064e3b,stroke:#10b981,color:#d1fae5 + style VALUE fill:#065f46,stroke:#34d399,color:#a7f3d0 +``` + +--- + +## 2. Архитектура интеграций + +```mermaid +flowchart LR + subgraph EXTERNAL ["Внешние системы (API / Webhook)"] + E1[Яндекс.Директ / Google Ads
VK Ads / MyTarget] + E2[AmoCRM / Bitrix24 / RetailCRM] + E3[1С / МойСклад / ERP] + E4[Сбербанк / Тинькофф / ЮKassa] + E5[Calltouch / Mango / ROIS] + E6[Метрика / GA4 / Roistat] + end + + subgraph GATEWAY ["🌐 Интеграционный шлюз"] + G1[OAuth2 / Token Management] + G2[Rate Limiting / Retry] + G3[Data Normalization] + G4[Event Bus / Kafka] + end + + subgraph CORE ["🧠 ROI24 Core Engine"] + C1[Rule Engine
YAML-конфигурация] + C2[ML Service
Транскрипция, NLP, Score] + C3[Analytics Engine
Бенчмарки, Прогнозы] + C4[Action Runner
Webhooks, API calls] + end + + subgraph OUTPUT ["📤 Обратная интеграция"] + O1[Авто-редактирование рекламы] + O2[Обновление карточек лидов] + O3[Telegram-бот / Slack] + O4[Дашборд ROI24 Web UI] + end + + EXTERNAL --> G1 + EXTERNAL --> G2 + G1 --> G3 + G2 --> G3 + G3 --> G4 + G4 --> C1 + G4 --> C2 + G4 --> C3 + + C1 --> O1 + C1 --> O2 + C1 --> O3 + C1 --> O4 + + C2 --> O2 + C2 --> O3 + C2 --> O4 + + C3 --> O1 + C3 --> O3 + C3 --> O4 + + style EXTERNAL fill:#312e81,stroke:#818cf8,color:#c7d2fe + style GATEWAY fill:#1e1b4b,stroke:#6366f1,color:#e0e7ff + style CORE fill:#0f172a,stroke:#3b82f6,color:#bfdbfe + style OUTPUT fill:#042f2e,stroke:#14b8a6,color:#99f6e4 +``` + +--- + +## 3. Rule Engine архитектура + +Ядро системы — декларативные правила, не требующие кода для добавления новых сценариев. + +```mermaid +flowchart TB + subgraph RULE_INPUT ["📥 Входные данные"] + R1[Метрики в реальном времени
CAC, LTV, ROI, Конверсия...] + R2[Тренды и аномалии
Δ за 1ч / 24ч / 7д] + R3[Бенчмарки по нише
Агрегированная база] + end + + subgraph RULE_ENGINE ["⚙️ Rule Engine"] + E1[Парсер YAML правил] + E2[Expression Evaluator
JQ / Lua] + E3[Condition Matcher
AND / OR / NOT / SLIDING_WINDOW] + E4[Action Router
Auto / Warn / Alert] + end + + subgraph RULE_FORMAT ["📜 Пример правила (YAML)"] + Y1["rule: caс_spike_detection +enabled: true +priority: 10 + +conditions: + - metric: caс_daily + operator: gt + threshold: 1200 + window: 24h + - metric: caс_trend + operator: gt + threshold: 0.25 + window: 24h + +actions: + - type: alert + channel: telegram + template: '⚠️ CAC вырос на {{caс_trend*100}}% — {{caс_daily}}₽ + severity: high + - type: auto_action + target: yandex_direct + action: reduce_bid + by_percent: 20 + reason: caс_exceeds_target"] + end + + subgraph RULE_OUTPUT ["📤 Результаты"] + O1[Auto: немедленное действие] + O2[Warn: уведомление менеджеру] + O3[Alert: escalation владельцу] + O4[Log: аудит и обучение] + end + + RULE_INPUT --> E1 + E1 --> E2 + E2 --> E3 + E3 --> E4 + E4 --> O1 + E4 --> O2 + E4 --> O3 + E4 --> O4 + + RULE_ENGINE --> Y1 + + style RULE_INPUT fill:#fef3c7,stroke:#f59e0b,color:#78350f + style RULE_ENGINE fill:#1e3a8a,stroke:#60a5fa,color:#dbeafe + style RULE_FORMAT fill:#1e293b,stroke:#34d399,color:#a7f3d0 + style RULE_OUTPUT fill:#064e3b,stroke:#34d399,color:#6ee7b7 +``` + +--- + +## 4. ML Pipeline: Анализ звонков + +Трансформация сырых аудио-записей в actionable business insights. + +```mermaid +flowchart TB + subgraph AUDIO ["🎙️ Вход: сырые звонки"] + A1[Загрузка audio/mp3
Call-tracking API] + A2[Предобработка
Noise reduction, VAD] + end + + subgraph TRANSCRIBE ["📝 Транскрипция"] + B1[Whisper / Yandex SpeechKit] + B2[Speaker Diarization
Кто говорит: клиент/менеджер] + B3[Text Segmentation
По репликам и паузам] + end + + subgraph NLP ["🧠 NLP Analysis"] + C1[Intent Classification
Интерес / Отказ / Вопрос] + C2[Sentiment Analysis
Позитив / Нейтр / Нега] + C3[Topic Extraction
Темы разговора] + C4[Script Compliance
Соблюдение скрипта] + end + + subgraph SCORING ["📊 Scoring & Insights"] + D1[Manager Scorecard
Рейтинг по KPI] + D2[Objection Handling
Отработка возражений] + D3[Conversion Probability
Вероятность сделки] + D4[Summary & Next Steps] + end + + subgraph ACTIONS ["🎯 Экшены"] + E1[Обновление карточки в CRM] + E2[Напоминание менеджеру] + E3[Алерт руководителю] + E4[Рекомендации по скрипту] + end + + AUDIO --> A1 --> A2 --> B1 --> B2 --> B3 + B3 --> C1 & C2 & C3 & C4 + C1 & C2 & C3 & C4 --> D1 & D2 & D3 & D4 + D1 & D2 & D3 & D4 --> E1 & E2 & E3 & E4 + + style AUDIO fill:#fef3c7,stroke:#f59e0b,color:#78350f + style TRANSCRIBE fill:#ede9fe,stroke:#8b5cf6,color:#4c1d95 + style NLP fill:#312e81,stroke:#6366f1,color:#e0e7ff + style SCORING fill:#0f172a,stroke:#3b82f6,color:#bfdbfe + style ACTIONS fill:#064e3b,stroke:#10b981,color:#d1fae5 +``` + +--- + +## 5. Три продукта (Go-to-Market) + +```mermaid +flowchart LR + subgraph TIER1 ["🥉 Audit Mode"] + T1[Разовый аудит
50-100k₽] + T2[Все источники подключены] + T3[Отчёт: где теряете деньги] + T4[Бенчмарки по нише] + T5[Воронка в основную подписку] + end + + subgraph TIER2 ["🥈 Monitor + Recommend"] + T6[24/7 мониторинг
100-150k₽/мес] + T7[Rule Engine + Бенчмарки] + T8[ML анализ звонков] + T9[Авто-рекомендации
через API] + T10[Еженедельный дайджест] + end + + subgraph TIER3 ["🥇 Autonomous Controller"] + T11[Авто-действия без согласования
300k+₽/мес] + T12[Всё из Monitor +] + T13[Авто-оптимизация рекламы
через API] + T14[Персональный AI-ассистент] + T15[% от экономии / прибыли] + T16[SLA, выделенный аккаунт] + end + + TIER1 -->|"Пилот → Доказательство ценности"| TIER2 + TIER2 -->|"Кейс → Доверие"| TIER3 + + style TIER1 fill:#44403c,stroke:#a8a29e,color:#f5f5f4 + style TIER2 fill:#1e3a8a,stroke:#3b82f6,color:#dbeafe + style TIER3 fill:#065f46,stroke:#10b981,color:#d1fae5 +``` + +--- + +## 6. Комбинированные сценарии (Cross-System Intelligence) + +Самая высокая ценность — связывание данных из разных систем в единую картину. + +```mermaid +flowchart TB + subgraph SCENARIO1 ["📉 Сценарий 1: Лидов много, продаж мало"] + S1A[Реклама: CAC норма ✅] + S1B[Лиды в CRM: много ✅] + S1C[Звонки: качество низкое ❌] + S1D[ML: менеджер не отрабатывает возражения] + S1E[Решение: замена скрипта / обучение / замена менеджера] + end + + subgraph SCENARIO2 ["💸 Сценарий 2: Канал эффективный, но LTV маленький"] + S2A[Реклама: конверсия низкая ❌] + S2B[Звонки: клиенты холодные, не готовы платить] + S2C[Финансы: CAC > LTV ❌] + S2D[Решение: сменить креативы → привлечь ЦА с высоким LTV] + end + + subgraph SCENARIO3 ["🔄 Сценарий 3: Авто-цикл оптимизации"] + S3A[Правило: CAC вырос > 25% за 24ч] + S3B[ML: анализ звонков показывает падение конверсии в продажу] + S3C[Вывод: проблема не в рекламе, а в менеджерах] + S3D[Авто-действие: не трогать рекламу, запустить обучение менеджеров] + S3E[Результат: бюджет не потрачен зря, фокус на продажах] + end + + SCENARIO1 -->|"Вывод: проблема в продажах"| SCENARIO3 + SCENARIO2 -->|"Вывод: проблема в таргете"| SCENARIO3 + SCENARIO3 -->|"Обучение системы"| SCENARIO1 + SCENARIO3 -->|"Обучение системы"| SCENARIO2 + + style SCENARIO1 fill:#fef3c7,stroke:#f59e0b,color:#78350f + style SCENARIO2 fill:#fce7f3,stroke:#ec4899,color:#831843 + style SCENARIO3 fill:#064e3b,stroke:#34d399,color:#a7f3d0 +``` + +--- + +## 7. Tech Stack + +```mermaid +graph TB + subgraph FRONTEND ["🖥️ Frontend"] + F1[React / Next.js] + F2[Tailwind CSS + shadcn/ui] + F3[ECharts / Recharts] + F4[Telegram Bot WebApp] + end + + subgraph BACKEND ["⚙️ Backend"] + B1[Python / FastAPI] + B2[Rule Engine (YAML + Lua)] + B3[ML Service (PyTorch / Transformers)] + B4[Celery + Redis / RabbitMQ] + end + + subgraph DATA ["💾 Data"] + D1[PostgreSQL / TimescaleDB] + D2[ClickHouse (аналитика)] + D3[Redis (кэш, очереди)] + D4[S3 / MinIO (audio, logs)] + end + + subgraph ML_SERVICES ["🤖 ML Services"] + M1[Whisper (ASR)] + M2[Speaker Diarization] + M3[Custom NLP Models] + M4[LLM API (LLM-инсайты)] + end + + subgraph INFRA ["🏗️ Infrastructure"] + I1[Docker + Kubernetes] + I2[GitLab CI / GitHub Actions] + I3[Prometheus + Grafana] + I4[Nginx / Traefik] + end + + FRONTEND --> BACKEND + BACKEND --> DATA + BACKEND --> ML_SERVICES + BACKEND --> INFRA + ML_SERVICES --> DATA + INFRA --> DATA + + style FRONTEND fill:#1e1b4b,stroke:#6366f1,color:#e0e7ff + style BACKEND fill:#0f172a,stroke:#3b82f6,color:#bfdbfe + style DATA fill:#312e81,stroke:#818cf8,color:#c7d2fe + style ML_SERVICES fill:#881337,stroke:#fb7185,color:#ffe4e6 + style INFRA fill:#0c4a6e,stroke:#38bdf8,color:#bae6fd +``` + +--- + +## 8. Roadmap (MVP → Production) + +```mermaid +gantt + title ROI24 v2 Roadmap + dateFormat YYYY-MM-DD + section Phase 1 — MVP (2 недели) + Rule Engine (базовый) :done, rule_engine, 2024-01-01, 5d + Интеграция 1С + CRM :done, integrations, 2024-01-01, 7d + Дашборд (базовый) :done, dashboard, 2024-01-03, 7d + 5 правил анализа :active, rules, 2024-01-06, 4d + + section Phase 2 — ML (4 недели) + Транскрипция звонков : whisper, 2024-01-08, 5d + NLP анализ / Scorecard : ml_nlp, 2024-01-10, 7d + Telegram-уведомления : notify, 2024-01-12, 5d + Пилот на 3 клиента : pilot, 2024-01-15, 14d + + section Phase 3 — API Actions (4 недели) + Рекламные кабинеты API : ad_api, 2024-01-22, 7d + Авто-оптимизация ставок : auto_opt, 2024-01-25, 7d + CRM-триггеры : crm_trig, 2024-01-28, 5d + Бенчмарк-база : benchmark, 2024-02-01, 10d + + section Phase 4 — Enterprise (6 недель) + LLM-инсайты : llm, 2024-02-05, 7d + Прогнозирование прибыли : forecast, 2024-02-10, 10d + Web UI v2 : webui_v2, 2024-02-12, 14d + SLA + Multi-tenant : sla, 2024-02-15, 10d + Публичный запуск : launch, 2024-02-20, 14d +``` + +--- + +## 9. Unit Economics (пример для клиента) + +```mermaid +xychart-beta + title "Экономический эффект ROI24 v2 (мес.)" + xaxis ["Без
ROI24", "Audit", "Monitor", "Autonomous"] + yaxis "Экономия / Прибыль" 0 --> 1000 + bar [0, 200, 600, 900] + bar [30, 150, 400, 700] + + note on [2, 600]: "+400k/мес экономии
Авто-действия" + note on [3, 900]: "+500k/мес экономии
LLM-инсайты" +``` + +| Этап | Стоимость | Эффект | ROMI | +|------|-----------|--------|------| +| Без ROI24 | — | Утечки не видны | — | +| Audit | 50-100к (разово) | Найти утечки на 500к+/мес | 5-10x | +| Monitor | 100-150к/мес | Закрыть 60% утечек | 3-5x | +| Autonomous | 300к+/мес + % | Закрыть 90% + авто-действия | 5-10x | + +--- + +> **Ключевое отличие:** ROI24 v2 — не инструмент для просмотра данных. Это **автономный бизнес-контролёр**, который находит утечки денег, рекомендует решения и применяет их через API. Вы платите за результат, а не за красивые графики.