ChatBot/docs/architecture/layers.md

# 🏛️ Слои приложения

Детальное описание каждого слоя архитектуры 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)