==============================================================================
KAMLETFX BOT V2 — PEMASANGAN EA PENUTUP CEPAT (KFX_FastClose)
==============================================================================
Dokumen ini menjelaskan cara memasang mesin penutupan cepat di MT5.
Tanpa EA ini bot tetap berjalan seperti sebelumnya (penutupan berurutan dari
Python). EA ini HANYA mempercepat penutupan; strategi tetap di Python.

Berkas yang dibutuhkan:
  1) KFX_FastClose.mq5      -> dipasang di folder Experts MT5
  2) bot_mt5_v2.py          -> script bot (sudah mendukung EA ini otomatis)

------------------------------------------------------------------------------
BAGIAN 1 — KENAPA PERLU EA?
------------------------------------------------------------------------------
mt5.order_send() di Python bersifat BLOCKING: ia menunggu jawaban trade server
sebelum kembali. Menutup 10 posisi berarti 10 kali menunggu -> total waktunya
kurang lebih 10 x round-trip.

Di dalam MQL5 (EA) tersedia OrderSendAsync(): permintaan hanya dimasukkan ke
antrean terminal lalu fungsi langsung kembali TANPA menunggu jawaban server.
Semua permintaan terkirim ke server hampir bersamaan, sehingga latensi jaringan
dibayar sekali, bukan sepuluh kali.

Hasil simulasi (RTT 50 ms/order):
    Posisi   Berurutan (Python)   Async (EA)     Percepatan
    1              50 ms            66 ms          0.8x
    5             251 ms            98 ms          2.6x
    10            502 ms           131 ms          3.8x
    20           1003 ms           213 ms          4.7x

Catatan: untuk 1 posisi EA sedikit lebih lambat (~15 ms) karena ada serah-terima
berkas. Keuntungan besar muncul pada basket banyak posisi — kasus yang dikeluhkan.

PENTING: semua posisi TIDAK akan tertutup pada harga yang sama. EA mengirim
permintaan secepat mungkin; harga eksekusi akhir tetap ditentukan broker.

------------------------------------------------------------------------------
BAGIAN 2 — ARSITEKTUR (Python + EA)
------------------------------------------------------------------------------
    +--------------------------+          +---------------------------+
    |  bot_mt5_v2.py (Python)  |          |  KFX_FastClose.mq5 (EA)   |
    |  - sinyal M1             |          |  - OrderSendAsync         |
    |  - grid, lot, TP, DD     |          |  - verifikasi posisi      |
    |  - ON/OFF, heartbeat     |          |  - laporan hasil          |
    +-----------+--------------+          +-------------+-------------+
                |                                       |
                | tulis kfx_close_cmd.txt               |
                +-------> MQL5\Files  ---------------->|
                |                                       |
                | baca  kfx_close_result.txt            |
                |<------ MQL5\Files  <------------------+
                |                                       |
                | baca  kfx_ea_state.txt (detak 1 detik)|
                |<------ MQL5\Files  <------------------+

Komunikasi memakai berkas teks di folder data terminal:
    C:\Users\<user>\AppData\Roaming\MetaQuotes\Terminal\<hash>\MQL5\Files
Python menemukan folder ini otomatis dari terminal_info().data_path.

Alur saat Basket TP tercapai:
  1. Python mendeteksi floating >= target.
  2. Status CLOSING langsung aktif -> entry & grid diblokir.
  3. Python menulis berkas perintah (atomik) + request_id unik.
  4. EA membaca perintah pada timer 25 ms, lalu mengirim SEMUA penutupan
     dengan OrderSendAsync tanpa menunggu satu per satu.
  5. Python membaca berkas hasil, lalu MEMVERIFIKASI ULANG posisi lewat MT5.
  6. Bila masih ada sisa -> Python melanjutkan penutupan (tidak ada yang tertinggal).

Kalau EA tidak terpasang / detak basi / AutoTrading OFF -> Python otomatis
memakai jalur lama. Tidak ada perubahan perilaku yang membahayakan.

