07.4.3.13 - Risk-based Sizing and Margin Protection

docs/stages/stage-07_4_3_13-risk-based_sizing_and_margin_protection.md

@@ -0,0 +1,242 @@
+# 07.4.3.13 — Risk-Based Position Sizing & Margin Protection
+
+## Цель
+
+Перевести paper execution с “фиксированного размера позиции” на полноценную risk-based модель, где:
+
+- размер позиции рассчитывается через Risk %
+- Stop Loss участвует в sizing
+- execution защищён от oversized positions
+- margin usage контролируется до открытия сделки
+- UI показывает реальную нагрузку на баланс
+
+---
+
+# Что было раньше
+
+Ранее:
+
+- risk_percent существовал только как UI-параметр
+- размер позиции не ограничивался margin usage
+- leverage мог создавать oversized exposure
+- позиция могла резервировать 100%+ баланса
+- SL / TP использовались только для close logic
+
+Пример проблемы:
+
+- balance = 1000 USD
+- leverage = x5
+- BTC = 80 000
+- risk = 2%
+- SL = 1%
+
+execution открывал позицию:
+
+- notional ≈ 10 000 USD
+- reserved ≈ 2 000 USD
+
+что превышало весь paper balance.
+
+---
+
+# Что реализовано
+
+## 1. Risk-Based Position Sizing
+
+ExecutionEngine теперь рассчитывает size через риск.
+
+Добавлена формула:
+
+```
+target_risk_usd = balance * (risk_percent / 100)
+stop_loss_distance_usd = price * (stop_loss_percent / 100)
+size = target_risk_usd / stop_loss_distance_usd
+```
+
+---
+
+## 2. SL стал обязательным для execution
+
+Теперь позиция не открывается без:
+
+* risk_percent
+* stop_loss_percent
+
+Причина:
+
+без SL невозможно определить:
+
+* допустимый убыток
+* размер позиции
+* риск сделки
+
+---
+
+## 3. Margin Protection
+
+Добавлено новое поле state:
+
+`max_reserved_balance_percent`
+
+По умолчанию: 50.0
+
+---
+
+## 4. Margin Validation
+
+Перед:
+
+* ENTRY
+* FLIP
+
+выполняется:
+`_validate_margin_usage()`
+
+---
+
+## 5. Проверка reserved margin
+
+Execution рассчитывает:
+```
+notional_usd = entry_price * size
+reserved_usd = notional_usd / leverage
+```
+
+и сравнивает с лимитом:
+```
+max_reserved_usd =
+balance * (max_reserved_balance_percent / 100)
+```
+
+---
+
+## 6. Execution Blocking
+
+Если margin превышает лимит:
+
+* позиция НЕ открывается
+* flip НЕ выполняется
+* execution возвращает BLOCK reason
+
+---
+
+## 7. Execution Block State
+
+Добавлено новое поле:
+`execution_block_reason`
+
+Используется для UI и debugging.
+
+---
+
+## UI Improvements
+
+Compact Mobile Layout
+
+Полностью переработан mobile rendering.
+
+### Новый формат позиции
+
+Было:
+`📦 Size: 0.02447179 · $ 2 000.41`
+
+Стало:
+`📦 Size: 0.0245 ($ 2 000)`
+
+### Новый формат SL / TP / ML
+
+Было:
+`🛑 SL: −$ 20.00 · $ 82 544.02`
+
+Стало:
+```
+🛑 SL: 1.00% · -$ 20 ⇢ $ 82 544
+🎯 TP: 2.00% · +$ 40 ⇢ $ 80 092
+💣 ML: -$ 100 ⇢ $ 85 813
+```
+
+### Добавлено отображение:
+
+* Est. Margin
+* Max Reserved
+* Blocked reason
+
+### Новые UI элементы
+
+Estimated Margin
+`Est. Margin: $ 400`
+
+Max Reserved
+`Max Reserved: 50% · $ 500`
+
+Execution Blocked
+`🔴 Blocked: Margin $ 1000 > limit $ 500`
+
+---
+
+## Изменения Execution Flow
+
+### ENTRY
+
+Теперь flow:
+signal
+→ size calculation
+→ margin validation
+→ open position
+
+### FLIP
+
+Теперь flip:
+
+* закрывает текущую позицию
+* рассчитывает новый size
+* валидирует margin
+* только потом открывает reverse position
+
+---
+
+## Архитектурный результат
+
+Теперь:
+
+* risk_percent реально влияет на trade size
+* leverage влияет на reserved balance
+* SL участвует в sizing engine
+* execution защищён от oversized exposure
+* UI показывает реальную margin load
+
+---
+
+## Ограничения текущей реализации
+
+Пока ещё нет:
+
+* dynamic balance updates
+* equity tracking
+* realized pnl balance updates
+* liquidation simulation
+* fees engine
+* funding
+* tiered leverage
+* maintenance margin
+* partial close
+
+---
+
+## Следующий этап
+
+07.4.3.14 — Strategy Engine Upgrade
+
+Планируется:
+
+* улучшение TREND strategy
+* rolling candles / history window
+* EMA-based trend detection
+* ATR volatility filter
+* noise reduction
+* smarter confidence model
+* configurable thresholds
+* полноценная SCALP strategy
+* anti-whipsaw protection
+* multi-confirmation signals
+