open-isp/docs/ANALISIS_SISTEM_DAN_UIUX.md

Analisis Komprehensif Sistem, Logika Backend, dan UI/UX — Billing RT/RW Net

Target Project: /opt/billing-rtrw (VPS deneva — 116.212.74.115)
Layanan: billing-rtrw.service (Node.js v20+, port 3001)
Repository Asal: https://github.com/alijayanet/billing-rtrw
Repository Fork/Deploy: https://github.com/alijayanet/billing-rtrw

---

1. Ringkasan Eksekutif & Gambaran Sistem

Billing RT/RW Net ini adalah sistem manajemen operasional ISP (Internet Service Provider) berbasis komunitas yang memadukan:

1. Billing & Invoicing: Siklus tagihan bulanan, isolir otomatis, dan pembayaran QRIS dinamis/manual.
2. Network Automation: Integrasi RouterOS MikroTik (PPPoE, Hotspot Voucher, Simple Queue, Address List).
3. Hardware Management (FTTH): Embedded ACS TR-069 Server (CWMP) untuk manajemen ONT klien dan SNMP OLT (EPON/GPON).
4. Customer Self-Service (PWA): Portal pelanggan mobile-first dengan auto-login 90 hari, ganti WiFi SSID/password mandiri, grafik pemakaian kuota/bandwidth, dan reboot modem.
5. Multi-Channel Bot: Bot WhatsApp (Baileys socket) dan Bot Telegram untuk notifikasi, penagihan, dan tiket operasional.

flowchart TD
    subgraph Klien_Pelanggan["Portal Klien & Interaksi"]
        CustPWA["Customer PWA (Tailwind + Lucide)"]
        PublicVoucher["Portal Voucher & QRIS"]
        WABot["WhatsApp Bot (Baileys)"]
        TeleBot["Telegram Bot Notifikasi"]
    end

    subgraph Core_Backend["Express 4 Engine (Port 3001)"]
        App["app-customer.js (Main Entry)"]
        ACSServer["Embedded TR-069 Server (/acs)"]
        AuthSvc["Auth & Token Service (90 Hari)"]
        BillSvc["Billing & Invoice Engine"]
        MikroSvc["MikroTik RouterOS API"]
        OLTSvc["OLT Service (SNMP / Web)"]
        UsageSvc["Bandwidth Usage Tracker"]
    end

    subgraph Data_Network["Infrastruktur Jaringan & Database"]
        DB[("SQLite WAL (better-sqlite3)")]
        MikroTik[("Router MikroTik (PPPoE / Hotspot)")]
        OLT[("OLT Fiber (Hioso/HSGQ/VSOL)")]
        CPE[("ONT / Modem Pelanggan (TR-069)")]
    end

    CustPWA -->|HTTP/REST| App
    PublicVoucher -->|HTTP/REST| App
    WABot <--> App
    TeleBot <--> App
    App --> AuthSvc
    App --> BillSvc
    App --> MikroSvc
    App --> OLTSvc
    App --> UsageSvc
    CPE <-->|CWMP SOAP| ACSServer
    ACSServer <--> DB
    BillSvc <--> DB
    MikroSvc <--> MikroTik
    OLTSvc <--> OLT
    UsageSvc <--> MikroTik

---

2. Analisis Backend & Logika Alur Fungsi

2.1 Arsitektur Server & Runtime

• Runtime: Node.js >=20.0.0 (Native ES Module + CommonJS hybrid).
• Database Engine: SQLite 3 melalui better-sqlite3 dengan mode WAL (Write-Ahead Logging), foreign keys aktif, sinkronisasi file cepat dan hemat resource.
• Proses Lifecycle: Dikelola oleh Systemd (billing-rtrw.service) dengan auto-restart on-failure (delay 5 detik), batas memori RAM --max-old-space-size=512.
• Proteksi Server:
  • Penanganan unhandledRejection dan uncaughtException terpusat agar error koneksi (misal timeout MikroTik) tidak mematikan server Express.
  • Fallback port otomatis (startServer mencoba port +1000 jika port 3001 bentrok).
  • Proteksi CSRF berbasis validasi header Origin dan Referer (mengecualikan webhook dan endpoint SOAP ACS).