------------------------------------------------------------------------------
BAGIAN 3 — PEMASANGAN (Windows RDP)
------------------------------------------------------------------------------
LANGKAH 1. Salin berkas EA ke terminal MT5
  a. Di MT5 tekan F4 (MetaEditor terbuka) atau buka MetaEditor.
  b. Menu File -> Open Data Folder.
  c. Masuk ke MQL5\Experts, buat folder "KAMLETFX" (opsional).
  d. Salin KFX_FastClose.mq5 ke folder tersebut.
  e. Di MetaEditor tekan F7 / tombol Compile.
     Berhasil bila muncul "0 error(s), 0 warning(s)".
     Kalau ada error, kirimkan isi tab "Errors" agar diperbaiki.

LANGKAH 2. Pasang EA ke chart
  a. Kembali ke MT5, buka chart simbol bot (mis. VOL_80).
  b. Panel Navigator (Ctrl+N) -> Expert Advisors -> KFX_FastClose.
  c. Seret ke chart. Pada dialog: centang "Allow Algo Trading".
  d. Klik OK. Muncul senyum di kanan atas chart = EA aktif.

LANGKAH 3. Aktifkan Algo Trading terminal
  Tombol "Algo Trading" di toolbar MT5 harus HIJAU (aktif).
  Tanpa ini EA menolak semua perintah dan menuliskan alasannya di berkas hasil.

LANGKAH 4. Verifikasi dari CMD (tanpa mengirim order)
    cd C:\kamletfx
    python bot_mt5_v2.py --ea-status

  Contoh keluaran bila berhasil:
    EA PENUTUP CEPAT (KFX_FastClose)
      Status          : SIAP
      Keterangan      : siap (chart VOL_80, umur detak 0.4s)
      EA versi        : 1.00
      AutoTrading     : ON

  Uji diagnostik lebih lengkap (TETAP tanpa order):
    python bot_mt5_v2.py --ea-selftest

  Bila "TIDAK SIAP", ikuti keterangan yang ditampilkan.

LANGKAH 5. Jalankan bot seperti biasa
    python bot_mt5_v2.py --live
  Bot akan otomatis memakai EA bila terdeteksi siap.

------------------------------------------------------------------------------
BAGIAN 4 — PENGATURAN (opsional, environment variable)
------------------------------------------------------------------------------
    KAMLETFX_EA_BRIDGE
        auto  (bawaan) = pakai EA bila siap, kalau tidak pakai Python
        0              = jangan pernah pakai EA
        1              = wajib EA (dicatat bila tidak siap, lalu tetap jalan)
    KAMLETFX_EA_TIMEOUT    (bawaan 20)   detik menunggu jawaban EA
    KAMLETFX_EA_POLL       (bawaan 0.008) jeda cek berkas hasil (detik)
    KAMLETFX_EA_STATE_AGE  (bawaan 5)    umur maksimum detak EA (detik)

Bisa ditulis di berkas kfx.env (sebelum baris python, folder sama):
    KAMLETFX_EA_BRIDGE=auto

Parameter EA (dialog EA di chart):
    InpTimerMs     = 25    periode pemeriksaan perintah (ms)
    InpMaxRounds   = 6     putaran kirim ulang maksimum
    InpRoundWaitMs = 400   tunggu konfirmasi per putaran (ms)
    InpDeviation   = 300   toleransi slippage (point)
    InpCmdMaxAgeS  = 10    umur maksimum perintah (detik)
    InpVerbose     = true  tulis jejak ke tab Experts

------------------------------------------------------------------------------
BAGIAN 5 — PENGAMAN YANG SUDAH TERPASANG
------------------------------------------------------------------------------
Di sisi EA:
  - Hanya menutup posisi dengan SYMBOL == perintah DAN MAGIC == perintah.
    Posisi manual / bot lain TIDAK tersentuh.
  - Menolak perintah dengan magic <= 0 atau symbol kosong.
  - Setiap request_id hanya diproses SEKALI (tidak ada eksekusi dobel).
  - Perintah lebih tua dari InpCmdMaxAgeS DITOLAK. Ini mencegah perintah lama
    dieksekusi bila EA baru dipasang beberapa saat kemudian.
  - Putaran retry terbatas; sukses hanya dilaporkan bila posisi benar-benar habis.
  - Berkas ditulis atomik (tmp lalu FileMove) agar tidak dibaca separuh.

