ChatBot/docs/api/bot-commands.md

# 🤖 Команды бота

Полное описание всех команд 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)