# *Telegram Notifications* — Sistem Notifikasi *Real-Time*

> **File:** `src/telegram_notifier.py`
> **Class:** `TelegramNotifier`
> **API:** Telegram Bot API (*async* via aiohttp)

---

## Arsitektur Notifikasi

```mermaid
flowchart LR
    A["Event\n(Trade / Alert / Timer)"] --> B["TelegramNotifier\n(async aiohttp)"]
    B --> C["Telegram Bot API\n(/sendMessage\n/sendPhoto\n/sendDocument)"]
    C --> D["User / Grup Telegram"]

    style A fill:#2d2d2d,stroke:#f5a623,color:#fff
    style B fill:#2d2d2d,stroke:#4a9eff,color:#fff
    style C fill:#2d2d2d,stroke:#50c878,color:#fff
    style D fill:#2d2d2d,stroke:#ff6b6b,color:#fff
```

```mermaid
flowchart TD
    LOOP["Main Loop\n(setiap 1 detik)"] --> NEW_DAY{"New day?"}
    NEW_DAY -- Ya --> DAILY["Daily Summary + Reset"]
    NEW_DAY -- Tidak --> HOURLY{"Hourly timer?"}
    HOURLY -- Ya --> HOUR_MSG["Hourly Analysis"]
    HOURLY -- Tidak --> HALF{"30-min timer?"}
    HALF -- Ya --> MARKET["Market Update"]
    HALF -- Tidak --> TRADE{"Trade executed?"}
    TRADE -- Ya --> OPEN["Trade Open Notification"]
    TRADE -- Tidak --> CLOSE{"Position closed?"}
    CLOSE -- Ya --> CLOSE_MSG["Trade Close Notification"]
    CLOSE -- Tidak --> LIMIT{"Limit hit?"}
    LIMIT -- Ya --> CRIT["Critical Limit Alert"]
    LIMIT -- Tidak --> FLASH{"Flash crash?"}
    FLASH -- Ya --> EMERG["Emergency Close Alert"]
    FLASH -- Tidak --> LOOP

    style LOOP fill:#1a1a2e,stroke:#4a9eff,color:#fff
    style DAILY fill:#1a1a2e,stroke:#50c878,color:#fff
    style HOUR_MSG fill:#1a1a2e,stroke:#50c878,color:#fff
    style MARKET fill:#1a1a2e,stroke:#50c878,color:#fff
    style OPEN fill:#1a1a2e,stroke:#f5a623,color:#fff
    style CLOSE_MSG fill:#1a1a2e,stroke:#f5a623,color:#fff
    style CRIT fill:#1a1a2e,stroke:#ff6b6b,color:#fff
    style EMERG fill:#1a1a2e,stroke:#ff6b6b,color:#fff
```

---

## Apa Itu *Telegram Notifications*?

*Telegram Notifications* mengirimkan **laporan *real-time*** ke grup Telegram setiap kali terjadi event penting — trade dibuka/ditutup, laporan harian, alert darurat, dan status sistem.

**Analogi:** *Telegram Notifications* seperti **dashboard pilot di cockpit** — menampilkan semua informasi penting secara *real-time* tanpa harus melihat layar trading.

---

## Konfigurasi

```
Bot Token:  Dari environment variable TELEGRAM_BOT_TOKEN
Chat ID:    Dari environment variable TELEGRAM_CHAT_ID
Format:     HTML (parse_mode)
Transport:  Async HTTP POST via aiohttp
Timezone:   WIB (Asia/Jakarta)
```

```python
# Inisialisasi
from dotenv import load_dotenv
load_dotenv()

bot_token = os.getenv("TELEGRAM_BOT_TOKEN")
chat_id = os.getenv("TELEGRAM_CHAT_ID")
enabled = bool(bot_token and chat_id)  # Auto-disable jika tidak dikonfigurasi
```

---

## 11 Tipe Notifikasi

| # | Tipe | Trigger | Frekuensi |
|---|------|---------|-----------|
| 1 | *Trade Open* | Order berhasil dieksekusi | Per trade |
| 2 | *Trade Close* | Posisi ditutup | Per trade |
| 3 | *Market Update* | Timer 30 menit | Setiap 30 menit |
| 4 | *Hourly Analysis* | Timer 1 jam | Setiap 1 jam |
| 5 | *Daily Summary* | Pergantian hari | 1x per hari |
| 6 | *Startup* | Bot dinyalakan | 1x per sesi |
| 7 | *Shutdown* | Bot dimatikan | 1x per sesi |
| 8 | *News Alert* | Event ekonomi terdeteksi | Per event |
| 9 | *Critical Limit* | Daily/total loss limit | Per event |
| 10 | *Emergency Close* | *Flash crash* / darurat | Per event |
| 11 | *System Status* | Status berkala | Per request |

---

## Format Pesan

### 1. *Trade Open*

```
🟢 LONG #123456
├ XAUUSD
├ Entry: 4950.00
├ Lot: 0.02
├ SL: 4937.00 (-$13)
├ TP: 4976.00 (+$26)
├ R:R: 1:2.0
├ AI: 75% | medium_volatility
└ SMC Bullish BOS + FVG
⏰ 14:35 WIB
```

