Elixir untuk Technical Leader — Bab 5 dari 10

Phoenix & LiveView

Web framework yang bikin v1 (React + 31 Edge Functions + 16 RPC) jadi v2 (1 codebase, 0 JavaScript framework). Ini bab paling penting untuk paham arsitektur LabaBersih.

Apa Itu Phoenix

Phoenix = web framework untuk Elixir. Posisinya sama kayak Rails untuk Ruby, atau Next.js untuk JavaScript. Dibuat oleh Chris McCord tahun 2014.

Tapi Phoenix punya 1 senjata yang gak dimiliki Rails atau Next.js: LiveView — teknologi yang bikin UI real-time tanpa perlu React, Vue, atau framework JavaScript apapun.

Kenapa LabaBersih pakai Phoenix:

Arsitektur: v1 vs v2

Ini perbedaan paling fundamental. Pahami ini dan kamu paham kenapa v2 lebih sederhana.

Request Lifecycle — Alur Setiap Permintaan

Ketika user buka halaman atau klik tombol, ini yang terjadi di belakang layar:

Router — Peta URL ke Halaman

Router = peta jalan. "Kalau user buka URL ini, tampilkan halaman ini." File-nya: lib/lababersih_web/router.ex

Ini potongan dari router LabaBersih yang sebenarnya:

# lib/lababersih_web/router.ex (LabaBersih aktual)

scope "/", LababersihWeb do
  pipe_through [:browser, :auth]    # wajib login dulu

  live_session :app,
    layout: {LababersihWeb.Layouts, :app},
    on_mount: [{LababersihWeb.LiveAuth, :require_auth}] do

    # Pesanan
    live "/pesanan",         App.OrderLive          # list semua order
    live "/pesanan/new",     App.OrderFormLive       # form buat order baru
    live "/pesanan/import",  App.OrderImportLive     # upload XLSX
    live "/pesanan/:id",     App.OrderDetailLive     # detail 1 order

    # Produk & Stok
    live "/produk",           App.ProdukLive
    live "/produk/:id",       App.ProdukDetailLive

    # Keuangan
    live "/jurnal",           App.JurnalLive
    live "/bagan-akun",       App.CoaLive
    live "/laporan",          App.LaporanLive
    live "/buku-besar",       App.BukuBesarLive
    live "/rekonsiliasi",     App.RekonsiliasiLive

    # ... dan 20+ route lainnya
  end
end

Cara bacanya sederhana:

Context Pattern — Aturan #1 LabaBersih

Ini konsep PALING PENTING di seluruh arsitektur LabaBersih. Kalau kamu cuma bisa ingat 1 hal dari bab ini, ingat ini:

Apa itu Context?

Context = modul Elixir yang berisi semua logic bisnis untuk 1 domain. Gak ada logic bisnis di tempat lain.

Kenapa ini penting?

# Di OrderFormLive:
def handle_event("ship", _, socket) do
  order = Repo.get!(Order, id)
  if order.status != "dikemas" do   # logic di LiveView!
    # potong stok manual
    # bikin jurnal manual
    # update status manual
  end
end

# Di LiveView: HANYA panggil function
def handle_event("ship", _, socket) do
  case Orders.ship_order(id, email) do
    {:ok, _} -> put_flash(:info, "Berhasil")
    {:error, reason} -> put_flash(:error, ...)
  end
end

# Di Context: SEMUA logic ada di sini
def ship_order(order_id, actor_email) do
  Repo.transaction(fn ->
    # 1. Validasi status
    # 2. Potong stok (FEFO)
    # 3. Bikin jurnal
    # 4. Update status
    # 5. Audit trail
  end)
end

Alur panggilan yang benar:

