mql5/Experts/testRefactor2/docs/ARCHITECTURE.md

# TestRefactor – Dokumentace EA

## Přehled

EA (Expert Advisor) pro MetaTrader 5 postavený v OOP stylu. Používá crossover rychlé a pomalé SMA + RSI pro generování signálů, s podporou režimu jedné pozice (Single) nebo Grid strategie. Trend je ověřován na H1 a dvou dodatečných timeframech (TF1, TF2).

---

## Inputy (parametry EA)

Všechny inputy jsou deklarovány v hlavním souboru `testRefactor2.mq5` a předávány do tříd přes `CContext`.

### Indikátory (SMA, RSI)

| Input | Typ | Výchozí | Popis |
|-------|-----|---------|------|
| `InpFastMaPeriod` | int | 5 | Perioda rychlé SMA – kratší MA pro detekci crossoveru |
| `InpSlowMaPeriod` | int | 15 | Perioda pomalé SMA – delší MA pro trend |
| `InpRsiPeriod` | int | 14 | Perioda RSI indikátoru |
| `InpRsiOverbought` | double | 70 | RSI horní hranice – signál BUY jen když RSI < tato hodnota |
| `InpRsiOversold` | double | 30 | RSI dolní hranice – signál SELL jen když RSI > tato hodnota |
| `InpSmaMinDistancePoints` | double | 0 | Min. vzdálenost SMA v bodech – signál jen když Fast-Slow >= tato hodnota (0 = vypnuto) |

### Trend (H1)

| Input | Typ | Výchozí | Popis |
|-------|-----|---------|------|
| `InpH1TrendMaPeriod` | int | 50 | Perioda SMA na H1 – trend: close > MA = uptrend, close < MA = downtrend (0 = vypnuto) |

### Ověření směru (TF1, TF2) – pro Grid

| Input | Typ | Výchozí | Popis |
|-------|-----|---------|------|
| `InpTimeframe1` | ENUM_TIMEFRAMES | PERIOD_H4 | První dodatečný timeframe pro filtrování otevření Grid pozic |
| `InpTimeframe1MaPeriod` | int | 20 | Perioda SMA na TF1 – BUY jen když close > MA, SELL jen když close < MA (0 = vypnuto) |
| `InpTimeframe2` | ENUM_TIMEFRAMES | PERIOD_D1 | Druhý dodatečný timeframe pro filtrování otevření Grid pozic |
| `InpTimeframe2MaPeriod` | int | 50 | Perioda SMA na TF2 – oba TF musí souhlasit se směrem (0 = vypnuto) |

### Obchodování

| Input | Typ | Výchozí | Popis |
|-------|-----|---------|------|
| `InpLotSize` | double | 0.1 | Velikost lotu pro otevření pozic |
| `InpTradeMode` | ENUM_TRADE_MODE | TRADE_SINGLE | Režim: Single (jedna pozice) nebo Grid (více úrovní) |
| `InpTrailingTriggerUSD` | double | 3.0 | Zisk v USD, od kterého se aktivuje trailing stop (Single režim) |
| `InpTrailingDistanceUSD` | double | 1.0 | Vzdálenost trailing stop od aktuálního zisku v USD |

### Grid

| Input | Typ | Výchozí | Popis |
|-------|-----|---------|------|
| `InpGridDistancePoints` | double | 50 | Vzdálenost mezi úrovněmi Gridu v bodech – nová pozice při pohybu ceny o tuto vzdálenost |
| `InpGridTargetProfitUSD` | double | 20.0 | Cílový zisk v USD – při dosažení se uzavře celý Grid |
| `InpGridMaxLevels` | int | 20 | Max. počet úrovní (pozic) v jednom směru |

### Ostatní