| Elemen | Arti |
|--------|------|
| 🟢/🔴 | BUY (hijau) / SELL (merah) |
| LONG/SHORT | Arah posisi |
| #123456 | Ticket ID dari broker |
| R:R | *Risk to Reward ratio* |
| AI: 75% | ML *confidence* |
| medium_volatility | HMM *regime* |

---

### 2. *Trade Close*

```
✅ WIN #123456
├ XAUUSD BUY
├ Entry: 4950.00
├ Exit: 4965.00
├ Lot: 0.02
├ P/L: +$30.00 (+0.49%)
├ Pips: +150.0
├ Duration: 2m
├ Bal Before: $6130.00
└ Bal After: $6160.00
⏰ 14:40 WIB
```

| Emoji | Arti |
|-------|------|
| ✅ | WIN (profit) |
| ❌ | LOSS (rugi) |
| ➖ | BREAKEVEN (impas) |

---

### 3. *Market Update* (Setiap 30 Menit)

```
📊 XAUUSD $4965.00
├ 🟢 BUY 75%
├ UPTREND
├ medium_volatility
├ London-NY Overlap
└ ✅
⏰ 14:45
```

---

### 4. *Hourly Analysis* (Setiap 1 Jam)

```
📊 HOURLY 14:00 WIB

Account
├ Bal: $5,094.68
├ Eq: $5,120.50
├ Float: +$25.82
└ Day: +$150.00 (12 trades)

Positions (2)
├ #123456 BUY: +$30.00 M:+45
└ #123457 SELL: -$15.00 M:-20

Market
├ XAUUSD $4,965.00
├ London-NY Overlap
└ medium_volatility | high

AI Signal
├ BUY 75% / thresh 70%
└ Quality: EXCELLENT (score:85) → READY

Risk NORMAL
└ Daily Loss: $0.00 / $148.34

✅ News: SAFE
```

---

### 5. *Daily Summary*

```
🎉 DAILY REPORT 2025-02-06

Result
├ P/L: +$150.00 (+3.03%)
├ Gross Win: +$500.00
├ Gross Loss: -$350.00
├ Bal Start: $4,944.68
└ Bal End: $5,094.68

Stats
├ Total: 12 trades
├ Wins: 8 | Losses: 4
├ Win Rate: 66.7%
├ Profit Factor: 1.43
└ Avg/Trade: $12.50

Recent Trades
├ ✅ BUY: +$30.00
├ ❌ SELL: -$25.00
├ ✅ BUY: +$45.00
├ ➖ SELL: $0.00
└ ✅ BUY: +$100.00
```

| Emoji Hari | Arti |
|-----------|------|
| 🎉 | Hari profit |
| 📉 | Hari loss |
| ➖ | Hari breakeven |

---

### 6. *Startup*

```
🚀 BOT STARTED

Config
├ Symbol: XAUUSD
├ Mode: small
├ Capital: $5,000.00
├ Balance: $4,944.68
└ ML: Loaded (37 features)

Risk Settings
├ Risk/Trade: 1%
├ Max Daily Loss: 5%
├ Max Total Loss: 10%
└ SL: Smart (ATR-based)

✅ News: SAFE
⏰ 2025-02-06 08:15 WIB
```

---

### 7. *Shutdown*

```
🔴 BOT STOPPED

Session Summary
├ Balance: $5,094.68
├ Total Trades: 12
├ ✅ P/L: +$150.00
└ Uptime: 8.5h

⏰ 2025-02-06 16:45 WIB
```

---

### 8. *News Alert*

```
🚨 NEWS DANGER_NEWS
├ NFP (Non-Farm Payroll) - HIGH IMPACT
├ High volatility expected during release
└ Buffer: 60m
⏰ 20:25
```

| Emoji | Kondisi |
|-------|---------|
| 🚨 | DANGER_NEWS |
| ⚠️ | CAUTION / DANGER_SENTIMENT |
| ✅ | SAFE |

---

### 9. *Critical Limit Alert*

```
🚨 DAILY LOSS LIMIT REACHED 🚨

Daily Loss: $250.00
Limit: $250.00 (5%)

⛔ TRADING STOPPED FOR TODAY
Will resume tomorrow automatically.
```

---

### 10. *Emergency Close*

```
🚨 EMERGENCY CLOSE COMPLETE

Closed 3 positions due to flash crash detection
Total P/L: -$45.00
```

---

### 11. Alert (Berbagai Tipe)

| Alert Type | Emoji | Contoh |
|-----------|-------|--------|
| *flash_crash* | 🚨 | "Flash crash detected on XAUUSD" |
| *high_volatility* | ⚡ | "Volatility spike detected" |
| *connection_error* | 📡 | "MT5 connection lost" |
| *model_retrain* | 🔄 | "ML model retrained successfully" |
| *market_close* | 🔔 | "Market closing in 30 minutes" |
| *low_balance* | 💰 | "Account balance below threshold" |

---

## 3 Metode Pengiriman