# ALUR BENAR:
# LiveView → Context → Repo → Database
#
# User klik "Kirim" di browser
#   → LiveView.handle_event("ship", ...)
#     → Orders.ship_order(order_id, email)    ← Context
#       → Repo.transaction (stok + jurnal + audit)
#         → PostgreSQL
#     → {:ok, result} atau {:error, reason}
#   → put_flash(:info, "Berhasil") atau put_flash(:error, "Gagal")
#   → browser update otomatis
#
# LiveView TIDAK TAU cara potong stok.
# LiveView TIDAK TAU cara bikin jurnal.
# LiveView HANYA tau: panggil function, tampilkan hasil.

LiveView — UI Tanpa React

LiveView = cara Phoenix render UI. Gak pakai React, Vue, atau framework JS apapun. Semua HTML di-render di server, dikirim ke browser via WebSocket.

Kenapa ini revolusioner?

Anatomi LiveView — 4 Function Penting

Setiap LiveView module punya 4 function utama. Ini yang kamu akan lihat di SETIAP file LiveView:

1. mount/3 — Load Data Awal

Dipanggil SEKALI saat user pertama kali buka halaman. Tugasnya: ambil data dari Context, simpan ke assigns.

# Dari OrderLive (LabaBersih aktual)
def mount(_params, _session, socket) do
  org_id = socket.assigns.current_org.id          # org user yang login
  {orders, total} = Orders.list_orders(org_id,     # panggil Context
                       page: 1, per_page: 20)
  fulfillment_counts = Orders.count_orders_by_fulfillment(org_id)

  {:ok,
   assign(socket,
     page_title: "Pesanan",
     orders: orders,          # data yang akan ditampilkan
     total: total,
     page: 1,
     search: "",
     fulfillment_counts: fulfillment_counts
   )}
end

2. render/1 — Gambar HTML

Dipanggil SETIAP KALI data berubah. Phoenix otomatis hitung diff dan kirim hanya yang berubah ke browser.

# Dari OrderLive (LabaBersih aktual, disederhanakan)
def render(assigns) do
  ~H"""
  <.page_header title="Pesanan">
    <:action>
      <.button navigate={~p"/pesanan/import"} variant="secondary">
        Upload XLSX
      </.button>
      <.button navigate={~p"/pesanan/new"}>
        + Buat Pesanan
      </.button>
    </:action>
  </.page_header>

  <.stats_row>
    <.stat_card label="Siap Kirim" value={@ready_count} />
    <.stat_card label="Dikirim" value={@shipped_count} />
    <.stat_card label="Terkirim" value={@delivered_count} />
    <.stat_card label="RTS" value={@rts_count} />
  </.stats_row>

  <div :for={o <- @orders}>
    <div phx-click="navigate" phx-value-to={~p"/pesanan/#{o.id}"}>
      {o.id} — {o.customer_name} — <.money amount={o.total_harga} />
    </div>
  </div>
  """
end

3. handle_event/3 — User Klik Sesuatu

Dipanggil saat user interaksi (klik button, submit form, ketik search). Ini jembatan antara UI dan Context.

# User ketik di search bar → event "search" masuk
def handle_event("search", %{"q" => q}, socket) do
  org_id = socket.assigns.current_org.id
  {orders, total} = Orders.list_orders(org_id, q: q)    # panggil Context
  {:noreply, assign(socket, orders: orders, total: total, search: q)}
end

# User klik tab filter "Dikirim" → event "filter_fulfillment"
def handle_event("filter_fulfillment", %{"fulfillment" => f}, socket) do
  # ... panggil Context dengan filter baru, update assigns
end

# User submit form "Buat Pesanan"
def handle_event("save_order", params, socket) do
  case Orders.create_order(attrs, items) do      # panggil Context
    {:ok, order} ->
      {:noreply, socket
        |> put_flash(:info, "Pesanan #{order.id} berhasil dibuat")
        |> push_navigate(to: ~p"/pesanan/#{order.id}")}
    {:error, reason} ->
      {:noreply, put_flash(socket, :error, "Gagal: #{inspect(reason)}")}
  end
end

4. handle_params/2 — URL Berubah