Di sisi Python:
  - CLOSING aktif SEBELUM apa pun; entry & grid diblokir seketika.
  - Hasil EA tetap diverifikasi ulang lewat MT5 (terminal = sumber kebenaran).
  - Sisa posisi ditangani Python sampai habis; Session Profit dibukukan sekali.
  - DRY RUN tidak pernah menyentuh EA.

------------------------------------------------------------------------------
BAGIAN 6 — MEMBACA HASIL PENGUKURAN DI CMD
------------------------------------------------------------------------------
Setelah penutupan, CMD menampilkan:

    ---- PENGUKURAN CLOSE ALL (Take Profit layer 3) ----
      Posisi  : 10 (berhasil 10, gagal 0, sisa 0)
      Trigger -> kirim pertama     : 0.1 ms
      Kirim -> respons pertama     : 128.4 ms
      Respons pertama -> tuntas    : 2.1 ms
      TOTAL durasi close all       : 130.6 ms (0.131 s)
      Putaran / worker             : 1 / 1
      Floating saat trigger        : 100.5
      Realized (estimasi)          : 100.5

Cara menafsirkan:
  - "Trigger -> kirim pertama" BESAR  -> hambatan di Python/berkas.
  - "Kirim -> respons pertama" BESAR  -> hambatan di broker/jaringan/likuiditas.
  - "Respons -> tuntas" BESAR         -> posisi menyusut bertahap (partial fill).
  - "sisa" > 0                        -> broker menolak; CLOSING dipertahankan
                                         dan bot mencoba lagi pada putaran loop.

------------------------------------------------------------------------------
BAGIAN 7 — MASALAH YANG SERING TERJADI
------------------------------------------------------------------------------
"EA tidak dipakai: berkas detak kfx_ea_state.txt belum ada"
    -> EA belum dipasang / belum di-attach ke chart. Ulangi Bagian 3.

"detak EA sudah X detik (basi)"
    -> EA dilepas, terminal ditutup, atau chart dihapus. Attach ulang.

"AutoTrading terminal OFF"
    -> Klik tombol Algo Trading di toolbar MT5 sampai hijau.

"EA tidak menjawab dalam 20 detik"
    -> MetaEditor belum compile, EA belum attach, atau terminal sibuk.
       Bot otomatis memakai jalur Python; tidak ada posisi yang tertinggal.

"perintah kedaluwarsa"
    -> Berkas perintah lama (> InpCmdMaxAgeS). Ini normal dan disengaja.
       Bot menulis perintah baru setiap kali penutupan dibutuhkan.

Kompilasi gagal di MetaEditor
    -> Kirim isi tab Errors. Jangan menjalankan EA hasil kompilasi gagal.

"0 error(s), 0 warning(s)" tetapi EA tidak bereaksi
    -> Pastikan chart memakai simbol yang sama dengan pengaturan bot,
       dan AutoTrading hijau. Jalankan: python bot_mt5_v2.py --ea-selftest

------------------------------------------------------------------------------
BAGIAN 8 — YANG PERLU DIUKUR DI AKUN DEMO ANDA
------------------------------------------------------------------------------
Angka pada Bagian 1 berasal dari SIMULASI, bukan dari terminal MT5 nyata.
Untuk mengukur yang sebenarnya:
  1. Jalankan bot dengan --live di akun demo, biarkan membuka beberapa posisi.
  2. Saat basket TP tercapai, salin seluruh blok "PENGUKURAN CLOSE ALL" dari CMD.
  3. Bandingkan dengan menjalankan tanpa EA (KAMLETFX_EA_BRIDGE=0) pada kondisi
     pasar serupa.
Kirimkan kedua blok itu bila ingin dianalisis lebih lanjut.
==============================================================================