---

2.2 Modul-Modul Inti & Alur Logika

A. Layanan Billing, Invoice & Isolir (services/billingService.js & services/cronService.js)

• Logika Pembuatan Tagihan:
  1. Cron berjalan setiap hari (cronService.js) memeriksa seluruh pelanggan aktif.
  2. Tagihan dibuat otomatis setiap siklus tanggal tagihan (billing_date) untuk periode bulan berjalan.
  3. Kode unik nominal QRIS (qris_amount_unique) diinjeksi 3 digit acak (1–999) agar mutasi bank/QRIS dapat dicocokkan otomatis tanpa payment gateway berbayar.
• Logika Isolir Otomatis:
  1. Bila tanggal saat ini mencapai atau melewati isolir_day (default tanggal 20 tiap bulan) dan tagihan pelanggan masih unpaid:
  2. Status pelanggan di database diubah menjadi isolated.
  3. mikrotikService dipanggil untuk memindahkan secret PPPoE ke profile isolir atau memasukkan IP klien ke Address List ISOLIR di MikroTik Firewall.
  4. Sesi aktif diputus (disconnectPPPoE) sehingga pelanggan ter-redirect ke halaman Walled Garden (/isolated).

B. Layanan TR-069 ACS Server (services/acsServerService.js & /acs)

• Protokol: CWMP (CPE WAN Management Protocol) via SOAP XML over HTTP POST.
• Alur Inform & Handshake:
  1. Modem (ONT) mengirim HTTP POST Inform ke endpoint /acs.
  2. Server memeriksa header Authorization. Jika belum diautentikasi, server membalas dengan HTTP 401 Unauthorized (Digest Challenge).
  3. Modem mengirim kembali request dengan Digest Hash yang dihitung berdasarkan username (skyfiber) dan password acak perangkat.
  4. Server membaca parameter XML (Device.DeviceInfo.*, Device.WANDevice.*, Device.Ethernet.*, Device.LANDevice.*).
  5. Data kekuatan redaman optik (RXPower, TXPower), serial number, model, dan versi software disimpan ke tabel acsdevices.
  6. Server memeriksa antrean tugas (task queue) per perangkat: jika ada perintah ganti password WiFi atau reboot, server merespons dengan SetParameterValues atau Reboot.

C. Pengelolaan WiFi Multi-Vendor (services/customerDeviceService.js)

• Masalah Klasik: Tiap vendor modem (Huawei, ZTE, FiberHome, Nokia) memiliki skema OID/TR-098 yang berbeda-beda. Mengirim parameter yang salah menyebabkan SOAP Fault 9007.
• Logika Adaptif Per-Vendor:
  • Huawei / FiberHome / Nokia: Memprioritaskan PreSharedKey.1.KeyPassphrase dan menghindari pengiriman hex 64-digit bersamaan dengan plain string.
  • ZTE / ZICG / CIOT: Memprioritaskan KeyPassphrase top-level.
  • Dual-Band SSID: Mengatur WLANConfiguration.1.SSID (2.4 GHz) dan WLANConfiguration.5.SSID (5 GHz) secara independen tanpa merusak konfigurasi guest SSID.

D. Integrasi Jaringan MikroTik (services/mikrotikService.js)

• Koneksi: RouterOS API (port default 25722/8728) menggunakan library routeros-client.
• Fitur Utama:
  • Sinkronisasi PPPoE: Read active connections, update secret passwords, kick active sessions.
  • Monitoring Traffic: Mengambil data byte RX/TX interface pelanggan untuk kalkulasi kuota.
  • Voucher Hotspot: Direct injection user hotspot, profile rate-limit, dan validitas voucher.

E. Autentikasi Pelanggan & Persistent Token (services/customerAuthTokenService.js)

