# 📘 Panduan Alur Penggunaan & Operasional — AI Market Signal Bot

Dokumen ini menjelaskan alur operasional, struktur menu Telegram, instruksi instalasi, serta langkah-langkah penggunaan bot trading agar berjalan stabil, aman, dan bebas dari kendala teknis.

---

## 1. Visi Produk & Target Pengguna
**AI Market Signal Bot** bertindak sebagai asisten analisis pasar pintar dan eksekutor trading otomatis berbasis probabilitas AI untuk instrumen Gold (XAUUSD) dan Forex. 
* **Target Pengguna**: Trader Forex/Gold yang membutuhkan asisten scalping cepat dengan perlindungan manajemen risiko otomatis.
* **Prinsip Utama**: Bebas batasan transaksi (Unlimited trades), pengamanan stop dinamis, dan kontrol penuh dari Telegram.

---

## 2. Alur Menu Telegram (Menu Flow)

Bot mendukung navigasi berbasis tombol interaktif (**Inline Keyboard**) yang bersih dan modular:

```mermaid
graph TD
    Start[/start] --> Welcome[Pesan Selamat Datang & Status]
    Welcome --> MenuMain{Menu Utama}
    
    MenuMain --> ButtonForex[📊 Sinyal Forex / Gold]
    ButtonForex --> KeyboardPairs{Pilih Pair}
    KeyboardPairs --> XAUUSD[Gold / XAUUSD]
    KeyboardPairs --> EURUSD[EURUSD]
    KeyboardPairs --> GBPUSD[GBPUSD]
    
    XAUUSD & EURUSD & GBPUSD --> KeyboardMode{Pilih Mode Trading}
    KeyboardMode --> Scalping[⚡ Scalping]
    KeyboardMode --> Intraday[🕒 Intraday]
    KeyboardMode --> Swing[📈 Swing]
    
    Scalping & Intraday & Swing --> SignalCard[AI Signal Card Generated]
    SignalCard --> ButtonTradeReal[💰 Entry Akun Real]
    SignalCard --> ButtonTradeDemo[🧪 Entry Akun Demo]
    SignalCard --> ButtonWatch[⭐ Watchlist]
    
    MenuMain --> ButtonAuto[🟢 Kelola Auto Trading]
    ButtonAuto --> KeyboardAuto{Kontrol Auto}
    KeyboardAuto --> EnableAuto[🟢 Aktifkan Auto Trading]
    KeyboardAuto --> DisableAuto[🔴 Nonaktifkan Auto Trading]
    
    MenuMain --> ButtonWatchlist[⭐ Lihat Watchlist]
    MenuMain --> ButtonSettings[⚙️ Status & Parameter]
```

---

## 3. Alur Penggunaan Chat Bebas (Natural Language Flow)

Selain menggunakan tombol, pengguna dapat mengetik secara bebas. Bot dilengkapi **NLP Parser** sederhana untuk mendeteksi maksud:

| Chat Pengguna | Analisis Maksud | Respon Bot |
|---|---|---|
| `XAUUSD sekarang arah mana?` | Menganalisis Gold (XAUUSD) dalam mode default (Scalping) | Menampilkan AI Signal Card & tombol order |
| `EURUSD buy atau sell?` | Menganalisis EURUSD | Menampilkan AI Signal Card |
| `GBPUSD intraday` | Menganalisis GBPUSD dengan mode Intraday | Menampilkan AI Signal Card Intraday |
| `/watchlist` | Perintah melihat daftar pantau | Menampilkan daftar Watchlist aktif |
| `/auto` | Perintah mengelola Auto Trading | Membuka kontrol panel auto-trading |

---

## 4. Alur Kerja Auto Trading (Scalping Loop)

Sistem auto trading dirancang untuk melakukan transaksi cepat (scalping) dengan aturan penutupan ketat:

