merica/docs/user_guide.md

# 🎨 Panduan Penggunaan Pengguna (User Guide) — MERICA

> **Navigasi Cepat**: [🏠 Pusat Dokumentasi](index.md) | [🏛️ Arsitektur Platform](architecture.md) | [📦 Panduan Deployment](deployment_guide.md) | [📘 Integrasi Airflow External](panduan_integrasi_existing_airflow.md)

Panduan komprehensif bagi **Data Engineer, Analytics Engineer, dan Data Architect** dalam menggunakan antarmuka grafis **MERICA Canvas** untuk merancang, mengonfigurasi, menguji (*Shift-Left Testing*), dan menyusun task DAG Apache Airflow 3 secara deklaratif.

> [!NOTE]
> **Fokus Peran MERICA**: MERICA dirancang murni sebagai **Visual Low-Code DAG Builder** untuk mempercepat rancang bangun pipeline data lakehouse modern tanpa menulis boilerplate Python manual. MERICA bukan dashboard monitoring runtime; pemantauan eksekusi, log task, retry, dan alerting tetap didelegasikan sepenuhnya ke antarmuka resmi **Apache Airflow 3**.

---

## 🖥️ 1. Mengakses Antarmuka Web MERICA Canvas

Buka peramban (*web browser*) modern (Google Chrome, Mozilla Firefox, Microsoft Edge) dan akses URL:
```text
http://<ip-server-merica>:14000
```
* **Kredensial Default**:
  * **Username**: `admin`
  * **Password**: `admin`

### Tampilan Awal: Pipelines Explorer (Anti-Blank Canvas)
Setelah masuk, Anda akan langsung disajikan halaman **Pipelines Explorer**. MERICA dilengkapi fitur *Anti-Blank Canvas* dengan 3 pipeline produksi siap pakai:
1. `e2e_modernized_ingestion_flow`: Pipeline ingestion modern yang menggabungkan Database CDC Sling, Google Spreadsheet Auto-Cleansing, dan dlt REST API.
2. `e2e_medallion_permits_flow`: Pipeline perizinan Medallion (Bronze Parquet $\to$ Silver Iceberg $\to$ Gold dbt Mart).
3. `e2e_orders_master_medallion_flow`: Pipeline master order e-commerce dengan deduplikasi DuckDB dan quality gate Great Expectations.

Anda dapat langsung mengklik salah satu pipeline untuk membukanya di Canvas, atau mengklik tombol **`+ New Pipeline`** di kanan atas untuk membuat pipeline baru dari awal.

---

## 🧩 2. Katalog Komponen & Operator Lakehouse

Panel kiri kanvas (*Component Catalog*) menyediakan pustaka node terstandarisasi untuk arsitektur Medallion Lakehouse:

```mermaid
graph LR
    subgraph SOURCES ["1. Ingestion Sources (Bronze)"]
        N_DB["Database CDC (Sling)"]
        N_GWS["Google Workspace (Drive/Sheet)"]
        N_REST["REST API (dlt Ingestor)"]
    end

    subgraph SINK ["2. Lakehouse Storage (Silver)"]
        N_BRONZE["Bronze S3 Parquet"]
        N_SILVER["Silver Iceberg + DuckDB Dedup"]
    end

    subgraph TRANS ["3. Transformation (Gold)"]
        N_DBT["dbt Medallion Model (Cosmos)"]
        N_GE["Great Expectations Quality Gate"]
    end

    SOURCES --> SINK --> TRANS
```

---

### A. Database Ingestor (Sling CDC + Introspection & Safe Preview)
Digunakan untuk mengekstraksi data transaksional dari PostgreSQL, MySQL, SQL Server, atau Oracle:
* **Log-Based CDC**: Ekstraksi berbasis log transaksi untuk meminimalkan beban CPU pada database produksi.
* **Database Introspection Otomatis**: Saat memilih koneksi dan tabel target, MERICA secara otomatis menginspeksi metadata skema tabel dari PostgreSQL.
* **Auto-Detect Primary Key & Watermark**: Kolom kunci utama (*Primary Key*) dan kolom jejak waktu (*timestamp watermark*) terdeteksi otomatis untuk kebutuhan inkremental.
* **Safe 10-Row Data Preview**: Tombol **`Preview Data`** menampilkan 10 baris data sampel secara aman (dengan statement timeout terkendali) langsung di panel konfigurasi tanpa mengunci tabel produksi.

---