• Alur Sesi PWA:
  1. Pelanggan memasukkan nomor HP / ID Pelanggan.
  2. Saat login berhasil, backend men-generate token kriptografi acak crypto.randomBytes(32).toString('hex').
  3. Token di-hash dengan SHA-256 dan disimpan di tabel SQLite customer_auth_tokens dengan masa berlaku 90 hari.
  4. Plain token dikirimkan ke browser sebagai cookie customer_remember (httpOnly, secure, sameSite: lax).
  5. Ketika pengguna membuka PWA (bahkan setelah browser/HP di-restart), middleware auto-login memverifikasi cookie ini dan merekonstruksi session secara transparan.

F. Pelacakan Kuota & Pemakaian Bandwidth (services/usageService.js)

• Logika Agregasi:
  1. Mengambil byte delta dari MikroTik queue / interface.
  2. Menyimpan sampel agregat harian dan bulanan ke database.
  3. Menyediakan API untuk konsumsi frontend (Chart.js di dashboard pelanggan).

---

3. Analisis UI / UX, Styling, Typografi & Layout

Pemeriksaan mendalam terhadap template EJS dan file CSS/JS di /opt/billing-rtrw/views/ dan /opt/billing-rtrw/public/ mengungkap sejumlah temuan penting mengenai styling, engine, dan konsistensi desain:

3.1 Peta Engine & Library UI per Portal