```
[Mulai Auto Trading]
       │
       ▼
┌─────────────────────────────┐
│ Cek Apakah Ada Posisi Aktif  │◄──────────────────────────────┐
└──────────────┬──────────────┘                                │
               │                                               │
        (Ada Posisi?)                                          │
       ┌───────┴───────┐                                       │
      YES              NO                                      │
       │               │                                       │
       ▼               ▼                                       │
┌──────────────┐ ┌──────────────────────────────────────────┐  │
│ Pantau P&L   │ │ AI Scan & Entry Posisi (BUY/SELL)        │  │
└──────┬───────┘ │ (SL/TP Otomatis Disesuaikan Broker)      │  │
       │         └────────────────────┬─────────────────────┘  │
  (TP/SL Hit?)                        │                        │
   ┌───┴───┐                          ▼                        │
  NO      YES                  [Posisi Dibuka]                 │
   │       │                          │                        │
   │       ▼                          └────────────────────────┘
   │     [Tutup Posisi & Update Rekap]
   │       │
   ▼       ▼
[Tunggu Cooldown 15 Detik] ─────────────────────────────────────┘
```

---

## 5. Fitur Pengaman Otomatis (Safety Filters)
* **Dynamic Stops Level**: Jika harga bergerak mendekati stop saat eksekusi, jembatan MT5 otomatis menggeser SL/TP ke jarak aman minimal agar broker tidak menolak order (`retcode 10016`).
* **Auto-Decimal Rounding**: SL/TP dibulatkan menyesuaikan dengan jumlah digit desimal simbol broker (XAUUSD 2 desimal).
* **Unlimited Trades**: `MAX_OPEN_TRADES=0` memungkinkan bot bertransaksi terus menerus tanpa batas sampai dinonaktifkan secara manual.

---

## 6. Panduan Operasional & Troubleshooting

> [!IMPORTANT]
> **ATURAN UTAMA OPERASIONAL MT5**
> Karena MetaTrader 5 menggunakan GUI Windows, **Aplikasi Desktop MetaTrader 5 harus selalu dibuka secara manual oleh Anda di laptop/PC**. Jangan biarkan sistem Python meluncurkannya di background karena Windows akan menahannya (hang/freeze).

### Langkah Menjalankan Bot Sehari-hari:
1. **Buka MT5**: Klik dua kali ikon MT5 di laptop Anda. Pastikan tombol **Algo Trading** di menu atas berwarna hijau.
2. **Pilih Akun**: 
   * Jika ingin trading **Demo**: Login ke akun demo Anda di MT5 laptop.
   * Jika ingin trading **Real**: Login ke akun real Anda di MT5 laptop.
   *(Bot otomatis mengikuti akun apa pun yang aktif di aplikasi MT5 Anda)*
3. **Aktifkan Bot**: Masuk ke Telegram Bot Anda, ketik `/auto` lalu klik **🟢 Aktifkan Auto Trading**.

### Mengatasi Kendala (Troubleshooting):
* **Error `MT5 bridge health gagal dibaca` (Error 530/1033)**: 
  * Ini berarti aplikasi MT5 di laptop Anda sedang freeze/hang atau jembatan Python membeku.
  * **Solusi**: Tutup aplikasi MT5 di laptop Anda. Buka Windows PowerShell di folder project, ketik perintah berikut untuk merestart total jembatan:
    ```powershell
    Stop-Process -Name "terminal64" -Force -ErrorAction SilentlyContinue
    Stop-Process -Name "python" -Force -ErrorAction SilentlyContinue
    ```
  * Setelah mati, buka kembali aplikasi MT5 Anda secara manual, jembatan akan otomatis pulih kembali dalam 5 detik.

---

## 7. Cara Install & Menjalankan Project

### A. Di Laptop (Jembatan MT5):
1. **Instal dependencies Python**:
   ```bash
   cd mt5-bridge
   pip install -r requirements.txt
   ```
2. **Jalankan Jembatan**:
   ```powershell
   .\scripts\start-bridge.ps1
   ```
3. **Aktifkan Terowongan Cloudflare (Tunnel)**:
   ```powershell
   .\cloudflared.exe tunnel --url http://127.0.0.1:8095
   ```

### B. Di Server VPS (Bot Telegram):
1. **Instal dependencies Node.js**:
   ```bash
   npm install
   ```
2. **Build Project**:
   ```bash
   npm run build
   ```
3. **Jalankan via PM2**:
   ```bash
   pm2 start dist/src/index.js --name "treding-forex-ai"
   ```
