Spesifikasi teknis modul Decision Simulation (/app/simulasi atau /dashboard/simulation), pemodelan skenario krisis (What-If Policy Sandbox), penautan peristiwa empiris via Elasticsearch, inferensi kausalitas LLM (POST /ai/simulate), dan persistensi PostgreSQL simulation_runs.

simulation`)

Modul Decision Simulation menyediakan lingkungan sandbox pengujian kebijakan dan pemodelan skenario krisis (What-If Analysis Sandbox) bagi pengambil keputusan strategis untuk memproyeksikan deviasi indikator nasional, efek domino lintas sektor (Cascading Impact), serta sebaran risiko geospasial ke 38 provinsi di Indonesia.

Interactive On-Demand AI Service

Modul ini tidak memerlukan background pipeline ETL atau worker streaming tersendiri. Modul ini bekerja secara interaktif on-demand: melakukan pencarian teks ke indeks Elasticsearch articles eksisting sebagai pijakan bukti empiris, mengeksekusi inferensi kausalitas melalui panggilan API ke model AI (POST /ai/simulate), dan mencatat riwayat hasil simulasi ke tabel PostgreSQL simulation_runs.

1. Arsitektur Alur Interaktif End-to-End

              [Pengguna Menentukan Skenario, Intensitas, Wilayah & Durasi]
                                           │
                                           ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ TAHAP 1: PENAUTAN PERISTIWA NYATA (SCENARIO EVENT GROUNDING)                            │
│                                                                                         │
│   Frontend Request: GET /scrape/scenario-events?scenario={key}&region={region}          │
│                                          │                                              │
│                                          ▼                                              │
│               [Elasticsearch Service: Multi-Match BM25 Query]                           │
│                 • Filter: date range (30 hari terakhir)                                 │
│                 • Match: scenario taxonomy keywords & region                            │
│                 • Sort: relevancy score & published_at DESC                             │
│                                          │                                              │
│                                          ▼                                              │
│               [Daftar Berita Empiris Terkait Disajikan di UI]                           │
│               (Pengguna memilih 1 atau beberapa peristiwa kunci sebagai pijakan)        │
└──────────────────────────────────────────┬──────────────────────────────────────────────┘
                                           │
                                           ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ TAHAP 2: EKSEKUSI PENALARAN KAUSALITAS AI (CAUSAL INFERENCE ENGINE)                     │
│                                                                                         │
│   Frontend Request: POST /ai/simulate                                                   │
│     Payload: scenario, severity, region, duration, detail_note, basis_events            │
│                                          │                                              │
│                                          ▼                                              │
│               [Retrieval Baseline Indikator Makro dari PostgreSQL]                      │
│                 • Tabel fact_indicator (IPH, PDRB, Rasio Faskes, dsb.)                  │
│                                          │                                              │
│                                          ▼                                              │
│               [AI Causal Engine / AI-Middleware (Gemini 1.5 Pro / Flash)]               │
│                 • Reasoning Multi-Step:                                                 │
│                     1. Causal Chain Modeling (Penyebab -> Efek Primer -> Sekunder)      │
│                     2. Indicator Deviation (Before vs After)                            │
│                     3. Cascading Impact Matrix (A -> B -> Efek)                         │
│                     4. Geospatial Scoring (Dampak ke 38 Provinsi)                       │
│                     5. Actionable Mitigation Roadmap                                    │
└──────────────────────────────────────────┬──────────────────────────────────────────────┘
                                           │
                                           ▼
┌─────────────────────────────────────────────────────────────────────────────────────────┐
│ TAHAP 3: PERSISTENSI HASIL & VISUALISASI UI                                             │
│                                                                                         │
│   1. Simpan Sesi Simulasi ke PostgreSQL: simulation_runs                                │
│   2. Render Hasil Interaktif di Frontend:                                               │
│       • KPI Delta Indikator Nasional (Trending Up / Down)                               │
│       • Rantai Dampak Berjenjang (Interactive Cascade Diagram)                          │
│       • Peta Interaktif Leaflet (Circle Marker & Skala Warna Keparahan)                  │
│       • Tabel Pemetaan Provinsi Terdampak                                               │
└─────────────────────────────────────────────────────────────────────────────────────────┘

2. Tabel Pemetaan Komponen ke PostgreSQL & Elasticsearch

Komponen / Bagian UI	Endpoint API Backend	Elasticsearch (Indeks & Field)	PostgreSQL (Tabel & Kolom)	Alur Event & Pemrosesan
Pemilihan Skenario & Bukti Berita	`GET /scrape/scenario-events`	`articles` ↳ `title`, `content`, `summary`, `published_at`	—	Pencarian teks BM25 filter 30 hari terakhir.
Baseline Indikator Makro	—	—	`fact_indicator` ↳ `indicator_type`, `value`, `region_id`	Menjadi nilai awal sebelum terjadinya guncangan krisis.
Eksekusi Simulasi Kausalitas	`POST /ai/simulate`	—	—	Mengirim parameter & konteks berita ke AI Middleware (Gemini LLM).
Riwayat Sesi Simulasi	`GET /ai/simulations/history` `GET /ai/simulations/:id`	—	`simulation_runs` ↳ `scenario`, `severity_level`, `region`, `duration`, `result_json`	Snapshot permanen hasil pengujian untuk audit dan perbandingan.

3. Matriks Skenario Simulasi & Taksonomi Entitas Kritis

Simulator mendukung 7 kelompok skenario utama yang dapat dikombinasikan dengan tingkat keparahan (Ringan, Sedang, Berat, Kritis) dan durasi waktu (6 jam s.d. 1 bulan):

Kelompok	Kunci Skenario	Entitas Terdampak / Fokus Simulasi
Bencana Alam	`banjir`, `gempa`	Mobilitas logistik darat, evakuasi warga, jaringan sanitasi, kesiapan faskes.
Infrastruktur & Energi	`infrastruktur`, `listrik`, `komunikasi`, `jalan`	Gardu induk, BTS telekomunikasi, jalur arteri logistik, keandalan server perbankan.
Logistik & Distribusi	`pelabuhan`, `bandara`, `bbm`, `komoditas`	Arus peti kemas, rantai dingin pangan, ketersediaan solar subsidi, stok beras.
Pangan & Kesehatan	`pangan`, `rs`	Kapasitas bed isolasi RS, deviasi harga HET sembako, stabilitas pasar induk.
Keamanan & Siber	`siber`	Pusat data nasional, gateway pembayaran digital, kebocoran data pribadi (UU PDP).
Kebijakan & Ekonomi	`kebijakan`, `investasi`	Regulasi tarif, subsidi silang, daya beli UMKM, kepastian hukum investasi.
Kustom	`kustom`	Skenario multi-krisis gabungan yang didefinisikan bebas oleh analis.

4. Tahap 1: Pencarian Peristiwa Nyata (`GET /scrape/scenario-events`)

Saat pengguna memilih skenario (misal: bbm) dan wilayah (misal: Sumatera Selatan), backend mengeksekusi pencarian teks penuh terarah ke Elasticsearch:

{
  "query": {
    "bool": {
      "must": [
        {
          "multi_match": {
            "query": "solar subsidi antrean SPBU kelangkaan BBM pasokan logistik",
            "fields": ["title^3", "content", "summary^2"],
            "fuzziness": "AUTO"
          }
        }
      ],
      "filter": [
        { "range": { "published_at": { "gte": "now-30d/d" } } },
        { "term": { "location_province.keyword": "Sumatera Selatan" } }
      ]
    }
  },
  "size": 15,
  "sort": [{ "_score": { "order": "desc" } }, { "published_at": { "order": "desc" } }]
}

Hasil pencarian ini disajikan di antarmuka agar analis dapat mencentang berita yang benar-benar menjadi pijakan asumsi simulasi.

5. Tahap 2: Mesin Inferensi Kausalitas LLM (`POST /ai/simulate`)

A. Payload Permintaan (Request Payload)

{
  "scenario": "bbm",
  "scenario_label": "Kelangkaan BBM",
  "scenario_desc": "Kekurangan bahan bakar yang mengganggu logistik dan transportasi.",
  "severity_level": "Berat",
  "region": "Sumatera Selatan",
  "duration": "1 minggu",
  "detail_note": "Asumsikan antrean armada logistik sembako tertahan lebih dari 48 jam di lintas timur.",
  "basis_events": [
    {
      "title": "Antrean Truk di SPBU Jalur Lintas Palembang Mengular Hingga 2 Km",
      "source": "Tribun Sumsel",
      "date": "2026-10-05T08:00:00Z"
    }
  ]
}

B. Prompt Engineering & Causal Reasoning Guardrails

Model AI diinstruksikan bertindak sebagai National Crisis Simulation Specialist:

Aturan Konsistensi Numerik: Perubahan indikator (after - before) harus proporsional terhadap parameter keparahan dan durasi.
Efek Domino Logis (Cascade Effect): Rantai dampak wajib mencerminkan hubungan sebab-akibat antar-sektor (misal: Transportasi → Distribusi Sembako → Inflasi Eceran → Potensi Gesekan Kamtibmas).
Penyebaran Geospasial: Dampak tidak boleh hanya bernilai pada provinsi target, melainkan merembet ke provinsi penyangga (buffer provinces) dengan skor yang meluruh seiring jarak geografis.

6. Skema Luaran Hasil Simulasi (Output Schema)

{
  "simulation_id": "SIM-179654890123",
  "result": {
    "summary": "Gangguan pasokan solar subsidi selama 1 minggu di Sumatera Selatan berpotensi menahan 42% armada angkutan pangan regional, memicu deviasi inflasi pangan lokal hingga +1.4% dan risiko antrean kamtibmas di 8 titik lintas timur.",
    "timeline_note": "Eskalasi tertinggi diproyeksikan pada hari ke-3 hingga ke-5 sebelum distribusi cadangan penyangga tiba.",
    "confidence": 88,
    "indicators": [
      {
        "name": "Kelancaran Distribusi Logistik",
        "before": 85.0,
        "after": 48.5,
        "unit": "skor",
        "direction": "bad"
      },
      {
        "name": "Indeks Harga Pangan Pokok",
        "before": 102.3,
        "after": 114.7,
        "unit": "poin",
        "direction": "bad"
      },
      {
        "name": "Indeks Stabilitas Kamtibmas",
        "before": 90.0,
        "after": 72.0,
        "unit": "skor",
        "direction": "bad"
      }
    ],
    "risiko_utama": [
      "Keterlambatan pasokan komoditas sayur dan telur ke pasar induk Palembang dan sekitarnya.",
      "Potensi gesekan fisik antrean pengemudi truk di simpul SPBU lintas batas provinsi.",
      "Aksi penimbunan solar bersubsidi oleh oknum spekulan daerah."
    ],
    "mitigasi": [
      "Instruksikan Pertamina Patra Niaga menambah alokasi harian solar mobile storage sebesar 35% di 12 SPBU kantong.",
      "Kerahkan personel kepolisian untuk pengamanan antrean dan pengaturan jalur prioritas truk sembako.",
      "Buka posko koordinasi terpadu pemda bersama asosiasi logistik untuk pemantauan ketersediaan pangan 24 jam."
    ],
    "cascade": [
      { "from": "Kelangkaan BBM Solar", "to": "Kemacetan Jalur Lintas", "effect": "Truk ekspedisi tertahan di bahu jalan lintas timur" },
      { "from": "Kemacetan Jalur Lintas", "to": "Keterlambatan Bahan Pangan", "effect": "Kerusakan komoditas sayuran segar & penurunan mutu pangan" },
      { "from": "Keterlambatan Bahan Pangan", "to": "Kenaikan Harga Pasar", "effect": "Pedagang menaikkan harga eceran hingga 15-20%" }
    ],
    "regional": [
      { "province": "Sumatera Selatan", "score": -78, "note": "Episentrum krisis; antrean kritis di jalur lintas Palembang-Betung" },
      { "province": "Lampung", "score": -52, "note": "Dampak imbas antrean penyeberangan Bakauheni dan pasokan balik" },
      { "province": "Jambi", "score": -44, "note": "Keterlambatan pasokan sembako yang melintasi jalur Sumatera Bagian Selatan" },
      { "province": "Bengkulu", "score": -31, "note": "Hambatan jalur distribusi logistik lintas pegunungan tengah" },
      { "province": "DKI Jakarta", "score": -18, "note": "Keterlambatan minor pasokan hortikultura asal Sumatera" }
    ]
  }
}

7. Skema Penyimpanan Database (PostgreSQL & Elasticsearch)

A. Tabel PostgreSQL: `simulation_runs`

CREATE TABLE IF NOT EXISTS simulation_runs (
    id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id uuid REFERENCES users(id) ON DELETE SET NULL,
    scenario varchar(100) NOT NULL,
    severity_level varchar(50) NOT NULL,
    region varchar(100) NOT NULL,
    duration varchar(50) NOT NULL,
    detail_note text,
    basis_events jsonb DEFAULT '[]'::jsonb,
    result_json jsonb NOT NULL,
    confidence real NOT NULL,
    executed_at timestamptz DEFAULT now(),
    created_at timestamptz DEFAULT now()
);

CREATE INDEX IF NOT EXISTS sim_scenario_idx ON simulation_runs (scenario);
CREATE INDEX IF NOT EXISTS sim_region_idx ON simulation_runs (region);
CREATE INDEX IF NOT EXISTS sim_executed_at_idx ON simulation_runs (executed_at);

B. Indeks Elasticsearch: `articles` (Konfigurasi Pencarian Bukti)

title: Field teks diindeks dengan analyzer indonesian dan keyword standard.
content / summary: Pencarian semantik konten berita pendukung.
location_province: Filter mutlak kesesuaian wilayah geografis kejadian.
published_at: Filter rentang waktu 30 hari terakhir guna menjamin aktualitas peristiwa.

8. Penanganan Galat & Edge Cases

Ketiadaan Berita Nyata Terkait Skenario di Wilayah Tertentu:
- Jika query Elasticsearch tidak menemukan berita lokal (misal: Skenario Gempa Bumi di Kalimantan Barat), UI menampilkan pesan bahwa peristiwa nyata nihil di database, namun pengguna tetap diizinkan menjalankan simulasi murni hipotetis tanpa menyertakan basis_events.
Skenario Kustom Tanpa Deskripsi:
- Validasi sisi klien dan server menolak eksekusi kustom jika kolom deskripsi kosong untuk mencegah inferensi terbuka tak terkendali (Unbounded Prompt Execution).
Format Respons AI Tidak Valid (Malformed JSON):
- AI Middleware dilengkapi JSON Schema Validator & Repairer. Jika LLM memutus respons sebelum tanda kurung siku/kurawal penutup, parser otomatis melakukan perbaikan struktur sebelum diteruskan ke frontend.

Decision Simulation

On this page