### B. Google Workspace Ingestor (Drive Folder Explorer & Header Auto-Cleansing)
Digunakan untuk mengonsumsi spreadsheet Google Sheets dari Google Drive organisasi:
* **Drive Folder Explorer**: Antarmuka visual untuk menelusuri folder dan memilih berkas Spreadsheet secara interaktif (`/api/v1/discovery/gws/folders`).
* **Dynamic Tab Resolution**: Mendukung pemilihan tab berbasis indeks (`sheet_index: 0`) atau pencocokan nama regex dinamis.
* **Header Row Suggestion**: Menganalisis baris-baris awal spreadsheet dan merekomendasikan baris mana yang merupakan baris nama kolom aktual (*Header Row*).
* **Auto-Cleansing Engine**:
  * Otomatis mengubah nama kolom menjadi format `snake_case` dan membuang spasi tersembunyi.
  * Mengeliminasi sufiks unit teks pada data numerik (misal: `"1.500.000 (Rp)"` $\to$ `1500000`).
  * Menerapkan pengisian sel yang digabungkan (*Forward-Fill merged cells* / `ffill`).

---

### C. REST API Ingestor (dlt Framework)
Digunakan untuk mengambil data dari sensor IoT (seperti sensor udara SPKU) atau REST API pihak ketiga:
* **Declarative Pagination**: Mendukung strategi paginasi standar: *Page Number*, *Offset/Limit*, dan *Cursor/Next-URL Link*.
* **Automated Flattening & Unnesting**: Respon JSON bertingkat (*nested payloads*) otomatis diurai (*unnested*) menjadi skema tabel tabular relasional di Bronze S3 Parquet.
* **Sliding Lookback Window**: Mendukung jendela pengambilan mundur (misal `now() - 3 hours` s/d `now()`) untuk mencegah *data gap* akibat keterlambatan transmisi sensor.

---

### D. Silver Lakehouse Sink (Apache Iceberg + DuckDB Deduplication)
* **ACID Iceberg Table**: Menulis data ke partisi Silver menggunakan format Apache Iceberg dengan metadata snapshot time-travel.
* **Idempotent Deduplication via DuckDB**: Mencegah duplikasi data pada proses *incremental reload* menggunakan formula SQL terstandarisasi:
  ```sql
  ROW_NUMBER() OVER (PARTITION BY primary_key ORDER BY updated_at DESC) = 1
  ```

---

### E. dbt Medallion Transformator (Astronomer Cosmos + Shift-Left Testing)
Digunakan untuk menyusun transformasi bisnis dari Silver ke Gold Mart:
* **Otomasi Model SQL**: Menulis query transformasi bisnis (misal: aggregasi bulanan, join master data) langsung di editor SQL kanvas.
* **Smart DDL Data Type Inference**: Engine MERICA secara otomatis menginferensi tipe data kolom target (`INTEGER`, `DECIMAL(18,2)`, `TIMESTAMP`, `VARCHAR`) berdasarkan ekspresi SQL yang ditulis.
* **Shift-Left Quality Testing**: Anda dapat menentukan aturan validasi langsung di kanvas:
  * `contract: enforced`: Menjamin struktur kolom tabel tidak boleh melenceng dari skema yang disepakati.
  * Constraint kolom bawaan: `unique`, `not_null`, dan `accepted_values: [...]`.
* **Astronomer Cosmos Granular TaskGroup**: Di Airflow 3, model dbt tidak dieksekusi sebagai satu task raksasa buram (*black-box*), melainkan dipecah menjadi task granular:
  * `model_name.run`: Menjalankan kompilasi dan pembuatan tabel SQL.
  * `model_name.test`: Menjalankan pengujian kualitas data segera setelah model selesai (`TestBehavior.AFTER_EACH`).

---

### F. Great Expectations Quality Gate
Node validasi batasan fisik data (*Data Sanity Rules*):
* Menguji batas kewajaran data (misal: konsentrasi PM2.5 sensor harus berada pada rentang $0 \le x \le 500$; jika di luar rentang, ditandai atau dikonversi menjadi `NULL`).
* Menguji persentase ambang batas nilai kosong (*Null Percentage Threshold*).

---

## 🛠️ 3. Alur Kerja Perancangan Pipeline di Canvas (Langkah-demi-Langkah)

```mermaid
flowchart TD
    S1["1. Tarik Node dari Katalog ke Kanvas\n(Drag & Drop)"] --> S2["2. Hubungkan Output Port ke Input Port\n(Edge Linking)"]
    S2 --> S3["3. Konfigurasi Parameter di Panel Kanan\n(Drawer Configuration)"]
    S3 --> S4["4. Validasi Pra-Kompilasi\n(Shift-Left Pre-Flight Check: #val)"]
    S4 --> S5["5. Deploy Pipeline ke Airflow 3\n(GitOps Hot-Reload dalam 30 Detik)"]
```

### Langkah 1: Drag & Drop Node
Pilih komponen sumber dari panel katalog kiri (misal: **Database CDC**), lalu tarik (*drag*) ke kanvas tengah. Tambahkan node pemrosesan (misal: **Silver Iceberg Sink**) dan node transformasi (**dbt Medallion Model**).

