mrleo1nid/ChatBot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add docs
All checks were successful
SonarQube / Build and analyze (push) Successful in 3m22s
Details

Browse Source
This commit is contained in:
Leonid Pershin
2025-10-21 05:08:40 +03:00
parent bc1b3c4015
commit e5e69470f8
12 changed files with 3550 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
README.md
View File

@@ -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 # Database Configuration
DB_HOST=localhost DB_HOST=localhost
DB_PORT=5432 DB_PORT=5432
@@ -16,5 +52,244 @@ DB_PASSWORD=your_secure_password
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
# Ollama Configuration # Ollama Configuration
OLLAMA_URL=https://sample.api.home/ OLLAMA_URL=http://localhost:11434
OLLAMA_DEFAULT_MODEL=gemma3:4b 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<ReplyInfo> ExecuteAsync(TelegramCommandContext context)
{
return new ReplyInfo { Text = "Ответ" };
}
}
```
Зарегистрируйте в `Program.cs`:
```csharp
builder.Services.AddScoped<ITelegramCommand, MyCommand>();
```
## 🤝 Вклад в проект
Мы приветствуем вклад в развитие проекта!
### Как внести изменения
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**

63
docs/README.md Normal file
View File

@@ -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) для подробностей.

357
docs/api/bot-commands.md Normal file
View File

@@ -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<ReplyInfo> 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<ReplyInfo> 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<HealthCheckService>();
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<ReplyInfo> ExecuteAsync(TelegramCommandContext context)
{
// Ваша логика
return new ReplyInfo
{
Text = "Ответ команды"
};
}
}
```
### 2. Зарегистрировать в DI
В `Program.cs`:
```csharp
builder.Services.AddScoped<ITelegramCommand, MyCommand>();
```
### 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)

369
docs/architecture/data-models.md Normal file
View File

@@ -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<ChatMessage> 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<ChatMessageEntity> 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)

351
docs/architecture/database.md Normal file
View File

@@ -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<ChatSessionEntity> ChatSessions { get; set; }
public DbSet<ChatMessageEntity> ChatMessages { get; set; }
}
```
### Конфигурация моделей
```csharp
protected override void OnModelCreating(ModelBuilder modelBuilder)
{
// ChatSessionEntity
modelBuilder.Entity<ChatSessionEntity>(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<ChatMessageEntity>(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<ChatBotDbContext>(
(serviceProvider, options) =>
{
var dbSettings = serviceProvider
.GetRequiredService<IOptions<DatabaseSettings>>()
.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<ChatSessionEntity?> GetByChatIdAsync(long chatId);
Task<ChatSessionEntity> CreateAsync(ChatSessionEntity session);
Task UpdateAsync(ChatSessionEntity session);
Task DeleteAsync(int id);
Task<List<ChatSessionEntity>> GetAllAsync();
}
```
### Implementation
```csharp
public class ChatSessionRepository : IChatSessionRepository
{
private readonly ChatBotDbContext _context;
public async Task<ChatSessionEntity?> GetByChatIdAsync(long chatId)
{
return await _context.ChatSessions
.Include(s => s.Messages)
.FirstOrDefaultAsync(s => s.ChatId == chatId);
}
public async Task<ChatSessionEntity> 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)

349
docs/architecture/layers.md Normal file
View File

@@ -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<ReplyInfo> 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<ChatSessionEntity> ChatSessions
DbSet<ChatMessageEntity> 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)

210
docs/architecture/overview.md Normal file
View File

@@ -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<ITelegramBotClient>
services.AddSingleton<ITelegramBotService>
services.AddSingleton<ITelegramMessageHandler>
// Core Services
services.AddSingleton<IAIService, AIService>
services.AddScoped<ChatService>
services.AddScoped<ISessionStorage, DatabaseSessionStorage>
// Data Access
services.AddDbContext<ChatBotDbContext>
services.AddScoped<IChatSessionRepository, ChatSessionRepository>
```
## 🔄 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<T>
↓
Validation (FluentValidation)
↓
Services
```

449
docs/configuration.md Normal file
View File

@@ -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<ISessionStorage, DatabaseSessionStorage>();
// На
builder.Services.AddScoped<ISessionStorage, InMemorySessionStorage>();
```
### Отключение сжатия истории
В `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)

344
docs/development/project-structure.md Normal file
View File

@@ -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
<PackageReference Include="Telegram.Bot" Version="22.7.2" />
<PackageReference Include="OllamaSharp" Version="5.4.7" />
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.10" />
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.4" />
```
### Логирование
```xml
<PackageReference Include="Serilog" Version="4.3.0" />
<PackageReference Include="Serilog.Extensions.Hosting" Version="9.0.0" />
<PackageReference Include="Serilog.Sinks.Console" Version="6.0.0" />
<PackageReference Include="Serilog.Sinks.File" Version="7.0.0" />
```
### Validation
```xml
<PackageReference Include="FluentValidation" Version="12.0.0" />
<PackageReference Include="FluentValidation.DependencyInjectionExtensions" Version="12.0.0" />
```
## 🧪 Тестовый проект
### Структура
```
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)

485
docs/installation.md Normal file
View File

@@ -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 развертывание

144
docs/overview.md Normal file
View File

@@ -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) для деталей.

148
docs/quickstart.md Normal file
View File

@@ -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/)