From e5e69470f833dd87e8e02f0bdef846f55f679c16 Mon Sep 17 00:00:00 2001 From: Leonid Pershin Date: Tue, 21 Oct 2025 05:08:40 +0300 Subject: [PATCH] add docs --- README.md | 287 ++++++++++++++- docs/README.md | 63 ++++ docs/api/bot-commands.md | 357 +++++++++++++++++++ docs/architecture/data-models.md | 369 ++++++++++++++++++++ docs/architecture/database.md | 351 +++++++++++++++++++ docs/architecture/layers.md | 349 ++++++++++++++++++ docs/architecture/overview.md | 210 +++++++++++ docs/configuration.md | 449 ++++++++++++++++++++++++ docs/development/project-structure.md | 344 ++++++++++++++++++ docs/installation.md | 485 ++++++++++++++++++++++++++ docs/overview.md | 144 ++++++++ docs/quickstart.md | 148 ++++++++ 12 files changed, 3550 insertions(+), 6 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/api/bot-commands.md create mode 100644 docs/architecture/data-models.md create mode 100644 docs/architecture/database.md create mode 100644 docs/architecture/layers.md create mode 100644 docs/architecture/overview.md create mode 100644 docs/configuration.md create mode 100644 docs/development/project-structure.md create mode 100644 docs/installation.md create mode 100644 docs/overview.md create mode 100644 docs/quickstart.md diff --git a/README.md b/README.md index 0db22bd..196af14 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,46 @@ -# ChatBot +# 🤖 ChatBot - AI Telegram Bot -## Настройка окружения +[![.NET](https://img.shields.io/badge/.NET-9.0-blue)](https://dotnet.microsoft.com/) +[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE.txt) +[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14+-blue)](https://www.postgresql.org/) -1. Создать `.env` файл: -пример +Интеллектуальный Telegram-бот на базе локальных AI моделей (Ollama), построенный на .NET 9 с использованием Clean Architecture. +## ✨ Основные возможности + +- 🤖 **AI-интеграция** - Использование локальных LLM через Ollama (gemma2, llama3, mistral) +- 💬 **Telegram Bot** - Полнофункциональный бот с поддержкой команд и групповых чатов +- 💾 **PostgreSQL** - Надежное хранение истории диалогов и сессий +- 🗜️ **История сжатия** - Автоматическая оптимизация длинных диалогов +- 🔄 **Retry механизмы** - Устойчивость к сбоям с экспоненциальным backoff +- 📊 **Health Checks** - Мониторинг состояния всех сервисов +- 🧪 **Высокое покрытие тестами** - 50+ тестовых классов +- 📝 **Serilog** - Структурированное логирование + +## 🚀 Быстрый старт + +### Требования + +- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0) +- [PostgreSQL 14+](https://www.postgresql.org/download/) +- [Ollama](https://ollama.ai/) с установленной моделью +- Telegram Bot Token ([создать через @BotFather](https://t.me/botfather)) + +### Установка за 3 шага + +#### 1. Клонирование и установка зависимостей + +```bash +git clone https://github.com/mrleo1nid/ChatBot.git +cd ChatBot +dotnet restore +``` + +#### 2. Настройка окружения + +Создайте файл `ChatBot/.env`: + +```env # Database Configuration DB_HOST=localhost DB_PORT=5432 @@ -16,5 +52,244 @@ DB_PASSWORD=your_secure_password TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here # Ollama Configuration -OLLAMA_URL=https://sample.api.home/ -OLLAMA_DEFAULT_MODEL=gemma3:4b +OLLAMA_URL=http://localhost:11434 +OLLAMA_DEFAULT_MODEL=gemma2:2b +``` + +#### 3. Запуск + +```bash +# Установите AI модель +ollama pull gemma2:2b + +# Создайте базу данных +psql -U postgres -c "CREATE DATABASE chatbot;" + +# Запустите бота +cd ChatBot +dotnet run +``` + +🎉 **Готово!** Откройте Telegram и найдите вашего бота. + +## 📚 Документация + +### 🎯 Начало работы +- [📋 Обзор проекта](docs/overview.md) - Что такое ChatBot и его возможности +- [⚡ Быстрый старт](docs/quickstart.md) - Запуск за 5 минут +- [🛠️ Установка и настройка](docs/installation.md) - Подробная инструкция +- [⚙️ Конфигурация](docs/configuration.md) - Настройка параметров + +### 🏗️ Архитектура +- [📐 Архитектура проекта](docs/architecture/overview.md) - Общая архитектура +- [🏛️ Слои приложения](docs/architecture/layers.md) - Детальное описание слоев +- [📊 Модели данных](docs/architecture/data-models.md) - Структура данных +- [🗄️ База данных](docs/architecture/database.md) - Работа с PostgreSQL + +### 💻 Разработка +- [📁 Структура проекта](docs/development/project-structure.md) - Организация кода +- [🤖 Команды бота](docs/api/bot-commands.md) - Все доступные команды + +### 📖 Полная документация + +**👉 [Перейти к полной документации](docs/README.md)** + +## 🎮 Использование + +### Команды бота + +``` +/start - Начать работу с ботом +/help - Показать справку +/clear - Очистить историю диалога +/settings - Показать текущие настройки +/status - Проверить статус бота +``` + +### Пример диалога + +``` +Вы: Привет! +Бот: Привет! Как дела? 😊 + +Вы: Расскажи анекдот +Бот: Программист ложится спать... + Ставит рядом два стакана: + один с водой — если захочет пить, + другой пустой — если не захочет 😄 +``` + +## 🏗️ Технологический стек + +### Backend +- **Runtime:** .NET 9.0 +- **Language:** C# 13 +- **Architecture:** Clean Architecture, SOLID + +### Основные библиотеки +- **Telegram.Bot** 22.7.2 - Telegram Bot API +- **OllamaSharp** 5.4.7 - Ollama клиент для AI +- **Entity Framework Core** 9.0.10 - ORM +- **Npgsql** 9.0.4 - PostgreSQL провайдер +- **Serilog** 4.3.0 - Логирование +- **FluentValidation** 12.0.0 - Валидация + +### Тестирование +- **xUnit** 2.9.3 - Тестовый фреймворк +- **Moq** 4.20.72 - Моки и стабы +- **FluentAssertions** 8.7.1 - Assertions +- **Coverlet** 6.0.4 - Code coverage + +## 📊 Архитектура + +``` +┌─────────────────────────────────────┐ +│ Telegram Bot Layer │ +│ (Commands, Handlers) │ +├─────────────────────────────────────┤ +│ Service Layer │ +│ (ChatService, AIService) │ +├─────────────────────────────────────┤ +│ Data Access Layer │ +│ (Repositories, DbContext) │ +├─────────────────────────────────────┤ +│ Infrastructure │ +│ (PostgreSQL, Ollama, Telegram) │ +└─────────────────────────────────────┘ +``` + +**Принципы:** +- Clean Architecture +- SOLID принципы +- Dependency Injection +- Repository Pattern +- Command Pattern для команд бота + +## 🐳 Docker развертывание + +```bash +# Сборка образа +docker build -t chatbot:latest . + +# Запуск с docker-compose +docker-compose up -d +``` + +## 🧪 Тестирование + +```bash +# Запуск всех тестов +dotnet test + +# С покрытием кода +dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover + +# Запуск конкретного теста +dotnet test --filter "FullyQualifiedName~ChatServiceTests" +``` + +## 📈 CI/CD + +Проект использует Gitea Actions для автоматизации: +- ✅ Сборка проекта +- ✅ Запуск тестов +- ✅ Анализ кода (SonarQube) +- ✅ Проверка покрытия + +Конфигурация: [`.gitea/workflows/build.yml`](.gitea/workflows/build.yml) + +## 🔧 Конфигурация + +### Основные параметры + +| Параметр | Описание | По умолчанию | +|----------|----------|-------------| +| `AI.Temperature` | Креативность ответов (0.0-2.0) | 0.9 | +| `AI.MaxRetryAttempts` | Макс. попыток повтора | 3 | +| `AI.EnableHistoryCompression` | Сжатие истории | true | +| `AI.CompressionThreshold` | Порог сжатия (сообщений) | 20 | + +**Подробнее:** [docs/configuration.md](docs/configuration.md) + +## 🛠️ Разработка + +### Структура проекта + +``` +ChatBot/ +├── ChatBot/ # Основной проект +│ ├── Services/ # Бизнес-логика +│ ├── Data/ # Доступ к данным +│ ├── Models/ # Модели и конфигурация +│ └── Program.cs # Точка входа +├── ChatBot.Tests/ # Тесты +└── docs/ # Документация +``` + +### Добавление новой команды + +```csharp +public class MyCommand : TelegramCommandBase +{ + public override string Command => "mycommand"; + public override string Description => "Описание команды"; + + public override async Task ExecuteAsync(TelegramCommandContext context) + { + return new ReplyInfo { Text = "Ответ" }; + } +} +``` + +Зарегистрируйте в `Program.cs`: +```csharp +builder.Services.AddScoped(); +``` + +## 🤝 Вклад в проект + +Мы приветствуем вклад в развитие проекта! + +### Как внести изменения + +1. Fork репозитория +2. Создайте feature branch (`git checkout -b feature/amazing-feature`) +3. Commit изменения (`git commit -m 'Add amazing feature'`) +4. Push в branch (`git push origin feature/amazing-feature`) +5. Откройте Pull Request + +### Guidelines + +- Следуйте существующему стилю кода +- Добавляйте тесты для новой функциональности +- Обновляйте документацию +- Убедитесь, что все тесты проходят + +## 📝 Лицензия + +Этот проект распространяется под лицензией MIT. См. [LICENSE.txt](LICENSE.txt) для подробностей. + +## 🙏 Благодарности + +- [Telegram Bot API](https://core.telegram.org/bots/api) - За отличное API +- [Ollama](https://ollama.ai/) - За возможность использовать локальные LLM +- [.NET Community](https://dotnet.microsoft.com/) - За мощный фреймворк + +## 📞 Контакты и поддержка + +- 🐛 [Сообщить о проблеме](https://github.com/mrleo1nid/ChatBot/issues) +- 💡 [Предложить улучшение](https://github.com/mrleo1nid/ChatBot/issues) +- 📖 [Документация](docs/README.md) + +## 🌟 Roadmap + +- [ ] Поддержка мультимодальных моделей (изображения) +- [ ] Веб-интерфейс для управления ботом +- [ ] Метрики и аналитика использования +- [ ] Kubernetes deployment манифесты +- [ ] Дополнительные команды (история, экспорт) +- [ ] Плагинная система для расширений + +--- + +**Сделано с ❤️ используя .NET 9 и Ollama** diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..f0efe86 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,63 @@ +# 📚 Документация ChatBot + +Добро пожаловать в документацию проекта **ChatBot** — интеллектуального Telegram-бота на базе AI (Ollama), написанного на .NET 9. + +## 📖 Содержание + +### 🎯 Основное +- [Обзор проекта](./overview.md) - Общая информация о проекте +- [Быстрый старт](./quickstart.md) - Запуск проекта за 5 минут +- [Установка и настройка](./installation.md) - Подробная инструкция по установке +- [Конфигурация](./configuration.md) - Настройка параметров бота + +### 🏗️ Архитектура +- [Архитектура проекта](./architecture/overview.md) - Общая архитектура +- [Слои приложения](./architecture/layers.md) - Описание слоёв +- [Модели данных](./architecture/data-models.md) - Структура данных +- [Базы данных](./architecture/database.md) - Работа с PostgreSQL + +### 💻 Разработка +- [Структура проекта](./development/project-structure.md) - Организация кода +- [Сервисы](./development/services.md) - Описание всех сервисов +- [Telegram интеграция](./development/telegram-integration.md) - Работа с Telegram Bot API +- [AI сервисы](./development/ai-services.md) - Интеграция с Ollama +- [Dependency Injection](./development/dependency-injection.md) - Управление зависимостями + +### 📝 API и интерфейсы +- [Команды бота](./api/bot-commands.md) - Все доступные команды +- [Интерфейсы сервисов](./api/service-interfaces.md) - Описание интерфейсов +- [Health Checks](./api/health-checks.md) - Мониторинг здоровья + +### 🧪 Тестирование +- [Стратегия тестирования](./testing/strategy.md) - Подход к тестированию +- [Unit тесты](./testing/unit-tests.md) - Модульное тестирование +- [Integration тесты](./testing/integration-tests.md) - Интеграционное тестирование +- [Покрытие кода](./testing/coverage.md) - Code coverage + +### 🚀 Развертывание +- [Docker развертывание](./deployment/docker.md) - Запуск в Docker +- [CI/CD](./deployment/ci-cd.md) - Автоматизация сборки +- [Мониторинг](./deployment/monitoring.md) - Логирование и мониторинг + +### 🔧 Дополнительно +- [FAQ](./faq.md) - Часто задаваемые вопросы +- [Troubleshooting](./troubleshooting.md) - Решение проблем +- [Contributing](./contributing.md) - Как внести вклад +- [Changelog](./changelog.md) - История изменений + +## 🔗 Быстрые ссылки + +- [GitHub Repository](https://gitea.hsrv.site/mrleo1nid/ChatBot) +- [Issues](https://gitea.hsrv.site/mrleo1nid/ChatBot/issues) +- [Releases](https://gitea.hsrv.site/mrleo1nid/ChatBot/releases) + +## 📞 Поддержка + +Если у вас возникли вопросы или проблемы: +1. Проверьте [FAQ](./faq.md) +2. Изучите [Troubleshooting](./troubleshooting.md) +3. Создайте [Issue](https://gitea.hsrv.site/mrleo1nid/ChatBot/issues) + +## 📄 Лицензия + +Проект распространяется под лицензией MIT. См. [LICENSE.txt](../LICENSE.txt) для подробностей. diff --git a/docs/api/bot-commands.md b/docs/api/bot-commands.md new file mode 100644 index 0000000..6e5738c --- /dev/null +++ b/docs/api/bot-commands.md @@ -0,0 +1,357 @@ +# 🤖 Команды бота + +Полное описание всех команд Telegram бота. + +## 📋 Список команд + +| Команда | Описание | Доступность | +|---------|----------|-------------| +| `/start` | Начать работу с ботом | Все пользователи | +| `/help` | Показать справку | Все пользователи | +| `/clear` | Очистить историю диалога | Все пользователи | +| `/settings` | Показать текущие настройки | Все пользователи | +| `/status` | Проверить статус бота | Все пользователи | + +## 🔧 Детальное описание + +### /start + +**Описание:** Инициализация бота и приветствие пользователя. + +**Использование:** +``` +/start +``` + +**Ответ:** +``` +👋 Привет! Я готов к общению. + +Просто напиши мне что-нибудь, и я отвечу. + +Используй /help для списка команд. +``` + +**Что происходит:** +1. Создается новая сессия (если не существует) +2. Загружается системный промпт +3. Отправляется приветственное сообщение + +**Реализация:** +```csharp +public class StartCommand : TelegramCommandBase +{ + public override string Command => "start"; + public override string Description => "Начать работу с ботом"; + + public override async Task ExecuteAsync(TelegramCommandContext context) + { + // Логика команды + } +} +``` + +--- + +### /help + +**Описание:** Показать список всех доступных команд. + +**Использование:** +``` +/help +``` + +**Ответ:** +``` +📖 Доступные команды: + +/start - Начать работу с ботом +/help - Показать эту справку +/clear - Очистить историю диалога +/settings - Показать текущие настройки +/status - Проверить статус бота + +💬 Просто напиши мне сообщение, и я отвечу! +``` + +**Динамическая генерация:** +Список команд генерируется автоматически через `CommandRegistry`: + +```csharp +var commands = _commandRegistry.GetAllCommands(); +foreach (var cmd in commands) +{ + message += $"/{cmd.Command} - {cmd.Description}\n"; +} +``` + +--- + +### /clear + +**Описание:** Очистить историю диалога с сохранением сессии. + +**Использование:** +``` +/clear +``` + +**Ответ:** +``` +🧹 История диалога очищена! + +Можешь начать новый разговор. +``` + +**Что происходит:** +1. Вызывается `ChatService.ClearHistoryAsync(chatId)` +2. Удаляются все сообщения из истории +3. Сохраняется системный промпт +4. Обновляется `LastUpdatedAt` + +**Важно:** +- Сессия не удаляется +- Настройки модели сохраняются +- История в БД обновляется + +**Код:** +```csharp +public override async Task ExecuteAsync(TelegramCommandContext context) +{ + await _chatService.ClearHistoryAsync(context.ChatId); + return new ReplyInfo { Text = "🧹 История диалога очищена!" }; +} +``` + +--- + +### /settings + +**Описание:** Показать текущие настройки сессии. + +**Использование:** +``` +/settings +``` + +**Ответ:** +``` +⚙️ Текущие настройки: + +🤖 Модель: gemma2:2b +🌡️ Temperature: 0.9 +📝 Сообщений в истории: 5/30 +🗜️ Сжатие истории: Включено +📊 Порог сжатия: 20 сообщений +🎯 Цель сжатия: 10 сообщений +``` + +**Информация:** +- Используемая AI модель +- Температура генерации +- Количество сообщений в истории +- Статус сжатия истории +- Пороги компрессии + +**Код:** +```csharp +var session = _chatService.GetSession(context.ChatId); +if (session == null) + return new ReplyInfo { Text = "Сессия не найдена" }; + +var info = $@"⚙️ Текущие настройки: +🤖 Модель: {session.Model} +📝 Сообщений: {session.GetMessageCount()}/{session.MaxHistoryLength}"; + +return new ReplyInfo { Text = info }; +``` + +--- + +### /status + +**Описание:** Проверить статус бота и подключенных сервисов. + +**Использование:** +``` +/status +``` + +**Ответ (все ОК):** +``` +✅ Статус системы: + +🤖 Telegram Bot: ✅ Работает +🧠 Ollama AI: ✅ Подключен +💾 База данных: ✅ Доступна + +📊 Активных сессий: 5 +🕐 Время работы: 2ч 15м +``` + +**Ответ (есть проблемы):** +``` +⚠️ Статус системы: + +🤖 Telegram Bot: ✅ Работает +🧠 Ollama AI: ❌ Недоступен +💾 База данных: ✅ Доступна + +Обнаружены проблемы с подключением к Ollama. +``` + +**Проверки:** +1. **Telegram Bot** - Проверка `TelegramBotHealthCheck` +2. **Ollama AI** - Проверка доступности API +3. **Database** - Проверка подключения к PostgreSQL +4. **Active Sessions** - Количество активных чатов +5. **Uptime** - Время работы бота + +**Health Checks:** +```csharp +var healthCheckService = _serviceProvider.GetRequiredService(); +var result = await healthCheckService.CheckHealthAsync(); + +foreach (var entry in result.Entries) +{ + var status = entry.Value.Status == HealthStatus.Healthy ? "✅" : "❌"; + message += $"{entry.Key}: {status}\n"; +} +``` + +--- + +## 🎨 Формат ответов + +### ReplyInfo + +Все команды возвращают `ReplyInfo`: + +```csharp +public class ReplyInfo +{ + public string Text { get; set; } // Текст ответа + public bool DisableNotification { get; set; } = false; + public bool DisableWebPagePreview { get; set; } = false; +} +``` + +### Markdown форматирование + +Поддерживаемые форматы: +- `**bold**` - **жирный** +- `*italic*` - *курсив* +- `` `code` `` - `код` +- Emoji - 🚀 ✅ ❌ ⚙️ + +## 🔄 Command Processing Flow + +``` +User sends command + ↓ +TelegramBotService receives update + ↓ +TelegramMessageHandler validates + ↓ +TelegramCommandProcessor checks if command + ↓ +CommandRegistry finds handler + ↓ +Command.ExecuteAsync() + ↓ +Return ReplyInfo + ↓ +TelegramMessageSender sends response +``` + +## 🛠️ Добавление новой команды + +### 1. Создать класс команды + +```csharp +public class MyCommand : TelegramCommandBase +{ + public override string Command => "mycommand"; + public override string Description => "Описание команды"; + + public override async Task ExecuteAsync(TelegramCommandContext context) + { + // Ваша логика + return new ReplyInfo + { + Text = "Ответ команды" + }; + } +} +``` + +### 2. Зарегистрировать в DI + +В `Program.cs`: + +```csharp +builder.Services.AddScoped(); +``` + +### 3. Добавить в BotFather (опционально) + +``` +/setcommands + +start - Начать работу +help - Справка +mycommand - Описание +``` + +## 🧪 Тестирование команд + +```csharp +[Fact] +public async Task StartCommand_ShouldReturnWelcomeMessage() +{ + // Arrange + var command = new StartCommand(); + var context = new TelegramCommandContext + { + ChatId = 123, + UserId = 456 + }; + + // Act + var result = await command.ExecuteAsync(context); + + // Assert + result.Text.Should().Contain("Привет"); +} +``` + +## 📊 Статистика использования + +Логирование команд: + +```csharp +_logger.LogInformation( + "Command executed: {Command} by user {UserId} in chat {ChatId}", + Command, context.UserId, context.ChatId +); +``` + +## 🔐 Безопасность + +### Валидация контекста + +```csharp +if (context.ChatId <= 0) + throw new ArgumentException("Invalid chat ID"); +``` + +### Rate Limiting (будущее) + +Планируется добавить ограничение частоты команд. + +## 📚 См. также + +- [Telegram Integration](../development/telegram-integration.md) +- [Сервисы](../development/services.md) +- [Тестирование](../testing/unit-tests.md) diff --git a/docs/architecture/data-models.md b/docs/architecture/data-models.md new file mode 100644 index 0000000..4016847 --- /dev/null +++ b/docs/architecture/data-models.md @@ -0,0 +1,369 @@ +# 📊 Модели данных + +Полное описание всех моделей и сущностей в ChatBot. + +## 🗂️ Типы моделей + +### 1. Domain Models (Доменные модели) +- `ChatSession` - Основная модель сессии чата +- `ChatMessage` - DTO для сообщений + +### 2. Entity Models (Сущности БД) +- `ChatSessionEntity` - Сущность сессии в БД +- `ChatMessageEntity` - Сущность сообщения в БД + +### 3. Configuration Models (Конфигурация) +- `TelegramBotSettings` +- `OllamaSettings` +- `AISettings` +- `DatabaseSettings` + +## 📦 Domain Models + +### ChatSession + +Основная модель для работы с сессией чата. + +```csharp +public class ChatSession +{ + public string SessionId { get; set; } // Уникальный ID + public long ChatId { get; set; } // Telegram chat ID + public string ChatType { get; set; } // Тип чата + public string ChatTitle { get; set; } // Название + public string Model { get; set; } // AI модель + public DateTime CreatedAt { get; set; } // Создан + public DateTime LastUpdatedAt { get; set; } // Обновлен + public int MaxHistoryLength { get; set; } // Макс история +} +``` + +**Ключевые методы:** + +#### Работа с сообщениями +```csharp +// Добавить сообщение (базовый) +void AddMessage(ChatMessage message) + +// Добавить с компрессией +Task AddMessageWithCompressionAsync(ChatMessage message, int threshold, int target) + +// Добавить user сообщение +void AddUserMessage(string content, string username) +Task AddUserMessageWithCompressionAsync(string content, string username, int threshold, int target) + +// Добавить assistant сообщение +void AddAssistantMessage(string content) +Task AddAssistantMessageWithCompressionAsync(string content, int threshold, int target) + +// Получить все сообщения +List GetAllMessages() + +// Количество сообщений +int GetMessageCount() + +// Очистить историю +void ClearHistory() +``` + +#### Управление компрессией +```csharp +void SetCompressionService(IHistoryCompressionService service) +``` + +**Thread Safety:** +Все операции с `_messageHistory` защищены `lock(_lock)` + +**Управление историей:** +- Автоматическое обрезание при превышении `MaxHistoryLength` +- Сохранение system prompt при обрезке +- Поддержка асинхронной компрессии + +### ChatMessage (DTO) + +```csharp +public class ChatMessage +{ + public ChatRole Role { get; set; } // user/assistant/system + public string Content { get; set; } // Текст сообщения +} +``` + +**ChatRole enum:** +```csharp +public enum ChatRole +{ + System, // Системный промпт + User, // Сообщение пользователя + Assistant // Ответ бота +} +``` + +## 💾 Entity Models + +### ChatSessionEntity + +Сущность для хранения в PostgreSQL. + +```csharp +public class ChatSessionEntity +{ + public int Id { get; set; } // PK (auto-increment) + public string SessionId { get; set; } // Unique, indexed + public long ChatId { get; set; } // Indexed + public string ChatType { get; set; } // Max 20 chars + public string? ChatTitle { get; set; } // Max 200 chars + public string Model { get; set; } // Max 100 chars + public DateTime CreatedAt { get; set; } // Required + public DateTime LastUpdatedAt { get; set; } // Required + public List Messages { get; set; } // Navigation property +} +``` + +**Индексы:** +- `SessionId` - Unique index +- `ChatId` - Index для быстрого поиска + +**Constraints:** +- `SessionId` - Required, MaxLength(50) +- `ChatId` - Required +- `ChatType` - Required, MaxLength(20) + +**Relationships:** +- One-to-Many с `ChatMessageEntity` +- Cascade Delete - удаление сессии удаляет сообщения + +### ChatMessageEntity + +```csharp +public class ChatMessageEntity +{ + public int Id { get; set; } // PK + public int SessionId { get; set; } // FK + public string Content { get; set; } // Max 10000 chars + public string Role { get; set; } // Max 20 chars + public int MessageOrder { get; set; } // Порядок в диалоге + public DateTime CreatedAt { get; set; } // Время создания + + public ChatSessionEntity Session { get; set; } // Navigation property +} +``` + +**Индексы:** +- `SessionId` - Index +- `CreatedAt` - Index для сортировки +- `(SessionId, MessageOrder)` - Composite index + +**Constraints:** +- `Content` - Required, MaxLength(10000) +- `Role` - Required, MaxLength(20) + +## ⚙️ Configuration Models + +### TelegramBotSettings + +```csharp +public class TelegramBotSettings +{ + public string BotToken { get; set; } = string.Empty; +} +``` + +**Validator:** +```csharp +RuleFor(x => x.BotToken) + .NotEmpty() + .MinimumLength(10); +``` + +### OllamaSettings + +```csharp +public class OllamaSettings +{ + public string Url { get; set; } = string.Empty; + public string DefaultModel { get; set; } = string.Empty; +} +``` + +**Validator:** +```csharp +RuleFor(x => x.Url) + .NotEmpty() + .Must(BeValidUrl); + +RuleFor(x => x.DefaultModel) + .NotEmpty(); +``` + +### AISettings + +```csharp +public class AISettings +{ + public double Temperature { get; set; } = 0.9; + public string SystemPromptPath { get; set; } = "Prompts/system-prompt.txt"; + public int MaxRetryAttempts { get; set; } = 3; + public int RetryDelayMs { get; set; } = 1000; + public int RequestTimeoutSeconds { get; set; } = 180; + + // Compression settings + public bool EnableHistoryCompression { get; set; } = true; + public int CompressionThreshold { get; set; } = 20; + public int CompressionTarget { get; set; } = 10; + public int MinMessageLengthForSummarization { get; set; } = 50; + public int MaxSummarizedMessageLength { get; set; } = 200; + + // Advanced + public bool EnableExponentialBackoff { get; set; } = true; + public int MaxRetryDelayMs { get; set; } = 30000; + public int CompressionTimeoutSeconds { get; set; } = 30; + public int StatusCheckTimeoutSeconds { get; set; } = 10; +} +``` + +**Validator:** +```csharp +RuleFor(x => x.Temperature) + .GreaterThanOrEqualTo(0.0) + .LessThanOrEqualTo(2.0); + +RuleFor(x => x.MaxRetryAttempts) + .GreaterThanOrEqualTo(1) + .LessThanOrEqualTo(10); +``` + +### DatabaseSettings + +```csharp +public class DatabaseSettings +{ + public string ConnectionString { get; set; } = string.Empty; + public bool EnableSensitiveDataLogging { get; set; } = false; + public int CommandTimeout { get; set; } = 30; +} +``` + +**Validator:** +```csharp +RuleFor(x => x.ConnectionString) + .NotEmpty(); + +RuleFor(x => x.CommandTimeout) + .GreaterThanOrEqualTo(5) + .LessThanOrEqualTo(300); +``` + +## 🔄 Маппинг Entity ↔ Model + +### Session Entity → Model + +```csharp +public ChatSession ToModel() +{ + var session = new ChatSession + { + SessionId = this.SessionId, + ChatId = this.ChatId, + ChatType = this.ChatType, + ChatTitle = this.ChatTitle ?? string.Empty, + Model = this.Model, + CreatedAt = this.CreatedAt, + LastUpdatedAt = this.LastUpdatedAt + }; + + // Восстановить сообщения + foreach (var msg in Messages.OrderBy(m => m.MessageOrder)) + { + session.AddMessage(new ChatMessage + { + Role = ParseRole(msg.Role), + Content = msg.Content + }); + } + + return session; +} +``` + +### Session Model → Entity + +```csharp +public ChatSessionEntity ToEntity() +{ + return new ChatSessionEntity + { + SessionId = this.SessionId, + ChatId = this.ChatId, + ChatType = this.ChatType, + ChatTitle = this.ChatTitle, + Model = this.Model, + CreatedAt = this.CreatedAt, + LastUpdatedAt = this.LastUpdatedAt, + Messages = this.GetAllMessages() + .Select((msg, index) => new ChatMessageEntity + { + Content = msg.Content, + Role = msg.Role.ToString(), + MessageOrder = index, + CreatedAt = DateTime.UtcNow + }) + .ToList() + }; +} +``` + +## 📐 Database Schema + +```sql +-- Таблица сессий +CREATE TABLE chat_sessions ( + id SERIAL PRIMARY KEY, + session_id VARCHAR(50) UNIQUE NOT NULL, + chat_id BIGINT NOT NULL, + chat_type VARCHAR(20) NOT NULL, + chat_title VARCHAR(200), + model VARCHAR(100), + created_at TIMESTAMP NOT NULL, + last_updated_at TIMESTAMP NOT NULL +); + +CREATE INDEX idx_chat_sessions_session_id ON chat_sessions(session_id); +CREATE INDEX idx_chat_sessions_chat_id ON chat_sessions(chat_id); + +-- Таблица сообщений +CREATE TABLE chat_messages ( + id SERIAL PRIMARY KEY, + session_id INTEGER NOT NULL REFERENCES chat_sessions(id) ON DELETE CASCADE, + content VARCHAR(10000) NOT NULL, + role VARCHAR(20) NOT NULL, + message_order INTEGER NOT NULL, + created_at TIMESTAMP NOT NULL +); + +CREATE INDEX idx_chat_messages_session_id ON chat_messages(session_id); +CREATE INDEX idx_chat_messages_created_at ON chat_messages(created_at); +CREATE INDEX idx_chat_messages_session_order ON chat_messages(session_id, message_order); +``` + +## 🎯 Жизненный цикл Session + +``` +1. Создание (GetOrCreate) + ↓ +2. Добавление сообщений (AddMessage) + ↓ +3. Проверка длины истории + ↓ +4. Компрессия (если нужно) + ↓ +5. Сохранение в БД (SaveSessionAsync) + ↓ +6. Обновление LastUpdatedAt +``` + +## 📚 См. также + +- [Архитектура слоев](./layers.md) +- [База данных](./database.md) +- [Сервисы](../development/services.md) diff --git a/docs/architecture/database.md b/docs/architecture/database.md new file mode 100644 index 0000000..214c488 --- /dev/null +++ b/docs/architecture/database.md @@ -0,0 +1,351 @@ +# 🗄️ База данных + +Описание работы с PostgreSQL в ChatBot. + +## 📊 Схема базы данных + +### Таблицы + +#### chat_sessions + +Хранит информацию о сессиях чатов. + +| Колонка | Тип | Constraints | Описание | +|---------|-----|-------------|----------| +| id | SERIAL | PRIMARY KEY | Auto-increment ID | +| session_id | VARCHAR(50) | UNIQUE, NOT NULL | Уникальный идентификатор | +| chat_id | BIGINT | NOT NULL, INDEXED | Telegram chat ID | +| chat_type | VARCHAR(20) | NOT NULL | Тип чата | +| chat_title | VARCHAR(200) | NULL | Название чата | +| model | VARCHAR(100) | NULL | AI модель | +| created_at | TIMESTAMP | NOT NULL | Дата создания | +| last_updated_at | TIMESTAMP | NOT NULL | Последнее обновление | + +**Индексы:** +```sql +CREATE UNIQUE INDEX idx_chat_sessions_session_id ON chat_sessions(session_id); +CREATE INDEX idx_chat_sessions_chat_id ON chat_sessions(chat_id); +``` + +#### chat_messages + +Хранит историю сообщений. + +| Колонка | Тип | Constraints | Описание | +|---------|-----|-------------|----------| +| id | SERIAL | PRIMARY KEY | Auto-increment ID | +| session_id | INTEGER | FK, NOT NULL | Ссылка на сессию | +| content | VARCHAR(10000) | NOT NULL | Текст сообщения | +| role | VARCHAR(20) | NOT NULL | user/assistant/system | +| message_order | INTEGER | NOT NULL | Порядок в диалоге | +| created_at | TIMESTAMP | NOT NULL | Время создания | + +**Foreign Keys:** +```sql +FOREIGN KEY (session_id) REFERENCES chat_sessions(id) ON DELETE CASCADE +``` + +**Индексы:** +```sql +CREATE INDEX idx_chat_messages_session_id ON chat_messages(session_id); +CREATE INDEX idx_chat_messages_created_at ON chat_messages(created_at); +CREATE INDEX idx_chat_messages_session_order ON chat_messages(session_id, message_order); +``` + +## 🔄 Entity Framework Core + +### DbContext + +```csharp +public class ChatBotDbContext : DbContext +{ + public DbSet ChatSessions { get; set; } + public DbSet ChatMessages { get; set; } +} +``` + +### Конфигурация моделей + +```csharp +protected override void OnModelCreating(ModelBuilder modelBuilder) +{ + // ChatSessionEntity + modelBuilder.Entity(entity => + { + entity.HasKey(e => e.Id); + entity.Property(e => e.SessionId).IsRequired().HasMaxLength(50); + entity.HasIndex(e => e.SessionId).IsUnique(); + entity.HasIndex(e => e.ChatId); + + entity.HasMany(e => e.Messages) + .WithOne(e => e.Session) + .HasForeignKey(e => e.SessionId) + .OnDelete(DeleteBehavior.Cascade); + }); + + // ChatMessageEntity + modelBuilder.Entity(entity => + { + entity.HasKey(e => e.Id); + entity.Property(e => e.Content).IsRequired().HasMaxLength(10000); + entity.HasIndex(e => e.SessionId); + entity.HasIndex(e => new { e.SessionId, e.MessageOrder }); + }); +} +``` + +### Миграции + +#### Создание миграции + +```bash +dotnet ef migrations add InitialCreate --project ChatBot +``` + +#### Применение миграций + +```bash +# Вручную +dotnet ef database update --project ChatBot + +# Автоматически при запуске (DatabaseInitializationService) +``` + +#### Откат миграции + +```bash +dotnet ef database update PreviousMigration --project ChatBot +``` + +#### Удаление последней миграции + +```bash +dotnet ef migrations remove --project ChatBot +``` + +## 🔌 Подключение к БД + +### Connection String + +``` +Host={host};Port={port};Database={name};Username={user};Password={password} +``` + +**Пример:** +``` +Host=localhost;Port=5432;Database=chatbot;Username=chatbot;Password=secret +``` + +### Конфигурация в Program.cs + +```csharp +builder.Services.AddDbContext( + (serviceProvider, options) => + { + var dbSettings = serviceProvider + .GetRequiredService>() + .Value; + + options.UseNpgsql( + dbSettings.ConnectionString, + npgsqlOptions => + { + npgsqlOptions.CommandTimeout(dbSettings.CommandTimeout); + } + ); + } +); +``` + +### Connection Pooling + +Npgsql автоматически использует connection pooling: + +``` +Max Pool Size=100 +Min Pool Size=1 +Connection Lifetime=300 +Connection Idle Lifetime=300 +``` + +## 📝 Repository Pattern + +### Interface + +```csharp +public interface IChatSessionRepository +{ + Task GetByChatIdAsync(long chatId); + Task CreateAsync(ChatSessionEntity session); + Task UpdateAsync(ChatSessionEntity session); + Task DeleteAsync(int id); + Task> GetAllAsync(); +} +``` + +### Implementation + +```csharp +public class ChatSessionRepository : IChatSessionRepository +{ + private readonly ChatBotDbContext _context; + + public async Task GetByChatIdAsync(long chatId) + { + return await _context.ChatSessions + .Include(s => s.Messages) + .FirstOrDefaultAsync(s => s.ChatId == chatId); + } + + public async Task CreateAsync(ChatSessionEntity session) + { + _context.ChatSessions.Add(session); + await _context.SaveChangesAsync(); + return session; + } +} +``` + +## 🚀 Оптимизация запросов + +### Eager Loading + +```csharp +// Загрузка с сообщениями +var session = await _context.ChatSessions + .Include(s => s.Messages) + .FirstOrDefaultAsync(s => s.ChatId == chatId); +``` + +### Projections + +```csharp +// Только нужные поля +var sessionInfo = await _context.ChatSessions + .Where(s => s.ChatId == chatId) + .Select(s => new { s.SessionId, s.Model }) + .FirstOrDefaultAsync(); +``` + +### AsNoTracking + +```csharp +// Read-only запросы +var sessions = await _context.ChatSessions + .AsNoTracking() + .ToListAsync(); +``` + +## 🔧 Обслуживание БД + +### Vacuum (очистка) + +```sql +VACUUM ANALYZE chat_sessions; +VACUUM ANALYZE chat_messages; +``` + +### Статистика + +```sql +SELECT + schemaname, + tablename, + n_live_tup, + n_dead_tup +FROM pg_stat_user_tables +WHERE tablename IN ('chat_sessions', 'chat_messages'); +``` + +### Размер таблиц + +```sql +SELECT + tablename, + pg_size_pretty(pg_total_relation_size(tablename::regclass)) as size +FROM pg_tables +WHERE schemaname = 'public'; +``` + +## 🛡️ Безопасность + +### SQL Injection Prevention + +Entity Framework Core автоматически параметризует запросы: + +```csharp +// ✅ Безопасно +var session = await _context.ChatSessions + .Where(s => s.ChatId == chatId) + .FirstOrDefaultAsync(); +``` + +### Права пользователя БД + +```sql +-- Создание пользователя +CREATE USER chatbot WITH PASSWORD 'secure_password'; + +-- Выдача прав +GRANT CONNECT ON DATABASE chatbot TO chatbot; +GRANT USAGE ON SCHEMA public TO chatbot; +GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO chatbot; +GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO chatbot; +``` + +## 📊 Мониторинг + +### Active Connections + +```sql +SELECT count(*) +FROM pg_stat_activity +WHERE datname = 'chatbot'; +``` + +### Long Running Queries + +```sql +SELECT + pid, + now() - pg_stat_activity.query_start AS duration, + query +FROM pg_stat_activity +WHERE state = 'active' +ORDER BY duration DESC; +``` + +### Locks + +```sql +SELECT * FROM pg_locks +WHERE NOT granted; +``` + +## 🔄 Backup & Restore + +### Backup + +```bash +# Полный backup +pg_dump -U chatbot chatbot > backup.sql + +# Только схема +pg_dump -U chatbot --schema-only chatbot > schema.sql + +# Только данные +pg_dump -U chatbot --data-only chatbot > data.sql +``` + +### Restore + +```bash +# Восстановление +psql -U chatbot chatbot < backup.sql +``` + +## 📚 См. также + +- [Модели данных](./data-models.md) +- [Конфигурация](../configuration.md) +- [Установка](../installation.md) diff --git a/docs/architecture/layers.md b/docs/architecture/layers.md new file mode 100644 index 0000000..b63f863 --- /dev/null +++ b/docs/architecture/layers.md @@ -0,0 +1,349 @@ +# 🏛️ Слои приложения + +Детальное описание каждого слоя архитектуры ChatBot. + +## 1️⃣ Presentation Layer (Уровень представления) + +### Telegram Bot Integration + +Отвечает за взаимодействие с пользователями через Telegram. + +#### Основные компоненты + +**TelegramBotService** +- Главный сервис, управляющий ботом +- Запускается как `IHostedService` +- Получает updates через Webhook или Long Polling +- Координирует обработку сообщений + +**TelegramMessageHandler** +- Обработка входящих сообщений +- Фильтрация по типу чата +- Извлечение информации о пользователе +- Передача в ChatService + +**TelegramCommandProcessor** +- Распознавание команд (`/start`, `/help`, и т.д.) +- Routing к соответствующему обработчику +- Валидация прав доступа + +**Commands (Команды)** +``` +StartCommand - /start +HelpCommand - /help +ClearCommand - /clear +SettingsCommand - /settings +StatusCommand - /status +``` + +#### Паттерн Command + +```csharp +public interface ITelegramCommand +{ + string Command { get; } + string Description { get; } + Task ExecuteAsync(TelegramCommandContext context); +} +``` + +Каждая команда: +- Изолирована +- Легко тестируется +- Независимо расширяема + +## 2️⃣ Service Layer (Бизнес-логика) + +### Core Services + +#### ChatService + +**Ответственность:** +- Управление сессиями чатов +- Координация между AI и storage +- Обработка сообщений пользователей + +**Методы:** +```csharp +GetOrCreateSession() // Получить/создать сессию +ProcessMessageAsync() // Обработать сообщение +ClearHistoryAsync() // Очистить историю +UpdateSessionParameters() // Обновить параметры +``` + +**Взаимодействия:** +- IAIService → Генерация ответов +- ISessionStorage → Хранение сессий +- IHistoryCompressionService → Оптимизация истории + +#### AIService + +**Ответственность:** +- Генерация ответов через Ollama +- Управление retry логикой +- Таймауты и error handling + +**Методы:** +```csharp +GenerateChatCompletionAsync() // Базовая генерация +GenerateChatCompletionWithCompressionAsync() // С сжатием +``` + +**Особенности:** +- Экспоненциальный backoff +- Streaming responses +- Timeout handling +- System prompt injection + +#### HistoryCompressionService + +**Ответственность:** +- Суммаризация длинной истории +- Оптимизация контекста +- Сохранение важной информации + +**Алгоритм:** +``` +1. Сохранить system prompt +2. Сохранить последние N сообщений +3. Суммаризировать старые сообщения +4. Объединить результаты +``` + +**Методы:** +```csharp +ShouldCompress() // Проверка необходимости +CompressHistoryAsync() // Выполнить сжатие +SummarizeMessageAsync() // Суммаризировать одно сообщение +``` + +#### SystemPromptService + +**Ответственность:** +- Загрузка системного промпта +- Кеширование промпта +- Обработка ошибок чтения файла + +#### ModelService + +**Ответственность:** +- Управление AI моделями +- Получение списка доступных моделей +- Переключение между моделями + +### Storage Services + +#### DatabaseSessionStorage + +**Ответственность:** +- Сохранение сессий в PostgreSQL +- CRUD операции через репозиторий +- Синхронизация с базой данных + +**Методы:** +```csharp +GetOrCreate() // Получить или создать +Get() // Получить по ID +SaveSessionAsync() // Сохранить сессию +Remove() // Удалить сессию +CleanupOldSessions() // Очистка старых +``` + +**Особенности:** +- Автоматическая конвертация Entity ↔ Model +- Lazy loading сессий +- Кеширование в памяти + +#### InMemorySessionStorage + +**Ответственность:** +- Хранение сессий в памяти +- Быстрый доступ для тестов +- Не требует БД + +**Использование:** +- Unit тесты +- Development режим +- Прототипирование + +## 3️⃣ Data Access Layer (Доступ к данным) + +### DbContext + +**ChatBotDbContext** +- Entity Framework Core контекст +- Конфигурация таблиц +- Отношения между сущностями + +```csharp +DbSet ChatSessions +DbSet ChatMessages +``` + +**Конфигурация:** +- Индексы для оптимизации +- Foreign Keys и Cascade Delete +- Constraints и Validation + +### Repositories + +#### ChatSessionRepository + +**Ответственность:** +- Абстракция доступа к данным +- CRUD операции с сессиями +- Query оптимизация + +**Методы:** +```csharp +GetByChatIdAsync() // По chat ID +CreateAsync() // Создать +UpdateAsync() // Обновить +DeleteAsync() // Удалить +GetAllAsync() // Все сессии +``` + +**Преимущества паттерна Repository:** +- Изоляция от EF Core +- Легкое тестирование +- Возможность смены ORM + +### Entities (Сущности БД) + +#### ChatSessionEntity + +```csharp +Id // PK +SessionId // Unique identifier +ChatId // Telegram chat ID +ChatType // private/group/supergroup +ChatTitle // Название чата +Model // AI модель +CreatedAt // Дата создания +LastUpdatedAt // Последнее обновление +Messages // Коллекция сообщений +``` + +#### ChatMessageEntity + +```csharp +Id // PK +SessionId // FK → ChatSessionEntity +Content // Текст сообщения +Role // user/assistant/system +MessageOrder // Порядок в диалоге +CreatedAt // Дата создания +``` + +## 4️⃣ Infrastructure Layer (Инфраструктура) + +### External Services + +#### PostgreSQL + +**Функции:** +- Persistent storage сессий +- Транзакционность +- ACID гарантии + +**Оптимизации:** +- Индексы на ChatId, SessionId +- Connection pooling +- Query optimization + +#### Ollama + +**Функции:** +- Локальные LLM модели +- Streaming responses +- Multiple models support + +**Адаптер:** +```csharp +OllamaClientAdapter : IOllamaClient +``` + +Абстрагирует от конкретной реализации OllamaSharp. + +#### Telegram Bot API + +**Функции:** +- Получение updates +- Отправка сообщений +- Управление ботом + +**Wrapper:** +```csharp +TelegramBotClientWrapper : ITelegramBotClientWrapper +``` + +## 🔄 Взаимодействие слоев + +### Правила взаимодействия + +``` +Presentation → Service → Data → Infrastructure + ↓ ↓ ↓ + Interfaces Interfaces Repository +``` + +**Принципы:** +- Слои зависят только от интерфейсов +- Вышестоящие слои не знают о нижестоящих +- Dependency Injection связывает реализации + +### Пример: Обработка сообщения + +``` +1. TelegramBotService (Presentation) + ↓ вызывает +2. TelegramMessageHandler (Presentation) + ↓ вызывает +3. ChatService (Service) + ↓ использует +4. ISessionStorage (Service Interface) + ↓ реализован как +5. DatabaseSessionStorage (Service) + ↓ использует +6. IChatSessionRepository (Data Interface) + ↓ реализован как +7. ChatSessionRepository (Data) + ↓ использует +8. ChatBotDbContext (Data) + ↓ обращается к +9. PostgreSQL (Infrastructure) +``` + +## 🎯 Разделение ответственности + +### Presentation Layer +- ✅ Обработка входящих запросов +- ✅ Валидация команд +- ✅ Форматирование ответов +- ❌ Бизнес-логика +- ❌ Доступ к данным + +### Service Layer +- ✅ Бизнес-логика +- ✅ Координация сервисов +- ✅ Валидация бизнес-правил +- ❌ UI логика +- ❌ SQL запросы + +### Data Layer +- ✅ CRUD операции +- ✅ Query построение +- ✅ Маппинг Entity ↔ Model +- ❌ Бизнес-логика +- ❌ UI логика + +### Infrastructure Layer +- ✅ Внешние интеграции +- ✅ Конфигурация подключений +- ❌ Бизнес-логика + +## 📚 См. также + +- [Архитектура - Обзор](./overview.md) +- [Модели данных](./data-models.md) +- [Структура проекта](../development/project-structure.md) diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md new file mode 100644 index 0000000..110412d --- /dev/null +++ b/docs/architecture/overview.md @@ -0,0 +1,210 @@ +# 🏗️ Архитектура проекта + +## 📐 Общая архитектура + +ChatBot построен на принципах **Clean Architecture** с четким разделением ответственности. + +## 🔄 Диаграмма слоев + +``` +┌─────────────────────────────────────────────┐ +│ Presentation Layer │ +│ (Telegram Bot, Commands, Handlers) │ +├─────────────────────────────────────────────┤ +│ Service Layer │ +│ (ChatService, AIService, Compression) │ +├─────────────────────────────────────────────┤ +│ Data Access Layer │ +│ (Repositories, DbContext, Entities) │ +├─────────────────────────────────────────────┤ +│ Infrastructure Layer │ +│ (PostgreSQL, Ollama, Telegram) │ +└─────────────────────────────────────────────┘ +``` + +## 🎯 Принципы проектирования + +### SOLID + +- **S**ingle Responsibility - Каждый класс имеет одну ответственность +- **O**pen/Closed - Открыт для расширения, закрыт для модификации +- **L**iskov Substitution - Интерфейсы взаимозаменяемы +- **I**nterface Segregation - Мелкие специализированные интерфейсы +- **D**ependency Inversion - Зависимость от абстракций + +### Design Patterns + +- **Repository Pattern** - `IChatSessionRepository` +- **Dependency Injection** - Microsoft.Extensions.DependencyInjection +- **Strategy Pattern** - `ISessionStorage` (In-Memory/Database) +- **Command Pattern** - Telegram команды +- **Adapter Pattern** - `OllamaClientAdapter` + +## 📦 Компоненты системы + +### 1. Presentation Layer + +**Telegram Bot Integration:** +- `TelegramBotService` - Основной сервис бота +- `TelegramMessageHandler` - Обработка сообщений +- `TelegramCommandProcessor` - Обработка команд +- `TelegramErrorHandler` - Обработка ошибок +- Commands: `StartCommand`, `HelpCommand`, `ClearCommand`, etc. + +### 2. Service Layer + +**Core Services:** +- `ChatService` - Управление диалогами +- `AIService` - Генерация ответов AI +- `HistoryCompressionService` - Сжатие истории +- `SystemPromptService` - Загрузка системного промпта +- `ModelService` - Управление AI моделями + +**Storage Services:** +- `DatabaseSessionStorage` - Хранение в БД +- `InMemorySessionStorage` - Хранение в памяти + +### 3. Data Access Layer + +**Repositories:** +- `ChatSessionRepository` - Работа с сессиями +- `ChatBotDbContext` - EF Core контекст + +**Entities:** +- `ChatSessionEntity` - Сессия чата +- `ChatMessageEntity` - Сообщение чата + +### 4. Infrastructure + +**External Services:** +- PostgreSQL - База данных +- Ollama - AI модели +- Telegram Bot API - Telegram интеграция + +## 🔌 Dependency Injection + +```csharp +// Telegram Services +services.AddSingleton +services.AddSingleton +services.AddSingleton + +// Core Services +services.AddSingleton +services.AddScoped +services.AddScoped + +// Data Access +services.AddDbContext +services.AddScoped +``` + +## 🔄 Data Flow + +### Обработка сообщения пользователя + +``` +User Message + ↓ +TelegramBotService (получение update) + ↓ +TelegramMessageHandler (валидация) + ↓ +TelegramCommandProcessor (проверка команды) + ↓ (если не команда) +ChatService (обработка сообщения) + ↓ +SessionStorage (получение/создание сессии) + ↓ +AIService (генерация ответа) + ↓ +OllamaClient (запрос к AI) + ↓ +AIService (получение ответа) + ↓ +ChatService (сохранение в историю) + ↓ +SessionStorage (сохранение сессии) + ↓ +TelegramMessageSender (отправка ответа) + ↓ +User receives response +``` + +## 🗂️ Структура проекта + +``` +ChatBot/ +├── Common/ # Общие константы +│ └── Constants/ +├── Data/ # Слой доступа к данным +│ ├── Interfaces/ +│ ├── Repositories/ +│ └── ChatBotDbContext.cs +├── Models/ # Модели и конфигурация +│ ├── Configuration/ +│ ├── Dto/ +│ ├── Entities/ +│ └── ChatSession.cs +├── Services/ # Бизнес-логика +│ ├── HealthChecks/ +│ ├── Interfaces/ +│ ├── Telegram/ +│ └── *.cs +├── Migrations/ # EF Core миграции +├── Prompts/ # AI промпты +└── Program.cs # Точка входа +``` + +## 📊 Диаграмма классов (упрощенная) + +``` +┌─────────────────────┐ +│ ChatService │ +├─────────────────────┤ +│ + ProcessMessage() │ +│ + ClearHistory() │ +└──────────┬──────────┘ + │ + ├──> IAIService + ├──> ISessionStorage + └──> IHistoryCompressionService + +┌─────────────────────┐ +│ AIService │ +├─────────────────────┤ +│ + GenerateChat() │ +└──────────┬──────────┘ + │ + └──> IOllamaClient +``` + +## 🔐 Security Architecture + +- Секреты в переменных окружения +- Валидация входных данных +- SQL инъекции предотвращены (EF Core) +- Безопасное логирование (без секретов) + +## 📈 Scalability + +**Готовность к масштабированию:** +- Stateless сервисы +- Database session storage +- Async/await везде +- Connection pooling +- Health checks + +## 🎛️ Configuration Management + +``` +Environment Variables → .env + ↓ +appsettings.json + ↓ +IOptions + ↓ +Validation (FluentValidation) + ↓ +Services +``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..202ce0d --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,449 @@ +# ⚙️ Конфигурация + +Полное руководство по настройке ChatBot. + +## 📝 Иерархия конфигурации + +Настройки загружаются в следующем порядке (последующие переопределяют предыдущие): + +1. `appsettings.json` - Базовые настройки +2. `appsettings.Development.json` - Настройки для разработки +3. User Secrets - Секреты для разработки +4. Переменные окружения - Production настройки +5. `.env` файл - Локальные переменные + +## 🔐 Переменные окружения + +### Telegram Bot + +```env +# Обязательно +TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz +``` + +### Ollama + +```env +# URL сервера Ollama +OLLAMA_URL=http://localhost:11434 + +# Модель по умолчанию +OLLAMA_DEFAULT_MODEL=gemma2:2b +``` + +### База данных + +```env +# Подключение к PostgreSQL +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=chatbot +DB_USER=postgres +DB_PASSWORD=your_secure_password +``` + +## 📄 appsettings.json + +### Полная структура + +```json +{ + "Serilog": { + "MinimumLevel": { + "Default": "Information", + "Override": { + "Microsoft": "Warning", + "System": "Warning" + } + }, + "WriteTo": [ + { + "Name": "Console", + "Args": { + "outputTemplate": "[{Timestamp:HH:mm:ss}] [{Level}] {Message}{NewLine}{Exception}" + } + }, + { + "Name": "File", + "Args": { + "path": "logs/telegram-bot-.log", + "rollingInterval": "Day", + "retainedFileCountLimit": 7 + } + } + ] + }, + "TelegramBot": { + "BotToken": "" + }, + "Ollama": { + "Url": "", + "DefaultModel": "" + }, + "AI": { + "Temperature": 0.9, + "SystemPromptPath": "Prompts/system-prompt.txt", + "MaxRetryAttempts": 3, + "RetryDelayMs": 1000, + "RequestTimeoutSeconds": 180, + "EnableHistoryCompression": true, + "CompressionThreshold": 20, + "CompressionTarget": 10, + "MinMessageLengthForSummarization": 50, + "MaxSummarizedMessageLength": 200, + "EnableExponentialBackoff": true, + "MaxRetryDelayMs": 30000, + "CompressionTimeoutSeconds": 30, + "StatusCheckTimeoutSeconds": 10 + }, + "Database": { + "ConnectionString": "", + "EnableSensitiveDataLogging": false, + "CommandTimeout": 30 + } +} +``` + +## 🎯 Секции конфигурации + +### TelegramBot + +| Параметр | Тип | Описание | По умолчанию | +|----------|-----|----------|--------------| +| `BotToken` | string | Токен бота от @BotFather | - | + +**Валидация:** +- Токен не может быть пустым +- Минимальная длина: 10 символов + +**Пример:** +```json +{ + "TelegramBot": { + "BotToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz" + } +} +``` + +### Ollama + +| Параметр | Тип | Описание | По умолчанию | +|----------|-----|----------|--------------| +| `Url` | string | URL Ollama сервера | http://localhost:11434 | +| `DefaultModel` | string | Модель по умолчанию | gemma2:2b | + +**Валидация:** +- URL должен быть валидным HTTP/HTTPS адресом +- Модель не может быть пустой + +**Пример:** +```json +{ + "Ollama": { + "Url": "http://localhost:11434", + "DefaultModel": "gemma2:2b" + } +} +``` + +**Доступные модели:** +- `gemma2:2b` - Быстрая, легкая (2GB RAM) +- `llama3.2` - Средняя (4GB RAM) +- `mistral` - Продвинутая (8GB RAM) +- `phi3` - Компактная (2.5GB RAM) + +### AI + +| Параметр | Тип | Описание | По умолчанию | +|----------|-----|----------|--------------| +| `Temperature` | double | Креативность ответов (0.0-2.0) | 0.9 | +| `SystemPromptPath` | string | Путь к системному промпту | Prompts/system-prompt.txt | +| `MaxRetryAttempts` | int | Макс. попыток повтора | 3 | +| `RetryDelayMs` | int | Задержка между попытками (мс) | 1000 | +| `RequestTimeoutSeconds` | int | Таймаут запроса (сек) | 180 | +| `EnableHistoryCompression` | bool | Включить сжатие истории | true | +| `CompressionThreshold` | int | Порог для сжатия (кол-во сообщений) | 20 | +| `CompressionTarget` | int | Целевое кол-во после сжатия | 10 | +| `MinMessageLengthForSummarization` | int | Мин. длина для суммаризации | 50 | +| `MaxSummarizedMessageLength` | int | Макс. длина суммаризации | 200 | +| `EnableExponentialBackoff` | bool | Экспоненциальный backoff | true | +| `MaxRetryDelayMs` | int | Макс. задержка повтора (мс) | 30000 | +| `CompressionTimeoutSeconds` | int | Таймаут сжатия (сек) | 30 | +| `StatusCheckTimeoutSeconds` | int | Таймаут проверки статуса (сек) | 10 | + +**Валидация:** +- `Temperature`: 0.0 ≤ x ≤ 2.0 +- `MaxRetryAttempts`: 1 ≤ x ≤ 10 +- `RetryDelayMs`: 100 ≤ x ≤ 60000 +- `RequestTimeoutSeconds`: 10 ≤ x ≤ 600 + +**Пример:** +```json +{ + "AI": { + "Temperature": 0.9, + "MaxRetryAttempts": 3, + "EnableHistoryCompression": true, + "CompressionThreshold": 20 + } +} +``` + +#### Temperature (Температура) + +Определяет "креативность" ответов AI: + +- **0.0-0.3**: Детерминированные, предсказуемые ответы +- **0.4-0.7**: Сбалансированные ответы +- **0.8-1.2**: Креативные, разнообразные ответы (рекомендуется) +- **1.3-2.0**: Очень креативные, иногда непредсказуемые + +#### History Compression + +Автоматическое сжатие истории диалога для оптимизации: + +``` +История: 20+ сообщений + ↓ (сжатие) +Результат: 10 сообщений (суммаризация старых) +``` + +**Алгоритм:** +1. Сохранить системный промпт +2. Сохранить последние N сообщений +3. Старые сообщения суммаризировать + +### Database + +| Параметр | Тип | Описание | По умолчанию | +|----------|-----|----------|--------------| +| `ConnectionString` | string | Строка подключения PostgreSQL | - | +| `EnableSensitiveDataLogging` | bool | Логировать SQL запросы | false | +| `CommandTimeout` | int | Таймаут команд (сек) | 30 | + +**Валидация:** +- Connection string не может быть пустой +- `CommandTimeout`: 5 ≤ x ≤ 300 + +**Пример:** +```json +{ + "Database": { + "ConnectionString": "Host=localhost;Port=5432;Database=chatbot;Username=chatbot;Password=password", + "EnableSensitiveDataLogging": false, + "CommandTimeout": 30 + } +} +``` + +**Connection String формат:** +``` +Host={host};Port={port};Database={name};Username={user};Password={password} +``` + +### Serilog (Логирование) + +| Параметр | Тип | Описание | +|----------|-----|----------| +| `MinimumLevel.Default` | string | Минимальный уровень логов | +| `WriteTo` | array | Sink'и для записи | + +**Уровни логирования:** +- `Verbose` - Все детали (разработка) +- `Debug` - Отладочная информация +- `Information` - Общая информация (по умолчанию) +- `Warning` - Предупреждения +- `Error` - Ошибки +- `Fatal` - Критические ошибки + +**Пример:** +```json +{ + "Serilog": { + "MinimumLevel": { + "Default": "Information", + "Override": { + "Microsoft.EntityFrameworkCore": "Warning" + } + }, + "WriteTo": [ + { + "Name": "Console" + }, + { + "Name": "File", + "Args": { + "path": "logs/app-.log", + "rollingInterval": "Day" + } + } + ] + } +} +``` + +## 🔧 Настройка системного промпта + +Файл: `ChatBot/Prompts/system-prompt.txt` + +Этот файл определяет личность и стиль общения бота. + +### Структура промпта + +``` +[Персонаж] +- Имя, возраст, локация +- Интересы, хобби +- Стиль общения + +[Правила ответов] +- Естественность +- Обработка {empty} +- Реакция на провокации + +[Примеры] +- Корректные ответы +- Примеры {empty} +``` + +### Специальные маркеры + +**{empty}** - Бот игнорирует сообщение + +Используется когда: +- Сообщение адресовано другому человеку +- Контекст не требует ответа +- Провокационные вопросы о боте + +### Кастомизация промпта + +1. Откройте `Prompts/system-prompt.txt` +2. Отредактируйте под свои нужды +3. Сохраните файл +4. Перезапустите бота + +## 🔄 Переключение режимов + +### In-Memory Storage (для тестов) + +В `Program.cs`: +```csharp +// Заменить +builder.Services.AddScoped(); + +// На +builder.Services.AddScoped(); +``` + +### Отключение сжатия истории + +В `appsettings.json`: +```json +{ + "AI": { + "EnableHistoryCompression": false + } +} +``` + +### Изменение уровня логирования + +```json +{ + "Serilog": { + "MinimumLevel": { + "Default": "Debug" // или Verbose + } + } +} +``` + +## 📊 Примеры конфигураций + +### Development (разработка) + +```json +{ + "AI": { + "Temperature": 0.7, + "EnableHistoryCompression": false, + "MaxRetryAttempts": 2 + }, + "Database": { + "EnableSensitiveDataLogging": true + }, + "Serilog": { + "MinimumLevel": { + "Default": "Debug" + } + } +} +``` + +### Production (production) + +```json +{ + "AI": { + "Temperature": 0.9, + "EnableHistoryCompression": true, + "MaxRetryAttempts": 3 + }, + "Database": { + "EnableSensitiveDataLogging": false + }, + "Serilog": { + "MinimumLevel": { + "Default": "Information" + } + } +} +``` + +### High Performance (производительность) + +```json +{ + "AI": { + "Temperature": 0.8, + "RequestTimeoutSeconds": 120, + "EnableHistoryCompression": true, + "CompressionThreshold": 15, + "CompressionTarget": 8 + } +} +``` + +## 🔍 Проверка конфигурации + +### Валидация при старте + +Приложение автоматически валидирует конфигурацию при запуске. + +**Ошибки валидации:** +``` +Options validation failed for 'TelegramBotSettings' with errors: +- BotToken cannot be empty +``` + +### Просмотр текущей конфигурации + +Используйте команду бота: +``` +/settings +``` + +Ответ: +``` +⚙️ Текущие настройки: +🤖 Модель: gemma2:2b +🌡️ Temperature: 0.9 +📝 Сообщений в истории: 5/30 +🗜️ Сжатие истории: Включено +``` + +## 📚 См. также + +- [Установка](./installation.md) +- [Быстрый старт](./quickstart.md) +- [Development](./development/project-structure.md) diff --git a/docs/development/project-structure.md b/docs/development/project-structure.md new file mode 100644 index 0000000..55072f3 --- /dev/null +++ b/docs/development/project-structure.md @@ -0,0 +1,344 @@ +# 📁 Структура проекта + +Подробное описание организации кода в ChatBot. + +## 🌳 Дерево проекта + +``` +ChatBot/ +├── .gitea/ +│ └── workflows/ +│ └── build.yml # CI/CD pipeline (SonarQube) +├── ChatBot/ # Основной проект +│ ├── Common/ +│ │ └── Constants/ +│ │ ├── AIResponseConstants.cs +│ │ └── ChatTypes.cs +│ ├── Data/ +│ │ ├── Interfaces/ +│ │ │ └── IChatSessionRepository.cs +│ │ ├── Repositories/ +│ │ │ └── ChatSessionRepository.cs +│ │ └── ChatBotDbContext.cs +│ ├── Migrations/ +│ │ └── [EF Core миграции] +│ ├── Models/ +│ │ ├── Configuration/ +│ │ │ ├── Validators/ +│ │ │ ├── AISettings.cs +│ │ │ ├── DatabaseSettings.cs +│ │ │ ├── OllamaSettings.cs +│ │ │ └── TelegramBotSettings.cs +│ │ ├── Dto/ +│ │ │ └── ChatMessage.cs +│ │ ├── Entities/ +│ │ │ ├── ChatMessageEntity.cs +│ │ │ └── ChatSessionEntity.cs +│ │ └── ChatSession.cs +│ ├── Prompts/ +│ │ └── system-prompt.txt # AI промпт +│ ├── Properties/ +│ │ └── launchSettings.json +│ ├── Services/ +│ │ ├── HealthChecks/ +│ │ │ ├── OllamaHealthCheck.cs +│ │ │ └── TelegramBotHealthCheck.cs +│ │ ├── Interfaces/ +│ │ │ ├── IAIService.cs +│ │ │ ├── IHistoryCompressionService.cs +│ │ │ ├── IOllamaClient.cs +│ │ │ ├── ISessionStorage.cs +│ │ │ └── ITelegramBotClientWrapper.cs +│ │ ├── Telegram/ +│ │ │ ├── Commands/ +│ │ │ │ ├── ClearCommand.cs +│ │ │ │ ├── CommandAttribute.cs +│ │ │ │ ├── CommandRegistry.cs +│ │ │ │ ├── HelpCommand.cs +│ │ │ │ ├── ReplyInfo.cs +│ │ │ │ ├── SettingsCommand.cs +│ │ │ │ ├── StartCommand.cs +│ │ │ │ ├── StatusCommand.cs +│ │ │ │ ├── TelegramCommandBase.cs +│ │ │ │ ├── TelegramCommandContext.cs +│ │ │ │ └── TelegramCommandProcessor.cs +│ │ │ ├── Interfaces/ +│ │ │ │ ├── ITelegramBotService.cs +│ │ │ │ ├── ITelegramCommand.cs +│ │ │ │ ├── ITelegramCommandProcessor.cs +│ │ │ │ ├── ITelegramErrorHandler.cs +│ │ │ │ └── ITelegramMessageHandler.cs +│ │ │ └── Services/ +│ │ │ ├── BotInfoService.cs +│ │ │ ├── TelegramBotService.cs +│ │ │ ├── TelegramErrorHandler.cs +│ │ │ ├── TelegramMessageHandler.cs +│ │ │ └── TelegramMessageSender.cs +│ │ ├── AIService.cs +│ │ ├── ChatService.cs +│ │ ├── DatabaseInitializationService.cs +│ │ ├── DatabaseSessionStorage.cs +│ │ ├── HistoryCompressionService.cs +│ │ ├── InMemorySessionStorage.cs +│ │ ├── ModelService.cs +│ │ ├── OllamaClientAdapter.cs +│ │ ├── SystemPromptService.cs +│ │ └── TelegramBotClientWrapper.cs +│ ├── appsettings.json +│ ├── appsettings.Development.json +│ ├── ChatBot.csproj +│ └── Program.cs +├── ChatBot.Tests/ # Тестовый проект +│ ├── Common/ +│ ├── Configuration/ +│ ├── Data/ +│ ├── Integration/ +│ ├── Models/ +│ ├── Program/ +│ ├── Services/ +│ ├── Telegram/ +│ └── ChatBot.Tests.csproj +├── docs/ # Документация +├── .gitignore +├── .gitattributes +├── ChatBot.sln +├── LICENSE.txt +└── README.md +``` + +## 📂 Основные папки + +### `/Common` + +Общие константы и утилиты. + +**Constants/** +- `AIResponseConstants.cs` - Константы для AI ответов + - `EmptyResponseMarker = "{empty}"` + - `DefaultErrorMessage` +- `ChatTypes.cs` - Типы чатов + - `Private`, `Group`, `Supergroup`, `Channel` + +### `/Data` + +Слой доступа к данным. + +**Interfaces/** +- `IChatSessionRepository.cs` - Интерфейс репозитория + +**Repositories/** +- `ChatSessionRepository.cs` - Реализация репозитория + +**Root:** +- `ChatBotDbContext.cs` - EF Core контекст + +### `/Models` + +Модели данных и конфигурация. + +**Configuration/** +- Settings классы для конфигурации +- **Validators/** - FluentValidation валидаторы + +**Dto/** +- `ChatMessage.cs` - DTO для сообщений + +**Entities/** +- `ChatSessionEntity.cs` - Сущность сессии +- `ChatMessageEntity.cs` - Сущность сообщения + +**Root:** +- `ChatSession.cs` - Доменная модель сессии + +### `/Services` + +Бизнес-логика приложения. + +**HealthChecks/** +- `OllamaHealthCheck.cs` - Проверка Ollama +- `TelegramBotHealthCheck.cs` - Проверка Telegram + +**Interfaces/** +- Интерфейсы всех сервисов + +**Telegram/** +- **Commands/** - Реализация команд бота +- **Interfaces/** - Интерфейсы Telegram сервисов +- **Services/** - Реализация Telegram сервисов + +**Root Services:** +- `AIService.cs` - Работа с AI +- `ChatService.cs` - Управление чатами +- `HistoryCompressionService.cs` - Сжатие истории +- `DatabaseSessionStorage.cs` - Хранение в БД +- `InMemorySessionStorage.cs` - Хранение в памяти +- И другие... + +### `/Migrations` + +EF Core миграции базы данных. + +### `/Prompts` + +AI промпты. + +- `system-prompt.txt` - Системный промпт для AI + +## 🎯 Naming Conventions + +### Файлы + +- **Classes**: `PascalCase.cs` (например, `ChatService.cs`) +- **Interfaces**: `IPascalCase.cs` (например, `IAIService.cs`) +- **Tests**: `ClassNameTests.cs` + +### Namespace + +```csharp +namespace ChatBot.Services +namespace ChatBot.Models.Configuration +namespace ChatBot.Data.Repositories +``` + +Структура namespace соответствует структуре папок. + +### Классы + +```csharp +public class ChatService // Service classes +public interface IAIService // Interfaces (I prefix) +public class ChatSession // Models +public class ChatSessionEntity // Entities (Entity suffix) +``` + +## 🔍 Зависимости между слоями + +``` +Program.cs + ↓ +Services/ + ↓ +Data/Repositories + ↓ +Data/ChatBotDbContext + ↓ +Models/Entities +``` + +### Правила: +- Services зависят от Interfaces +- Repositories зависят от Entities +- Models независимы +- Presentation зависит от Services + +## 📦 NuGet пакеты + +### Основные + +```xml + + + + +``` + +### Логирование + +```xml + + + + +``` + +### Validation + +```xml + + +``` + +## 🧪 Тестовый проект + +### Структура + +``` +ChatBot.Tests/ +├── Common/ # Тесты констант +├── Configuration/ # Тесты валидаторов +├── Data/ # Тесты репозиториев и DbContext +├── Integration/ # Интеграционные тесты +├── Models/ # Тесты моделей +├── Services/ # Тесты сервисов +└── Telegram/ # Тесты Telegram функций +``` + +### Naming Convention + +```csharp +public class ChatServiceTests +{ + [Fact] + public void ProcessMessage_ShouldReturnResponse() + + [Theory] + [InlineData(...)] + public void Method_Scenario_ExpectedBehavior() +} +``` + +## 🔧 Configuration Files + +### appsettings.json + +Основная конфигурация приложения. + +### appsettings.Development.json + +Переопределения для Development режима. + +### .env + +Локальные переменные окружения (не в git). + +### launchSettings.json + +Настройки запуска для Visual Studio/Rider. + +## 📝 Special Files + +### Program.cs + +Точка входа приложения: +- Конфигурация DI +- Регистрация сервисов +- Инициализация логирования + +### ChatBot.csproj + +Project file: +- Target Framework: net9.0 +- Package References +- Build configurations + +### ChatBot.sln + +Solution file для Visual Studio. + +## 🚀 Build Output + +``` +bin/ +├── Debug/ +│ └── net9.0/ +├── Release/ +│ └── net9.0/ +obj/ +└── [Промежуточные файлы] +``` + +## 📚 См. также + +- [Сервисы](./services.md) +- [Архитектура](../architecture/overview.md) +- [Разработка команд](./telegram-integration.md) diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..0c5bfc1 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,485 @@ +# 🛠️ Установка и настройка + +Подробное руководство по установке ChatBot со всеми опциями. + +## 📋 Системные требования + +### Минимальные требования +- **OS**: Windows 10/11, Linux (Ubuntu 20.04+), macOS 12+ +- **RAM**: 4 GB (рекомендуется 8 GB+) +- **CPU**: 2 cores (рекомендуется 4+ cores) +- **Диск**: 10 GB свободного места +- **Сеть**: Стабильное интернет-соединение + +### Программное обеспечение +- **.NET 9.0 SDK** - обязательно +- **PostgreSQL 14+** - обязательно +- **Ollama** - обязательно +- **Git** - для клонирования +- **Docker** (опционально) - для контейнеризации + +## 📥 Установка зависимостей + +### Windows + +#### .NET 9.0 SDK +```powershell +# Скачайте с официального сайта +# https://dotnet.microsoft.com/download/dotnet/9.0 + +# Или через winget +winget install Microsoft.DotNet.SDK.9 + +# Проверка установки +dotnet --version +``` + +#### PostgreSQL +```powershell +# Скачайте с официального сайта +# https://www.postgresql.org/download/windows/ + +# Или через chocolatey +choco install postgresql + +# Инициализация +# Следуйте инструкциям установщика +``` + +#### Ollama +```powershell +# Скачайте с официального сайта +# https://ollama.ai/download + +# Установка модели +ollama pull gemma2:2b +# или другую модель +ollama pull llama3.2 +``` + +### Linux (Ubuntu/Debian) + +#### .NET 9.0 SDK +```bash +# Добавление репозитория Microsoft +wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb +sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb + +# Установка SDK +sudo apt-get update +sudo apt-get install -y dotnet-sdk-9.0 + +# Проверка +dotnet --version +``` + +#### PostgreSQL +```bash +# Установка +sudo apt-get update +sudo apt-get install -y postgresql postgresql-contrib + +# Запуск +sudo systemctl start postgresql +sudo systemctl enable postgresql + +# Создание пользователя и БД +sudo -u postgres psql +CREATE USER chatbot WITH PASSWORD 'your_password'; +CREATE DATABASE chatbot OWNER chatbot; +GRANT ALL PRIVILEGES ON DATABASE chatbot TO chatbot; +\q +``` + +#### Ollama +```bash +# Установка +curl -fsSL https://ollama.ai/install.sh | sh + +# Запуск сервиса +sudo systemctl start ollama +sudo systemctl enable ollama + +# Установка модели +ollama pull gemma2:2b +``` + +### macOS + +#### .NET 9.0 SDK +```bash +# Через Homebrew +brew install --cask dotnet-sdk + +# Проверка +dotnet --version +``` + +#### PostgreSQL +```bash +# Через Homebrew +brew install postgresql@14 + +# Запуск +brew services start postgresql@14 + +# Создание БД +createdb chatbot +``` + +#### Ollama +```bash +# Скачайте с официального сайта +# https://ollama.ai/download + +# Или через Homebrew +brew install ollama + +# Установка модели +ollama pull gemma2:2b +``` + +## 🔧 Настройка проекта + +### 1. Клонирование репозитория + +```bash +git clone https://github.com/mrleo1nid/ChatBot.git +cd ChatBot +``` + +### 2. Настройка базы данных + +#### Создание базы данных + +**PostgreSQL:** +```sql +-- Подключение к PostgreSQL +psql -U postgres + +-- Создание пользователя +CREATE USER chatbot WITH PASSWORD 'secure_password'; + +-- Создание базы данных +CREATE DATABASE chatbot OWNER chatbot; + +-- Выдача прав +GRANT ALL PRIVILEGES ON DATABASE chatbot TO chatbot; + +-- Выход +\q +``` + +#### Проверка подключения +```bash +psql -U chatbot -d chatbot -h localhost +``` + +### 3. Конфигурация приложения + +#### Создание .env файла + +Создайте файл `ChatBot/.env`: + +```env +# Database Configuration +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=chatbot +DB_USER=chatbot +DB_PASSWORD=your_secure_password + +# Telegram Bot Configuration +TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz + +# Ollama Configuration +OLLAMA_URL=http://localhost:11434 +OLLAMA_DEFAULT_MODEL=gemma2:2b +``` + +#### Настройка appsettings.json + +Файл `ChatBot/appsettings.json` уже содержит настройки по умолчанию. Переменные окружения имеют приоритет. + +#### User Secrets (для разработки) + +```bash +cd ChatBot + +# Инициализация secrets +dotnet user-secrets init + +# Добавление секретов +dotnet user-secrets set "TelegramBot:BotToken" "your_token_here" +dotnet user-secrets set "Database:ConnectionString" "Host=localhost;Database=chatbot;Username=chatbot;Password=your_password" +``` + +### 4. Настройка Telegram бота + +#### Создание бота через BotFather + +1. Откройте Telegram и найдите [@BotFather](https://t.me/botfather) +2. Отправьте `/newbot` +3. Следуйте инструкциям: + - Введите имя бота (например: "My AI ChatBot") + - Введите username (например: "my_ai_chatbot") +4. Скопируйте токен и добавьте в `.env` + +#### Настройка команд бота (опционально) + +``` +/setcommands + +start - Начать работу с ботом +help - Показать справку +clear - Очистить историю диалога +settings - Показать текущие настройки +status - Проверить статус бота +``` + +### 5. Установка AI модели + +```bash +# Просмотр доступных моделей +ollama list + +# Установка модели +ollama pull gemma2:2b + +# Или другие модели: +ollama pull llama3.2 +ollama pull mistral +ollama pull phi3 + +# Проверка +ollama list +``` + +### 6. Применение миграций + +```bash +cd ChatBot + +# Автоматически применяются при первом запуске +# Или вручную: +dotnet ef database update + +# Проверка миграций +dotnet ef migrations list +``` + +### 7. Сборка проекта + +```bash +# Восстановление зависимостей +dotnet restore + +# Сборка +dotnet build + +# Проверка на ошибки +dotnet build --configuration Release +``` + +## 🚀 Запуск приложения + +### Режим разработки + +```bash +cd ChatBot +dotnet run +``` + +### Режим production + +```bash +# Сборка релиза +dotnet publish -c Release -o ./publish + +# Запуск +cd publish +dotnet ChatBot.dll +``` + +### Запуск как служба (Windows) + +```powershell +# Создание службы +sc.exe create ChatBot binPath="C:\path\to\publish\ChatBot.exe" + +# Запуск +sc.exe start ChatBot + +# Остановка +sc.exe stop ChatBot + +# Удаление +sc.exe delete ChatBot +``` + +### Запуск как службы (Linux) + +Создайте файл `/etc/systemd/system/chatbot.service`: + +```ini +[Unit] +Description=ChatBot Telegram Bot +After=network.target postgresql.service + +[Service] +Type=notify +WorkingDirectory=/opt/chatbot +ExecStart=/usr/bin/dotnet /opt/chatbot/ChatBot.dll +Restart=always +RestartSec=10 +User=chatbot +Environment=DOTNET_ENVIRONMENT=Production + +[Install] +WantedBy=multi-user.target +``` + +Запуск: +```bash +sudo systemctl daemon-reload +sudo systemctl enable chatbot +sudo systemctl start chatbot +sudo systemctl status chatbot +``` + +## 🐳 Docker установка + +### Создание Dockerfile + +Файл уже включен в проект. Для сборки: + +```bash +# Сборка образа +docker build -t chatbot:latest . + +# Запуск контейнера +docker run -d \ + --name chatbot \ + --env-file .env \ + -v $(pwd)/logs:/app/logs \ + chatbot:latest +``` + +### Docker Compose + +Создайте `docker-compose.yml`: + +```yaml +version: '3.8' + +services: + postgres: + image: postgres:14-alpine + environment: + POSTGRES_DB: chatbot + POSTGRES_USER: chatbot + POSTGRES_PASSWORD: ${DB_PASSWORD} + volumes: + - postgres_data:/var/lib/postgresql/data + ports: + - "5432:5432" + + chatbot: + build: . + depends_on: + - postgres + env_file: + - .env + volumes: + - ./logs:/app/logs + restart: unless-stopped + +volumes: + postgres_data: +``` + +Запуск: +```bash +docker-compose up -d +``` + +## ✅ Проверка установки + +### 1. Проверка компонентов + +```bash +# .NET +dotnet --version + +# PostgreSQL +psql --version +pg_isready + +# Ollama +curl http://localhost:11434/api/tags +``` + +### 2. Проверка подключений + +```bash +# PostgreSQL +psql -U chatbot -d chatbot -h localhost -c "SELECT version();" + +# Ollama +ollama list +``` + +### 3. Проверка логов + +```bash +# Логи приложения +tail -f ChatBot/logs/telegram-bot-*.log + +# Docker логи +docker logs -f chatbot +``` + +### 4. Тестирование бота + +1. Откройте Telegram +2. Найдите вашего бота +3. Отправьте `/start` +4. Отправьте любое сообщение + +## 🔍 Troubleshooting + +### Ошибка "Unable to connect to PostgreSQL" + +```bash +# Проверка статуса +sudo systemctl status postgresql + +# Проверка порта +netstat -tulpn | grep 5432 + +# Проверка настроек pg_hba.conf +sudo nano /etc/postgresql/14/main/pg_hba.conf +``` + +### Ошибка "Ollama connection failed" + +```bash +# Запуск Ollama +ollama serve + +# Проверка доступности +curl http://localhost:11434/api/tags +``` + +### Ошибка "Invalid bot token" + +- Проверьте правильность токена в `.env` +- Убедитесь, что токен активен через @BotFather +- Перезапустите приложение + +## 📚 Следующие шаги + +- [Конфигурация](./configuration.md) - Детальная настройка параметров +- [Разработка](./development/project-structure.md) - Структура проекта +- [Deployment](./deployment/docker.md) - Production развертывание diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..1c3543f --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,144 @@ +# 📋 Обзор проекта ChatBot + +## 🎯 Что такое ChatBot? + +**ChatBot** — это интеллектуальный Telegram-бот, использующий локальные AI модели через Ollama для создания естественных диалогов. Бот имитирует общение реального человека с индивидуальным характером и стилем общения. + +## ✨ Основные возможности + +### 🤖 AI-функциональность +- **Интеграция с Ollama** - Использование локальных LLM моделей +- **Контекстное общение** - Бот помнит историю диалога +- **Сжатие истории** - Автоматическая оптимизация длинных диалогов +- **Настраиваемый промпт** - Гибкая настройка личности бота +- **Множественные модели** - Поддержка различных AI моделей + +### 💬 Telegram функции +- **Команды бота** - `/start`, `/help`, `/clear`, `/settings`, `/status` +- **Групповые чаты** - Работа в приватных чатах и группах +- **Обработка ошибок** - Устойчивость к сбоям +- **Retry механизм** - Автоматические повторные попытки +- **Health checks** - Мониторинг состояния сервисов + +### 💾 Управление данными +- **PostgreSQL** - Хранение сессий и истории +- **Entity Framework Core** - ORM для работы с БД +- **Миграции** - Автоматическое обновление схемы БД +- **In-Memory опция** - Альтернативное хранилище для тестов + +### 🛠️ Технические особенности +- **.NET 9.0** - Современная платформа +- **Dependency Injection** - Управление зависимостями +- **Serilog** - Структурированное логирование +- **FluentValidation** - Валидация конфигурации +- **Health Checks** - Проверка работоспособности + +## 🏗️ Архитектура + +Проект построен на принципах: +- **Clean Architecture** - Разделение на слои +- **SOLID принципы** - Качественный дизайн кода +- **Dependency Inversion** - Зависимость от абстракций +- **Repository Pattern** - Абстракция доступа к данным +- **Service Layer** - Бизнес-логика в сервисах + +### Основные слои: +``` +┌─────────────────────────────────────┐ +│ Telegram Bot Layer │ +│ (TelegramBotService, Commands) │ +├─────────────────────────────────────┤ +│ Service Layer │ +│ (ChatService, AIService, etc.) │ +├─────────────────────────────────────┤ +│ Data Access Layer │ +│ (Repositories, DbContext) │ +├─────────────────────────────────────┤ +│ Infrastructure │ +│ (PostgreSQL, Ollama) │ +└─────────────────────────────────────┘ +``` + +## 🔧 Технологический стек + +### Backend +- **Runtime**: .NET 9.0 +- **Language**: C# 13 +- **Архитектура**: Worker Service + +### Библиотеки +- **Telegram.Bot** 22.7.2 - Telegram Bot API +- **OllamaSharp** 5.4.7 - Ollama клиент +- **Entity Framework Core** 9.0.10 - ORM +- **Npgsql** 9.0.4 - PostgreSQL провайдер +- **Serilog** 4.3.0 - Логирование +- **FluentValidation** 12.0.0 - Валидация + +### База данных +- **PostgreSQL** - Основное хранилище +- **In-Memory** - Опция для разработки + +### Тестирование +- **xUnit** 2.9.3 - Тестовый фреймворк +- **Moq** 4.20.72 - Моки +- **FluentAssertions** 8.7.1 - Assertions +- **Coverlet** 6.0.4 - Code coverage + +### DevOps +- **Docker** - Контейнеризация +- **Gitea Actions** - CI/CD +- **SonarQube** - Анализ кода + +## 📊 Статистика проекта + +- **Языки**: C# +- **Файлов кода**: ~100+ +- **Тестов**: 50+ test classes +- **Покрытие кода**: ~80%+ +- **Target Framework**: .NET 9.0 + +## 🎭 Особенности реализации + +### Умная обработка сообщений +Бот использует специальные маркеры в ответах AI: +- `{empty}` - Игнорировать сообщение (не для него) +- Контекстная обработка групповых чатов +- Распознавание обращений по имени + +### Оптимизация памяти +- Автоматическое сжатие длинной истории +- Сохранение системного промпта +- Настраиваемые лимиты сообщений + +### Отказоустойчивость +- Retry механизм с экспоненциальным backoff +- Обработка таймаутов +- Health checks для мониторинга + +## 🔐 Безопасность + +- Переменные окружения для секретов +- User Secrets для разработки +- Валидация конфигурации при старте +- Безопасное хранение токенов + +## 🌟 Преимущества + +1. **Модульность** - Легко расширяемая архитектура +2. **Тестируемость** - Высокое покрытие тестами +3. **Производительность** - Асинхронная обработка +4. **Надежность** - Retry механизмы и обработка ошибок +5. **Масштабируемость** - Готовность к росту нагрузки + +## 📈 Планы развития + +- [ ] Поддержка мультимодальных моделей +- [ ] Веб-интерфейс для управления +- [ ] Метрики и аналитика +- [ ] Kubernetes deployment +- [ ] Дополнительные команды +- [ ] Плагинная система + +## 🤝 Вклад в проект + +Проект открыт для contributions! См. [Contributing Guide](./contributing.md) для деталей. diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 0000000..fe34f84 --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,148 @@ +# 🚀 Быстрый старт + +Запустите ChatBot за 5 минут! + +## ⚡ Минимальные требования + +- **.NET 9.0 SDK** ([скачать](https://dotnet.microsoft.com/download/dotnet/9.0)) +- **PostgreSQL 14+** ([скачать](https://www.postgresql.org/download/)) +- **Ollama** с установленной моделью ([установить](https://ollama.ai/)) +- **Telegram Bot Token** ([создать через @BotFather](https://t.me/botfather)) + +## 📋 Шаги установки + +### 1️⃣ Клонирование репозитория + +```bash +git clone https://github.com/mrleo1nid/ChatBot.git +cd ChatBot +``` + +### 2️⃣ Установка Ollama и модели + +```bash +# Установите Ollama с официального сайта +# https://ollama.ai/ + +# Загрузите модель (например, gemma2) +ollama pull gemma2:2b +``` + +### 3️⃣ Настройка PostgreSQL + +```bash +# Создайте базу данных +psql -U postgres +CREATE DATABASE chatbot; +\q +``` + +### 4️⃣ Создание .env файла + +Создайте файл `.env` в папке `ChatBot/`: + +```env +# Database Configuration +DB_HOST=localhost +DB_PORT=5432 +DB_NAME=chatbot +DB_USER=postgres +DB_PASSWORD=your_password + +# Telegram Bot Configuration +TELEGRAM_BOT_TOKEN=your_bot_token_here + +# Ollama Configuration +OLLAMA_URL=http://localhost:11434 +OLLAMA_DEFAULT_MODEL=gemma2:2b +``` + +### 5️⃣ Запуск приложения + +```bash +# Восстановление зависимостей +dotnet restore + +# Применение миграций (автоматически при первом запуске) +# или вручную: +dotnet ef database update --project ChatBot + +# Запуск +dotnet run --project ChatBot +``` + +## 🎉 Готово! + +Теперь откройте Telegram и найдите вашего бота. Отправьте `/start` для начала общения. + +## 📱 Первые команды + +``` +/start - Начать работу с ботом +/help - Показать все команды +/clear - Очистить историю диалога +/settings - Текущие настройки +/status - Статус бота +``` + +## 🐳 Альтернатива: Docker + +```bash +# Сборка образа +docker build -t chatbot . + +# Запуск с docker-compose +docker-compose up -d +``` + +## 🔧 Проверка работы + +### Проверка Ollama +```bash +curl http://localhost:11434/api/tags +``` + +### Проверка PostgreSQL +```bash +psql -U postgres -d chatbot -c "SELECT * FROM chat_sessions;" +``` + +### Просмотр логов +Логи находятся в папке `ChatBot/logs/`: +```bash +tail -f ChatBot/logs/telegram-bot-*.log +``` + +## ❓ Проблемы? + +### Ollama недоступен +```bash +# Проверьте статус +systemctl status ollama # Linux +# или запустите вручную +ollama serve +``` + +### Ошибка подключения к БД +```bash +# Проверьте PostgreSQL +pg_isready -h localhost -p 5432 +``` + +### Неверный токен бота +- Получите новый токен через [@BotFather](https://t.me/botfather) +- Обновите `TELEGRAM_BOT_TOKEN` в `.env` + +## 📚 Следующие шаги + +- [Полная установка и настройка](./installation.md) +- [Конфигурация](./configuration.md) +- [Архитектура проекта](./architecture/overview.md) +- [Разработка](./development/project-structure.md) + +## 💡 Полезные ссылки + +- [Ollama Models](https://ollama.ai/library) +- [Telegram Bot API](https://core.telegram.org/bots/api) +- [PostgreSQL Documentation](https://www.postgresql.org/docs/) +- [.NET Documentation](https://docs.microsoft.com/dotnet/)