FRONTEND_API_DOC.md

# Aeterna AI - Front-End API Integration Guide (v4.0.0)

Dokumen ini ditujukan bagi tim Front-End untuk mengintegrasikan antarmuka pengguna dengan backend **Aeterna AI (Waste Intelligence Platform)**.

---

## 📡 Konfigurasi Global
*   **Base URL (Local)**: `http://localhost:8001`
*   **Content-Type**: `application/json`
*   **CORS**: Diaktifkan secara wildcard (`*`) untuk semua origin, method, dan header.

---

## 🗺️ Konstanta Wilayah (44 Kecamatan DKI Jakarta)
Untuk memetakan wilayah pada leaflet/map atau drop-down pilihan di FE, gunakan konstanta koordinat dan baseline berikut:

```typescript
export interface RegionMetadata {
  latitude: number;
  longitude: number;
  normal_avg: number;
  warning_threshold: number;
  critical_threshold: number;
  city: 'Jakarta Pusat' | 'Jakarta Utara' | 'Jakarta Barat' | 'Jakarta Selatan' | 'Jakarta Timur' | 'Kepulauan Seribu';
}

export const KECAMATAN_DATABASE: Record<string, RegionMetadata> = {
  // JAKARTA PUSAT
  "Menteng": { latitude: -6.1950, longitude: 106.8322, normal_avg: 120.0, warning_threshold: 160.0, critical_threshold: 180.0, city: "Jakarta Pusat" },
  "Senen": { latitude: -6.1822, longitude: 106.8452, normal_avg: 180.0, warning_threshold: 220.0, critical_threshold: 240.0, city: "Jakarta Pusat" },
  "Cempaka Putih": { latitude: -6.1802, longitude: 106.8686, normal_avg: 90.0, warning_threshold: 120.0, critical_threshold: 140.0, city: "Jakarta Pusat" },
  "Johar Baru": { latitude: -6.1866, longitude: 106.8572, normal_avg: 70.0, warning_threshold: 95.0, critical_threshold: 110.0, city: "Jakarta Pusat" },
  "Kemayoran": { latitude: -6.1628, longitude: 106.8438, normal_avg: 180.0, warning_threshold: 220.0, critical_threshold: 240.0, city: "Jakarta Pusat" },
  "Sawah Besar": { latitude: -6.1554, longitude: 106.8322, normal_avg: 110.0, warning_threshold: 145.0, critical_threshold: 165.0, city: "Jakarta Pusat" },
  "Tanah Abang": { latitude: -6.2104, longitude: 106.8122, normal_avg: 250.0, warning_threshold: 320.0, critical_threshold: 350.0, city: "Jakarta Pusat" },
  "Gambir": { latitude: -6.1764, longitude: 106.8190, normal_avg: 150.0, warning_threshold: 195.0, critical_threshold: 215.0, city: "Jakarta Pusat" },

  // JAKARTA UTARA
  "Penjaringan": { latitude: -6.1264, longitude: 106.7822, normal_avg: 280.0, warning_threshold: 350.0, critical_threshold: 380.0, city: "Jakarta Utara" },
  "Tanjung Priok": { latitude: -6.1322, longitude: 106.8722, normal_avg: 260.0, warning_threshold: 320.0, critical_threshold: 350.0, city: "Jakarta Utara" },
  "Koja": { latitude: -6.1214, longitude: 106.9133, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Utara" },
  "Cilincing": { latitude: -6.1288, longitude: 106.9452, normal_avg: 290.0, warning_threshold: 370.0, critical_threshold: 400.0, city: "Jakarta Utara" },
  "Pademangan": { latitude: -6.1328, longitude: 106.8422, normal_avg: 140.0, warning_threshold: 180.0, critical_threshold: 200.0, city: "Jakarta Utara" },
  "Kelapa Gading": { latitude: -6.1552, longitude: 106.9022, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Utara" },

  // JAKARTA BARAT
  "Cengkareng": { latitude: -6.1528, longitude: 106.7322, normal_avg: 340.0, warning_threshold: 420.0, critical_threshold: 460.0, city: "Jakarta Barat" },
  "Grogol Petamburan": { latitude: -6.1622, longitude: 106.7882, normal_avg: 220.0, warning_threshold: 280.0, critical_threshold: 310.0, city: "Jakarta Barat" },
  "Kalideres": { latitude: -6.1428, longitude: 106.7022, normal_avg: 260.0, warning_threshold: 330.0, critical_threshold: 360.0, city: "Jakarta Barat" },
  "Kebon Jeruk": { latitude: -6.1922, longitude: 106.7722, normal_avg: 210.0, warning_threshold: 260.0, critical_threshold: 290.0, city: "Jakarta Barat" },
  "Kembangan": { latitude: -6.1828, longitude: 106.7382, normal_avg: 180.0, warning_threshold: 230.0, critical_threshold: 250.0, city: "Jakarta Barat" },
  "Palmerah": { latitude: -6.2028, longitude: 106.7882, normal_avg: 160.0, warning_threshold: 200.0, critical_threshold: 220.0, city: "Jakarta Barat" },
  "Taman Sari": { latitude: -6.1454, longitude: 106.8182, normal_avg: 100.0, warning_threshold: 130.0, critical_threshold: 150.0, city: "Jakarta Barat" },
  "Tambora": { latitude: -6.1500, longitude: 106.8000, normal_avg: 80.0, warning_threshold: 110.0, critical_threshold: 125.0, city: "Jakarta Barat" },

  // JAKARTA SELATAN
  "Cilandak": { latitude: -6.2928, longitude: 106.7922, normal_avg: 180.0, warning_threshold: 230.0, critical_threshold: 250.0, city: "Jakarta Selatan" },
  "Jagakarsa": { latitude: -6.3328, longitude: 106.8222, normal_avg: 220.0, warning_threshold: 280.0, critical_threshold: 310.0, city: "Jakarta Selatan" },
  "Kebayoran Baru": { latitude: -6.2422, longitude: 106.7982, normal_avg: 210.0, warning_threshold: 260.0, critical_threshold: 290.0, city: "Jakarta Selatan" },
  "Kebayoran Lama": { latitude: -6.2488, longitude: 106.7722, normal_avg: 230.0, warning_threshold: 290.0, critical_threshold: 320.0, city: "Jakarta Selatan" },
  "Mampang Prapatan": { latitude: -6.2522, longitude: 106.8182, normal_avg: 120.0, warning_threshold: 150.0, critical_threshold: 170.0, city: "Jakarta Selatan" },
  "Pancoran": { latitude: -6.2622, longitude: 106.8382, normal_avg: 130.0, warning_threshold: 160.0, critical_threshold: 180.0, city: "Jakarta Selatan" },
  "Pasar Minggu": { latitude: -6.2828, longitude: 106.8438, normal_avg: 240.0, warning_threshold: 300.0, critical_threshold: 330.0, city: "Jakarta Selatan" },
  "Pesanggrahan": { latitude: -6.2588, longitude: 106.7588, normal_avg: 160.0, warning_threshold: 200.0, critical_threshold: 220.0, city: "Jakarta Selatan" },
  "Setiabudi": { latitude: -6.2228, longitude: 106.8282, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Selatan" },
  "Tebet": { latitude: -6.2288, longitude: 106.8482, normal_avg: 170.0, warning_threshold: 210.0, critical_threshold: 230.0, city: "Jakarta Selatan" },

  // JAKARTA TIMUR
  "Cakung": { latitude: -6.1828, longitude: 106.9482, normal_avg: 350.0, warning_threshold: 430.0, critical_threshold: 470.0, city: "Jakarta Timur" },
  "Cipayung": { latitude: -6.3128, longitude: 106.9022, normal_avg: 140.0, warning_threshold: 180.0, critical_threshold: 200.0, city: "Jakarta Timur" },
  "Ciracas": { latitude: -6.3228, longitude: 106.8782, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Timur" },
  "Duren Sawit": { latitude: -6.2228, longitude: 106.9282, normal_avg: 300.0, warning_threshold: 370.0, critical_threshold: 410.0, city: "Jakarta Timur" },
  "Jatinegara": { latitude: -6.2222, longitude: 106.8682, normal_avg: 240.0, warning_threshold: 300.0, critical_threshold: 330.0, city: "Jakarta Timur" },
  "Kramat Jati": { latitude: -6.2722, longitude: 106.8682, normal_avg: 220.0, warning_threshold: 270.0, critical_threshold: 300.0, city: "Jakarta Timur" },
  "Makasar": { latitude: -6.2622, longitude: 106.8782, normal_avg: 160.0, warning_threshold: 200.0, critical_threshold: 220.0, city: "Jakarta Timur" },
  "Matraman": { latitude: -6.2022, longitude: 106.8582, normal_avg: 130.0, warning_threshold: 160.0, critical_threshold: 180.0, city: "Jakarta Timur" },
  "Pasar Rebo": { latitude: -6.3122, longitude: 106.8522, normal_avg: 150.0, warning_threshold: 190.0, critical_threshold: 210.0, city: "Jakarta Timur" },
  "Pulo Gadung": { latitude: -6.1922, longitude: 106.8922, normal_avg: 220.0, warning_threshold: 270.0, critical_threshold: 300.0, city: "Jakarta Timur" },

  // KEPULAUAN SERIBU
  "Kepulauan Seribu Utara": { latitude: -5.5722, longitude: 106.5522, normal_avg: 11.0, warning_threshold: 15.0, critical_threshold: 18.0, city: "Kepulauan Seribu" },
  "Kepulauan Seribu Selatan": { latitude: -5.7722, longitude: 106.6522, normal_avg: 9.0, warning_threshold: 12.0, critical_threshold: 15.0, city: "Kepulauan Seribu" }
};
```

