Stage 07.4.3.10 — Risk and position control

docs/stages/stage-07_4_3_10-risk_position_control.md

@@ -0,0 +1,300 @@
+# Stage 07.4.3.10 — Risk & Position Control
+
+## 📌 Обзор
+
+На данном этапе реализована система контроля риска для paper-trading:
+
+- Stop Loss (по движению цены)
+- Take Profit (по движению цены)
+- Max Loss (по абсолютному убытку)
+- Принудительное закрытие позиции (forced execution)
+- Интеграция с EventBus, Journal и Telegram alerts
+
+---
+
+## ⚙️ Поддерживаемые risk-механики
+
+### 1. Stop Loss (%)
+
+Процентное ограничение убытка относительно цены входа.
+Закрывает позицию при неблагоприятном движении цены:
+LONG: цена ↓
+SHORT: цена ↑
+
+### 2. Take Profit (%)
+Процентное ограничение прибыли.
+Фиксирует прибыль при благоприятном движении:
+LONG: цена ↑
+SHORT: цена ↓
+
+### 3. Max Loss (USD)
+Абсолютное ограничение убытка в USD.
+
+---
+
+## 🧠 Логика работы
+
+Risk-контроль выполняется до execution сигнала:
+1. Обновление PnL
+2. Проверка risk-условий
+3. При необходимости → forced CLOSE
+4. Только потом → обычный execution
+
+### 🔁 Типы execution событий
+
+ENTRY
+paper_position_opened
+
+EXIT (обычный)
+paper_position_closed
+
+EXIT (forced)
+```
+{
+  "execution_type": "EXIT",
+  "risk_reason": "STOP_LOSS | TAKE_PROFIT | MAX_LOSS",
+  "is_forced": true
+}
+```
+
+FLIP
+paper_position_flipped
+
+### 📡 EventBus события
+
+* paper_position_opened
+* paper_position_closed
+* paper_position_flipped
+
+## 🧾 Journal
+
+Пример записи:
+[DEMO] Paper EXIT закрыта по риску TAKE_PROFIT: LONG BTC/USD
+
+Payload:
+```
+{
+  "risk_reason": "TAKE_PROFIT",
+  "is_forced": true,
+  "pnl": 0.75
+}
+```
+
+## 📲 Telegram Alerts
+
+Пример:
+```
+✅ Paper position closed
+
+LONG · BTC / USD · x2
+Entry: $ 81 022.85
+Exit: $ 81 041.70
+Size: 0.04
+
+PnL: 🟢 +0.75 USD
+Risk: TAKE_PROFIT
+```
+
+## 📊 Расчёты
+
+PnL:
+LONG:  (current - entry) * size
+SHORT: (entry - current) * size
+
+Price Move %:
+LONG:  (current - entry) / entry * 100
+SHORT: (entry - current) / entry * 100
+
+---
+
+## 🧪 Тестирование
+
+### STOP LOSS
+stop_loss_percent = 0.01
+
+Ожидаемо:
+Risk: STOP_LOSS
+PnL: 🔴 отрицательный
+
+### TAKE PROFIT
+take_profit_percent = 0.01
+
+Ожидаемо:
+Risk: TAKE_PROFIT
+PnL: 🟢 положительный
+
+### MAX LOSS
+max_loss_usd = 0.01
+
+Ожидаемо:
+Risk: MAX_LOSS
+
+### SHORT сценарий
+/debug_signal SELL 0.95 3
+
+Проверяется обратная логика TP/SL.
+
+---
+
+## ⚠️ Важно
+
+* Risk работает только в RUNNING
+* Работает независимо от новых сигналов
+* Может закрыть позицию без нового READY
+* Не конфликтует с flip logic
+
+---
+
+## 🧩 Архитектура
+
+AutoTradeService
+        ↓
+ExecutionEngine.process()
+        ↓
+Risk Control (NEW)
+        ↓
+Execution (ENTRY / EXIT / FLIP)
+        ↓
+EventBus
+        ↓
+AutoTradeRunner
+        ↓
+Telegram + Journal
+
+---
+
+## 🚀 Результат этапа
+
+* Добавлен полноценный риск-контроль
+* Реализованы forced exits
+* Интеграция с UI, Journal и Telegram
+* Подготовка к real trading
+
+---
+
+## Математика расчётов
+
+Обозначения:
+
+- P_entry — цена входа
+- P_current — текущая цена
+- size — размер позиции
+- side — направление (LONG / SHORT)
+
+---
+
+### 1. PnL
+
+#### LONG:
+PnL = (P_current - P_entry) * size
+
+#### SHORT:
+PnL = (P_entry - P_current) * size
+
+---
+
+### 2. Stop Loss
+
+#### LONG:
+если P_current <= P_entry * (1 - SL%)
+
+#### SHORT:
+если P_current >= P_entry * (1 + SL%)
+
+---
+
+### 3. Take Profit
+
+#### LONG:
+если P_current >= P_entry * (1 + TP%)
+
+#### SHORT:
+если P_current <= P_entry * (1 - TP%)
+
+---
+
+### 4. Max Loss
+
+условие:
+PnL <= -max_loss_usd
+
+---
+
+## Приоритет проверок
+
+1. Max Loss (самый жёсткий)
+2. Stop Loss
+3. Take Profit
+
+Первое выполненное условие закрывает позицию.
+
+---
+
+## Execution Flow
+
+ExecutionEngine.process():
+
+1. update_unrealized_pnl()
+2. check_risk_conditions()
+3. если риск сработал → close_position(risk_reason)
+4. иначе:
+   - flip
+   - open
+
+---
+
+## Payload событий
+
+### paper_position_closed
+
+Добавлено:
+
+- risk_reason: STOP_LOSS | TAKE_PROFIT | MAX_LOSS
+- is_forced: true
+
+---
+
+## Telegram отображение
+
+Пример:
+
+PnL: 🟢 +0.75 USD  
+Risk: TAKE_PROFIT
+
+---
+
+## Journal
+
+Message:
+Paper EXIT закрыта по риску TAKE_PROFIT
+
+Payload:
+{
+  "pnl": ...,
+  "risk_reason": "TAKE_PROFIT",
+  "is_forced": true
+}
+
+---
+
+## Важные нюансы
+
+- Risk работает ТОЛЬКО в RUNNING
+- Работает независимо от сигналов
+- Срабатывает раньше flip
+- Не зависит от decision_status
+
+---
+
+## Результат
+
+Добавлен критический слой защиты:
+
+- ограничение убытков
+- фиксация прибыли
+- автономное поведение системы
+
+Это база для:
+- real trading
+- advanced risk management
+- portfolio-level контроля