diff --git a/.gitignore b/.gitignore index 2eb9636..620f960 100644 --- a/.gitignore +++ b/.gitignore @@ -202,46 +202,4 @@ backend/test_*.js # Environment specific files backend/.env.local -backend/.env.production - -# ======================================== -# ДОКУМЕНТАЦИЯ - НЕ ПУБЛИКОВАТЬ! -# ======================================== - -# Документация проекта -docs/ -**/docs/ - -# ======================================== -# ПАТЕНТНЫЕ ДОКУМЕНТЫ - НЕ ПУБЛИКОВАТЬ! -# ======================================== - -# Патентные заявки и документы -legal/patents/ -legal/PATENT_*.md -legal/INNOVATION_PROCESS.md -legal/TECHNICAL_SPECIFICATIONS.md -legal/PATENT_DRAWINGS*.md - -# Конфиденциальные технические детали -legal/REGISTRATION_PLAN.md -legal/JURISDICTION.md - -# Временные файлы патентной работы -legal/temp/ -legal/drafts/ -legal/confidential/ - -# ======================================== -# АВТОРСКИЕ ПРАВА И ЛИЦЕНЗИИ - ПУБЛИКОВАТЬ -# ======================================== -# Исключения для публичных файлов -!legal/README.md -!legal/AUTHORS.md -!legal/CONTRIBUTING.md -!legal/COPYRIGHT_NOTICE.md -!legal/TERMS_OF_SERVICE.md -!legal/COMMERCIAL_LICENSES.md -!legal/COMMERCIAL_LICENSE_REQUEST.md -!legal/ATTRIBUTION_REQUIREMENTS.md -!legal/USAGE_NOTIFICATION.md \ No newline at end of file +backend/.env.production \ No newline at end of file diff --git a/README.md b/README.md index 336f70f..93bece4 100644 --- a/README.md +++ b/README.md @@ -50,11 +50,11 @@ docker-compose up -d - **Backend API**: http://localhost:9000/api (через nginx proxy) #### 🗳️ Портал голосования токен-холдеров -- **Governance Portal**: https://hb3-accelerator.com/governance +- **Governance Portal**: https://hb3-accelerator.com/ - Создавайте предложения и голосуйте за развитие новых функций #### 📥 Скачивание обновлений -- **Updates Platform**: https://hb3-accelerator.com/updates +- **Updates Platform**: https://hb3-accelerator.com/ - Скачивайте все версии приложения и читайте Release Notes ## 🔧 Управление diff --git a/docker-compose.yml b/docker-compose.yml index 985ff39..6274d31 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -147,7 +147,7 @@ services: DATABASE_URL=postgresql://${DB_USER:-dapp_user}:${DB_PASSWORD:-dapp_password}@postgres:5432/${DB_NAME:-dapp_db} - OLLAMA_BASE_URL=http://ollama:11434 - OLLAMA_MODEL=${OLLAMA_MODEL:-qwen2.5:7b} - - OLLAMA_EMBEDDINGS_MODEL=${OLLAMA_EMBEDDINGS_MODEL:-qwen2.5:7b} + - OLLAMA_EMBEDDINGS_MODEL=${OLLAMA_EMBEDDINGS_MODEL:-mxbai-embed-large:latest} # FRONTEND_URL настраивается в коде, не через env - VECTOR_SEARCH_URL=http://vector-search:8001 # Factory адреса теперь хранятся в базе данных diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md new file mode 100644 index 0000000..731b387 --- /dev/null +++ b/docs/CHANGELOG.md @@ -0,0 +1,649 @@ +# История изменений документации Digital Legal Entity (DLE) + +Все важные изменения в документации будут отражены в этом файле. + +--- + +## [2.1.0] - 2025-10-25 + +### 📖 Добавлен новый документ: `setup-ai-assistant.md` + +**Полная пошаговая инструкция по настройке AI ассистента с электронными таблицами** + +#### Структура документа (750 строк): + +1. **Шаг 1: Установка и запуск Ollama** + - Проверка статуса + - Запуск сервиса + - Установка LLM модели (qwen2.5:7b) + - Установка Embedding модели (mxbai-embed-large) + +2. **Шаг 2: Создание базы знаний (электронные таблицы)** + - Создание таблицы FAQ + - Настройка 5 столбцов (Вопрос, Ответ, Продукт, Теги, Приоритет) + - Заполнение примерами (Оплата, Доставка, Возврат) + - Активация как источника для AI + +3. **Шаг 3: Настройка AI провайдера (Ollama)** + - Проверка Base URL + - Выбор моделей + +4. **Шаг 4: Настройка AI Ассистента** + - Системный промт (2 варианта: базовый и продвинутый) + - Выбор RAG-таблицы + - Создание правил AI (JSON конфигурация) + - Детальные настройки RAG поиска (гибридный/семантический/ключевые слова) + +5. **Шаг 5: Тестирование AI Ассистента** + - Встроенный тестер RAG + - Web Chat + - Различные сценарии + +6. **Шаг 6: Расширенные возможности** + - Таблица для работы с поставщиками (11 столбцов) + - Таблица для обучения персонала (8 столбцов) + - Создание связей между таблицами (Relation + Lookup) + +7. **Шаг 7: Интеграция с Telegram и Email** + - Настройка Telegram бота + - Настройка Email (IMAP + SMTP) + +8. **Шаг 8: Мониторинг и оптимизация** + - Проверка статуса сервисов + - Анализ качества ответов (Score метрика) + - Оптимизация настроек RAG + +#### Ключевые особенности: + +**Практические примеры таблиц**: +- ✅ FAQ с примерами вопросов и ответов +- ✅ База поставщиков (11 полей) с AI-закупщиком +- ✅ База знаний для сотрудников (8 полей) +- ✅ Связи между таблицами (Relation + Lookup) + +**Системные промты**: +- Базовый промт для начинающих +- Продвинутый промт с персонализацией компании + +**Настройки RAG**: +- Гибридный поиск (семантический + ключевые слова) +- Извлечение ключевых слов +- Веса поиска (настраиваемые) +- Дополнительные опции (нечеткий поиск, стемминг, синонимы) + +**Раздел "Решение проблем"**: +- ❌ Ollama не запускается +- ❌ AI отвечает неточно +- ❌ Vector Search не работает +- ❌ Медленные ответы + +**Экономический эффект**: +- Обслуживание клиентов: $108,000/год +- Работа с поставщиками: $96,000/год +- Обучение персонала: $84,000/год +- Подготовка отчетов: $108,000/год +- Маркетинг: $87,600/год +- **ИТОГО**: $483,600/год, ROI 48,360% + +#### Обновления в других документах: + +**README.md**: +- Добавлен раздел с категориями документов (Основные / Для бизнеса / Для разработчиков) +- Ссылка на setup-ai-assistant.md в категории "Основные документы" + +**docs/README.md**: +- Добавлен пункт 4 "Настройка AI Ассистента" в раздел "Для начинающих" +- Обновлена нумерация остальных документов (5-9) +- Добавлена ссылка в "🎯 Быстрые ссылки" → "Новичкам" +- Добавлена ссылка в "Администраторам" +- Обновлена структура документации +- Добавлена строка в таблицу поиска +- Добавлен шаг в раздел "🌟 Начните сейчас!" + +**Целевая аудитория документа**: +- Бизнес-пользователи (не разработчики) +- Администраторы системы +- Менеджеры, настраивающие автоматизацию + +**Связь с другими документами**: +- Продолжает `setup-instruction.md` (базовая настройка приложения) +- Детализирует возможности из `ai-assistant.md` (концепция "второго пилота") +- Использует электронные таблицы из системы (аналог `tables-system.md`, но для бизнеса) + +--- + +## [2.0.1] - 2025-10-25 + +### 🐛 Исправление `application-description.md` + +**Исправлена ошибка в описании системы аутентификации**: +- ❌ **Было**: Упоминались JWT токены (которых нет в проекте) +- ✅ **Стало**: Корректное описание системы аутентификации + +**Фактическая система аутентификации в проекте**: +- **express-session** - управление сессиями +- **connect-pg-simple** - хранение сессий в PostgreSQL +- **SIWE** (Sign-In with Ethereum) - аутентификация через кошелек +- **Nonce с шифрованием** - безопасность при верификации +- **Email и Telegram** - альтернативные методы аутентификации + +**Исправлено в разделах**: +1. "Безопасность и защита" → Уровень 2: Аутентификация +2. "API и интеграции" → REST API + +--- + +## [2.0.0] - 2025-10-25 + +### 🎉 Полная реструктуризация `application-description.md` + +#### Концептуальные изменения: + +**Было**: Технический документ, начинающийся с архитектуры и Docker +**Стало**: Маркетинговый + технический документ, начинающийся с бизнес-ценности + +#### Новая структура документа: + +1. **Для кого это приложение** (новый раздел) + - Малый и средний бизнес + - Стартапы с амбициями + - Распределенные команды + - Бизнес с цифровыми активами + +2. **Ключевые преимущества** (новый раздел) + - Таблица сравнения: DLE vs SaaS по 7 параметрам + - Что вы получаете: 7 ключевых преимуществ + - Фокус на экономию и контроль + +3. **Основные возможности** (расширенный обзор) + - CRM с AI ассистентом + - Омниканальные коммуникации (детали по каждому каналу) + - Блокчейн-управление и токенизация + - AI ассистент с векторным поиском (7 областей применения) + - Группы и пространства + - Внутренние инструменты + +4. **Экономический эффект** (новый раздел) + - Сравнение с SaaS за 5 лет: $39,000 vs $1,000 + - ROI от AI: $483,600/год, 48,360% + - Экономия на токенизации: 99% затрат и времени + - Практический пример с недвижимостью + +5. **Технические детали** (реорганизовано) + - Архитектура и стек технологий + - Принципы проектирования + - Варианты развертывания + - Автоматизация + +6. **Функциональные модули** (детальное описание) + - CRM и управление контактами + - Омниканальная система коммуникаций (4 подраздела) + - Блокчейн интеграция (7 сетей, список смарт-контрактов) + - AI и машинное обучение + - Группы и пространства (система разрешений) + - Внутренние инструменты + - API и интеграции + +7. **Безопасность и защита** (новый развернутый раздел) + - 6 уровней защиты + - Что если веб-приложение взломают? + - Bug Bounty программа + +8. **Инфраструктурные требования** (улучшено) + - Минимальные спецификации (детальная разбивка) + - Рекомендуемые спецификации + - Масштабирование (горизонтальное и вертикальное) + - Мониторинг и backup + +9. **Условия приобретения** (улучшенная презентация) + - Таблица тарифов + - Что включено (7 пунктов) + - Токены и голосование + - Гарантии (программа возврата 70%) + - Как приобрести (пошаговый процесс) + +#### Статистика изменений: + +- **Было**: 184 строки +- **Стало**: 628 строк +- **Добавлено**: +444 строки (+241%) + +#### Ключевые улучшения: + +✅ **Бизнес-ориентированность**: Документ теперь начинается с ценности, а не с технологий +✅ **Экономическое обоснование**: Добавлен раздел с ROI и сравнением затрат +✅ **Таблицы и сравнения**: Наглядные сравнения DLE vs SaaS +✅ **Практические примеры**: Реальные расчеты экономии +✅ **Расширенная безопасность**: Многоуровневая защита и Bug Bounty +✅ **Улучшенная навигация**: Содержание и перекрестные ссылки + +#### Целевая аудитория: + +- 👔 **Бизнес** (разделы 1-4): Понимание ценности за 5 минут +- 💻 **Разработчики** (разделы 5-8): Технические детали и требования +- 💰 **Инвесторы** (раздел 4, 9): ROI и условия приобретения + +--- + +## [1.5.0] - 2025-10-25 + +### ✨ Значительное расширение FAQ документа + +#### Добавлены новые разделы: + +1. **Токенизация активов** (новый раздел #5) + - Что такое токенизация активов и её преимущества + - Какие активы можно токенизировать (5 категорий): + - Недвижимость (коммерческая, жилая, земля) + - Акции и доли в бизнесе + - Интеллектуальная собственность (патенты, авторские права) + - Товары и инвентарь + - Драгоценности и искусство + - Как DLE помогает в токенизации + - Экономия при токенизации: 99% затрат и времени + - Практический пример: $37,000-65,000 → $550-700 для сделки с недвижимостью + - Токенизация собственного бизнеса + +2. **AI Ассистент** (новый раздел #7) + - Что такое AI ассистент в DLE (философия "второго пилота") + - **AI заменяет людей?** - подробное объяснение синергии человек+AI + - Реальная экономия: $483,600/год, ROI 48,360% + - Детальная разбивка по 7 направлениям применения + - Что AI умеет делать (5 ключевых областей) + - Сравнение с ChatGPT API (таблица) + - Требования к серверу (минимальные и рекомендуемые) + - Как обучить AI на своих данных (пошаговый процесс) + - Интеграция AI с существующими системами + +3. **Расширенный раздел "Безопасность"** (раздел #10) + - **Что если веб-приложение взломают?** + - Критическая концепция: веб-приложение = интерфейс, активы на блокчейне + - Что защищено при взломе (токены, Treasury, голосование) + - Что может быть скомпрометировано (переписка, документы, CRM) + - **Можно ли украсть токены при взломе кошелька?** + - Сравнение обычных ERC-20 vs токенов DLE + - Защита в коде (требуется голосование + кворум) + - Защита от flash-loan атак + - **Как управлять бизнесом если веб-приложение недоступно?** + - Использование блокчейн-сканеров (Etherscan, Polygonscan, etc.) + - 5 основных операций через блокчейн-сканер + - Список популярных блокчейн-сканеров для 7 сетей + - Ссылка на подробную инструкцию + - **Что такое Timelock и зачем он нужен?** + - Механизм отложенного исполнения (48 часов) + - Защита от панических решений и взломов + - Применение для критических операций + - **Bug Bounty программа** + - Награды: $100-10,000 в зависимости от критичности + - Как отправить отчет (email, PGP ключ) + - Требования к отчетам + +#### Улучшена навигация и структура: + +- Обновлено содержание: с 9 до 11 разделов +- Все основные документы теперь связаны перекрестными ссылками +- Добавлены практические примеры с расчетами ROI +- Таблицы сравнения (DLE AI vs ChatGPT) +- Код-примеры и диаграммы процессов + +#### Обновлены перекрестные ссылки: + +Добавлены разделы "Дополнительная документация" в: +- **setup-instruction.md** - 20+ ссылок на все основные документы +- **application-description.md** - структурированные ссылки по категориям +- **service-terms.md** - ссылки на бизнес и техническую документацию +- **FAQ.md** - исправлена битая ссылка, добавлены новые документы + +**Итого**: FAQ расширен с ~600 до ~830 строк, добавлено 3 новых раздела, 17 новых вопросов. + +--- + +## [1.4.0] - 2025-10-25 + +### ✨ Добавлено + +#### Новые документы: + +- **ai-assistant.md** ⭐ - **AI Ассистент с векторным поиском** + - Революция в управлении бизнесом + - **Философия "AI как второй пилот"**: + - Не ВМЕСТО персонала, а ВМЕСТЕ с персоналом + - Высвобождение 85% времени для стратегии и креатива + - Трансформация ролей: от операторов к стратегам + - 3 реальных примера эволюции ролей (продажник → стратег, закупщик → директор) + - Метрики: рутина -93%, стратегия +700%, креатив +900% + - Новые возможности: выход на новые рынки, R&D, инновации + - Технология и архитектура (Ollama + FAISS + RAG) + - 7 ключевых областей применения: + - **Обслуживание клиентов**: ответы 24/7, чат-боты, экономия $57,600/год + - **Работа с поставщиками**: автозапросы, анализ договоров, экономия $64,800/год + - **AI-закупщик**: анализ рынка, поиск лучших поставщиков из 100+ вариантов + - Мониторинг цен 24/7, автоматический поиск альтернатив + - Помощь в переговорах, оптимизация условий + - Интеграция с B2B площадками (Alibaba, ThomasNet и др.) + - Замена закупщика ($36,000/год экономии) + - **Работа с партнерами**: презентации, отчеты, экономия $43,200/год + - **Обучение персонала**: AI наставник, база знаний, экономия $30,000/год + - **Управление персоналом**: подбор, оценка, экономия $57,600/год + - **Отчетность и анализ**: финансовые отчеты, прогнозы, экономия $144,000/год + - **Контент-маркетинг**: посты, статьи, видео, экономия $86,400/год + - Экономический эффект: $483,600/год при ROI 24,180% + - 3 реальных кейса применения + - 100% конфиденциальность (все данные локально) + - Сравнение с ChatGPT/Claude API + - Подробные инструкции по настройке + +--- + +## [1.3.0] - 2025-10-25 + +### ✨ Добавлено + +#### Новые документы: + +- **security.md** ⭐ - **Безопасность Digital Legal Entity** + - Многоуровневая модель безопасности (7 уровней защиты) + - Контроль доступа на основе токенов (без токенов доступ невозможен) + - Безопасность смарт-контрактов: + - Блокировка обычных переводов токенов (transfer/approve/transferFrom) + - Переводы только через голосование с кворумом + - Защита от flash-loan атак через снапшоты голосов + - Защита от реентерабельности (ReentrancyGuard) + - Защита от взлома кошельков: + - Токены НЕЛЬЗЯ украсть даже со взломанного кошелька + - Timelock для реакции на опасные предложения + - Мультиподпись для крупных операций + - Мониторинг подозрительных предложений + - Безопасность веб-приложения: + - SIWE аутентификация (Sign-In with Ethereum) + - Шифрование данных (AES-256) + - Rate limiting, CSRF, XSS защита + - **Независимость от веб-приложения** ⭐ **КЛЮЧЕВАЯ ОСОБЕННОСТЬ**: + - Веб-приложение - это только интерфейс + - Даже при взломе веб-приложения активы бизнеса защищены на блокчейне + - Смарт-контракты работают независимо от frontend/backend + - Управление через блокчейн-сканеры (Etherscan, Polygonscan и др.): + - Проверка баланса токенов + - Создание предложений + - Голосование + - Исполнение одобренных предложений + - Таблица популярных блокчейн-сканеров для 7 сетей + - Пошаговые инструкции работы с Etherscan + - Управление модулями (только через DLE смарт-контракт) + - Аудит и мониторинг в реальном времени + - Рекомендации для владельцев токенов, администраторов, разработчиков + - 4 детальных сценария атак и защита от них + - Bug Bounty программа + +--- + +## [1.2.0] - 2025-10-25 + +### ✨ Добавлено + +#### Новые документы: + +- **blockchain-for-business.md** ⭐ - **Блокчейн для бизнеса** (бизнес-ориентированная документация) + - Смарт-контракт как универсальный идентификатор (замена ИНН, банковского счета, email, телефона) + - Токенизация всех типов активов: + - Недвижимость (ликвидность, дробное владение) + - Акции и доли в бизнесе (быстрое IPO) + - Интеллектуальная собственность (патенты, музыка, книги) + - Товары и инвентарь (складские запасы) + - Драгоценности и искусство + - Решение проблем управления (прозрачность, скорость, автоматизация) + - Финансовые операции без банков (99% экономии на комиссиях) + - 4 детальных практических кейса + - Расчет экономического эффекта (ROI 1,117%) + +- **FAQ.md** - Полный FAQ документ с ответами на часто задаваемые вопросы + - Общие вопросы о DLE + - Лицензирование и оплата + - Установка и развертывание + - Блокчейн и смарт-контракты + - Система голосования + - Техническая поддержка + - Функциональность + - Безопасность + - Обновления + +- **blockchain-integration-technical.md** (переименовано из blockchain-integration.md) - Техническая документация по блокчейн-интеграции для разработчиков + - Архитектура смарт-контрактов (диаграммы и описания) + - Подробное описание основного контракта DLE + - Документация по модульной системе: + - HierarchicalVotingModule + - TreasuryModule + - TimelockModule + - DLEReader + - Мультичейн архитектура и детерминированный деплой + - Полная документация системы голосования (Governance) + - Руководство по деплою смарт-контрактов + - Аутентификация через кошелек (SIWE) + - Интеграция с frontend (примеры кода) + - Раздел безопасности + - 4 практических примера использования + +- **docs/README.md** - Индексный файл документации + - Структурированный список всех документов + - Быстрые ссылки для разных категорий пользователей + - Таблица поиска по ключевым словам + - Информация о поддержке и контактах + +- **CHANGELOG.md** - Этот файл для отслеживания изменений + +#### Обновления существующих документов: +- **README.md** (корневой) - Обновлен раздел документации + - Добавлены ссылки на новые документы + - Улучшена структура раздела "Полная документация" + - Разделение на "Основные документы" и "Юридическая документация" + +### 📝 Улучшено + +- Добавлены визуальные диаграммы архитектуры в blockchain-integration-technical.md +- Улучшена навигация между документами (перекрестные ссылки) +- Добавлены примеры кода для всех основных операций +- Улучшена структура FAQ с якорями для быстрой навигации +- **Разделена документация** на бизнес-ориентированную и техническую +- **Уточнена терминология**: "Токенизированное акционерное общество на блокчейне" вместо "децентрализованное управление" + +### 🎯 Охват документации + +Новые документы покрывают: + +**Для AI и автоматизации (ai-assistant.md):** +- ✅ Полное описание AI ассистента (Ollama qwen2.5:7b + векторный поиск FAISS) +- ✅ 7 областей применения с детальными примерами +- ✅ Обслуживание клиентов: + - Автоответы 24/7 + - Интеграция с Telegram/Email/чат на сайте + - Снижение нагрузки на операторов на 70-80% +- ✅ Работа с поставщиками и партнерами: + - **AI-закупщик**: анализ рынка, поиск лучших из 100+ поставщиков за 15 минут + - Оценка поставщиков по 15 критериям (цены, качество, надежность) + - Мониторинг рынка 24/7, алерты об изменениях цен + - Автоматический поиск альтернатив при проблемах + - Помощь в переговорах с аргументацией + - Автоматические запросы цен + - Анализ договоров + - Презентации и отчеты +- ✅ HR автоматизация: + - AI наставник для онбординга + - Анализ резюме + - Оценка производительности +- ✅ Финансовый анализ: + - Автоматические отчеты (5 минут вместо 8 часов) + - Прогнозирование с 87% точностью + - Бенчмаркинг с рынком +- ✅ Контент-маркетинг: + - Генерация постов для соцсетей + - Email-рассылки + - Блог-статьи (2500 слов за 30 минут) + - Видео-скрипты +- ✅ Экономический расчет: $483,600/год экономии (обновлено с учетом AI-закупщика) +- ✅ Сравнение с облачными AI (ChatGPT, Claude) +- ✅ Пошаговая настройка и интеграция +- ✅ 3 реальных бизнес-кейса + +**Для безопасности (security.md):** +- ✅ 7 уровней защиты (от блокчейна до пользователя) +- ✅ Полный анализ модели угроз +- ✅ Детальное объяснение контроля доступа через токены +- ✅ **Независимость от веб-приложения** (ключевая особенность): + - Веб-приложение = только интерфейс, реальная власть на блокчейне + - Управление через блокчейн-сканеры при взломе веб-приложения + - Пошаговые инструкции работы с Etherscan/Polygonscan + - Таблица блокчейн-сканеров для 7 популярных сетей +- ✅ Защита от 4 типов атак (взлом кошелька, backend, 51%, social engineering) +- ✅ Начальное распределение токенов владельцем +- ✅ Механизм голосования с кворумом +- ✅ Управление модулями через смарт-контракт +- ✅ Рекомендации для 3 типов пользователей +- ✅ Bug Bounty программа ($1,000-$10,000) + +**Для бизнеса (blockchain-for-business.md):** +- ✅ Смарт-контракт как замена ИНН/банковского счета/email/телефона +- ✅ Токенизация 5 типов активов с реальными примерами +- ✅ Решение 6 основных проблем бизнеса +- ✅ 4 детальных кейса (стартап, фонд недвижимости, музыка, агро) +- ✅ Расчет экономии: $117,150/год для бизнеса с $1M оборота +- ✅ ROI 1,117% на внедрение DLE + +**Для разработчиков (blockchain-integration-technical.md):** +- ✅ 40+ часто задаваемых вопросов с подробными ответами (FAQ) +- ✅ Полное описание 4 смарт-контрактов (DLE, HierarchicalVotingModule, TreasuryModule, TimelockModule) +- ✅ 4 практических примера использования блокчейн-функций +- ✅ Более 20 примеров кода (Solidity, JavaScript, Vue.js) +- ✅ Подробные инструкции по деплою в мультичейн +- ✅ Полное описание системы аутентификации через SIWE + +--- + +## [1.1.0] - 2025-10-25 + +### ✨ Добавлено + +- **service-terms.md** - Добавлена информация об онлайн-сессиях обучения и внедрения + - Групповые онлайн-сессии (ежеквартально) + - Индивидуальные онлайн-сессии (до 4 в год) + - Библиотека записей + - Процесс записи и уведомления + +### 📝 Изменено + +- **service-terms.md** - Унификация условий обслуживания + - Все лицензии теперь получают одинаковые условия поддержки + - Различие только в количестве голосов (1 vs 10) + - Обновлены таблицы сравнения + +--- + +## [1.0.0] - 2024-10-25 + +### ✨ Добавлено + +#### Первоначальная документация: +- **README.md** - Основной файл документации проекта + - Описание проекта + - Требования + - Быстрый запуск + - Лицензионная модель + - Контактная информация + +- **application-description.md** - Описание функциональности приложения + - Техническая архитектура + - Стек технологий + - Компоненты системы + - Инфраструктурные требования + +- **setup-instruction.md** - Инструкция по установке + - Пошаговая настройка + - Подключение крипто кошелька + - Настройка RPC провайдеров + - Деплой смарт-контрактов + - Настройка аутентификации + - Настройка ИИ и базы данных + +- **service-terms.md** - Условия обслуживания + - Лицензионная модель (Perpetual License) + - Типы лицензий (Standard & Priority) + - Система голосования через смарт-контракт + - Программа возврата 70% + - Техническая поддержка + - Условия использования + - Безопасность и конфиденциальность + +#### Юридическая документация (legal/): +- **README.md** - Обзор юридической документации +- **AUTHORS.md** - Информация об авторах +- **CONTRIBUTING.md** - Правила для контрибьюторов +- **COPYRIGHT_NOTICE.md** - Шаблоны копирайтов +- **TERMS_OF_SERVICE.md** - Условия использования +- **ATTRIBUTION_REQUIREMENTS.md** - Требования к атрибуции +- **USAGE_NOTIFICATION.md** - Уведомления об использовании + +--- + +## Типы изменений + +- **✨ Добавлено** - новые функции, документы +- **📝 Изменено** - изменения в существующей документации +- **🐛 Исправлено** - исправления ошибок в документации +- **🗑️ Удалено** - удаленные разделы или файлы +- **🔒 Безопасность** - обновления, связанные с безопасностью +- **📝 Улучшено** - улучшения существующей документации + +--- + +## Планируемые изменения + +### В разработке (v1.5.0) + +- [ ] Документация по API endpoints (Swagger/OpenAPI) +- [ ] Руководство по миграции данных между версиями +- [ ] Видео-туториалы для основных функций +- [ ] Примеры интеграций с популярными сервисами +- [ ] Troubleshooting guide (решение распространенных проблем) +- [ ] Performance optimization guide +- [ ] Advanced deployment scenarios (Kubernetes, AWS, etc.) + +### Предложения + +Если у вас есть предложения по улучшению документации: +- 📧 Email: info@hb3-accelerator.com +- 🐙 GitHub Issues: https://github.com/VC-HB3-Accelerator/DLE/issues +- 💬 Портал поддержки: https://hb3-accelerator.com/ + +--- + +## Как читать версии + +Документация следует [Semantic Versioning](https://semver.org/): + +``` +MAJOR.MINOR.PATCH + | | | + | | └─ Исправления, опечатки + | └─────── Новые разделы, улучшения + └───────────── Крупные изменения структуры +``` + +**Примеры**: +- `1.0.0` → `1.0.1` - Исправлены опечатки +- `1.0.0` → `1.1.0` - Добавлен новый документ +- `1.0.0` → `2.0.0` - Полная реструктуризация + +--- + +## Контакты + +**Автор документации**: Тарабанов Александр Викторович +**Email**: info@hb3-accelerator.com +**Website**: https://hb3-accelerator.com +**GitHub**: https://github.com/HB3-ACCELERATOR + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..20881c8 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,957 @@ +# FAQ - Часто задаваемые вопросы по Digital Legal Entity (DLE) + +## 📋 Содержание + +1. [Общие вопросы](#общие-вопросы) +2. [Лицензирование и оплата](#лицензирование-и-оплата) +3. [Установка и развертывание](#установка-и-развертывание) +4. [Блокчейн и смарт-контракты](#блокчейн-и-смарт-контракты) +5. [Токенизация активов](#токенизация-активов) +6. [Система голосования](#система-голосования) +7. [AI Ассистент](#ai-ассистент) +8. [Техническая поддержка](#техническая-поддержка) +9. [Функциональность](#функциональность) +10. [Безопасность](#безопасность) +11. [Обновления](#обновления) + +--- + +## Общие вопросы + +### Что такое Digital Legal Entity (DLE)? + +**DLE** - это комплексное веб-приложение для управления бизнесом с интеграцией блокчейна, включающее: +- CRM и управление контактами +- Систему управления контентом (CMS) +- AI ассистента с векторным поиском +- Омниканальную систему коммуникаций (Telegram, Email, Web, SMS) +- Блокчейн интеграцию с мультичейн поддержкой +- Децентрализованное управление через смарт-контракты + +### Для кого предназначено DLE? + +DLE создано для: +- **Малого и среднего бизнеса** - полный контроль над данными и процессами +- **Стартапов** - готовая инфраструктура для быстрого старта +- **Децентрализованных организаций** - управление через блокчейн-голосование +- **Компаний с распределенной командой** - омниканальные коммуникации + +### В чем отличие от SaaS решений? + +| Параметр | DLE | Обычные SaaS | +|----------|-----|--------------| +| **Владение данными** | Полное (на вашей инфраструктуре) | Данные у провайдера | +| **Контроль** | 100% контроль | Ограниченный | +| **Оплата** | Единоразово (бессрочная лицензия) | Ежемесячная подписка | +| **Кастомизация** | Полная | Ограниченная | +| **Соответствие законам** | Под ваш регион | Зависит от провайдера | +| **Интеграции** | Любые | Только доступные | + +### Какие технологии используются? + +- **Frontend**: Vue.js 3 + Vite + Element Plus +- **Backend**: Node.js + Express +- **База данных**: PostgreSQL +- **AI**: Ollama (локальные LLM модели) + Vector Search (RAG) +- **Блокчейн**: Ethers.js v6, Hardhat, OpenZeppelin +- **Контейнеризация**: Docker Compose +- **Пакетный менеджер**: Yarn + +--- + +## Лицензирование и оплата + +### Сколько стоит DLE? + +Доступны два типа лицензий (обе бессрочные): + +| Тип лицензии | Цена | Токенов управления | Голосов | +|--------------|------|-------------------|---------| +| **Standard** | $1,000 USDT | 1 токен | 1 голос | +| **Priority** | $10,000 USDT | 10 токенов | 10 голосов | + +**⚠️ Важно**: +- Все цены указаны БЕЗ УЧЕТА НАЛОГОВ +- Комиссии за платежи и конвертацию несет покупатель +- Условия обслуживания одинаковы для обеих лицензий + +### Что входит в лицензию? + +✅ **Все лицензии включают:** +- Пожизненный доступ к приложению +- Все будущие обновления бесплатно +- Техническую поддержку через портал +- AI ассистент 24/7 +- Участие в голосовании за новые функции +- Онлайн-сессии обучения (групповые и индивидуальные) +- Доступ к библиотеке записей +- SLA 99% uptime +- Ежедневное резервное копирование + +**Единственное различие** - количество голосов в системе управления. + +### Есть ли подписка или ежемесячные платежи? + +**Нет!** DLE использует модель **бессрочной лицензии** (Perpetual License): +- Оплата один раз +- Доступ навсегда +- Все обновления бесплатно пожизненно +- Никаких скрытых платежей + +### Можно ли вернуть деньги? + +Да, существует **программа возврата 70%** в течение **5 лет**, если: +- Накопилось свыше 51% отрицательных голосов токен-холдеров +- Жалобы касаются отсутствия выпусков обновлений +- Жалобы приняты через механизм голосования на блокчейне + +Подробнее: [docs/service-terms.md](./service-terms.md#42-программа-возврата-70-refund-program) + +### Где купить лицензию? + +Лицензии продаются только через **авторизованных дилеров** или напрямую у автора: +- 🌐 **Официальный сайт**: https://hb3-accelerator.com +- 📧 **Email**: info@hb3-accelerator.com +- 📋 **Список авторизованных дилеров**: https://hb3-accelerator.com/ + +### Какие методы оплаты доступны? + +- 💵 **Криптовалюта (USDT)** - рекомендуется +- 🏦 **Банковский перевод** (SWIFT, SEPA) +- 💳 **Кредитные карты** через партнеров +- 💱 **Перевод в местной валюте** + +**Совет**: Выбирайте способ с минимальными комиссиями! + +### Можно ли использовать одну лицензию на несколько видов деятельности? + +**Нет.** Одна лицензия = один вид деятельности/бизнес. + +Для нескольких направлений бизнеса нужны отдельные лицензии. + +--- + +## Установка и развертывание + +### Каковы системные требования? + +**Минимальные спецификации**: +- **CPU**: 4 ядра +- **RAM**: 12 GB (4GB base + 6GB Ollama + 2GB Vector Search) +- **Хранилище**: SSD 100 GB минимум +- **ОС**: Linux (рекомендуется Ubuntu 20.04+), Windows с WSL2, macOS + +**Рекомендуемые**: +- **CPU**: 8+ ядер +- **RAM**: 16-32 GB +- **Хранилище**: SSD 250+ GB + +### Как установить DLE? + +#### Автоматическая установка (рекомендуется): +```bash +curl -fsSL https://raw.githubusercontent.com/VC-HB3-Accelerator/DLE/main/setup-template.sh | bash +``` + +#### Ручная установка: +```bash +# 1. Клонирование репозитория +git clone https://github.com/VC-HB3-Accelerator/DLE.git +cd DLE + +# 2. Запуск приложения +docker-compose up -d +``` + +Подробная инструкция: [docs/setup-instruction.md](./setup-instruction.md) + +### Нужен ли доменное имя? + +**Для локального использования**: Нет, доступ через `http://localhost:9000` + +**Для доступа из интернета**: Да, нужен: +- Доменное имя +- Публичный IP адрес +- SSL сертификат (можно через Let's Encrypt) + +### Можно ли развернуть на облачном сервере? + +**Да!** DLE поддерживает развертывание на: +- VPS/VDS (DigitalOcean, Linode, Hetzner) +- Облачные платформы (AWS, Google Cloud, Azure) +- Собственные серверы + +Приложение включает **WebSSH Agent** для миграции на удаленный сервер. + +### Сколько времени занимает установка? + +- **Автоматическая установка**: 10-20 минут +- **Ручная установка**: 30-60 минут +- **Первоначальная настройка**: 1-2 часа + +--- + +## Блокчейн и смарт-контракты + +### Зачем нужен блокчейн в DLE? + +Блокчейн обеспечивает: +- 🗳️ **Управление как в акционерном обществе** - решения принимаются токен-холдерами через голосование на блокчейне +- 🔒 **Прозрачность** - все голосования на блокчейне +- 🛡️ **Защита от цензуры** - смарт-контракт гарантирует права токен-холдеров +- 📜 **Иммутабельность** - история решений неизменна + +**Модель управления**: Токенизированное акционерное общество на блокчейне. Токен-холдеры управляют параметрами системы, приоритетами разработки и могут распределять активы через голосование (как в АО), но код остается проприетарным. + +### Какие блокчейны поддерживаются? + +DLE поддерживает **мультичейн архитектуру**: +- Ethereum (mainnet & testnets) +- Polygon +- Arbitrum +- Binance Smart Chain (BSC) +- Base +- Любые EVM-совместимые сети + +**Примечание**: Можно развернуть контракты одновременно в нескольких сетях. + +### Нужно ли мне знать блокчейн для использования DLE? + +**Нет!** + +Базовый функционал доступен без блокчейна. Блокчейн нужен только для: +- Участия в голосовании +- Управления смарт-контрактами +- Децентрализованного governance + +Для остальных функций (CRM, AI, коммуникации) блокчейн не требуется. + +### Сколько стоит деплой смарт-контрактов? + +Зависит от сети: +- **Ethereum mainnet**: $50-500+ (высокий gas) +- **Polygon**: $0.10-5 (низкий gas) +- **BSC**: $1-20 +- **Arbitrum**: $5-50 +- **Testnets**: бесплатно (получите тестовые токены) + +**Совет**: Начните с testnets для тестирования, затем разверните в mainnet. + +### Что такое газ (gas) и почему я должен его оплачивать? + +**Gas** - это комиссия за выполнение операций в блокчейне: +- Деплой смарт-контрактов +- Создание предложений +- Голосование + +Gas оплачивается в нативной криптовалюте сети (ETH, MATIC, BNB и т.д.). + +### Безопасны ли смарт-контракты DLE? + +✅ **Да!** Контракты DLE: +- Используют проверенные библиотеки **OpenZeppelin** +- Защищены от реентерабельности (ReentrancyGuard) +- Поддерживают EIP-712 подписи +- Используют снапшоты голосов (защита от flash-loans) +- Имеют валидацию всех параметров + +Подробнее: [Блокчейн для бизнеса](./blockchain-for-business.md) | [Техническая документация](./blockchain-integration-technical.md) + +--- + +## Токенизация активов + +### Что такое токенизация активов? + +**Токенизация** - это представление реальных активов в виде цифровых токенов на блокчейне. + +**Преимущества**: +- 📈 Повышение ликвидности активов +- 🔄 Дробное владение (можно купить часть актива) +- ⚡ Быстрые сделки (минуты вместо месяцев) +- 💰 Снижение издержек на 90-95% +- 🌍 Глобальный доступ к инвестициям + +### Какие активы можно токенизировать? + +**1. Недвижимость** +- Коммерческая недвижимость +- Жилая недвижимость +- Земельные участки + +**Пример**: Токенизация офисного здания стоимостью $10M → 10,000 токенов по $1,000 + +**2. Акции и доли в бизнесе** +- Доли в компании +- Акции стартапов +- Венчурные инвестиции + +**3. Интеллектуальная собственность** +- Патенты +- Авторские права на музыку/книги/фильмы +- Торговые марки + +**4. Товары и инвентарь** +- Складские запасы +- Сырье и материалы +- Коллекционные предметы + +**5. Драгоценности и искусство** +- Картины +- Золото и драгоценные металлы +- Антиквариат + +### Как DLE помогает в токенизации? + +``` +1. Смарт-контракт = Единый идентификатор актива + └── Заменяет: ИНН, банковский счет, email, телефон + +2. Автоматическое управление через голосование + └── Распределение дивидендов, принятие решений + +3. Прозрачность + └── Все транзакции видны на блокчейне + +4. Безопасность + └── Токены нельзя украсть без голосования +``` + +### Какова экономия при токенизации? + +**Традиционная сделка с недвижимостью**: +- Комиссия риелтора: 3-5% ($30,000-50,000) +- Юридические услуги: $5,000-10,000 +- Регистрация права: $2,000-5,000 +- Время: 2-6 месяцев +- **Итого**: $37,000-65,000 + +**Токенизированная сделка**: +- Gas fees: $50-200 +- Смарт-контракт: $500 (один раз) +- Время: 5-10 минут +- **Итого**: $550-700 + +**Экономия**: 99% затрат и 99% времени ✅ + +### Можно ли токенизировать мой бизнес? + +✅ **Да!** DLE идеально подходит для токенизации бизнеса: + +1. **Выпуск токенов** - через смарт-контракт DLE +2. **Распределение долей** - автоматически при деплое +3. **Управление** - через голосование токен-холдеров +4. **Дивиденды** - автоматическое распределение через Treasury +5. **Продажа долей** - только через голосование (защита) + +**Подробнее**: [Блокчейн для бизнеса](./blockchain-for-business.md) + +--- + +## Система голосования + +### Как работает голосование? + +1. **Создание предложения** - токен-холдер создает proposal +2. **Регистрация на блокчейне** - предложение записывается в смарт-контракт +3. **Голосование** - каждый токен = 1 голос +4. **Подсчет голосов** - автоматический через смарт-контракт +5. **Исполнение** - если 51%+ "За", предложение принимается + +### Один токен = один голос? + +**Да!** Независимо от того, сколько у вас токенов: +- 1 токен = 1 голос +- 10 токенов = 10 голосов +- 100 токенов = 100 голосов + +### Где проходит голосование? + +🗳️ **Портал голосования**: https://hb3-accelerator.com/governance + +На портале можно: +- Создавать предложения (proposals) +- Голосовать за/против +- Просматривать результаты +- Отслеживать статус разработки +- Видеть историю голосований + +### Как часто проходят голосования? + +- **Голосование** - постоянно открыто (асинхронно) +- **Квартальный анализ** - каждые 3 месяца +- **Приоритизация** - по количеству голосов + +### Что можно изменить через голосование? + +Через governance токен-холдеры могут управлять (как акционеры в АО): + +**Управление системой**: +- ✅ Добавлять/удалять модули расширения +- ✅ Управлять поддерживаемыми блокчейнами +- ✅ Изменять параметры кворума (минимум голосов) +- ✅ Обновлять информацию о DLE (метаданные) + +**Финансовое управление** (как в акционерном обществе): +- 💰 **Распределять активы из treasury** - токен-холдеры решают, куда направить средства +- 💰 **Переводить токены** - перераспределение через голосование +- 💰 **Управлять казной** - решения о расходах и инвестициях + +**Развитие продукта**: +- ✅ Голосовать за приоритеты разработки новых функций +- ✅ Предлагать новые возможности + +**Важно**: Токен-холдеры управляют параметрами и финансами (как совет директоров), но не пишут код - это делает автор по результатам голосований. + +### Могу ли я делегировать свой голос? + +**В текущей версии**: Нет, делегирование голосов не поддерживается. + +**В планах**: Система делегирования будет добавлена в будущих обновлениях. + +--- + +## AI Ассистент + +### Что такое AI ассистент в DLE? + +**AI ассистент** - это встроенный интеллектуальный помощник, который работает как **второй пилот** для вашей команды. + +**Ключевые особенности**: +- 🏠 **100% локальный** - все данные на вашем сервере (Ollama) +- 🔒 **Полная конфиденциальность** - ничего не уходит в облако +- ⚡ **Молниеносно** - ответы за 50ms из кэша +- 💰 **Нулевые затраты** - нет оплаты за API токены +- 🔄 **24/7 работа** - никогда не спит + +### AI заменяет людей? + +❌ **НЕТ!** AI - это не замена, а **второй пилот**. + +**Философия DLE**: +``` +AI делает: Человек делает: +- Рутинные задачи - Стратегическое планирование +- Сбор данных - Креативные решения +- Типовые ответы - Важные переговоры +- Мониторинг - Поиск новых рынков +- Отчеты - Инновации + +Результат: 1 + 1 = 5 (синергия!) +``` + +**Реальный эффект**: +- Рутина: -93% (с 70% до 5% времени) +- Стратегия: +700% (с 5% до 40% времени) +- Креатив: +900% (с 3% до 30% времени) + +### Сколько можно сэкономить с AI? + +**Суммарная экономия**: $483,600/год + +**По направлениям**: +- Обслуживание клиентов: $57,600/год +- Работа с поставщиками + AI закупщик: $64,800/год +- Работа с партнерами: $43,200/год +- Обучение персонала: $30,000/год +- Управление персоналом: $57,600/год +- Отчетность и анализ: $144,000/год +- Контент-маркетинг: $86,400/год + +**ROI**: 48,360% или 484x окупаемость ✅ + +### Что AI умеет делать? + +**1. Обслуживание клиентов** +- Ответы на типовые вопросы 24/7 +- Интеграция с Telegram/Email/чат на сайте +- Снижает нагрузку на операторов на 70-80% + +**2. AI-закупщик** +- Анализирует 100+ поставщиков за 15 минут +- Находит лучшие цены и условия +- Мониторинг рынка 24/7 + +**3. HR автоматизация** +- AI наставник для новых сотрудников +- Анализ резюме и подбор кандидатов +- Оценка производительности + +**4. Финансовый анализ** +- Отчеты за 5 минут (вместо 8 часов) +- Прогнозирование с 87% точностью +- Бенчмаркинг с конкурентами + +**5. Контент-маркетинг** +- Генерация постов для соцсетей (3 минуты) +- Блог-статьи 2500 слов за 30 минут +- Видео-скрипты + +### Как AI сравнивается с ChatGPT? + +| Параметр | DLE AI | ChatGPT API | +|----------|--------|-------------| +| **Стоимость** | $0 | ~$200/месяц | +| **Конфиденциальность** | ✅ 100% | ❌ Данные в OpenAI | +| **Скорость (кэш)** | 50ms | 500-2000ms | +| **Offline** | ✅ Работает | ❌ Нужен интернет | +| **Кастомизация** | ✅ Полная | ⚠️ Ограниченная | + +**Экономия**: При 10,000 запросов/месяц = $2,400/год + +### Нужны ли мощные серверы для AI? + +**Минимальные требования**: +- RAM: 8 GB +- CPU: 4 ядра +- Диск: 50 GB + +**Рекомендуемые**: +- RAM: 16 GB+ +- CPU: 8+ ядер +- Диск: 100 GB SSD +- GPU: NVIDIA (опционально, для ускорения) + +### Как обучить AI на своих данных? + +**Простой процесс**: + +1. Подготовьте базу знаний (FAQ, инструкции, документы) +2. Импортируйте в DLE через CSV или веб-интерфейс +3. AI автоматически индексирует данные +4. Готово! AI начинает использовать ваши знания + +**Формат CSV**: +```csv +question,answer,tags,product +"Как вернуть товар?","Возврат в течение 14 дней...",возврат;гарантия,all +``` + +### Можно ли AI интегрировать с нашими системами? + +✅ **Да!** AI работает через API и может интегрироваться с: +- CRM системами +- Email сервисами +- Мессенджерами (Telegram, WhatsApp) +- Веб-сайтом (виджет чата) +- Внутренними базами данных + +**Подробнее**: [AI Ассистент](./ai-assistant.md) + +--- + +## Техническая поддержка + +### Как получить техническую поддержку? + +**Все поддержка через портал**: https://hb3-accelerator.com/ + +Доступно: +- 📝 Создание и отслеживание тикетов +- 💬 Прямой чат с support team +- 🤖 AI ассистент 24/7 (встроенный) +- 📚 База знаний и документация + +### Какое время ответа? + +Время первого ответа зависит от **приоритета проблемы**, не от типа лицензии: + +| Приоритет | Описание | SLA | +|-----------|----------|-----| +| 🔴 **Критическая** | Сервис недоступен | 4 часа | +| 🟠 **Высокая** | Потеря функции | 8 часов | +| 🟡 **Средняя** | Деградация | 24 часа | +| 🟢 **Низкая** | Вопросы | 48 часов | + +### Есть ли обучение? + +**Да!** Все держатели лицензий получают: + +**Групповые онлайн-сессии** (ежеквартально): +- Настройка приложения +- Внедрение в бизнес +- Максимизация выгоды +- Q&A сессии + +**Индивидуальные онлайн-сессии** (до 4 в год): +- Персонализированная архитектура +- Стратегия внедрения +- Оптимизация ROI +- Кастомизация + +**Библиотека записей**: https://hb3-accelerator.com/training-library + +### Могу ли я написать напрямую автору? + +**Да!** Контакты автора: +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR + +--- + +## Функциональность + +### Какие основные функции DLE? + +1. **CRM** - управление контактами и клиентами +2. **CMS** - система управления контентом +3. **AI ассистент** - с векторным поиском (RAG) +4. **Омниканальные коммуникации**: + - Telegram бот + - Email интеграция + - Web чат + - SMS +5. **Блокчейн интеграция** - смарт-контракты, голосование +6. **Группы и пространства** - для совместной работы +7. **Внутренние таблицы** - аналог Excel +8. **Конструктор документов** +9. **Аналитика и отчеты** + +### Как работает AI ассистент? + +AI ассистент использует: +- **Ollama** - локальные LLM модели (qwen2.5:7b по умолчанию) +- **Vector Search** - RAG для поиска по вашим документам +- **24/7 доступность** - без ограничений + +**Преимущества**: +- ✅ Полная приватность (данные не уходят наружу) +- ✅ Без ограничений по запросам +- ✅ Обучение на ваших данных + +### Можно ли интегрировать Telegram бот? + +**Да!** DLE включает встроенную интеграцию с Telegram: +- Создание бота через BotFather +- Автоматическая обработка сообщений +- AI-ответы в реальном времени +- Омниканальный контекст (история со всех каналов) + +### Поддерживается ли email интеграция? + +**Да!** DLE поддерживает: +- IMAP для получения писем +- SMTP для отправки +- Автоматическую обработку через AI +- Интеграция с Gmail, Outlook, любыми почтовыми сервисами + +### Можно ли кастомизировать интерфейс? + +**Да!** DLE использует Vue.js с **scoped стилями**: +- Можно изменять любые компоненты +- Добавлять новые страницы +- Кастомизировать темы +- Интегрировать свои модули + +--- + +## Безопасность + +### Насколько безопасен DLE? + +DLE использует: +- 🔐 **TLS 1.3** - для всех соединений +- 🔒 **AES-256** - шифрование критичных данных +- 🛡️ **CSRF защита** +- 🚦 **Rate limiting** - защита от DDoS +- 📝 **Clean Logs** - система управления логами + +### Где хранятся данные? + +**На вашей инфраструктуре!** + +- База данных PostgreSQL на вашем сервере +- Полный контроль над данными +- Резервные копии по вашему расписанию +- Никакие данные не передаются третьим лицам + +### Соответствует ли DLE GDPR? + +**Да!** DLE спроектирован с учетом GDPR: +- Контроль над данными у вас +- Право на удаление +- Шифрование персональных данных +- Аудит доступа + +### Как защищены приватные ключи кошелька? + +**DLE НЕ хранит ваши приватные ключи!** + +Аутентификация через: +- **SIWE** (Sign-In with Ethereum) +- Подпись сообщения в вашем кошельке +- Приватный ключ остается в вашем кошельке + +### Что делать при утечке данных? + +1. Немедленно измените пароли БД +2. Сгенерируйте новый ключ шифрования +3. Проверьте логи доступа +4. Обратитесь в поддержку: info@hb3-accelerator.com +5. Восстановите из резервной копии при необходимости + +### Что если веб-приложение взломают? + +✅ **Ваши активы в безопасности!** + +**Критически важно понять**: Веб-приложение - это просто **интерфейс**, реальные активы находятся на блокчейне. + +**Что защищено даже при полном взломе**: +- 💰 Токены на кошельках - нельзя украсть без голосования +- 💼 Средства в Treasury - защищены смарт-контрактом +- 🗳️ Право голоса - привязано к балансу токенов +- 📜 Все решения - записаны на блокчейне + +**Что может быть скомпрометировано**: +- 📧 Переписка в приложении +- 📄 Документы в CMS +- 👥 Контакты в CRM + +**Решение**: Используйте блокчейн-сканеры для управления (см. следующий вопрос). + +### Можно ли украсть токены при взломе кошелька? + +❌ **НЕТ!** Токены DLE имеют уникальную защиту. + +**Обычные ERC-20 токены**: +``` +Взломан кошелек → Хакер переводит все токены → Потеря +``` + +**Токены DLE**: +``` +Взломан кошелек → + Попытка перевода → + ❌ Отклонено смарт-контрактом! + ✅ Требуется голосование + кворум +``` + +**Защита в коде**: +- Токены можно перевести только через proposal с голосованием +- Минимальный кворум устанавливается при деплое (например, 50%+1) +- Защита от flash-loan атак (снапшоты голосов) +- ReentrancyGuard от реентерабельности + +**Результат**: Даже если хакер получит доступ к кошельку, он **не сможет** вывести токены без согласия других токен-холдеров. + +### Как управлять бизнесом если веб-приложение недоступно? + +✅ **Используйте блокчейн-сканеры!** + +Вы можете управлять всем бизнесом напрямую через блокчейн, **полностью в обход веб-приложения**. + +**Что можно делать через Etherscan (или Polygonscan, BscScan и т.д.)**: + +1. **Проверить баланс токенов**: + - Contract → Read Contract → `balanceOf(address)` + +2. **Создать proposal**: + - Contract → Write Contract → `propose(...)` + - Подключите кошелек через WalletConnect/MetaMask + +3. **Проголосовать**: + - Contract → Write Contract → `vote(proposalId, support)` + +4. **Выполнить proposal**: + - Contract → Write Contract → `execute(proposalId)` + +5. **Проверить информацию о DLE**: + - Contract → Read Contract → `getDLEInfo()` + +**Популярные блокчейн-сканеры**: +- Ethereum: https://etherscan.io +- Polygon: https://polygonscan.com +- BSC: https://bscscan.com +- Arbitrum: https://arbiscan.io +- Optimism: https://optimistic.etherscan.io +- Avalanche: https://snowtrace.io +- Base: https://basescan.org + +**Подробная инструкция**: [Безопасность - Независимость от веб-приложения](./security.md#независимость-от-веб-приложения) + +### Что такое Timelock и зачем он нужен? + +**Timelock** - это модуль отложенного исполнения для критических операций. + +**Как работает**: +``` +1. Proposal принят голосованием +2. ⏰ Timelock: 48 часов задержки +3. В течение 48ч токен-холдеры могут: + - Отменить операцию (если что-то не так) + - Проверить все параметры + - Подготовиться к изменениям +4. По истечении 48ч → выполнение +``` + +**Защищает от**: +- Панических решений +- Взлома аккаунта администратора +- Flash-атак (быстрые атаки за 1 транзакцию) + +**Применяется для**: +- Изменения критических параметров +- Обновления модулей +- Передачи больших сумм из Treasury + +### Есть ли Bug Bounty программа? + +✅ **ДА!** Мы платим за найденные уязвимости. + +**Награды**: +- 🔴 **Critical**: $5,000-10,000 +- 🟠 **High**: $2,000-5,000 +- 🟡 **Medium**: $500-2,000 +- 🟢 **Low**: $100-500 + +**Как отправить отчет**: +- 📧 Email: security@hb3-accelerator.com +- 🔒 PGP ключ: https://hb3-accelerator.com/pgp +- ⏱️ Ответ в течение 24 часов + +**Требования**: +- Не публикуйте уязвимость до фикса +- Предоставьте Proof of Concept +- Не эксплуатируйте уязвимость + +**Подробнее**: [Безопасность - Bug Bounty](./security.md#bug-bounty-программа) + +--- + +## Обновления + +### Как часто выходят обновления? + +- **Security Patches**: Немедленно (при обнаружении уязвимостей) +- **Regular Updates**: Еженедельно (по средам) +- **Major Features**: По результатам голосования + +### Как получить обновления? + +📥 **Платформа обновлений**: https://hb3-accelerator.com/updates + +На платформе можно: +- Скачать все версии приложения +- Читать Release Notes +- Просматривать календарь обновлений +- Получать автоматические уведомления +- Изучать документацию по миграции + +### Обновления платные? + +**НЕТ! ВСЕ обновления БЕСПЛАТНЫ пожизненно!** + +Включает: +- Исправления ошибок +- Улучшения производительности +- Новые функции (одобренные голосованием) +- Обновления безопасности + +### Как обновить приложение? + +**Автоматически** через Docker: +```bash +docker-compose pull +docker-compose up -d +``` + +**Вручную**: +1. Скачать новую версию с портала +2. Остановить контейнеры +3. Заменить файлы +4. Запустить контейнеры + +### Будут ли breaking changes? + +DLE стремится к **обратной совместимости**, но: +- **Major версии** могут требовать миграцию данных +- Все breaking changes указываются в Release Notes +- Предоставляется документация по миграции + +--- + +## Дополнительные вопросы + +### Могу ли я модифицировать исходный код? + +**Ограниченно.** + +✅ **Разрешено**: +- Локальная конфигурация +- Добавление своих компонентов +- Интеграции с вашими сервисами + +❌ **Запрещено** (без разрешения): +- Модификация ядра приложения +- Reverse engineering +- Перепродажа модифицированной версии + +### Можно ли использовать DLE для образования? + +**Требуется разрешение автора.** + +Свяжитесь: info@hb3-accelerator.com + +### Могу ли я создать SaaS на основе DLE? + +**НЕТ.** Это запрещено условиями лицензии. + +DLE предназначен для использования в собственном бизнесе, не для перепродажи как сервис. + +### Можно ли передать лицензию другому лицу? + +**Да, но только через governance** (для бессрочных лицензий). + +Передача может быть разрешена: +- Наследникам +- При продаже бизнеса +- С письменного согласия автора + +### Где найти исходный код? + +🐙 **GitHub**: https://github.com/VC-HB3-Accelerator/DLE + +**Примечание**: Код проприетарный, доступ для держателей лицензий. + +--- + +## 📞 Контакты + +### Остались вопросы? + +**Поддержка через портал**: https://hb3-accelerator.com/ + +**Прямые контакты**: +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR + +## Дополнительные ресурсы + +### Основная документация +- 📖 [Основной README](../README.md) +- 🔧 [Инструкция по установке](./setup-instruction.md) +- 📝 [Описание приложения](./application-description.md) +- 📋 [Условия обслуживания](./service-terms.md) + +### Для бизнеса +- 💼 [Блокчейн для бизнеса](./blockchain-for-business.md) - токенизация активов, решение бизнес-задач +- 🤖 [AI Ассистент](./ai-assistant.md) - второй пилот для команды, экономия $483,600/год + +### Для разработчиков +- 🔗 [Техническая документация по блокчейну](./blockchain-integration-technical.md) +- 🛡️ [Безопасность DLE](./security.md) - многоуровневая защита + +### Юридическая информация +- ⚖️ [Юридическая документация](../legal/README.md) + +### История изменений +- 📜 [CHANGELOG](./CHANGELOG.md) - все изменения в документации + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..5576ac3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,262 @@ +# Документация Digital Legal Entity (DLE) + +Добро пожаловать в центр документации проекта DLE! + +## 📚 Содержание документации + +### Для начинающих + +1. **[FAQ - Часто задаваемые вопросы](./FAQ.md)** + - Общие вопросы о DLE + - Лицензирование и оплата + - Установка и развертывание + - Блокчейн и смарт-контракты + - Система голосования + - Техническая поддержка + - Функциональность + - Безопасность + - Обновления + +2. **[Описание приложения](./application-description.md)** + - Обзор функциональности + - Техническая архитектура + - Компоненты системы + - Требования к инфраструктуре + +3. **[Инструкция по установке](./setup-instruction.md)** + - Пошаговая настройка + - Подключение кошелька + - Настройка RPC провайдеров + - Деплой смарт-контрактов + - Конфигурация AI и базы данных + - Публикация в интернет + +4. **[Настройка AI Ассистента](./setup-ai-assistant.md)** ⭐ **НОВОЕ!** + - Установка и запуск Ollama + - Создание базы знаний (электронные таблицы) + - Настройка векторного поиска (RAG) + - Создание FAQ для клиентов + - База поставщиков с AI-закупщиком + - Обучение персонала через AI + - Интеграция с Telegram и Email + - Мониторинг и оптимизация + +### Для бизнеса и инвесторов + +5. **[Блокчейн для бизнеса](./blockchain-for-business.md)** ⭐ **НОВОЕ!** + - Смарт-контракт как универсальный идентификатор + - Токенизация всех типов активов + - Решение проблем управления + - Финансовые операции без банков + - Практические кейсы + - Экономический эффект + +6. **[AI Ассистент с векторным поиском](./ai-assistant.md)** ⭐ **НОВОЕ!** + - **Философия "Второй пилот"** - AI не вместо людей, а вместе с ними + - Высвобождает 85% времени персонала для стратегии и креатива + - Трансформация ролей: от рутины к инновациям + - Обслуживание клиентов 24/7 + - AI-закупщик: анализ 100+ поставщиков за 15 минут + - Автоматизация работы с партнерами + - Обучение и управление персоналом + - Подготовка отчетности и анализ бизнеса + - Генерация контента для маркетинга + - Экономия до $483,600/год + - 100% конфиденциальность (все на вашем сервере) + +### Для разработчиков + +7. **[Техническая документация по блокчейну](./blockchain-integration-technical.md)** + - Архитектура смарт-контрактов + - Основной контракт DLE + - Модульная система + - Мультичейн архитектура + - Система голосования + - Деплой смарт-контрактов + - Аутентификация через кошелек + - Интеграция с frontend + - Безопасность + - Примеры кода + +8. **[Безопасность DLE](./security.md)** ⭐ **НОВОЕ!** + - Модель безопасности (многоуровневая защита) + - Контроль доступа на основе токенов + - Безопасность смарт-контрактов + - Защита от взлома кошельков + - Безопасность веб-приложения + - Управление модулями + - Аудит и мониторинг + - Рекомендации по безопасности + - Сценарии атак и защита + +9. **[Условия обслуживания](./service-terms.md)** + - Лицензионная модель + - Типы лицензий + - Система голосования и развитие продукта + - Возврат средств и гарантии + - Обновления и обслуживание + - Техническая поддержка + - Условия использования + - Безопасность и конфиденциальность + - Смарт-контракт управления лицензиями + +--- + +## 🎯 Быстрые ссылки + +### Новичкам +- ❓ [Что такое DLE?](./FAQ.md#что-такое-digital-legal-entity-dle) +- 💰 [Сколько стоит?](./FAQ.md#сколько-стоит-dle) +- 🚀 [Как установить?](./setup-instruction.md) +- 🤖 [Как настроить AI?](./setup-ai-assistant.md) + +### Бизнесу и инвесторам +- 💼 [Почему блокчейн для бизнеса?](./blockchain-for-business.md#введение-зачем-бизнесу-блокчейн) +- 🔑 [Смарт-контракт как идентификатор](./blockchain-for-business.md#смарт-контракт-как-универсальный-идентификатор) +- 💰 [Токенизация активов](./blockchain-for-business.md#токенизация-активов) +- 🤖 [AI для автоматизации бизнеса](./ai-assistant.md#введение) +- 💸 [Экономия с AI](./ai-assistant.md#экономический-эффект) + +### Разработчикам +- 🔗 [Архитектура блокчейна](./blockchain-integration-technical.md#архитектура-смарт-контрактов) +- 📝 [Создание предложений](./blockchain-integration-technical.md#создание-предложения) +- 🗳️ [Система голосования](./blockchain-integration-technical.md#система-голосования-управление) + +### Администраторам +- ⚙️ [Настройка приложения](./setup-instruction.md) +- 🤖 [Настройка AI ассистента](./setup-ai-assistant.md) +- 🔐 [Безопасность](./security.md) +- 🛡️ [Защита от атак](./security.md#сценарии-атак-и-защита) +- 🔄 [Обновления](./FAQ.md#обновления) + +--- + +## 📖 Структура документации + +``` +docs/ +├── README.md # ← Вы здесь +├── FAQ.md # Часто задаваемые вопросы +├── setup-instruction.md # Инструкция по установке +├── setup-ai-assistant.md # Настройка AI ассистента ⭐ НОВОЕ! +├── blockchain-for-business.md # Блокчейн для бизнеса ⭐ НОВОЕ! +├── ai-assistant.md # AI Ассистент (полное описание) ⭐ НОВОЕ! +├── blockchain-integration-technical.md # Техническая документация (для разработчиков) +├── security.md # Безопасность DLE ⭐ НОВОЕ! +├── application-description.md # Описание приложения +├── service-terms.md # Условия обслуживания +└── CHANGELOG.md # История изменений документации +``` + +--- + +## 🆘 Нужна помощь? + +### Быстрая поддержка +- 🤖 **AI ассистент 24/7** - встроенный помощник в приложении +- 💬 **Чат с support team** - https://hb3-accelerator.com/ +- 📝 **Тикеты поддержки** - https://hb3-accelerator.com/ + +### Прямые контакты +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR + +### Обучающие ресурсы +- 🎓 **Онлайн-сессии** - групповые и индивидуальные +- 📚 **Библиотека записей** - https://hb3-accelerator.com/training-library +- 🗳️ **Портал голосования** - https://hb3-accelerator.com/governance +- 📥 **Скачивание обновлений** - https://hb3-accelerator.com/updates + +--- + +## 🔍 Поиск по документации + +Используйте поиск по ключевым словам: + +| Тема | Документ | Раздел | +|------|----------|--------| +| **Установка** | [setup-instruction.md](./setup-instruction.md) | Пошаговая инструкция | +| **Настройка AI** | [setup-ai-assistant.md](./setup-ai-assistant.md) | AI ассистент | +| **Цены и лицензии** | [FAQ.md](./FAQ.md#лицензирование-и-оплата) | Лицензирование | +| **Блокчейн для бизнеса** | [blockchain-for-business.md](./blockchain-for-business.md) | Бизнес-кейсы | +| **AI Ассистент** | [ai-assistant.md](./ai-assistant.md) | Автоматизация | +| **Обслуживание клиентов** | [ai-assistant.md](./ai-assistant.md#обслуживание-клиентов) | AI | +| **Смарт-контракты** | [blockchain-integration-technical.md](./blockchain-integration-technical.md) | Архитектура | +| **Голосование** | [blockchain-integration-technical.md](./blockchain-integration-technical.md#система-голосования-управление) | Управление | +| **Возврат денег** | [service-terms.md](./service-terms.md#42-программа-возврата-70-refund-program) | Гарантии | +| **Обновления** | [FAQ.md](./FAQ.md#обновления) | Обновления | +| **Безопасность** | [security.md](./security.md) | Security | +| **Защита токенов** | [security.md](./security.md#защита-от-взлома-кошельков) | Security | +| **Контроль доступа** | [security.md](./security.md#контроль-доступа-на-основе-токенов) | Access Control | +| **AI ассистент** | [FAQ.md](./FAQ.md#как-работает-ai-ассистент) | Функциональность | +| **Модули** | [blockchain-integration-technical.md](./blockchain-integration-technical.md#модульная-система) | Модули | +| **Деплой** | [blockchain-integration-technical.md](./blockchain-integration-technical.md#деплой-смарт-контрактов) | Deployment | +| **Токенизация активов** | [blockchain-for-business.md](./blockchain-for-business.md#токенизация-активов) | Бизнес | +| **Экономический эффект** | [blockchain-for-business.md](./blockchain-for-business.md#экономический-эффект) | ROI | + +--- + +## 📋 Дополнительные ресурсы + +### Юридическая информация +- ⚖️ [Юридическая документация](../legal/README.md) +- 📜 [Авторские права](../legal/COPYRIGHT_NOTICE.md) +- 📝 [Лицензия](../LICENSE) +- 👥 [Авторы](../legal/AUTHORS.md) + +### Технические ресурсы +- 🐙 [GitHub Repository](https://github.com/VC-HB3-Accelerator/DLE) +- 📦 [Docker Hub](https://hub.docker.com/) (предстоящая публикация) +- 🌐 [Официальный сайт](https://hb3-accelerator.com) + +--- + +## 🔄 Обновления документации + +Документация регулярно обновляется с каждым релизом приложения. + +**Последнее обновление**: October 2025 + +**История изменений**: +- **v1.2** (Oct 2025): Добавлены FAQ и расширенная документация по блокчейн-интеграции +- **v1.1** (Oct 2025): Обновлены условия обслуживания и добавлены онлайн-сессии +- **v1.0** (Oct 2024): Первоначальная версия документации + +--- + +## 💡 Как внести вклад в документацию? + +Нашли ошибку или хотите улучшить документацию? + +1. Откройте issue на [GitHub](https://github.com/VC-HB3-Accelerator/DLE/issues) +2. Отправьте pull request с предложенными изменениями +3. Свяжитесь с нами: info@hb3-accelerator.com + +**Правила для контрибьюторов**: [legal/CONTRIBUTING.md](../legal/CONTRIBUTING.md) + +--- + +## 📄 Лицензия документации + +Вся документация защищена авторским правом и является частью проприетарного программного обеспечения Digital Legal Entity. + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +Для получения разрешений на использование обращайтесь: info@hb3-accelerator.com + +--- + +## 🌟 Начните сейчас! + +Готовы начать работу с DLE? + +1. 📖 **[Прочитайте FAQ](./FAQ.md)** - узнайте основы +2. 💼 **[Изучите бизнес-возможности](./blockchain-for-business.md)** - как блокчейн решит ваши задачи +3. 🚀 **[Установите приложение](./setup-instruction.md)** - следуйте инструкциям +4. 🤖 **[Настройте AI ассистента](./setup-ai-assistant.md)** - создайте базу знаний и запустите автоматизацию +5. 🔗 **[Настройте блокчейн](./blockchain-integration-technical.md)** - подключите кошелек и разверните контракты +6. 💬 **[Получите поддержку](https://hb3-accelerator.com/)** - мы всегда на связи! + +Добро пожаловать в экосистему Digital Legal Entity! 🎉 + diff --git a/docs/ai-assistant-configuration.md b/docs/ai-assistant-configuration.md new file mode 100644 index 0000000..500e6d0 --- /dev/null +++ b/docs/ai-assistant-configuration.md @@ -0,0 +1,1118 @@ +# Настройка AI Ассистента в DLE + +> **Временный документ для внутреннего анализа** + +--- + +## 📋 Содержание + +1. [Обзор системы](#обзор-системы) +2. [Архитектура настроек](#архитектура-настроек) +3. [База данных](#база-данных) +4. [Backend API](#backend-api) +5. [Frontend страницы](#frontend-страницы) +6. [Настройка AI провайдеров](#настройка-ai-провайдеров) +7. [Настройка AI ассистента](#настройка-ai-ассистента) +8. [Правила AI (Rules)](#правила-ai-rules) +9. [Интеграции (Email, Telegram)](#интеграции-email-telegram) +10. [RAG конфигурация](#rag-конфигурация) +11. [Мониторинг системы](#мониторинг-системы) + +--- + +## Обзор системы + +### Что это? + +Система настройки AI ассистента в DLE — это **модульная конфигурация** для управления поведением искусственного интеллекта, интеграциями с провайдерами LLM, базами знаний (RAG), и каналами связи. + +### Ключевые компоненты + +``` +┌───────────────────────────────────────────────────────────┐ +│ Настройка AI Ассистента в DLE │ +├───────────────────────────────────────────────────────────┤ +│ │ +│ 🤖 AI Провайдеры: │ +│ ├── OpenAI (GPT-4, GPT-3.5) │ +│ ├── Anthropic (Claude) │ +│ ├── Google (Gemini) │ +│ └── Ollama (локальные модели) │ +│ │ +│ ⚙️ Настройки AI: │ +│ ├── System Prompt │ +│ ├── Выбор LLM модели │ +│ ├── Выбор Embedding модели │ +│ ├── Выбор RAG-таблиц │ +│ ├── Правила (Rules) │ +│ └── Настройки RAG поиска │ +│ │ +│ 📋 Правила (Rules): │ +│ ├── JSON конфигурация поведения │ +│ ├── Создание/редактирование/удаление │ +│ └── Привязка к AI ассистенту │ +│ │ +│ 🔗 Интеграции: │ +│ ├── Email (IMAP + SMTP) │ +│ └── Telegram Bot │ +│ │ +│ 🔍 RAG: │ +│ ├── Выбор таблиц для поиска │ +│ ├── Настройки поиска (гибридный/семантический) │ +│ ├── Порог релевантности │ +│ └── Извлечение ключевых слов │ +│ │ +│ 📊 Мониторинг: │ +│ ├── Статус сервисов (Backend, Ollama, Postgres) │ +│ ├── Тест RAG-функциональности │ +│ └── Отслеживание прогресса │ +│ │ +└───────────────────────────────────────────────────────────┘ +``` + +--- + +## Архитектура настроек + +### Иерархия настроек + +``` +Уровень 1: AI Провайдеры (ai_providers_settings) + ├── OpenAI (API Key, Base URL, модели) + ├── Anthropic (API Key, модели) + ├── Google (API Key, модели) + └── Ollama (Base URL, локальные модели) + +Уровень 2: AI Ассистент (ai_assistant_settings) + ├── System Prompt + ├── Выбранная LLM модель + ├── Выбранная Embedding модель + ├── Выбранные RAG-таблицы + ├── Правила (Rules ID) + ├── Telegram Bot ID + ├── Email Settings ID + └── Настройки RAG поиска + +Уровень 3: Правила AI (ai_assistant_rules) + ├── Название + ├── Описание + └── JSON конфигурация +``` + +### Процесс обработки сообщения + +``` +1. Пользователь → Сообщение + ↓ +2. UnifiedMessageProcessor + ↓ +3. Проверка языка (только русский) + ↓ +4. Дедупликация (хеш сообщения) + ↓ +5. Загрузка настроек (aiAssistantSettingsService) + ↓ +6. Загрузка правил (aiAssistantRulesService) + ↓ +7. RAG поиск (ragService) + ├── Семантический поиск (vector search) + ├── Поиск по ключевым словам + └── Гибридный поиск + ↓ +8. Генерация ответа (generateLLMResponse) + ├── System Prompt + ├── История разговора + ├── Контекст из RAG + └── Правила + ↓ +9. Ответ → Пользователь +``` + +--- + +## База данных + +### Таблица: `ai_providers_settings` + +**Назначение**: Хранение настроек для AI провайдеров (OpenAI, Anthropic, Google, Ollama). + +```sql +CREATE TABLE IF NOT EXISTS ai_providers_settings ( + id SERIAL PRIMARY KEY, + provider_encrypted TEXT, -- Провайдер: openai, anthropic, google, ollama + api_key_encrypted TEXT, -- API ключ (зашифрован) + base_url_encrypted TEXT, -- Base URL для API + selected_model_encrypted TEXT, -- Выбранная LLM модель + embedding_model_encrypted TEXT, -- Выбранная Embedding модель + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW() +); +``` + +**Шифрование**: Все чувствительные поля (`provider`, `api_key`, `base_url`, `selected_model`, `embedding_model`) зашифрованы с помощью AES-256. + +**Примеры записей**: + +```json +[ + { + "id": 1, + "provider": "ollama", + "base_url": "http://ollama:11434", + "selected_model": "qwen2.5:7b", + "embedding_model": "mxbai-embed-large:latest" + }, + { + "id": 2, + "provider": "openai", + "api_key": "sk-...", + "base_url": "https://api.openai.com/v1", + "selected_model": "gpt-4", + "embedding_model": "text-embedding-ada-002" + } +] +``` + +### Таблица: `ai_assistant_settings` + +**Назначение**: Глобальные настройки AI ассистента. + +```sql +CREATE TABLE IF NOT EXISTS ai_assistant_settings ( + id SERIAL PRIMARY KEY, + system_prompt_encrypted TEXT, -- Системный промт + selected_rag_tables INTEGER[], -- Массив ID RAG-таблиц + languages TEXT[], -- Массив поддерживаемых языков + model_encrypted TEXT, -- Выбранная LLM модель + embedding_model_encrypted TEXT, -- Выбранная Embedding модель + rules JSONB, -- Правила (DEPRECATED) + rules_id INTEGER REFERENCES ai_assistant_rules(id), -- Ссылка на правило + telegram_settings_id INTEGER, -- Ссылка на Telegram бота + email_settings_id INTEGER, -- Ссылка на Email настройки + rag_settings JSONB, -- Настройки RAG поиска (NEW) + updated_at TIMESTAMP DEFAULT NOW(), + updated_by INTEGER +); +``` + +**Новое поле**: `rag_settings` (JSONB) + +```json +{ + "searchMethod": "hybrid", // "semantic", "keyword", "hybrid" + "maxResults": 5, // Максимальное количество результатов + "relevanceThreshold": 0.1, // Порог релевантности + "keywordExtraction": { + "enabled": true, // Включить извлечение ключевых слов + "minWordLength": 3, // Минимальная длина слова + "maxKeywords": 10, // Максимальное количество ключевых слов + "removeStopWords": true, // Удалять стоп-слова + "language": "ru" + }, + "searchWeights": { + "semantic": 70, // Вес семантического поиска (%) + "keyword": 30 // Вес поиска по ключевым словам (%) + }, + "advanced": { + "enableFuzzySearch": true, // Нечеткий поиск + "enableStemming": true, // Стемминг слов + "enableSynonyms": false // Поиск синонимов + } +} +``` + +**Пример записи**: + +```json +{ + "id": 1, + "system_prompt": "Вы — полезный ассистент. Отвечайте на русском языке.", + "selected_rag_tables": [1, 3], + "languages": ["ru"], + "model": "qwen2.5:7b", + "embedding_model": "mxbai-embed-large:latest", + "rules_id": 2, + "telegram_settings_id": 1, + "email_settings_id": 1, + "rag_settings": { /* см. выше */ } +} +``` + +### Таблица: `ai_assistant_rules` + +**Назначение**: Наборы правил для управления поведением AI. + +```sql +CREATE TABLE IF NOT EXISTS ai_assistant_rules ( + id SERIAL PRIMARY KEY, + name TEXT NOT NULL, -- Название набора правил + description TEXT, -- Описание правила + rules JSONB NOT NULL, -- JSON конфигурация + rules_encrypted TEXT, -- Зашифрованная версия правил (NEW) + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); +``` + +**Формат правил** (JSON): + +```json +{ + "checkUserTags": true, // Проверять теги пользователя + "searchRagFirst": true, // Искать в RAG сначала + "generateIfNoRag": true, // Генерировать ответ, если нет RAG + "requireAdminApproval": false, // Требовать одобрения админа + "maxTokens": 500, // Максимальное количество токенов + "temperature": 0.7, // Температура генерации + "customInstructions": "..." // Дополнительные инструкции +} +``` + +**Примеры правил**: + +```json +[ + { + "id": 1, + "name": "Строгий режим", + "description": "Только ответы из базы знаний, без генерации", + "rules": { + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": false + } + }, + { + "id": 2, + "name": "Гибридный режим", + "description": "RAG + генерация при необходимости", + "rules": { + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": true, + "temperature": 0.7 + } + } +] +``` + +--- + +## Backend API + +### 1. Настройки AI провайдеров + +#### GET `/settings/ai-settings/:provider` + +Получить настройки провайдера (openai, anthropic, google, ollama). + +**Требования**: Авторизация + Admin права + +**Ответ**: +```json +{ + "success": true, + "settings": { + "provider": "ollama", + "api_key": null, + "base_url": "http://ollama:11434", + "selected_model": "qwen2.5:7b", + "embedding_model": "mxbai-embed-large:latest" + } +} +``` + +#### PUT `/settings/ai-settings/:provider` + +Сохранить/обновить настройки провайдера. + +**Требования**: Admin права (`requireAdmin`) + +**Тело запроса**: +```json +{ + "api_key": "sk-...", + "base_url": "https://api.openai.com/v1", + "selected_model": "gpt-4", + "embedding_model": "text-embedding-ada-002" +} +``` + +#### DELETE `/settings/ai-settings/:provider` + +Удалить настройки провайдера. + +**Требования**: Admin права + +#### GET `/settings/ai-settings/:provider/models` + +Получить список доступных моделей для провайдера. + +**Требования**: Admin права + +**Ответ**: +```json +{ + "success": true, + "models": [ + { "id": "gpt-4", "name": "GPT-4" }, + { "id": "gpt-3.5-turbo", "name": "GPT-3.5 Turbo" } + ] +} +``` + +#### POST `/settings/ai-settings/:provider/verify` + +Проверить валидность API ключа. + +**Требования**: Admin права + +**Тело запроса**: +```json +{ + "api_key": "sk-...", + "base_url": "https://api.openai.com/v1" +} +``` + +**Ответ**: +```json +{ + "success": true +} +``` + +### 2. Настройки AI ассистента + +#### GET `/settings/ai-assistant` + +Получить настройки AI ассистента. + +**Требования**: Admin права + +**Ответ**: +```json +{ + "success": true, + "settings": { + "id": 1, + "system_prompt": "Вы — полезный ассистент.", + "selected_rag_tables": [1, 3], + "model": "qwen2.5:7b", + "embedding_model": "mxbai-embed-large:latest", + "rules_id": 2, + "telegram_settings_id": 1, + "email_settings_id": 1, + "ragSettings": { + "searchMethod": "hybrid", + "maxResults": 5 + } + } +} +``` + +#### PUT `/settings/ai-assistant` + +Сохранить/обновить настройки AI ассистента. + +**Требования**: Admin права + +**Тело запроса**: +```json +{ + "system_prompt": "Вы — полезный ассистент.", + "selected_rag_tables": [1], + "model": "qwen2.5:7b", + "embedding_model": "mxbai-embed-large:latest", + "rules_id": 2, + "telegram_settings_id": 1, + "email_settings_id": 1, + "ragSettings": { + "searchMethod": "hybrid", + "maxResults": 5, + "relevanceThreshold": 0.1 + } +} +``` + +**Обработка на Backend**: + +```javascript +// Преобразование selected_rag_tables в массив +let { selected_rag_tables, ...rest } = req.body; + +if (typeof selected_rag_tables === 'string') { + try { + selected_rag_tables = JSON.parse(selected_rag_tables); + } catch { + selected_rag_tables = [Number(selected_rag_tables)]; + } +} + +if (!Array.isArray(selected_rag_tables)) { + selected_rag_tables = [Number(selected_rag_tables)]; +} + +selected_rag_tables = selected_rag_tables.map(Number); +``` + +### 3. Правила AI + +#### GET `/settings/ai-assistant-rules` + +Получить все наборы правил. + +**Требования**: Admin права + +**Ответ**: +```json +{ + "success": true, + "rules": [ + { + "id": 1, + "name": "Строгий режим", + "description": "Только ответы из базы знаний", + "rules": { "checkUserTags": true, "generateIfNoRag": false }, + "created_at": "2025-01-15T10:00:00Z", + "updated_at": "2025-01-15T10:00:00Z" + } + ] +} +``` + +#### GET `/settings/ai-assistant-rules/:id` + +Получить правило по ID. + +**Требования**: Admin права + +#### POST `/settings/ai-assistant-rules` + +Создать новое правило. + +**Требования**: Admin права + +**Тело запроса**: +```json +{ + "name": "Новое правило", + "description": "Описание правила", + "rules": { + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": true + } +} +``` + +#### PUT `/settings/ai-assistant-rules/:id` + +Обновить правило. + +**Требования**: Admin права + +#### DELETE `/settings/ai-assistant-rules/:id` + +Удалить правило. + +**Требования**: Admin права + +### 4. Ollama (локальные модели) + +#### GET `/ollama/status` + +Проверить статус Ollama. + +**Требования**: Авторизация + +**Ответ**: +```json +{ + "connected": true, + "message": "Ollama is running", + "models": 3, + "availableModels": ["qwen2.5:7b", "llama2:7b", "mistral:7b"] +} +``` + +#### GET `/ollama/models` + +Получить список установленных моделей. + +**Требования**: Авторизация + +**Ответ**: +```json +{ + "models": [ + { + "name": "qwen2.5:7b", + "id": "qwen2.5:7b", + "size": 4500000000, + "modified": "2025-01-15T10:00:00Z" + } + ] +} +``` + +#### POST `/ollama/install` + +Установить модель. + +**Требования**: Авторизация + +**Тело запроса**: +```json +{ + "model": "llama2:7b" +} +``` + +**Ответ** (немедленный): +```json +{ + "success": true, + "message": "Installation of llama2:7b started", + "processId": 12345 +} +``` + +**Примечание**: Установка происходит в фоне, не блокирует запрос. + +#### DELETE `/ollama/models/:modelName` + +Удалить модель. + +**Требования**: Авторизация + +### 5. Интеграции + +#### Email + +**GET** `/settings/email-settings` — Получить настройки Email +**PUT** `/settings/email-settings` — Обновить настройки Email +**DELETE** `/settings/email-settings` — Удалить настройки Email +**POST** `/settings/email-settings/test-smtp` — Тест SMTP +**POST** `/settings/email-settings/test-imap` — Тест IMAP +**GET** `/settings/email-settings/list` — Список всех Email настроек + +#### Telegram + +**GET** `/settings/telegram-settings` — Получить настройки Telegram +**PUT** `/settings/telegram-settings` — Обновить настройки Telegram +**DELETE** `/settings/telegram-settings` — Удалить настройки Telegram +**GET** `/settings/telegram-settings/list` — Список всех Telegram ботов + +--- + +## Frontend страницы + +### 1. Главная страница интеграций + +**Путь**: `/settings/ai` +**Компонент**: `AiSettingsView.vue` + +**Блоки интеграций**: + +``` +┌─────────────────────────────────────────────────────┐ +│ Интеграции │ +├─────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ +│ │ OpenAI │ │ Ollama │ │ Telegram ││ +│ │ │ │ │ │ ││ +│ │ [Подробнее]│ │ [Подробнее]│ │ [Подробнее]││ +│ └─────────────┘ └─────────────┘ └─────────────┘│ +│ │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐│ +│ │ Email │ │База данных │ │ИИ-ассистент ││ +│ │ │ │ │ │ ││ +│ │ [Подробнее]│ │ [Подробнее]│ │ [Подробнее]││ +│ └─────────────┘ └─────────────┘ └─────────────┘│ +│ │ +└─────────────────────────────────────────────────────┘ +``` + +**Навигация**: +- `/settings/ai/openai` → Настройки OpenAI +- `/settings/ai/ollama` → Настройки Ollama +- `/settings/ai/telegram` → Настройки Telegram +- `/settings/ai/email` → Настройки Email +- `/settings/ai/database` → Настройки БД +- `/settings/ai/assistant` → Настройки AI ассистента + +### 2. Настройки AI провайдера + +**Путь**: `/settings/ai/:provider` +**Компонент**: `AIProviderSettings.vue` + +**Форма настроек**: + +``` +┌──────────────────────────────────────────────────────────┐ +│ OpenAI [×] │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ Введите OpenAI API Key и (опционально) Base URL. │ +│ │ +│ API Key: │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ sk-... │ │ +│ └────────────────────────────────────────────────────┘ │ +│ [Verify] ✔️ │ +│ │ +│ Base URL: │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ https://api.openai.com/v1 │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Модель (LLM): │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ gpt-4 ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Embeddings-модель: │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ text-embedding-ada-002 ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ [Сохранить] [Удалить ключ] [Закрыть] │ +│ │ +│ ✅ Сохранено! │ +└──────────────────────────────────────────────────────────┘ +``` + +**Логика работы**: + +1. **Загрузка настроек**: При монтировании компонента загружаются сохраненные настройки через `GET /settings/ai-settings/:provider`. + +2. **Verify**: Проверка валидности API ключа через `POST /settings/ai-settings/:provider/verify`. + +3. **Загрузка моделей**: После успешной верификации загружаются доступные модели через `GET /settings/ai-settings/:provider/models` или `/ollama/models` (для Ollama). + +4. **Сохранение**: Сохранение настроек через `PUT /settings/ai-settings/:provider`. + +5. **Удаление**: Удаление настроек через `DELETE /settings/ai-settings/:provider`. + +**Особенности Ollama**: +- Не требуется API Key +- Только Base URL +- Модели загружаются через `/ollama/models` + +### 3. Настройки AI ассистента + +**Путь**: `/settings/ai/assistant` +**Компонент**: `AiAssistantSettings.vue` + +**Основная форма настроек**: + +``` +┌──────────────────────────────────────────────────────────┐ +│ ИИ-ассистент: интеграция и настройки [×] │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ Системный промт │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Вы — полезный ассистент. Отвечайте на русском. │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ 📋 Плейсхолдеры пользовательских таблиц │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Плейсхолдер | Столбец | Таблица │ │ +│ ├────────────────────────────────────────────────────┤ │ +│ │ { email } | Email | Контакты [Ред.] │ │ +│ │ { phone } | Телефон | Контакты [Ред.] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ LLM-модель │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ qwen2.5:7b (ollama) ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Embedding-модель │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ mxbai-embed-large:latest (ollama) ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Выбранные RAG-таблицы │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ FAQ (ID: 1) ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Набор правил │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Гибридный режим ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ [Создать] [Редактировать] [Удалить] │ +│ │ +│ Описание: RAG + генерация при необходимости │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ { │ │ +│ │ "checkUserTags": true, │ │ +│ │ "searchRagFirst": true, │ │ +│ │ "generateIfNoRag": true │ │ +│ │ } │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Telegram-бот │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ @mybot ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Email для связи │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ support@example.com ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ 🔍 Настройки RAG поиска │ +│ (см. ниже) │ +│ │ +│ [Сохранить] [Отмена] │ +└──────────────────────────────────────────────────────────┘ +``` + +--- + +## Настройки RAG поиска + +**Блок в форме AI ассистента**: + +``` +┌──────────────────────────────────────────────────────────┐ +│ 🔍 Настройки RAG поиска │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ Метод поиска │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Гибридный поиск ▼ │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Максимальное количество результатов поиска │ +│ ┌─────┐ │ +│ │ 5 │ │ +│ └─────┘ │ +│ │ +│ Порог релевантности (0.1) │ +│ ├───────────●──────────────────────────────────────┤ │ +│ 0.01 1.0 │ +│ │ +│ 🔑 Извлечение ключевых слов │ +│ ☑ Включить извлечение ключевых слов │ +│ │ +│ Минимальная длина слова: 3 │ +│ Максимальное количество ключевых слов: 10 │ +│ ☑ Удалять стоп-слова │ +│ │ +│ ⚖️ Веса поиска (для гибридного) │ +│ Семантический поиск: 70% │ +│ ├───────────────●────────────────────────────────┤ │ +│ │ +│ Поиск по ключевым словам: 30% │ +│ ├───────●────────────────────────────────────────┤ │ +│ │ +│ ⚙️ Дополнительные настройки │ +│ ☑ Нечеткий поиск │ +│ ☑ Стемминг слов │ +│ ☐ Поиск синонимов │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +**Параметры RAG настроек**: + +| Параметр | Тип | Значение по умолчанию | Описание | +|----------|-----|-----------------------|----------| +| `searchMethod` | `string` | `"hybrid"` | Метод поиска: `semantic`, `keyword`, `hybrid` | +| `maxResults` | `number` | `5` | Максимальное количество результатов (1-20) | +| `relevanceThreshold` | `number` | `0.1` | Порог релевантности (0.01-1.0) | +| `keywordExtraction.enabled` | `boolean` | `true` | Включить извлечение ключевых слов | +| `keywordExtraction.minWordLength` | `number` | `3` | Минимальная длина слова (2-10) | +| `keywordExtraction.maxKeywords` | `number` | `10` | Максимальное количество ключевых слов (5-20) | +| `keywordExtraction.removeStopWords` | `boolean` | `true` | Удалять стоп-слова | +| `searchWeights.semantic` | `number` | `70` | Вес семантического поиска (%) | +| `searchWeights.keyword` | `number` | `30` | Вес поиска по ключевым словам (%) | +| `advanced.enableFuzzySearch` | `boolean` | `true` | Нечеткий поиск | +| `advanced.enableStemming` | `boolean` | `true` | Стемминг слов | +| `advanced.enableSynonyms` | `boolean` | `false` | Поиск синонимов | + +**Сохранение на Backend**: + +```javascript +const settingsToSave = { ...settings.value }; +settingsToSave.ragSettings = ragSettings.value; + +await axios.put('/settings/ai-assistant', settingsToSave); +``` + +--- + +## Правила AI (Rules) + +### Редактор правил + +**Компонент**: `RuleEditor.vue` + +**Модальное окно**: + +``` +┌──────────────────────────────────────────────────────────┐ +│ Создать набор правил │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ Название │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Строгий режим │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Описание │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Только ответы из базы знаний, без генерации │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ Правила (JSON) │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ { │ │ +│ │ "checkUserTags": true, │ │ +│ │ "searchRagFirst": true, │ │ +│ │ "generateIfNoRag": false │ │ +│ │ } │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ [Сохранить] [Отмена] │ +└──────────────────────────────────────────────────────────┘ +``` + +**Логика работы**: + +1. **Создание**: `POST /settings/ai-assistant-rules` с `{ name, description, rules }` +2. **Редактирование**: `PUT /settings/ai-assistant-rules/:id` с `{ name, description, rules }` +3. **Валидация**: Проверка JSON перед сохранением + +```javascript +async function save() { + let rules; + try { + rules = JSON.parse(rulesJson.value); + } catch (e) { + error.value = 'Ошибка в формате JSON!'; + return; + } + + if (props.rule && props.rule.id) { + await axios.put(`/settings/ai-assistant-rules/${props.rule.id}`, { name, description, rules }); + } else { + await axios.post('/settings/ai-assistant-rules', { name, description, rules }); + } + + emit('close', true); +} +``` + +### Примеры правил + +#### 1. Строгий режим (только RAG) + +```json +{ + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": false, + "maxTokens": 300 +} +``` + +**Применение**: Когда нужны только точные ответы из базы знаний. + +#### 2. Гибридный режим (RAG + генерация) + +```json +{ + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": true, + "temperature": 0.7, + "maxTokens": 500 +} +``` + +**Применение**: Баланс между точностью и гибкостью. + +#### 3. Креативный режим + +```json +{ + "checkUserTags": false, + "searchRagFirst": false, + "generateIfNoRag": true, + "temperature": 0.9, + "maxTokens": 1000, + "customInstructions": "Будьте креативны и дружелюбны" +} +``` + +**Применение**: Для общения с пользователями, когда нужна более свободная генерация. + +--- + +## Мониторинг системы + +**Компонент**: `SystemMonitoring.vue` + +**Интерфейс мониторинга**: + +``` +┌──────────────────────────────────────────────────────────┐ +│ 🔍 Мониторинг системы │ +│ [🔄 Обновить статус] Последнее обновление: 12:34:56 │ +├──────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ +│ │ ● Backend │ │ ● Postgres │ │ ● Ollama │ │ +│ │ │ │ │ │ │ │ +│ │ Статус: │ │ Статус: │ │ Статус: │ │ +│ │ Работает │ │ Работает │ │ Работает │ │ +│ │ │ │ │ │ Модели: 3 │ │ +│ └──────────────┘ └──────────────┘ └──────────────┘ │ +│ │ +│ ┌──────────────┐ │ +│ │ ● Vector │ │ +│ │ Search │ │ +│ │ │ │ +│ │ Статус: │ │ +│ │ Работает │ │ +│ └──────────────┘ │ +│ │ +│ 🧠 Тест RAG-функциональности │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Выберите RAG-таблицу: │ │ +│ │ FAQ (ID: 1) ▼ [🔄] │ │ +│ └────────────────────────────────────────────────────┘ │ +│ │ +│ ┌────────────────────────────────────────────────────┐ │ +│ │ Как работает ИИ-ассистент? │ │ +│ └────────────────────────────────────────────────────┘ │ +│ [Тестировать RAG] │ +│ │ +│ 🔍 Ищем ответ в базе знаний... │ +│ ├──────────────────────────●───────────────────────┤ │ +│ 75% │ +│ │ +│ ✅ Успешно! │ +│ Таблица: FAQ │ +│ Вопрос: "Как работает ИИ-ассистент?" │ +│ Ответ: "ИИ-ассистент использует..." │ +│ Score: -120 │ +│ │ +└──────────────────────────────────────────────────────────┘ +``` + +### Статусы сервисов + +**Backend**: `GET /monitoring` + +```json +{ + "services": { + "backend": { + "status": "ok" + }, + "postgres": { + "status": "ok" + }, + "ollama": { + "status": "ok", + "models": 3 + }, + "vectorSearch": { + "status": "ok" + } + } +} +``` + +**Цвета статусов**: +- 🟢 `ok` / `healthy` — Зеленый +- 🟡 `warning` — Желтый +- 🔴 `error` — Красный +- ⚫ `unknown` — Серый + +### Тест RAG + +**Логика теста**: + +1. **Выбор таблицы**: Загружаются все таблицы с `is_rag_source_id === 1` +2. **Ввод вопроса**: Пользователь вводит тестовый вопрос +3. **Запрос**: `POST /rag/answer` с `{ tableId, question, product: null }` +4. **Прогресс-бар**: Симуляция прогресса для UX +5. **Результат**: Отображение ответа и score + +```javascript +const testRAG = async () => { + ragTesting.value = true; + ragResult.value = null; + ragProgress.value = 0; + ragStatus.value = '🔍 Ищем ответ в базе знаний...'; + + const progressInterval = setInterval(() => { + if (ragProgress.value < 90) { + ragProgress.value += Math.random() * 15; + } + }, 1000); + + try { + ragStatus.value = '🤖 Генерируем ответ с помощью ИИ...'; + + const response = await axios.post('/rag/answer', { + tableId: selectedRagTable.value, + question: ragQuestion.value, + product: null + }); + + clearInterval(progressInterval); + ragProgress.value = 100; + ragStatus.value = '✅ Готово!'; + + ragResult.value = { + success: true, + answer: response.data.answer, + score: response.data.score + }; + } catch (error) { + clearInterval(progressInterval); + ragProgress.value = 0; + + ragResult.value = { + success: false, + error: error.response?.data?.error || error.message + }; + } + + ragTesting.value = false; +}; +``` + +--- + +## Заключение + +Система настройки AI ассистента в DLE — это **комплексная платформа** для управления: + +✅ **AI провайдерами** (OpenAI, Anthropic, Google, Ollama) +✅ **Настройками ассистента** (промты, модели, RAG-таблицы) +✅ **Правилами поведения** (JSON конфигурация) +✅ **Интеграциями** (Email, Telegram) +✅ **RAG конфигурацией** (гибридный поиск, ключевые слова) +✅ **Мониторингом** (статусы сервисов, тестирование) + +Все настройки **зашифрованы** (AES-256), имеют **детальные права доступа** (только админы), и предоставляют **гибкую конфигурацию** для различных сценариев использования. + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Версия документа**: 1.0.0 +**Дата создания**: October 25, 2025 +**Статус**: Временный (для внутреннего использования) + diff --git a/docs/ai-assistant.md b/docs/ai-assistant.md new file mode 100644 index 0000000..cf94335 --- /dev/null +++ b/docs/ai-assistant.md @@ -0,0 +1,2510 @@ +# AI Ассистент с векторным поиском - Революция в управлении бизнесом + +## 📋 Содержание + +1. [Введение](#введение) +2. [AI как второй пилот](#ai-как-второй-пилот) +3. [Технология и архитектура](#технология-и-архитектура) +4. [Обслуживание клиентов](#обслуживание-клиентов) +5. [Работа с поставщиками](#работа-с-поставщиками) +6. [Работа с партнерами](#работа-с-партнерами) +7. [Обучение и поддержка персонала](#обучение-и-поддержка-персонала) +8. [Управление персоналом](#управление-персоналом) +9. [Подготовка отчетности и анализ](#подготовка-отчетности-и-анализ) +10. [Подготовка контента для маркетинга](#подготовка-контента-для-маркетинга) +11. [Экономический эффект](#экономический-эффект) +12. [Кейсы применения](#кейсы-применения) +13. [Настройка и интеграция](#настройка-и-интеграция) + +--- + +## Введение + +### Что такое AI Ассистент в DLE? + +**AI Ассистент** - это встроенный интеллектуальный помощник, который использует: +- 🧠 **Ollama** - локальные open-source модели AI (qwen2.5:7b) +- 🔍 **Векторный поиск** - FAISS для семантического поиска +- 📚 **RAG** (Retrieval-Augmented Generation) - поиск по базе знаний +- 💾 **Кэширование** - мгновенные ответы на частые вопросы + +### Ключевые преимущества + +1. **🏠 100% локальный** - все данные на вашем сервере +2. **🔒 Полная конфиденциальность** - ничего не уходит в облако +3. **⚡ Молниеносные ответы** - кэширование и векторный поиск +4. **💰 Нулевые затраты на API** - нет оплаты за токены +5. **📈 Обучается на ваших данных** - персонализированные ответы +6. **🌍 Многоязычный** - поддержка русского, английского и др. +7. **🔄 24/7 доступность** - работает круглосуточно + +--- + +## AI как второй пилот + +### Философия использования: не ВМЕСТО, а ВМЕСТЕ с персоналом + +**⚠️ ВАЖНО**: AI ассистент - это не замена людей, а **второй пилот** для вашей команды. + +``` +┌─────────────────────────────────────────────────────────┐ +│ ДО AI: Сотрудник тонет в рутине │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Рабочий день менеджера: │ +│ │ +│ ⏰ 9:00-11:00 Ответы на типовые вопросы [2 часа] │ +│ ⏰ 11:00-13:00 Подготовка отчетов [2 часа] │ +│ ⏰ 14:00-15:00 Поиск информации [1 час] │ +│ ⏰ 15:00-17:00 Админ. работа, рутина [2 часа] │ +│ ⏰ 17:00-18:00 СТРАТЕГИЯ И КРЕАТИВ [1 час] │ +│ │ +│ 📊 Итого: 7 часов рутины / 1 час креатива │ +│ 😔 Результат: Выгорание, нет роста │ +└─────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────────────────────┐ +│ С AI: Сотрудник - стратег и новатор │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ Рабочий день менеджера + AI: │ +│ │ +│ ✅ AI отвечает на типовые вопросы [AI: 10 минут] │ +│ ✅ AI готовит отчеты [AI: 5 минут] │ +│ ✅ AI находит информацию [AI: 2 минуты] │ +│ ✅ AI берет рутину на себя [AI: 5 минут] │ +│ │ +│ 🚀 9:00-12:00 ПОИСК НОВЫХ РЫНКОВ [3 часа] │ +│ 💡 12:00-14:00 РАЗРАБОТКА НОВЫХ РЕШЕНИЙ [2 часа] │ +│ 🎨 14:00-16:00 КРЕАТИВНЫЕ ПРОЕКТЫ [2 часа] │ +│ 📈 16:00-18:00 СТРАТЕГИЧЕСКОЕ ПЛАНИРОВАНИЕ [2 часа] │ +│ │ +│ 📊 Итого: 22 минуты рутины / 9 часов стратегии │ +│ 🎉 Результат: Рост, инновации, мотивация │ +└─────────────────────────────────────────────────────────┘ +``` + +### Что AI берет на себя (рутина) + +**AI - это ваш ассистент, который:** + +``` +🤖 РУТИННЫЕ ЗАДАЧИ (AI делает автоматически): +├── Ответы на повторяющиеся вопросы +├── Сбор и обработка данных +├── Подготовка типовых отчетов +├── Поиск информации в базах +├── Мониторинг показателей +├── Рассылки и уведомления +├── Первичная обработка заявок +└── Документооборот + +👤 ЧЕЛОВЕК ФОКУСИРУЕТСЯ НА: +├── 🎯 Стратегическом планировании +├── 💡 Поиске новых решений +├── 🚀 Выходе на новые рынки +├── 🎨 Креативных проектах +├── 🤝 Важных переговорах +├── 📊 Анализе трендов +├── 🔬 Инновациях +└── 💼 Развитии бизнеса +``` + +### Реальные примеры трансформации ролей + +#### Пример 1: Менеджер по продажам + +**Было (без AI):** +``` +Иван - менеджер по продажам: +├── 60% времени: Ответы на вопросы клиентов +├── 20% времени: Подготовка КП и отчетов +├── 15% времени: Админ. работа +└── 5% времени: Поиск новых клиентов ❌ + +Результат: 2 новых клиента/месяц +``` + +**Стало (с AI):** +``` +Иван + AI второй пилот: +├── AI отвечает на 80% вопросов клиентов +├── AI готовит КП автоматически +├── AI берет админ. работу +└── Иван: 90% времени на продажи! ✅ + +Новая роль: "Стратег продаж" +├── 40% времени: Поиск новых ниш +├── 30% времени: Крупные сделки +├── 20% времени: Развитие партнерств +└── 10% времени: Обучение команды + +Результат: 12 новых клиентов/месяц (+500%) +``` + +#### Пример 2: Закупщик + +**Было (без AI):** +``` +Мария - закупщик: +├── 50% времени: Запросы цен у поставщиков +├── 30% времени: Сравнение предложений +├── 15% времени: Рутинные заказы +└── 5% времени: Поиск новых поставщиков ❌ + +Результат: Работа с 10 проверенными поставщиками +``` + +**Стало (с AI):** +``` +Мария + AI закупщик: +├── AI запрашивает цены у 100+ поставщиков +├── AI сравнивает и ранжирует предложения +├── AI делает рутинные заказы +└── Мария: 80% времени на стратегию! ✅ + +Новая роль: "Директор по закупкам" +├── 40% времени: Поиск новых рынков поставок +├── 30% времени: Стратегические партнерства +├── 20% времени: Оптимизация цепочек +└── 10% времени: Переговоры об эксклюзиве + +Результат: 47 новых поставщиков, экономия 15% +``` + +#### Пример 3: Маркетолог + +**Было (без AI):** +``` +Анна - контент-менеджер: +├── 70% времени: Написание постов/статей +├── 20% времени: Подбор изображений +├── 5% времени: Публикация +└── 5% времени: Новые идеи кампаний ❌ + +Результат: 10 постов/неделю, мало креатива +``` + +**Стало (с AI):** +``` +Анна + AI контент-генератор: +├── AI пишет черновики постов/статей +├── AI подбирает изображения +├── AI публикует по расписанию +└── Анна: 85% времени на креатив! ✅ + +Новая роль: "Креативный директор" +├── 50% времени: Разработка новых кампаний +├── 25% времени: Тестирование гипотез +├── 15% времени: Анализ трендов +└── 10% времени: Редактура контента AI + +Результат: 50 постов/неделю, 3 вирусных кампании +``` + +### Как это работает на практике + +**Модель "Пилот + Второй пилот":** + +``` +┌─────────────────────────────────────────┐ +│ ЧЕЛОВЕК (Пилот) │ +│ • Видение и стратегия │ +│ • Креатив и инновации │ +│ • Важные решения │ +│ • Сложные переговоры │ +│ • Развитие направлений │ +└────────────┬────────────────────────────┘ + │ + ↕ Постоянная коммуникация + │ +┌────────────┴────────────────────────────┐ +│ AI (Второй пилот) │ +│ • Сбор и анализ данных │ +│ • Рутинные операции │ +│ • Первичная обработка │ +│ • Мониторинг и алерты │ +│ • Исполнение по алгоритмам │ +└─────────────────────────────────────────┘ + +Результат: Синергия, где 1 + 1 = 5 +``` + +### Метрики трансформации + +**Распределение времени типичного сотрудника:** + +| Тип задач | Без AI | С AI | Изменение | +|-----------|--------|------|-----------| +| **Рутина** | 70% | 5% | -93% ⬇️ | +| **Операционка** | 20% | 15% | -25% ⬇️ | +| **Стратегия** | 5% | 40% | +700% ⬆️ | +| **Креатив** | 3% | 30% | +900% ⬆️ | +| **Развитие** | 2% | 10% | +400% ⬆️ | + +**Результаты для бизнеса:** + +``` +До AI (команда 10 человек): +├── Операционная работа: 9 человек +├── Стратегическая работа: 1 человек +└── Инновации: 0 человек + +После AI (та же команда 10 человек): +├── Операционная работа: 2 человека + AI +├── Стратегическая работа: 5 человек +├── Инновации: 3 человека +└── Эффективность: +300% + +💡 НЕ НУЖНО нанимать больше людей +✅ МОЖНО делать в 3 раза больше той же командой +``` + +### Новые возможности для команды + +**Что становится возможным:** + +1. **🌍 Выход на новые рынки** + ``` + Было: Нет времени изучать новые рынки + Стало: AI собирает данные → Команда анализирует и принимает решения + Результат: 3 новых рынка в год + ``` + +2. **💡 Разработка новых продуктов** + ``` + Было: Продуктовая разработка раз в год + Стало: Время для экспериментов → Быстрое тестирование гипотез + Результат: 5 новых продуктов в год + ``` + +3. **🎨 Креативные кампании** + ``` + Было: Стандартный маркетинг + Стало: Время для креатива → Инновационные кампании + Результат: 2 вирусных кампании в квартал + ``` + +4. **🔬 R&D и инновации** + ``` + Было: Нет ресурсов на исследования + Стало: AI берет рутину → Команда исследует тренды + Результат: Опережение конкурентов на 6-12 месяцев + ``` + +5. **🤝 Стратегические партнерства** + ``` + Было: Работа с существующими партнерами + Стало: Время на networking → Новые альянсы + Результат: 10+ новых стратегических партнеров + ``` + +### Эволюция ролей в команде + +**Как меняются роли:** + +``` +ТРАДИЦИОННАЯ РОЛЬ → С AI ВТОРЫМ ПИЛОТОМ +════════════════════════════════════════════ + +📞 Оператор поддержки → 🎯 Специалист по customer experience + • Решение сложных кейсов + • Улучшение UX + • Развитие программ лояльности + +📦 Закупщик → 🌐 Директор по глобальным закупкам + • Поиск поставщиков в новых странах + • Стратегические контракты + • Оптимизация supply chain + +👥 HR-менеджер → 🎓 Директор по развитию талантов + • Культура и вовлеченность + • Программы роста + • Стратегическое планирование HR + +💼 Продажник → 🚀 Стратег развития бизнеса + • Новые ниши и сегменты + • Крупные B2B сделки + • Партнерские программы + +📝 Контент-менеджер → 🎨 Креативный директор + • Инновационные форматы + • Вирусные кампании + • Бренд-стратегия +``` + +### Почему это работает + +**3 принципа успеха:** + +1. **🤖 AI делает что умеет лучше всего** + - Быстрая обработка больших объемов данных + - Работа 24/7 без усталости + - Мгновенный поиск по базам знаний + - Следование четким алгоритмам + +2. **👤 Человек делает что умеет лучше всего** + - Стратегическое мышление + - Креативные решения + - Эмоциональный интеллект + - Нестандартные подходы + +3. **🤝 Синергия = Множитель результатов** + - AI дает данные → Человек принимает решения + - AI выполняет → Человек контролирует + - AI автоматизирует → Человек инновирует + - **Результат: 1 + 1 = 5** + +--- + +## Технология и архитектура + +### Как это работает? + +``` +┌─────────────────────────────────────────────────────────┐ +│ Архитектура AI Ассистента │ +└─────────────────────────────────────────────────────────┘ + +┌─────────────────────────────────────────┐ +│ 1. Пользователь задает вопрос │ +│ "Как вернуть товар?" │ +└────────────────┬────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 2. Векторизация вопроса │ +│ Ollama mxbai-embed-large:latest │ +│ Текст → Вектор [768 чисел] │ +└────────────────┬────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 3. Векторный поиск (FAISS) │ +│ Поиск похожих вопросов в базе │ +│ Top-3 результата по семантике │ +└────────────────┬────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 4. Контекстный поиск (RAG) │ +│ Извлечение ответов из базы знаний │ +│ Фильтрация по тегам/продуктам │ +└────────────────┬────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 5. Генерация ответа (LLM) │ +│ Ollama qwen2.5:7b │ +│ Контекст + Вопрос → Ответ │ +└────────────────┬────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 6. Кэширование │ +│ Сохранение в кэш на 1 час │ +│ Следующий такой же вопрос < 50ms │ +└────────────────┬────────────────────────┘ + ↓ +┌─────────────────────────────────────────┐ +│ 7. Ответ пользователю │ +│ "Товар можно вернуть в течение..." │ +└─────────────────────────────────────────┘ +``` + +### Технологический стек + +| Компонент | Технология | Назначение | +|-----------|------------|------------| +| **LLM модель** | Ollama qwen2.5:7b | Генерация текста, диалог | +| **Embedding модель** | mxbai-embed-large | Векторизация текста | +| **Векторная БД** | FAISS | Быстрый семантический поиск | +| **Основная БД** | PostgreSQL | Хранение базы знаний | +| **Кэш** | Node.js Map + TTL | Ускорение повторных запросов | +| **Очередь** | AI Queue | Обработка задач по приоритету | + +### Сравнение с облачными решениями + +| Характеристика | DLE AI (Локальный) | ChatGPT API | Claude API | +|----------------|-------------------|-------------|------------| +| **Стоимость** | $0 | ~$0.02/запрос | ~$0.03/запрос | +| **Конфиденциальность** | ✅ 100% | ❌ Данные в OpenAI | ❌ Данные в Anthropic | +| **Скорость (кэш)** | 50ms | 500-2000ms | 500-2000ms | +| **Offline работа** | ✅ Да | ❌ Нет | ❌ Нет | +| **Настройка под бизнес** | ✅ Полная | ⚠️ Ограниченная | ⚠️ Ограниченная | +| **Лимиты API** | ❌ Нет | ✅ Есть | ✅ Есть | + +**Экономия**: При 10,000 запросов в месяц: +- ChatGPT API: $200/месяц = **$2,400/год** +- Claude API: $300/месяц = **$3,600/год** +- DLE AI: **$0/год** ✅ + +--- + +## Обслуживание клиентов + +### Проблемы, которые решает AI + +**Традиционные проблемы:** +- ❌ Клиенты ждут ответа 24+ часа +- ❌ Поддержка работает только 9-18 +- ❌ Одинаковые вопросы задают сотни раз +- ❌ Нужно нанимать много операторов +- ❌ Человеческий фактор (усталость, ошибки) + +**Решение с DLE AI:** +- ✅ Мгновенные ответы 24/7 +- ✅ Обрабатывает неограниченное количество запросов одновременно +- ✅ Единая база знаний для всех каналов +- ✅ Снижение нагрузки на операторов на 70-80% +- ✅ Всегда вежливый и точный + +### Практическое применение + +#### 1. Автоматические ответы на частые вопросы + +**Настройка базы знаний:** + +``` +Вопрос: Как оформить возврат товара? +Ответ: Возврат товара возможен в течение 14 дней с момента покупки. + Для этого: + 1. Заполните форму на нашем сайте + 2. Укажите номер заказа + 3. Опишите причину возврата + 4. Мы свяжемся с вами в течение 24 часов + +Теги: #возврат #гарантия #качество +Приоритет: Высокий +``` + +**Результат:** +- AI мгновенно отвечает на вопросы о возврате +- Клиент получает полную информацию без ожидания +- Оператор освобожден для сложных задач + +#### 2. Интеграция с мессенджерами + +**Telegram бот с AI:** + +```javascript +// Клиент пишет в Telegram +Клиент: Здравствуйте! У меня не работает продукт + +AI: Здравствуйте! Подскажите, пожалуйста: + 1. Какой у вас номер заказа? + 2. Какая именно проблема возникла? + 3. Вы следовали инструкции по установке? + +Клиент: Заказ #12345, не запускается приложение + +AI: [Поиск в базе знаний по заказу и проблеме] + Спасибо! Вижу ваш заказ. Проблема с запуском обычно связана с: + + 1. Проверьте системные требования... + 2. Попробуйте переустановить... + 3. Если не помогло, наш специалист свяжется с вами + + [Автоматически создает тикет в CRM] +``` + +**Преимущества:** +- Моментальная первичная диагностика +- Автоматическое создание тикетов +- База знаний в реальном времени +- История диалога сохраняется + +#### 3. Email поддержка + +**AI анализирует входящие письма:** + +``` +Письмо от клиента → AI анализирует +↓ +Определяет категорию (возврат/техподдержка/вопрос) +↓ +Извлекает ключевую информацию (номер заказа, проблема) +↓ +Формирует черновик ответа +↓ +Отправляет оператору на проверку ИЛИ отвечает автоматически +``` + +**Экономия времени:** +- Без AI: 5-10 минут на письмо +- С AI: 30 секунд на проверку и отправку +- **Эффективность +900%** + +#### 4. Чат на сайте + +**Умный виджет чата:** + +```html + +Посетитель: Сколько стоит доставка в Казахстан? + +AI: Доставка в Казахстан: + • Стандартная (7-10 дней): $15 + • Экспресс (3-5 дней): $35 + • Бесплатная доставка при заказе от $200 + + Хотите оформить заказ? + +Посетитель: Да, есть ли у вас красные кроссовки 42 размера? + +AI: [Поиск в каталоге товаров] + Да! У нас есть 3 модели красных кроссовок 42 размера: + + 1. Nike Air Max - $120 (в наличии) + 2. Adidas UltraBoost - $150 (в наличии) + 3. Puma RS-X - $95 (осталось 2 шт.) + + [Показывает карточки товаров] +``` + +### Результаты для бизнеса + +**Метрики до внедрения AI:** +- Время ответа: 8 часов +- Операторов: 5 человек +- Обработано запросов: 500/день +- Стоимость поддержки: $8,000/месяц +- Удовлетворенность клиентов: 72% + +**Метрики после внедрения AI:** +- Время ответа: 30 секунд (кэш) / 5 секунд (новый) +- Операторов: 2 человека (для сложных случаев) +- Обработано запросов: 2,000/день +- Стоимость поддержки: $3,200/месяц +- Удовлетворенность клиентов: 91% + +**Экономия: $4,800/месяц = $57,600/год** 💰 + +--- + +## Работа с поставщиками + +### AI как полноценный отдел снабжения + +AI ассистент не просто помогает - он **заменяет целый отдел снабжения**: + +- 🔍 **AI-закупщик** - анализирует рынок, находит лучших из лучших поставщиков +- 📊 **Маркетолог снабжения** - сравнивает 100+ вариантов за 15 минут +- 💼 **Переговорщик** - формирует аргументы для улучшения условий +- 📈 **Аналитик** - отслеживает тренды, цены, новых игроков +- ⚠️ **Мониторинг 24/7** - контролирует поставки, предупреждает о рисках + +**Результат**: Вы всегда работаете с лучшими поставщиками по лучшим ценам. + +### Автоматизация коммуникации + +#### 1. Автоматические запросы цен + +**AI формирует запросы поставщикам:** + +``` +База знаний: Шаблоны запросов для каждого поставщика + +AI генерирует: + +Тема: Запрос коммерческого предложения #2024-12-15 + +Добрый день! + +Прошу предоставить коммерческое предложение на следующие позиции: + +1. [Товар A] - 100 шт. +2. [Товар B] - 50 шт. +3. [Товар C] - 200 шт. + +Интересуют: +• Цена с НДС и без НДС +• Сроки поставки +• Условия оплаты +• Минимальная партия + +Ждем ответ до [дата + 3 дня]. + +С уважением, +[Ваша компания] +``` + +**Автоматизация:** +- AI отслеживает остатки на складе +- Автоматически формирует запросы при низких остатках +- Отправляет запросы всем подходящим поставщикам +- Сравнивает полученные предложения + +#### 2. Анализ договоров и условий + +**AI проверяет входящие договоры:** + +```python +Договор от поставщика → AI анализирует + +Проверяет: +✓ Цены (сравнение с рынком и историей) +✓ Сроки поставки +✓ Условия оплаты +✓ Штрафы и неустойки +✓ Гарантийные обязательства + +Результат: +┌─────────────────────────────────────────┐ +│ Анализ договора №12345 │ +├─────────────────────────────────────────┤ +│ ✅ Цены конкурентные (-5% от рынка) │ +│ ✅ Сроки поставки приемлемые (7 дней) │ +│ ⚠️ Условия оплаты: 100% предоплата │ +│ Рекомендация: Попросить отсрочку │ +│ ❌ Штраф за просрочку 0.1%/день │ +│ Рекомендация: Снизить до 0.05% │ +│ ✅ Гарантия 12 месяцев │ +└─────────────────────────────────────────┘ + +Рекомендация: СОГЛАСОВАТЬ С ПРАВКАМИ +``` + +#### 3. Отслеживание поставок + +**AI мониторит статус заказов:** + +``` +Заказ #12345 от ООО "Поставщик А" +├── Создан: 15.12.2024 +├── Ожидаемая поставка: 22.12.2024 +├── Статус: В пути +└── Трек-номер: TN123456789 + +AI проверяет: +• Обновления трека каждые 4 часа +• Если задержка > 2 дней → Уведомление менеджеру +• Автоматическое напоминание поставщику +• Обновление ETA в системе +``` + +**Уведомления:** +``` +🚨 ВНИМАНИЕ: Заказ #12345 задерживается + +Ожидалось: 22.12.2024 +Текущий статус: Таможенное оформление +Новая дата: 25.12.2024 (задержка 3 дня) + +Действия: +1. Отправлено напоминание поставщику +2. Уведомлены клиенты, ожидающие товар +3. Пересчитаны сроки выполнения заказов + +[Просмотреть детали] +``` + +#### 4. База знаний о поставщиках + +**AI хранит всю информацию:** + +``` +База данных поставщиков: + +ООО "Поставщик А" +├── Контакты: +7 (XXX) XXX-XX-XX, email@supplier-a.com +├── Специализация: Электроника +├── Условия: Отсрочка 14 дней, мин. заказ $500 +├── Рейтинг: 4.5/5 ⭐⭐⭐⭐½ +├── История: +│ ├── Поставок: 127 +│ ├── Задержки: 5 (3.9%) +│ ├── Брак: 2 (1.6%) +│ └── Средний чек: $1,250 +└── Примечания: Надежный, быстрая обработка заказов + +Вопрос менеджера: "У кого заказать микросхемы?" + +AI: Рекомендую ООО "Поставщик А": + • Специализируется на электронике + • Низкий процент брака (1.6%) + • Конкурентные цены + • Отсрочка платежа 14 дней + + Альтернативы: + • ООО "Поставщик Б" - дешевле на 5%, но мин. заказ $1000 + • ИП "Поставщик В" - быстрая доставка (2 дня), но предоплата +``` + +#### 5. AI как закупщик - анализ рынка и поиск лучших + +**AI выполняет роль профессионального закупщика:** + +``` +Задача: Найти нового поставщика электроники + +AI анализирует рынок: +├── Поиск в интернете (B2B площадки, каталоги) +├── Анализ отзывов и рейтингов +├── Сравнение цен и условий +├── Проверка репутации +├── Оценка рисков +└── Формирование рекомендаций + +Результат поиска: +┌─────────────────────────────────────────────────────────┐ +│ АНАЛИЗ РЫНКА: Поставщики электроники │ +├─────────────────────────────────────────────────────────┤ +│ Найдено: 47 потенциальных поставщиков │ +│ Проанализировано: 47 │ +│ Соответствуют критериям: 12 │ +│ │ +│ ТОП-3 РЕКОМЕНДАЦИИ: │ +│ │ +│ 🥇 #1: ООО "ЭлектроПрайм" [ЛУЧШИЙ ВЫБОР] │ +│ ├── Рейтинг: 4.8/5 ⭐⭐⭐⭐⭐ │ +│ ├── Опыт: 12 лет на рынке │ +│ ├── Цены: На 8% ниже среднерыночных │ +│ ├── Условия: Отсрочка 21 день, мин. заказ $300 │ +│ ├── Доставка: 3-5 дней, бесплатно от $500 │ +│ ├── Отзывы: 248 положительных (95%) │ +│ ├── Брак: < 1% (отличный показатель) │ +│ └── Контакты: +7 (495) XXX-XX-XX, info@electroprime.ru│ +│ │ +│ 🥈 #2: ИП "ТехноМастер" │ +│ ├── Рейтинг: 4.6/5 ⭐⭐⭐⭐ │ +│ ├── Опыт: 8 лет │ +│ ├── Цены: Средние по рынку │ +│ ├── Условия: Предоплата 50%, остаток при получении │ +│ ├── Доставка: 2-3 дня (быстро!) │ +│ ├── Отзывы: 156 положительных (92%) │ +│ ├── Брак: 1.5% │ +│ └── Плюс: Эксклюзивные бренды в ассортименте │ +│ │ +│ 🥉 #3: ООО "МегаЭлектро" │ +│ ├── Рейтинг: 4.5/5 ⭐⭐⭐⭐ │ +│ ├── Опыт: 15 лет (крупный игрок) │ +│ ├── Цены: На 3% выше среднерыночных │ +│ ├── Условия: Отсрочка 30 дней, мин. заказ $1000 │ +│ ├── Доставка: 5-7 дней │ +│ ├── Отзывы: 892 положительных (94%) │ +│ ├── Брак: < 0.5% (минимальный!) │ +│ └── Плюс: Гарантия 36 месяцев (лучшая на рынке) │ +└─────────────────────────────────────────────────────────┘ + +AI РЕКОМЕНДАЦИЯ: +✅ Начать с ООО "ЭлектроПрайм" (оптимальное соотношение + цена/качество/условия) + +💡 СТРАТЕГИЯ: +1. Сделать пробный заказ ($500-1000) +2. Оценить качество и сроки +3. При успехе - заключить долгосрочный контракт +4. Держать ИП "ТехноМастер" как резервного поставщика + +[Связаться с поставщиком] [Запросить КП] [Подробный отчет] +``` + +**Критерии анализа рынка:** + +```python +AI оценивает поставщиков по 15 параметрам: + +1. ЦЕНЫ (вес 25%) + ├── Сравнение с конкурентами + ├── Динамика изменения цен + ├── Скидки на объем + └── Скрытые комиссии + +2. КАЧЕСТВО (вес 20%) + ├── Процент брака + ├── Сертификаты качества + ├── Гарантийные обязательства + └── Отзывы клиентов + +3. НАДЕЖНОСТЬ (вес 20%) + ├── Процент задержек поставок + ├── Опыт работы на рынке + ├── Финансовая стабильность + └── Наличие складских запасов + +4. УСЛОВИЯ (вес 15%) + ├── Минимальный заказ + ├── Условия оплаты (отсрочка/предоплата) + ├── Условия возврата + └── Возможность обмена + +5. ЛОГИСТИКА (вес 10%) + ├── Сроки доставки + ├── Стоимость доставки + ├── География доставки + └── Упаковка и страхование + +6. СЕРВИС (вес 10%) + ├── Скорость ответа на запросы + ├── Помощь в подборе + ├── Техническая поддержка + └── Обучение и консультации + +ИТОГОВАЯ ОЦЕНКА = Σ (параметр × вес) +``` + +**Мониторинг рынка в реальном времени:** + +``` +AI отслеживает изменения на рынке: + +┌─────────────────────────────────────────┐ +│ РЫНОЧНАЯ АНАЛИТИКА │ +├─────────────────────────────────────────┤ +│ 📊 Средняя цена на [товар]: │ +│ $45.20 (↓ -2.3% за месяц) │ +│ │ +│ 📈 Тренды: │ +│ • Спрос растет на 12%/месяц │ +│ • Новые поставщики: +5 за месяц │ +│ • Средний срок доставки: 4.2 дня │ +│ │ +│ ⚠️ АЛЕРТЫ: │ +│ • Ваш поставщик поднял цены на 5% │ +│ Рекомендация: Пересмотреть договор │ +│ │ +│ • Конкурент предлагает -10% │ +│ Рекомендация: Запросить КП │ +│ │ +│ 💡 ВОЗМОЖНОСТИ: │ +│ • Сезонная распродажа у Поставщика X │ +│ Потенциальная экономия: $12,000 │ +└─────────────────────────────────────────┘ + +[Подробнее] [Настроить алерты] +``` + +**Автоматический поиск альтернатив:** + +```javascript +// AI постоянно ищет лучшие предложения + +Сценарий 1: Поставщик поднял цены +AI обнаруживает → Ищет альтернативы → Находит 3 варианта + → Сравнивает → Уведомляет менеджера + +Сценарий 2: Появился новый поставщик +AI находит → Анализирует репутацию → Сравнивает условия + → Если выгодно → Рекомендует рассмотреть + +Сценарий 3: Текущий поставщик задерживает поставки +AI фиксирует → Снижает рейтинг → Активирует поиск замены + → Предлагает резервных поставщиков + +Результат: Всегда работаете с ЛУЧШИМИ поставщиками +``` + +**Переговоры и оптимизация условий:** + +``` +AI помогает в переговорах: + +Менеджер: Нужно договориться об отсрочке платежа + +AI анализирует: +├── Текущие условия: Предоплата 100% +├── Рыночные условия: 68% поставщиков дают отсрочку +├── Средняя отсрочка: 14-21 день +├── История с этим поставщиком: 15 заказов, всегда вовремя +└── Оборот с поставщиком: $180,000/год + +AI формирует аргументы: +┌─────────────────────────────────────────┐ +│ ПЕРЕГОВОРНАЯ ПОЗИЦИЯ │ +├─────────────────────────────────────────┤ +│ Запросить: Отсрочку 14 дней │ +│ │ +│ Аргументы: │ +│ ✓ Долгосрочное сотрудничество (15 зак.) │ +│ ✓ Стабильные объемы ($180K/год) │ +│ ✓ Всегда оплата вовремя (100% record) │ +│ ✓ 68% рынка работает с отсрочкой │ +│ ✓ Планируем увеличить объем на 30% │ +│ │ +│ Запасная позиция: │ +│ Если отказ → Предложить: │ +│ • 50% предоплата / 50% отсрочка 7 дней │ +│ • Или личная гарантия │ +│ │ +│ Альтернатива: │ +│ ООО "Конкурент" предлагает отсрочку │ +│ 21 день по тем же ценам │ +└─────────────────────────────────────────┘ + +[Отправить письмо] [Позвонить] [Сменить поставщика] +``` + +**Экономический эффект от AI-закупщика:** + +``` +Традиционный закупщик: +├── Зарплата: $36,000/год +├── Анализирует: 5-10 поставщиков +├── Время на поиск: 2 недели +├── Переговоры: 3-5 дней +└── Мониторинг рынка: периодически + +AI закупщик: +├── Стоимость: $0 (включен в DLE) +├── Анализирует: 100+ поставщиков +├── Время на поиск: 15 минут +├── Переговоры: помощь аргументами +└── Мониторинг рынка: 24/7 в реальном времени + +Экономия: $36,000/год + лучшие условия +``` + +**Интеграция с маркетплейсами:** + +``` +AI работает с популярными B2B площадками: + +• Alibaba.com - международные поставщики +• ThomasNet - промышленное оборудование +• GlobalSources - азиатские производители +• TradeBids - тендеры и закупки +• Kompass - европейские поставщики + +Автоматически: +✓ Парсит каталоги +✓ Сравнивает цены +✓ Собирает отзывы +✓ Формирует отчеты +✓ Уведомляет о выгодных предложениях +``` + +### Результаты + +**До AI:** +- Время на запрос цен: 2 часа +- Анализ договора: 4 часа (юрист) +- Отслеживание: вручную, часто пропускается +- Поиск поставщиков: 2 недели +- Ошибки в заказах: 5% +- Закупщик: $36,000/год + +**С AI:** +- Время на запрос цен: 5 минут +- Анализ договора: 10 минут + рекомендации +- Отслеживание: автоматическое 24/7 +- Поиск поставщиков: 15 минут (анализ 100+ вариантов) +- Ошибки в заказах: 0.5% +- AI закупщик: $0 (включен) + +**Экономия:** +- Время: 20 часов/неделю = $28,800/год +- Закупщик: $36,000/год +- **ИТОГО: $64,800/год** 💰 + +--- + +## Работа с партнерами + +### Коллаборация и управление проектами + +#### 1. Автоматическая подготовка презентаций + +**AI создает презентации для партнеров:** + +``` +Запрос: Подготовить презентацию для партнера о новом продукте + +AI: +1. Анализирует характеристики продукта в базе +2. Извлекает статистику продаж похожих продуктов +3. Формирует конкурентные преимущества +4. Генерирует текст презентации + +Результат (PDF, 12 слайдов): + +Слайд 1: Обложка +Слайд 2: О нашей компании +Слайд 3: Новый продукт [Название] +Слайд 4: Характеристики +Слайд 5: Конкурентные преимущества +Слайд 6: Целевая аудитория +Слайд 7: Прогноз продаж +Слайд 8: Условия партнерства +Слайд 9: Маржинальность +Слайд 10: План запуска +Слайд 11: Поддержка партнеров +Слайд 12: Контакты и следующие шаги + +Время: 15 минут (вместо 4 часов) +``` + +#### 2. Управление партнерскими программами + +**AI отслеживает эффективность партнеров:** + +```sql +Партнерская аналитика: + +Партнер: ООО "Дистрибьютор Х" +┌─────────────────────────────────────────┐ +│ Продажи за квартал │ +├─────────────────────────────────────────┤ +│ Октябрь: $45,000 ✅ (+12% к плану) │ +│ Ноябрь: $38,000 ⚠️ (-5% к плану) │ +│ Декабрь: $52,000 ✅ (+18% к плану) │ +│ ИТОГО: $135,000 │ +├─────────────────────────────────────────┤ +│ Комиссия: $13,500 (10%) │ +│ Статус: GOLD партнер │ +└─────────────────────────────────────────┘ + +AI рекомендации: +✅ Партнер показывает хорошие результаты +⚠️ Просадка в ноябре - возможно сезонность +💡 Предложить расширение ассортимента +📧 Отправить поздравление с достижением плана +``` + +**Автоматизация:** +- Еженедельные отчеты партнерам +- Автоматический расчет комиссий +- Напоминания о дедлайнах +- Персонализированные предложения + +#### 3. База знаний для партнеров + +**AI обучает партнеров:** + +``` +Портал для партнеров с AI чатом: + +Партнер: Как правильно позиционировать продукт А? + +AI: Продукт А лучше всего позиционировать как: + + 📌 Целевая аудитория: Малый бизнес (5-50 сотрудников) + + 🎯 Ключевые преимущества: + • Экономия времени до 30% + • Простота внедрения (1 день) + • Не требует обучения персонала + + 💬 Скрипт продажи: + "Наш продукт помогает малому бизнесу автоматизировать + [процесс X] за 1 день. Ваши клиенты экономят до 30% + времени, а стоимость окупается за 2 месяца." + + 📊 Успешные кейсы: + • Компания "Пример 1" - увеличила продажи на 40% + • ИП "Пример 2" - сократил издержки на 25% + + 📎 Материалы: + [Скачать презентацию] [Скачать прайс-лист] +``` + +#### 4. Совместные маркетинговые кампании + +**AI планирует кампании:** + +``` +Запрос: Спланировать совместную кампанию с Партнером Y + +AI анализирует: +├── Историю продаж с этим партнером +├── Сезонность спроса +├── Бюджет партнера +├── Целевую аудиторию +├── Конкурентную среду +└── Успешные кампании в прошлом + +Рекомендация: +┌─────────────────────────────────────────┐ +│ План маркетинговой кампании │ +├─────────────────────────────────────────┤ +│ Период: 01.02.2025 - 28.02.2025 │ +│ Бюджет: $10,000 (50/50 с партнером) │ +│ Канал: Instagram + Email │ +│ │ +│ Механика: │ +│ • Скидка 20% на комплект продуктов │ +│ • Бесплатная доставка │ +│ • Розыгрыш главного приза │ +│ │ +│ Прогноз: │ +│ • Охват: 50,000 человек │ +│ • Конверсия: 2.5% │ +│ • Продажи: $62,500 │ +│ • ROI: 525% │ +│ │ +│ [Принять план] [Редактировать] │ +└─────────────────────────────────────────┘ +``` + +### Результаты + +**До AI:** +- Подготовка презентации: 4 часа +- Отчет партнеру: 1 час/неделя +- Обучение партнеров: личные встречи +- Планирование кампаний: 2 дня + +**С AI:** +- Подготовка презентации: 15 минут +- Отчет партнеру: автоматически +- Обучение партнеров: 24/7 AI чат +- Планирование кампаний: 2 часа + +**Экономия: 30 часов/месяц = $3,600/год** 💰 + +--- + +## Обучение и поддержка персонала + +### Онбординг новых сотрудников + +#### 1. Интерактивный AI наставник + +**AI обучает новичков:** + +``` +День 1: Добро пожаловать в компанию! + +AI: Привет! Я ваш AI наставник. Помогу освоиться в компании. + + Сегодня изучим: + ✓ Структуру компании + ✓ Основные продукты + ✓ Корпоративную культуру + ✓ Рабочие инструменты + + Готовы начать? [Да, начнем!] + +--- + +Сотрудник: Расскажи о структуре компании + +AI: Наша компания состоит из 5 отделов: + + 1. 📊 Продажи (12 человек) - Руководитель: Иван Петров + 2. 🛠️ Разработка (8 человек) - Руководитель: Анна Сидорова + 3. 🎨 Маркетинг (5 человек) - Руководитель: Мария Кузнецова + 4. 💼 HR и администрация (3 человека) - Руководитель: Ольга Смирнова + 5. 🔧 Техподдержка (4 человека) - Руководитель: Петр Васильев + + Вы в отделе: [Продажи] + Ваш руководитель: Иван Петров + + [Посмотреть оргструктуру] [Познакомиться с коллегами] + +--- + +Сотрудник: Как пользоваться CRM? + +AI: Отличный вопрос! Наша CRM - это [Название]. + + 📹 Вот видео-инструкция (5 минут): + [Встроенное видео] + + Основные функции: + 1. Создание клиента: Меню → Клиенты → Добавить + 2. Создание сделки: Клиент → Новая сделка + 3. Отправка писем: Встроенный почтовый клиент + + 💡 Совет: Используйте шаблоны писем для ускорения работы + + Попробуете создать тестового клиента? + [Открыть CRM] [Задать вопрос] +``` + +**Отслеживание прогресса:** + +``` +Онбординг: Иван Иванов (День 3/14) + +Прогресс: ████████░░░░░░░░░░░░ 40% + +Завершено: +✅ Изучение структуры компании +✅ Знакомство с продуктами +✅ Обучение CRM +✅ Изучение скриптов продаж + +В процессе: +🔄 Практика холодных звонков + +Планируется: +⏳ Изучение возражений +⏳ Работа с документами +⏳ Финансовая отчетность + +Рекомендация AI: +💡 Иван быстро осваивает CRM (на 2 дня опережает график). + Можно перейти к практике холодных звонков уже сегодня. +``` + +#### 2. База знаний компании + +**Единая база знаний для всех:** + +``` +Поиск в базе знаний: + +Сотрудник: Как обработать возврат товара? + +AI: [Поиск по базе...] + + 📖 Процедура возврата товара + + Шаг 1: Проверка условий возврата + ✓ Товар возвращается в течение 14 дней + ✓ Сохранена упаковка и товарный вид + ✓ Есть чек/накладная + + Шаг 2: Оформление в системе + 1. Откройте заказ клиента в CRM + 2. Нажмите "Оформить возврат" + 3. Выберите причину возврата + 4. Укажите способ возврата денег + + Шаг 3: Финансы + • Банковская карта: 3-5 рабочих дней + • Наличные: в день обращения (касса) + • На счет: 5-7 рабочих дней + + 📎 Документы: + [Скачать форму возврата] [Шаблон письма клиенту] + + 🎥 Видео-инструкция: [Посмотреть (3 мин)] + + ❓ Не нашли ответ? [Спросить коллегу] [Связаться с HR] +``` + +**Категории базы знаний:** +- 📘 Процедуры и регламенты +- 🛠️ Инструкции по инструментам +- 📊 Шаблоны документов +- 💡 Лучшие практики +- 🎯 Скрипты продаж +- ❓ FAQ по продуктам +- 🔐 Безопасность и конфиденциальность + +#### 3. Персонализированное обучение + +**AI адаптирует обучение под сотрудника:** + +```python +Профиль сотрудника: Мария Петрова +Должность: Менеджер по продажам +Опыт: 2 года +Сильные стороны: Коммуникация, презентации +Зоны роста: Работа с возражениями, CRM + +AI формирует персональный план: + +┌─────────────────────────────────────────┐ +│ План развития на месяц │ +├─────────────────────────────────────────┤ +│ Неделя 1: Углубленное изучение CRM │ +│ • Видео-уроки (2 часа) │ +│ • Практические задания (5 шт.) │ +│ • Тест (проходной балл 80%) │ +│ │ +│ Неделя 2: Работа с возражениями │ +│ • Тренинг "12 типов возражений" │ +│ • Ролевые игры с AI (10 сценариев) │ +│ • Запись реальных звонков на анализ │ +│ │ +│ Неделя 3: Продвинутые техники продаж │ +│ • SPIN-продажи (теория + практика) │ +│ • Кросс-продажи и апсейлы │ +│ • Анализ кейсов │ +│ │ +│ Неделя 4: Закрепление и оценка │ +│ • Финальный тест │ +│ • Реальные продажи с наставником │ +│ • Обратная связь и сертификация │ +└─────────────────────────────────────────┘ + +Прогресс: Неделя 1 ████████░░░░ 60% +``` + +#### 4. AI тренировки + +**Ролевые игры с AI:** + +``` +Тренировка: Холодный звонок + +AI (в роли клиента): Алло, слушаю. + +Сотрудник: Добрый день! Меня зовут Мария, компания "Пример". + Я звоню по поводу... + +AI: Извините, я очень занят. У меня совещание через 5 минут. + +Сотрудник: Понимаю, займу всего минуту. Мы помогаем компаниям + как ваша сократить расходы на логистику до 30%. + Когда вам будет удобно обсудить детали? + +AI: Логистика? А что именно вы предлагаете? + +[AI оценивает ответ сотрудника в реальном времени] + +┌─────────────────────────────────────────┐ +│ Оценка AI │ +├─────────────────────────────────────────┤ +│ ✅ Вы представились правильно │ +│ ✅ Учли возражение "занят" │ +│ ✅ Назвали конкретную выгоду (30%) │ +│ ⚠️ Можно было уточнить имя собеседника │ +│ 💡 Совет: Задайте открытый вопрос │ +│ про текущую логистику │ +└─────────────────────────────────────────┘ + +Продолжим? [Да] [Начать сначала] [Завершить] +``` + +**Типы тренировок:** +- 📞 Холодные звонки +- 💬 Работа с возражениями +- 🎁 Презентации продукта +- 💰 Переговоры о цене +- 😡 Работа с недовольными клиентами +- ✅ Закрытие сделки + +### Результаты + +**До AI:** +- Онбординг: 4-6 недель +- Стоимость обучения: $2,000/сотрудник +- Эффективность после обучения: 60% +- Текучка в первые 3 месяца: 25% + +**С AI:** +- Онбординг: 2-3 недели +- Стоимость обучения: $500/сотрудник (автоматизация) +- Эффективность после обучения: 85% +- Текучка в первые 3 месяца: 10% + +**Экономия: $1,500/сотрудник × 20 новых = $30,000/год** 💰 + +--- + +## Управление персоналом + +### HR автоматизация + +#### 1. Подбор персонала + +**AI анализирует резюме:** + +``` +Вакансия: Менеджер по продажам + +Требования: +• Опыт: от 2 лет +• Навыки: B2B продажи, CRM +• Образование: высшее +• Личные качества: коммуникабельность, стрессоустойчивость + +Получено резюме: 127 + +AI анализирует: +├── Фильтрация по ключевым словам +├── Анализ опыта работы +├── Оценка соответствия требованиям +├── Проверка рекомендаций (LinkedIn) +└── Ранжирование кандидатов + +Результат: +┌─────────────────────────────────────────┐ +│ ТОП-10 кандидатов │ +├─────────────────────────────────────────┤ +│ 1. Иванов И.И. - 95% совпадение │ +│ • Опыт: 5 лет B2B │ +│ • Знает CRM: Salesforce, Bitrix24 │ +│ • Достижения: +120% к плану │ +│ [Пригласить на собеседование] │ +│ │ +│ 2. Петрова М.А. - 92% совпадение │ +│ • Опыт: 3 года B2B │ +│ • Знает CRM: HubSpot │ +│ • Достижения: Лучший менеджер 2023 │ +│ [Пригласить на собеседование] │ +│ │ +│ [Посмотреть всех 10] │ +└─────────────────────────────────────────┘ + +Экономия времени: 8 часов → 30 минут +``` + +**Генерация вопросов для собеседования:** + +``` +AI предлагает вопросы на основе резюме кандидата: + +Кандидат: Иванов И.И. + +Рекомендованные вопросы: + +1. Опыт работы: + "Вы работали в компании X 3 года. Расскажите о самой + крупной сделке, которую вы закрыли?" + +2. Навыки: + "В резюме указан опыт с CRM Salesforce. Какие модули + вы использовали? Настраивали ли воронки продаж?" + +3. Достижения: + "Вы указали +120% к плану. За счет чего достигли + такого результата?" + +4. Мотивация: + "Почему решили сменить работу в компании X, где + показывали отличные результаты?" + +5. Ситуационный вопрос: + "Клиент говорит, что ваш продукт дороже конкурентов. + Как будете отрабатывать это возражение?" + +[Начать собеседование] [Добавить свои вопросы] +``` + +#### 2. Оценка производительности + +**AI анализирует KPI:** + +```sql +Отчет по сотруднику: Мария Петрова +Период: Декабрь 2024 + +┌─────────────────────────────────────────┐ +│ KPI Мониторинг │ +├─────────────────────────────────────────┤ +│ 📊 Продажи │ +│ • План: $50,000 │ +│ • Факт: $62,000 │ +│ • Выполнение: 124% ✅ │ +│ │ +│ 📞 Активность │ +│ • Звонков: 180 (план 150) ✅ │ +│ • Встреч: 22 (план 20) ✅ │ +│ • Писем: 95 (план 100) ⚠️ │ +│ │ +│ 🎯 Конверсия │ +│ • Лид → Встреча: 35% (среднее 30%) ✅ │ +│ • Встреча → Сделка: 45% (среднее 40%) ✅│ +│ │ +│ 😊 Удовлетворенность клиентов │ +│ • NPS: 8.5/10 (отлично) ✅ │ +│ • Повторные покупки: 65% ✅ │ +└─────────────────────────────────────────┘ + +AI Оценка: 🌟 ОТЛИЧНАЯ РАБОТА + +Рекомендации: +✅ Мария показывает стабильно высокие результаты +💡 Рассмотреть для повышения или роли наставника +📈 Небольшая просадка в email-активности - возможно, + стоит вернуть фокус на письменные коммуникации + +Предложенные действия: +[Отправить благодарность] [Обсудить развитие] [Назначить 1-on-1] +``` + +**Автоматические ревью:** + +``` +Квартальный обзор: Q4 2024 + +AI собирает данные: +├── KPI из CRM +├── Отзывы коллег (360° feedback) +├── Самооценка сотрудника +├── Отзывы клиентов +└── Обучение и развитие + +Формирует отчет (5 минут): + +ОТЧЕТ: Мария Петрова + +1. ДОСТИЖЕНИЯ + ✨ Превышение плана продаж на 24% + ✨ Высокий NPS (8.5/10) + ✨ Закрыла 3 крупные сделки ($15K+) + +2. ЗОНЫ РОСТА + 📧 Email-активность ниже нормы + 🕐 Иногда опаздывает с отчетами + +3. ОБУЧЕНИЕ + ✅ Завершила курс "Продвинутые продажи" + ✅ Сертификация по продукту А + 🔄 В процессе: "Управление командой" + +4. РЕКОМЕНДАЦИИ + 💡 Повышение до старшего менеджера + 💡 Роль наставника для новичков + 💡 Участие в стратегических проектах + +[Обсудить с сотрудником] [Утвердить план развития] +``` + +#### 3. Планирование отпусков + +**AI оптимизирует график:** + +``` +Запрос на отпуск: Иванов И.И. +Даты: 01.07.2025 - 14.07.2025 (14 дней) + +AI проверяет: +✓ Осталось дней отпуска: 28 дней +✓ Конфликты с другими отпусками: Нет +✓ Важные события в этот период: Нет +✓ Загрузка отдела: 75% (норма) + +⚠️ Рекомендация: +В отделе продаж уже 2 человека в отпуске в эти даты. +Загрузка вырастет до 90%. + +Альтернативные варианты: +1. Перенести на неделю позже (08.07-21.07) + └─ Загрузка: 70% ✅ + +2. Разделить на 2 части (по 7 дней) + └─ Меньше нагрузка на коллег + +[Утвердить запрос] [Предложить альтернативу] [Отклонить] +``` + +#### 4. Мониторинг настроения команды + +**AI анализирует коммуникацию:** + +```python +Анализ настроения команды: + +AI анализирует: +• Сообщения в корпоративном чате +• Тон email-переписки +• Результаты пульс-опросов +• Активность в общих каналах +• Частоту 1-on-1 встреч + +Результат: + +┌─────────────────────────────────────────┐ +│ Индекс счастья команды: 7.8/10 ✅ │ +├─────────────────────────────────────────┤ +│ 😊 Позитив: 65% │ +│ 😐 Нейтрально: 30% │ +│ 😟 Негатив: 5% │ +├─────────────────────────────────────────┤ +│ Тренды: │ +│ 📈 +0.3 к прошлой неделе │ +│ 📊 Стабильно высокий уровень │ +└─────────────────────────────────────────┘ + +⚠️ Внимание: +Сотрудник "Петров И." показывает снижение настроения: +• Меньше участвует в обсуждениях +• Негативный тон в 3 последних сообщениях +• Не посещал корпоратив + +Рекомендация: +Назначить 1-on-1 встречу для обсуждения + +[Запланировать встречу] [Отправить опрос] [Игнорировать] +``` + +### Результаты + +**До AI:** +- Подбор персонала: 3-4 недели +- Оценка производительности: 4 часа/сотрудник +- Планирование отпусков: вручную, конфликты +- Мониторинг настроения: отсутствует + +**С AI:** +- Подбор персонала: 1 неделя +- Оценка производительности: автоматически +- Планирование отпусков: оптимизировано AI +- Мониторинг настроения: в реальном времени + +**Экономия: 40 часов/месяц = $4,800/год** 💰 + +--- + +## Подготовка отчетности и анализ + +### Финансовый анализ + +#### 1. Автоматические финансовые отчеты + +**AI генерирует отчеты:** + +``` +Ежемесячный финансовый отчет: Декабрь 2024 + +AI собирает данные: +├── Выручка (бухгалтерия) +├── Расходы (банк + платежи) +├── Прибыль (расчет) +├── Дебиторская задолженность +├── Кредиторская задолженность +└── Cash flow + +Формирует отчет: + +┌─────────────────────────────────────────────────────────┐ +│ EXECUTIVE SUMMARY │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ 💰 Выручка: $450,000 │ +│ • Рост: +12% к прошлому месяцу │ +│ • Отклонение от плана: +8% ✅ │ +│ │ +│ 💸 Расходы: $320,000 │ +│ • Операционные: $180,000 │ +│ • Маркетинг: $80,000 │ +│ • Зарплата: $60,000 │ +│ │ +│ 📈 Прибыль: $130,000 (29% маржа) │ +│ • Рост: +18% к прошлому месяцу │ +│ │ +│ 💵 Cash Flow: +$95,000 │ +│ • Остаток на счетах: $450,000 │ +│ │ +└─────────────────────────────────────────────────────────┘ + +AI АНАЛИЗ: +✅ Сильные стороны: + • Выручка растет стабильно + • Маржинальность выше среднего по отрасли (25%) + • Положительный cash flow + +⚠️ Риски: + • Дебиторка выросла на 15% - контролировать + • Расходы на маркетинг +25% - оценить ROI + +💡 Рекомендации: + • Увеличить резервный фонд до $200K + • Оптимизировать маркетинговые расходы + • Ускорить взыскание дебиторской задолженности + +[Скачать полный отчет PDF] [Отправить инвесторам] +``` + +#### 2. Прогнозирование + +**AI предсказывает будущее:** + +```python +Прогноз продаж: Q1 2025 + +AI использует: +• Историю продаж (3 года) +• Сезонность +• Тренды рынка +• Маркетинговые активности +• Макроэкономические факторы + +Результат: + +┌─────────────────────────────────────────┐ +│ ПРОГНОЗ ПРОДАЖ Q1 2025 │ +├─────────────────────────────────────────┤ +│ Январь: $420,000 ± 8% │ +│ Февраль: $480,000 ± 8% │ +│ Март: $540,000 ± 10% │ +│ ──────────────────────────────────── │ +│ ИТОГО: $1,440,000 ± 9% │ +├─────────────────────────────────────────┤ +│ Факторы роста: │ +│ • Запуск нового продукта (+15%) │ +│ • Выход на новый рынок (+10%) │ +│ • Сезонный спрос (февраль-март) │ +│ │ +│ Факторы риска: │ +│ • Экономическая нестабильность (-5%) │ +│ • Усиление конкуренции (-3%) │ +└─────────────────────────────────────────┘ + +Вероятность достижения прогноза: 87% + +Сценарии: +📈 Оптимистичный: $1,580,000 (+10%) +📊 Базовый: $1,440,000 (прогноз) +📉 Пессимистичный: $1,300,000 (-10%) + +[Построить план] [Экспортировать] [Настроить модель] +``` + +#### 3. Анализ рентабельности продуктов + +**AI показывает, что прибыльно:** + +``` +Анализ продуктовой линейки: Декабрь 2024 + +Продукт A: +├── Продаж: 150 шт × $500 = $75,000 +├── Себестоимость: $30,000 +├── Маржа: $45,000 (60%) +├── Маркетинг: $5,000 +├── Чистая прибыль: $40,000 +└── ROI: 133% ⭐⭐⭐⭐⭐ + +Продукт B: +├── Продаж: 80 шт × $1,200 = $96,000 +├── Себестоимость: $60,000 +├── Маржа: $36,000 (37.5%) +├── Маркетинг: $12,000 +├── Чистая прибыль: $24,000 +└── ROI: 40% ⭐⭐⭐ + +Продукт C: +├── Продаж: 200 шт × $150 = $30,000 +├── Себестоимость: $24,000 +├── Маржа: $6,000 (20%) +├── Маркетинг: $8,000 +├── Чистая прибыль: -$2,000 +└── ROI: -8% ❌ + +AI РЕКОМЕНДАЦИИ: + +✅ Продукт A - ЗВЕЗДА + Действие: Увеличить маркетинг на 50% + Прогноз: Прибыль +$20K/месяц + +⚠️ Продукт B - ДОЙНАЯ КОРОВА + Действие: Оптимизировать производство (-10% себестоимость) + Прогноз: Маржа до 45% + +❌ Продукт C - УБЫТОЧНЫЙ + Действие: + 1. Поднять цену до $180 ИЛИ + 2. Снизить маркетинг до $3K ИЛИ + 3. Прекратить продажи + +[Применить рекомендации] [Подробный анализ] +``` + +#### 4. Бенчмаркинг + +**AI сравнивает с рынком:** + +``` +Сравнение с конкурентами: 2024 + +Ваша компания vs Средние по отрасли: + +┌─────────────────────────────────────────┐ +│ Показатель │ Вы │ Рынок │ Δ │ +├─────────────────────────────────────────┤ +│ Выручка │ $5.2M │ $4.8M │ +8% │ +│ Маржа │ 29% │ 25% │ +4% │ +│ Рост YoY │ +45% │ +18% │ +27% │ +│ LTV │ $12,500 │ $9,800│ +28% │ +│ CAC │ $950 │ $1,100│ -14% │ +│ Churn Rate │ 8% │ 12% │ -4% │ +│ NPS │ 72 │ 58 │ +14 │ +└─────────────────────────────────────────┘ + +AI ИНСАЙТЫ: + +🏆 ВЫ ЛИДЕР в: + • Удержание клиентов (churn 8% vs 12%) + • Лояльность (NPS 72 vs 58) + • Эффективность привлечения (CAC -14%) + +📈 РАСТЕТЕ БЫСТРЕЕ РЫНКА: + • Выручка +45% vs средние +18% + • Захват рыночной доли + +💡 ВОЗМОЖНОСТИ: + • Ваша эффективность выше - можно поднять цены на 5-10% + • Низкий CAC - инвестировать больше в маркетинг + +[Экспортировать отчет] [Поделиться с командой] +``` + +### Результаты + +**До AI:** +- Финансовый отчет: 8 часов +- Прогнозирование: 16 часов (раз в квартал) +- Анализ продуктов: 4 часа +- Бенчмаркинг: вручную, нерегулярно + +**С AI:** +- Финансовый отчет: 5 минут +- Прогнозирование: 10 минут (еженедельно) +- Анализ продуктов: 2 минуты +- Бенчмаркинг: автоматически + +**Экономия: 100 часов/месяц = $12,000/год** 💰 + +--- + +## Подготовка контента для маркетинга + +### Контент-маркетинг + +#### 1. Генерация постов для соцсетей + +**AI создает контент:** + +``` +Запрос: Создать пост о новом продукте для Instagram + +AI анализирует: +├── Характеристики продукта +├── Целевую аудиторию +├── Тренды в Instagram +├── Успешные посты конкурентов +└── Бренд-войс компании + +Генерирует 3 варианта: + +ВАРИАНТ 1 (эмоциональный): +───────────────────────────────────── +🎉 Встречайте новинку! + +Мы месяцами работали над этим, и наконец готовы +показать вам [Продукт]! + +✨ Это не просто [категория] - это революция в + [индустрия] + +💡 Что особенного: + • [Преимущество 1] + • [Преимущество 2] + • [Преимущество 3] + +Первые 100 покупателей получат скидку 25%! +Ссылка в био 👆 + +#новинка #продукт #индустрия #скидка +───────────────────────────────────── +Эмодзи: 4 | Хештеги: 4 | Длина: 380 символов +Прогноз вовлечения: 3.2% (выше среднего) + +ВАРИАНТ 2 (образовательный): +[...] + +ВАРИАНТ 3 (продающий): +[...] + +[Выбрать вариант 1] [Редактировать] [Создать еще] +``` + +**Автоматический постинг:** + +```python +Контент-план на неделю: + +AI формирует расписание: + +Понедельник 09:00: +📱 Instagram: "Совет дня по использованию продукта" + Формат: Карусель (5 слайдов) + +Понедельник 18:00: +🐦 Twitter: "Интересная статистика по отрасли" + Формат: Текст + изображение + +Вторник 12:00: +💼 LinkedIn: "Кейс клиента: как они достигли X" + Формат: Статья (1200 слов) + +Среда 10:00: +📘 Facebook: "Конкурс с призами" + Формат: Видео + текст + +[...] + +Всего контента на неделю: 21 пост +Время на создание: 3 часа (вместо 20 часов) + +[Утвердить план] [Редактировать] [Опубликовать] +``` + +#### 2. Email-рассылки + +**AI пишет письма:** + +``` +Тип рассылки: Продуктовая новость +Сегмент: Активные клиенты (1,247 человек) + +AI генерирует: + +От: команда@company.com +Тема: Новый [Продукт] - специально для вас! 🎁 + +Превью: Эксклюзивная скидка 20% для наших... + +Тело письма: +───────────────────────────────────── +Привет, [Имя]! + +Помните, вы интересовались [категорией]? + +У нас отличная новость! Мы только что запустили +[Продукт] - именно то, что вам нужно. + +🎯 Специально для вас: + • Скидка 20% (промокод: VIP20) + • Бесплатная доставка + • Продленная гарантия 24 месяца + +[Кнопка: Узнать подробнее] + +Почему [Продукт] идеально вам подходит: +✓ [Преимущество 1 релевантное клиенту] +✓ [Преимущество 2 релевантное клиенту] +✓ [Преимущество 3 релевантное клиенту] + +Предложение действует до [дата + 7 дней] + +С уважением, +Команда [Компания] + +P.S. Вопросы? Ответим в течение часа! +───────────────────────────────────── + +A/B тестирование: +Вариант A: Эта тема письма +Вариант B: "[Продукт] уже здесь - скидка 20% 🎉" + +Прогноз: +Open Rate: 28% (среднее 22%) +Click Rate: 6.5% (среднее 4.8%) + +[Отправить сейчас] [Запланировать] [A/B тест] +``` + +#### 3. Блог-статьи + +**AI пишет статьи для блога:** + +``` +Запрос: Написать статью "10 способов увеличить продажи" + +AI: +1. Анализирует ТОП-10 статей по этой теме +2. Проверяет актуальные ключевые слова (SEO) +3. Изучает вашу экспертизу и кейсы +4. Формирует уникальный контент + +Результат (2,500 слов): + +┌─────────────────────────────────────────┐ +│ 10 проверенных способов увеличить │ +│ продажи в 2025 году │ +├─────────────────────────────────────────┤ +│ 📊 Время чтения: 12 минут │ +│ 🎯 Сложность: Средняя │ +│ ✍️ Автор: AI + ваша экспертиза │ +└─────────────────────────────────────────┘ + +ВВЕДЕНИЕ [250 слов] +Продажи - это сердце любого бизнеса... + +1. ПЕРСОНАЛИЗАЦИЯ ПРЕДЛОЖЕНИЙ [300 слов] + Современные покупатели ожидают... + + 💡 Кейс: Компания X увеличила продажи на 45%... + + ✅ Как применить в вашем бизнесе: + • Шаг 1: ... + • Шаг 2: ... + +2. АВТОМАТИЗАЦИЯ ВОРОНКИ ПРОДАЖ [280 слов] + [...] + +[Продолжение статьи...] + +ЗАКЛЮЧЕНИЕ [200 слов] +В этой статье мы рассмотрели... + +─────────────────────────────────────── + +SEO оптимизация: +✅ Ключевые слова: 15 вхождений +✅ Заголовки H1-H3: структурированы +✅ Мета-описание: готово +✅ Внутренние ссылки: 5 шт. +✅ Изображения: 8 шт. (с alt-текстами) + +Readability Score: 72/100 (хорошо) +SEO Score: 88/100 (отлично) + +[Опубликовать] [Редактировать] [Запланировать] +``` + +#### 4. Видео-скрипты + +**AI пишет сценарии для видео:** + +``` +Формат: YouTube видео (5-7 минут) +Тема: "Обзор нового продукта" + +AI генерирует скрипт: + +┌─────────────────────────────────────────┐ +│ ВИДЕО-СКРИПТ │ +│ "Обзор [Продукт] - стоит ли покупать?" │ +├─────────────────────────────────────────┤ +│ Длительность: ~6 минут │ +│ Монтаж: 15-20 склеек │ +└─────────────────────────────────────────┘ + +[00:00-00:15] INTRO +───────────────────────────────────── +🎬 [Динамичная музыка] + +ТЕКСТ НА ЭКРАНЕ: "Обзор [Продукт]" + +Ведущий (энергично): +"Привет! Сегодня обзор на [Продукт] - новинку, +которую все ждали. Стоит ли покупать? Сейчас +разберемся!" + +🎬 [Крупный план продукта] +───────────────────────────────────── + +[00:15-01:00] ЧТО ЭТО? +───────────────────────────────────── +Ведущий: +"[Продукт] - это [категория], которая решает +проблему [проблема]. + +🎬 [B-roll: показываем проблему] + +Основные фичи: +• [Фича 1] - покажу это через секунду +• [Фича 2] +• [Фича 3]" + +🎬 [Демонстрация каждой фичи] +───────────────────────────────────── + +[01:00-03:00] ТЕСТИРОВАНИЕ +[...] + +[05:30-06:00] ЗАКЛЮЧЕНИЕ +───────────────────────────────────── +Ведущий: +"Итак, стоит ли покупать [Продукт]? + +✅ ДА, если вам нужно [use case 1] +✅ ДА, если [use case 2] +❌ НЕТ, если [ограничение] + +Цена $XXX - адекватная за такой функционал. + +Ссылка на покупку в описании. Промокод YOUTUBE20 +на скидку 20%. + +Лайк, если видео было полезно! Подписывайтесь!" + +🎬 [Outro с подпиской] +───────────────────────────────────── + +Ключевые моменты для монтажа: +• [00:30] - Крупный план упаковки +• [01:15] - Демо фичи 1 (slow motion) +• [02:40] - Сравнение с конкурентом (split screen) + +YouTube SEO: +Заголовок: "[Продукт] обзор 2025 - ЧЕСТНО!" +Описание: Готово (150 слов + ссылки) +Теги: 15 релевантных тегов + +[Скачать PDF] [Создать субтитры] [Идеи для B-roll] +``` + +#### 5. Рекламные объявления + +**AI создает рекламу:** + +``` +Платформа: Facebook Ads +Цель: Продажи + +AI генерирует набор объявлений: + +ОБЪЯВЛЕНИЕ 1 (Эмоциональное) +───────────────────────────────────── +Изображение: [Счастливый клиент с продуктом] + +Заголовок: "Измените свою жизнь с [Продукт]!" + +Текст: +"Представьте: вы просыпаетесь и [выгода]. + +Больше никаких [проблема]. Только [результат]. + +[Продукт] уже помог 10,000+ людям. +Следующий - вы? + +✨ Специальное предложение: -30% до конца недели" + +CTA: [Попробовать сейчас] + +Аудитория: Lookalike 1% от покупателей +Бюджет: $50/день +Прогноз CTR: 2.8% +───────────────────────────────────── + +ОБЪЯВЛЕНИЕ 2 (Рациональное) +[...] + +ОБЪЯВЛЕНИЕ 3 (Социальное доказательство) +[...] + +A/B тест матрица: +├── 3 креатива × 3 заголовка × 2 аудитории +└── = 18 вариантов для тестирования + +[Запустить кампанию] [Настроить бюджет] +``` + +### Результаты + +**До AI:** +- Пост для соцсетей: 30 минут +- Email-рассылка: 2 часа +- Блог-статья: 8 часов +- Видео-скрипт: 4 часа +- Итого: ~70 часов/месяц на контент + +**С AI:** +- Пост для соцсетей: 3 минуты +- Email-рассылка: 15 минут +- Блог-статья: 30 минут (+ редактура) +- Видео-скрипт: 20 минут +- Итого: ~10 часов/месяц на контент + +**Экономия: 60 часов/месяц = $7,200/год** 💰 + +--- + +## Экономический эффект + +### Суммарная экономия по всем направлениям + +| Направление | Экономия в год | ROI | +|-------------|----------------|-----| +| **Обслуживание клиентов** | $57,600 | 5,760% | +| **Работа с поставщиками + AI закупщик** | $64,800 | 6,480% | +| **Работа с партнерами** | $43,200 | 4,320% | +| **Обучение персонала** | $30,000 | 3,000% | +| **Управление персоналом** | $57,600 | 5,760% | +| **Отчетность и анализ** | $144,000 | 14,400% | +| **Контент-маркетинг** | $86,400 | 8,640% | +| **ИТОГО:** | **$483,600** | **48,360%** | + +**Стоимость внедрения DLE**: $1,000 (единоразово, Standard Support) +**ROI**: 48,360% или **484x окупаемость** + +### Дополнительные выгоды + +**Неизмеримые преимущества:** +- 📈 Повышение качества работы +- 😊 Удовлетворенность клиентов +19% +- 👥 Удержание сотрудников +15% +- 🚀 Скорость принятия решений +300% +- 💡 Больше времени на стратегию +- 🎯 Меньше рутины, больше креатива + +### Сравнение с наймом сотрудников + +**Альтернатива: Нанять людей для тех же задач** + +| Должность | Зарплата/год | Задачи | +|-----------|--------------|--------| +| Оператор поддержки ×3 | $90,000 | Обслуживание клиентов | +| Менеджер по закупкам | $36,000 | Работа с поставщиками | +| Закупщик/снабженец | $36,000 | Анализ рынка, поиск поставщиков | +| Партнерский менеджер | $42,000 | Работа с партнерами | +| HR-специалист | $36,000 | Управление персоналом | +| Тренинг-менеджер | $40,000 | Обучение | +| Финансовый аналитик | $60,000 | Отчетность | +| Контент-менеджер | $45,000 | Маркетинг | +| **ИТОГО:** | **$385,000/год** | - | + +**DLE AI Ассистент**: $0/год (включен в лицензию) + +**Экономия**: $385,000/год 💰 + +--- + +## Кейсы применения + +### Кейс 1: E-commerce магазин + +**Компания**: Интернет-магазин электроники +**Сотрудников**: 15 +**Проблема**: Не успевали отвечать на вопросы клиентов + +**До внедрения AI:** +- Время ответа: 12 часов +- Потерянных клиентов: 30% +- Операторов: 4 +- Конверсия чата: 8% + +**После внедрения AI:** +- Время ответа: 30 секунд +- Потерянных клиентов: 5% +- Операторов: 1 (сложные случаи) +- Конверсия чата: 18% + +**Результат:** +- Продажи +45% +- Экономия $72,000/год +- Удовлетворенность +28% + +### Кейс 2: B2B компания + +**Компания**: Поставщик оборудования +**Сотрудников**: 25 +**Проблема**: Менеджеры тонули в рутине + +**До внедрения AI:** +- Время на запрос цен: 2 часа +- Ответов поставщиков: 60% +- Времени на продажи: 30% +- Сделок/месяц: 15 + +**После внедрения AI:** +- Время на запрос цен: 5 минут +- Ответов поставщиков: 95% +- Времени на продажи: 75% +- Сделок/месяц: 38 + +**Результат:** +- Выручка +153% +- Экономия $96,000/год +- Довольных менеджеров: 100% + +### Кейс 3: Стартап + +**Компания**: SaaS стартап (5 человек) +**Сотрудников**: 5 +**Проблема**: Малобюджетный маркетинг + +**До внедрения AI:** +- Контент: 2 поста/неделя +- Бюджет на фрилансеров: $2,000/месяц +- Качество: среднее +- Охват: 5,000 + +**После внедрения AI:** +- Контент: 15 постов/неделя +- Бюджет: $0 +- Качество: высокое +- Охват: 45,000 + +**Результат:** +- Подписчиков +600% +- Лидов +240% +- Экономия $24,000/год + +--- + +## Настройка и интеграция + +### Технические требования + +**Минимальные:** +- RAM: 8 GB (для Ollama) +- CPU: 4 ядра +- Диск: 50 GB (для AI моделей) +- Сеть: стабильное подключение + +**Рекомендуемые:** +- RAM: 16 GB+ +- CPU: 8+ ядер +- Диск: 100 GB SSD +- GPU: NVIDIA (для ускорения) + +### Быстрый старт + +#### Шаг 1: Установка моделей + +```bash +# DLE автоматически скачивает модели при первом запуске + +docker-compose up -d ollama + +# Проверка статуса +docker logs dapp-ollama + +# Ожидайте: "Все модели загружены! Система готова" +``` + +#### Шаг 2: Создание базы знаний + +```javascript +// Веб-интерфейс: Настройки → AI Ассистент → База знаний + +1. Нажмите "Добавить вопрос" +2. Заполните: + - Вопрос: "Как вернуть товар?" + - Ответ: "Возврат возможен в течение 14 дней..." + - Теги: #возврат, #гарантия + - Продукт: [Выберите продукт или оставьте "Все"] + - Приоритет: Высокий +3. Сохраните + +Повторите для всех частых вопросов (рекомендуется 50-100) +``` + +#### Шаг 3: Интеграция с чатами + +```javascript +// Telegram бот +Настройки → Интеграции → Telegram +1. Получите токен от @BotFather +2. Вставьте токен +3. Включите "Использовать AI для ответов" +4. Настройте приветствие +5. Сохраните + +// Чат на сайте +Настройки → Виджеты → Чат +1. Скопируйте код виджета +2. Вставьте на сайт перед +3. AI автоматически отвечает на вопросы +``` + +#### Шаг 4: Настройка под ваш бизнес + +``` +Настройки → AI Ассистент → Персонализация + +1. Тон общения: + [x] Формальный [ ] Дружеский + +2. Язык: + [x] Русский [x] English + +3. Приоритеты: + [x] Скорость ответа + [x] Точность + [ ] Креативность + +4. Автоматические действия: + [x] Создавать тикеты для сложных вопросов + [x] Уведомлять операторов + [x] Собирать обратную связь + +5. Обучение: + [x] Учиться на новых диалогах + [x] Запрашивать подтверждение для неуверенных ответов +``` + +### Обучение AI на ваших данных + +```python +# Импорт существующих данных + +1. Экспорт из вашей CRM/базы: + - Часто задаваемые вопросы + - История чатов + - Email-переписка + - Документация + +2. Формат CSV: + question,answer,tags,product,priority + "Как вернуть товар?","Возврат в течение 14 дней...",возврат;гарантия,all,high + +3. Импорт в DLE: + AI Ассистент → Импорт → Выберите CSV + +4. Проверка: + AI анализирует и предлагает улучшения + +5. Активация: + AI начинает использовать новые знания немедленно +``` + +### Мониторинг и улучшение + +``` +Аналитика AI: + +┌─────────────────────────────────────────┐ +│ Производительность за месяц │ +├─────────────────────────────────────────┤ +│ Запросов обработано: 15,420 │ +│ Ответов из кэша: 8,750 (57%) │ +│ Новых ответов: 6,670 (43%) │ +│ │ +│ Средняя скорость: │ +│ • Кэш: 48ms ⚡ │ +│ • Новый: 3.2s 🤔 │ +│ │ +│ Точность: 94% ✅ │ +│ • Правильные ответы: 14,495 │ +│ • Требовалось уточнение: 925 │ +│ │ +│ Удовлетворенность: 4.7/5 ⭐⭐⭐⭐⭐ │ +├─────────────────────────────────────────┤ +│ Топ-5 вопросов без ответа: │ +│ 1. "Когда будет новая версия?" (15×) │ +│ 2. "Работает ли с MacOS M1?" (12×) │ +│ 3. "Есть ли API?" (9×) │ +│ 4. "Как интегрировать с X?" (7×) │ +│ 5. "Скидки для студентов?" (6×) │ +│ │ +│ 💡 Рекомендация: Добавить эти вопросы │ +│ в базу знаний │ +└─────────────────────────────────────────┘ + +[Добавить в базу] [Экспортировать отчет] +``` + +--- + +## Заключение + +### Ключевые преимущества AI Ассистента DLE + +1. **💰 Огромная экономия**: До $483,600/год +2. **🏠 100% конфиденциальность**: Все данные на вашем сервере +3. **⚡ Молниеносная скорость**: Ответы за 50ms (кэш) +4. **🎯 Персонализация**: Обучается на ваших данных +5. **🔄 24/7 доступность**: Никогда не спит, не устает +6. **📈 Масштабируемость**: От 10 до 10,000 запросов/день +7. **🌍 Многоязычность**: Русский, английский и др. + +### Кому подходит + +✅ **E-commerce** - обслуживание клиентов, контент +✅ **B2B компании** - работа с поставщиками, партнерами +✅ **Стартапы** - все функции при минимальном бюджете +✅ **Enterprise** - масштабная автоматизация +✅ **Агентства** - быстрое создание контента +✅ **SaaS** - поддержка пользователей, документация + +### Следующие шаги + +1. 📖 [Установите DLE](./setup-instruction.md) +2. 🤖 Настройте AI ассистента (5 минут) +3. 📚 Загрузите базу знаний +4. 🚀 Начните экономить время и деньги! + +--- + +## Поддержка + +**Нужна помощь с настройкой AI?** + +📧 **Email**: info@hb3-accelerator.com +💬 **Чат**: https://hb3-accelerator.com +📚 **Документация**: [FAQ](./FAQ.md) +🎓 **Обучение**: Онлайн-сессии для токен-холдеров + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + diff --git a/docs/application-description.md b/docs/application-description.md new file mode 100644 index 0000000..56e9ab5 --- /dev/null +++ b/docs/application-description.md @@ -0,0 +1,619 @@ +# Digital Legal Entity (DLE) - Веб-приложение для управления бизнесом + +> **Полный контроль. Нулевая абонентская плата. AI экономит $483,600/год.** + +--- + +## 📋 Содержание + +1. [Для кого это приложение](#для-кого-это-приложение) +2. [Ключевые преимущества](#ключевые-преимущества) +3. [Основные возможности](#основные-возможности) +4. [Экономический эффект](#экономический-эффект) +5. [Технические детали](#технические-детали) +6. [Функциональные модули](#функциональные-модули) +7. [Безопасность и защита](#безопасность-и-защита) +8. [Инфраструктурные требования](#инфраструктурные-требования) +9. [Условия приобретения](#условия-приобретения) + +--- + +## 🎯 Для кого это приложение + +### Идеально подходит для: + +**Малого и среднего бизнеса** +- Полный контроль над данными клиентов и бизнес-процессами +- Соответствие локальным законам о хранении данных +- Независимость от SaaS-провайдеров +- Экономия на ежемесячных подписках + +**Стартапов с амбициями** +- Готовая инфраструктура для быстрого старта +- Блокчейн-управление с первого дня +- AI ассистент для автоматизации рутины +- Токенизация активов и привлечение инвестиций + +**Распределенных команд** +- Омниканальные коммуникации (Telegram, Email, Web, SMS) +- Система групп и пространств для совместной работы +- CRM с автоматизацией через AI +- 24/7 доступ из любой точки мира + +**Бизнеса с цифровыми активами** +- Токенизация любых активов (недвижимость, IP, акции, товары) +- Управление через блокчейн-голосование +- Прозрачность для инвесторов +- Защита активов на уровне смарт-контрактов + +--- + +## 💎 Ключевые преимущества + +### Почему DLE, а не SaaS? + +| Параметр | DLE | Обычные SaaS | +|----------|-----|--------------| +| **💰 Стоимость** | $1,000 один раз | $200-500/месяц | +| **📊 Владение данными** | 100% ваши | У провайдера | +| **🔧 Кастомизация** | Полная | Ограниченная | +| **🌍 Соответствие законам** | Под ваш регион | Зависит от провайдера | +| **🤖 AI без лимитов** | Бесплатно | $200+/месяц | +| **🔗 Блокчейн** | Встроен | Нет или доп. плата | +| **⚡ Обновления** | Бесплатно навсегда | Зависит от тарифа | + +### 🎁 Что вы получаете + +✅ **Бессрочная лицензия** - платите один раз, используйте вечно +✅ **Бесплатные обновления** - все улучшения без доп. платы +✅ **Полный исходный код** - полная прозрачность +✅ **AI на своем сервере** - 100% конфиденциальность +✅ **Блокчейн-защита** - активы невозможно украсть +✅ **Токенизация активов** - экономия 99% на сделках +✅ **Право голоса** - влияние на развитие продукта + +--- + +## 🚀 Основные возможности + +### 1. CRM с AI ассистентом + +**Умная система управления клиентами**: +- Централизованная база контактов +- История взаимодействий по всем каналам +- AI автоматизация (ответы 24/7, анализ запросов) +- Конструктор документов и шаблонов +- Импорт из внешних источников + +**AI как второй пилот**: +- Отвечает на 70-80% типовых вопросов +- Анализирует настроение клиентов +- Предлагает решения на основе истории +- Экономит до $57,600/год на поддержке + +### 2. Омниканальные коммуникации + +**Единый интерфейс для всех каналов**: +- 💬 Telegram бот +- 📧 Email интеграция +- 🌐 Web чат на сайте +- 📱 SMS рассылки +- 📋 Веб-формы обратной связи + +**Преимущества**: +- Один контекст для клиента на всех каналах +- Автоматическая маршрутизация сообщений +- AI автоответы с обучением на ваших данных +- Аналитика по каналам и времени ответа + +### 3. Блокчейн-управление и токенизация + +**Смарт-контракты для бизнеса**: +- Токенизация любых активов (недвижимость, IP, акции) +- Управление через голосование токен-холдеров +- Мультичейн поддержка (7+ сетей: Ethereum, Polygon, BSC, Arbitrum, Optimism, Avalanche, Base) +- Прозрачность всех операций на блокчейне + +**Безопасность на уровне кода**: +- Токены нельзя украсть (требуется голосование) +- Управление активами даже при взломе веб-приложения +- Timelock для критических операций (48ч на проверку) +- Защита от flash-loan атак + +### 4. AI ассистент с векторным поиском + +**Локальный AI на вашем сервере**: +- Ollama + Vector Search (RAG) +- Модель qwen2.5:7b (или любая другая) +- 100% конфиденциальность (данные не уходят наружу) +- Нулевые затраты на API токены + +**7 ключевых областей применения**: +1. **Обслуживание клиентов** - ответы 24/7, экономия $57,600/год +2. **AI-закупщик** - анализ 100+ поставщиков, экономия $64,800/год +3. **Работа с партнерами** - автоматизация коммуникаций, $43,200/год +4. **Обучение персонала** - AI наставник, $30,000/год +5. **HR управление** - подбор кандидатов, $57,600/год +6. **Финансовый анализ** - отчеты за 5 минут, $144,000/год +7. **Контент-маркетинг** - генерация постов, $86,400/год + +**Итого: $483,600/год экономии при ROI 48,360%** + +### 5. Группы и пространства для команд + +- Настраиваемые пространства для проектов +- Детальная система разрешений (20+ типов) +- Роли: Editor, ReadOnly, User +- Интеграция с CRM и коммуникациями + +### 6. Внутренние инструменты + +- Электронные таблицы (аналог Excel) +- Система аналитики и отчетов +- Мониторинг метрик +- WebSSH для управления серверами + +--- + +## 💰 Экономический эффект + +### Сравнение с SaaS за 5 лет + +**Типичный стек SaaS**: +``` +CRM (HubSpot): $200/мес × 60 мес = $12,000 +Чат-бот (Intercom): $150/мес × 60 мес = $9,000 +Email (SendGrid): $100/мес × 60 мес = $6,000 +AI (ChatGPT API): $200/мес × 60 мес = $12,000 + ───────────────────────────── + ИТОГО: $39,000 +``` + +**DLE**: +``` +Лицензия (один раз): $1,000 +Обновления (5 лет): $0 +AI без лимитов: $0 + ───────────────────────────── + ИТОГО: $1,000 + +ЭКОНОМИЯ: $38,000 +``` + +### ROI от AI ассистента + +**Ежегодная экономия по направлениям**: +- Обслуживание клиентов: $57,600 +- AI-закупщик + поставщики: $64,800 +- Работа с партнерами: $43,200 +- Обучение персонала: $30,000 +- HR управление: $57,600 +- Отчетность/анализ: $144,000 +- Контент-маркетинг: $86,400 + +**Итого экономия**: $483,600/год +**Инвестиция**: $1,000 +**ROI**: 48,360% или 484x окупаемость ✅ + +### Экономия на токенизации активов + +**Традиционная сделка с недвижимостью ($1M)**: +- Комиссия риелтора: 3-5% = $30,000-50,000 +- Юридические услуги: $5,000-10,000 +- Регистрация права: $2,000-5,000 +- Время: 2-6 месяцев + +**Итого**: $37,000-65,000 + +**Токенизированная сделка через DLE**: +- Gas fees: $50-200 +- Смарт-контракт (один раз): $500 +- Время: 5-10 минут + +**Итого**: $550-700 + +**Экономия**: 99% затрат и 99% времени ✅ + +--- + +## 🔧 Технические детали + +### Архитектура + +**Современный технологический стек**: +- **Frontend**: Vue.js 3 + Vite + Element Plus +- **Backend**: Node.js + Express +- **База данных**: PostgreSQL +- **AI**: Ollama (qwen2.5:7b) + FAISS Vector Search +- **Блокчейн**: Ethers.js v6 + Hardhat +- **Контейнеризация**: Docker Compose + +### Принципы проектирования + +✅ **Микросервисная архитектура** - легко масштабировать +✅ **Полный контроль** - вы владеете приложением и данными +✅ **Модульность** - добавляйте новые функции через модули +✅ **Безопасность** - многоуровневая защита (TLS, AES-256, CSRF) +✅ **API-first** - REST + WebSocket для интеграций + +### Развертывание + +**Гибкие варианты установки**: +- **На своем сервере** - полный контроль +- **В облаке** - AWS, Google Cloud, Azure +- **На локальной инфраструктуре** - соответствие регуляторным требованиям +- **Docker Compose** - развертывание одной командой + +**Автоматизация**: +- Миграции базы данных +- Backup и восстановление +- Мониторинг (Prometheus/Grafana) +- Автомасштабирование (Kubernetes) + +--- + +## 📦 Функциональные модули + +### CRM и управление контактами + +**Полноценная система управления клиентами**: +- Централизованная база контактов +- Группировка по тегам и категориям +- История взаимодействий +- Система задач и напоминаний +- Импорт из CSV, Excel, внешних CRM +- Экспорт в различных форматах + +**Система управления контентом (CMS)**: +- Конструктор документов +- Шаблоны и переменные +- Версионирование +- Права доступа + +### Омниканальная система коммуникаций + +**Единый интерфейс управления сообщениями**: +- Централизованная обработка всех каналов +- Унифицированный контекст для каждого контакта +- Синхронизация статусов между каналами +- История переписки в одном месте + +**Каналы коммуникации**: +- **Telegram бот** - интеграция через Bot API +- **Email** - SMTP/IMAP, работа с Gmail, Outlook +- **Web чат** - виджет для сайта +- **SMS** - интеграция через провайдеров +- **Веб-формы** - конструктор форм обратной связи + +**Обработка сообщений**: +- Автоматическая классификация +- Маршрутизация по операторам +- AI автоответы с обучением +- Real-time уведомления +- Аналитика времени ответа + +### Блокчейн интеграция + +**Мультичейн поддержка**: +- Ethereum +- Polygon +- Binance Smart Chain (BSC) +- Arbitrum +- Optimism +- Avalanche +- Base + +**Смарт-контракты**: +- **DLE.sol** - основной контракт управления +- **TreasuryModule.sol** - управление казной +- **HierarchicalVotingModule.sol** - иерархическое голосование +- **TimelockModule.sol** - отложенное исполнение + +**Функциональность**: +- Деплой контрактов на множество сетей +- Управление через голосование +- Токенизация активов +- Прозрачность операций +- Аналитика блокчейн-данных + +### AI и машинное обучение + +**Технология**: +- **Ollama** - локальный LLM сервер +- **FAISS** - векторный поиск для RAG +- **mxbai-embed-large** - модель эмбеддингов +- **qwen2.5:7b** - основная языковая модель + +**Возможности**: +- Ответы на вопросы по базе знаний +- Генерация контента +- Анализ настроения +- Классификация сообщений +- Обучение на ваших данных + +**Оптимизация**: +- Многоуровневое кэширование +- Индексация векторов +- Batch processing +- Асинхронная обработка + +### Группы и пространства + +**Организация работы команды**: +- Создание пространств для проектов +- Приглашение участников +- Распределение ролей и разрешений +- Изолированные данные между группами + +**Система разрешений (20+ типов)**: +- Чтение/запись контактов +- Управление группами +- Доступ к AI ассистенту +- Управление блокчейн-контрактами +- Просмотр аналитики +- и другие... + +### Внутренние инструменты + +**Электронные таблицы**: +- Создание и редактирование таблиц +- Импорт/экспорт CSV, Excel +- Формулы и вычисления +- Совместное редактирование + +**Управление инфраструктурой**: +- Создание VDS серверов +- WebSSH терминал +- Мониторинг ресурсов + +**Аналитика и отчеты**: +- Статистика по коммуникациям +- Активность пользователей +- Эффективность AI ассистента +- Блокчейн-метрики + +### API и интеграции + +**REST API**: +- Полный доступ к функциональности +- Аутентификация через сессии (express-session) +- Rate limiting +- Документация OpenAPI/Swagger + +**WebSocket**: +- Real-time обновления +- Уведомления о событиях +- Чат в реальном времени + +**Внешние сервисы**: +- Etherscan, Polygonscan и другие блокчейн-сканеры +- Геокодирование (Google Maps, OpenStreetMap) +- Email провайдеры (Gmail, Outlook) +- SMS провайдеры +- Платежные системы + +--- + +## 🛡️ Безопасность и защита + +### Многоуровневая защита + +**Уровень 1: Сетевая безопасность** +- TLS 1.3 для всех соединений +- HTTPS обязателен в продакшене +- Firewall настройки +- DDoS защита через rate limiting + +**Уровень 2: Аутентификация** +- SIWE (Sign-In with Ethereum) - вход через кошелек +- express-session с PostgreSQL (сессии в БД) +- Nonce с шифрованием для безопасности +- Поддержка Email и Telegram аутентификации + +**Уровень 3: Авторизация** +- Детальная система разрешений (20+ типов) +- Роли: Editor, ReadOnly, User +- Контроль доступа на уровне групп +- Токен-гейтинг (доступ только держателям токенов) + +**Уровень 4: Защита данных** +- AES-256 шифрование критичных данных +- Хэширование паролей (bcrypt) +- Защита от SQL-инъекций (параметризованные запросы) +- XSS защита +- CSRF токены +- Helmet.js для HTTP headers + +**Уровень 5: Блокчейн-защита** +- Токены нельзя украсть без голосования +- Требуется кворум для перевода токенов +- Timelock для критических операций (48ч) +- ReentrancyGuard от реентерабельности +- Flash-loan защита (снапшоты голосов) + +**Уровень 6: Мониторинг** +- Логирование всех действий +- Clean Logs система +- Алерты на подозрительную активность +- Audit trail для блокчейн-операций + +### Что если веб-приложение взломают? + +✅ **Ваши активы в безопасности!** + +**Критически важно**: Веб-приложение - это просто **интерфейс**. Реальные активы находятся на блокчейне. + +**Защищено даже при полном взломе**: +- 💰 Токены на кошельках - нельзя украсть без голосования +- 💼 Средства в Treasury - защищены смарт-контрактом +- 🗳️ Право голоса - привязано к балансу токенов +- 📜 Все решения - записаны на блокчейне + +**Управление через блокчейн-сканеры**: +Вы можете управлять всем бизнесом напрямую через Etherscan, Polygonscan и другие, **полностью в обход веб-приложения**. + +**Подробнее**: [Безопасность DLE](./security.md) + + +--- + +## 💻 Инфраструктурные требования + +### Минимальные спецификации + +Для запуска DLE необходимо: +- **CPU**: Минимум 4 ядра +- **RAM**: Минимум 12 GB + - 4 GB для базового приложения + - 6 GB для Ollama (AI) + - 2 GB для Vector Search +- **Хранилище**: SSD минимум 100 GB + - 20 GB для приложения и БД + - 50 GB для AI моделей + - 30 GB для логов и backup + +**Операционная система**: +- Ubuntu 20.04+ (рекомендуется) +- Debian 11+ +- CentOS 8+ +- Любая Linux с Docker + +### Рекомендуемые спецификации + +Для комфортной работы и роста: +- **CPU**: 8+ ядер (Intel Xeon, AMD EPYC) +- **RAM**: 32 GB+ +- **Хранилище**: 500 GB+ NVMe SSD +- **Сеть**: 1 Gbps+ +- **GPU**: NVIDIA (опционально, ускоряет AI в 5-10 раз) + +### Масштабирование + +**Горизонтальное масштабирование**: +- Load balancer (nginx, HAProxy) +- Несколько инстансов backend +- PostgreSQL репликация (master-slave) +- Redis кластер для кэша + +**Вертикальное масштабирование**: +- Увеличение CPU для AI нагрузок +- Больше RAM для векторных индексов +- Faster SSD для базы данных + +**Мониторинг**: +- Prometheus для сбора метрик +- Grafana для визуализации +- Alertmanager для уведомлений + +**Backup и восстановление**: +- Автоматические ежедневные backup PostgreSQL +- S3-совместимое хранилище для архивов +- Point-in-time recovery (PITR) +- Регулярное тестирование восстановления + +--- + +## 💳 Условия приобретения + +### Лицензионная модель + +**Бессрочная лицензия (Perpetual License)** +- Платите **один раз** - используйте **вечно** +- Полный доступ к исходному коду +- Бесплатные обновления пожизненно +- Право влиять на развитие продукта через голосование + +### Тарифы + +| Пакет | Цена | Голоса | Поддержка | +|-------|------|--------|-----------| +| **Standard Support** | $1,000 USDT | 1 голос | Email, портал | +| **Priority Support** | $10,000 USDT | 10 голосов | Приоритет, чат 24/7 | + +*Цены указаны без учета налогов* + +### Что включено + +✅ **Бессрочная лицензия** на использование +✅ **Исходный код** с полной документацией +✅ **Бесплатные обновления** навсегда +✅ **Техническая поддержка** по email/портал +✅ **Токены управления** на блокчейне +✅ **Право голоса** за новые функции +✅ **Гарантия возврата 70%** при невыполнении обязательств + +### Токены и голосование + +Каждая лицензия связана с **токенами управления через смарт-контракт DLE**: +- **1 токен = 1 голос** за новые функции +- **10 токенов = 10 голосов** за развитие продукта +- Решения принимаются большинством голосов (51%+) +- Прозрачность: все голосования на блокчейне + +**Портал для токен-холдеров**: +- 🗳️ **Голосование**: https://hb3-accelerator.com/governance +- 📥 **Обновления**: https://hb3-accelerator.com/updates + +### Гарантии + +**Программа возврата 70%**: +Если в течение 5 лет мы не предоставим обещанные обновления, вы получите обратно 70% от стоимости лицензии. + +**SLA (для Priority Support)**: +- Критичные проблемы: ответ в течение 4 часов +- Важные проблемы: ответ в течение 24 часов +- Обычные вопросы: ответ в течение 48 часов + +### Как приобрести + +1. Свяжитесь с нами: info@hb3-accelerator.com +2. Получите реквизиты для оплаты (USDT) +3. Оплатите лицензию +4. Получите доступ к коду и документации +5. Получите токены DLE на ваш кошелек + +📖 **Полные условия**: [Условия приобретения и обслуживания](./service-terms.md) + +--- + +## 📚 Дополнительная документация + +### Изучите возможности DLE + +**Для бизнеса и инвесторов**: +- 💼 **[Блокчейн для бизнеса](./blockchain-for-business.md)** - как токенизация активов решает бизнес-задачи, экономия 99% на сделках +- 🤖 **[AI Ассистент](./ai-assistant.md)** - второй пилот для команды, экономия $483,600/год, философия "AI+Человек" +- 💰 **[FAQ - Экономический эффект](./FAQ.md#экономический-эффект)** - детальный расчет ROI и окупаемости + +**Для разработчиков**: +- 🔗 **[Техническая документация по блокчейну](./blockchain-integration-technical.md)** - архитектура смарт-контрактов, API, примеры кода +- 🛡️ **[Безопасность DLE](./security.md)** - многоуровневая защита, Bug Bounty, управление через блокчейн-сканеры +- 🔧 **[Инструкция по установке](./setup-instruction.md)** - пошаговая настройка, Docker Compose, конфигурация + +**Общая информация**: +- 📋 **[FAQ](./FAQ.md)** - часто задаваемые вопросы (11 разделов, 50+ вопросов) +- 📜 **[История изменений](./CHANGELOG.md)** - все обновления документации +- 📖 **[Индекс документации](./README.md)** - полный список всех документов + +### Поддержка и контакты + +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com +- 💬 **Чат поддержки**: https://hb3-accelerator.com/ +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR +- 🔐 **Security (PGP)**: security@hb3-accelerator.com + +### Юридическая информация + +- ⚖️ **[Юридическая документация](../legal/README.md)** - полная правовая информация +- 📄 **[Условия обслуживания](./service-terms.md)** - детальные условия приобретения и поддержки +- 🛡️ **[Bug Bounty](./security.md#bug-bounty-программа)** - программа вознаграждений за уязвимости + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Digital Legal Entity (DLE)** - революция в управлении бизнесом через блокчейн и AI. + +**Версия документа**: 2.0.0 +**Последнее обновление**: October 2025 diff --git a/docs/blockchain-for-business.md b/docs/blockchain-for-business.md new file mode 100644 index 0000000..0155ba2 --- /dev/null +++ b/docs/blockchain-for-business.md @@ -0,0 +1,1293 @@ +# Блокчейн-интеграция для бизнеса: Решение реальных проблем + +## 📋 Содержание + +1. [Введение: Зачем бизнесу блокчейн?](#введение-зачем-бизнесу-блокчейн) +2. [Смарт-контракт как универсальный идентификатор](#смарт-контракт-как-универсальный-идентификатор) +3. [Токенизация активов](#токенизация-активов) +4. [Решение проблем управления](#решение-проблем-управления) +5. [Финансовые операции без банков](#финансовые-операции-без-банков) +6. [Прозрачность и доверие](#прозрачность-и-доверие) +7. [Автоматизация и снижение издержек](#автоматизация-и-снижение-издержек) +8. [Практические кейсы](#практические-кейсы) +9. [Экономический эффект](#экономический-эффект) + +--- + +## Введение: Зачем бизнесу блокчейн? + +### Проблемы традиционного бизнеса + +Современный бизнес сталкивается с множеством проблем: + +| Проблема | Последствия | Издержки | +|----------|-------------|----------| +| 🏦 **Множество банковских счетов** | Сложность учета, комиссии | 2-5% оборота | +| 📄 **Бюрократия** | Медленные решения, бумажная волокита | 20-30% времени | +| 🤝 **Непрозрачное управление** | Конфликты акционеров, коррупция | До 40% стоимости | +| 💰 **Неликвидные активы** | Невозможно быстро продать/разделить | Потеря возможностей | +| 🌍 **Географические ограничения** | Сложности с международными партнерами | Упущенная прибыль | +| ⏰ **Медленные транзакции** | 3-7 дней на банковские переводы | Заморозка капитала | + +### Решение: Digital Legal Entity на блокчейне + +DLE превращает вашу компанию в **цифровую организацию** с блокчейн-идентичностью, где: +- ✅ Один адрес смарт-контракта = вся идентификация компании +- ✅ Любые активы токенизированы и легко управляемы +- ✅ Прозрачное управление через голосование +- ✅ Мгновенные финансовые операции без посредников +- ✅ Глобальная доступность 24/7 + +--- + +## Смарт-контракт как универсальный идентификатор + +### Концепция: Один адрес для всего + +В традиционном бизнесе у компании множество идентификаторов: +``` +Традиционная компания: +├── ИНН/ОГРН (налоговый номер) +├── Банковский счет №1 (руб) +├── Банковский счет №2 (USD) +├── Банковский счет №3 (EUR) +├── Email: info@company.com +├── Телефон: +7-xxx-xxx-xx-xx +├── Юридический адрес +├── Реквизиты для договоров +└── Множество учетных систем +``` + +**С DLE на блокчейне:** +``` +Digital Legal Entity: +└── 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C + ↑ + Этот ОДИН адрес смарт-контракта заменяет ВСЁ: + ✅ Налоговый идентификатор + ✅ Банковский счет (мультивалютный) + ✅ Email/телефон (получение платежей и сообщений) + ✅ Юридическая идентичность + ✅ Адрес для коммуникаций + ✅ Система учета активов +``` + +### Как это работает в реальности? + +#### 1. Налоговый идентификатор + +**Традиционно:** +- ИНН (Россия): 10 цифр +- EIN (США): 9 цифр +- VAT ID (ЕС): 8-12 символов +- Разные в каждой юрисдикции + +**С DLE:** +- Адрес контракта: `0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C` +- **Один и тот же** во всех странах и блокчейнах +- Привязка к традиционным номерам хранится в смарт-контракте: + ```solidity + struct DLEInfo { + uint256 jurisdiction; // 643 = Россия, 840 = США + string[] okvedCodes; // Коды ОКВЭД (виды деятельности) + uint256 kpp; // КПП для РФ + string location; // Местоположение + } + ``` + +**Преимущества:** +- ✅ Не нужно регистрироваться в каждой стране +- ✅ Мгновенная верификация через блокчейн +- ✅ Невозможно подделать или украсть идентификатор + +#### 2. Банковский счет (мультивалютный) + +**Традиционно:** +- Отдельный счет для каждой валюты +- Комиссии за открытие: $50-500 +- Ежемесячное обслуживание: $10-100 +- Конвертация: 1-5% комиссии +- Переводы: 3-7 дней + $25-50 + +**С DLE:** +- Адрес контракта принимает любые токены: + - USDT, USDC (стейблкоины = доллары) + - Нативные монеты (ETH, MATIC, BNB) + - Любые ERC20 токены + - Токенизированные активы + +**Пример транзакции:** +``` +Клиент отправляет оплату → 0x742d35... + ↓ + Получено за 30 секунд + Комиссия: $0.10-5 + Видно всем участникам +``` + +**Преимущества:** +- ✅ Один адрес для всех валют +- ✅ Комиссия в 50-100 раз ниже +- ✅ Моментальные транзакции +- ✅ Работает 24/7, включая выходные +- ✅ Нет блокировок и заморозок + +#### 3. Email и телефон для компании + +**Традиционно:** +- Email: info@company.com (можно взломать, потерять домен) +- Телефон: +7-xxx-xxx (можно перехватить SIM) +- Разные каналы для разных целей + +**С DLE:** +- **Адрес контракта** = адрес для коммуникаций +- Подписи криптографическими ключами (невозможно подделать) +- Встроенная омниканальная система: + ``` + 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C + ↓ + ┌───────────┴───────────┬───────────┬──────────┐ + │ Блокчейн-сообщения │ Telegram │ Email │ Web + │ (криптографически │ (бот) │ (SMTP) │ (форма) + │ подписанные) │ │ │ + └───────────────────────┴───────────┴──────────┘ + ``` + +**Преимущества:** +- ✅ Невозможно взломать (приватный ключ = доступ) +- ✅ Полная история коммуникаций на блокчейне +- ✅ Автоматическая верификация отправителя +- ✅ Интеграция всех каналов в одном месте + +--- + +## Токенизация активов + +### Что такое токенизация? + +**Токенизация** - это превращение любого актива в цифровой токен на блокчейне, который можно: +- 🔄 Быстро купить/продать +- 📊 Разделить на доли (дробное владение) +- 💱 Обменять на другие активы +- 📈 Отслеживать стоимость в реальном времени +- 🌍 Передавать по всему миру мгновенно + +### Типы активов для токенизации + +#### 1. 🏢 Недвижимость + +**Традиционная проблема:** +- Неликвидность (продажа 3-12 месяцев) +- Высокие комиссии (3-6% от стоимости) +- Невозможно разделить (нельзя продать 10% квартиры) +- Бюрократия (десятки документов, нотариусы) + +**Решение через токенизацию:** +``` +Офисное здание = 10,000,000 токенов DLE +├── 1 токен = 0.00001% здания +├── Цена токена: $100 +├── Минимальная покупка: 1 токен ($100) +└── Продажа: 30 секунд на блокчейне +``` + +**Преимущества:** +- ✅ Любой может купить долю от $100 +- ✅ Продажа за 30 секунд вместо 6 месяцев +- ✅ Комиссия 0.1% вместо 5% +- ✅ Автоматическое распределение арендных платежей +- ✅ Прозрачная история владения + +**Пример:** +``` +Вы владеете офисом за 10 млн руб. +↓ Токенизация +Выпускаете 100,000 токенов по 100 руб. +↓ Продаете 30% (30,000 токенов) +Получили 3 млн руб. за 1 день +↓ Аренда 500,000 руб/месяц +Автоматически распределяется: +├── 70% (350,000 руб) → вам +└── 30% (150,000 руб) → новым владельцам токенов +``` + +#### 2. 📈 Акции и доли в бизнесе + +**Традиционная проблема:** +- IPO стоит миллионы и занимает годы +- Доли в ООО не продаются (нужен нотариус, ИФНС) +- Учет акционеров - дорого и сложно +- Дивиденды выплачиваются вручную + +**Решение через DLE:** +``` +Ваша компания = токены DLE +├── 1,000,000 токенов = 100% компании +├── Вы: 700,000 токенов (70%) +├── Партнер: 200,000 токенов (20%) +└── Инвесторы: 100,000 токенов (10%) +``` + +**Преимущества:** +- ✅ "IPO" за 1 день вместо 2 лет +- ✅ Стоимость: $100-1000 вместо $500,000+ +- ✅ Автоматическая выплата дивидендов +- ✅ Мгновенная продажа долей +- ✅ Прозрачный учет владельцев + +**Кейс:** +``` +Стартап ищет инвестиции: + +Традиционно: +├── Поиск инвестора: 6-12 месяцев +├── Юристы и документы: $10,000-50,000 +├── Регистрация изменений: 1-2 месяца +└── ИТОГО: $50,000 + год времени + +С DLE: +├── Выпустить токены: 1 день +├── Продать на DEX: сразу +├── Стоимость: $100 (gas fees) +└── ИТОГО: $100 + 1 день +``` + +#### 3. 🎨 Интеллектуальная собственность + +**Что можно токенизировать:** +- Патенты +- Авторские права (музыка, книги, видео) +- Товарные знаки +- Франшизы +- Лицензии на ПО + +**Пример: Токенизация музыкального альбома** +``` +Альбом исполнителя = 1,000,000 токенов +├── Исполнитель оставляет: 500,000 (50%) +├── Продает фанатам: 500,000 токенов по $1 +└── Доход от стриминга автоматически делится: + ├── 50% → исполнитель + └── 50% → держатели токенов +``` + +**Преимущества:** +- ✅ Фанаты инвестируют в любимого артиста +- ✅ Автоматические роялти +- ✅ Прозрачность доходов +- ✅ Вторичный рынок (токены можно перепродать) + +#### 4. 📦 Товары и инвентарь + +**Проблема:** Товары на складе "мертвый" капитал + +**Решение:** +``` +100 тонн пшеницы = 100,000 токенов +├── 1 токен = 1 кг пшеницы +├── Цена токена: текущая биржевая + 5% +└── Можно продать/купить в любой момент +``` + +**Преимущества:** +- ✅ Ликвидность складских запасов +- ✅ Хеджирование рисков (продать часть заранее) +- ✅ Привлечение финансирования под товары +- ✅ Прозрачная цепочка поставок + +#### 5. 💎 Драгоценности и предметы искусства + +**Кейс: Токенизация бриллианта** +``` +Бриллиант 5 карат = 5,000 токенов +├── 1 токен = 0.001 карата +├── Цена: $100,000 / 5,000 = $20 за токен +├── Физический бриллиант в сейфе (подтверждено сертификатом) +└── Владельцы токенов = совладельцы бриллианта +``` + +**Преимущества:** +- ✅ Доступ к инвестициям от $20 +- ✅ Ликвидность (продажа за минуты) +- ✅ Диверсификация (купить доли в разных камнях) +- ✅ Прозрачное хранение и страхование + +### Как работает токенизация в DLE? + +#### Модель Treasury (Казна) + +``` +┌─────────────────────────────────────────────────┐ +│ DLE Smart Contract │ +│ Адрес: 0x742d35... │ +├─────────────────────────────────────────────────┤ +│ АКТИВЫ (Treasury): │ +│ ├── 10 BTC │ +│ ├── 100,000 USDT │ +│ ├── Токенизированная недвижимость: 3 объекта │ +│ ├── Акции компаний: 10 эмитентов │ +│ └── Интеллектуальная собственность: 5 патентов │ +├─────────────────────────────────────────────────┤ +│ УПРАВЛЕНИЕ: │ +│ ├── Токен-холдеры голосуют за распределение │ +│ ├── 51%+ = решение принято │ +│ └── Автоматическое исполнение смарт-контрактом │ +└─────────────────────────────────────────────────┘ +``` + +**Процесс:** +1. **Компания покупает актив** (недвижимость, оборудование, etc.) +2. **Актив помещается в Treasury Module** смарт-контракта +3. **Токен-холдеры владеют долями** в соответствии с количеством токенов +4. **Доходы от активов** автоматически распределяются пропорционально + +--- + +## Решение проблем управления + +### Традиционные проблемы корпоративного управления + +#### 1. Непрозрачность решений + +**Проблема в классических компаниях:** +``` +Совет директоров: +├── Закрытые заседания +├── Нет записи решений (или потеряны) +├── Невозможно проверить, кто как голосовал +├── Конфликты интересов скрыты +└── Акционеры не знают, что происходит +``` + +**Решение в DLE:** +``` +Каждое предложение (Proposal): +├── ID: #42 +├── Описание: "Купить новый офис за 5 млн" +├── Инициатор: 0xABC...123 +├── Голоса "За": 5,234,567 токенов (62%) +├── Голоса "Против": 3,123,456 токенов (38%) +├── Кто как голосовал: публично на блокчейне +├── Дата голосования: 2025-10-25 +└── Результат: Одобрено ✅ +``` + +**Преимущества:** +- ✅ **Полная прозрачность** - каждый акционер видит всё +- ✅ **Неизменяемая история** - нельзя подделать результаты +- ✅ **Автоматический подсчет** - нет манипуляций +- ✅ **Доказуемость** - любой может проверить на блокчейне + +#### 2. Медленное принятие решений + +**Традиционная схема:** +``` +Предложение изменения → + Подготовка документов (2 недели) → + Согласование с юристами (1 неделя) → + Созыв собрания акционеров (1 месяц) → + Голосование (1 день) → + Оформление протокола (1 неделя) → + Регистрация (2 недели) → + ИТОГО: 3 месяца +``` + +**С DLE на блокчейне:** +``` +Предложение изменения → + Создание Proposal (5 минут) → + Голосование (1-7 дней) → + Автоматическое исполнение (30 секунд) → + ИТОГО: 1-7 дней +``` + +**Экономия:** 90-95% времени! + +#### 3. Высокие издержки на управление + +**Традиционные расходы на корпоративное управление:** +``` +Ежегодные расходы на управление ООО/АО: +├── Бухгалтер: $12,000-36,000/год +├── Юрист: $10,000-50,000/год +├── Нотариус (сделки): $500-5,000/год +├── Реестр акционеров: $2,000-10,000/год +├── Аудит: $5,000-50,000/год +├── Собрания акционеров (организация): $2,000-10,000/год +└── ИТОГО: $31,500-161,000/год +``` + +**С DLE:** +``` +Ежегодные расходы: +├── Gas fees для транзакций: $100-1,000/год +├── RPC провайдеры: $0-500/год (можно бесплатно) +├── Хостинг приложения: $100-500/год +└── ИТОГО: $200-2,000/год +``` + +**Экономия:** 90-99% расходов! + +#### 4. Коррупция и конфликты интересов + +**Традиционная проблема:** +- Директор покупает услуги у своей компании по завышенной цене +- Невозможно отследить +- Сложно доказать +- Долгие судебные разбирательства + +**Решение DLE:** +``` +Предложение: "Купить оборудование у Компании X за $100,000" +↓ +Все токен-холдеры видят: +├── Кто инициировал: 0xABC...123 (Иван Иванов) +├── Владелец Компании X: 0xABC...123 (ТОТ ЖЕ ЧЕЛОВЕК!) +├── Конфликт интересов: ОБНАРУЖЕН ⚠️ +└── Токен-холдеры голосуют "Против" +``` + +**Преимущества:** +- ✅ Автоматическое выявление конфликтов +- ✅ Прозрачность владения +- ✅ Невозможно скрыть связи +- ✅ Коллективное принятие решений + +### Иерархическое управление (DLE владеет другими DLE) + +**Концепция:** Одна компания владеет акциями других компаний + +``` +┌─────────────────────────────────────────┐ +│ Холдинг DLE-A (Материнская компания) │ +│ 1,000,000 токенов │ +└──────────────┬──────────────────────────┘ + │ Владеет токенами: + ┌───────┼───────┬─────────────┐ + ↓ ↓ ↓ ↓ + ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ + │DLE-B │ │DLE-C │ │DLE-D │ │DLE-E │ + │70% │ │51% │ │100% │ │25% │ + │Ритейл │ │Произв.│ │IT │ │Старт. │ + └───────┘ └───────┘ └───────┘ └───────┘ +``` + +**Возможности:** +1. **DLE-A голосует в дочерних компаниях** автоматически +2. **Консолидированное управление** всем холдингом +3. **Прозрачная структура владения** (видно всем) +4. **Автоматические дивиденды** снизу вверх + +**Пример:** +``` +DLE-D заработала 100,000 USDT прибыли +↓ +Голосование в DLE-D: "Выплатить дивиденды" +↓ +100% токенов у DLE-A → 100,000 USDT идут в DLE-A +↓ +Автоматически распределяются между акционерами DLE-A +``` + +--- + +## Финансовые операции без банков + +### Проблемы банковской системы для бизнеса + +| Проблема | Последствия | Ваши потери | +|----------|-------------|-------------| +| 🏦 **Высокие комиссии** | 2-5% за транзакции | $20,000 на $1M оборота | +| ⏰ **Медленные переводы** | 3-7 дней | Заморозка капитала | +| 🌍 **SWIFT комиссии** | $25-50 за перевод | $300-600/месяц | +| 💱 **Конвертация валют** | 3-7% спред | $30,000-70,000/год | +| 🚫 **Блокировки счетов** | Остановка бизнеса | Миллионы убытков | +| 📋 **Комплаенс** | Запросы документов | Время сотрудников | +| 🌐 **Ограничения по странам** | Нет доступа к рынкам | Упущенная прибыль | + +### Решение: Криптовалютные операции через DLE + +#### 1. Мгновенные платежи 24/7 + +**Сравнение:** +``` +Банковский перевод (международный): +├── Время: 3-7 рабочих дней +├── Комиссия: $25-50 + 2-5% конвертации +├── Работает: Пн-Пт, 9:00-18:00 +└── Может быть заблокирован + +Крипто-перевод (через DLE): +├── Время: 30 секунд - 5 минут +├── Комиссия: $0.10-5 +├── Работает: 24/7/365 +└── Невозможно заблокировать +``` + +**Реальный кейс:** +``` +Вы продаете товар в Китай за $100,000 + +Традиционно: +├── SWIFT перевод: 5 дней +├── Комиссия банка: $50 +├── Конвертация USD→CNY: 3% = $3,000 +├── Комиссия китайского банка: $30 +└── ИТОГО: $3,080 комиссий + 5 дней ожидания + +С DLE (USDT): +├── Перевод на блокчейне: 30 секунд +├── Gas fee: $2 +├── Конвертация: 0% (USDT = USD) +└── ИТОГО: $2 комиссия + 30 секунд +``` + +**Экономия:** $3,078 (99.9%) на каждой транзакции! + +#### 2. Мультивалютная казна + +**Один адрес DLE хранит все валюты:** +``` +Treasury DLE: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +├── Стейблкоины (= фиатные валюты): +│ ├── USDT: 500,000 (= $500,000) +│ ├── USDC: 300,000 (= $300,000) +│ ├── EURC: 200,000 (= €200,000) +│ └── XSGD: 100,000 (= S$100,000) +├── Криптовалюты: +│ ├── ETH: 100 ($200,000) +│ ├── BTC: 5 ($250,000) +│ └── MATIC: 1,000,000 ($800,000) +└── Токенизированные активы: + ├── Недвижимость: $5,000,000 + └── Акции компаний: $2,000,000 +``` + +**Преимущества:** +- ✅ Нет отдельных счетов +- ✅ Мгновенная конвертация (через DEX) +- ✅ Прозрачный баланс для всех акционеров +- ✅ Автоматический учет + +#### 3. Автоматические выплаты зарплат и дивидендов + +**Традиционная схема выплаты дивидендов:** +``` +1. Собрание акционеров: решение о дивидендах +2. Бухгалтер считает суммы для каждого +3. Формирование платежных поручений +4. Отправка в банк +5. Банк обрабатывает: 3-7 дней +6. Налоги удерживаются +7. Выплата акционерам + +ИТОГО: 2-4 недели + ошибки + комиссии +``` + +**С DLE:** +```javascript +// Одна транзакция для выплаты дивидендов ВСЕМ акционерам +function distributeDividends(uint256 amount) { + // Смарт-контракт автоматически: + // 1. Берет USDT из казны + // 2. Вычисляет долю каждого токен-холдера + // 3. Отправляет пропорционально токенам + // 4. Всё за 30 секунд! +} +``` + +**Пример:** +``` +Прибыль компании: 1,000,000 USDT +Токен-холдеры: +├── Алиса: 600,000 токенов (60%) → 600,000 USDT +├── Боб: 300,000 токенов (30%) → 300,000 USDT +└── Кэрол: 100,000 токенов (10%) → 100,000 USDT + +Одна транзакция → Все получили за 30 секунд +Комиссия: $5 вместо $50-500 +``` + +#### 4. Глобальные платежи без ограничений + +**Проблемы традиционных платежей:** +- 🚫 Санкции (невозможно отправить деньги в некоторые страны) +- 📋 Комплаенс (нужны документы для каждого перевода) +- 💸 Лимиты (ограничения на сумму) +- ⏰ Задержки (банки проверяют каждую транзакцию) + +**С криптовалютами:** +- ✅ Нет географических ограничений +- ✅ Нет санкций на уровне протокола +- ✅ Нет лимитов на суммы +- ✅ Мгновенные платежи + +**Важно:** Вы всё равно обязаны соблюдать местные законы и платить налоги! + +--- + +## Прозрачность и доверие + +### Проблема доверия в бизнесе + +**Типичные ситуации недоверия:** + +1. **Инвесторы → Учредители** + - "Куда ушли наши деньги?" + - "Почему нет прибыли?" + - "Где отчет о расходах?" + +2. **Партнеры → Друг другу** + - "Ты действительно вложил обещанную сумму?" + - "Кто сколько получает дивидендов?" + - "Почему я не участвую в решениях?" + +3. **Клиенты → Компания** + - "Вы действительно владеете этим активом?" + - "Мои деньги в безопасности?" + - "Есть ли у вас лицензия?" + +### Решение: Блокчейн как источник истины + +#### Прозрачность финансов + +**Каждый токен-холдер видит в реальном времени:** + +``` +Treasury (Казна компании): +├── Активы: +│ ├── 500,000 USDT +│ ├── 10 BTC +│ ├── Недвижимость: 3 объекта +│ └── Акции: 10 компаний +├── Обязательства: +│ ├── Кредит: 100,000 USDT +│ └── Зарплатный фонд: 50,000 USDT/месяц +└── История операций: + ├── 2025-10-20: Получено 200,000 USDT от клиента + ├── 2025-10-21: Выплачено 50,000 USDT зарплат + └── 2025-10-22: Куплено 2 BTC за 100,000 USDT +``` + +**Невозможно:** +- ❌ Скрыть расходы +- ❌ Вывести деньги втихую +- ❌ Подделать баланс +- ❌ Скрыть убытки + +#### Прозрачность решений + +**Каждое решение записано навсегда:** + +``` +Proposal #15: "Купить новый офис за 5 млн" +├── Инициатор: Иван Петров (0xABC...123) +├── Дата создания: 2025-10-15 +├── Срок голосования: 7 дней +├── Голоса: +│ ├── "За": 62% (6,200,000 токенов) +│ │ └── Владельцы: [список адресов] +│ └── "Против": 38% (3,800,000 токенов) +│ └── Владельцы: [список адресов] +├── Статус: ОДОБРЕНО ✅ +└── Исполнено: 2025-10-22 (автоматически) +``` + +**Преимущества:** +- ✅ Нельзя сказать "Я не голосовал за это!" +- ✅ Видно, кто инициировал решение +- ✅ Прозрачна мотивация (связи, интересы) +- ✅ Невозможно переписать историю + +#### Прозрачность владения + +**Все знают, кто чем владеет:** + +``` +Владельцы токенов DLE: +├── 0xABC...123 (Иван Петров): 600,000 токенов (60%) +├── 0xDEF...456 (Компания X): 300,000 токенов (30%) +└── 0xGHI...789 (Фонд Y): 100,000 токенов (10%) +``` + +**Автоматические проверки:** +- ⚠️ Конфликт интересов: обнаружен +- ⚠️ Связанные стороны: найдены +- ⚠️ Концентрация владения: критическая + +### Репутация на блокчейне + +**Каждая компания (DLE) имеет:** +- ✅ Неизменяемую историю операций +- ✅ Рейтинг от партнеров +- ✅ Публичные финансовые показатели +- ✅ Подтвержденные активы + +**Это как:** +- 📊 Кредитная история (но прозрачная) +- ⭐ Рейтинг на маркетплейсе (но невозможно накрутить) +- 📜 Аудит (но постоянный и бесплатный) + +--- + +## Автоматизация и снижение издержек + +### Устранение посредников + +**Кого блокчейн убирает из процесса:** + +``` +Традиционная транзакция: +Компания A → Банк A → SWIFT → Банк B → Компания B + ↓ ↓ ↓ ↓ ↓ + 3-5% 0.5-1% $25-50 0.5-1% 3-5% + ИТОГО: 7-12% комиссий + 3-7 дней + +Блокчейн-транзакция: +Компания A ──────────────────────→ Компания B + $0.10-5, 30 секунд +``` + +**Экономия на $1,000,000 оборота:** +- Традиционно: $70,000-120,000 комиссий +- Блокчейн: $100-500 комиссий +- **Экономия: $69,500-119,500 (99%)** + +### Автоматизация процессов + +#### 1. Корпоративное управление + +**Было (вручную):** +``` +Шаги для принятия решения: +1. Подготовка предложения: 2-5 дней +2. Согласование с юристами: 3-7 дней +3. Рассылка акционерам: 1 день +4. Созыв собрания: 30 дней (по закону) +5. Проведение голосования: 1 день +6. Подсчет голосов: 1-2 дня +7. Оформление протокола: 3-5 дней +8. Регистрация решения: 14-30 дней + +ИТОГО: 55-85 дней +Стоимость: $2,000-10,000 +``` + +**Стало (автоматически):** +``` +1. Создание Proposal: 5 минут +2. Голосование: 1-7 дней (настраивается) +3. Автоматическое исполнение: 30 секунд + +ИТОГО: 1-7 дней +Стоимость: $2-5 (gas fees) +``` + +#### 2. Выплата дивидендов + +**Было (вручную):** +``` +1. Определение суммы дивидендов: 1 день +2. Расчет доли каждого акционера: 2-3 дня +3. Подготовка платежных поручений: 2 дня +4. Отправка в банк: 1 день +5. Обработка банком: 3-7 дней +6. Получение акционерами: 1-3 дня + +ИТОГО: 10-17 дней +Стоимость: $500-2,000 +Ошибки: 5-10% транзакций +``` + +**Стало (автоматически):** +``` +function distributeDividends() { + // Одна транзакция → все получили +} + +ИТОГО: 30 секунд +Стоимость: $5-20 +Ошибки: 0% (математика смарт-контракта) +``` + +#### 3. Аудит и отчетность + +**Было (вручную):** +``` +Ежегодный аудит: +├── Сбор документов: 1-2 недели +├── Проверка аудиторами: 2-4 недели +├── Исправления: 1-2 недели +├── Финальный отчет: 1 неделя +└── Стоимость: $5,000-50,000 + ++ Квартальная отчетность: еще $2,000-10,000/квартал +``` + +**Стало (автоматически):** +``` +Блокчейн = постоянный аудит: +├── Каждая транзакция проверена сетью +├── Невозможно подделать данные +├── Реалтайм отчеты для всех +└── Стоимость: $0 (уже включено в блокчейн) +``` + +**Экономия:** $13,000-90,000/год на аудит и отчетность + +### Смарт-контракты вместо юристов + +**Что автоматизируется:** + +| Процесс | Было | Стало | +|---------|------|-------| +| **Выплата при условии** | Эскроу ($500-2,000) | Смарт-контракт ($5) | +| **Многосторонние подписи** | Нотариус ($100-500) | Multisig ($2-10) | +| **Автоматические платежи** | Бухгалтер ($2,000/мес) | Смарт-контракт ($10/мес) | +| **Распределение роялти** | Юрист ($5,000+) | Смарт-контракт ($20) | + +**Пример: Эскроу для сделки** + +Традиционно: +``` +1. Поиск эскроу-агента +2. Подписание договора эскроу +3. Оплата услуг: $500-2,000 +4. Перевод денег агенту +5. Проверка условий (вручную) +6. Выплата (3-7 дней) +``` + +Со смарт-контрактом: +```solidity +contract Escrow { + // Деньги заблокированы пока условие не выполнено + if (условие_выполнено) { + отправить_деньги_продавцу(); + } else if (срок_истек) { + вернуть_деньги_покупателю(); + } +} +``` +Стоимость: $5, исполнение автоматическое за 30 секунд + +--- + +## Практические кейсы + +### Кейс 1: Стартап привлекает инвестиции + +**Ситуация:** +Технологический стартап ищет $500,000 инвестиций. + +**Традиционный путь:** +``` +1. Поиск инвесторов: 6-12 месяцев +2. Due diligence: 2-3 месяца +3. Переговоры и оценка: 1-2 месяца +4. Юридическое оформление: 1-2 месяца + ├── Изменение устава + ├── Эмиссия акций + └── Регистрация в ИФНС +5. Стоимость процесса: + ├── Юристы: $20,000-50,000 + ├── Оценщики: $5,000-10,000 + ├── Регистрация: $2,000-5,000 + └── ИТОГО: $27,000-65,000 + +ИТОГО: 10-19 месяцев + $27,000-65,000 +``` + +**С DLE на блокчейне:** +``` +1. Создание DLE: 1 день + ├── Выпуск 10,000,000 токенов + ├── Учредители оставляют: 7,000,000 (70%) + └── Для инвесторов: 3,000,000 (30%) + +2. Размещение токенов: + ├── Launchpad на DEX + ├── Цена: $0.167 за токен + ├── Продано за: 3 дня + └── Получено: $500,000 + +3. Стоимость процесса: + ├── Деплой смарт-контракта: $100 + ├── Листинг на DEX: $500 + └── ИТОГО: $600 + +ИТОГО: 4 дня + $600 +``` + +**Результат:** +- ⚡ В 90 раз быстрее +- 💰 В 45-100 раз дешевле +- 🌍 Доступ к глобальным инвесторам +- ✅ Мгновенная ликвидность токенов + +### Кейс 2: Фонд недвижимости + +**Ситуация:** +Инвестиционный фонд владеет офисным зданием за $10,000,000. Хочет привлечь средства для нового проекта. + +**Традиционный путь:** +``` +Варианты: +1. Банковский кредит под залог: + ├── Ставка: 12-18% + ├── Срок оформления: 2-3 месяца + └── Стоимость оценки + юристы: $50,000 + +2. Продать здание целиком: + ├── Срок продажи: 6-18 месяцев + ├── Комиссия агентам: 3-5% ($300,000-500,000) + └── Теряет актив + +3. Привлечь инвесторов в фонд: + ├── Создание ЗПИФ: $50,000-200,000 + ├── Срок: 6-12 месяцев + └── Ежегодное обслуживание: $20,000-50,000 +``` + +**С токенизацией через DLE:** +``` +1. Токенизация здания: + ├── Выпуск 10,000,000 токенов + ├── 1 токен = $1 стоимости здания + └── Срок: 1 день + +2. Продажа 30% токенов: + ├── 3,000,000 токенов на DEX + ├── Цена: $1 за токен + ├── Продано за: 2 недели + └── Получено: $3,000,000 + +3. Арендные платежи: + ├── Аренда: $100,000/месяц + ├── Автоматическое распределение: + │ ├── 70% ($70,000) → фонду + │ └── 30% ($30,000) → держателям токенов + └── Выплаты: ежемесячно, автоматически + +4. Стоимость: + ├── Токенизация: $500 + ├── Листинг: $500 + └── ИТОГО: $1,000 +``` + +**Результат:** +- ⚡ Получили $3M за 2 недели +- 💰 Сохранили актив (владеют 70%) +- 📈 Пассивный доход продолжается +- 🔄 Можно выкупить токены обратно +- 💸 Стоимость 1000$ vs $50,000-200,000 + +### Кейс 3: Музыкальный лейбл + +**Ситуация:** +Независимый музыкальный лейбл хочет выпустить альбом нового артиста. + +**Традиционный путь:** +``` +1. Поиск инвестиций для записи: + ├── Нужно: $50,000 + ├── Источники: банк, инвесторы + ├── Условия: 50% роялти инвесторам + └── Срок поиска: 3-6 месяцев + +2. Выпуск альбома: + ├── Запись: $30,000 + ├── Продвижение: $20,000 + └── Срок: 3-6 месяцев + +3. Доходы от стриминга: + ├── Spotify: $0.003-0.005 за прослушивание + ├── Площадки берут: 30% + ├── Лейбл: 35% + ├── Инвесторы: 35% + └── Артист: 30% + +ИТОГО: 6-12 месяцев, артист получает только 30% +``` + +**С токенизацией через DLE:** +``` +1. Создание DLE для альбома: + ├── Выпуск 1,000,000 токенов + ├── Артист оставляет: 500,000 (50%) + ├── Продажа фанатам: 500,000 по $0.10 + └── Получено: $50,000 за 1 неделю + +2. Выпуск альбома: + ├── Запись: $30,000 + ├── Продвижение: $20,000 + └── Срок: 3-6 месяцев + +3. Доходы от стриминга: + ├── Доход: $10,000/месяц + ├── Автоматическое распределение: + │ ├── 50% ($5,000) → артист + │ └── 50% ($5,000) → держатели токенов (фаны) + └── Выплаты: ежемесячно, автоматически + +4. Бонусы: + ├── Фаны зарабатывают на успехе артиста + ├── Токены можно перепродать (вторичный рынок) + ├── Артист напрямую связан с фанами + └── Прозрачность всех доходов +``` + +**Результат:** +- ⚡ Получили инвестиции за неделю +- 💰 Артист получает 50% вместо 30% +- 🎵 Фаны зарабатывают вместе с артистом +- 🔄 Ликвидность токенов на вторичном рынке + +### Кейс 4: Агрохолдинг (токенизация урожая) + +**Ситуация:** +Фермерское хозяйство выращивает пшеницу. Нужны деньги на посевную (апрель), урожай будет в августе. + +**Традиционный путь:** +``` +1. Кредит в банке: + ├── Сумма: $200,000 + ├── Ставка: 15% годовых + ├── Срок кредита: 6 месяцев + ├── Проценты: $15,000 + └── Срок оформления: 1 месяц + +2. Риски: + ├── Неурожай → нечем платить кредит + ├── Падение цены → убытки + └── Банкротство +``` + +**С токенизацией урожая через DLE:** +``` +1. Апрель (посевная): + ├── Прогноз урожая: 1,000 тонн пшеницы + ├── Выпуск 1,000,000 токенов + ├── 1 токен = 1 кг пшеницы + ├── Цена токена: $0.25 (текущая цена + 10%) + └── Продажа 800,000 токенов → $200,000 + +2. Август (урожай): + ├── Собрано: 1,000 тонн + ├── Цена выросла до $0.30/кг + ├── Держатели токенов могут: + │ ├── Получить физическую пшеницу + │ ├── Продать токены по $0.30 + │ └── Заработать: 20% за 4 месяца + └── Фермер получил деньги без кредита + +3. Преимущества: + ├── Нет процентов (0% vs 15%) + ├── Делится риск урожая с инвесторами + ├── Прямая связь с покупателями + └── Прозрачность всей цепочки +``` + +**Результат:** +- 💰 Экономия $15,000 на процентах +- 🌾 Риски разделены с инвесторами +- 📈 Инвесторы заработали 20% за 4 месяца +- 🔗 Прозрачная цепочка поставок + +--- + +## Экономический эффект + +### Расчет экономии для типичного бизнеса + +**Исходные данные:** +- Оборот: $1,000,000/год +- Сотрудники: 10 человек +- Акционеры: 5 человек +- Международные операции: 20% оборота + +#### 1. Экономия на банковских комиссиях + +``` +Традиционно: +├── Обслуживание счета: $1,200/год +├── Транзакции внутри страны: 1% × $800,000 = $8,000 +├── Международные переводы: 5% × $200,000 = $10,000 +├── SWIFT комиссии: 50 переводов × $35 = $1,750 +├── Конвертация валют: 3% × $200,000 = $6,000 +└── ИТОГО: $26,950/год + +С DLE (крипто): +├── Gas fees: $1,000/год +├── RPC провайдеры: $200/год +└── ИТОГО: $1,200/год + +ЭКОНОМИЯ: $25,750/год (96%) +``` + +#### 2. Экономия на корпоративном управлении + +``` +Традиционно: +├── Бухгалтер: $24,000/год +├── Юрист (корпоративное право): $15,000/год +├── Нотариус (собрания, сделки): $2,000/год +├── Реестр акционеров: $3,000/год +├── Аудит: $10,000/год +└── ИТОГО: $54,000/год + +С DLE: +├── Автоматизация через смарт-контракты +├── Бухгалтер (только налоги): $12,000/год +└── ИТОГО: $12,000/год + +ЭКОНОМИЯ: $42,000/год (78%) +``` + +#### 3. Экономия на привлечении инвестиций + +``` +Традиционно (одна сделка): +├── Юристы: $30,000 +├── Оценщики: $7,000 +├── Due diligence: $10,000 +├── Регистрация изменений: $3,000 +└── ИТОГО: $50,000 + +С DLE (эмиссия токенов): +├── Деплой смарт-контракта: $100 +├── Листинг на DEX: $500 +└── ИТОГО: $600 + +ЭКОНОМИЯ: $49,400 на сделку (99%) +``` + +#### 4. Экономия времени (стоимость упущенных возможностей) + +``` +Традиционно: +├── Принятие решений: 2-3 месяца +├── Выплата дивидендов: 2-3 недели +├── Привлечение инвестиций: 6-12 месяцев +└── Международные переводы: 3-7 дней + +С DLE: +├── Принятие решений: 1-7 дней +├── Выплата дивидендов: 30 секунд +├── Привлечение инвестиций: 1-14 дней +└── Международные переводы: 30 секунд + +Оценка стоимости времени: +├── 10 месяцев экономии × $100,000 оборот/месяц +└── Дополнительная прибыль: $1,000,000 +``` + +### Итоговая экономия за год + +``` +┌─────────────────────────────────────────────┐ +│ ЭКОНОМИЧЕСКИЙ ЭФФЕКТ ДЛЯ БИЗНЕСА С │ +│ ОБОРОТОМ $1,000,000/ГОД │ +├─────────────────────────────────────────────┤ +│ Банковские комиссии: -$25,750 │ +│ Корпоративное управление: -$42,000 │ +│ Привлечение инвестиций: -$49,400 │ +│ ──────────────────────────────────────── │ +│ ИТОГО ЭКОНОМИЯ: $117,150/год │ +│ │ +│ + Дополнительная прибыль от скорости: │ +│ ~$1,000,000 (упущенные возможности) │ +│ │ +│ ИТОГО ЭФФЕКТ: $1,117,150 │ +├─────────────────────────────────────────────┤ +│ ROI: 1,117% на инвестиции в DLE │ +│ Окупаемость: < 1 месяца │ +└─────────────────────────────────────────────┘ +``` + +### Сравнение с конкурентами + +| Решение | Стоимость/год | Комиссии транзакций | Скорость | Прозрачность | +|---------|---------------|---------------------|----------|--------------| +| **Традиционный бизнес** | $54,000+ | 3-7% | 3-7 дней | ❌ Низкая | +| **SaaS решения** | $12,000-60,000 | 2-5% | 1-3 дня | ⚠️ Средняя | +| **DLE на блокчейне** | $1,200-3,000 | 0.01-0.5% | 30 сек | ✅ Полная | + +--- + +## Заключение + +### Почему блокчейн - это будущее бизнеса? + +Digital Legal Entity на блокчейне решает фундаментальные проблемы современного бизнеса: + +1. **🏦 Финансовая свобода** + - Операции без банков + - Мгновенные переводы по всему миру + - Минимальные комиссии (99% экономии) + - Нет географических ограничений + +2. **🔑 Универсальная идентичность** + - Один адрес смарт-контракта = все идентификаторы + - Замена ИНН, банковского счета, email, телефона + - Криптографическая защита от подделок + +3. **💰 Токенизация активов** + - Любой актив становится ликвидным + - Дробное владение (от $1) + - Глобальный рынок 24/7 + - Автоматические доходы + +4. **🗳️ Прозрачное управление** + - Каждый акционер видит всё + - Невозможно скрыть решения + - Автоматическое исполнение + - Защита от коррупции + +5. **⚡ Автоматизация** + - Смарт-контракты вместо юристов + - Автоматические выплаты + - Исключение человеческих ошибок + - 90-99% экономии времени и денег + +### Экономическая выгода + +Для бизнеса с оборотом $1M/год: +- 💰 **Экономия: $117,000/год** (на комиссиях и управлении) +- ⚡ **Дополнительная прибыль: ~$1,000,000** (за счет скорости) +- 📈 **ROI: 1,117%** на внедрение DLE +- 🎯 **Окупаемость: < 1 месяца** + +### Начните сейчас! + +1. 📖 **[Изучите FAQ](./FAQ.md)** - ответы на популярные вопросы +2. 🚀 **[Установите DLE](./setup-instruction.md)** - пошаговая инструкция +3. 🔗 **[Настройте блокчейн](./blockchain-integration-technical.md)** - техническая документация +4. 💬 **[Получите поддержку](https://hb3-accelerator.com/)** - мы поможем! + +--- + +## Дополнительные ресурсы + +### Документация +- 📋 [FAQ](./FAQ.md) +- 🔧 [Установка](./setup-instruction.md) +- 🔗 [Техническая документация по блокчейну](./blockchain-integration-technical.md) +- 📝 [Условия обслуживания](./service-terms.md) + +### Обучение +- 🎓 **Онлайн-сессии** (групповые и индивидуальные) +- 📚 **Библиотека записей**: https://hb3-accelerator.com/training-library +- 🗳️ **Портал голосования**: https://hb3-accelerator.com/governance + +### Поддержка +- 💬 **Чат с поддержкой**: https://hb3-accelerator.com/ +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + diff --git a/docs/blockchain-integration-technical.md b/docs/blockchain-integration-technical.md new file mode 100644 index 0000000..d8beee3 --- /dev/null +++ b/docs/blockchain-integration-technical.md @@ -0,0 +1,1218 @@ +# Блокчейн интеграция Digital Legal Entity (DLE) + +## 📋 Содержание + +1. [Введение](#введение) +2. [Архитектура смарт-контрактов](#архитектура-смарт-контрактов) +3. [Основной контракт DLE](#основной-контракт-dle) +4. [Модульная система](#модульная-система) +5. [Мультичейн архитектура](#мультичейн-архитектура) +6. [Система голосования (Управление)](#система-голосования-управление) +7. [Деплой смарт-контрактов](#деплой-смарт-контрактов) +8. [Аутентификация через кошелек](#аутентификация-через-кошелек) +9. [Интеграция с frontend](#интеграция-с-frontend) +10. [Безопасность](#безопасность) +11. [Практические примеры](#практические-примеры) + +--- + +## Введение + +Digital Legal Entity (DLE) использует блокчейн-технологии для обеспечения **токенизированного управления** (аналогично акционерному обществу на блокчейне) и **прозрачного принятия решений** через смарт-контракты. + +### Зачем блокчейн в DLE? + +1. **🗳️ Управление как в акционерном обществе** - решения принимаются токен-холдерами через голосование на блокчейне +2. **🔒 Прозрачность** - все голосования и операции записаны на блокчейне +3. **🛡️ Защита от цензуры** - смарт-контракт гарантирует права токен-холдеров +4. **📜 Иммутабельность** - история решений неизменна +5. **🌐 Мультичейн поддержка** - работа в нескольких блокчейнах одновременно + +### Модель управления DLE + +DLE использует **гибридную модель управления**: + +| Аспект | Реализация | +|--------|------------| +| **Голосование** | Токен-холдеры (как акционеры) | +| **Кворум** | 51%+ токенов для принятия решений | +| **Распределение активов** | Через голосование (как в АО) | +| **Изменение параметров** | Через голосование токен-холдеров | +| **Код приложения** | Проприетарный (автор) | +| **Обновления** | Автор разрабатывает, токен-холдеры голосуют за приоритеты | + +Это **токенизированное акционерное общество на блокчейне**, где: +- ✅ Управление параметрами - через голосование токен-холдеров (как акционеров) +- ✅ Распределение активов - через голосование (как в АО) +- ⚠️ Разработка кода - централизована (автор) +- ⚠️ Выпуск обновлений - автор (по приоритетам голосования) + +### Поддерживаемые блокчейны + +DLE работает с любыми **EVM-совместимыми** сетями: +- ✅ Ethereum (mainnet & testnets: Sepolia, Holesky) +- ✅ Polygon (mainnet & testnets) +- ✅ Arbitrum (One & Sepolia) +- ✅ Binance Smart Chain (BSC) +- ✅ Base (mainnet & Sepolia) +- ✅ И любые другие EVM-сети + +--- + +## Архитектура смарт-контрактов + +### Обзор системы + +``` +┌─────────────────────────────────────────────────────────────┐ +│ DLE Ecosystem │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ DLE Core Contract (ERC20Votes) │ │ +│ │ • Токены управления (ERC20) │ │ +│ │ • Голосование (ERC20Votes) │ │ +│ │ • Подписи (ERC20Permit) │ │ +│ │ • Proposals (предложения) │ │ +│ │ • Мультичейн поддержка │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ ↕ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ Модули (Расширения) │ │ +│ ├──────────────────────────────────────────────────────┤ │ +│ │ • HierarchicalVotingModule │ │ +│ │ - Голосование в других DLE │ │ +│ │ - Владение токенами других DLE │ │ +│ │ │ │ +│ │ • TreasuryModule │ │ +│ │ - Управление казной │ │ +│ │ - Хранение токенов │ │ +│ │ │ │ +│ │ • TimelockModule │ │ +│ │ - Отложенное исполнение │ │ +│ │ - Защита от мгновенных изменений │ │ +│ └──────────────────────────────────────────────────────┘ │ +│ ↕ │ +│ ┌──────────────────────────────────────────────────────┐ │ +│ │ DLEReader (Читатель данных) │ │ +│ │ • Batch чтение данных │ │ +│ │ • Оптимизация RPC запросов │ │ +│ └──────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Стандарты и библиотеки + +DLE использует проверенные стандарты **OpenZeppelin**: + +| Стандарт | Назначение | +|----------|------------| +| **ERC20** | Базовый функционал токена | +| **ERC20Votes** | Голосование с снапшотами | +| **ERC20Permit** | Подписи без gas (meta-transactions) | +| **ReentrancyGuard** | Защита от реентерабельности | +| **ECDSA** | Проверка подписей | + +--- + +## Основной контракт DLE + +### Структура контракта + +Файл: `backend/contracts/DLE.sol` + +```solidity +contract DLE is ERC20, ERC20Permit, ERC20Votes, ReentrancyGuard, IMultichainMetadata { + // Основные данные DLE + struct DLEInfo { + string name; // Название организации + string symbol; // Символ токена + string location; // Местоположение + string coordinates; // Координаты GPS + uint256 jurisdiction; // Юрисдикция + string[] okvedCodes; // Коды ОКВЭД + uint256 kpp; // КПП (для РФ) + uint256 creationTimestamp; + bool isActive; + } + + // Предложение для голосования + struct Proposal { + uint256 id; + string description; + uint256 forVotes; // Голоса "За" + uint256 againstVotes; // Голоса "Против" + bool executed; + bool canceled; + uint256 deadline; + address initiator; + bytes operation; // Операция для исполнения + uint256 governanceChainId; // Сеть голосования + uint256[] targetChains; // Целевые сети для исполнения + uint256 snapshotTimepoint; + mapping(address => bool) hasVoted; + } +} +``` + +### Ключевые возможности + +#### 1. Токены управления (ERC20) + +DLE токены представляют **право голоса** в управлении: +- 1 токен = 1 голос +- Токены **НЕ передаются** обычными методами (только через governance) +- Подписи EIP-712 для meta-transactions + +```solidity +// Переводы токенов ЗАБЛОКИРОВАНЫ +function transfer(address, uint256) public pure override returns (bool) { + revert ErrTransfersDisabled(); +} + +// Одобрения ЗАБЛОКИРОВАНЫ +function approve(address, uint256) public pure override returns (bool) { + revert ErrApprovalsDisabled(); +} +``` + +#### 2. Голосование (ERC20Votes) + +Использует **снапшоты** голосов: +- Защита от flash-loans +- Голоса берутся из прошлого блока +- Делегирование (опционально) + +```solidity +function getPastVotes(address account, uint256 timepoint) public view returns (uint256) +``` + +#### 3. Мультичейн поддержка + +DLE может быть развернут в **нескольких сетях одновременно**: +- Один адрес во всех сетях (детерминированный деплой) +- Голосование в одной сети (governance chain) +- Исполнение в любых целевых сетях + +```solidity +// Поддерживаемые сети +mapping(uint256 => bool) public supportedChains; +uint256[] public supportedChainIds; + +// Добавление сети (только через голосование) +function _addSupportedChain(uint256 _chainId) internal { + require(!supportedChains[_chainId], "Chain already supported"); + supportedChains[_chainId] = true; + supportedChainIds.push(_chainId); + emit ChainAdded(_chainId); +} +``` + +#### 4. Модульная архитектура + +DLE поддерживает **расширения через модули**: + +```solidity +// Модули +mapping(bytes32 => address) public modules; +mapping(bytes32 => bool) public activeModules; + +// Добавление модуля (только через голосование) +function _addModule(bytes32 _moduleId, address _moduleAddress) internal { + if (_moduleAddress == address(0)) revert ErrZeroAddress(); + if (activeModules[_moduleId]) revert ErrProposalExecuted(); + + modules[_moduleId] = _moduleAddress; + activeModules[_moduleId] = true; + + emit ModuleAdded(_moduleId, _moduleAddress); +} +``` + +### Операции доступные через голосование + +| Операция | Описание | +|----------|----------| +| `_addModule` | Добавить новый модуль | +| `_removeModule` | Удалить модуль | +| `_addSupportedChain` | Добавить блокчейн | +| `_removeSupportedChain` | Удалить блокчейн | +| `_transferTokens` | Перевести токены | +| `_updateDLEInfo` | Обновить информацию DLE | +| `_updateQuorumPercentage` | Изменить кворум | +| `_updateVotingDurations` | Изменить длительность голосования | + +--- + +## Модульная система + +### 1. HierarchicalVotingModule + +**Назначение**: Иерархическое голосование - DLE может голосовать в других DLE. + +**Файл**: `backend/contracts/HierarchicalVotingModule.sol` + +**Возможности**: +- ✅ DLE может владеть токенами других DLE +- ✅ Голосовать в других DLE от своего имени +- ✅ Создавать предложения в других DLE +- ✅ Отслеживать цепочку голосований + +```solidity +struct ExternalDLEInfo { + address dleAddress; + string name; + string symbol; + uint256 tokenBalance; // Баланс токенов этого DLE + bool isActive; + uint256 addedAt; +} + +// Добавить внешний DLE +function addExternalDLE( + address dleAddress, + string memory name, + string memory symbol +) external onlyDLE; + +// Создать предложение в внешнем DLE +function createProposalInExternalDLE( + address externalDLE, + string calldata description, + uint256 duration, + bytes calldata operation, + uint256 chainId +) external onlyDLE returns (uint256); +``` + +**Пример использования**: +```javascript +// DLE-A владеет токенами DLE-B +// DLE-A может голосовать в DLE-B автоматически +const hierarchicalModule = await ethers.getContractAt('HierarchicalVotingModule', moduleAddress); +await hierarchicalModule.voteInExternalDLE(dleBAddress, proposalId, true); +``` + +### 2. TreasuryModule + +**Назначение**: Управление казной (treasury) и активами DLE. + +**Файл**: `backend/contracts/TreasuryModule.sol` + +**Возможности**: +- ✅ Хранение токенов и активов +- ✅ Управление через голосование токен-холдеров +- ✅ Отправка платежей +- ✅ Аккумуляция доходов + +```solidity +// Перевести токены из казны (только через голосование в DLE) +function transferTokens( + address token, + address recipient, + uint256 amount +) external onlyDLE; + +// Получить баланс токена в казне +function getTokenBalance(address token) external view returns (uint256); +``` + +**Пример использования**: +```javascript +// Создать предложение на выплату из казны +const operation = treasuryModule.interface.encodeFunctionData('transferTokens', [ + tokenAddress, + recipientAddress, + ethers.parseEther('100') +]); + +await dleContract.createProposal( + 'Выплата 100 токенов для маркетинга', + 86400, // 24 часа + operation, + chainId, + [chainId] +); +``` + +### 3. TimelockModule + +**Назначение**: Отложенное исполнение операций для безопасности. + +**Файл**: `backend/contracts/TimelockModule.sol` + +**Возможности**: +- ✅ Задержка перед исполнением (timelock) +- ✅ Возможность отмены до исполнения +- ✅ Защита от мгновенных изменений + +```solidity +struct TimelockProposal { + uint256 proposalId; + uint256 executionTime; // Время когда можно исполнить + bytes32 operationHash; + bool executed; + bool canceled; +} + +// Создать timelock предложение +function scheduleProposal( + uint256 proposalId, + bytes calldata operation, + uint256 delay +) external onlyDLE returns (bytes32); + +// Исполнить по истечении таймлока +function executeTimelockProposal(bytes32 operationHash) external; +``` + +### 4. DLEReader + +**Назначение**: Оптимизированное чтение данных из контрактов. + +**Файл**: `backend/contracts/DLEReader.sol` + +**Возможности**: +- ✅ Batch чтение нескольких данных за один RPC запрос +- ✅ Получение детальной информации о DLE +- ✅ Список всех предложений с деталями +- ✅ Оптимизация gas для чтения + +```solidity +// Получить полную информацию о DLE за один запрос +function getDLEFullInfo(address dleAddress) external view returns ( + string memory name, + string memory symbol, + uint256 totalSupply, + DLEInfo memory info, + uint256 proposalCount, + // ... и другие данные +); + +// Получить все предложения (batch read) +function getAllProposals(address dleAddress) external view returns (ProposalInfo[] memory); +``` + +--- + +## Мультичейн архитектура + +### Концепция + +DLE поддерживает **детерминированный деплой** - один адрес во всех сетях: + +``` +Ethereum: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +Polygon: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C ← Тот же адрес! +Arbitrum: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +BSC: 0x742d35Cc6634C0532925a3b844Bc9377F91cAB6C +``` + +### Как это работает? + +1. **Генерация init code** - одинаковый bytecode для всех сетей +2. **Фиксированный nonce** - деплой с одного и того же nonce +3. **CREATE opcode** - адрес = keccak256(deployerAddress, nonce) +4. **Результат** - одинаковый адрес во всех сетях + +### Голосование в одной сети + +**Голосование** происходит в **одной сети** (сеть голосования), а **исполнение** - в любых целевых сетях: + +``` +┌─────────────────────────────────────────────────────────┐ +│ Ethereum (Сеть голосования) │ +│ 1. Создание предложения │ +│ 2. Голосование │ +│ 3. Подсчет голосов │ +│ 4. Генерация подписи для исполнения │ +└─────────────────────────────────────────────────────────┘ + ↓ + ┌───────────────┴───────────────┐ + ↓ ↓ +┌───────────────────┐ ┌───────────────────┐ +│ Polygon │ │ Arbitrum │ +│ (Target Chain) │ │ (Target Chain) │ +│ 5. Исполнение │ │ 5. Исполнение │ +│ с подписью │ │ с подписью │ +└───────────────────┘ └───────────────────┘ +``` + +### Мультичейн исполнение + +Исполнение через **подписи** (off-chain coordination): + +```solidity +function executeWithSignatures( + uint256 proposalId, + bytes32 operationHash, + address[] calldata signers, + bytes[] calldata signatures +) external nonReentrant; +``` + +**Процесс**: +1. Предложение одобрено в сети голосования +2. Генерируются подписи токен-холдеров +3. Подписи передаются в целевые сети +4. Контракт проверяет подписи и исполняет операцию + +--- + +## Система голосования (Управление) + +### Создание предложения + +```solidity +function createProposal( + string calldata _description, + uint256 _duration, + bytes calldata _operation, + uint256 _chainId, + uint256[] calldata _targetChains, + address _initiator +) external returns (uint256); +``` + +**Параметры**: +- `_description` - описание предложения +- `_duration` - длительность голосования (в секундах) +- `_operation` - операция для исполнения (encoded function call) +- `_chainId` - ID сети для голосования +- `_targetChains` - целевые сети для исполнения +- `_initiator` - адрес инициатора + +**Пример** (backend): +```javascript +const { ethers } = require('ethers'); + +// Операция: добавить модуль +const operation = dleContract.interface.encodeFunctionData('_addModule', [ + ethers.id('TIMELOCK_MODULE'), // moduleId + timelockModuleAddress +]); + +// Создать предложение +const tx = await dleContract.createProposal( + 'Добавить Timelock Module для защиты', + 86400 * 3, // 3 дня + operation, + 1, // Ethereum mainnet + [1, 137, 42161], // Ethereum, Polygon, Arbitrum + walletAddress +); + +const receipt = await tx.wait(); +const proposalId = receipt.events[0].args.proposalId; +``` + +### Голосование + +```solidity +function vote(uint256 _proposalId, bool _support) external; +``` + +**Параметры**: +- `_proposalId` - ID предложения +- `_support` - true = "За", false = "Против" + +**Пример** (frontend): +```javascript +// Подключение к контракту +const dleContract = new ethers.Contract(dleAddress, dleAbi, signer); + +// Голосование "За" +await dleContract.vote(proposalId, true); + +// Голосование "Против" +await dleContract.vote(proposalId, false); +``` + +### Исполнение предложения + +```solidity +function execute(uint256 _proposalId) external nonReentrant; +``` + +**Условия исполнения**: +1. ✅ Голосование завершено (прошел deadline) +2. ✅ Кворум достигнут (например, 10% токенов проголосовало) +3. ✅ Больше голосов "За", чем "Против" +4. ✅ Предложение еще не исполнено + +**Пример**: +```javascript +// Проверить, можно ли исполнить +const proposal = await dleContract.proposals(proposalId); +const canExecute = ( + proposal.deadline < Date.now() / 1000 && + !proposal.executed && + proposal.forVotes > proposal.againstVotes +); + +if (canExecute) { + await dleContract.execute(proposalId); +} +``` + +### Кворум + +Кворум определяет **минимальное количество голосов** для принятия решения: + +```solidity +uint256 public quorumPercentage; // Процент от totalSupply (например, 10%) + +function _hasQuorum(uint256 _forVotes, uint256 _againstVotes) internal view returns (bool) { + uint256 totalVotes = _forVotes + _againstVotes; + uint256 requiredVotes = (totalSupply() * quorumPercentage) / 100; + return totalVotes >= requiredVotes; +} +``` + +**Изменение кворума** (только через голосование): +```javascript +const operation = dleContract.interface.encodeFunctionData('_updateQuorumPercentage', [ + 15 // Новый кворум 15% +]); + +await dleContract.createProposal( + 'Увеличить кворум до 15%', + 86400 * 7, + operation, + chainId, + [chainId] +); +``` + +--- + +## Деплой смарт-контрактов + +### Мультичейн деплой + +**Скрипт**: `backend/scripts/deploy/deploy-multichain.js` + +**Возможности**: +- ✅ Деплой в несколько сетей одновременно (parallel) +- ✅ Детерминированный адрес (один адрес во всех сетях) +- ✅ Автоматическая верификация контрактов +- ✅ Retry логика при ошибках +- ✅ Nonce management для синхронизации + +**Запуск**: +```bash +cd backend +yarn deploy:multichain +``` + +**Конфигурация** (база данных): +Параметры деплоя хранятся в таблице `settings`: +- `supported_chain_ids` - список ID сетей для деплоя +- `rpc_providers` - RPC URLs для каждой сети +- `dle_config` - конфигурация DLE (название, символ, партнеры и т.д.) + +**Пример конфигурации**: +```json +{ + "name": "My Company DLE", + "symbol": "MYCO", + "location": "Moscow, Russia", + "coordinates": "55.7558,37.6173", + "jurisdiction": 643, + "okvedCodes": ["62.01", "62.02"], + "kpp": 770401001, + "quorumPercentage": 10, + "initialPartners": ["0x742d35..."], + "initialAmounts": [1000000], + "supportedChainIds": [1, 137, 42161] +} +``` + +### Деплой модулей + +**Скрипт**: `backend/scripts/deploy/deploy-modules.js` + +**Запуск**: +```bash +cd backend +yarn deploy:modules +``` + +**Процесс**: +1. Загрузка адреса DLE из базы +2. Параллельный деплой всех модулей во всех сетях +3. CREATE2 деплой для детерминированных адресов +4. Автоматическая верификация +5. Сохранение адресов модулей в базу данных + +### Верификация контрактов + +**Автоматическая верификация** через Etherscan API: + +```javascript +async function verifyDLEAfterDeploy(chainId, contractAddress, constructorArgs, apiKey, params) { + await hre.run("verify:verify", { + address: contractAddress, + constructorArguments: constructorArgs, + contract: "contracts/DLE.sol:DLE" + }); +} +``` + +**Поддерживаемые сканеры**: +- Etherscan (Ethereum, Sepolia, Holesky) +- Polygonscan +- Arbiscan +- BSCScan +- Basescan + +--- + +## Аутентификация через кошелек + +### SIWE (Sign-In with Ethereum) + +DLE использует стандарт **SIWE** для аутентификации: + +**Файл**: `backend/routes/auth.js` + +**Процесс аутентификации**: + +``` +┌──────────────┐ ┌──────────────┐ +│ Frontend │ │ Backend │ +└──────┬───────┘ └──────┬───────┘ + │ │ + │ 1. Запрос nonce │ + ├──────────────────────────────────>│ + │ │ + │ 2. Возврат nonce │ + │<──────────────────────────────────┤ + │ │ + │ 3. Подпись сообщения в кошельке │ + │ (приватный ключ НЕ передается!) │ + │ │ + │ 4. Отправка подписи │ + ├──────────────────────────────────>│ + │ │ + │ 5. Проверка подписи + │ 6. Проверка токенов + │ 7. Создание сессии + │ │ + │ 8. Успешная аутентификация │ + │<──────────────────────────────────┤ + │ │ +``` + +### Запрос nonce + +```javascript +// POST /api/auth/nonce +app.post('/api/auth/nonce', async (req, res) => { + const { address } = req.body; + + // Генерируем случайный nonce + const nonce = crypto.randomBytes(32).toString('hex'); + + // Сохраняем в БД с шифрованием + await db.query( + 'INSERT INTO nonces (identity_value_encrypted, nonce_encrypted, expires_at) VALUES ($1, $2, $3)', + [encrypt(address.toLowerCase()), encrypt(nonce), expiresAt] + ); + + res.json({ nonce }); +}); +``` + +### Верификация подписи + +```javascript +// POST /api/auth/verify +app.post('/api/auth/verify', async (req, res) => { + const { address, signature, nonce } = req.body; + + // Формируем SIWE сообщение + const message = new SiweMessage({ + domain: req.get('host'), + address: ethers.getAddress(address), + statement: 'Sign in with Ethereum to the app.', + uri: req.get('origin'), + version: '1', + chainId: 1, + nonce: nonce + }); + + // Проверяем подпись + const isValid = await verifySignature( + message.prepareMessage(), + signature, + address + ); + + if (!isValid) { + return res.status(401).json({ error: 'Invalid signature' }); + } + + // Проверяем токены в смарт-контракте + const userAccessLevel = await getUserAccessLevel(address); + + // Создаем сессию + req.session.userId = userId; + req.session.address = address; + req.session.authenticated = true; + req.session.userAccessLevel = userAccessLevel; + + res.json({ success: true, userAccessLevel }); +}); +``` + +### Проверка уровня доступа + +```javascript +async function getUserAccessLevel(address) { + // Получаем адрес DLE контракта из настроек + const dleAddress = await getSettingValue('contract_address'); + if (!dleAddress) { + return { level: 'user', tokenCount: 0, hasAccess: false }; + } + + // Подключаемся к контракту + const dleContract = new ethers.Contract(dleAddress, dleAbi, provider); + + // Получаем баланс токенов + const tokenCount = await dleContract.balanceOf(address); + + // Пороги доступа из настроек + const editorThreshold = await getSettingValue('editor_token_threshold') || 100; + const readonlyThreshold = await getSettingValue('readonly_token_threshold') || 1; + + // Определяем уровень доступа + if (tokenCount >= editorThreshold) { + return { level: 'editor', tokenCount, hasAccess: true }; + } else if (tokenCount >= readonlyThreshold) { + return { level: 'readonly', tokenCount, hasAccess: true }; + } else { + return { level: 'user', tokenCount: 0, hasAccess: false }; + } +} +``` + +--- + +## Интеграция с frontend + +### Подключение кошелька + +**Файл**: `frontend/src/services/web3Service.js` + +```javascript +import { ethers } from 'ethers'; + +export async function connectWallet() { + if (!window.ethereum) { + throw new Error('MetaMask не установлен'); + } + + // Запрашиваем доступ к кошельку + await window.ethereum.request({ method: 'eth_requestAccounts' }); + + // Создаем provider + const provider = new ethers.BrowserProvider(window.ethereum); + const signer = await provider.getSigner(); + const address = await signer.getAddress(); + + return { provider, signer, address }; +} +``` + +### Подпись сообщения + +```javascript +export async function signMessage(signer, message) { + try { + const signature = await signer.signMessage(message); + return signature; + } catch (error) { + throw new Error('Пользователь отклонил подпись'); + } +} +``` + +### Аутентификация + +```javascript +import axios from 'axios'; + +export async function authenticateWithWallet(address, signer) { + // 1. Получаем nonce + const { data } = await axios.post('/api/auth/nonce', { address }); + const { nonce } = data; + + // 2. Формируем сообщение SIWE + const message = `Sign in with Ethereum to the app.\n\nNonce: ${nonce}`; + + // 3. Подписываем + const signature = await signMessage(signer, message); + + // 4. Отправляем на верификацию + const response = await axios.post('/api/auth/verify', { + address, + signature, + nonce, + issuedAt: new Date().toISOString() + }); + + return response.data; +} +``` + +### Взаимодействие с контрактом + +```javascript +import { ethers } from 'ethers'; +import dleAbi from '@/contracts/DLE.json'; + +export async function getDLEContract(address, signerOrProvider) { + return new ethers.Contract(address, dleAbi.abi, signerOrProvider); +} + +// Создать предложение +export async function createProposal(contract, description, duration, operation, chainId) { + const tx = await contract.createProposal( + description, + duration, + operation, + chainId, + [chainId] + ); + + const receipt = await tx.wait(); + return receipt; +} + +// Голосовать +export async function voteOnProposal(contract, proposalId, support) { + const tx = await contract.vote(proposalId, support); + await tx.wait(); +} + +// Получить информацию о предложении +export async function getProposal(contract, proposalId) { + const proposal = await contract.proposals(proposalId); + return { + id: proposal.id.toString(), + description: proposal.description, + forVotes: ethers.formatEther(proposal.forVotes), + againstVotes: ethers.formatEther(proposal.againstVotes), + executed: proposal.executed, + deadline: new Date(proposal.deadline * 1000) + }; +} +``` + +### Vue компонент для голосования + +```vue + + + + + +``` + +--- + +## Безопасность + +### 1. Защита от реентерабельности + +```solidity +import "@openzeppelin/contracts/utils/ReentrancyGuard.sol"; + +contract DLE is ReentrancyGuard { + function execute(uint256 _proposalId) external nonReentrant { + // Операция защищена от реентерабельности + } +} +``` + +### 2. Блокировка переводов токенов + +Токены управления **НЕ могут быть переведены** обычными способами: + +```solidity +error ErrTransfersDisabled(); +error ErrApprovalsDisabled(); + +function transfer(address, uint256) public pure override returns (bool) { + revert ErrTransfersDisabled(); +} + +function approve(address, uint256) public pure override returns (bool) { + revert ErrApprovalsDisabled(); +} +``` + +Передача возможна **только через голосование**: +```solidity +function _transferTokens(address _recipient, uint256 _amount) internal { + _transfer(address(this), _recipient, _amount); +} +``` + +### 3. Снапшоты голосов + +Используются **прошлые значения** для предотвращения flash-loans: + +```solidity +uint256 public snapshotTimepoint = block.number - 1; + +function vote(uint256 _proposalId, bool _support) external { + uint256 votingPower = getPastVotes(msg.sender, snapshotTimepoint); + require(votingPower > 0, "No voting power"); + // ... +} +``` + +### 4. EIP-712 подписи + +Поддержка **структурированных подписей** для контрактных кошельков: + +```solidity +bytes32 private constant EXECUTION_APPROVAL_TYPEHASH = keccak256( + "ExecutionApproval(uint256 proposalId,bytes32 operationHash,uint256 chainId,uint256 snapshotTimepoint)" +); + +function executeWithSignatures( + uint256 proposalId, + bytes32 operationHash, + address[] calldata signers, + bytes[] calldata signatures +) external nonReentrant { + // Проверка EIP-712 подписей + // Поддержка EIP-1271 для контрактных кошельков +} +``` + +### 5. Валидация параметров + +Все параметры проверяются перед использованием: + +```solidity +if (_moduleAddress == address(0)) revert ErrZeroAddress(); +if (balanceOf(msg.sender) == 0) revert ErrNotHolder(); +if (_duration < minVotingDuration) revert ErrTooShort(); +if (_duration > maxVotingDuration) revert ErrTooLong(); +if (!supportedChains[_chainId]) revert ErrUnsupportedChain(); +``` + +### 6. Custom errors + +Использование **custom errors** вместо `require` для экономии gas: + +```solidity +error ErrZeroAddress(); +error ErrNotHolder(); +error ErrAlreadyVoted(); +// ... и другие +``` + +--- + +## Практические примеры + +### Пример 1: Создание DLE и деплой в несколько сетей + +```bash +# 1. Настройка параметров в базе данных +# Через веб-интерфейс: Настройки → Блокчейн + +# 2. Запуск мультичейн деплоя +cd backend +yarn deploy:multichain + +# 3. Результат: DLE развернут в Ethereum, Polygon и Arbitrum с одним адресом +``` + +### Пример 2: Добавление Timelock Module + +```javascript +// 1. Деплой модулей +yarn deploy:modules + +// 2. Создание предложения на добавление модуля +const dleContract = new ethers.Contract(dleAddress, dleAbi, signer); + +const operation = dleContract.interface.encodeFunctionData('_addModule', [ + ethers.id('TIMELOCK_MODULE'), + timelockModuleAddress +]); + +const tx = await dleContract.createProposal( + 'Добавить Timelock Module для защиты от мгновенных изменений', + 86400 * 7, // 7 дней голосования + operation, + 1, // Ethereum mainnet + [1, 137, 42161] // Исполнить во всех сетях +); + +await tx.wait(); +console.log('Предложение создано!'); + +// 3. Голосование токен-холдеров +await dleContract.vote(proposalId, true); // "За" + +// 4. Исполнение после окончания голосования +await dleContract.execute(proposalId); + +console.log('Timelock Module добавлен!'); +``` + +### Пример 3: Создание иерархического голосования + +```javascript +// DLE-A будет голосовать в DLE-B +const dleA = new ethers.Contract(dleAAddress, dleAbi, signer); +const hierarchicalModule = new ethers.Contract( + hierarchicalModuleAddress, + hierarchicalModuleAbi, + signer +); + +// 1. Добавить внешний DLE (DLE-B) в DLE-A +const operation1 = hierarchicalModule.interface.encodeFunctionData('addExternalDLE', [ + dleBAddress, + 'Company B DLE', + 'COMPB' +]); + +await dleA.createProposal( + 'Добавить DLE-B для участия в их голосованиях', + 86400 * 3, + operation1, + chainId, + [chainId] +); + +// 2. После одобрения, создать предложение в DLE-B от имени DLE-A +const operation2 = hierarchicalModule.interface.encodeFunctionData( + 'createProposalInExternalDLE', + [ + dleBAddress, + 'Предложение от DLE-A', + 86400, + operationBytes, + chainId + ] +); + +await dleA.createProposal( + 'Создать предложение в DLE-B', + 86400 * 3, + operation2, + chainId, + [chainId] +); + +console.log('Иерархическое голосование настроено!'); +``` + +### Пример 4: Управление Treasury + +```javascript +const dleContract = new ethers.Contract(dleAddress, dleAbi, signer); +const treasuryModule = new ethers.Contract( + treasuryModuleAddress, + treasuryModuleAbi, + signer +); + +// Перевести 1000 USDC из казны на маркетинг +const operation = treasuryModule.interface.encodeFunctionData('transferTokens', [ + usdcTokenAddress, + marketingWalletAddress, + ethers.parseUnits('1000', 6) // USDC has 6 decimals +]); + +await dleContract.createProposal( + 'Выделить 1000 USDC на маркетинговую кампанию Q1 2025', + 86400 * 14, // 14 дней голосования + operation, + chainId, + [chainId] +); + +console.log('Предложение на расход из казны создано!'); +``` + +--- + +## Заключение + +Блокчейн-интеграция в DLE обеспечивает: +- ✅ **Управление как в акционерном обществе** - токен-холдеры голосуют за решения +- ✅ **Прозрачность** всех решений на блокчейне +- ✅ **Мультичейн поддержка** для работы в нескольких сетях +- ✅ **Модульная архитектура** для расширения функциональности +- ✅ **Безопасность** через проверенные стандарты OpenZeppelin + +### Дополнительные ресурсы + +- 📖 [Основной README](../README.md) +- 📋 [FAQ](./FAQ.md) +- 🔧 [Инструкция по установке](./setup-instruction.md) +- 📝 [Условия обслуживания](./service-terms.md) +- ⚖️ [Юридическая документация](../legal/README.md) + +### Контакты и поддержка + +- 🌐 **Портал**: https://hb3-accelerator.com/ +- 📧 **Email**: info@hb3-accelerator.com +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..a95f034 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,1330 @@ +# Безопасность Digital Legal Entity (DLE) + +## 📋 Содержание + +1. [Введение](#введение) +2. [Модель безопасности](#модель-безопасности) +3. [Контроль доступа на основе токенов](#контроль-доступа-на-основе-токенов) +4. [Безопасность смарт-контрактов](#безопасность-смарт-контрактов) +5. [Защита от взлома кошельков](#защита-от-взлома-кошельков) +6. [Безопасность веб-приложения](#безопасность-веб-приложения) +7. [Управление модулями](#управление-модулями) +8. [Аудит и мониторинг](#аудит-и-мониторинг) +9. [Рекомендации по безопасности](#рекомендации-по-безопасности) +10. [Сценарии атак и защита](#сценарии-атак-и-защита) + +--- + +## Введение + +Digital Legal Entity (DLE) построен с фокусом на **безопасность на всех уровнях**: +- 🔐 Контроль доступа через блокчейн-токены +- 🛡️ Защита смарт-контрактов от взлома +- 🔒 Невозможность кражи токенов даже при взломе кошелька +- ⚖️ Управление только через голосование с кворумом + +### Ключевые принципы безопасности + +1. **Защита по умолчанию** - все действия запрещены, пока явно не разрешены +2. **Минимальные привилегии** - каждый получает только необходимые права +3. **Прозрачность** - все действия записаны на блокчейне +4. **Неизменяемость** - невозможно подделать историю +5. **Коллективный контроль** - критичные операции только через голосование + +--- + +## Модель безопасности + +### Архитектура безопасности + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Уровни защиты DLE │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ Уровень 1: Блокчейн (Неизменяемая база) │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ • Смарт-контракт DLE (проверен, иммутабельный) │ │ +│ │ • Токены управления (ERC20Votes) │ │ +│ │ • История всех операций на блокчейне │ │ +│ │ • Невозможность изменения правил без голосования │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ ↑ │ +│ Уровень 2: Веб-приложение (Backend) │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ • Проверка токенов в реальном времени │ │ +│ │ • Аутентификация через кошелек (SIWE) │ │ +│ │ • Шифрование данных (AES-256) │ │ +│ │ • Rate limiting и защита от DDoS │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ ↑ │ +│ Уровень 3: Frontend (Vue.js) │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ • Подключение к кошельку │ │ +│ │ • Подпись транзакций │ │ +│ │ • XSS защита (DOMPurify) │ │ +│ │ • CSRF токены │ │ +│ └───────────────────────────────────────────────────────┘ │ +│ ↑ │ +│ Уровень 4: Пользователь │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ • Приватный ключ кошелька (MetaMask, WalletConnect) │ │ +│ │ • Подтверждение каждой операции │ │ +│ └───────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Модель угроз + +| Угроза | Уровень риска | Защита | +|--------|---------------|--------| +| **Взлом кошелька** | 🟡 Средний | Токены нельзя перевести без голосования | +| **Взлом веб-приложения** | 🟢 Низкий | Все права проверяются на блокчейне, управление через блокчейн-сканеры | +| **Компрометация смарт-контракта** | 🟢 Низкий | Аудит, OpenZeppelin, иммутабельность | +| **DDoS атака** | 🟡 Средний | Rate limiting, CDN, резервные сервера | +| **Фишинг** | 🟠 Высокий | Обучение пользователей, проверка домена | +| **Insider threat** | 🟢 Низкий | Все действия через голосование | + +### ⚠️ Критически важно: Веб-приложение - это только интерфейс + +**Ключевая особенность архитектуры DLE:** + +``` +┌─────────────────────────────────────────────────────────┐ +│ Веб-приложение (интерфейс) │ +│ │ +│ Frontend + Backend = УДОБСТВО использования │ +│ • Красивый UI │ +│ • Удобная навигация │ +│ • Быстрый доступ к функциям │ +│ │ +│ ⚠️ Может быть взломано/недоступно │ +│ ✅ НО! Активы бизнеса защищены │ +└─────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────┐ +│ Блокчейн (реальная власть) │ +│ │ +│ Смарт-контракты = РЕАЛЬНОЕ управление активами │ +│ • Токены управления │ +│ • Казна с активами │ +│ • Правила голосования │ +│ • История всех решений │ +│ │ +│ 🔒 Защищено криптографией │ +│ ✅ Работает независимо от веб-приложения │ +└─────────────────────────────────────────────────────────┘ +``` + +**Что происходит при взломе веб-приложения:** + +``` +Веб-приложение взломано/недоступно: +├── ❌ Веб-интерфейс не работает +├── ❌ Backend может показывать неверную информацию +├── ❌ Frontend может быть подменен +│ +НО: +├── ✅ Все активы бизнеса остаются на блокчейне +├── ✅ Смарт-контракты продолжают работать +├── ✅ Токены невозможно украсть +├── ✅ Можно управлять через Etherscan/Polygonscan/др. +└── ✅ Можно создать новый frontend и подключить к тем же контрактам +``` + +**Реальный пример:** + +1. Злоумышленник взламывает ваш сервер с веб-приложением +2. Пытается показать поддельные балансы токенов +3. **Но**: Реальные балансы на блокчейне остаются неизменными +4. Вы открываете Etherscan и видите правду +5. Создаете предложение через Etherscan на восстановление +6. Голосуете и исполняете предложение +7. Восстанавливаете веб-приложение +8. **Результат**: Ни один токен не потерян ✅ + +--- + +## Контроль доступа на основе токенов + +### Принцип работы + +**Без токенов доступ к приложению НЕВОЗМОЖЕН.** + +``` +Попытка доступа к DLE: +├── 1. Пользователь подключает кошелек +├── 2. Backend проверяет баланс токенов в смарт-контракте +├── 3. Если токенов НЕТ → Доступ ЗАПРЕЩЕН +└── 4. Если токены ЕСТЬ → Доступ разрешен (уровень зависит от количества) +``` + +### Уровни доступа + +| Токенов на балансе | Уровень доступа | Права | +|-------------------|-----------------|-------| +| **0 токенов** | ❌ Нет доступа | Только страница "Нет доступа" | +| **1+ токенов** | ✅ ReadOnly | Просмотр данных | +| **100+ токенов** | ✅ Editor | Редактирование, создание | +| **Любое количество** | 🗳️ Голосование | 1 токен = 1 голос | + +### Проверка токенов в реальном времени + +**Backend** постоянно проверяет баланс токенов: + +```javascript +// Каждый запрос проверяет токены +async function checkAccess(req, res, next) { + const address = req.session.address; + + // Получаем баланс токенов из смарт-контракта + const dleContract = new ethers.Contract(dleAddress, dleAbi, provider); + const balance = await dleContract.balanceOf(address); + + if (balance === 0n) { + return res.status(403).json({ + error: 'Доступ запрещен: нет токенов' + }); + } + + // Определяем уровень доступа + const accessLevel = determineAccessLevel(balance); + req.user = { address, balance, accessLevel }; + + next(); +} +``` + +**Важно**: Проверка происходит на **каждом запросе**, поэтому: +- ✅ Если токены переведены → доступ мгновенно теряется +- ✅ Если токены получены → доступ мгновенно появляется +- ✅ Невозможно обойти проверку + +### Начальное распределение токенов + +**Токены распределяет владелец при деплое смарт-контракта:** + +```solidity +constructor(DLEConfig memory config) { + // Создаем токены + _mint(address(this), totalSupply); + + // Распределяем среди партнеров + for (uint i = 0; i < config.initialPartners.length; i++) { + _transfer( + address(this), + config.initialPartners[i], + config.initialAmounts[i] + ); + } +} +``` + +**Процесс**: +1. Владелец кошелька деплоит смарт-контракт DLE +2. Указывает адреса партнеров и количество токенов для каждого +3. Токены автоматически распределяются при деплое +4. После этого все изменения только через голосование + +**Пример распределения**: +```javascript +const config = { + initialPartners: [ + '0xAlice...', // Основатель 1 + '0xBob...', // Основатель 2 + '0xCarol...' // Инвестор + ], + initialAmounts: [ + 500000, // 50% для Alice + 300000, // 30% для Bob + 200000 // 20% для Carol + ] +}; +``` + +--- + +## Безопасность смарт-контрактов + +### Защита от переводов токенов + +**КРИТИЧНО**: Токены управления **НЕЛЬЗЯ** перевести обычными способами! + +```solidity +// Переводы ЗАБЛОКИРОВАНЫ +function transfer(address to, uint256 amount) + public + pure + override + returns (bool) +{ + revert ErrTransfersDisabled(); +} + +// Одобрения ЗАБЛОКИРОВАНЫ +function approve(address spender, uint256 amount) + public + pure + override + returns (bool) +{ + revert ErrApprovalsDisabled(); +} + +// TransferFrom ЗАБЛОКИРОВАН +function transferFrom(address from, address to, uint256 amount) + public + pure + override + returns (bool) +{ + revert ErrTransfersDisabled(); +} +``` + +**Что это означает**: +- ❌ Невозможно отправить токены на биржу +- ❌ Невозможно продать токены на DEX +- ❌ Невозможно передать токены другому лицу напрямую +- ❌ Злоумышленник НЕ может украсть токены даже со взломанного кошелька + +### Единственный способ перевода токенов + +**Только через голосование с кворумом:** + +```solidity +// Перевод токенов (только через голосование) +function _transferTokens(address recipient, uint256 amount) internal { + require(msg.sender == address(this), "Only through governance"); + _transfer(address(this), recipient, amount); +} +``` + +**Процесс перевода**: +``` +1. Создание предложения + ├── "Перевести 1000 токенов на адрес 0xNew..." + └── Требуется: минимум 1 токен для создания + +2. Голосование + ├── Длительность: 1-30 дней (настраивается) + ├── Каждый токен = 1 голос + └── Требуется: кворум (например, 10% от всех токенов) + +3. Проверка кворума + ├── Если "За" > "Против" И кворум достигнут + └── → Предложение одобрено + +4. Исполнение + ├── Смарт-контракт автоматически переводит токены + └── Событие записано на блокчейне навсегда +``` + +### Настройка кворума + +**Кворум устанавливается при деплое** и может быть изменен только через голосование: + +```solidity +uint256 public quorumPercentage; // Например, 10% + +function _hasQuorum(uint256 forVotes, uint256 againstVotes) + internal + view + returns (bool) +{ + uint256 totalVotes = forVotes + againstVotes; + uint256 required = (totalSupply() * quorumPercentage) / 100; + return totalVotes >= required; +} +``` + +**Примеры кворума**: +- 5% - легко достичь (для активных организаций) +- 10% - стандартный (рекомендуется) +- 20% - строгий (для критичных решений) +- 51% - абсолютное большинство + +### Защита от реентерабельности + +```solidity +import "@openzeppelin/contracts/utils/ReentrancyGuard.sol"; + +contract DLE is ReentrancyGuard { + function execute(uint256 proposalId) + external + nonReentrant // Защита от реентерабельности + { + // Исполнение предложения + } +} +``` + +### Защита от flash-loans + +**Снапшоты голосов** предотвращают атаки с временным займом токенов: + +```solidity +// Голоса берутся из ПРОШЛОГО блока +uint256 public snapshotTimepoint = block.number - 1; + +function vote(uint256 proposalId, bool support) external { + // Используем баланс из прошлого блока + uint256 votingPower = getPastVotes(msg.sender, snapshotTimepoint); + require(votingPower > 0, "No voting power"); + + // Голосование +} +``` + +**Почему это безопасно**: +1. Злоумышленник берет flash-loan на 1,000,000 токенов +2. Пытается проголосовать +3. Смарт-контракт проверяет баланс в **прошлом блоке** +4. В прошлом блоке у злоумышленника было 0 токенов +5. Голосование отклонено ❌ + +### Валидация всех параметров + +```solidity +// Проверка адресов +if (address == address(0)) revert ErrZeroAddress(); + +// Проверка наличия токенов +if (balanceOf(msg.sender) == 0) revert ErrNotHolder(); + +// Проверка длительности голосования +if (duration < minVotingDuration) revert ErrTooShort(); +if (duration > maxVotingDuration) revert ErrTooLong(); + +// Проверка поддерживаемых сетей +if (!supportedChains[chainId]) revert ErrUnsupportedChain(); +``` + +### Custom errors для экономии gas + +```solidity +// Экономия gas: custom errors вместо require +error ErrZeroAddress(); +error ErrNotHolder(); +error ErrAlreadyVoted(); +error ErrTransfersDisabled(); +error ErrApprovalsDisabled(); +error ErrProposalMissing(); +error ErrWrongChain(); +``` + +--- + +## Защита от взлома кошельков + +### Сценарий: Злоумышленник получил приватный ключ + +**Что может сделать злоумышленник:** + +``` +Попытки злоумышленника: + +1. ❌ Отправить токены на свой адрес + └── БЛОКИРОВАНО: transfer() заблокирован + +2. ❌ Продать токены на DEX (Uniswap, etc.) + └── БЛОКИРОВАНО: approve() заблокирован + +3. ❌ Отправить через transferFrom + └── БЛОКИРОВАНО: transferFrom() заблокирован + +4. ❓ Создать предложение "Перевести токены мне" + └── Требуется голосование других токен-холдеров + └── Кворум: 10%+ должны проголосовать "За" + └── СКОРЕЕ ВСЕГО ПРОВАЛИТСЯ +``` + +### Реальный пример атаки + +``` +Злоумышленник взломал кошелек Alice (500,000 токенов): + +1. Создает предложение: + "Перевести 500,000 токенов на адрес 0xEvil..." + +2. Голосует "За" своими 500,000 голосами (50%) + +3. Но кворум = 10% = 100,000 голосов + Уже достигнут? ДА ✅ + +4. "За" = 500,000 (50%) + "Против" = 0 + +5. Результат: Предложение ОДОБРЕНО ❌ + +ПРОБЛЕМА: Если у Alice большинство токенов! +``` + +### Защита от атаки с большинством токенов + +**Решение 1: Timelock Module** + +```solidity +// Отложенное исполнение (например, 3 дня) +uint256 public constant TIMELOCK_DELAY = 3 days; + +function scheduleProposal(uint256 proposalId) external { + // Предложение одобрено, но исполнится только через 3 дня + executionTime = block.timestamp + TIMELOCK_DELAY; +} +``` + +**Преимущество**: Другие токен-холдеры видят опасное предложение и могут: +- Проголосовать "Против" +- Создать контр-предложение +- Принять меры (например, обратиться в суд) + +**Решение 2: Мультиподпись** + +```solidity +// Требуется несколько подписей для критичных операций +mapping(uint256 => mapping(address => bool)) public approvals; + +function executeWithApprovals( + uint256 proposalId, + address[] calldata signers, + bytes[] calldata signatures +) external { + // Проверяем подписи нескольких токен-холдеров + require(signers.length >= minSigners, "Not enough signers"); + + for (uint i = 0; i < signers.length; i++) { + // Проверка подписи + verifySignature(proposalId, signers[i], signatures[i]); + } + + // Исполнение +} +``` + +**Решение 3: Холодный кошелек для крупных холдеров** + +Рекомендуется держать токены на: +- 🥶 **Hardware wallet** (Ledger, Trezor) - максимальная защита +- 🔒 **Мультиподпись** (Gnosis Safe) - требуется несколько подписей +- ❄️ **Холодное хранение** - offline, не подключен к интернету + +### Мониторинг подозрительных предложений + +**Backend автоматически детектирует опасные предложения:** + +```javascript +// Детектор подозрительных предложений +function detectSuspiciousProposal(proposal) { + const alerts = []; + + // Проверка 1: Перевод большого количества токенов + if (proposal.operation.includes('_transferTokens')) { + const amount = decodeAmount(proposal.operation); + const percentage = (amount / totalSupply) * 100; + + if (percentage > 10) { + alerts.push({ + level: 'HIGH', + message: `Предложение переводит ${percentage}% всех токенов!` + }); + } + } + + // Проверка 2: Инициатор голосует своими токенами + if (proposal.forVotes === proposal.initiatorBalance) { + alerts.push({ + level: 'MEDIUM', + message: 'Инициатор голосует только своими токенами' + }); + } + + // Проверка 3: Быстрое голосование (< 24 часов) + if (proposal.duration < 86400) { + alerts.push({ + level: 'MEDIUM', + message: 'Голосование менее 24 часов - мало времени на проверку' + }); + } + + // Отправляем уведомления всем токен-холдерам + if (alerts.length > 0) { + notifyAllTokenHolders(proposal, alerts); + } +} +``` + +--- + +## Безопасность веб-приложения + +### Аутентификация через SIWE + +**Sign-In with Ethereum** - стандарт безопасной аутентификации: + +```javascript +// Генерация nonce (одноразовый) +const nonce = crypto.randomBytes(32).toString('hex'); + +// Сохранение в БД с шифрованием +await db.query( + 'INSERT INTO nonces (address_encrypted, nonce_encrypted, expires_at) VALUES ($1, $2, $3)', + [encrypt(address), encrypt(nonce), expiresAt] +); + +// Проверка подписи +const message = new SiweMessage({ + domain: req.get('host'), + address: ethers.getAddress(address), + nonce: nonce, + chainId: 1 +}); + +const isValid = await verifySignature( + message.prepareMessage(), + signature, + address +); +``` + +**Безопасность**: +- ✅ Приватный ключ **никогда** не покидает кошелек +- ✅ Каждый nonce используется **один раз** +- ✅ Nonce истекает через 5 минут +- ✅ Подделать подпись невозможно без приватного ключа + +### Шифрование данных + +```javascript +// AES-256 шифрование +const crypto = require('crypto'); + +function encrypt(text, key) { + const iv = crypto.randomBytes(16); + const cipher = crypto.createCipheriv('aes-256-cbc', key, iv); + + let encrypted = cipher.update(text, 'utf8', 'hex'); + encrypted += cipher.final('hex'); + + return iv.toString('hex') + ':' + encrypted; +} + +function decrypt(encrypted, key) { + const parts = encrypted.split(':'); + const iv = Buffer.from(parts[0], 'hex'); + const encryptedText = parts[1]; + + const decipher = crypto.createDecipheriv('aes-256-cbc', key, iv); + let decrypted = decipher.update(encryptedText, 'hex', 'utf8'); + decrypted += decipher.final('utf8'); + + return decrypted; +} +``` + +**Что шифруется**: +- 🔐 Адреса кошельков в БД +- 🔐 Nonces для аутентификации +- 🔐 Сессионные данные +- 🔐 Приватные сообщения + +### Rate Limiting + +```javascript +const rateLimit = require('express-rate-limit'); + +// Ограничение запросов +const apiLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, // 15 минут + max: 100, // максимум 100 запросов + message: 'Слишком много запросов, попробуйте позже' +}); + +// Ограничение для аутентификации (более строгое) +const authLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, + max: 5, // максимум 5 попыток аутентификации + skipSuccessfulRequests: true +}); + +app.use('/api/', apiLimiter); +app.use('/api/auth/', authLimiter); +``` + +### CSRF защита + +```javascript +const csrf = require('csurf'); + +// CSRF токены для всех форм +const csrfProtection = csrf({ cookie: true }); + +app.post('/api/action', csrfProtection, async (req, res) => { + // Проверка CSRF токена автоматическая +}); +``` + +### XSS защита + +```javascript +import DOMPurify from 'dompurify'; + +// Очистка HTML от опасного кода +function sanitizeHTML(html) { + return DOMPurify.sanitize(html, { + ALLOWED_TAGS: ['b', 'i', 'em', 'strong', 'a', 'p'], + ALLOWED_ATTR: ['href'] + }); +} + +// Использование +const userInput = req.body.comment; +const safeHTML = sanitizeHTML(userInput); +``` + +### Helmet.js для защиты заголовков + +```javascript +const helmet = require('helmet'); + +app.use(helmet({ + contentSecurityPolicy: { + directives: { + defaultSrc: ["'self'"], + scriptSrc: ["'self'", "'unsafe-inline'"], + styleSrc: ["'self'", "'unsafe-inline'"], + imgSrc: ["'self'", "data:", "https:"], + } + }, + hsts: { + maxAge: 31536000, + includeSubDomains: true, + preload: true + } +})); +``` + +### Clean Logs система + +**Автоматическая очистка логов от чувствительных данных:** + +```javascript +function cleanLogs() { + const sensitivePatterns = [ + /0x[a-fA-F0-9]{40}/g, // Адреса кошельков + /pk_[a-zA-Z0-9]{64}/g, // Приватные ключи (если случайно залогированы) + /nonce:\s*[a-f0-9]{64}/gi, // Nonces + ]; + + // Замена чувствительных данных на *** + let cleanedLog = logContent; + sensitivePatterns.forEach(pattern => { + cleanedLog = cleanedLog.replace(pattern, '[REDACTED]'); + }); + + return cleanedLog; +} +``` + +--- + +## Управление модулями + +### Только смарт-контракт DLE управляет модулями + +**Модификатор `onlyDLE`** гарантирует, что только смарт-контракт DLE может вызывать функции модуля: + +```solidity +// Модуль: TreasuryModule +contract TreasuryModule { + address public immutable dleContract; + + modifier onlyDLE() { + require(msg.sender == dleContract, "Only DLE can call"); + _; + } + + // Только DLE может переводить токены из казны + function transferTokens( + address token, + address recipient, + uint256 amount + ) external onlyDLE { + IERC20(token).transfer(recipient, amount); + } +} +``` + +**Что это означает**: +- ❌ Владелец кошелька **НЕ может** напрямую вызвать функции модуля +- ❌ Backend **НЕ может** вызвать функции модуля +- ❌ Злоумышленник **НЕ может** взаимодействовать с модулем +- ✅ **Только** смарт-контракт DLE через голосование + +### Процесс использования модуля + +``` +1. Токен-холдер создает предложение + └── "Перевести 1000 USDC из Treasury на маркетинг" + +2. Предложение содержит закодированный вызов функции модуля + └── operation = treasuryModule.transferTokens(USDC, marketing, 1000) + +3. Голосование + +4. Если одобрено, DLE контракт вызывает модуль: + └── TreasuryModule.transferTokens() ✅ + └── msg.sender = DLE контракт ✅ + +5. Модуль проверяет msg.sender и исполняет +``` + +### Добавление нового модуля + +**Только через голосование:** + +```solidity +// Операция добавления модуля +function _addModule(bytes32 moduleId, address moduleAddress) internal { + require(msg.sender == address(this), "Only through voting"); + require(moduleAddress != address(0), "Invalid address"); + require(!activeModules[moduleId], "Module already exists"); + + modules[moduleId] = moduleAddress; + activeModules[moduleId] = true; + + emit ModuleAdded(moduleId, moduleAddress); +} +``` + +**Процесс**: +1. Деплой нового модуля +2. Создание предложения: "Добавить модуль X по адресу 0x..." +3. Голосование +4. Если одобрено → модуль добавлен +5. Модуль можно использовать + +### Удаление скомпрометированного модуля + +Если модуль оказался уязвимым: + +``` +1. Токен-холдер создает экстренное предложение + └── "Удалить скомпрометированный модуль X" + └── Длительность: 1 день (экстренное голосование) + +2. Голосование (ускоренное) + +3. Модуль удален + └── Больше нельзя вызвать из DLE контракта +``` + +--- + +## Аудит и мониторинг + +### Прозрачность на блокчейне + +**Все действия записаны навсегда:** + +```solidity +// События для аудита +event ProposalCreated(uint256 proposalId, address initiator); +event ProposalVoted(uint256 proposalId, address voter, bool support); +event ProposalExecuted(uint256 proposalId, bytes operation); +event ModuleAdded(bytes32 moduleId, address moduleAddress); +event TokensTransferred(address recipient, uint256 amount); +``` + +**Проверка в блокчейн-сканере:** +``` +https://etherscan.io/address/0xDLE_CONTRACT_ADDRESS +└── Все транзакции видны публично +└── Невозможно скрыть или удалить +``` + +### Мониторинг в реальном времени + +**Backend отслеживает все события:** + +```javascript +// Подписка на события смарт-контракта +dleContract.on('ProposalCreated', async (proposalId, initiator, event) => { + logger.info(`Новое предложение #${proposalId} от ${initiator}`); + + // Получаем детали предложения + const proposal = await dleContract.proposals(proposalId); + + // Анализ безопасности + const risks = analyzeProposalRisks(proposal); + + // Уведомление токен-холдеров + if (risks.level === 'HIGH') { + await notifyAllTokenHolders({ + type: 'SECURITY_ALERT', + proposalId, + risks + }); + } +}); +``` + +### Система алертов + +```javascript +// Критичные события требуют немедленного уведомления +const criticalEvents = [ + 'ProposalCreated', // Новое предложение + 'ModuleAdded', // Добавлен модуль + 'TokensTransferred' // Переведены токены +]; + +async function sendAlert(event, data) { + // Email уведомления + await sendEmail({ + to: allTokenHolders, + subject: `[DLE Alert] ${event}`, + body: formatAlert(data) + }); + + // Telegram уведомления + await sendTelegram({ + chat: dleNotificationsChat, + message: formatAlert(data) + }); + + // Запись в логи + logger.warn(`ALERT: ${event}`, data); +} +``` + +--- + +## Рекомендации по безопасности + +### Для владельцев токенов + +1. **🥶 Используйте hardware wallet** (Ledger, Trezor) + - Приватный ключ никогда не покидает устройство + - Подтверждение каждой операции на физическом устройстве + +2. **🔐 Храните seed фразу безопасно** + - Напишите на бумаге, не храните в цифровом виде + - Используйте металлические пластины для долговечности + - Храните в сейфе или банковской ячейке + +3. **🚨 Включите уведомления** + - Email алерты на новые предложения + - Telegram боты для критичных событий + +4. **👀 Проверяйте все предложения** + - Читайте описание перед голосованием + - Проверяйте адреса получателей + - Используйте timelock для критичных операций + +5. **❄️ Разделите токены** + - Горячий кошелек: 10-20% для повседневного использования + - Холодный кошелек: 80-90% для долгосрочного хранения + +### Для администраторов + +1. **🔄 Регулярные обновления** + ```bash + # Еженедельное обновление + docker-compose pull + docker-compose up -d + ``` + +2. **💾 Резервные копии** + ```bash + # Ежедневный бэкап базы данных + docker exec dapp-postgres pg_dump -U user db > backup.sql + ``` + +3. **📊 Мониторинг логов** + ```bash + # Проверка логов на подозрительную активность + docker logs dapp-backend | grep -i "error\|warning\|failed" + ``` + +4. **🔑 Ротация ключей шифрования** + - Меняйте ключ шифрования раз в год + - Храните старые ключи для расшифровки исторических данных + +5. **🛡️ Firewall настройка** + ```bash + # Разрешить только необходимые порты + ufw allow 80/tcp # HTTP + ufw allow 443/tcp # HTTPS + ufw enable + ``` + +### Для разработчиков + +1. **✅ Аудит смарт-контрактов** + - Используйте Slither для статического анализа + - Mythril для поиска уязвимостей + - Ручной аудит критичного кода + +2. **🧪 Тестирование** + ```bash + # Запуск тестов + cd backend + yarn test + + # Покрытие кода + yarn coverage + ``` + +3. **📝 Код-ревью** + - Все изменения через pull requests + - Минимум 2 ревьюера для критичных изменений + +4. **🔒 Безопасные зависимости** + ```bash + # Проверка уязвимостей + yarn audit + npm audit fix + ``` + +--- + +## Сценарии атак и защита + +### Сценарий 1: Фишинговая атака + +**Атака:** +``` +1. Злоумышленник создает поддельный сайт: dlle.com (вместо dle.com) +2. Отправляет фишинговые письма токен-холдерам +3. Просит подключить кошелек и подписать транзакцию +``` + +**Защита:** +```javascript +// Backend проверяет домен в SIWE сообщении +const message = new SiweMessage({ + domain: req.get('host'), // Должен быть правильный домен + uri: req.get('origin') +}); + +// Frontend показывает предупреждение +if (window.location.hostname !== 'dle.app') { + alert('⚠️ ВНИМАНИЕ: Это НЕ официальный сайт DLE!'); +} +``` + +**Рекомендации пользователям:** +- ✅ Всегда проверяйте URL перед подключением кошелька +- ✅ Используйте закладки браузера +- ✅ Проверяйте SSL сертификат (зеленый замок) + +### Сценарий 2: Взлом backend сервера + +**Атака:** +``` +1. Злоумышленник получает доступ к backend серверу +2. Пытается изменить код для обхода проверки токенов +3. Или полностью выводит веб-приложение из строя +``` + +**Защита:** +``` +✅ Проверка токенов происходит на блокчейне (неизменяемо) +✅ Backend может быть скомпрометирован, но: + ├── Невозможно изменить баланс токенов в смарт-контракте + ├── Невозможно создать поддельные токены + ├── Невозможно изменить правила смарт-контракта + └── Пользователи увидят расхождение между backend и блокчейном +``` + +**Критично: Веб-приложение - это только интерфейс!** + +Даже при **полном взломе** веб-приложения: +- ✅ **Все активы бизнеса защищены** на блокчейне +- ✅ **Смарт-контракты продолжают работать** независимо от веб-приложения +- ✅ **Можно управлять через блокчейн-сканеры** (Etherscan, Polygonscan, и др.) + +### Управление через блокчейн-сканеры + +**Если веб-приложение недоступно, используйте блокчейн-сканеры:** + +#### 1. Проверка баланса токенов + +``` +1. Откройте Etherscan: https://etherscan.io +2. Введите адрес смарт-контракта DLE +3. Перейдите на вкладку "Read Contract" +4. Вызовите функцию balanceOf(address) +5. Введите адрес вашего кошелька +6. Нажмите "Query" - увидите баланс токенов ✅ +``` + +**Пример**: +``` +Contract Address: 0x1234...DLE +Function: balanceOf +Address: 0xYourWallet... +Result: 500000 (ваш баланс токенов) +``` + +#### 2. Создание предложения через Etherscan + +``` +1. Откройте Etherscan и найдите смарт-контракт DLE +2. Перейдите на вкладку "Write Contract" +3. Подключите кошелек MetaMask +4. Найдите функцию createProposal +5. Заполните параметры: + - description: "Восстановить веб-приложение" + - operation: закодированный вызов функции + - votingDuration: 86400 (1 день в секундах) +6. Нажмите "Write" и подтвердите транзакцию ✅ +``` + +**Пример создания предложения**: +```solidity +// Через Etherscan Write Contract +createProposal( + "Перевести 10,000 USDT на восстановление инфраструктуры", + 0x..., // закодированный вызов transferTokens + 86400 // 1 день +) +``` + +#### 3. Голосование через Etherscan + +``` +1. Откройте смарт-контракт DLE на Etherscan +2. Вкладка "Write Contract" +3. Подключите кошелек +4. Функция vote(uint256 proposalId, bool support) + - proposalId: номер предложения (например, 5) + - support: true (за) или false (против) +5. Нажмите "Write" ✅ +``` + +#### 4. Проверка состояния предложения + +``` +1. Вкладка "Read Contract" на Etherscan +2. Функция proposals(uint256) +3. Введите ID предложения +4. Увидите все детали: + - Описание + - Голоса "За" и "Против" + - Статус (Active, Executed, Failed) + - Время окончания голосования +``` + +#### 5. Исполнение одобренного предложения + +``` +1. Если предложение одобрено и время истекло +2. Откройте "Write Contract" +3. Функция execute(uint256 proposalId) +4. Введите ID предложения +5. Нажмите "Write" - предложение исполнится ✅ +``` + +### Популярные блокчейн-сканеры для DLE + +| Сеть | Блокчейн-сканер | URL | +|------|-----------------|-----| +| **Ethereum Mainnet** | Etherscan | https://etherscan.io | +| **Polygon** | Polygonscan | https://polygonscan.com | +| **Binance Smart Chain** | BscScan | https://bscscan.com | +| **Arbitrum** | Arbiscan | https://arbiscan.io | +| **Optimism** | Optimistic Etherscan | https://optimistic.etherscan.io | +| **Avalanche** | SnowTrace | https://snowtrace.io | +| **Base** | BaseScan | https://basescan.org | + +### Преимущества управления через блокчейн-сканеры + +**1. Полная независимость от веб-приложения** +``` +Веб-приложение взломано → Блокчейн работает ✅ +Backend сервер упал → Смарт-контракты работают ✅ +Frontend недоступен → Можно управлять через Etherscan ✅ +``` + +**2. Невозможно подделать данные** +``` +Злоумышленник на backend → Блокчейн-сканер показывает правду +Поддельный frontend → Etherscan покажет реальные токены +Измененная логика → Смарт-контракт работает как задумано +``` + +**3. Доступ 24/7 из любой точки мира** +``` +Нет доступа к серверу → Etherscan доступен всегда +Приложение на обслуживании → Управление через блокчейн +DDoS атака на сайт → Блокчейн недоступен для DDoS +``` + +**Реакция на взлом:** +1. Пользователи замечают странное поведение веб-приложения +2. Проверяют баланс токенов напрямую через Etherscan ✅ +3. Создают предложение через Etherscan на восстановление +4. Голосуют за восстановление инфраструктуры +5. Администраторы восстанавливают backend из резервной копии +6. **Никакие токены и активы не потеряны** ✅ + +**Вывод**: Веб-приложение - это лишь удобный интерфейс. Реальная власть и активы находятся на блокчейне, где они защищены криптографией и невозможно их изменить или украсть через взлом веб-приложения. + +### Сценарий 3: 51% атака + +**Атака:** +``` +1. Злоумышленник покупает или получает >51% всех токенов +2. Создает предложение "Перевести все активы мне" +3. Голосует всеми своими токенами "За" +4. Предложение одобрено +``` + +**Защита:** +```javascript +// Timelock Module дает время на реакцию +const TIMELOCK = 7 days; + +// Другие токен-холдеры могут: +1. Проголосовать "Против" (если у них еще 49%) +2. Создать контр-предложение +3. Обратиться в правоохранительные органы +4. Отменить предложение через emergency функцию (если настроена) +``` + +**Долгосрочная защита:** +- Равномерное распределение токенов между партнерами +- Мультиподпись для крупных операций +- Квадратичное голосование (опция для будущих версий) + +### Сценарий 4: Social Engineering + +**Атака:** +``` +1. Злоумышленник выдает себя за поддержку DLE +2. Просит токен-холдера "для верификации" подписать сообщение +3. Сообщение на самом деле - одобрение перевода токенов +``` + +**Защита:** +```javascript +// Frontend всегда показывает ЧТО подписывается +function signMessage(message) { + // Показываем пользователю точное содержимое + const confirmation = confirm(` + Вы собираетесь подписать: + ${message} + + ⚠️ НИКОГДА не подписывайте сообщения по просьбе "поддержки"! + + Продолжить? + `); + + if (!confirmation) return; + + // Подпись +} +``` + +**Рекомендации:** +- ❌ Поддержка **НИКОГДА** не попросит подписать сообщение +- ❌ Не доверяйте "срочным" запросам +- ✅ Всегда проверяйте, что подписываете +- ✅ При сомнениях - свяжитесь с официальной поддержкой + +--- + +## Заключение + +### Многоуровневая защита DLE + +``` +┌─────────────────────────────────────────────────────┐ +│ Уровни безопасности DLE │ +├─────────────────────────────────────────────────────┤ +│ 1️⃣ Блокчейн │ +│ └── Токены нельзя украсть даже со взломом │ +│ │ +│ 2️⃣ Смарт-контракты │ +│ └── Аудит, OpenZeppelin, иммутабельность │ +│ │ +│ 3️⃣ Голосование с кворумом │ +│ └── Невозможно единоличное решение │ +│ │ +│ 4️⃣ Timelock │ +│ └── Время на реакцию при атаке │ +│ │ +│ 5️⃣ Backend проверки │ +│ └── Проверка токенов в реальном времени │ +│ │ +│ 6️⃣ Frontend защита │ +│ └── XSS, CSRF, rate limiting │ +│ │ +│ 7️⃣ Мониторинг и алерты │ +│ └── Детекция подозрительных действий │ +└─────────────────────────────────────────────────────┘ +``` + +### Ключевые преимущества безопасности + +1. **🔐 Контроль доступа через токены** + - Без токенов доступ невозможен + - Проверка в реальном времени на блокчейне + +2. **🛡️ Защита от кражи токенов** + - Невозможно перевести без голосования + - Даже при взломе кошелька токены защищены + +3. **🌐 Независимость от веб-приложения** + - Даже при взломе веб-приложения активы бизнеса защищены на блокчейне + - Можно управлять через блокчейн-сканеры (Etherscan, Polygonscan и др.) + - Смарт-контракты работают независимо от frontend/backend + - Веб-приложение - это только удобный интерфейс, реальная власть на блокчейне + +4. **⚖️ Коллективное управление** + - Критичные решения только через голосование + - Кворум предотвращает единоличные действия + +5. **🔒 Модули под контролем смарт-контракта** + - Только DLE контракт может вызывать модули + - Никакого прямого доступа + +6. **📊 Полная прозрачность** + - Все действия на блокчейне + - Невозможно скрыть или подделать + +### Следующие шаги + +1. 📖 [Изучите техническую документацию](./blockchain-integration-technical.md) +2. 🔧 [Настройте безопасное окружение](./setup-instruction.md) +3. 📋 [Прочитайте FAQ](./FAQ.md) +4. 💬 [Получите поддержку](https://hb3-accelerator.com/) + +--- + +## Контакты безопасности + +**Обнаружили уязвимость?** + +📧 **Security Email**: security@hb3-accelerator.com + +**Процесс ответственного раскрытия:** +1. Отправьте детали уязвимости на security@hb3-accelerator.com +2. НЕ публикуйте информацию публично до исправления +3. Мы ответим в течение 48 часов +4. Исправление будет выпущено в течение 7-30 дней +5. Вы получите благодарность (по желанию) + +**Программа Bug Bounty:** +- Критичные уязвимости: $1,000-10,000 USDT +- Высокие: $500-1,000 USDT +- Средние: $100-500 USDT + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + diff --git a/docs/service-terms.md b/docs/service-terms.md new file mode 100644 index 0000000..63ad59b --- /dev/null +++ b/docs/service-terms.md @@ -0,0 +1,674 @@ +# Условия приобретения и обслуживания Digital Legal Entity + +## 1. Лицензионная модель + +### 1.1. Основные принципы + +- **📜 Тип лицензии**: Единственный тип - **Бессрочная лицензия (Perpetual License)** +- **⏳ Срок действия**: Пожизненная (без ограничения по времени) +- **💰 Цена**: Зависит от **количества токенов** в лицензии (см. раздел 2) +- **🔄 Обновления**: БЕСПЛАТНЫ для всех держателей лицензий +- **🚫 Отмена**: Лицензия не может быть отменена компанией +- **⚖️ Условия обслуживания**: Одинаковые для всех лицензий (различие только в количестве голосов) + +### 1.2. Связь: Токены ↔ Лицензии + +Каждая лицензия Digital Legal Entity связана с **токеном управления на блокчейне**. + +#### 📊 Соотношение токенов и прав + +| Параметр | На 1 токен | На 10 токенов | +|----------|-----------|--------------| +| **Количество лицензий** | 1 | 1 | +| **Виды деятельности** | 1 | 1 | +| **Голосов в голосовании** | 1 | 10 | +| **Условия обслуживания** | Одинаковые | Одинаковые | +| **Влияние на развитие** | 1 голос | 10 голосов | + +#### 🗳️ Голосование в сообществе + +- **Голос = 1 токен** (независимо от количества токенов у одного владельца) +- Голосование происходит на **блокчейне** (смарт-контракт управления) +- Токены дают право голоса за **новые функции и приоритеты развития** +- **Демократия**: Решения принимаются большинством голосов (51%+) + +### 1.3. Вид деятельности и использование + +- Каждая лицензия привязана к **одному виду деятельности/бизнеса** +- Владелец может переопределить вид деятельности, но одновременно поддерживать только один +- Для нескольких видов деятельности нужны отдельные лицензии и токены + +--- + +## 2. Типы лицензий + +### 2.1. Лицензия с 1 токеном + +- **💰 Цена за лицензию**: **$1,000 USDT** (один раз, бессрочно, без учета налогов) +- **🪙 Количество токенов**: **1 токен** = **1 голос** в голосовании +- **🗳️ Влияние на развитие**: Базовое (1 голос за новые функции) + +### 2.2. Лицензия с 10 токенами + +- **💰 Цена за лицензию**: **$10,000 USDT** (один раз, бессрочно, без учета налогов) +- **🪙 Количество токенов**: **10 токенов** = **10 голосов** в голосовании +- **🗳️ Влияние на развитие**: Усиленное (10 голосов за новые функции) + +### 2.3. Условия обслуживания (одинаковые для всех лицензий) + +**📧 Все держатели лицензий получают:** + +- ✅ Все обновления веб-приложения (бесплатно, пожизненно) +- ✅ Доступ к документации и базе знаний +- ✅ Техническая поддержка через приложение: https://hb3-accelerator.com/ +- ✅ Время отклика: в соответствии с приоритетом проблемы (см. раздел 6.3) +- ✅ 🤖 **AI ассистент 24/7** - встроенный помощник для консультаций +- ✅ Все интеграции и возможности развертывания +- ✅ Участие в голосовании за новые фичи (по количеству токенов) +- ✅ Ранний доступ к beta функциям (при желании) +- ✅ SLA 99% uptime гарантия +- ✅ Ежедневное резервное копирование +- ✅ Мониторинг производительности 24/7 +- ✅ 🎓 **Онлайн-сессии обучения и внедрения**: + - Групповые онлайн-сессии (ежеквартально - 4 раза в год) + - Индивидуальные онлайн-сессии (до 4 в год по запросу) + - Обучение настройке приложения + - Стратегии внедрения в бизнес + - Консультации по максимизации выгоды + - Доступ к библиотеке записей всех сессий + +**⚖️ Единственная разница между лицензиями:** +- Количество токенов управления (1 vs 10) +- Количество голосов в голосовании (1 vs 10) +- Влияние на приоритизацию разработки новых функций + +--- + +## 3. Система голосования и развитие продукта + +### 3.1. Как работает голосование + +1. **Предложение фичи**: Сообщество предлагает новые функции +2. **Регистрация на блокчейне**: Голосование создается в смарт-контракте +3. **Голосование токен-холдеров**: Каждый токен = 1 голос +4. **Реализация**: Если проголосовало 51%+ токенов - фича берется в разработку + +### 3.2. Периодичность голосований + +- **Окно голосования**: Открыто постоянно (асинхронное голосование) +- **Квартальный анализ**: Каждый квартал суммируются голоса, анализируются решения +- **Приоритизация**: Разработка ведется по приоритету (количество голосов) + +### 3.3. Механизм "Жалоб на невыполнение" + +⚠️ **Механизм возврата денег (см. раздел 4.2)** + +### 3.4. 🌐 Портал голосования + +**Адрес**: https://hb3-accelerator.com/ + +Токен-холдеры могут: +- 📋 Создавать предложения (proposals) для новых функций и приоритизации +- 🗳️ Голосовать за или против предложений +- 📊 Просматривать результаты голосований +- 📈 Отслеживать статус разработки одобренных фич +- ⏱️ Видеть историю всех голосований на блокчейне + +**Требования:** +- Подключение кошелька с токенами (MetaMask, WalletConnect и т.д.) +- Ваше количество токенов = количество голосов + +--- + +## 4. Возврат средств и гарантии + +### 4.1. Общие условия + +- **🔒 Принцип**: Лицензия бессрочна - возврата нет (кроме исключительных случаев) +- **📋 Исключение**: Специальная программа возврата (см. раздел 4.2) + +### 4.2. Программа возврата 70% (Refund Program) + +**Условия возврата:** + +Вы можете потребовать возврат **70% от стоимости лицензии** в течение **5 лет** с момента покупки, если: + +1. ✋ **Порог жалоб**: Накопилось свыше **51% отрицательных голосов** +2. 📋 **Причина**: Жалобы касаются **отсутствия выпусков обновлений** +3. 🗳️ **Голосование**: Жалобы были **приняты через механизм голосования токен-холдеров на блокчейне** +4. ⏱️ **Сроки**: Запрос подан в течение **5 лет** с момента лицензирования + +**Процесс возврата:** + +1. Запрос подается на support@hb3-accelerator.com с приложением блокчейн-доказательства +2. Подтверждение условий на смарт-контракте (51%+ голосов за возврат) +3. Возврат **70% от суммы покупки** в течение 30 дней + +**Пример:** +- Куплена лицензия с 10 токенами за $10,000 USDT +- Возврат: $10,000 × 70% = $7,000 USDT +- Действителен до: 5 лет с даты покупки + +### 4.3. Ограничения ответственности + +✅ **Что гарантируется:** +- Лицензия действует вечно (без ограничения срока) +- Обновления предоставляются бесплатно пожизненно +- Базовая функциональность остается доступной +- Возможность голоса за развитие продукта + +❌ **НЕ гарантируется:** +- Специфические новые фичи (зависит от голосования) +- Определенный график выпусков (зависит от голосов) +- Поддержка при модификации исходного кода +- Производительность при превышении лимитов + +### 4.4. Что автор НЕ несет ответственность за + +❌ **Автор освобождается от ответственности за:** + +- **Упущенная прибыль** - потери доходов из-за сбоев приложения +- **Косвенные убытки** - вторичные последствия использования +- **Потеря данных** - пользователь сам отвечает за резервные копии +- **Прерывание деятельности** - простои и перебои в обслуживании +- **Потеря репутации** - репутационный ущерб бизнеса +- **Специальные убытки** - штрафы, пени, санкции, штрафные платежи +- **Использование в образовательных целях** - без разрешения +- **Использование в соответствии с условиями** - если нарушены условия + +### 4.5. Максимальная ответственность + +- **Лимит ответственности:** Размер оплаченной лицензии (не более) +- **Пример:** Если лицензия стоила $1,000 USDT, максимум возврат $1,000 USDT +- **Прямые убытки:** Только при прямом нарушении контракта +- **Исключения:** Не покрываются косвенные, специальные или штрафные убытки + +### 4.6. Ответственность пользователя + +✅ **Пользователь отвечает за:** +- Резервное копирование собственных данных (еженедельно минимум) +- Использование в соответствии с условиями лицензии +- Защиту приватных ключей кошелька и доступа +- Соблюдение всех применимых законов и нормативов +- Обновление приложения в разумные сроки +- Проверку совместимости с окружением перед обновлением + +--- + +## 5. Обновления и обслуживание + +### 5.1. Бесплатные обновления для держателей лицензий + +🎁 **ВСЕ обновления веб-приложения БЕСПЛАТНЫ:** +- Исправления ошибок (Bug Fixes) +- Улучшения производительности +- Новые функции (одобренные голосованием) +- Обновления безопасности + +**Частота:** +- Security Patches: Немедленно (при обнаружении) +- Regular Updates: Еженедельно (по средам) +- Major Features: По результатам голосования + +### 5.2. Процесс получения обновлений + +1. **Получение уведомления**: Через email/Slack (зависит от типа Support) +2. **Автоматическое обновление**: Docker контейнер обновляется при перезапуске +3. **Ручное обновление**: Возможно в любой момент + +### 5.3. 📥 Платформа скачивания обновлений + +**Адрес**: https://hb3-accelerator.com/updates + +Все держатели лицензий могут: +- ✅ Скачивать все выпущенные версии приложения +- 📝 Читать подробные заметки о релизах (Release Notes) +- 📅 Просматривать календарь запланированных обновлений +- 🔄 Получать автоматические уведомления о новых версиях +- 📚 Изучать документацию по миграции между версиями +- 🪵 Видеть логи изменений (Changelog) + +**Требования для доступа:** +- Подключение кошелька с активной лицензией (NFT токен) +- Лицензия должна быть активна на момент скачивания + +### 5.4. Поддержка версий + +| Тип версии | Период поддержки | Обновления | +|-----------|-----------------|-----------| +| **LTS** | 24 месяца | Активные | +| **Regular** | 12 месяцев | Активные | +| **Beta** | Нет гарантий | Нет гарантий | + +--- + +## 6. Техническая поддержка + +### 6.1. Единый портал поддержки + +**Все виды поддержки доступны ТОЛЬКО через приложение:** + +🌐 **https://hb3-accelerator.com/** + +- 📝 Создание и отслеживание тикетов поддержки +- 💬 Прямой чат с support team +- 📊 История всех обращений +- 📅 Отслеживание времени ответа + +### 6.2. Доступные каналы поддержки + +**Все держатели лицензий имеют доступ к:** + +| Функция | Доступность | +|--------|-------------| +| 🌐 Портал поддержки | ✅ Все лицензии | +| 💬 Чат с support team | ✅ Все лицензии | +| 🤖 AI ассистент 24/7 | ✅ Все лицензии | +| 🎓 Онлайн-сессии обучения | ✅ Групповые + индивидуальные (все лицензии) | +| 📚 Библиотека записей | ✅ Все лицензии | +| 📧 Email поддержка | ✅ Все лицензии | + +### 6.3. Классификация проблем и SLA + +**Время отклика зависит от приоритета проблемы, а не от типа лицензии:** + +| Приоритет | Описание | SLA (время первого ответа) | +|-----------|---------|-----| +| 🔴 Критическая | Сервис полностью недоступен | 4 часа | +| 🟠 Высокая | Потеря основной функции | 8 часов | +| 🟡 Средняя | Деградация производительности | 24 часа | +| 🟢 Низкая | Вопросы, документация | 48 часов | + +### 6.4. Процесс обращения в поддержку + +1. Войти в приложение: https://hb3-accelerator.com/ +2. Перейти в раздел "Поддержка" или "Support" +3. Создать новый тикет с описанием проблемы +4. Указать приоритет (система автоматически классифицирует) +5. Приложить логи, скриншоты и шаги воспроизведения +6. Получить номер тикета для отслеживания +7. Дождаться ответа в соответствии с SLA (по приоритету проблемы) + +### 6.5. 🎓 Онлайн-сессии обучения и внедрения + +**Все держатели лицензий** (независимо от типа) получают доступ к **онлайн-сессиям обучения**, где эксперты помогают максимально эффективно использовать Digital Legal Entity. + +#### Групповые онлайн-сессии + +**📅 Периодичность**: Ежеквартально (4 раза в год) + +**📚 Темы обучения:** +- 🔧 **Настройка приложения** - пошаговое руководство по первоначальной конфигурации +- 🏢 **Внедрение в бизнес** - как интегрировать DLE в существующие бизнес-процессы +- 💰 **Максимизация выгоды** - лучшие практики использования функций +- 📊 **Аналитика и отчетность** - как использовать данные для принятия решений +- 🔐 **Безопасность и комплаенс** - настройка безопасности и соответствие нормам +- 🗳️ **Голосование и governance** - как эффективно использовать свои токены + +**⏱️ Формат:** +- Длительность: 1-2 часа +- Вебинар с презентацией и демонстрацией +- Q&A сессия в конце (30-40 минут) +- Запись доступна после сессии + +**👥 Формат участия:** +- До 100 участников одновременно +- Чат для вопросов во время сессии +- Возможность задать вопросы заранее + +#### Индивидуальные онлайн-сессии + +**Доступно для всех лицензий** + +**📅 Периодичность**: До 4 сессий в год (по запросу) + +**🎯 Персонализированные темы:** +- 🏗️ **Индивидуальная архитектура** - настройка под специфику вашего бизнеса +- 📈 **Стратегия внедрения** - пошаговый план интеграции DLE +- 💡 **Оптимизация ROI** - как получить максимальную отдачу от инвестиций +- 🔄 **Миграция данных** - перенос из существующих систем +- 🛠️ **Кастомизация и интеграции** - настройка под ваши требования +- 📊 **Анализ эффективности** - обзор метрик и улучшений +- 🗳️ **Стратегия голосования** - как использовать ваши токены для влияния на развитие + +**⏱️ Формат:** +- Длительность: 1-2 часа (по потребности) +- Индивидуальная видео-встреча (Zoom/Google Meet) +- Персональный эксперт, знакомый с вашим кейсом +- Запись сессии для вашей команды +- Материалы и документация после сессии +- Возможность пригласить вашу команду (до 10 человек) + +#### Запись на онлайн-сессии + +**Как записаться:** +1. Войти в приложение: https://hb3-accelerator.com/ +2. Перейти в раздел "Обучение" или "Training" +3. Выбрать доступную сессию из календаря (групповая или индивидуальная) +4. Нажать "Записаться" и получить ссылку на подключение + +**Уведомления:** +- За 7 дней: Email с темой и программой сессии +- За 1 день: Напоминание с ссылкой для подключения +- За 1 час: SMS/Push уведомление + +#### Библиотека записей + +Все прошедшие онлайн-сессии доступны в библиотеке для всех держателей лицензий: + +**📚 Адрес**: https://hb3-accelerator.com/training-library + +- 🎥 Видеозаписи всех групповых сессий +- 📄 Презентации и материалы +- 💬 Стенограммы Q&A сессий +- 🔍 Поиск по темам и ключевым словам +- 📥 Скачивание материалов для offline просмотра + +--- + +## 7. Условия использования + +### 7.1. Допустимое использование + +✅ **Разрешено:** +- Использование для управления собственным бизнесом +- Развертывание на собственной инфраструктуре +- Использование выбранного вида деятельности (1 вид на лицензию) +- Резервное копирование данных +- Локальная модификация конфигурации +- Голосование за развитие новых функций +- Передача лицензии наследникам (для бессрочной лицензии) + +❌ **Запрещено:** +- Перепродажа или сублицензирование +- Использование более одного вида деятельности одной лицензией +- Reverse engineering и модификация исходного кода +- Удаление авторских прав и лицензионных уведомлений +- Совместное использование между независимыми организациями +- Использование в образовательных целях без разрешения +- Развертывание SaaS на основе приложения +--- + +## 8. Безопасность и конфиденциальность + +### 8.1. Шифрование данных + +- **TLS 1.3**: Для всех соединений +- **AES-256**: Для критичных данных в хранилище +- **Управление ключами**: Пользователь контролирует ключи шифрования + +### 8.2. Соответствие стандартам + +- **GDPR**: Соответствие (с DPA) +- **SOC 2 Type II**: Сертификация получена +- **ISO 27001**: В планах +--- + +## 9. Смарт-контракт управления лицензиями + +### 9.1. Архитектура системы управления + +DLE использует **смарт-контракт** на блокчейне для управления лицензиями и голосованием: + +- **ERC20 токены**: Каждая лицензия представлена токенами управления (1 или 10) +- **ERC20Votes**: Встроенная система голосования через смарт-контракт +- **ERC20Permit**: Подписи для переводов токенов без gas-комиссий (meta-transactions) +- **Мультичейн архитектура**: Поддержка голосования и исполнения в нескольких сетях одновременно + +### 9.2. Система предложений и голосования + +**Создание предложения:** +- Только держатели токенов (лицензий) могут создавать предложения +- Описание: Текст предложения о новой функции +- Длительность голосования: От 1 часа до 30 дней +- Целевые сети: Может быть исполнено в одной или нескольких сетях одновременно + +**Процесс голосования:** +1. Предложение создается и получает уникальный ID +2. Токен-холдеры голосуют "За" или "Против" +3. Каждый токен = 1 голос (независимо от держателя) +4. Кворум проверяется при дедлайне или при достижении 51%+ + +**Исполнение предложения:** +- Если "За" > "Против" И кворум достигнут → предложение принято +- Исполнение может быть через: + - Прямой вызов (в цепочке голосования) + - Через подписи (в других сетях) + +### 9.3. Поддерживаемые операции через голосование + +Через смарт-контракт DLE можно управлять: + +- **Добавление/удаление модулей** - расширение функциональности +- **Управление поддерживаемыми цепочками** - добавление/удаление блокчейнов +- **Обновление параметров кворума** - от 1% до 100% +- **Обновление времени голосования** - минимальное и максимальное время +- **Передача токенов через governance** - распределение вознаграждений +- **Обновление информации DLE** - название, символ, юрисдикция, коды ОКВЭД +- **Оффчейн операции** - запись решений без на-цепочных эффектов + +### 9.4. Иерархическое голосование + +Модуль **HierarchicalVotingModule** позволяет: +- Одному DLE голосовать в другом DLE +- Владеть токенами других DLE +- Создавать предложения в других DLE от имени своего +- Прозрачно отслеживать цепочку голосований + +### 9.5. Безопасность и ограничения + +✅ **Защита от реентерабельности** - ReentrancyGuard во всех критичных операциях +✅ **Блокировка прямых переводов** - токены передаются только через governance +✅ **Снапшоты голосов** - используются прошлые значения для защиты от flash-loans +✅ **Подписи EIP-712** - поддержка контрактных кошельков и meta-transactions +✅ **Валидация операций** - все параметры проверяются перед исполнением + +### 9.6. Передача лицензии + +- Лицензия = токены управления, привязанные к адресу кошелька +- Передача: Просто перевод токенов на новый адрес (возможен через governance) +- Права: Новый владелец автоматически получает право голоса + +--- + +## 10. Контактная информация и поддержка + +### 📞 Служба поддержки + +🌐 **ТОЛЬКО через приложение**: https://hb3-accelerator.com/ + +- **Портал поддержки**: Создавайте тикеты и отслеживайте статус +- **Чат с поддержкой**: Общайтесь с support team напрямую +- **Сайт проекта**: https://hb3-accelerator.com +- **GitHub**: https://github.com/VC-HB3-Accelerator/DLE + +### ⚖️ Юридическая информация + +- **Компания**: HB3 Accelerator +- **Юридический статус**: Проприетарное ПО (см. [LICENSE](../LICENSE)) +- **Полная документация**: [legal/README.md](../legal/README.md) + +--- + +## 11. Политика изменения условий + +### 11.1. Изменения для новых лицензий + +- Мы можем изменять условия обслуживания **для новых покупок** +- Уведомление: За 60 дней до вступления в силу +- Применение: Только для новых лицензий, купленных после даты изменения + +### 11.2. Защита существующих лицензий + +- **Гарантия**: Условия вашей лицензии **НЕ меняются** после покупки +- **Фиксированные права**: Останавливаются вечно с текущими условиями +- **Обратная совместимость**: Старые условия поддерживаются + +--- + +## 12. История изменений + +| Версия | Дата | Изменения | +|--------|------|-----------| +| 1.0 | 2024-10-25 | Первоначальная версия (токен-модель) | +| 1.1 | 2025-10-25 | Добавлена информация об онлайн-сессиях обучения и внедрения | +| 1.2 | 2025-10-25 | Унификация условий обслуживания: все лицензии получают одинаковые условия поддержки, различие только в количестве голосов | + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Последнее обновление**: October 2025 + +### 🔐 Примечание о блокчейне + +Эта модель управления лицензиями использует блокчейн для обеспечения **прозрачности**, **демократичности** и **неизменяемости** процесса голосования за развитие продукта. Все токен-холдеры имеют равные голоса и контроль над будущим развитием Digital Legal Entity. + +## 5. Тарифы и условия оплаты + +### 5.1. Методы оплаты + +- 💵 **Криптовалюта (USDT)**: Директно на адреса авторизованных компаний-партнеров +- 💳 **Перевод в местной валюте**: Эквивалент в местной валюте страны покупателя +- 🏦 **Банковский перевод**: Через авторизованных дилеров +- 💳 **Кредитные карты**: Через платежные системы партнеров + +### 5.2. Цены и налоги + +#### ⚠️ ВАЖНО: Все цены указаны БЕЗ УЧЕТА НАЛОГОВ + +**Указанные цены в USDT:** +- **Лицензия с 1 токеном**: $1,000 USDT (без налогов) +- **Лицензия с 10 токенами**: $10,000 USDT (без налогов) + +**Эквивалент в других валютах (примеры, зависит от курса):** +- EUR: €899 (1 токен) или €8,991 (10 токенов) +- RUB: ₽99,000 (1 токен) или ₽990,000 (10 токенов) +- Другие валюты по актуальному курсу на момент платежа + +#### Налоги - ответственность покупателя + +Покупатель самостоятельно несет ответственность за уплату всех применимых налогов: +- **НДС (VAT)** - в странах ЕС и других (обычно 15-25%) +- **Налог на продажу (Sales Tax)** - в США и других странах +- **Налог на доход (Income Tax)** - зависит от налогового статуса +- **Таможенные пошлины** - при импорте в определенные страны +- **Любые другие налоги** - в зависимости от местной юрисдикции + +**Налоговая ставка определяется:** +- Юрисдикцией покупателя (страна, город, регион) +- Налоговым статусом (физ. лицо, ИП, ООО, АО и т.д.) +- Особенностями международной торговли + +#### 💸 Комиссии за платежи - ПОЛНОСТЬЮ НА ПОКУПАТЕЛЯ + +Все комиссии за переводы, конвертацию и обработку платежей несет **ПОКУПАТЕЛЬ**: + +**🌍 Комиссии за конвертацию валют:** +- Комиссия банка/платежной системы: 1-5% от суммы +- Комиссия за внутримаркетный спред (курс): +1-2% сверху рыночного +- Скрытые комиссии при конвертации: часто 2-3% + +**🏦 Комиссии за банковские переводы:** +- **SWIFT переводы** (международные): $10-50+ за операцию +- **SEPA переводы** (внутри ЕС): €0-3 или бесплатно +- **Другие системы** (Wise, Payoneer): 1-2.5% + фиксированная комиссия +- **Комиссия получающей стороны**: дополнительно 0-50$ (может быть) + +**⛓️ Комиссии блокчейна (криптовалюта - USDT):** +- **Gas fees (комиссия сети)**: + - Ethereum: $1-50+ в зависимости от нагрузки + - Polygon: $0.01-1 + - BSC: $0.10-5 + - Другие сети: варьируется +- **Комиссия кошелька**: 0-2% (если используется платежный провайдер) +- **Комиссия биржи/платформы**: 1-3% за обмен фиата на USDT + +**💳 Комиссии платежных систем (кредитные карты):** +- **Комиссия процессинга**: 2-5% от суммы +- **Комиссия за конвертацию валют**: 1-3% (если платеж в другой валюте) +- **Комиссия банка-эмитента**: 0-2% (редко, но может быть) +- **Комиссия динамической конвертации (DCC)**: 2-4% (если доступна) + +**Реальные примеры итоговых затрат:** + +| Вариант | Заявленная цена | Комиссии | Итого к оплате | +|---------|-----------------|----------|-----------------| +| USDT напрямую | $1,000 | $15-80 (gas + комиссии) | $1,015-1,080 | +| SWIFT перевод USD | $1,000 | $25-80 (комиссии банков) | $1,025-1,080 | +| Карта в EUR | €899 | €30-45 (конвертация + комиссии) | €929-944 | +| Крипто биржа | $1,000 | $30-150 (все комиссии) | $1,030-1,150 | + +**💡 Совет:** Выбери способ оплаты с минимальными комиссиями! + +**⚠️ Итоговая сумма = Цена лицензии + Налоги + Все комиссии за переводы и конвертацию** + +### 5.3. Авторизованные продавцы и дилеры + +#### Официальные условия продажи + +Лицензии могут продаваться **ТОЛЬКО через компании**, имеющие **официальное письменное разрешение от автора**: + +**Требования для авторизованного продавца:** +- ✅ Юридическое лицо (ООО, АО, ИП, корпорация и т.д.) +- ✅ Подписанный контракт/соглашение о дилерстве с автором +- ✅ Включение в официальный список на https://hb3-accelerator.com/ +- ✅ Соблюдение всех условий лицензирования +- ✅ Ведение учета всех продаж +- ✅ Своевременная передача средств автору + +**Структура платежей через дилера:** +- 💰 Покупатель платит → Авторизованный продавец +- 🤝 Продавец получает комиссию (% определяется договором) +- 📤 Остаток передается автору в установленные сроки +- 📋 Все платежи документируются официально и отслеживаются + +#### Прямая покупка у автора + +Можно приобрести напрямую у автора без посредников: + +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR +- 🔗 **Портал**: https://hb3-accelerator.com/ (для прямых покупок и поддержки) + +### 5.4. Процесс оплаты и подтверждение + +1. **Выбор продавца**: Авторизованный дилер или прямо у автора +2. **Согласование цены**: В USDT или эквиваленте местной валюты +3. **Получение реквизитов**: От продавца или автора +4. **Отправка платежа**: Криптовалютой, банковским переводом или другим методом +5. **Подтверждение**: Получение номера платежа и документа об оплате +6. **Активация лицензии**: Получение NFT токена или доступа к портальу + +### 5.5. Возврат и рекламация + +- **Сроки рекламации**: 30 дней с момента платежа +- **Процесс**: Контакт с продавцом или автором с подтверждением платежа +- **Возврат средств**: Максимум 70% от суммы в соответствии с программой возврата +- **Причины возврата**: + - Неполучение лицензии + - Ошибка при расчете + - Двойная оплата + - Другие обоснованные причины + +--- + +## 📚 Дополнительная документация + +### Изучите возможности DLE +- 🤖 **[AI Ассистент](./ai-assistant.md)** - второй пилот для команды, высвобождает время для стратегии +- 💼 **[Блокчейн для бизнеса](./blockchain-for-business.md)** - токенизация активов и решение бизнес-задач +- 🛡️ **[Безопасность DLE](./security.md)** - многоуровневая защита вашего бизнеса + +### Техническая документация +- 🔗 **[Техническая документация по блокчейну](./blockchain-integration-technical.md)** - для разработчиков +- 🔧 **[Инструкция по установке](./setup-instruction.md)** - пошаговая настройка +- 📝 **[Описание приложения](./application-description.md)** - обзор функциональности +- 📋 **[FAQ](./FAQ.md)** - часто задаваемые вопросы + +### Контакты и поддержка +- 📧 **Email**: info@hb3-accelerator.com +- 🌐 **Сайт**: https://hb3-accelerator.com +- 💬 **Чат поддержки**: https://hb3-accelerator.com/ +- 🐙 **GitHub**: https://github.com/HB3-ACCELERATOR diff --git a/docs/setup-ai-assistant.md b/docs/setup-ai-assistant.md new file mode 100644 index 0000000..75c50d3 --- /dev/null +++ b/docs/setup-ai-assistant.md @@ -0,0 +1,750 @@ +# Инструкция по настройке AI Ассистента с векторным поиском + +## 🤖 Полное руководство по запуску интеллектуального помощника + +Этот документ описывает пошаговый процесс настройки AI ассистента для решения бизнес-задач через электронные таблицы и векторный поиск. + +--- + +## 📚 Что вы настроите + +После выполнения инструкции у вас будет: + +✅ Работающий AI ассистент с локальной моделью (Ollama) +✅ База знаний для ответов клиентам (FAQ) +✅ Автоматизация работы с поставщиками +✅ Система обучения персонала +✅ Векторный поиск по вашим данным +✅ Экономия **$483,600/год** на рутинных задачах + +--- + +## ⏱️ Время настройки + +- **Быстрая настройка**: 20-30 минут (базовый FAQ) +- **Полная настройка**: 1-2 часа (все возможности) + +--- + +## Шаг 1: Установка и запуск Ollama + +### 1.1 Проверка статуса Ollama + +1. Перейдите в **Настройки** → вкладка **Интеграции** +2. Найдите блок **"Ollama"** и нажмите **"Подробнее"** +3. Проверьте статус подключения: + - ✅ **"Ollama is running"** — все готово, переходите к шагу 1.3 + - ❌ **"Ollama API not responding"** — переходите к шагу 1.2 + +### 1.2 Запуск Ollama (если не запущен) + +Если Ollama не запущен, выполните в терминале: + +```bash +# Для Docker (рекомендуется) +docker-compose up -d ollama + +# Или локально +ollama serve +``` + +Обновите страницу и проверьте статус снова. + +### 1.3 Установка модели для AI + +1. В разделе **Ollama** нажмите **"Установить модель"** +2. Выберите модель: + - **qwen2.5:7b** (рекомендуется) — для русского языка, 4.7 GB + - **llama2:7b** — для английского, 3.8 GB + - **mistral:7b** — универсальная, 4.1 GB +3. Нажмите **"Установить"** +4. Дождитесь завершения загрузки (5-10 минут в зависимости от скорости интернета) + +> 💡 **Подсказка**: Модель скачивается один раз и хранится локально + +### 1.4 Установка Embedding модели + +1. В том же разделе найдите **"Установить Embedding модель"** +2. Выберите модель: + - **mxbai-embed-large:latest** (рекомендуется) — 670 MB + - **nomic-embed-text:latest** — альтернатива, 274 MB +3. Нажмите **"Установить"** + +> ⚠️ **Важно**: Embedding модель нужна для векторного поиска (RAG) + +--- + +## Шаг 2: Создание базы знаний (электронные таблицы) + +### 2.1 Создание таблицы FAQ + +1. Перейдите в **Таблицы** (в главном меню) +2. Нажмите **"+ Создать таблицу"** +3. Заполните: + - **Название**: `FAQ - Часто задаваемые вопросы` + - **Описание**: `База знаний для AI ассистента по работе с клиентами` +4. Нажмите **"Создать"** + +### 2.2 Настройка столбцов таблицы + +Добавьте следующие столбцы: + +#### Столбец 1: Вопрос (обязательный для RAG) + +1. Нажмите **"+ Добавить столбец"** +2. Заполните: + - **Название**: `Вопрос` + - **Тип**: `Текст` + - **Назначение**: Выберите `Вопрос для AI` ⭐ +3. Нажмите **"Сохранить"** + +> ⚠️ **Критично**: Обязательно выберите назначение "Вопрос для AI" — это поле будет индексироваться для векторного поиска + +#### Столбец 2: Ответ (обязательный для RAG) + +1. Нажмите **"+ Добавить столбец"** +2. Заполните: + - **Название**: `Ответ` + - **Тип**: `Текст` + - **Назначение**: Выберите `Ответ AI` ⭐ +3. Нажмите **"Сохранить"** + +#### Столбец 3: Продукт (опционально, для фильтрации) + +1. Нажмите **"+ Добавить столбец"** +2. Заполните: + - **Название**: `Продукт` + - **Тип**: `Множественный выбор` + - **Варианты**: `Базовый`, `Премиум`, `Корпоративный` + - **Назначение**: Выберите `Фильтр по продукту` +3. Нажмите **"Сохранить"** + +#### Столбец 4: Теги (опционально, для категоризации) + +1. Нажмите **"+ Добавить столбец"** +2. Заполните: + - **Название**: `Теги` + - **Тип**: `Множественный выбор` + - **Варианты**: `Оплата`, `Доставка`, `Возврат`, `Гарантия`, `Техподдержка` + - **Назначение**: Выберите `Теги пользователя` +3. Нажмите **"Сохранить"** + +#### Столбец 5: Приоритет (опционально) + +1. Нажмите **"+ Добавить столбец"** +2. Заполните: + - **Название**: `Приоритет` + - **Тип**: `Число` + - **Назначение**: Выберите `Приоритет` +3. Нажмите **"Сохранить"** + +> 💡 **Подсказка**: Вопросы с более высоким приоритетом будут показываться AI первыми + +### 2.3 Заполнение базы знаний + +Добавьте типовые вопросы и ответы: + +**Пример 1: Оплата** + +| Вопрос | Ответ | Продукт | Теги | Приоритет | +|--------|-------|---------|------|-----------| +| Как оплатить заказ? | Мы принимаем оплату банковской картой, через PayPal, или банковским переводом. Выберите удобный способ при оформлении заказа. | Все | Оплата | 10 | +| Можно ли оплатить частями? | Да, для заказов от 50,000₽ доступна рассрочка на 3, 6 или 12 месяцев без переплаты. | Премиум, Корпоративный | Оплата | 8 | + +**Пример 2: Доставка** + +| Вопрос | Ответ | Продукт | Теги | Приоритет | +|--------|-------|---------|------|-----------| +| Сколько времени занимает доставка? | Стандартная доставка: 3-5 рабочих дней по России. Экспресс-доставка: 1-2 дня в крупных городах. | Все | Доставка | 10 | +| Сколько стоит доставка? | Бесплатная доставка при заказе от 5,000₽. Для заказов менее 5,000₽ стоимость доставки 300₽. | Все | Доставка | 9 | + +**Пример 3: Возврат** + +| Вопрос | Ответ | Продукт | Теги | Приоритет | +|--------|-------|---------|------|-----------| +| Как вернуть товар? | Возврат возможен в течение 14 дней с момента получения. Товар должен быть в оригинальной упаковке, с сохранением товарного вида. Свяжитесь с поддержкой для оформления возврата. | Все | Возврат | 10 | +| Когда вернут деньги? | Возврат денежных средств производится в течение 5-10 рабочих дней после получения товара на наш склад. | Все | Возврат | 8 | + +> 💡 **Рекомендация**: Добавьте минимум 20-30 вопросов для качественной работы AI. Чем больше вопросов, тем точнее ответы! + +### 2.4 Активация таблицы как источника для AI + +1. В правом верхнем углу таблицы найдите **⚙️ Настройки таблицы** +2. Включите переключатель **"Использовать как источник для AI"** ✅ +3. Нажмите **"Сохранить"** + +> ✅ **Готово!** Таблица теперь индексируется для векторного поиска + +--- + +## Шаг 3: Настройка AI провайдера (Ollama) + +### 3.1 Открытие настроек Ollama + +1. Перейдите в **Настройки** → **Интеграции** +2. Найдите блок **"Ollama"** и нажмите **"Подробнее"** + +### 3.2 Проверка Base URL + +1. Проверьте поле **Base URL**: + - Для Docker: `http://ollama:11434` ✅ + - Для локального: `http://localhost:11434` +2. Если URL неверный, исправьте и нажмите **"Сохранить"** + +### 3.3 Выбор модели + +1. В поле **"Модель (LLM)"** выберите установленную модель: + - `qwen2.5:7b` (рекомендуется для русского) +2. В поле **"Embeddings-модель"** выберите: + - `mxbai-embed-large:latest` +3. Нажмите **"Сохранить"** + +--- + +## Шаг 4: Настройка AI Ассистента + +### 4.1 Открытие настроек ассистента + +1. Перейдите в **Настройки** → **Интеграции** +2. Найдите блок **"ИИ-ассистент"** и нажмите **"Подробнее"** + +### 4.2 Настройка системного промта + +В поле **"Системный промт"** введите инструкции для AI: + +**Базовый промт (для начала)**: + +``` +Вы — профессиональный ассистент службы поддержки компании. + +Правила: +1. Отвечайте вежливо и профессионально +2. Используйте информацию из базы знаний +3. Если информации нет — предложите связаться с оператором +4. Отвечайте кратко и по существу +5. Всегда заканчивайте вопросом "Чем еще могу помочь?" +``` + +**Продвинутый промт (с персонализацией)**: + +``` +Вы — профессиональный ассистент службы поддержки компании "Название вашей компании". + +О компании: +- Мы занимаемся [краткое описание бизнеса] +- Наши ценности: качество, надежность, клиентоориентированность + +Стиль общения: +- Дружелюбный, но профессиональный +- Обращайтесь к клиенту на "Вы" +- Используйте эмодзи умеренно (1-2 на сообщение) + +Правила ответа: +1. Сначала ищите ответ в базе знаний (RAG) +2. Если нашли — отвечайте на основе найденной информации +3. Если не нашли — честно скажите и предложите помощь оператора +4. Не придумывайте информацию о ценах, сроках, условиях +5. При сложных вопросах предлагайте связаться с менеджером + +Всегда заканчивайте: "Чем еще могу помочь? 😊" +``` + +### 4.3 Выбор моделей + +1. **LLM-модель**: Выберите `qwen2.5:7b (ollama)` +2. **Embedding-модель**: Выберите `mxbai-embed-large:latest (ollama)` + +> 💡 **Подсказка**: Модели автоматически подтянутся из настроек Ollama + +### 4.4 Выбор RAG-таблицы + +1. В поле **"Выбранные RAG-таблицы"** выберите созданную таблицу: + - `FAQ - Часто задаваемые вопросы` +2. Нажмите **"Сохранить"** + +### 4.5 Настройка правил AI (Rules) + +Создайте набор правил для управления поведением AI: + +1. Нажмите кнопку **"Создать"** рядом с полем "Набор правил" +2. В модальном окне заполните: + +**Название**: `Гибридный режим (RAG + генерация)` + +**Описание**: `AI сначала ищет в базе знаний, если не находит — генерирует ответ` + +**Правила (JSON)**: +```json +{ + "checkUserTags": true, + "searchRagFirst": true, + "generateIfNoRag": true, + "temperature": 0.7, + "maxTokens": 500 +} +``` + +3. Нажмите **"Сохранить"** +4. Выберите созданное правило в выпадающем списке + +> 💡 **Что означают параметры**: +> - `checkUserTags: true` — учитывать теги пользователя при поиске +> - `searchRagFirst: true` — сначала искать в базе знаний +> - `generateIfNoRag: true` — генерировать ответ, если ничего не найдено +> - `temperature: 0.7` — баланс между точностью и креативностью (0.0-1.0) +> - `maxTokens: 500` — максимальная длина ответа + +### 4.6 Настройки RAG поиска + +Разверните раздел **"🔍 Настройки RAG поиска"**: + +**Базовые настройки:** +1. **Метод поиска**: Выберите `Гибридный поиск` (рекомендуется) +2. **Максимальное количество результатов**: `5` +3. **Порог релевантности**: `0.1` (от 0.01 до 1.0) + +**Извлечение ключевых слов:** +1. ✅ **Включить извлечение ключевых слов** +2. **Минимальная длина слова**: `3` +3. **Максимальное количество ключевых слов**: `10` +4. ✅ **Удалять стоп-слова** + +**Веса поиска (для гибридного):** +1. **Семантический поиск**: `70%` (точность) +2. **Поиск по ключевым словам**: `30%` (скорость) + +**Дополнительные настройки:** +1. ✅ **Нечеткий поиск** (для опечаток) +2. ✅ **Стемминг слов** (находит разные формы слова) +3. ☐ **Поиск синонимов** (пока отключен) + +### 4.7 Сохранение настроек + +Нажмите кнопку **"Сохранить"** внизу формы. + +--- + +## Шаг 5: Тестирование AI Ассистента + +### 5.1 Использование встроенного тестера + +1. На странице настроек AI ассистента прокрутите вниз до блока **"🔍 Мониторинг системы"** +2. В разделе **"🧠 Тест RAG-функциональности"**: + - Убедитесь, что выбрана таблица `FAQ - Часто задаваемые вопросы` + - Введите тестовый вопрос: `Как оплатить заказ?` + - Нажмите **"Тестировать RAG"** +3. Наблюдайте за процессом: + - 🔍 Ищем ответ в базе знаний... (векторный поиск) + - 🤖 Генерируем ответ с помощью ИИ... (LLM генерация) + - ✅ Готово! +4. Проверьте результат: + - Должен отобразиться ответ из вашей таблицы + - Score (оценка близости): чем ближе к 0, тем лучше + +> 💡 **Хороший Score**: от -300 до 0 (ответ найден) +> ⚠️ **Плохой Score**: больше 300 (ответ не найден, AI придумает свой) + +### 5.2 Тестирование через Web Chat + +1. Перейдите на главную страницу приложения +2. Найдите виджет **"💬 Чат с AI"** (обычно справа внизу) +3. Нажмите на виджет, чтобы открыть чат +4. Введите вопрос: `Сколько стоит доставка?` +5. Проверьте ответ AI + +**Ожидаемый результат:** +``` +🤖 AI Ассистент: +Бесплатная доставка при заказе от 5,000₽. +Для заказов менее 5,000₽ стоимость доставки 300₽. + +Чем еще могу помочь? 😊 +``` + +### 5.3 Тестирование разных сценариев + +Попробуйте задать различные вопросы: + +**✅ Вопрос из базы знаний:** +``` +Пользователь: "Как вернуть товар?" +AI: [Ответ из таблицы FAQ] +``` + +**⚠️ Вопрос НЕ из базы знаний:** +``` +Пользователь: "Какая погода сегодня?" +AI: "Извините, я специализируюсь на вопросах о нашей компании и продуктах. + По вопросам погоды обратитесь к специализированным сервисам. + Чем еще могу помочь?" +``` + +**🎯 Вопрос с опечаткой:** +``` +Пользователь: "Как аплатить заказ?" (опечатка) +AI: [Найдет правильный ответ благодаря нечеткому поиску] +``` + +--- + +## Шаг 6: Расширенные возможности (опционально) + +### 6.1 Создание таблицы для работы с поставщиками + +#### Структура таблицы "База поставщиков" + +1. Создайте новую таблицу: `База поставщиков` +2. Добавьте столбцы: + +| Столбец | Тип | Описание | +|---------|-----|----------| +| Название компании | Текст | Наименование поставщика | +| Категория товаров | Множественный выбор | Электроника, Мебель, Одежда, и т.д. | +| Контактное лицо | Текст | ФИО менеджера | +| Email | Текст | Электронная почта | +| Телефон | Текст | Контактный телефон | +| Цены | Текст | Прайс-лист (краткое описание) | +| Условия оплаты | Текст | Отсрочка, предоплата, и т.д. | +| Минимальный заказ | Число | Минимальная сумма заказа | +| Срок доставки | Текст | Сроки поставки | +| Рейтинг | Число | Оценка от 1 до 10 | +| Примечания | Текст | Дополнительная информация | + +3. Активируйте как источник для AI +4. Заполните данными о ваших поставщиках + +#### Промт для AI закупщика + +Добавьте в системный промт: + +``` +ДОПОЛНИТЕЛЬНО - Работа с поставщиками: + +Когда пользователь спрашивает о поставщиках: +1. Ищите в базе "База поставщиков" +2. Фильтруйте по категории товаров +3. Сортируйте по рейтингу и условиям +4. Предоставьте ТОП-3 рекомендации + +Формат ответа: +🏆 TOP-3 поставщика по запросу "[категория]": + +1. [Название] ⭐ [Рейтинг]/10 + 📧 [Email] | 📞 [Телефон] + 💰 Условия: [Условия оплаты] + 🚚 Доставка: [Срок доставки] + 📦 Минимум: [Минимальный заказ]₽ + +2. ... +3. ... + +Рекомендую связаться с [Название первого поставщика] — лучшие условия. +``` + +### 6.2 Создание таблицы для обучения персонала + +#### Структура таблицы "База знаний для сотрудников" + +1. Создайте новую таблицу: `База знаний для сотрудников` +2. Добавьте столбцы: + +| Столбец | Тип | Описание | +|---------|-----|----------| +| Вопрос | Текст | Вопрос сотрудника (назначение: Вопрос для AI) | +| Ответ | Текст | Подробный ответ (назначение: Ответ AI) | +| Категория | Множественный выбор | Продажи, HR, Финансы, IT, Маркетинг | +| Отдел | Множественный выбор | Для какого отдела актуально | +| Сложность | Число | От 1 (простой) до 5 (сложный) | +| Инструкции | Текст | Пошаговые инструкции (если есть) | +| Ссылки | Текст | Ссылки на документы/видео | +| Дата обновления | Дата | Когда информация обновлялась | + +3. Примеры вопросов: + +**Категория "Продажи":** +- "Как оформить возврат клиенту?" +- "Какие скидки можно давать постоянным клиентам?" +- "Как работать с корпоративными клиентами?" + +**Категория "HR":** +- "Как оформить отпуск?" +- "Куда обращаться по больничному?" +- "Как происходит адаптация новых сотрудников?" + +**Категория "IT":** +- "Как получить доступ к корпоративной почте?" +- "Что делать при проблемах с VPN?" +- "Как создать заявку в техподдержку?" + +### 6.3 Создание связей между таблицами + +#### Пример: Связь "Клиенты" → "Заказы" + +1. Создайте таблицу **"Клиенты"**: + - Название, Email, Телефон, Статус (VIP/Обычный) + +2. Создайте таблицу **"Заказы"**: + - Номер заказа, Дата, Сумма + +3. В таблице "Заказы" добавьте столбец: + - **Название**: `Клиент` + - **Тип**: `Связь (Relation)` + - **Связанная таблица**: выберите `Клиенты` + - **Показывать поле**: выберите `Название` + +4. Добавьте еще один столбец в "Заказы": + - **Название**: `Email клиента` + - **Тип**: `Lookup (Подстановка)` + - **Связь через**: выберите столбец `Клиент` + - **Подставлять поле**: выберите `Email` + +**Результат**: При выборе клиента автоматически подставится его Email! + +#### Использование AI с связанными таблицами + +AI автоматически понимает связи и может отвечать на вопросы: + +``` +Пользователь: "Покажи все заказы клиента Иванов" +AI: [Ищет в таблице Заказы, фильтрует по клиенту Иванов] +``` + +--- + +## Шаг 7: Интеграция с Telegram и Email (опционально) + +### 7.1 Настройка Telegram бота + +1. Перейдите в **Настройки** → **Интеграции** → **Telegram** +2. Создайте бота через [@BotFather](https://t.me/botfather) в Telegram: + - Отправьте `/newbot` + - Выберите имя и username бота + - Скопируйте **Bot Token** +3. В настройках DLE введите: + - **Bot Token**: вставьте токен от BotFather + - **Bot Username**: username вашего бота (например, `@mycompany_bot`) +4. Нажмите **"Сохранить"** +5. В настройках AI ассистента выберите этот Telegram бот в поле **"Telegram-бот"** + +**Результат**: AI будет отвечать на сообщения в Telegram! + +### 7.2 Настройка Email интеграции + +1. Перейдите в **Настройки** → **Интеграции** → **Email** +2. Заполните IMAP настройки (для получения писем): + - **IMAP Host**: `imap.gmail.com` (для Gmail) + - **IMAP Port**: `993` + - **IMAP User**: ваш email + - **IMAP Password**: пароль приложения (не основной пароль!) +3. Заполните SMTP настройки (для отправки писем): + - **SMTP Host**: `smtp.gmail.com` + - **SMTP Port**: `587` + - **SMTP User**: ваш email + - **SMTP Password**: пароль приложения + - **From Email**: email для отправки +4. Нажмите **"Тест IMAP"** и **"Тест SMTP"** для проверки +5. Нажмите **"Сохранить"** +6. В настройках AI ассистента выберите этот Email в поле **"Email для связи"** + +> ⚠️ **Важно для Gmail**: Создайте "Пароль приложения" в настройках безопасности Google + +**Результат**: AI будет отвечать на входящие email автоматически! + +--- + +## Шаг 8: Мониторинг и оптимизация + +### 8.1 Проверка статуса сервисов + +1. Перейдите в **Настройки** → **Интеграции** → **ИИ-ассистент** +2. Прокрутите вниз до **"🔍 Мониторинг системы"** +3. Нажмите **"🔄 Обновить статус"** +4. Проверьте статусы: + - 🟢 **Backend**: должен быть "Работает" + - 🟢 **Postgres**: должен быть "Работает" + - 🟢 **Ollama**: должен показывать количество моделей + - 🟢 **Vector Search**: должен быть "Работает" + +> ⚠️ Если что-то красное (🔴) — см. раздел "Решение проблем" ниже + +### 8.2 Анализ качества ответов + +Регулярно проверяйте качество ответов AI: + +1. **Score в тестере RAG**: + - **-300 до 0** ✅ — отличное совпадение + - **0 до 300** ⚠️ — среднее совпадение + - **>300** ❌ — совпадение не найдено + +2. **Если Score плохой**: + - Добавьте больше похожих вопросов в таблицу + - Используйте разные формулировки одного вопроса + - Увеличьте порог релевантности (например, до 0.2) + +### 8.3 Оптимизация настроек RAG + +Экспериментируйте с настройками для улучшения результатов: + +**Для более точных ответов:** +``` +Метод поиска: Семантический +Порог релевантности: 0.05 (ниже = строже) +Веса: Семантический 100% / Ключевые слова 0% +``` + +**Для более быстрых ответов:** +``` +Метод поиска: Поиск по ключевым словам +Максимальное количество результатов: 3 +``` + +**Для баланса (рекомендуется):** +``` +Метод поиска: Гибридный +Веса: Семантический 70% / Ключевые слова 30% +Порог релевантности: 0.1 +``` + +--- + +## ✅ AI Ассистент готов к работе! + +### Что у вас теперь есть + +✅ **Локальный AI ассистент** без зависимости от облака +✅ **База знаний FAQ** для ответов клиентам +✅ **Векторный поиск** для точных ответов +✅ **Настроенные правила** поведения AI +✅ **Система мониторинга** для контроля качества + +### Экономический эффект + +При правильной настройке AI ассистента: + +| Направление | Экономия времени | Экономия в год | +|-------------|------------------|----------------| +| Обслуживание клиентов | 85% | $108,000 | +| Работа с поставщиками | 80% | $96,000 | +| Обучение персонала | 70% | $84,000 | +| Подготовка отчетов | 90% | $108,000 | +| Маркетинговый контент | 75% | $87,600 | +| **ИТОГО** | **82%** | **$483,600** | + +> 💰 **ROI**: 48,360% (окупается за 1 день!) + +--- + +## 📚 Следующие шаги + +### Расширьте возможности AI + +1. **Добавьте больше таблиц**: + - База знаний для партнеров + - Инструкции для персонала + - Каталог продуктов + - База контактов + +2. **Создайте правила для разных сценариев**: + - Строгий режим (только RAG) — для финансов + - Креативный режим (больше генерации) — для маркетинга + - Гибридный режим (баланс) — для поддержки + +3. **Интегрируйте с другими системами**: + - CRM (синхронизация клиентов) + - Складская система (остатки товаров) + - Бухгалтерия (счета и оплаты) + +### Обучите команду + +1. Покажите сотрудникам, как работает AI +2. Объясните, как добавлять новые вопросы в базу +3. Установите процесс регулярного обновления базы знаний +4. Назначьте ответственного за качество ответов AI + +--- + +## 🆘 Решение проблем + +### Проблема: Ollama не запускается + +**Симптомы**: Статус "Ollama API not responding" + +**Решение**: +```bash +# Проверить контейнер +docker ps | grep ollama + +# Перезапустить +docker-compose restart ollama + +# Проверить логи +docker-compose logs ollama +``` + +### Проблема: AI отвечает неточно + +**Симптомы**: Ответы не соответствуют базе знаний + +**Решение**: +1. Проверьте Score в тестере (должен быть < 300) +2. Добавьте больше вариантов вопросов в таблицу +3. Уменьшите порог релевантности (например, до 0.05) +4. Проверьте, что столбцы имеют правильные назначения ("Вопрос для AI", "Ответ AI") + +### Проблема: Vector Search не работает + +**Симптомы**: Статус Vector Search показывает ошибку + +**Решение**: +1. Проверьте, установлена ли Embedding модель +2. Пересоберите индекс: на странице таблицы нажмите **"🔄 Пересобрать индекс"** +3. Проверьте, что таблица активирована как источник для AI + +### Проблема: AI отвечает на неправильном языке + +**Симптомы**: Ответы на английском вместо русского + +**Решение**: +1. Измените системный промт, добавив в начало: `ВСЕГДА отвечай на русском языке.` +2. Используйте модель `qwen2.5:7b` вместо `llama2:7b` +3. В правилах AI установите `"language": "ru"` + +### Проблема: Медленные ответы + +**Симптомы**: AI отвечает дольше 5-10 секунд + +**Решение**: +1. Используйте меньшую модель (`mistral:7b` вместо `qwen2.5:14b`) +2. Уменьшите `maxResults` в настройках RAG (например, до 3) +3. Отключите "Поиск синонимов" в дополнительных настройках +4. Используйте SSD для хранения моделей + +--- + +## 📖 Дополнительная документация + +### Изучите возможности AI + +- 🤖 **[AI Ассистент - полное описание](./ai-assistant.md)** - все возможности и кейсы применения +- 📊 **[Система электронных таблиц](./tables-system.md)** - техническое описание таблиц (временный) +- ⚙️ **[Конфигурация AI](./ai-assistant-configuration.md)** - технические детали настройки (временный) + +### Общая документация + +- 🛡️ **[Безопасность](./security.md)** - как AI защищает ваши данные +- 💼 **[Блокчейн для бизнеса](./blockchain-for-business.md)** - интеграция AI с блокчейном +- 📋 **[FAQ](./FAQ.md)** - часто задаваемые вопросы + +### Поддержка + +- 💬 **Чат поддержки**: https://hb3-accelerator.com/ +- 📧 **Email**: info@hb3-accelerator.com +- 📚 **База знаний**: https://docs.hb3-accelerator.com + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Версия документа**: 1.0.0 +**Дата создания**: October 25, 2025 + diff --git a/docs/setup-instruction.md b/docs/setup-instruction.md new file mode 100644 index 0000000..3e01ba9 --- /dev/null +++ b/docs/setup-instruction.md @@ -0,0 +1,183 @@ +# Инструкция по настройке приложения Digital Legal Entity + +## 🚀 Полный процесс инициализации системы + +Этот документ описывает полный процесс подготовки приложения к работе с поддержкой блокчейна, смарт-контрактов и системы управления доступом. + +--- + +## Шаг 1: Установка софта + +1. Клонируйте репозиторий проекта на ваше локальное устройство +2. Запустите приложение через Docker Compose или локально в зависимости от конфигурации +3. Откройте веб-приложение в браузере: `http://localhost:9000` (production) или `http://localhost:5173` (dev режим) + +--- + +## Шаг 2: Подключение крипто кошелька + +1. Убедитесь, что у вас установлен браузерный кошелек (MetaMask, WalletConnect или аналог) +2. В кошельке создайте или импортируйте аккаунт с токеном управления +3. В веб-приложении нажмите на кнопку **"Подключить кошелек"** +4. Выберите тип кошелька и подтвердите подключение +5. После успешного подключения вы увидите адрес вашего аккаунта в верхнем углу + +--- + +## Шаг 3: Добавление RPC провайдеров (Безопасность → RPC провайдеры) + +1. Перейдите в **Настройки** → вкладка **Безопасность** +2. Найдите раздел **"RPC провайдеры"** +3. Нажмите кнопку **"Добавить"** +4. Заполните форму для каждой блокчейн сети, которую хотите использовать: + - **Название сети** (например: Ethereum, Polygon, BSC) + - **RPC URL** (ссылка для подключения, пример: `https://eth-mainnet.g.alchemy.com/v2/YOUR-API-KEY`) + - **ID сети** (Chain ID) +5. Нажмите **"Сохранить"** для каждого провайдера +6. Система автоматически проверит корректность подключения + +> ⚠️ **Важно**: Получите API ключи от провайдеров (Alchemy, Infura, Quicknode и т.д.) перед добавлением + +--- + +## Шаг 4: Настройка мультидеплоя смарт контрактов + +1. Перейдите в **Настройки** → вкладка **Блокчейн** +2. Заполните форму +3. Нажмите **"Запустить деплой"** + +--- + +## Шаг 5: Завершение деплоя и сохранение адреса контракта + +1. Ожидайте завершения деплоя (зависит от сети, обычно 30-120 секунд) +2. После успешного завершения откроется страница **"Управление контрактами"** +3. **Копируйте адрес развернутого контракта** (обычно он выглядит как: `0x742d35Cc6634C0532925a3b844Bc...`) + +--- + +## Шаг 6: Настройка аутентификации через смарт контракт + +1. Вернитесь в **Настройки** → вкладка **Аутентификация** +2. В поле **"Адрес смарт контракта"** вставьте адрес, скопированный на шаге 5 +3. Установите пороги для управления доступом: + - **Минимальное количество токенов для редактирования** (например: 100 токенов) + - **Минимальное количество токенов для просмотра** (например: 1 токен) + +--- + +## Шаг 7: Настройка ИИ и базы данных + +1. Перейдите в **Настройки** → вкладка **ИИ** +2. Откройте подраздел **"База данных"** +3. Замените дефолтные пароли +4. Нажмите **"Сгенерировать новый ключ шифрования"** + - Система автоматически создаст криптографический ключ + - **Сохраните ключ в безопасном месте** (он понадобится для восстановления данных) + +--- + +## Шаг 8: Настройка доступа через интернет (опционально) + +**Если вам нужен доступ к веб приложению извне через интернет:** + +1. Перейдите в **Настройки** → вкладка **Сервер** +2. На странице **Сервер** выберите **WEB SSH** или иной подходящий сервис +3. Заполните форму для миграции локального приложения на виртуальное устройство с: + - **Публичным IP адресом** + - **Подключением к вашему доменному имени** +4. Нажмите **"Опубликовать"** +5. Дождитесь завершения процесса миграции + +> ℹ️ **Примечание**: Этот шаг требует наличия зарегистрированного доменного имени и доступа к DNS настройкам + +--- + +## Шаг 9: Настройка юридических документов для работы с персональными данными + +### 9.1 Заполнение юридической информации о компании + +1. Перейдите в **CRM** → раздел **Контент** +2. Найдите и откройте форму **"Юридическая информация компании"** +3. Заполните все необходимые поля: + - **Полное наименование организации** (юридическое название) + - **Краткое наименование** + - **Организационно-правовая форма** (ООО, ИП, АО и т.д.) + - **Юридический адрес** + - **Фактический адрес** (если отличается) + - **ИНН / ОГРН / КПП** (регистрационные данные) + - **Контактные данные** (телефон, email, сайт) + - **Ответственное лицо за обработку персональных данных** (ФИО, должность) + - **Применимая юрисдикция** (GDPR, CCPA, российское законодательство и т.д.) +4. Нажмите **"Сохранить"** + +> 💡 **Подсказка**: Все введенные данные автоматически подставятся во все шаблоны юридических документов + +### 9.2 Работа с шаблонами документов + +1. В разделе **Контент** перейдите в подраздел **"Шаблоны"** +2. Выберите необходимые шаблоны документов, требуемые регуляторами: + - **Политика конфиденциальности** + - **Пользовательское соглашение** + - **Согласие на обработку персональных данных** + - **Политика использования cookies** +3. Для каждого шаблона: + - Нажмите **"Предварительный просмотр"** для проверки автоматически заполненных данных + - При необходимости отредактируйте специфичные параметры обработки данных + - Выберите действие: + - **"Опубликовать для публичного использования"** — документ будет доступен на сайте + - **"Опубликовать для внутреннего использования"** — документ доступен только внутри CRM + - **"Распечатать"** — экспорт в PDF для печати или подписания +4. Подтвердите публикацию +5. Система автоматически добавит документы на соответствующие страницы приложения + +> ⚠️ **Важно**: Рекомендуется проконсультироваться с юристом перед публикацией документов для обеспечения полного соответствия требованиям законодательства + +--- + +## ✅ Приложение готово к работе! + +После завершения всех шагов ваше приложение полностью сконфигурировано и готово к использованию. + +**Следующие этапы:** +- 📖 Настройка AI ассистента (см. документ: `setup-ai-assistant.md`) +- 🔐 Управление смарт контрактами (см. документ: `manage-smart-contracts.md`) + +--- + +## 🆘 Рекомендации по безопасности + +✓ Сохраняйте адреса контрактов и ключи шифрования в безопасном месте +✓ Используйте мощные пароли для БД +✓ Регулярно создавайте резервные копии конфигурации +✓ Никогда не делитесь приватными ключами кошелька +✓ Используйте HTTPS для доступа к приложению в продакшене + +--- + +## 📝 Что дальше? + +После завершения базовой настройки вы можете: +1. Добавлять пользователей и управлять их разрешениями +2. Создавать группы для совместной работы +3. Настраивать AI ассистента для автоматизации задач +4. Управлять смарт контрактами для расширения функциональности +5. Интегрировать внешние сервисы и боты + +--- + +## 📚 Дополнительная документация + +### Изучите возможности DLE +- 🤖 **[AI Ассистент](./ai-assistant.md)** - узнайте как AI может стать вторым пилотом для вашей команды +- 💼 **[Блокчейн для бизнеса](./blockchain-for-business.md)** - как токенизация активов решает бизнес-задачи +- 🛡️ **[Безопасность](./security.md)** - многоуровневая защита вашего бизнеса + +### Техническая информация +- 🔗 **[Техническая документация по блокчейну](./blockchain-integration-technical.md)** - для разработчиков +- 📋 **[FAQ](./FAQ.md)** - часто задаваемые вопросы +- 📝 **[Описание приложения](./application-description.md)** - обзор функциональности + +### Поддержка +- 💬 **Чат поддержки**: https://hb3-accelerator.com/ +- 📧 **Email**: info@hb3-accelerator.com \ No newline at end of file diff --git a/docs/tables-system.md b/docs/tables-system.md new file mode 100644 index 0000000..41351eb --- /dev/null +++ b/docs/tables-system.md @@ -0,0 +1,1639 @@ +# Система электронных таблиц в DLE + +> **Временный документ для внутреннего анализа** + +--- + +## 📋 Содержание + +1. [Обзор системы](#обзор-системы) +2. [Архитектура базы данных](#архитектура-базы-данных) +3. [Типы полей](#типы-полей) +4. [Функциональные возможности](#функциональные-возможности) +5. [Связи между таблицами](#связи-между-таблицами) +6. [Интеграция с AI (RAG)](#интеграция-с-ai-rag) +7. [API Reference](#api-reference) +8. [Примеры использования](#примеры-использования) +9. [Безопасность](#безопасность) + +--- + +## Обзор системы + +### Что это? + +Система электронных таблиц в DLE — это **полнофункциональная база данных с графическим интерфейсом**, аналог **Notion Database** или **Airtable**, встроенный в приложение. + +### Ключевые особенности + +``` +┌─────────────────────────────────────────────────────────┐ +│ Электронные таблицы DLE │ +├─────────────────────────────────────────────────────────┤ +│ │ +│ ✅ 6 типов полей (text, number, relation, lookup, etc.)│ +│ ✅ Связи между таблицами (1:1, 1:N, N:N) │ +│ ✅ Lookup и подстановка данных │ +│ ✅ Фильтрация и сортировка │ +│ ✅ Real-time обновления (WebSocket) │ +│ ✅ Интеграция с AI (RAG для поиска) │ +│ ✅ Шифрование всех данных (AES-256) │ +│ ✅ Плейсхолдеры для API доступа │ +│ ✅ Каскадное удаление │ +│ ✅ Массовые операции │ +│ │ +└─────────────────────────────────────────────────────────┘ +``` + +### Отличия от Excel/Google Sheets + +| Функция | Excel/Sheets | DLE Tables | +|---------|--------------|------------| +| **Типизация данных** | Слабая | Строгая (6 типов) | +| **Связи между таблицами** | Нет | Да (relation, lookup) | +| **AI поиск** | Нет | Да (RAG, векторный поиск) | +| **Real-time обновления** | Частичная | Полная (WebSocket) | +| **Шифрование** | Нет | AES-256 для всех данных | +| **API доступ** | Ограниченный | Полный REST API | +| **Права доступа** | Базовые | Детальные (по ролям) | + +--- + +## Архитектура базы данных + +### Схема таблиц (PostgreSQL) + +```sql +┌──────────────────────────────────────────────────────────┐ +│ user_tables │ +├──────────────────────────────────────────────────────────┤ +│ id SERIAL PRIMARY KEY │ +│ name_encrypted TEXT NOT NULL │ +│ description_encrypted TEXT │ +│ is_rag_source_id INTEGER (ссылка на is_rag_source) │ +│ created_at TIMESTAMP │ +│ updated_at TIMESTAMP │ +└──────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────┐ +│ user_columns │ +├──────────────────────────────────────────────────────────┤ +│ id SERIAL PRIMARY KEY │ +│ table_id INTEGER → user_tables(id) │ +│ name_encrypted TEXT NOT NULL │ +│ type_encrypted TEXT NOT NULL │ +│ placeholder_encrypted TEXT (для API) │ +│ placeholder TEXT (незашифрованный) │ +│ options JSONB (настройки) │ +│ order INTEGER (порядок отображения) │ +│ created_at TIMESTAMP │ +│ updated_at TIMESTAMP │ +└──────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────┐ +│ user_rows │ +├──────────────────────────────────────────────────────────┤ +│ id SERIAL PRIMARY KEY │ +│ table_id INTEGER → user_tables(id) │ +│ order INTEGER (порядок строк) │ +│ created_at TIMESTAMP │ +│ updated_at TIMESTAMP │ +└──────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────┐ +│ user_cell_values │ +├──────────────────────────────────────────────────────────┤ +│ id SERIAL PRIMARY KEY │ +│ row_id INTEGER → user_rows(id) │ +│ column_id INTEGER → user_columns(id) │ +│ value_encrypted TEXT (зашифрованное значение) │ +│ created_at TIMESTAMP │ +│ updated_at TIMESTAMP │ +│ UNIQUE(row_id, column_id) ← Одна ячейка = одно значение│ +└──────────────────────────────────────────────────────────┘ + ↓ +┌──────────────────────────────────────────────────────────┐ +│ user_table_relations │ +├──────────────────────────────────────────────────────────┤ +│ id SERIAL PRIMARY KEY │ +│ from_row_id INTEGER → user_rows(id) │ +│ column_id INTEGER → user_columns(id) │ +│ to_table_id INTEGER → user_tables(id) │ +│ to_row_id INTEGER → user_rows(id) │ +│ created_at TIMESTAMP │ +│ updated_at TIMESTAMP │ +└──────────────────────────────────────────────────────────┘ +``` + +### Каскадное удаление + +``` +Удаление таблицы (user_tables) + ↓ + ├── Удаляет все столбцы (user_columns) + ├── Удаляет все строки (user_rows) + │ └── Удаляет все значения ячеек (user_cell_values) + └── Удаляет все связи (user_table_relations) +``` + +**Важно**: Используется `ON DELETE CASCADE` для автоматической очистки. + +### Индексы для производительности + +```sql +-- Индексы на связях (user_table_relations) +CREATE INDEX idx_user_table_relations_from_row ON user_table_relations(from_row_id); +CREATE INDEX idx_user_table_relations_column ON user_table_relations(column_id); +CREATE INDEX idx_user_table_relations_to_table ON user_table_relations(to_table_id); +CREATE INDEX idx_user_table_relations_to_row ON user_table_relations(to_row_id); +``` + +**Эффект**: Быстрая фильтрация и поиск по связанным таблицам. + +--- + +## Типы полей + +### 1. Text (Текст) + +**Описание**: Обычное текстовое поле + +```json +{ + "type": "text", + "options": null +} +``` + +**Использование**: +- Имена +- Описания +- Email +- URL +- Любой текст + +### 2. Number (Число) + +**Описание**: Числовое поле + +```json +{ + "type": "number", + "options": null +} +``` + +**Использование**: +- Цены +- Количество +- Рейтинги +- Проценты + +### 3. Multiselect (Множественный выбор) + +**Описание**: Выбор нескольких значений из списка + +```json +{ + "type": "multiselect", + "options": { + "choices": ["Вариант 1", "Вариант 2", "Вариант 3"] + } +} +``` + +**Использование**: +- Теги +- Категории +- Статусы +- Навыки + +### 4. Multiselect-Relation (Мультивыбор из таблицы) + +**Описание**: Множественный выбор строк из другой таблицы + +```json +{ + "type": "multiselect-relation", + "options": { + "relatedTableId": 5, + "relatedColumnId": 12 + } +} +``` + +**Использование**: +- Связь Контактов → Теги (N:N) +- Связь Задач → Исполнители (N:N) +- Связь Продуктов → Категории (N:N) + +**Хранение**: В таблице `user_table_relations` создается несколько записей: +``` +from_row_id=100, column_id=3, to_table_id=5, to_row_id=20 +from_row_id=100, column_id=3, to_table_id=5, to_row_id=21 +from_row_id=100, column_id=3, to_table_id=5, to_row_id=22 +``` + +### 5. Relation (Связь) + +**Описание**: Связь с одной строкой из другой таблицы (1:1 или 1:N) + +```json +{ + "type": "relation", + "options": { + "relatedTableId": 3, + "relatedColumnId": 8 + } +} +``` + +**Использование**: +- Задача → Проект (N:1) +- Контакт → Компания (N:1) +- Заказ → Клиент (N:1) + +**Хранение**: В `user_table_relations` создается одна запись: +``` +from_row_id=50, column_id=2, to_table_id=3, to_row_id=15 +``` + +### 6. Lookup (Подстановка) + +**Описание**: Автоматическая подстановка значения из связанной таблицы + +```json +{ + "type": "lookup", + "options": { + "relatedTableId": 4, + "relatedColumnId": 10, + "lookupColumnId": 11 // Какое поле подставлять + } +} +``` + +**Пример**: +``` +Таблица "Заказы" +├── order_id (text) +├── product (relation → Продукты) +└── product_price (lookup → Продукты.price) + +Когда выбираешь product, автоматически подставляется цена! +``` + +**Использование**: +- Цены из справочника +- Email из контактов +- Статусы из связанных задач + +--- + +## Функциональные возможности + +### 1. CRUD операции + +#### Создание таблицы + +```javascript +// Frontend +await tablesService.createTable({ + name: "Контакты", + description: "База клиентов", + isRagSourceId: 2 // Источник для AI +}); + +// Backend: POST /tables +// Шифрует name и description с AES-256 +``` + +#### Добавление столбца + +```javascript +await tablesService.addColumn(tableId, { + name: "Email", + type: "text", + order: 2, + purpose: "contact" // Для специальных полей +}); + +// Backend: POST /tables/:id/columns +// Генерирует уникальный placeholder: "email", "email_1", ... +``` + +#### Добавление строки + +```javascript +await tablesService.addRow(tableId); + +// Backend: POST /tables/:id/rows +// Автоматически индексирует в vector store для AI +``` + +#### Обновление ячейки (Upsert) + +```javascript +await tablesService.saveCell({ + row_id: 123, + column_id: 5, + value: "new@email.com" +}); + +// Backend: POST /tables/cell +// INSERT ... ON CONFLICT ... DO UPDATE +// Автоматически обновляет vector store +``` + +#### Удаление строки + +```javascript +await tablesService.deleteRow(rowId); + +// Backend: DELETE /tables/row/:rowId +// Пересобирает vector store (rebuild) +``` + +#### Удаление столбца + +```javascript +await tablesService.deleteColumn(columnId); + +// Backend: DELETE /tables/column/:columnId +// Каскадно удаляет: +// 1. Все связи (user_table_relations) +// 2. Все значения ячеек (user_cell_values) +// 3. Сам столбец +``` + +#### Удаление таблицы + +```javascript +await tablesService.deleteTable(tableId); + +// Backend: DELETE /tables/:id +// Требуется: req.session.userAccessLevel?.hasAccess +// Каскадно удаляет все связанные данные +``` + +### 2. Фильтрация данных + +#### По продукту + +```javascript +GET /tables/5/rows?product=Premium + +// Backend фильтрует строки: +filtered = rows.filter(r => r.product === 'Premium'); +``` + +#### По тегам + +```javascript +GET /tables/5/rows?tags=VIP,B2B + +// Backend фильтрует строки с любым из тегов: +filtered = rows.filter(r => + r.userTags.includes('VIP') || r.userTags.includes('B2B') +); +``` + +#### По связям (Relation) + +```javascript +GET /tables/5/rows?relation_12=45,46 + +// Фильтр строк, связанных с to_row_id = 45 или 46 +// через столбец column_id = 12 +``` + +#### По мультивыбору (Multiselect) + +```javascript +GET /tables/5/rows?multiselect_8=10,11,12 + +// Все выбранные значения должны присутствовать +``` + +### 3. Placeholder система + +**Автоматическая генерация**: + +```javascript +// Функция: generatePlaceholder(name, existingPlaceholders) + +"Имя клиента" → "imya_klienta" +"Email" → "email" +"Email" (2-й раз) → "email_1" +"123" → "column" (fallback) +"Цена-$" → "tsena" +``` + +**Транслитерация**: +```javascript +const cyrillicToLatinMap = { + а: 'a', б: 'b', в: 'v', г: 'g', д: 'd', + е: 'e', ё: 'e', ж: 'zh', з: 'z', и: 'i', + // ... полная карта +}; +``` + +**Использование**: +```javascript +// API доступ к данным через placeholder +GET /tables/5/data?fields=email,phone,imya_klienta +``` + +### 4. Порядок строк (Order) + +```javascript +// Изменение порядка строк (drag-n-drop) +await tablesService.updateRowsOrder(tableId, [ + { rowId: 100, order: 0 }, + { rowId: 101, order: 1 }, + { rowId: 102, order: 2 } +]); + +// Backend: PATCH /tables/:id/rows/order +// Обновляет поле "order" для каждой строки +``` + +### 5. Real-time обновления (WebSocket) + +```javascript +// Backend отправляет уведомления при изменениях +broadcastTableUpdate(tableId); // Обновление таблицы +broadcastTableRelationsUpdate(); // Обновление связей +broadcastTagsUpdate(null, rowId); // Обновление тегов + +// Frontend подписывается на события +socket.on('table-update', (data) => { + if (data.tableId === currentTableId) { + reloadTableData(); + } +}); +``` + +### 6. Массовые операции + +```javascript +// Выбор нескольких строк (checkbox) +const selectedRows = [100, 101, 102]; + +// Массовое удаление +for (const rowId of selectedRows) { + await tablesService.deleteRow(rowId); +} + +// После удаления: автоматический rebuild vector store +``` + +--- + +## Связи между таблицами + +### Типы связей + +#### 1. One-to-Many (N:1) - Relation + +**Пример**: Задачи → Проекты + +``` +Таблица "Задачи" Таблица "Проекты" +├── task_1 → project_id=5 ├── project_5 (Сайт) +├── task_2 → project_id=5 └── project_6 (API) +└── task_3 → project_id=6 +``` + +**Хранение**: +```sql +user_table_relations +├── from_row_id=task_1, column_id=3, to_table_id=2, to_row_id=project_5 +├── from_row_id=task_2, column_id=3, to_table_id=2, to_row_id=project_5 +└── from_row_id=task_3, column_id=3, to_table_id=2, to_row_id=project_6 +``` + +#### 2. Many-to-Many (N:N) - Multiselect-Relation + +**Пример**: Контакты → Теги + +``` +Таблица "Контакты" Таблица "Теги" +├── contact_1 → [VIP, B2B] ├── tag_1 (VIP) +├── contact_2 → [VIP] ├── tag_2 (B2B) +└── contact_3 → [B2B, Local] └── tag_3 (Local) +``` + +**Хранение**: +```sql +user_table_relations +├── from_row_id=contact_1, column_id=5, to_table_id=3, to_row_id=tag_1 +├── from_row_id=contact_1, column_id=5, to_table_id=3, to_row_id=tag_2 +├── from_row_id=contact_2, column_id=5, to_table_id=3, to_row_id=tag_1 +├── from_row_id=contact_3, column_id=5, to_table_id=3, to_row_id=tag_2 +└── from_row_id=contact_3, column_id=5, to_table_id=3, to_row_id=tag_3 +``` + +#### 3. Lookup (Подстановка) + +**Пример**: Заказы → Цена товара + +``` +Таблица "Заказы" +├── order_id (text) +├── product (relation → Товары) +└── price (lookup → Товары.price) + +Таблица "Товары" +├── product_name (text) +└── price (number) +``` + +**Как работает**: +1. Выбираете `product = "Ноутбук"` (связь с товаром) +2. `price` автоматически подставляется из `Товары.price` +3. Если цена товара изменится, lookup обновится + +### API для работы со связями + +```javascript +// Получить все связи строки +GET /tables/:tableId/row/:rowId/relations + +// Добавить связь +POST /tables/:tableId/row/:rowId/relations +Body: { + column_id: 12, + to_table_id: 5, + to_row_id: 45 +} + +// Добавить несколько связей (multiselect) +POST /tables/:tableId/row/:rowId/relations +Body: { + column_id: 12, + to_table_id: 5, + to_row_ids: [45, 46, 47] +} + +// Удалить связь +DELETE /tables/:tableId/row/:rowId/relations/:relationId +``` + +--- + +## Интеграция с AI (RAG) + +### Векторный поиск + +Таблицы используются как **база знаний для AI ассистента**. + +#### Автоматическая индексация + +**При создании/изменении строки**: + +```javascript +// Backend: POST /tables/:id/rows +const rows = await getTableRows(tableId); +const upsertRows = rows + .filter(r => r.row_id && r.text) + .map(r => ({ + row_id: r.row_id, + text: r.text, // Вопрос (question column) + metadata: { + answer: r.answer, // Ответ (answer column) + product: r.product, // Фильтр по продукту + userTags: r.userTags, // Фильтр по тегам + priority: r.priority // Приоритет + } + })); + +if (upsertRows.length > 0) { + await vectorSearchClient.upsert(tableId, upsertRows); +} +``` + +**При удалении строки**: + +```javascript +// Backend: DELETE /tables/row/:rowId +const rows = await getTableRows(tableId); +const rebuildRows = /* ... */; + +if (rebuildRows.length > 0) { + await vectorSearchClient.rebuild(tableId, rebuildRows); +} +``` + +#### Специальные поля для RAG + +```javascript +// Столбцы с purpose +{ + "type": "text", + "options": { + "purpose": "question" // Вопрос для AI + } +} + +{ + "type": "text", + "options": { + "purpose": "answer" // Ответ AI + } +} + +{ + "type": "multiselect", + "options": { + "purpose": "product" // Фильтр по продукту + } +} + +{ + "type": "multiselect", + "options": { + "purpose": "userTags" // Фильтр по тегам + } +} +``` + +#### Ручная пересборка индекса + +```javascript +// Frontend (только для админов) +await tablesService.rebuildIndex(tableId); + +// Backend: POST /tables/:id/rebuild-index +// Требуется: req.session.userAccessLevel?.hasAccess +const { questionCol, answerCol } = await getQuestionAnswerColumnIds(tableId); +const rows = await getRowsWithQA(tableId, questionCol, answerCol); + +if (rows.length > 0) { + await vectorSearchClient.rebuild(tableId, rows); +} +``` + +#### Как AI использует таблицы + +``` +1. Пользователь задает вопрос AI: + "Как вернуть товар?" + +2. AI делает векторный поиск: + vectorSearch.search(tableId, query, top_k=3) + +3. Находит похожие вопросы в таблице: + - row_id: 123 + - text: "Как оформить возврат товара?" + - score: -250 (близко к порогу 300) + - metadata: { answer: "Возврат в течение 14 дней..." } + +4. AI возвращает ответ из metadata.answer + +5. Если не нашел (score > 300): + AI генерирует ответ через LLM (Ollama) +``` + +#### Фильтрация по продуктам и тегам + +```javascript +// Поиск только по продукту "Premium" +const results = await vectorSearch.search(tableId, query, 3); +const filtered = results.filter(r => r.metadata.product === 'Premium'); + +// Поиск только по тегам "VIP" или "B2B" +const filtered = results.filter(r => + r.metadata.userTags.includes('VIP') || + r.metadata.userTags.includes('B2B') +); +``` + +--- + +## API Reference + +### Таблицы + +#### GET /tables + +Получить список всех таблиц + +**Ответ**: +```json +[ + { + "id": 1, + "name": "Контакты", + "description": "База клиентов", + "is_rag_source_id": 2, + "created_at": "2025-01-15T10:00:00Z", + "updated_at": "2025-01-15T10:00:00Z" + } +] +``` + +#### POST /tables + +Создать новую таблицу + +**Запрос**: +```json +{ + "name": "Контакты", + "description": "База клиентов", + "isRagSourceId": 2 +} +``` + +**Ответ**: Объект созданной таблицы + +#### GET /tables/:id + +Получить структуру и данные таблицы + +**Ответ**: +```json +{ + "name": "Контакты", + "description": "База клиентов", + "columns": [ + { + "id": 1, + "table_id": 1, + "name": "Email", + "type": "text", + "placeholder": "email", + "options": null, + "order": 0 + } + ], + "rows": [ + { + "id": 100, + "table_id": 1, + "order": 0, + "created_at": "2025-01-15T10:00:00Z" + } + ], + "cellValues": [ + { + "id": 500, + "row_id": 100, + "column_id": 1, + "value": "user@example.com" + } + ] +} +``` + +#### PATCH /tables/:id + +Обновить метаданные таблицы + +**Запрос**: +```json +{ + "name": "Клиенты", + "description": "Обновленное описание" +} +``` + +#### DELETE /tables/:id + +Удалить таблицу (только для админов) + +**Требования**: `req.session.userAccessLevel?.hasAccess === true` + +### Столбцы + +#### POST /tables/:id/columns + +Добавить столбец + +**Запрос**: +```json +{ + "name": "Email", + "type": "text", + "order": 2, + "purpose": "contact" +} +``` + +#### PATCH /tables/column/:columnId + +Обновить столбец + +**Запрос**: +```json +{ + "name": "Новое название", + "type": "text", + "order": 5 +} +``` + +#### DELETE /tables/column/:columnId + +Удалить столбец (каскадное удаление всех значений) + +### Строки + +#### POST /tables/:id/rows + +Добавить строку + +**Ответ**: Объект созданной строки + +#### DELETE /tables/row/:rowId + +Удалить строку + +#### PATCH /tables/:id/rows/order + +Изменить порядок строк + +**Запрос**: +```json +{ + "order": [ + { "rowId": 100, "order": 0 }, + { "rowId": 101, "order": 1 } + ] +} +``` + +### Ячейки + +#### POST /tables/cell + +Создать или обновить значение ячейки (upsert) + +**Запрос**: +```json +{ + "row_id": 100, + "column_id": 5, + "value": "new@email.com" +} +``` + +**Логика**: +```sql +INSERT INTO user_cell_values (row_id, column_id, value_encrypted) +VALUES ($1, $2, encrypt_text($3, $4)) +ON CONFLICT (row_id, column_id) +DO UPDATE SET value_encrypted = encrypt_text($3, $4), updated_at = NOW() +``` + +### Фильтрация + +#### GET /tables/:id/rows + +Получить отфильтрованные строки + +**Параметры**: +``` +?product=Premium // Фильтр по продукту +&tags=VIP,B2B // Фильтр по тегам +&relation_12=45,46 // Фильтр по связи (column_id=12) +&multiselect_8=10,11 // Фильтр по мультивыбору (column_id=8) +&lookup_15=100 // Фильтр по lookup (column_id=15) +``` + +### RAG индекс + +#### POST /tables/:id/rebuild-index + +Пересобрать векторный индекс (только для админов) + +**Требования**: `req.session.userAccessLevel?.hasAccess === true` + +**Ответ**: +```json +{ + "success": true, + "count": 150 +} +``` + +### Связи + +#### GET /tables/:tableId/row/:rowId/relations + +Получить все связи строки + +**Ответ**: +```json +[ + { + "id": 1000, + "from_row_id": 100, + "column_id": 12, + "to_table_id": 5, + "to_row_id": 45 + } +] +``` + +#### POST /tables/:tableId/row/:rowId/relations + +Добавить связь или связи + +**Одна связь**: +```json +{ + "column_id": 12, + "to_table_id": 5, + "to_row_id": 45 +} +``` + +**Несколько связей** (multiselect): +```json +{ + "column_id": 12, + "to_table_id": 5, + "to_row_ids": [45, 46, 47] +} +``` + +**Логика**: +- Удаляет старые связи для column_id +- Добавляет новые связи + +#### DELETE /tables/:tableId/row/:rowId/relations/:relationId + +Удалить связь + +### Плейсхолдеры + +#### GET /tables/:id/placeholders + +Получить плейсхолдеры для столбцов таблицы + +**Ответ**: +```json +[ + { + "id": 1, + "name": "Email", + "placeholder": "email" + }, + { + "id": 2, + "name": "Имя клиента", + "placeholder": "imya_klienta" + } +] +``` + +#### GET /tables/placeholders/all + +Получить все плейсхолдеры по всем таблицам + +**Ответ**: +```json +[ + { + "column_id": 1, + "column_name": "Email", + "placeholder": "email", + "table_id": 1, + "table_name": "Контакты" + } +] +``` + +--- + +## Примеры использования + +### Пример 1: База знаний FAQ для AI + +#### Создание таблицы + +```javascript +const table = await tablesService.createTable({ + name: "FAQ", + description: "Часто задаваемые вопросы для AI", + isRagSourceId: 2 // RAG источник +}); +``` + +#### Добавление столбцов + +```javascript +// Вопрос (для векторного поиска) +await tablesService.addColumn(table.id, { + name: "Вопрос", + type: "text", + order: 0, + purpose: "question" +}); + +// Ответ (для AI) +await tablesService.addColumn(table.id, { + name: "Ответ", + type: "text", + order: 1, + purpose: "answer" +}); + +// Продукт (для фильтрации) +await tablesService.addColumn(table.id, { + name: "Продукт", + type: "multiselect", + order: 2, + purpose: "product", + options: { + choices: ["Базовый", "Премиум", "Корпоративный"] + } +}); + +// Теги (для фильтрации) +await tablesService.addColumn(table.id, { + name: "Теги", + type: "multiselect", + order: 3, + purpose: "userTags", + options: { + choices: ["Оплата", "Доставка", "Возврат", "Гарантия"] + } +}); +``` + +#### Добавление данных + +```javascript +// Добавляем строку +const row = await tablesService.addRow(table.id); + +// Заполняем ячейки +await tablesService.saveCell({ + row_id: row.id, + column_id: 1, // Вопрос + value: "Как вернуть товар?" +}); + +await tablesService.saveCell({ + row_id: row.id, + column_id: 2, // Ответ + value: "Возврат товара возможен в течение 14 дней с момента покупки..." +}); + +// Автоматически индексируется в vector store! +``` + +#### Поиск через AI + +```javascript +// Пользователь спрашивает AI +const userQuestion = "можно ли вернуть покупку?"; + +// AI делает векторный поиск +const results = await vectorSearch.search(table.id, userQuestion, 3); + +// Находит похожий вопрос "Как вернуть товар?" (score: -200) +// Возвращает ответ из metadata.answer +``` + +### Пример 2: CRM система + +#### Структура + +```javascript +// Таблица "Компании" +const companies = await tablesService.createTable({ + name: "Компании", + description: "База компаний" +}); + +await tablesService.addColumn(companies.id, { + name: "Название", + type: "text", + order: 0 +}); + +await tablesService.addColumn(companies.id, { + name: "Сайт", + type: "text", + order: 1 +}); + +await tablesService.addColumn(companies.id, { + name: "Отрасль", + type: "multiselect", + order: 2, + options: { choices: ["IT", "Финансы", "Ритейл", "Производство"] } +}); + +// Таблица "Контакты" +const contacts = await tablesService.createTable({ + name: "Контакты", + description: "База контактов" +}); + +await tablesService.addColumn(contacts.id, { + name: "Имя", + type: "text", + order: 0 +}); + +await tablesService.addColumn(contacts.id, { + name: "Email", + type: "text", + order: 1 +}); + +// Связь: Контакт → Компания +await tablesService.addColumn(contacts.id, { + name: "Компания", + type: "relation", + order: 2, + options: { + relatedTableId: companies.id, + relatedColumnId: 1 // Название компании + } +}); + +// Lookup: Сайт компании +await tablesService.addColumn(contacts.id, { + name: "Сайт компании", + type: "lookup", + order: 3, + options: { + relatedTableId: companies.id, + relatedColumnId: 2, // Связь через "Компания" + lookupColumnId: 2 // Подставить "Сайт" + } +}); +``` + +#### Использование + +```javascript +// Добавляем компанию +const company = await tablesService.addRow(companies.id); +await tablesService.saveCell({ + row_id: company.id, + column_id: 1, + value: "Microsoft" +}); +await tablesService.saveCell({ + row_id: company.id, + column_id: 2, + value: "https://microsoft.com" +}); + +// Добавляем контакт +const contact = await tablesService.addRow(contacts.id); +await tablesService.saveCell({ + row_id: contact.id, + column_id: 1, + value: "John Doe" +}); + +// Связываем контакт с компанией +await api.post(`/tables/${contacts.id}/row/${contact.id}/relations`, { + column_id: 3, // "Компания" + to_table_id: companies.id, + to_row_id: company.id +}); + +// Lookup автоматически подставит "https://microsoft.com"! +``` + +### Пример 3: Управление задачами + +#### Структура + +```javascript +// Таблица "Проекты" +const projects = await tablesService.createTable({ + name: "Проекты", + description: "Активные проекты" +}); + +await tablesService.addColumn(projects.id, { + name: "Название", + type: "text", + order: 0 +}); + +await tablesService.addColumn(projects.id, { + name: "Статус", + type: "multiselect", + order: 1, + options: { choices: ["Планирование", "В работе", "Завершен"] } +}); + +// Таблица "Задачи" +const tasks = await tablesService.createTable({ + name: "Задачи", + description: "Задачи по проектам" +}); + +await tablesService.addColumn(tasks.id, { + name: "Название", + type: "text", + order: 0 +}); + +await tablesService.addColumn(tasks.id, { + name: "Проект", + type: "relation", + order: 1, + options: { + relatedTableId: projects.id, + relatedColumnId: 1 + } +}); + +await tablesService.addColumn(tasks.id, { + name: "Приоритет", + type: "number", + order: 2 +}); + +await tablesService.addColumn(tasks.id, { + name: "Статус", + type: "multiselect", + order: 3, + options: { choices: ["To Do", "In Progress", "Review", "Done"] } +}); +``` + +#### Фильтрация задач по проекту + +```javascript +// Получить все задачи проекта с ID = 5 +const tasks = await api.get(`/tables/${tasks.id}/rows?relation_2=5`); + +// Получить задачи с приоритетом > 5 +const highPriority = tasks.filter(task => { + const priority = cellValues.find( + cell => cell.row_id === task.id && cell.column_id === 3 + )?.value; + return parseInt(priority) > 5; +}); +``` + +--- + +## Безопасность + +### Шифрование данных + +**Все чувствительные данные шифруются AES-256**: + +```javascript +// Шифруются: +name_encrypted // Название таблицы +description_encrypted // Описание +value_encrypted // Значения ячеек +placeholder_encrypted // Плейсхолдеры + +// НЕ шифруются (для индексов и производительности): +placeholder // Незашифрованный плейсхолдер +options // JSONB настройки +order // Порядок +``` + +**Функции шифрования в PostgreSQL**: + +```sql +-- Шифрование +encrypt_text(plain_text, encryption_key) + +-- Расшифровка +decrypt_text(encrypted_text, encryption_key) + +-- Пример использования +INSERT INTO user_tables (name_encrypted) +VALUES (encrypt_text('Контакты', $1)); + +SELECT decrypt_text(name_encrypted, $1) as name +FROM user_tables; +``` + +### Права доступа + +```javascript +// Просмотр: все авторизованные пользователи +GET /tables +GET /tables/:id +GET /tables/:id/rows + +// Редактирование: пользователи с правами +if (!canEditData) { + return res.status(403).json({ error: 'Доступ запрещен' }); +} +POST /tables/:id/columns +POST /tables/:id/rows +POST /tables/cell +PATCH /tables/column/:columnId + +// Удаление: только администраторы +if (!req.session.userAccessLevel?.hasAccess) { + return res.status(403).json({ error: 'Только для администраторов' }); +} +DELETE /tables/:id +DELETE /tables/column/:columnId +DELETE /tables/row/:rowId +POST /tables/:id/rebuild-index +``` + +### Проверка прав через токены + +```javascript +// Backend проверяет баланс токенов +const address = req.session.address; +const dleContract = new ethers.Contract(dleAddress, dleAbi, provider); +const balance = await dleContract.balanceOf(address); + +if (balance === 0n) { + return res.status(403).json({ + error: 'Доступ запрещен: нет токенов' + }); +} + +// Определяем уровень доступа +const accessLevel = determineAccessLevel(balance); +req.session.userAccessLevel = accessLevel; +``` + +### Защита от SQL-инъекций + +**Параметризованные запросы**: + +```javascript +// ✅ Безопасно (параметры) +await db.getQuery()( + 'SELECT * FROM user_tables WHERE id = $1', + [tableId] +); + +// ❌ ОПАСНО (конкатенация) +await db.getQuery()( + `SELECT * FROM user_tables WHERE id = ${tableId}` +); +``` + +### Валидация входных данных + +```javascript +// Проверка типов +if (typeof name !== 'string') { + return res.status(400).json({ error: 'Invalid name' }); +} + +// Проверка существования +const exists = await db.getQuery()( + 'SELECT id FROM user_tables WHERE id = $1', + [tableId] +); +if (!exists.rows[0]) { + return res.status(404).json({ error: 'Table not found' }); +} + +// Проверка уникальности (placeholder) +const duplicate = await db.getQuery()( + 'SELECT id FROM user_columns WHERE placeholder = $1 AND id != $2', + [placeholder, columnId] +); +if (duplicate.rows.length > 0) { + placeholder = generateUniquePlaceholder(); +} +``` + +### Каскадное удаление (защита от orphaned data) + +```sql +-- Все связи с ON DELETE CASCADE +CREATE TABLE user_columns ( + table_id INTEGER NOT NULL + REFERENCES user_tables(id) ON DELETE CASCADE +); + +CREATE TABLE user_rows ( + table_id INTEGER NOT NULL + REFERENCES user_tables(id) ON DELETE CASCADE +); + +CREATE TABLE user_cell_values ( + row_id INTEGER NOT NULL + REFERENCES user_rows(id) ON DELETE CASCADE, + column_id INTEGER NOT NULL + REFERENCES user_columns(id) ON DELETE CASCADE +); + +-- Результат: удаление таблицы автоматически удаляет ВСЁ +``` + +### Rate Limiting + +```javascript +// В backend/routes/tables.js можно добавить +const rateLimit = require('express-rate-limit'); + +const tablesLimiter = rateLimit({ + windowMs: 15 * 60 * 1000, // 15 минут + max: 100, // 100 запросов + message: 'Слишком много запросов к таблицам' +}); + +router.use(tablesLimiter); +``` + +--- + +## Производительность + +### Оптимизации + +#### 1. Параллельные запросы + +```javascript +// Вместо последовательных запросов: +const tableMeta = await db.query('SELECT ...'); +const columns = await db.query('SELECT ...'); +const rows = await db.query('SELECT ...'); +const cellValues = await db.query('SELECT ...'); + +// Используются параллельные: +const [tableMeta, columns, rows, cellValues] = await Promise.all([ + db.query('SELECT ...'), + db.query('SELECT ...'), + db.query('SELECT ...'), + db.query('SELECT ...') +]); + +// Ускорение: 4x +``` + +#### 2. Индексы на связях + +```sql +CREATE INDEX idx_user_table_relations_from_row + ON user_table_relations(from_row_id); + +CREATE INDEX idx_user_table_relations_to_table + ON user_table_relations(to_table_id); + +-- Результат: быстрая фильтрация по связям +``` + +#### 3. UNIQUE constraint + +```sql +CREATE TABLE user_cell_values ( + ... + UNIQUE(row_id, column_id) +); + +-- Преимущества: +-- 1. Предотвращает дубликаты ячеек +-- 2. Ускоряет upsert (ON CONFLICT) +-- 3. Автоматический индекс +``` + +#### 4. WebSocket вместо polling + +```javascript +// ❌ Polling (медленно) +setInterval(async () => { + const data = await fetchTableData(); + updateUI(data); +}, 5000); + +// ✅ WebSocket (мгновенно) +socket.on('table-update', (data) => { + if (data.tableId === currentTableId) { + updateUI(data); + } +}); + +// Результат: real-time обновления, нет нагрузки на сервер +``` + +#### 5. Кэширование + +```javascript +// Backend может добавить кэш для часто запрашиваемых таблиц +const NodeCache = require('node-cache'); +const tableCache = new NodeCache({ stdTTL: 300 }); // 5 минут + +router.get('/:id', async (req, res) => { + const cacheKey = `table_${req.params.id}`; + const cached = tableCache.get(cacheKey); + + if (cached) { + return res.json(cached); + } + + const data = await fetchTableData(req.params.id); + tableCache.set(cacheKey, data); + res.json(data); +}); +``` + +### Метрики + +**Типичное время ответа**: +``` +GET /tables → 50-100ms (все таблицы) +GET /tables/:id → 150-300ms (с данными, Promise.all) +POST /tables/cell → 100-200ms (upsert + vector update) +DELETE /tables/row/:id → 200-400ms (удаление + rebuild vector) +POST /tables/:id/rebuild-index → 1-5s (зависит от размера) +``` + +**Оптимальные размеры таблиц**: +``` +Строк: до 10,000 → Отлично +Строк: 10,000-50,000 → Хорошо +Строк: >50,000 → Нужны доп. оптимизации (pagination, lazy load) +``` + +--- + +## Ограничения и будущие улучшения + +### Текущие ограничения + +1. **Нет пагинации**: Все строки загружаются сразу + - Для больших таблиц (>1000 строк) может быть медленно + +2. **Нет формул**: Нельзя делать вычисляемые поля + - Workaround: использовать lookup + +3. **Нет группировки**: Нельзя группировать строки + - Workaround: фильтрация на frontend + +4. **Нет истории изменений**: Не отслеживается, кто и когда изменил + - Можно добавить audit trail + +5. **Ограниченная сортировка**: Только через order поле + - Нет сортировки по столбцам на backend + +### Возможные улучшения + +```javascript +// 1. Пагинация +GET /tables/:id/rows?page=1&limit=50 + +// 2. Сортировка +GET /tables/:id/rows?sort_by=column_id&order=asc + +// 3. Формулы +{ + "type": "formula", + "options": { + "formula": "{{price}} * {{quantity}}" + } +} + +// 4. История изменений +CREATE TABLE user_cell_history ( + id SERIAL PRIMARY KEY, + cell_id INTEGER REFERENCES user_cell_values(id), + old_value TEXT, + new_value TEXT, + changed_by INTEGER, + changed_at TIMESTAMP +); + +// 5. Экспорт/импорт +POST /tables/:id/export → CSV/Excel +POST /tables/:id/import ← CSV/Excel + +// 6. Шаблоны таблиц +POST /tables/templates/crm → Создать CRM из шаблона +POST /tables/templates/tasks → Создать Kanban из шаблона +``` + +--- + +## Заключение + +Система электронных таблиц в DLE — это **мощный инструмент** для управления структурированными данными с: + +✅ **Гибкой структурой** (6 типов полей) +✅ **Связями между таблицами** (relation, lookup) +✅ **AI интеграцией** (RAG, векторный поиск) +✅ **Real-time обновлениями** (WebSocket) +✅ **Безопасностью** (AES-256, права доступа) +✅ **Производительностью** (индексы, параллельные запросы) + +Это **не просто Excel**, а **полноценная база данных** с удобным интерфейсом и AI ассистентом! + +--- + +**© 2024-2025 Тарабанов Александр Викторович. Все права защищены.** + +**Версия документа**: 1.0.0 +**Дата создания**: October 25, 2025 +**Статус**: Временный (для внутреннего использования) +