| Input | Typ | Výchozí | Popis |
|-------|-----|---------|------|
| `InpMaxEquityDrawdownPct` | double | 10.0 | Max. povolený drawdown equity v % – při překročení se uzavřou všechny pozice (jen Single) |
| `InpExitMode` | ENUM_EXIT_MODE | EXIT_BY_SL_TRAIL | Režim uzavření: Stop Loss & Trailing nebo Opposite Crossover (uzavření při protisměrném signálu) |

---

## Třídy

### CContext

**Účel:** Centrální úložiště konfigurace z inputů. Všechny třídy dostávají parametry přes `SContext` z `CContext.Get()`.

**Metody:**
- `SetFromInputs(...)` – naplní kontext hodnotami z inputů
- `Get()` – vrátí kopii `SContext`
- `SetGridMaxLevels(int)` – nastaví max. počet úrovní Gridu

---

### CLogger

**Účel:** Centralizované logování s úrovněmi Error, Info, Debug.

**Metody:**
- `Error(string)` – chyby
- `Info(string)` – informace
- `Debug(string)` – ladění
- `SetMinLevel(ENUM_LOG_LEVEL)` – minimální úroveň pro výstup
- `SetPrefix(string)` – prefix zpráv

---

### CPosition

**Účel:** Reprezentace jedné otevřené pozice. Čte data z terminálu přes `PositionSelectByTicket()`.

**Metody:**
- `Set(ticket, symbol)` – nastaví ticket a symbol
- `GetTicket()`, `GetSymbol()` – identifikace
- `Select()` – vybere pozici v terminálu
- `GetType()` – BUY/SELL
- `GetOpenPrice()`, `GetVolume()`, `GetProfit()`, `GetSwap()`, `GetSL()`, `GetTP()`
- `IsBuy()`, `IsSell()` – pomocné predikáty

---

### CPositions

**Účel:** Kolekce otevřených pozic daného symbolu. Jediné místo, kde se volá `PositionsTotal()` / `PositionGetTicket()` pro daný symbol.

**Metody:**
- `Refresh()` – znovu načte pozice z terminálu
- `Count()`, `CountBuy()`, `CountSell()` – počty
- `GetMinOpenPriceBuy()`, `GetMaxOpenPriceSell()` – min/max ceny pro Grid
- `GetTotalProfit()` – součet profit + swap všech pozic
- `GetTickets(ulong &[])` – seznam ticketů
- `HasNoPositions()`, `HasBuy()`, `HasSell()` – predikáty

---

### CClosedPosition / CClosedPositions

**Účel:** Snapshot zavřené pozice a kolekce pro historii/statistiky. Připraveno pro budoucí rozšíření (ukládání při uzavření).

**CClosedPosition:** ticket, symbol, type, openPrice, closePrice, volume, profit, swap, openTime, closeTime

**CClosedPositions:** `Add()`, `Count()`, `At(index)`, `GetTotalProfit()`

---

### CSignalEngine

**Účel:** Indikátory (SMA, RSI) a výpočet obchodních signálů. Drží handly, detekuje nový bar, vrací buy/sell signály s filtrem trendu.

**Indikátory:**
- Fast MA, Slow MA (aktuální timeframe)
- RSI (aktuální timeframe)
- H1 trend MA (volitelné)
- TF1 MA, TF2 MA (volitelné)

**Metody:**
- `Init()` / `Deinit()` – vytvoření a uvolnění handleů
- `IsNewBar()` – true při novém baru na aktuálním grafu
- `GetSignals()` – vrací `SSignalResult` (buySignal, sellSignal, volume, trendUp, smaDistancePoints)
- `GetH1Trend()` – trend na H1 (close > MA = uptrend)
- `GetTf1Trend()`, `GetTf2Trend()` – trend na TF1, TF2
- `IsBuyDirectionValid()` – true když TF1 i TF2 ukazují uptrend
- `IsSellDirectionValid()` – true když TF1 i TF2 ukazují downtrend
- `GetLastBarValues()` – hodnoty MA a RSI pro dashboard

