software.md

Dokumentasi Rekayasa Perangkat Lunak: Desain Antarmuka (UI) & Alur Kerja (Web Flow)

Dokumen ini mendefinisikan arsitektur antarmuka pengguna (User Interface), pola desain (Design Pattern), dan alur navigasi (Web Flow) untuk Sistem Pengaduan Digital. Perancangan ini ditujukan untuk memberikan panduan teknis yang presisi bagi tim pengembang (Frontend Engineer dan UI/UX Designer) dalam mengimplementasikan sistem.

---

1. Pola Desain Arsitektur Antarmuka (UI Design Patterns)

Sistem ini mengadopsi beberapa pola desain standar industri untuk menjamin skalabilitas, maintainability, dan performa aplikasi:

A. Component-Based Architecture (Atomic Design)

Antarmuka dibangun menggunakan pendekatan modular di mana setiap elemen UI dipecah menjadi komponen independen yang dapat digunakan kembali (reusable):

• Atoms: Elemen dasar UI yang tidak dapat dipecah lagi (contoh: Button, InputText, BadgeStatus, SpinnerLoading).
• Molecules: Gabungan beberapa atoms yang membentuk satu kesatuan fungsi (contoh: SearchGroup yang terdiri dari InputText dan Button).
• Organisms: Komponen kompleks yang membentuk bagian dari halaman (contoh: Navbar, Sidebar, TableLaporan, FormAduan).
• Templates & Pages: Susunan organisms dalam tata letak (layout) tertentu yang merepresentasikan halaman utuh aplikasi.

B. MVVM (Model-View-ViewModel) Pattern / State Management Centralized

Untuk memisahkan logika bisnis dengan presentasi UI, terutama pada implementasi Single Page Application (SPA):

• View: Komponen deklaratif UI (HTML/JSX) yang menangani rendering data ke layar.
• ViewModel / State: Mengelola kondisi data lokal (reactive state), penanganan event pengguna, dan komunikasi dengan API Service Layer.
• Model: Representasi skema data objek (contoh: User, Laporan, Statistik).

C. Container-Presenter Pattern

Komponen dipisahkan menjadi dua kategori:

1. Container Components (Smart): Mengatur penarikan data (data fetching), pengelolaan state manajemen, dan logika fungsional.
2. Presenter Components (Dumb): Hanya menerima data melalui properties/props dan merendernya ke UI tanpa mengetahui asal-usul data tersebut. Menjamin tingkat reusabilitas yang tinggi.

---

2. Struktur Tata Letak Utama (Global Layout Structure)

Sistem ini dibagi menjadi dua area tata letak utama berdasarkan hak akses pengguna:

Layout A: Public & Masyarakat Layout (Responsive Clean Grid)

• Header / Navigation Bar: Berisi logo sistem, menu navigasi utama (Beranda, Statistik, Panduan), serta tombol aksi "Masuk" dan "Daftar".
• Main Content Area: Menggunakan kontainer terpusat (max-width Container) dengan pendekatan sistem Grid (12 kolom) yang fleksibel untuk perangkat desktop, tablet, maupun mobile.
• Footer: Berisi informasi hak cipta, kontak instansi, dan tautan sosial media resmi.

Layout B: Admin Dashboard Layout (Fixed Sidebar Grid)

• Sidebar (Navigation Panel): Terpasang tetap di sisi kiri layar (fixed positional). Berisi profil singkat admin, menu manajemen (Dashboard, Verifikasi Laporan, Distribusi Kerja, Statistik Analitik), dan tombol keluar.
• Top Header: Berisi indikator status koneksi, panel notifikasi real-time, dan informasi tanggal sistem.
• Content Canvas: Area dinamis di sisi kanan sidebar untuk memuat tabel data tabel, grafik analitik, atau formulir verifikasi dokumen dengan kapabilitas scrolling independen.

---

3. Spesifikasi Tampilan Antarmuka Halaman (UI Page Descriptions)

Halaman 1: Beranda & Landing Page (Akses: Publik)

• Hero Section: Judul utama aplikasi "Sistem Pengaduan Digital Masyarakat", deskripsi singkat, serta tombol Call to Action (CTA) utama yang mengarah langsung ke formulir pengaduan.
• Section Alur Kerja: Infografis langkah mudah melapor (Tulis -> Verifikasi -> Tindak Lanjut -> Selesai).
• Section Statistik Singkat: Widget interaktif menampilkan total aduan masuk dan persentase penyelesaian saat ini.

Halaman 2: Autentikasi - Login & Register (Akses: Publik)

• Formulir Pendaftaran (UC-01): Input teks terstruktur untuk Nama Lengkap, Alamat Email, Nomor Telepon, Kata Sandi, dan Konfirmasi Kata Sandi. Dilengkapi dengan indikator validasi real-time (kekuatan password dan keunikan email).
• Formulir Masuk: Input Email dan Kata Sandi dengan mekanisme proteksi serangan Brute Force (reCAPTCHA v3 terintegrasi).

Halaman 3: Ruang Kerja Masyarakat (Akses: Masyarakat Terautentikasi)

