Berikut adalah **Dokumentasi API Lengkap (VSOL Multi-OLT Manager v2.1)**.

Dokumentasi ini dirancang agar mudah dibaca oleh frontend developer atau untuk keperluan integrasi dengan sistem lain (seperti Grafana, Telegram Bot, atau Web Dashboard Custom).

Silakan simpan ini sebagai file `README.md` atau `API_DOCS.md`.

---

```markdown
# 📡 VSOL Multi-OLT API Documentation v2.1

Service ini berfungsi sebagai **Middleware (Jembatan)** yang mengubah antarmuka web HTML OLT VSOL (yang jadul) menjadi **RESTful JSON API** modern. Mendukung multiple OLT management dalam satu endpoint.

## 📋 Base Information

* **Base URL:** `http://<IP_SERVER>:8000`
* **Content-Type:** `application/json`
* **Interactive Docs (Swagger UI):** `http://<IP_SERVER>:8000/docs` (Sangat direkomendasikan untuk testing langsung).
* **Redoc:** `http://<IP_SERVER>:8000/redoc`

---

## 🚀 Daftar Endpoints

### 1. Cek Kesehatan Sistem (Health Check)
Memastikan service API berjalan normal.

* **Endpoint:** `GET /`
* **Parameters:** Tidak ada.

**Response:**
```json
{
  "msg": "VSOL Multi-OLT API Ready"
}

```

---

### 2. Mendapatkan Daftar OLT

Mendapatkan list server OLT yang terdaftar di konfigurasi `OLT_LIST`.

* **Endpoint:** `GET /system/olts`
* **Parameters:** Tidak ada.

**Response:**

```json
[
  {
    "id": 1,
    "name": "OLT Wuznet (Main)",
    "ip": "[http://ip.wuznet.com:88](http://ip.wuznet.com:88)"
  },
  {
    "id": 2,
    "name": "OLT Cabang Selatan",
    "ip": "[http://192.168.1.100](http://192.168.1.100)"
  }
]

```

---

### 3. Dashboard Statistik

Mengambil ringkasan data untuk ditampilkan di halaman depan (Home) dashboard. Data mencakup jumlah total, online, offline, dan kesehatan sinyal.

* **Endpoint:** `GET /dashboard/stats`
* **Parameters:**

| Parameter | Tipe | Wajib | Deskripsi |
| --- | --- | --- | --- |
| `olt_id` | `int` | **Ya** | ID dari OLT (didapat dari endpoint `/system/olts`) |

**Contoh Request:**
`GET /dashboard/stats?olt_id=1`

**Response:**

```json
{
  "olt_name": "OLT Wuznet (Main)",
  "total_onu": 61,
  "online": 57,
  "offline": 4,
  "signal_health": {
    "good": 50,      // Sinyal > -24 dBm
    "warning": 5,    // Sinyal antara -24 s/d -27 dBm
    "critical": 2,   // Sinyal < -27 dBm
    "avg_rx": -19.45 // Rata-rata sinyal
  },
  "last_update": "10:30:15"
}

```

---

### 4. Mendapatkan List Semua ONU

Mengambil daftar tabel semua ONU beserta status ringkas (Status, Sinyal, Jarak).

* **Endpoint:** `GET /onu/list`
* **Parameters:**

| Parameter | Tipe | Wajib | Deskripsi |
| --- | --- | --- | --- |
| `olt_id` | `int` | **Ya** | ID dari OLT. |

**Contoh Request:**
`GET /onu/list?olt_id=1`

**Response:**

```json
[
  {
    "id": "EPON0/1:1",
    "mac": "D4:D5:1B:63:6B:00",
    "name": "Yuli_Setianingati",
    "status": "Online",
    "rx_power": "-18.04",
    "tx_power": "2.21",
    "distance": "1147",
    "status_color": "green" // Helper untuk frontend (green/red)
  },
  {
    "id": "EPON0/1:2",
    "mac": "A4:BE:2B:4C:BF:15",
    "name": "Pelanggan_B",
    "status": "Offline",
    "rx_power": "N/A",
    "tx_power": "N/A",
    "distance": "-",
    "status_color": "red"
  }
]

```

