diff --git a/README.md b/README.md index 3e57a90..fa0cc54 100644 --- a/README.md +++ b/README.md @@ -9,4 +9,305 @@ IP (Customer Intelligence Platform) — Платформа клиентской "Synapse" (Синапс) -Почему подходит: Идеально отражает идею "центральной нервной системы" вашего бизнеса, которую мы обсуждали. Система, как синапс в мозге, связывает разрозненные сигналы (из чатов, звонков, соцсетей) в единую осмысленную картину и генерирует "мысли" (рекомендации). \ No newline at end of file +Почему подходит: Идеально отражает идею "центральной нервной системы" вашего бизнеса, которую мы обсуждали. Система, как синапс в мозге, связывает разрозненные сигналы (из чатов, звонков, соцсетей) в единую осмысленную картину и генерирует "мысли" (рекомендации). + +Базовая инфраструктура + +WSL2 + Ubuntu 22.04/24.04 (на Windows ПК) — базовая ОС для всего стека. + +Docker + Docker Compose — изоляция сервисов, простой деплой/обновления. + +Nginx Proxy Manager (NPM) — прокси/SSL/домены, точка входа снаружи. + +Authelia (ForwardAuth к NPM) — логин, 2FA, группы/роли (SSO ко всем внутренним сервисам). + +Хранилища и очереди + +PostgreSQL — основная БД (контакты, диалоги, транскрипты, теги, роли пользователей). + +MinIO (S3-совместимое) — файлы: записи звонков, вложения, экспорты. + +RabbitMQ (или Redis) — очередь задач (транскрибы, суммаризации, ETL). + +Сервисы обработки + +ASR-воркер (faster-whisper, CPU-only) — транскрипция аудио с Asterisk; VAD/нормализация; пишет текст/метаданные в Postgres/MinIO. + +LLM-движок (Ollama, CPU-only на старте) — локальные модели: + +для текста/аналитики: llama3:8b (Q4/Q5), + +для кода/подсказок: codellama:7b или deepseek-coder:6.7b (при необходимости). + +NLU/правила — извлечение тем/чек-листа качества, токсичности, next-steps (пока правила + лёгкая LLM). + +Бизнес-логика и UI + +API (FastAPI) — единая точка: приём событий, статусы задач, доступ к данным/файлам, вебхуки. + +UI (Next.js + Tailwind + shadcn/ui) — интерфейс: + +/inbox (очередь задач/диалогов), + +карточка разговора (текст, метки, чек-лист, статусы), + +/review (апрув/комменты), + +/reports (KPI/воронки/SLA). + +Metabase — дашборды руководителя (бизнес-аналитика: утечки, SLA, конверсия обращение→чек). + +(Опционально позже) Grafana + Prometheus — тех.мониторинг (очереди, ошибки, загрузка, алерты). + +Интеграции (входящие данные) + +Asterisk — CDR/CEL + записи → в MinIO; метаданные в Postgres; триггер задач ASR. + +1С (CSV-экспорт раз в день/час) — загрузка чеков → матчинг с диалогами (телефон/email/время). + +Омниканалы (по мере готовности): Telegram Bot, WhatsApp Business Cloud API, почта (IMAP), сайт-формы/события. + +Web-метрики — GTM: клики tel:/WA/TG, scroll/depth, sessionId/utm → в API (склейка путей клиента). + +Роли и безопасность + +Роли: admin, expert, reviewer, observer (RBAC в Postgres). + +SSO: Authelia (2FA, пароли Argon2id); NPM шлёт заголовки X-Forwarded-User/Groups в API/UI. + +Аудит: audit_log на все мутирующие действия (кто/что/когда/откуда). + +PII: маскирование телефонов/емейлов в UI по ролям; подписанные URL на аудио; срок хранения аудио 30–90 дней, архив дальше. + +Порты/доступ (типовой) + +UI (Next.js): внутренняя сеть Docker (порт 3000) → публикуем через NPM как llm.domain. + +API (FastAPI): внутренняя сеть (порт 8000) → api.domain через NPM (с ForwardAuth). + +Metabase: оставить внутри/VPN; временно можно :3001. + +MinIO: консоль :9001 (только локально/VPN), S3 :9000 (только внутренней сети). + +RabbitMQ mgmt: :15672 (лучше внутри/VPN). + +Authelia: отдельный хост auth.domain (NPM). + +Ресурсы и ожидания (твой ПК, CPU-only) + +Звонки ≈ 30 мин/сутки → ASR на CPU справится (обработка за ~30–60 мин в фоне). + +RAM 32 ГБ: ок для Postgres/MinIO/ASR/UI/Metabase. + +LLM локально: маленькие модели (2–8B, Q4/Q5) → ответы медленные, но работоспособные. + +GPU (старая GTX 750): не рассчитываем (без CUDA современного уровня). + +Мини-план запуска (первый проход) + +WSL2 + Ubuntu на Windows, затем Docker/Compose. + +Поднять Postgres, MinIO, RabbitMQ, API, ASR-воркер, UI, Metabase (CPU-compose). + +В MinIO создать бакет recordings. + +Настроить Asterisk: складывать записи в MinIO (или API-ингест) + метаданные о звонке в API. + +Проверить: транскрипт появляется в БД, UI показывает карточку, Metabase — базовые графики. + +Включить Authelia + NPM (доступ к UI/API только после логина). + +Подключить CSV из 1С (раз в день) → матчинг с диалогами. + +Добавить веб-события (GTM) и Telegram Bot — начать склейку путей клиента. + +Ежедневная эксплуатация + +Очереди: следим, чтобы transcribe не накапливалась (при твоих объёмах — не будет). + +Бэкапы: nightly pg_dump, MinIO mirror (актив 30–90 дней, архив далее). + +Обновления: docker compose pull/build && up -d. + +Алерты (позже): очередь > N, ошибки API/воркера, “нет CSV из 1С за сутки”. + +Стек (сводно) + +OS: Ubuntu (WSL2). + +Orchestration: Docker Compose. + +Auth/SSO: Authelia + NPM (ForwardAuth). + +DB: Postgres. + +Files: MinIO (S3). + +Queue: RabbitMQ. + +ASR: faster-whisper (CPU). + + + +----- +Интерфейс настроек (замена config.yaml) +Зачем + +Уходим от ручного правки config.yaml. + +Настройки живут в Postgres → доступны через веб-интерфейс админки. + +Все изменения версионируются, логируются и подхватываются сервисами на лету. + +Основные принципы + +UI-админка (в ui контейнере, раздел /admin/settings). + +Хранение: таблица settings (JSONB), secrets (зашифровано), audit_log. + +Валидация: фронт (Zod) + бэкенд (Pydantic/JSON Schema). + +Подхват: воркеры и API раз в 30 секунд проверяют /config/version, если вырос — обновляют кеш. + +Аудит: кто/когда/что изменил (diff), возможность отката (rollback). + +Разделы интерфейса +1. Обзор / Profiles + +Активный профиль (например default). + +Кнопки: Export JSON, Import JSON, Compare with template. + +Лента изменений (история). + +2. ASR (транскриб) + +Модель: tiny/base/small/medium/large-v3. + +Compute type: int8, float16. + +Beam size: число (1–5). + +Язык: ru или auto. + +VAD (обрезка тишины): On/Off. + +Кнопка: Benchmark test (загрузить 30-сек файл → показать время и WER). + +3. LLM (ассистент/аналитика) + +Endpoint Ollama (URL). + +Модель по умолчанию (например, llama3:8b). + +Лимиты токенов, таймауты. + +Кнопка: Test prompt (вбить вопрос → получить ответ). + +4. Интеграции + +MinIO: endpoint, bucket, срок хранения (30–90 дней), класс хранения. + +Test connection. + +Postgres: строка подключения, pool size. + +Test connection. + +Asterisk ingest: путь/маска файлов, расписание сбора. + +1С CSV: путь/маска, разделитель, маппинг колонок. + +Preview CSV (3 строки). + +Каналы (Telegram/WhatsApp/Email): вкл/выкл, ключи в Secrets. + +5. Пороги и алерты + +SLA (время ответа, мин). + +Токсичность (порог 0–1). + +Пропущенные без перезвона (>N мин). + +Очередь ASR (>N задач). + +Кнопка: Test alert webhook (проверка отправки в Telegram/Slack). + +6. UI / Брендинг + +Название организации. + +Логотип (загрузка). + +Цветовая схема (светлая/тёмная). + +7. Secrets (секреты) + +MinIO password. + +DB password. + +Telegram/WA токены. + +SMTP (логин/пароль). + +Поля скрытые (••••), с кнопками Show once / Test / Rotate. + +8. История изменений + +Лента изменений: кто/что/когда поменял. + +Diff (старое → новое). + +Кнопка Rollback to version. + +API для настроек + +GET /config/version — версия конфига. + +GET /config/full — весь конфиг (без секретов). + +GET/PUT /config/section/{name} — работа с разделами. + +POST /config/validate — прогнать JSON против схем. + +POST /config/test/{integration} — проверки MinIO/DB/Telegram. + +GET /config/changelog — история. + +POST /config/rollback/{version} — откат. + +📌 Как это работает в стеке + +UI (Next.js): форма настроек с валидацией → API. + +API (FastAPI): пишет в Postgres (settings/secrets), валидирует, пишет audit_log. + +Воркеры/сервисы: раз в 30с → GET /config/version → если версия обновилась → подхват новых значений. + +Admin доступ: только пользователи с ролью admin (Authelia/NPM). + +Итог + +Теперь твоя памятка включает: + +Что мы разворачиваем (сервисы). + +Для чего каждый (роль). + +Как управлять настройками (веб-интерфейс вместо config.yaml). + +Безопасность и роли. + +API для интеграций и воркеров. + +LLM: Ollama (локальные модели, CPU). + +API: FastAPI. + +UI: Next.js + Tailwind + shadcn/ui. + +BI: Metabase. + +(опционально позже) Monitoring: Prometheus + Grafana; Logs: Loki. \ No newline at end of file