This commit is contained in:
Leonid Pershin
349
docs/architecture/layers.md
Normal file
349
docs/architecture/layers.md
Normal 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)
|
||||
Reference in New Issue
Block a user