Dipanggil saat URL berubah (navigasi antar halaman dalam live_session). Biasanya untuk halaman detail yang butuh :id dari URL.

# User navigasi ke /pesanan/PS2603-00001
def handle_params(%{"id" => id}, _uri, socket) do
  order = Orders.get_order!(id)                   # panggil Context
  {:noreply, assign(socket, order: order)}
end

HEEx Templates — HTML di Elixir

HEEx = HTML + Embedded Elixir. Ini template engine Phoenix. Kamu nulis HTML biasa tapi bisa sisipkan data Elixir.

Syntax penting yang akan kamu lihat:

Contoh nyata dari LabaBersih:

<!-- Tampilkan order row (dari OrderLive) -->
<div
  :for={o <- @orders}
  phx-click="navigate"
  phx-value-to={~p"/pesanan/#{o.id}"}
  class="hover:bg-gray-50 cursor-pointer"
>
  <!-- ID pesanan -->
  <div class="font-mono text-sm">{o.id}</div>

  <!-- Nomor platform + resi (hanya tampil kalau ada) -->
  <div class="text-xs text-gray-400">
    {o.nomor_pesanan}
    <span :if={o.no_resi}> · {o.no_resi}</span>
  </div>

  <!-- Customer -->
  <div>{o.customer_name}</div>

  <!-- Platform badge (shared component) -->
  <.platform_badge platform={o.platform} />

  <!-- Status badge (shared component) -->
  <.status_badge status={o.fulfillment_status} />

  <!-- Revenue (shared component) -->
  <.money amount={o.total_harga} />
</div>

Components — UI yang Bisa Dipakai Ulang

LabaBersih punya CoreComponents — kumpulan komponen UI yang dipakai di SEMUA halaman. Ini yang bikin tampilan konsisten (beda dari v1 yang badge-nya beda style tiap halaman).

Semua ada di 1 file: lib/lababersih_web/components/core_components.ex

Contoh component definition:

# Di core_components.ex
def status_badge(assigns) do
  {bg, text} = Map.get(@badge_colors, assigns.status, {"#E2E7E5", "#3D4B46"})
  assigns = assign(assigns, bg: bg, text: text)

  ~H"""
  <span style={"display:inline-flex;padding:4px 10px;border-radius:999px;
    font-size:13px;font-weight:600;background:#{@bg};color:#{@text};"}>
    {status_label(@status)}
  </span>
  """
end

# status_label mengubah kode teknis ke bahasa Indonesia:
# "shipped" → "Dikirim"
# "delivered" → "Terkirim"
# "rts_detected" → "RTS Terdeteksi"

Flash Messages — Notifikasi ke User

Flash = pesan sementara yang muncul di atas halaman setelah aksi (berhasil/gagal). Di v1 ini pakai toast library. Di v2 built-in.

# Berhasil (hijau)
socket |> put_flash(:info, "Pesanan PS2603-00001 berhasil dibuat")

# Gagal (merah)
socket |> put_flash(:error, "Stok Forbest tidak cukup (ada: 3, butuh: 5)")

# Contoh di handle_event:
case Orders.create_order(attrs, items) do
  {:ok, order} ->
    socket
    |> put_flash(:info, "Pesanan #{order.id} berhasil dibuat")
    |> push_navigate(to: ~p"/pesanan/#{order.id}")
  {:error, reason} ->
    put_flash(socket, :error, "Gagal: #{inspect(reason)}")
end

Assigns (@) — State LiveView

Assigns = data yang tersimpan di LiveView process. Setiap kali assigns berubah, Phoenix otomatis re-render bagian HTML yang pakai data itu.

# Di mount:
assign(socket,
  orders: orders,            # → akses via @orders di template
  page: 1,                   # → @page
  search: "",                # → @search
  fulfillment_counts: counts  # → @fulfillment_counts
)