---

## 🔌 Referensi API Endpoint

### 1. Mengambil Berita Ter-crawled Harian
Endpoint ini menyajikan database berita seputar persampahan DKI Jakarta yang diperbarui berkala setiap 1 jam.

*   **URL**: `/api/v1/news`
*   **Method**: `GET`
*   **Headers**: `Accept: application/json`
*   **Response Schema (`200 OK`)**:
    ```json
    [
      {
        "title": "DKI Uji Coba Penarikan Retribusi Sampah Pelayanan Kebersihan Harian",
        "source": "Antara News",
        "url": "https://www.antaranews.com/tag/sampah-jakarta",
        "date_fetched": "2026-07-10",
        "summary": "Pemprov DKI Jakarta merencanakan uji coba penarikan retribusi pelayanan kebersihan/sampah berdasarkan golongan daya listrik..."
      }
    ]
    ```

---

### 2. Prediksi AI Otonom (Autopilot Mode)
Mengambil prediksi otonom untuk ke-44 kecamatan sekaligus untuk hari ini. Berguna untuk dashboard autopilot utama.

*   **URL**: `/api/v1/autopilot`
*   **Method**: `GET`
*   **Response Schema (`200 OK`)**:
    ```json
    {
      "status": "success",
      "date": "2026-07-10",
      "total_volume_ton": 8105.42,
      "total_trucks": 1640,
      "top_kecamatan": [
        {
          "location": "Cakung",
          "volume_ton": 355.20,
          "trucks": 72,
          "status": "SAFE",
          "city": "Jakarta Timur"
        }
      ],
      "rainy_regions": 0,
      "event_today": null
    }
    ```

