vvlad1973-telegram-framework/patches/README.md

Current version: *7.9.5*

# Patches

Патчи для внешних зависимостей с добавленной функциональностью.

## scenario.js

Патч для `vvlad1973-telegram-framework/src/classes/scenario.js` с поддержкой user tracing.

### Что добавляет

* Детальное логирование выполнения запросов для конкретных пользователей
* Трассировка всех этапов обработки: диалоги, actions, ветвления
* Форматирование больших объектов для читаемости логов

### Трассируемые события

| Событие | Описание |
|---------|----------|
| request_received | Получен запрос от пользователя |
| dialog_matched | Найден подходящий диалог |
| dialog_not_found | Диалог не найден |
| dialog_complete | Диалог завершён |
| dialog_error | Ошибка в диалоге |
| action_start | Начало выполнения action |
| action_result | Результат action |
| action_branch | Переход в ветку true/false |
| action_error | Ошибка в action |
| action_error_caught | Ошибка перехвачена, переход в false |
| action_not_defined | Action не найден |
| switch_start | Начало doSwitch |
| switch_case_matched | Найден case |
| switch_default | Переход в default |
| switch_no_match | Ни один case не подошёл |
| do_dialog | Переход в другой диалог |
| do_dialog_return | Возврат из диалога |
| request_complete | Запрос обработан |

### Применение

#### 1. Импорт патча вместо оригинала

В `init.js` замените импорт Scenario:

```javascript
// Было:
// import { Scenario } from 'vvlad1973-telegram-framework';

// Стало:
import { Scenario } from './patches/scenario.js';
```

#### 2. Инъекция userTracing

После создания scenario и инициализации userTracing:

```javascript
import { userTracing } from './src/user_tracing.js';

// ... создание scenario ...

// Инъекция userTracing в scenario
scenario.userTracing = userTracing;
```

### Пример интеграции в init.js

```javascript
import { Scenario } from './patches/scenario.js';
import { userTracing } from './src/user_tracing.js';

// Создание scenario
const scenario = new Scenario(logger);

// Инициализация userTracing
await userTracing.initialize({
  config,
  logger: logger.child({ name: 'UserTracing' }),
  storage: db.collection(config.tracing?.collection || 'user_traces'),
});

// Инъекция в scenario
scenario.userTracing = userTracing;

// Добавление в context
context.userTracing = userTracing;
context.scenario = scenario;
```

### Использование

После применения патча трассировка работает автоматически:

1. Включите трассировку для пользователя:

   ```text
   /admin trace on @username 30
   ```

2. Пользователь выполняет действия в боте

3. Все события записываются в файл трейса с детальной информацией

4. Получите лог:

   ```text
   /admin trace get @username
   ```

### Пример вывода

```text
[10:30:00.001] INFO: event=request_received
    request: { type: "command", contents: "/start", chat_type: "private" }
    user: { id: "123456", state: "ACTIVE", role: "user" }

[10:30:00.002] INFO: event=dialog_matched
    dialogId: "START_COMMAND"
    matchCriteria: { state: "ACTIVE", received: { type: "command", text: "start" } }
    actionsCount: 3

[10:30:00.003] INFO: event=action_start
    action: "sendMessage"
    options: { text: "Welcome!" }
    stack: 1

[10:30:00.050] INFO: event=action_result
    action: "sendMessage"
    result: { ok: true, message_id: 123 }
    duration: 47

[10:30:00.051] INFO: event=request_complete
    duration: 50
    dialogsProcessed: 1
    actionsExecuted: 3
```

### Совместимость

Патч полностью совместим с оригинальным Scenario:

* Все существующие диалоги работают без изменений
* Если `userTracing` не инъецирован, трассировка просто не выполняется
* Производительность не затрагивается для не-трассируемых пользователей