### Langkah 2: Menghubungkan Port (Edge Linking)
Klik titik lingkaran (*handle port*) output pada node sumber, lalu tarik garis konektor ke titik input pada node tujuan. Hubungan antar-node ini akan diterjemahkan menjadi dependensi upstream/downstream (`>>`) pada DAG Airflow.

### Langkah 3: Konfigurasi Parameter (Drawer Panel)
Klik pada node di kanvas untuk membuka laci konfigurasi di sebelah kanan:
* **Pada Database CDC**: Pilih koneksi database, klik nama tabel, amati deteksi otomatis Primary Key, dan klik **Preview Data** untuk memverifikasi 10 baris sampel.
* **Pada Google Workspace**: Jelajahi folder Google Drive, pilih sheet, dan periksa saran baris header.
* **Pada dbt Model**: Tulis query SQL, tambahkan aturan contract quality (`unique`, `not_null`).

### Langkah 4: Validasi Pra-Kompilasi (*Shift-Left Pre-Flight Check*)
Klik tombol **`Validate Pipeline`** di toolbar atas.
Backend FastAPI akan memverifikasi:
* Ketiadaan siklus (*cycle detection* / validasi DAG acyclic).
* Kesesuaian tipe data dan parameter wajib pada setiap node.
* Validitas model dbt dan kesiapan kontrak schema YAML.
Jika terdapat kesalahan konfigurasi, pesan perbaikan spesifik akan langsung muncul di kanvas sebelum pipeline sempat di-deploy ke server.

### Langkah 5: Simpan & Deploy Pipeline (*Zero Downtime GitOps*)
Klik tombol **`Deploy Pipeline`**:
1. MERICA mengompilasi desain kanvas ke dalam berkas kontrak deklaratif YAML (`configs/<pipeline_id>.yaml`) dan model SQL dbt (`dbt/models/...`).
2. Berkas disimpan langsung ke repositori pipeline SSOT (`merica-pipelines.git` atau direktori ter-mount `./pipelines/`).
3. Apache Airflow 3 AIP-66 Git DAG Processor mendeteksi pembaruan dan secara otomatis memuat ulang DAG ke Airflow MetaDB dalam waktu **$\le 30$ detik tanpa perlu restart Airflow**.

---

## ⚙️ 4. Pemantauan & Eksekusi di Apache Airflow 3

Setelah pipeline di-deploy dari MERICA Canvas:
1. Akses dashboard resmi Apache Airflow 3 pada URL:
   ```text
   http://<ip-server-airflow>:14080
   ```
2. Temukan DAG yang bersangkutan pada daftar DAG (nama DAG sesuai dengan ID yang Anda tentukan di kanvas).
3. **Tampilan Granular Astronomer Cosmos**:
   * Buka tampilan **Graph View** atau **Grid View**.
   * Anda dapat melihat TaskGroup dbt terbagi rapi menjadi task `.run` dan task `.test`.
   * Jika ada uji kontrak kolom yang gagal, task `.test` akan berwarna merah (*Failed*), menghentikan pipeline sebelum data rusak masuk ke Gold layer (*Data Quality Circuit Breaker*).
4. Klik pada task untuk membaca log eksekusi, melihat waktu eksekusi task, atau memicu eksekusi ulang (*Clear / Retry*).

---

## 🏛️ 5. Integrasi Tata Kelola Data OpenMetadata 2.0

Setiap kali Anda menekan tombol **Deploy Pipeline** di MERICA Canvas, sistem secara otomatis menyinkronkan aset ke portal **OpenMetadata 2.0**:
* **Pipeline Entity**: Pipeline terdaftar di bawah `dlh_airflow_service` lengkap dengan deskripsi, jadwal cron, dan daftar task.
* **Schema & Real Column Types**: Struktur kolom dari Bronze, Silver, dan Gold terdaftar di katalog data dengan tipe data presisi.
* **Sample Data 5 Baris**: Sampel baris aktual dari PostgreSQL tersimpan pada tab Sample Data OpenMetadata.
* **SQL Query Lineage**: Query transformasi dbt disematkan pada tab Queries tabel yang bersangkutan.
* **Data Quality Assertions**: Seluruh rule Great Expectations terhubung langsung ke tab **Data Quality** OpenMetadata, menampilkan riwayat persentase kelulusan data dari waktu ke waktu.

---

## 🧭 Navigasi Dokumen Terkait

* Pahami Rancang Bangun: [🏛️ Arsitektur Platform](architecture.md)
* Cara Install Appliance: [📦 Panduan Deployment & Build](deployment_guide.md)
* Menyiapkan Sisi Airflow: [📘 Panduan Integrasi Airflow External](panduan_integrasi_existing_airflow.md)
* Kembali ke Indeks: [🏠 Pusat Dokumentasi](index.md)