# 07.4.4.1.10.2 — Human-readable formatter

## Статус

✅ Этап реализован.

## Назначение этапа

Этап **07.4.4.1.10.2 Human-readable formatter** добавляет человекочитаемый слой поверх диагностического snapshot builder из этапа **07.4.4.1.10.1**.

Если предыдущий этап собирал структурированный diagnostic snapshot в виде технического словаря, то текущий этап превращает этот snapshot в понятный текстовый отчёт, который можно напрямую показывать пользователю в Telegram, писать в журнал или использовать как основу для отдельного diagnostic screen.

Главная цель этапа — сделать runtime-состояние автоторговли объяснимым: не только хранить значения `market_state`, `momentum_state`, `execution_quality`, `execution_confidence_score`, `adaptive_size_multiplier`, но и отображать их в единой логичной структуре.

## Что было реализовано

Создан отдельный formatter-слой:

```text
app/src/trading/diagnostics/formatter.py
```

В файл добавлен класс:

```python
SemanticDiagnosticFormatter
```

Класс получает на вход диагностический snapshot и формирует человекочитаемый отчёт по ключевым runtime-блокам автоторговли.

Formatter не меняет торговую логику, не влияет на сигналы, не открывает и не закрывает позиции, не пересчитывает market analysis и не изменяет состояние `AutoTradeState`. Это read-only presentation layer.

## Архитектурная роль

До этого этапа диагностическая информация существовала в виде набора технических полей:

- `last_signal`
- `decision_status`
- `market_state`
- `market_trend`
- `market_phase`
- `momentum_state`
- `breakout_reason`
- `execution_quality`
- `execution_confidence_score`
- `adaptive_size_multiplier`
- `runtime_expired_reason`
- `position_side`

Такая структура удобна для кода, но неудобна для ручной проверки в Telegram.

Этап **07.4.4.1.10.2** добавил промежуточный уровень:

```text
AutoTradeState
        ↓
SemanticDiagnosticSnapshotBuilder
        ↓
SemanticDiagnosticFormatter
        ↓
Telegram screen / journal / debug output
```

Теперь диагностический snapshot можно не только собрать, но и вывести в читаемом виде.

## Реализованные диагностические блоки

Formatter формирует отчёт из отдельных смысловых секций.

### 1. Runtime

Блок показывает базовый runtime-контекст автоторговли:

- статус автоторговли
- торговый инструмент
- стратегия
- признак корректной настройки

Этот блок нужен, чтобы сразу видеть, в каком режиме находится система: `OFF`, `OBSERVING` или `RUNNING`.

### 2. Signal

Блок отображает состояние сигнального слоя:

- текущий сигнал
- confidence стратегии
- decision status
- подтверждён ли сигнал
- готов ли сигнал к execution
- количество повторов
- прогресс подтверждения
- возраст сигнала
- причина сигнала

Этот блок помогает понять, почему бот держит `HOLD`, почему BUY / SELL ещё подтверждается, или почему сигнал уже готов к исполнению.

### 3. Market

Блок отображает semantic market diagnostics:

- состояние рынка
- направление тренда
- волатильность
- силу тренда
- качество тренда
- фазу рынка
- направление фазы
- причину блокировки входа
- возраст market analysis

Именно этот блок делает видимой работу market semantic layer, добавленного на предыдущих этапах.

Теперь можно увидеть не только короткую UI-строку вроде `📉 Рынок · снижение`, но и полный набор факторов, из которых это состояние собрано.

### 4. Momentum / Breakout

Блок отображает momentum и breakout diagnostics:

- momentum state
- momentum direction
- momentum strength
- процент изменения цены в momentum window
- breakout level
- breakout distance percent
- является ли состояние breakout
- причина классификации

Этот блок особенно важен после этапа **07.4.4.1.9.6.2 Momentum & Breakout Semantic Engine**, потому что позволяет проверить, видит ли бот импульс, пробой, направление ускорения и силу движения.

### 5. Execution

Блок отображает execution diagnostics:

- execution quality
- semantic execution status
- execution confidence score
- execution confidence level
- spread percent
- snapshot age
- признак runtime degradation
- semantic reason

Этот блок объясняет, почему execution разрешён, ограничен или заблокирован.

Он объединяет данные execution quality layer, execution confidence engine и semantic execution state.

### 6. Adaptive Sizing

Блок отображает adaptive sizing diagnostics:

- итоговый multiplier
- effective risk percent
- effective target risk USD
- причина изменения размера

Этот блок показывает, как execution context влияет на размер будущей позиции.