• Dashboard Riwayat: Tabel dinamis (Data Table) yang menampilkan daftar pengaduan pribadi. Kolom terdiri dari ID Laporan, Judul Aduan, Tanggal Kirim, Kategori, dan BadgeStatus warna (Kuning: Menunggu, Biru: Terverifikasi, Ungu: Didistribusikan, Hijau: Selesai).
• Formulir Pembuatan Laporan Baru (UC-02):
  • Input Judul (Teks baris tunggal, maks. 100 karakter).
  • Dropdown Kategori (Infrastruktur, Pelayanan Publik, Keamanan, Kesehatan, dll.).
  • Area Teks Deskripsi (Teks multi-baris kaya komponen teks mentah).
  • Komponen Drag-and-Drop Lampiran (Mendukung berkas JPG/PNG/PDF, maks. 5MB).
• Formulir Edit Laporan (UC-03): Replikasi dari formulir pembuatan laporan, namun memuat data lama secara otomatis (pre-populated data) dan hanya aktif jika status laporan masih "Menunggu".

Halaman 4: Ruang Kerja Admin - Control Panel (Akses: Admin)

• Dashboard Utama: Kumpulan ringkasan matriks berupa kartu indikator (KPI Cards) untuk memantau metrik operasional secara waktu nyata.
• Halaman Verifikasi & Distribusi (UC-04 & UC-05): Komponen Split-Screen View. Sisi kiri menampilkan daftar antrean laporan masuk, sisi kanan menampilkan detail dokumen laporan yang dipilih secara instan lengkap dengan tombol aksi "Setujui Verifikasi" atau "Tolak" serta dropdown instansi tujuan distribusi.
• Halaman Manajemen Status (UC-08): Panel entri data log aktivitas di mana admin dapat memilih dropdown status operasional terbaru disertai kolom catatan tindak lanjut yang akan dikirim ke pelapor.

Halaman 5: Dashboard Statistik Publik (UC-07) (Akses: Publik & Admin)

• Visualisasi Grafik: Representasi visual interaktif menggunakan library grafik berbasis performa (seperti Chart.js / Recharts):
  • Pie Chart: Distribusi aduan per kategori instansi.
  • Bar Chart: Tren volume aduan bulanan.
  • Line Chart: Kecepatan rata-rata waktu penyelesaian kasus.
• Fitur Filter Kontrol: Komponen seleksi tanggal (Date Range Picker) dan filter multi-opsi kategori untuk menyaring data grafik secara instan tanpa memuat ulang halaman (Asynchronous Re-rendering).

---

4. Arsitektur Alur Kerja Aplikasi (Systemic Web Flow)

Seluruh navigasi antar halaman diatur melalui struktur routing yang ketat dengan pengamanan tingkat tinggi (Route Guards). Di bawah ini merupakan representasi urutan langkah alur navigasi dari awal hingga akhir proses:

[Masyarakat / Publik]
       │
       ├──► Akses Landing Page ──► Melihat Statistik Publik (UC-07)
       │
       ├──► Mengklik "Daftar Akun" ──► Mengisi Form Pendaftaran (UC-01)
       │                                         │
       │                                    (Data Valid)
       │                                         ▼
       ├──► Mengklik "Masuk" ◄───────────────────┘
       │          │
       │     (Login Sukses)
       │          ▼
       └──► Masuk ke Ruang Kerja Masyarakat
                  │
                  ├──► Mengisi Formulir Pengaduan Baru (UC-02) ──► Simpan ke Database (Status: Menunggu)
                  │
                  └──► Membuka Riwayat Pengaduan 
                             │
                             └──► Status "Menunggu"? 
                                        ├──► Ya ──► Mengedit Laporan Aduan (UC-03)
                                        └──► Tidak ──► Akses Edit Terkunci (Read-Only)

───────────────────────────────────────────────────────────────────────────────────────────────────

[Admin]
       │
       ├──► Otentikasi Admin Melalui Portal Khusus
       │          │
       │     (Login Sukses)
       │          ▼
       └──► Masuk ke Admin Control Panel Dashboard
                  │
                  ├──► Buka Modul Antrean Verifikasi Laporan
                  │          │
                  │          └──► Memverifikasi Kelayakan & Kelengkapan Laporan (UC-04)
                  │                     │
                  │                (Laporan Valid)
                  │                     ▼
                  │          Meneruskan & Mengelola Distribusi ke Instansi (UC-05) (Status: Didistribusikan)
                  │
                  ├──► Membuka Log Pengaduan Aktif
                  │          │
                  │          └──► Mengupdate Status Laporan & Beri Catatan Progres (UC-08) (Status: Selesai)
                  │
                  └──► Membuka Analitik Internal ──► Melihat & Ekspor Data Statistik Komprehensif (UC-07)

Aturan Navigasi Operasional & Keamanan Routing:

1. Guarded Routes (Middleware): Halaman Ruang Kerja Masyarakat dan Admin Dashboard dilindungi oleh otentikasi berbasis Token (misal: JWT). Pengguna anonim yang mencoba mengakses tautan internal akan dilempar secara otomatis ke halaman Login.
2. Role-Based Access Control (RBAC): Akun bermasyarakat tidak memiliki akses fisik maupun logika program untuk membuka halaman dengan prefiks URL /admin/*. Pelanggaran akses akan memicu respon halaman kesalahan standar HTTP 403 (Forbidden).
3. Form State Preservation: Jika pengguna tidak sengaja menekan tombol kembali saat mengisi formulir UC-02 atau UC-03, sistem akan menampilkan dialog konfirmasi pop-up pencegah kehilangan data guna memastikan pengalaman pengguna tetap optimal.