Portal / Halaman	Engine CSS Utama	Library Icon	Font Family Utama	Style Pendekatan
Customer Dashboard (views/dashboard.ejs)	Tailwind CSS 3.4.17 (via CDN)	Lucide Icons (v1.48.0) + FontAwesome 6.4.0	Plus Jakarta Sans (Google Fonts)	Modern App Shell / Glassmorphism Mobile-first
Customer Login (views/login.ejs)	Bootstrap 5.3.2 (CDN)	Bootstrap Icons 1.11.3	System Font Stack (-apple-system, Segoe UI, Roboto)	Centered Glass Card / Radial Background
Admin Portal (views/admin/*)	Custom CSS (/css/admin.css)	Bootstrap Icons 1.11.3 + FontAwesome	Inter (Google Fonts)	Desktop Enterprise Sidebar & Table Layout
Teknisi Portal (views/tech/*)	Bootstrap 5 + /css/theme.css	Bootstrap Icons	System Font / Inter	Mobile Bottom Navigation
Halaman Peta Jaringan (views/admin/map.ejs)	Leaflet 1.9.4 + /css/admin.css	FontAwesome + SVG Animasi	Inter	Fullscreen Interactive Map & Vector Layer

---

3.2 Analisis Typografi & Hierarki Font

[Customer Dashboard]   Plus Jakarta Sans (300, 400, 500, 600, 700, 800)
       ├── Title / Header     : text-base sm:text-lg font-bold (Tracking tight)
       ├── Section Labels     : text-xs font-semibold text-slate-400 uppercase (Tracking wider)
       ├── Body / Konten      : text-sm font-normal text-slate-200 (Leading relaxed)
       └── Badges & Metadata  : text-[10px] sm:text-xs font-medium

[Customer Login]       System Font Stack (BlinkMacSystemFont, Segoe UI, Roboto)
       └── Ketidaksesuaian    : Font berbeda dengan Dashboard; saat user login terjadi visual jump dari font sistem ke Plus Jakarta Sans.

[Admin Portal]         Inter (300, 400, 500, 600, 700, 800)
       ├── Sidebar Items      : font-size 13px, font-weight 500
       ├── Data Table Header  : font-size 11px, text-transform uppercase, letter-spacing 0.5px
       └── Table Data Cells   : font-size 13px, color var(--text: #e6edf3)

---

3.3 Analisis Styling, Palette Warna & Tema Gelap/Terang

Palette Warna Dominan

1. Mode Gelap (Customer Dashboard):
   • Background Utama: #0b0f19 (Deep Blue-Black)
   • Card & Panel: #1e293b (Slate 800) dengan border #334155 (Slate 700)
   • Aksen Primer (Brand): Gradasi Teal #14b8a6 ke Cyan #06b6d4
   • Aksen Sekunder: Indigo #6366f1
   • Status Indikator: Hijau Sukses #10b981, Merah Warning/Error #f43f5e, Amber #f59e0b
2. Mode Terang (Customer Dashboard & Global Theme):
   • Background Utama: #f1f5f9 (Slate 100)
   • Card & Panel: #ffffff murni dengan border rgba(15, 23, 42, 0.08)
   • Teks Utama: #0f172a (Slate 900), Teks Muted: #64748b (Slate 500)
3. Mekanisme Tema (Theming Engine):
   • Terdapat dua sistem tema yang berjalan berdampingan:
     • views/dashboard.ejs menggunakan script lokal inline (localStorage: skyfiber-customer-theme) mengendalikan class dark pada <html> untuk Tailwind.
     • Portal lainnya menggunakan /js/theme.js dan /css/theme.css (localStorage: app-theme) mengendalikan atribut data-theme="light|dark".
   • Pada rilis v1.9.4, kedua key ini sudah disinkronkan, namun styling mode terang di portal admin masih membutuhkan penyesuaian kontras pada beberapa tabel dan modal.

---

3.4 Analisis Layout, Spacing, Alignment & UX

1. Customer Dashboard (Mobile App Shell)

• Alignment & Container:
  • Lebar maksimum dibatasi ke max-w-md atau max-w-lg di tengah layar (mx-auto), memberikan rasa native mobile application saat dibuka di smartphone maupun desktop browser.
  • Padding konten konsisten (px-4 py-3), dengan padding bawah ekstra (pb-28) untuk memberi ruang bagi floating navigation dock.
• Floating Glass Dock (5 Tab Navigasi):
  • Terpasang fixed di bagian bawah layar: fixed bottom-4 left-1/2 -translate-x-1/2.
  • Menggunakan efek glassmorphism (backdrop-blur-md, background semi-transparan, border tipis halus).
  • Indikator aktif berupa sliding pill yang bergerak halus mengikuti tab yang diklik (updatePillPosition).
  • Tab navigasi:
    1. tab-beranda (Home, status paket, kuota, shortcut aksi)
    2. tab-router (Status ONT, redaman fiber optic, ganti WiFi, reboot)
    3. tab-ppob (Layanan isi pulsa & token listrik - status Coming Soon)
    4. tab-tagihan (Riwayat invoice, tombol bayar QRIS)
    5. tab-profile (Data akun, riwayat tiket kendala, tombol CS WhatsApp, logout)
• Kerapian & Touch Target:
  • Seluruh tombol interaktif memiliki ukuran touch-target minimal 40x40px (ramah sentuhan jari di layar HP).
  • Safe-area-insets untuk iPhone (env(safe-area-inset-bottom)) sudah ditambahkan pada .dock-glass.

2. Admin & Staff Portal

• Layout:
  • Sidebar navigasi di sisi kiri (width: 240px, fixed).
  • Konten utama di sebelah kanan dengan header fixed dan breadcrumb.
  • Responsive breakpoint: Pada layar kecil (mobile), sidebar disembunyikan dan diakses lewat toggle menu hamburger.

---

3.5 Temuan Evaluasi & Celah UI/UX (Bottlenecks)

1. Fragmentasi Framework CSS:
   • Halaman login menggunakan Bootstrap 5, sedangkan dashboard pelanggan menggunakan Tailwind CSS. Ini membebani browser pengguna karena harus mengunduh dua framework CSS besar saat pertama kali membuka aplikasi.
2. Ketergantungan CDN Runtime (Client-Side Tailwind):
   • Dashboard pelanggan menggunakan <script src="https://cdn.tailwindcss.com/3.4.17"></script>. CDN ini mem-parse class Tailwind saat runtime di perangkat klien (JIT compiler di browser), yang dapat memperlambat rendering awal (First Contentful Paint) pada ponsel berspesifikasi rendah.
3. Dual Icon Libraries:
   • Halaman dashboard memuat Lucide Icons dan FontAwesome 6.4.0 secara bersamaan. FontAwesome (file CSS + font ~400KB) hanya digunakan untuk segelintir ikon kecil, sementara sebagian besar UI sudah menggunakan SVG Lucide.
4. Log Error Berulang di Backend:
   • Terdapat log Telegram Polling Error berkala pada journal server deneva karena token bot belum dikonfigurasi / timeout koneksi ke server Telegram API.

---

4. Rencana Kerja Terperinci (Execution Plan)

Rencana perubahan ini dibagi menjadi 4 fase berurutan dengan prinsip zero-downtime dan keamanan data:

timeline
    title Timeline Rencana Peningkatan Billing RTRW
    Fase 1 : Konsolidasi Backend & Error Fix : Fix Polling Telegram : Optimalisasi Error Handling
    Fase 2 : Unifikasi Design System : Standarisasi Font (Plus Jakarta Sans) : Harmonisasi Halaman Login & Dashboard
    Fase 3 : Optimasi Asset & Performa : Eliminasi Redundansi Icon : Cache Profiling & PWA Hardening
    Fase 4 : Testing & Validasi : Uji Responsivitas Semua Layar : Uji Fungsi WiFi & Pembayaran Live

Fase 1: Perbaikan Stabilitas & Logika Backend

1. Fix Polling Telegram (services/telegramBot.js):
   • Tambahkan pengecekan kondisi: jika token Telegram kosong, nonaktifkan polling: true agar tidak membanjiri log server dengan polling error setiap 5 detik.
2. Peningkatan Ketahanan Koneksi MikroTik (services/mikrotikService.js):
   • Implementasikan retry backoff otomatis saat query queue/PPPoE timeout, menghindari uncaught exception yang tidak perlu.
3. Audit Query Database (config/database.js):
   • Periksa indeks pada tabel pppoe_traffic_samples, invoices, dan customer_auth_tokens untuk mempercepat query bulanan.

Fase 2: Harmonisasi UI/UX & Standarisasi Tipografi

1. Standarisasi Tipografi:
   • Terapkan font Plus Jakarta Sans ke seluruh halaman pelanggan, termasuk halaman Login (views/login.ejs), Register, dan Isolir (views/isolated.ejs), menggantikan system font default agar pengalaman visual konsisten sejak awal.
2. Harmonisasi Desain Halaman Login (views/login.ejs):
   • Rombak halaman login agar memiliki nuansa tema, sudut rounded, dan aksen warna Teal/Cyan yang identik dengan Dashboard Pelanggan.
   • Ganti elemen Bootstrap pada halaman login menjadi layout yang selaras dengan tema dashboard.
3. Penyempurnaan Form Ganti WiFi di Tab Router:
   • Perjelas instruksi frekuensi 2.4 GHz vs 5 GHz.
   • Tambahkan toggle visibility (mata) untuk password WiFi dan validasi panjang password (minimal 8 karakter) di sisi klien sebelum submit.

Fase 3: Optimasi Frontend & Efisiensi Aset

1. Rasionalisasi Icon:
   • Migrasikan sisa ikon FontAwesome di Dashboard pelanggan ke Lucide Icons bawaan.
   • Hapus pemanggilan CSS FontAwesome di dashboard pelanggan untuk menghemat ukuran transfer data hingga ~400 KB.
2. Optimasi Mode Terang (Light Mode):
   • Periksa dan rapikan kontras teks di seluruh tab dashboard agar tidak ada teks putih yang tidak terbaca saat berganti ke background terang.
   • Pastikan border card dan form input terlihat tegas pada mode terang.

Fase 4: Pengujian, Validasi & Deployment

1. Uji Coba Lintas Perangkat:
   • Uji tampilan di mobile (Android Chrome, iOS Safari), tablet, dan desktop.
   • Uji fungsi PWA Add to Home Screen dan verifikasi auto-login setelah kill aplikasi.
2. Uji Fungsional End-to-End:
   • Uji ganti SSID/password pada modem online.
   • Uji alur pembuatan invoice dan QRIS.
   • Restart service billing-rtrw.service dan verifikasi log bersih tanpa error.