Stage 07.4.3.7 — Alert Priority & UX Improvements

docs/stages/stage-07_4_3_7-alert-priority-ux.md

@@ -0,0 +1,265 @@
+# Stage 07.4.3.7 — Alert Priority & UX Improvements
+
+## Цель этапа
+
+Улучшить Telegram-уведомления о сильных сигналах BUY / SELL:
+
+- сделать alert более читаемым;
+- добавить визуальный приоритет сигнала;
+- унифицировать формат symbol / leverage;
+- сохранить совместимость с cooldown / suppression;
+- не влиять на ExecutionEngine.
+
+---
+
+## Что изменено
+
+### 1. Новый формат Telegram alert
+
+Было:
+
+```text
+🚨 Сильный сигнал 🟢 BUY
+
+BTC/USD_LEVERAGE · TREND · x2
+Confidence: 0.90
+Repeats: 2
+
+Причина: DEBUG FORCE BUY
+```
+
+Стало:
+
+```text
+⚡ MEDIUM · 🟢 BUY
+
+BTC / USD · TREND · x2
+
+🧠 Confidence: 0.90
+🔁 Repeats: 2
+
+💡 Причина:
+DEBUG FORCE BUY
+```
+
+---
+
+## 2. Priority layer
+
+Добавлена логика определения приоритета:
+
+```python
+HIGH   = confidence >= 0.80 and repeat_count >= 3
+MEDIUM = confidence >= 0.60 or repeat_count >= 2
+LOW    = everything else
+```
+
+### Priority labels
+
+```text
+HIGH   → 🚨 HIGH
+MEDIUM → ⚡ MEDIUM
+LOW    → ℹ️ LOW
+```
+
+---
+
+## 3. Форматирование symbol
+
+Для UI alert-ов добавлено компактное отображение:
+
+```text
+BTC/USD_LEVERAGE → BTC / USD
+```
+
+Это делает alert визуально единым с экраном автоторговли.
+
+---
+
+## 4. Форматирование leverage
+
+Плечо выводится компактно:
+
+```text
+2.0 → x2
+5.0 → x5
+```
+
+---
+
+## 5. Совместимость с throttling
+
+Существующая логика cooldown / suppression сохранена:
+
+- одинаковый alert не отправляется чаще заданного cooldown;
+- suppressed alert логируется в Journal;
+- priority не ломает alert key;
+- debug и normal режимы используют один и тот же alert pipeline.
+
+---
+
+## Изменённые файлы
+
+```text
+app/src/trading/auto/runner.py
+app/src/telegram/handlers/debug.py
+```
+
+---
+
+## Проверка
+
+### 1. MEDIUM alert
+
+```text
+/debug_signal BUY 0.90 2
+```
+
+Ожидаемо:
+
+```text
+⚡ MEDIUM · 🟢 BUY
+```
+
+---
+
+### 2. HIGH alert
+
+```text
+/debug_signal BUY 0.95 3
+```
+
+Ожидаемо:
+
+```text
+🚨 HIGH · 🟢 BUY
+```
+
+---
+
+### 3. SELL alert
+
+```text
+/debug_signal SELL 0.70 2
+```
+
+Ожидаемо:
+
+```text
+⚡ MEDIUM · 🔴 SELL
+```
+
+---
+
+### 4. LOW alert
+
+```text
+/debug_signal BUY 0.40 1
+```
+
+Ожидаемо:
+
+```text
+ℹ️ LOW · 🟢 BUY
+```
+
+---
+
+### 5. HOLD
+
+```text
+/debug_signal HOLD 0.00 1
+```
+
+Ожидаемо:
+
+- decision = WAITING;
+- alert не отправляется;
+- execution не выполняется.
+
+---
+
+### 6. Cooldown
+
+```text
+/debug_signal BUY 0.95 3
+/debug_signal BUY 0.95 3
+```
+
+Ожидаемо:
+
+- первый alert отправляется;
+- второй alert подавляется;
+- в Journal появляется `auto_strong_signal_alert_suppressed`.
+
+---
+
+## Архитектурный результат
+
+Alert layer стал отдельным читаемым UX-слоем:
+
+```text
+EventBus
+  ↓
+AutoTradeRunner
+  ↓
+Priority / Formatting / Cooldown
+  ↓
+Telegram alert
+```
+
+Execution layer не изменён:
+
+```text
+Signal alert ≠ Execution alert
+```
+
+Это важно для будущего этапа `07.4.3.8 — Telegram execution alerts`.
+
+---
+
+## Roadmap update
+
+### Stage 07 roadmap
+
+```text
+07.4.3.7 — Alert Priority & UX Improvements ✅
+- priority labels HIGH / MEDIUM / LOW
+- improved alert layout
+- normalized symbol display
+- normalized leverage display
+- compatible with cooldown / suppression
+- parametrized debug signal testing
+```
+
+### Master roadmap
+
+```text
+Stage 07 — Auto Trading
+✔ 07.4.3.7 — Alert Priority & UX Improvements
+```
+
+---
+
+## Commit
+
+```bash
+git add app/src/telegram/handlers/debug.py
+git add app/src/trading/auto/runner.py
+git commit -m "Stage 07.4.3.7 — Alert priority and UX improvements"
+```
+
+---
+
+## Следующий этап
+
+```text
+07.4.3.8 — Telegram execution alerts
+```
+
+План:
+
+- отдельные сообщения OPEN_LONG / OPEN_SHORT;
+- отдельные сообщения CLOSE;
+- отображение Entry / Exit / PnL;
+- journal + Telegram consistency.