Если размер уменьшен, увеличен или заблокирован, formatter делает это видимым.

### 7. Position

Блок отображает состояние позиции:

- сторона позиции
- цена входа
- размер
- unrealized PnL
- realized PnL
- последнее execution-действие

Этот блок нужен для связи диагностики сигнала с фактической позицией.

### 8. Runtime Health

Блок отображает техническое здоровье runtime:

- есть ли degraded state
- возраст сигнала
- возраст market analysis
- причина runtime expiration
- наличие market data
- наличие momentum data

Этот блок помогает понять, устарели ли данные, сброшен ли сигнал, доступна ли рыночная аналитика и не работает ли бот на деградированном контексте.

### 9. Summary

Финальный блок собирает короткое резюме:

- market summary
- phase summary
- momentum summary
- execution summary
- position summary
- готовность к execution
- блокировка
- список blockers

Это верхнеуровневое объяснение текущего состояния автоторговли.

## Что сделано в части аналитики

На этом этапе аналитика была не пересчитана, а структурирована для человека.

Это важное отличие: formatter не добавляет новые торговые правила, но делает уже существующую аналитику наблюдаемой.

В человекочитаемый отчёт теперь выводятся ключевые аналитические слои:

- signal layer
- decision layer
- market semantic layer
- market phase layer
- trend strength layer
- trend quality layer
- momentum semantic layer
- breakout semantic layer
- execution quality layer
- execution confidence layer
- adaptive sizing layer
- runtime health layer
- position state layer

Таким образом, аналитика перестала быть скрытой внутри payload и runtime state.

Теперь можно вручную проверить:

- почему бот видит рынок как trend / range / squeeze / high volatility
- почему фаза определена как impulse / pullback / range / squeeze
- есть ли momentum или breakout
- насколько сильный импульс
- где находится breakout level
- почему вход заблокирован
- почему execution confidence низкий или нормальный
- почему adaptive sizing уменьшил или увеличил размер
- есть ли stale snapshot или широкий spread
- почему позиция открыта, не открыта или не переворачивается

## Почему это важно

До появления formatter диагностика была доступна только через внутренние поля и payload.

Это создавало несколько проблем:

1. В UI Telegram отображалось только несколько коротких строк.
2. Нельзя было быстро понять, какой именно слой заблокировал вход.
3. Momentum и breakout были рассчитаны, но не имели полноценного human-readable вывода.
4. Execution confidence был числом, но без нормальной расшифровки в общем контексте.
5. Adaptive sizing работал, но его причина не была частью единого diagnostic report.
6. Для проверки приходилось смотреть код, payload или журнал.

Новый formatter решает эти проблемы и готовит систему к отдельному diagnostic screen.

## Пример будущего использования

Formatter рассчитан на дальнейшее использование в Telegram Diagnostic Screen:

```python
snapshot = SemanticDiagnosticSnapshotBuilder().build()
text = SemanticDiagnosticFormatter().format(snapshot)
```

После этого `text` можно отправить в Telegram как отдельный экран диагностики.

## Что этап НЕ делает

Этап не добавляет новую торговую стратегию.

Этап не меняет расчёт сигналов.

Этап не меняет thresholds.

Этап не меняет execution engine.

Этап не меняет adaptive sizing.

Этап не пишет автоматически диагностику в журнал.

Этап не добавляет Telegram handler.

Этап только создаёт human-readable presentation layer для уже существующего diagnostic snapshot.

## Подготовка к следующим этапам

Этап подготавливает базу для:

- **07.4.4.1.10.3 Telegram Diagnostic Screen**
- **07.4.4.1.10.4 Diagnostic Journal Layer**
- **07.4.4.1.10.5 Auto-refresh Diagnostic UI**

После этого этапа можно безопасно строить отдельный экран диагностики, потому что форматтер уже умеет превращать технический snapshot в готовый текст для пользователя.

## Проверка

Минимальная проверка:

```bash
python3 -m compileall app/src/trading/diagnostics
```

Ожидаемый результат:

```text
Listing 'app/src/trading/diagnostics'...
Compiling 'app/src/trading/diagnostics/formatter.py'...
```

Если ошибок нет, formatter синтаксически корректен.

## Итог

Этап **07.4.4.1.10.2 Human-readable formatter** завершает второй слой диагностической инфраструктуры.

Теперь система умеет не только собирать semantic diagnostic snapshot, но и превращать его в понятный отчёт.

Это переводит диагностику автоторговли из raw technical state в explainable runtime representation и подготавливает основу для полноценного Telegram diagnostic screen.