```mermaid
flowchart LR
    N["TelegramNotifier"] --> SM["send_message()\n/sendMessage\nTeks biasa"]
    N --> SP["send_photo()\n/sendPhoto\nChart / grafik"]
    N --> SD["send_document()\n/sendDocument\nFile PDF"]

    style N fill:#2d2d2d,stroke:#4a9eff,color:#fff
    style SM fill:#2d2d2d,stroke:#50c878,color:#fff
    style SP fill:#2d2d2d,stroke:#f5a623,color:#fff
    style SD fill:#2d2d2d,stroke:#ff6b6b,color:#fff
```

| Metode | Endpoint | Kegunaan |
|--------|----------|---------|
| `send_message()` | `/sendMessage` | Teks biasa (semua notifikasi) |
| `send_photo()` | `/sendPhoto` | Chart/grafik (*daily report*) |
| `send_document()` | `/sendDocument` | File PDF (laporan detail) |

---

## *Error Handling*

```mermaid
flowchart TD
    SEND["send_message() / send_photo()"] --> TRY{"Try-Except"}
    TRY -- Berhasil --> CHECK{"HTTP Status\n== 200?"}
    CHECK -- Ya --> OK["Return True\n(Terkirim)"]
    CHECK -- Tidak --> LOG_ERR["Log Error\nReturn False"]
    TRY -- Exception --> LOG_WARN["Log Warning\nLanjut Trading"]

    DISABLED{"Token / ChatID\nkosong?"} --> AUTO["Auto-disable\nReturn True"]

    EMERG["Emergency Close"] --> CLOSE_POS["Tutup Posisi Dulu"]
    CLOSE_POS --> TRY_NOTIF{"Kirim Notifikasi"}
    TRY_NOTIF -- Gagal --> IGNORE["pass\n(Trading > Notifikasi)"]
    TRY_NOTIF -- Berhasil --> OK2["Notifikasi Terkirim"]

    style SEND fill:#1a1a2e,stroke:#4a9eff,color:#fff
    style OK fill:#1a1a2e,stroke:#50c878,color:#fff
    style OK2 fill:#1a1a2e,stroke:#50c878,color:#fff
    style LOG_ERR fill:#1a1a2e,stroke:#ff6b6b,color:#fff
    style LOG_WARN fill:#1a1a2e,stroke:#f5a623,color:#fff
    style IGNORE fill:#1a1a2e,stroke:#f5a623,color:#fff
    style AUTO fill:#1a1a2e,stroke:#888,color:#fff
```

```
Strategi: GRACEFUL DEGRADATION

1. Try-Except di setiap send method
   -> Gagal kirim? Log warning, lanjut trading

2. HTTP status check
   -> Status != 200? Log error, return False

3. Emergency close
   -> Telegram gagal? TETAP tutup posisi
   -> Trading > notifikasi dalam prioritas

4. Disabled mode
   -> Token/ChatID kosong? Auto-disable, return True
   -> Bot tetap berjalan tanpa notifikasi
```

Strategi ini menerapkan pola *graceful degradation* — kegagalan notifikasi **tidak pernah** menghentikan proses trading. Sistem *emergency close* akan tetap menutup posisi meskipun Telegram tidak responsif, menerapkan prinsip *circuit breaker* di mana komponen non-kritis diisolasi dari jalur kritis.

```python
# Contoh: Emergency close TIDAK boleh gagal karena Telegram
try:
    await telegram.send_message("Emergency close...")
except:
    pass  # Jangan biarkan Telegram failure menghentikan close
```

---

## *Rate Limiting*

| Notifikasi | Interval |
|-----------|----------|
| *Trade Open/Close* | Langsung (per event) |
| *Market Update* | 30 menit |
| *Hourly Analysis* | 1 jam |
| *Daily Summary* | 1x per hari |
| *Startup* / *Shutdown* | 1x per sesi |
| Min *message interval* | 1 detik (variable) |

*Rate limiting* mencegah flooding ke Telegram Bot API yang memiliki batas ~30 pesan/detik per grup. Interval minimum 1 detik antar pesan menjaga bot tetap dalam batas aman.

---

## Kapan Notifikasi Dikirim di *Main Loop*

```
Main Loop (setiap 1 detik)
    |
    |-- Cek new day? ------> Daily Summary + Reset
    |
    |-- Cek hourly timer? -> Hourly Analysis (setiap 1 jam)
    |
    |-- Cek 30min timer? --> Market Update (setiap 30 menit)
    |
    |-- Trade executed? ---> Trade Open notification
    |
    |-- Position closed? --> Trade Close notification
    |
    |-- Limit hit? --------> Critical Limit Alert
    |
    |-- Flash crash? ------> Emergency Close Alert
    |
    |-- (startup) ---------> Startup message
    |
    |-- (shutdown) --------> Shutdown message
```

---

## *Formatting* HTML

Semua pesan menggunakan HTML *parse mode*:

```html
<b>Bold</b>           -> Label penting
<code>Monospace</code> -> Angka, harga, nilai
<i>Italic</i>          -> Info tambahan, alasan signal
```

Tree structure menggunakan *box-drawing characters*:

```
├  -> Item tengah
└  -> Item terakhir
```