Lewati ke konten utama

Panduan Pengembangan

Pendahuluan​

Panduan ini menjelaskan cara menambahkan atau memodifikasi fitur di frontend Ravenxcope secara aman.

Sebelum Mengubah Kode​

  1. Identifikasi rute dan folder fitur yang terlibat.
  2. Periksa apakah alur kerja tersebut sudah memiliki metode API di src/lib/api.ts.
  3. Periksa apakah tipe bersama sudah ada di src/types/index.ts.
  4. Periksa apakah tindakan UI memerlukan pembatasan izin (permission gating).
  5. Periksa apakah teks harus dilokalisasi di src/locales/en.json dan src/locales/id.json.
  6. Periksa apakah fitur tersebut memerlukan konfigurasi runtime.

Menambahkan Titik Akhir (Endpoint) API​

  1. Tambahkan atau perbarui tipe TypeScript di src/types/index.ts.
  2. Tambahkan metode titik akhir ke grup yang relevan di src/lib/api.ts.
  3. Gunakan apiClient bersama kecuali jika titik akhir tersebut secara khusus memerlukan streaming fetch.
  4. Jaga jalur backend tetap relatif terhadap API_BASE.
  5. Kembalikan Promise<AxiosResponse<ApiResponse<T>>> yang bertipe jika memungkinkan.
  6. Gunakan buildRepeatedQueryParams() untuk parameter kueri array yang diharapkan backend sebagai kunci yang berulang.

Hindari membuat instans Axios baru di dalam komponen fitur.

Menambahkan Rute​

  1. Buat komponen tingkat rute di src/modules/<domain>/pages.
  2. Letakkan bagian khusus fitur di src/modules/<domain>/partials.
  3. Letakkan alur modal di src/modules/<domain>/dialogs.
  4. Impor halaman di src/app/routes.tsx.
  5. Tambahkan rute publik atau definisi rute dasbor bersarang.
  6. Jika rute tersebut termasuk dalam sidebar, atur showInNav, navLabelKey, dan icon pada rute dasbor.
  7. Jika modul lain memerlukan jalur tersebut, tambahkan/perbarui ROUTES di src/lib/constants.ts.

Menambahkan Layar Fitur​

Ikuti pola layar fitur yang sudah ada:

  • Gunakan primitif UI bersama dari src/components/ui.
  • Bungkus konten rute dasbor dalam RoutePage.
  • Gunakan DataTableCard untuk halaman daftar/tabel manajemen.
  • Gunakan Card, Table, Dialog, Badge, Skeleton, dan Button secara konsisten.
  • Jaga formulir buat/edit tetap di dalam dialog saat menyesuaikan alur pengguna, peran, dan sensor.
  • Gunakan bendera state lokal untuk memicu pengambilan data ulang (refetch) saat mengikuti hook saat ini.
  • Tampilkan umpan balik pengguna melalui pembantu alert/toast yang sudah ada.

Menambahkan Pengambilan Data (Data Fetching)​

Untuk pembacaan sumber daya umum, tambahkan atau perluas hook di src/hooks/useApi.ts.

Konvensi hook saat ini:

  • Gunakan useState untuk data, loading, dan error.
  • Gunakan useEffect untuk siklus hidup permintaan.
  • Periksa auth.isAuthenticated() ketika data bersifat privat.
  • Gunakan AbortController untuk menghindari pengaturan state setelah komponen di-unmount.
  • Kembalikan array fallback kosong untuk hook bergaya daftar.
  • Ekspos refetch hanya jika pemanggil memerlukannya.

Untuk permintaan satu kali (one-off) khusus fitur, memanggil api secara langsung di dalam komponen dapat diterima jika sesuai dengan kode di sekitarnya.

Menambahkan Tindakan dengan Batasan Izin​

  1. Tambahkan slug izin ke PERMISSIONS di src/lib/constants.ts jika belum ada.
  2. Gunakan useUserPermissions() di dalam layar.
  3. Sembunyikan tindakan ketika hasPermission(slug) bernilai false.
  4. Jaga tindakan destruktif tetap di balik konfirmasi.
  5. Jangan mengandalkan pemeriksaan frontend untuk keamanan; otorisasi backend tetap harus menegakkan aturan tersebut.

Menambahkan Formulir​

Formulir saat ini menggunakan state terkontrol dan penangan pengiriman (submit) manual.

Pola yang direkomendasikan:

  1. Inisialisasi state formulir dengan semua field yang diperlukan.
  2. Muat opsi pilihan di useEffect jika diperlukan.
  3. Validasi aturan wajib/lintas-field sederhana sebelum memanggil API.
  4. Nonaktifkan kontrol formulir saat pengiriman sedang berlangsung.
  5. Konversi nama field UI ke nama payload backend di satu tempat.
  6. Gunakan showSuccess, showError, atau toast untuk umpan balik.
  7. Tutup dialog atau navigasi hanya setelah respons berhasil.

Menambahkan Teks yang Dilokalisasi​

  1. Tambahkan kunci Bahasa Inggris ke src/locales/en.json.
  2. Tambahkan kunci Bahasa Indonesia ke src/locales/id.json.
  3. Gunakan const { t } = useTranslation() di dalam komponen.
  4. Hindari memperkenalkan string baru yang menghadap pengguna secara hard-coded di layar yang sudah menggunakan i18n.

Jika sebuah layar saat ini masih hard-coded, lokalisasikan teks yang disentuh jika memungkinkan, tetapi hindari penulisan ulang luas yang tidak terkait.

Memperbarui Konfigurasi Runtime​

Saat menambahkan bendera runtime baru:

  1. Perluas AppRuntimeConfig dan AppConfig di src/config/appConfig.ts.
  2. Urai dan validasi nilai di getRuntimeConfig().
  3. Tambahkan ke .env.example.
  4. Tambahkan ke docker-entrypoint.sh.
  5. Dokumentasikan di Runbook Konfigurasi dan Penyebaran.
  6. Pastikan nilai yang tidak valid gagal dengan aman (fail closed atau fall back safely).

Daftar Periksa Verifikasi Manual​

Untuk perubahan UI:

  1. Jalankan TypeScript/build jika perilaku berubah:
yarn build
  1. Jalankan lint jika kode berubah:
yarn lint
  1. Tes login dan perlindungan rute /dashboard.
  2. Tes rute yang diubah secara langsung dan setelah penyegaran browser.
  3. Tes jalur sukses dan gagal untuk mutasi API.
  4. Tes status tindakan yang tersembunyi karena izin jika relevan.
  5. Tes tata letak seluler untuk sidebar, tabel, dialog, atau sheet.

Untuk perubahan yang hanya bersifat dokumentasi, verifikasi nama file dan referensi jalur. Build frontend tidak diperlukan.

Pembaruan Dokumentasi​

Perbarui dokumentasi ketika:

  • Rute ditambahkan, dihapus, atau diubah namanya.
  • Kunci konfigurasi runtime berubah.
  • Grup titik akhir API atau kontrak payload berubah.
  • Perilaku auth/sesi berubah.
  • Perilaku fitur berubah pada sensor, analitik, pengguna, peran, atau organisasi.
  • Perilaku penyebaran berubah pada Docker, Nginx, atau injeksi konfigurasi.