Stage 07.4.3.8 — Telegram execution alerts

docs/stages/stage-07_4_3_8-telegram-execution-alerts.md

@@ -0,0 +1,258 @@
+# Stage 07.4.3.8 — Telegram Execution Alerts
+
+## Цель этапа
+
+Добавить отдельные Telegram-уведомления для paper execution событий:
+
+- открытие LONG / SHORT позиции;
+- закрытие позиции;
+- отображение Entry / Exit;
+- отображение Size;
+- отображение PnL;
+- отделить signal alerts от execution alerts.
+
+---
+
+## Что изменено
+
+### 1. Отдельный alert-слой для execution
+
+Теперь Telegram-уведомления разделены по смыслу:
+
+```text
+Strong signal alert  → рынок дал BUY / SELL
+Execution alert      → система открыла / закрыла paper-позицию
+```
+
+Это устраняет конфликт между:
+
+```text
+SELL для закрытия LONG
+SELL для открытия SHORT
+```
+
+---
+
+## 2. Обработка EventBus событий execution
+
+В `AutoTradeRunner` добавлена обработка событий:
+
+```text
+paper_position_opened
+paper_position_closed
+```
+
+Теперь runner реагирует не только на:
+
+```text
+auto_decision_changed
+```
+
+но и на paper execution события.
+
+---
+
+## 3. Telegram alert при открытии позиции
+
+Пример сообщения:
+
+```text
+📄 Paper position opened 🟢 LONG
+
+BTC / USD · x2
+Entry: $ 79 710.10
+Size: 0.01
+```
+
+Для SHORT:
+
+```text
+📄 Paper position opened 🔴 SHORT
+
+BTC / USD · x2
+Entry: $ 79 710.10
+Size: 0.01
+```
+
+---
+
+## 4. Telegram alert при закрытии позиции
+
+Пример сообщения:
+
+```text
+✅ Paper position closed
+
+LONG · BTC / USD · x2
+Entry: $ 79 710.10
+Exit: $ 79 720.15
+Size: 0.01
+
+PnL: 🟢 +0.10 USD
+```
+
+Для отрицательного PnL:
+
+```text
+PnL: 🔴 -0.02 USD
+```
+
+---
+
+## 5. Улучшено форматирование валют
+
+Добавлены UI helper-функции:
+
+```python
+format_usd_price(...)
+format_usd_pnl(...)
+```
+
+Теперь цены выводятся в читаемом формате:
+
+```text
+$ 79 710.10
+```
+
+а не:
+
+```text
+$ 79710.10
+```
+
+PnL отображается с направлением:
+
+```text
+🟢 +1.25 USD
+🔴 -0.02 USD
+⚪ 0.00 USD
+```
+
+---
+
+## 6. Dedup для execution alerts
+
+Добавлен отдельный ключ для execution alert:
+
+```text
+event_type + symbol + side + entry_price + exit_price + size + pnl
+```
+
+Это защищает от повторной отправки одного и того же execution-события, но не блокирует новые реальные события.
+
+---
+
+## Изменённые файлы
+
+```text
+app/src/trading/auto/runner.py
+app/src/trading/execution/engine.py
+app/src/telegram/ui/currency_ui.py
+```
+
+---
+
+## Проверка
+
+### 1. Открытие LONG
+
+```text
+/debug_signal BUY 0.95 3
+```
+
+Ожидаемо:
+
+```text
+🚨 HIGH · 🟢 BUY
+📄 Paper position opened 🟢 LONG
+```
+
+---
+
+### 2. Закрытие LONG
+
+```text
+/debug_signal SELL 0.95 3
+```
+
+Ожидаемо:
+
+```text
+🚨 HIGH · 🔴 SELL
+✅ Paper position closed
+```
+
+---
+
+### 3. Открытие SHORT
+
+После закрытия LONG:
+
+```text
+/debug_signal SELL 0.96 3
+```
+
+Ожидаемо:
+
+```text
+🚨 HIGH · 🔴 SELL
+📄 Paper position opened 🔴 SHORT
+```
+
+---
+
+### 4. Закрытие SHORT
+
+```text
+/debug_signal BUY 0.96 3
+```
+
+Ожидаемо:
+
+```text
+🚨 HIGH · 🟢 BUY
+✅ Paper position closed
+```
+
+---
+
+## Архитектурный результат
+
+Теперь система имеет отдельные слои:
+
+```text
+Strategy
+  ↓
+AutoTradeService
+  ↓
+EventBus
+  ↓
+Signal Alert Layer
+  ↓
+ExecutionEngine
+  ↓
+Execution Alert Layer
+```
+
+Главное разделение:
+
+```text
+Signal alert ≠ Execution alert
+```
+
+Это делает поведение более предсказуемым и готовит систему к следующему этапу — position flip flow.
+
+---
+
+## Следующий этап
+
+```text
+07.4.3.9 — Position flip flow
+```
+
+План:
+
+- SELL при LONG → закрыть LONG и открыть SHORT в одном цикле;
+- BUY при SHORT → закрыть SHORT и открыть LONG в одном цикле;
+- отдельные alerts для flip-сценариев;
+- подготовка к реальному execution.