**Logika signálů:**
- **BUY:** Fast MA crossover nad Slow MA + RSI < overbought + min. distance + H1 uptrend
- **SELL:** Fast MA crossover pod Slow MA + RSI > oversold + min. distance + H1 downtrend

---

### CEquityDrawdown

**Účel:** Sleduje vrchol equity. Při překročení max. drawdownu (např. 10 %) uzavře všechny pozice symbolu.

**Poznámka:** Aktivní jen v režimu TRADE_SINGLE. V Grid režimu se nepoužívá (Grid má vlastní logiku uzavření).

**Metody:**
- `CheckAndClose()` – voláno každý tick; při překročení limitu uzavře pozice

---

### CTrailingStop

**Účel:** Trailing stop pro režim jedné pozice. Posouvá SL za cenou při dosažení zisku.

**Podmínky:** Aktivní jen při `TRADE_SINGLE` a `EXIT_BY_SL_TRAIL`. V Grid režimu se nepoužívá.

**Logika:** Když profit >= `trailingTriggerUSD`, posune SL tak, aby zajištěný zisk byl `trailingTriggerUSD - trailingDistanceUSD`.

**Metody:**
- `Update()` – voláno každý tick; upraví SL u pozic splňujících podmínky

---

### CGrid

**Účel:** Logika Grid strategie – otevření první úrovně, přidání dalších úrovní podle distance, uzavření při cílovém zisku.

**Metody:**
- `CheckProfitTargetAndClose()` – když celkový zisk >= `gridTargetProfitUSD`, uzavře všechny pozice Gridu
- `OnNewBar(buySignal, sellSignal, volume, tfBuyValid, tfSellValid)` – na nový bar:
  - Bez pozic: otevře první BUY nebo SELL podle signálu **a** TF1+TF2 (pokud jsou nastaveny)
  - S BUY pozicemi: přidá další BUY, když cena klesla o `gridDistancePoints` a `canBuy` (signál + TF1+TF2 uptrend)
  - S SELL pozicemi: přidá další SELL, když cena vzrostla o `gridDistancePoints` a `canSell` (signál + TF1+TF2 downtrend)

**TF1/TF2 filtr:** Grid otevírá pozice jen když směr souhlasí s oběma timeframy. BUY jen při uptrendu na TF1 i TF2, SELL jen při downtrendu.

---

### CDashboard

**Účel:** Zobrazení informací na grafu přes `Comment()`.

**Zobrazuje:** slowMa, fastMa, RSI, SMA distance, H1 trend, TF1 trend, TF2 trend, stav Gridu (počet Buy/Sell).

**Metody:**
- `Update()` – voláno každý tick; sestaví a zobrazí text

---

## Tok OnTick()

1. `g_positions.Refresh()` – aktualizace seznamu pozic
2. `g_equityDD.CheckAndClose()` – kontrola drawdownu (Single)
3. `g_grid.CheckProfitTargetAndClose()` – uzavření Gridu při cílovém zisku
4. `g_trailing.Update()` – trailing stop (Single, SL_TRAIL)
5. **Na nový bar:**
   - `g_signals.GetSignals()` – výpočet signálů
   - Pokud `EXIT_BY_OPPOSITE_SIGNAL` + Single: uzavření protisměrných pozic
   - Single: otevření BUY/SELL podle signálu
   - Grid: `g_grid.OnNewBar(...)` s TF1/TF2 filtrem
6. `g_dashboard.Update()` – aktualizace dashboardu

---

## Enumerace

### ENUM_EXIT_MODE
- `EXIT_BY_SL_TRAIL` – uzavření přes Stop Loss a trailing stop
- `EXIT_BY_OPPOSITE_SIGNAL` – uzavření při protisměrném crossover signálu

### ENUM_TRADE_MODE
- `TRADE_SINGLE` – jedna pozice najednou
- `TRADE_GRID` – Grid strategie (více úrovní)