---

### 5. Detail Lengkap ONU

Mengambil data detail ("Kartu Pasien") dari satu ONU tertentu. Menggabungkan data Status, Optik, Info Dasar, dan Diagnosa.

* **Endpoint:** `GET /onu/detail`
* **Parameters:**

| Parameter | Tipe | Wajib | Deskripsi |
| --- | --- | --- | --- |
| `olt_id` | `int` | **Ya** | ID dari OLT. |
| `id` | `str` | **Ya** | ID ONU (Contoh: `EPON0/1:1`). Case insensitive. |

**Contoh Request:**
`GET /onu/detail?olt_id=1&id=EPON0/1:1`

**Response:**

```json
{
  "id": "EPON0/1:1",
  "basic_info": {
    "name": "Yuli_Setianingati",
    "mac": "D4:D5:1B:63:6B:00",
    "model": "V4.2",
    "vendor": "ZTE",
    "soft_ver": "V1.0.2"
  },
  "optical_info": {
    "rx_power": "-18.04",
    "tx_power": "2.21",
    "distance": "1147",
    "voltage": "3.25",
    "temperature": "45.2"
  },
  "status_info": {
    "status": "Online",
    "last_online": "2026/02/12 10:00:00",
    "last_offline": "2026/02/10 05:00:00",
    "uptime": "2 Days 5 Hours"
  },
  "diagnose_info": {
    "offline_reason": "Power Off" // Alasan mati terakhir
  }
}

```

---

## 🛠️ Cara Penggunaan (Contoh Python)

Berikut adalah contoh snippet Python sederhana untuk mengambil data dari API ini:

```python
import requests

API_URL = "http://localhost:8000"

# 1. Ambil List OLT
olts = requests.get(f"{API_URL}/system/olts").json()
print("OLT Tersedia:", olts)

# 2. Ambil Statistik OLT Pertama (ID=1)
stats = requests.get(f"{API_URL}/dashboard/stats", params={"olt_id": 1}).json()
print(f"Total ONU: {stats['total_onu']}")
print(f"Sinyal Rata-rata: {stats['signal_health']['avg_rx']} dBm")

# 3. Cari Detail ONU
onu_id = "EPON0/1:1"
detail = requests.get(f"{API_URL}/onu/detail", params={"olt_id": 1, "id": onu_id}).json()
print(f"Status {onu_id}: {detail['status_info']['status']}")
print(f"Rx Power: {detail['optical_info']['rx_power']} dBm")

```

## ⚠️ Catatan Penting

1. **Caching:** Data di-cache selama **20 detik** di sisi server. Jika Anda melakukan request berulang kali dalam waktu < 20 detik, Anda akan mendapatkan data yang sama. Ini fitur keamanan agar CPU OLT tidak overload.
2. **SessionKey:** API otomatis menangani login dan pengambilan `SessionKey`. Jika sesi OLT habis, API akan otomatis melakukan login ulang di background (mungkin butuh waktu 1-2 detik lebih lama saat request pertama setelah expired).
3. **URL Encoding:** Jika menggunakan browser/curl manual, karakter `/` pada ID ONU sebaiknya di-encode menjadi `%2F` (meskipun API ini sudah mendukung query param standar).
* Benar: `?id=EPON0/1:1` atau `?id=EPON0%2F1%3A1`



```

### Tips Tambahan:

Karena Anda menggunakan **FastAPI**, dokumentasi di atas sebenarnya sudah tersedia secara **Otomatis & Interaktif** di browser Anda.

Cukup buka browser dan ketik:
> **`http://<IP_SERVER_ANDA>:8000/docs`**

Di sana Anda bisa langsung mencoba tombol **"Try it out"**, mengisi kolom `olt_id`, dan melihat langsung respon JSON-nya tanpa perlu coding.

```