# Di template:
# {@orders}   → list of order data
# {@page}     → halaman saat ini (1, 2, 3, ...)
# {@search}   → teks yang diketik user di search bar

# Update assigns (misalnya user pindah halaman):
assign(socket, page: 2, orders: new_orders)
# → @page berubah jadi 2
# → @orders berubah jadi data baru
# → Phoenix re-render HANYA bagian yang pakai @page dan @orders

phx- Attributes — Event dari Browser ke Server

Ini yang bikin LiveView interaktif tanpa JavaScript custom. Tambahkan phx-xxx di HTML, dan LiveView otomatis handle.

Contoh nyata — form pesanan LabaBersih:

<!-- Form buat pesanan baru -->
<form phx-submit="save_order">                     <!-- submit → server -->
  <.input name="customer_name" label="Customer" required />
  <.input name="platform" type="select"
    options={[{"TikTok", "tiktok"}, {"Shopee", "shopee"}]} />

  <!-- Tombol tambah item -->
  <.button type="button" phx-click="add_item">     <!-- klik → server -->
    + Tambah item
  </.button>

  <!-- Tombol simpan -->
  <.button type="submit"
    phx-disable-with="Menyimpan...">                <!-- disable saat proses -->
    Simpan
  </.button>
</form>

Setiap phx-click="add_item" di template akan memanggil function ini di LiveView:

def handle_event("add_item", _, socket) do
  items = socket.assigns.items ++ [%{product_id: "", quantity: 1, price: 0}]
  {:noreply, assign(socket, items: items)}
end
# → items bertambah 1 → template re-render → 1 row baru muncul di browser
# Gak ada JavaScript. Gak ada API call. Gak ada useState.

WebSocket vs HTTP — Kenapa LiveView Cepat

Ini perbedaan teknis yang menjelaskan kenapa v2 terasa lebih responsif:

1. Browser buka koneksi TCP     ~50ms
2. TLS handshake               ~100ms
3. Kirim HTTP request           ~10ms
4. Server proses dari NOL       ~100ms
5. Kirim SELURUH HTML/JSON      ~50ms
6. Tutup koneksi
   ──────────────
   Total: ~310ms PER KLIK

1. Koneksi sudah TERBUKA        0ms
2. Kirim event kecil            ~5ms
3. Server proses (state ada)    ~50ms
4. Kirim HANYA yang berubah     ~10ms
5. Koneksi tetap terbuka
   ──────────────
   Total: ~65ms PER KLIK

5x lebih cepat. Dan itu belum hitung keuntungan lain: server ingat state user (assigns), jadi gak perlu query ulang semua data dari nol.

Checklist Review untuk Leader

Setiap kali kamu review code LiveView yang dibuat Claude, cek hal-hal ini:

Red Flags — Hal yang WAJIB Ditolak

Struktur File — Di Mana Semuanya

# Semua file web (LiveView, Components, Router) ada di:
lib/lababersih_web/
  router.ex                          # peta URL → halaman
  components/
    core_components.ex               # <.button>, <.status_badge>, dll
    layouts/
      app.html.heex                  # layout dengan sidebar
      root.html.heex                 # layout dasar (HTML head)
  live/
    app/
      order_live.ex                  # list pesanan
      order_detail_live.ex           # detail 1 pesanan
      order_form_live.ex             # form buat pesanan
      produk_live.ex                 # list produk
      jurnal_live.ex                 # list jurnal
      coa_live.ex                    # bagan akun (tree)
      laporan_live.ex                # laporan keuangan
      buku_besar_live.ex             # general ledger
      settings_live.ex               # pengaturan
      # ... 30+ file lainnya

# Semua business logic (Context) ada di:
lib/lababersih/
  orders/orders.ex                   # Context: pesanan
  accounting/accounting.ex           # Context: jurnal, laporan
  inventory/inventory.ex             # Context: produk, stok
  # ... dst

Pertanyaan Review yang Bisa Kamu Tanya

Ringkasan Bab 5