---

### 3. Simulasi Prediksi Wilayah (Predictor Tool)
Melakukan peramalan timbulan sampah untuk kecamatan tertentu dengan parameter simulasi cuaca/event keramaian.

*   **URL**: `/api/v1/predict`
*   **Method**: `POST`
*   **Request Body**:
    ```typescript
    interface PredictionRequest {
      forecast_days: number;       // Ambang batas: 1 - 30 hari
      rainfall_mm: number;         // Curah hujan override (0.0 = Auto Open-Meteo)
      event_scale: number;         // 0 (none) sampai 5 (massive crowd)
      location: string;            // Salah satu nama dari 44 kecamatan
      granularity: 'daily' | 'hourly';
      model_type: 'chronos' | 'gradient_boosting';
    }
    ```
*   **Contoh Request Payload**:
    ```json
    {
      "forecast_days": 7,
      "rainfall_mm": 0.0,
      "event_scale": 0,
      "location": "Menteng",
      "granularity": "daily",
      "model_type": "gradient_boosting"
    }
    ```
*   **Response Schema (`200 OK`)**:
    ```json
    {
      "status": "success",
      "message": "Normal conditions.",
      "confidence_score": 0.9828,
      "data": {
        "prediction_results": [
          {
            "date": "2026-07-10",
            "location": "Menteng",
            "total_volume_ton": 120.54,
            "organic_waste_ton": 60.11,
            "plastic_waste_ton": 27.66,
            "paper_waste_ton": 13.86,
            "glass_waste_ton": 3.86,
            "metal_waste_ton": 2.53,
            "textile_waste_ton": 5.06,
            "other_waste_ton": 7.46,
            "recommended_trucks": 25,
            "risk_status": "SAFE",
            "event_info": null,
            "hourly_breakdown": null
          }
        ],
        "logistics_plan": {
          "trucks_needed": 25,
          "manpower": 75,
          "estimated_duration_hours": 24.1,
          "efficiency_rate": "85% (Optimal)"
        }
      }
    }
    ```

