# Setup, API, dan Deployment Kita Signal

Dokumen ini mencatat semua hal eksternal yang dibutuhkan agar Kita Signal berpindah
dari **Mode Simulasi** ke **Data Live**.

## 1. Kebutuhan runtime

- Node.js `>= 22.13`
- Cloudflare Worker-compatible runtime
- Cloudflare D1 dengan binding bernama `DB`
- Market-data API Twelve Data untuk candle live

Kamu tidak membutuhkan API AI untuk menjalankan mesin sinyal. Entry, SL, TP,
indikator, dan alasan dasar dihitung secara deterministik agar hasil bisa diuji.

## 2. Environment variable

Salin `.env.example` menjadi `.env` untuk lingkungan lokal, lalu isi:

```env
TWELVE_DATA_API_KEY=isi_api_key_twelve_data
CRON_SECRET=ganti_dengan_random_secret_panjang
```

Jangan simpan API key asli ke Git atau memasukkannya ke kode frontend.

`CRON_SECRET` **tidak diperoleh dari layanan mana pun**. Nilainya dibuat sendiri
sebagai kata sandi acak untuk melindungi endpoint cron. Contoh membuatnya:

```bash
openssl rand -hex 32
```

Pada deployment resmi Kita Signal, `TWELVE_DATA_API_KEY` dan `CRON_SECRET` sudah
dipasang sebagai secret server. Nilai aslinya tidak disimpan di paket source.

### Mendapatkan Twelve Data API key

1. Daftar di <https://twelvedata.com/>.
2. Buka dashboard API key.
3. Salin key ke `TWELVE_DATA_API_KEY`.
4. Pastikan paket API mendukung forex, gold, crypto, interval `1min`, `1h`, dan
   `4h` untuk simbol yang dipakai.

Endpoint yang digunakan:

```text
GET https://api.twelvedata.com/time_series
```

Parameter: `symbol`, `interval`, `outputsize`, `timezone=UTC`, `order=asc`, dan
`apikey`. Dokumentasi resmi: <https://twelvedata.com/docs#time-series>

Mapping simbol:

| Internal | Twelve Data |
|---|---|
| XAUUSD | XAU/USD |
| BTCUSD | BTC/USD |
| GBPJPY | GBP/JPY |
| EURUSD | EUR/USD |

Harga provider umum dapat berbeda dari harga broker tempat kamu entry. Untuk
produksi serius, buat adapter broker sendiri yang memberikan candle **bid/ask**
dan mapping simbol yang sama dengan akun tradingmu.

## 3. Database

Binding D1 sudah dideklarasikan sebagai `DB` pada `.openai/hosting.json`. Schema
berada di `db/schema.ts`, sedangkan SQL migration berada di folder `drizzle/`.

Tabel utama:

- `instruments`
- `market_snapshots`
- `signals`
- `signal_events`
- `backtest_runs`

Data awal simulasi dibuat otomatis saat database masih kosong. Setelah API key
aktif dan scanner berjalan, snapshot berikutnya memakai data live dan diberi
label `live`; data simulasi lama tetap transparan sebagai riwayat demo.

## 4. Otomatisasi cron

Kita Signal menyediakan endpoint:

```text
GET /api/cron?task=scan
GET /api/cron?task=track
```

Keduanya wajib memakai header:

```http
Authorization: Bearer NILAI_CRON_SECRET
```

Jadwal yang disarankan:

- `scan`: setiap pergantian candle H1, misalnya menit ke-2 setiap jam.
- `track`: setiap 5 menit untuk mengecek entry/TP/SL.

Contoh cron Linux:

```cron
2 * * * * curl -fsS -H "Authorization: Bearer GANTI_SECRET" "https://signal.kitangoding.com/api/cron?task=scan"
*/5 * * * * curl -fsS -H "Authorization: Bearer GANTI_SECRET" "https://signal.kitangoding.com/api/cron?task=track"
```

Scanner mempunyai cache 10 menit dan backtest cache 1 jam untuk melindungi kuota
API dari klik berulang.

## 5. Endpoint aplikasi

| Method | Endpoint | Kegunaan |
|---|---|---|
| GET | `/api/overview` | Snapshot, sinyal aktif, riwayat, statistik |
| POST | `/api/scan` | Analisis satu instrumen atau `ALL` |
| POST | `/api/track` | Perbarui status entry/TP/SL |
| POST | `/api/backtest` | Uji aturan pada histori candle |
| GET | `/api/cron` | Pemicu terjadwal yang memakai bearer secret |

Body scanner/backtest:

```json
{ "symbol": "XAUUSD" }
```

Nilai simbol dapat berupa `XAUUSD`, `BTCUSD`, `GBPJPY`, `EURUSD`, atau `ALL`
untuk scanner dan tracker.

## 6. Deployment

Versi ini dibuat untuk runtime Cloudflare Worker/Vinext. Pada platform yang
mendukung proyek ini, proses build dijalankan melalui:

```bash
npm ci
npm run build
```

Domain produksi yang disiapkan adalah `https://signal.kitangoding.com/`.

Setelah deployment:

1. Pasang binding database `DB`.
2. Terapkan migration pada folder `drizzle/`.
3. Tambahkan `TWELVE_DATA_API_KEY` sebagai secret server.
4. Tambahkan `CRON_SECRET` sebagai secret server.
5. Jalankan `/api/overview` untuk membuat data awal.
6. Coba scanner pada satu instrumen.
7. Pasang cron setelah hasil manual berhasil.

Shared hosting yang hanya mendukung PHP tidak dapat menjalankan versi ini. Gunakan
Cloudflare-compatible hosting atau VPS Node.js. Jika nanti dipindahkan ke Laravel,
logika pada `app/lib/market.ts`, `strategy.ts`, dan `engine.ts` perlu diterjemahkan
ke service PHP; struktur tabel dan aturan bisnisnya tetap sama.

## 7. Sebelum dipakai sungguhan

- Hapus atau pisahkan riwayat demo dari statistik live.
- Cocokkan feed dengan broker dan gunakan harga bid/ask.
- Jalankan backtest per instrumen dan walk-forward test.
- Jalankan paper trading minimal beberapa minggu.
- Jangan mengubah sinyal lama setelah diterbitkan.
- Jangan menganggap setup score sebagai probabilitas menang.
- Jangan menjanjikan profit kepada pengguna.