---

### 4. Unduh Berkas CSV Prediksi
Mengunduh berkas tabel data hasil simulasi prediksi.

*   **URL**: `/api/v1/predict/csv`
*   **Method**: `POST`
*   **Request Body**: Sama dengan request `/api/v1/predict`
*   **Response**: Binary Blob (`text/csv` stream file).

---

### 5. Mengambil Peringatan Operasional Dinamis (Alerts)
Mendapatkan peringatan kritis wilayah yang volumenya melebihi ambang batas warning/critical.

*   **URL**: `/api/v1/alerts`
*   **Method**: `GET`
*   **Query Parameters**: `location` (opsional, untuk menyaring satu kecamatan)
*   **Response Schema (`200 OK`)**:
    ```json
    {
      "status": "success",
      "alert_count": 2,
      "alerts": [
        {
          "date": "2026-07-10",
          "location": "Cakung",
          "status": "WARNING",
          "estimated_volume_ton": 435.0,
          "message": "Alert: WARNING volume expected at Cakung"
        }
      ],
      "last_updated": "2026-07-10T20:52:00.123456"
    }
    ```

---

## ⚡ Contoh Integrasi Frontend (Axios / JavaScript)

Berikut adalah contoh cara menarik data prediksi Autopilot dan memuatnya ke komponen halaman FE Anda:

```javascript
import axios from 'axios';

const BACKEND_URL = 'http://localhost:8001';

// 1. Memuat Umpan Berita AI
export async function getWasteNews() {
  try {
    const res = await axios.get(`${BACKEND_URL}/api/v1/news`);
    return res.data; // Mengembalikan array berita
  } catch (error) {
    console.error("Gagal menarik berita sampah:", error);
    return [];
  }
}

// 2. Memuat Data Autopilot Otonom DKI
export async function getAutopilotData() {
  try {
    const res = await axios.get(`${BACKEND_URL}/api/v1/autopilot`);
    return res.data;
  } catch (error) {
    console.error("Gagal memuat autopilot data:", error);
    return null;
  }
}

// 3. Menjalankan Prediksi Manual (Simulation)
export async function postSimulationPrediction(kecamatan, hari = 7, model = 'gradient_boosting') {
  const payload = {
    forecast_days: hari,
    rainfall_mm: 0.0, // Auto
    event_scale: 0,
    location: kecamatan,
    granularity: hari <= 7 ? 'hourly' : 'daily',
    model_type: model
  };

  try {
    const res = await axios.post(`${BACKEND_URL}/api/v1/predict`, payload);
    return res.data;
  } catch (error) {
    console.error("Gagal melakukan prediksi simulasi:", error);
    throw error;
  }
}
```