Kode

NAHPU lebih dari sekadar aplikasi katalog digital untuk kerja lapangan sejarah alam. Ini adalah sistem perangkat lunak untuk mendukung digitalisasi spesimen tepat pada saat koleksi dilakukan. Halaman ini berfokus pada penjelasan tentang cara berkontribusi pada aplikasi utama NAHPU, yaitu katalog digital itu sendiri. Lihat bagian alat pengembangan untuk detail lebih lanjut tentang berkontribusi pada perangkat lunak pendukung proyek.

Memulai dengan Cepat

Prasyarat

Sebelum Anda dapat berkontribusi pada proyek NAHPU, pastikan Anda telah menginstal hal-hal berikut di mesin Anda:

Untuk menyiapkan mesin pengguna agar siap bagi pengembangan NAHPU:

Instal Flutter SDK
Ikuti panduan oleh tim Flutter. Anda juga perlu menginstal Android Studio.
Instal Rust toolchain
Instal Flutter rust bridge

Kontribusi Kode

Fork repositori NAHPU di GitHub.
Clone repositori yang telah di-fork ke mesin lokal Anda.
Terminal window
```
git clone https://github.com/hhandika/nahpu.git
```
Jika Anda menggunakan GitHub CLI.
Terminal window
```
gh repo clone hhandika/nahpu
```
Masuk ke direktori repositori NAHPU.
Terminal window
```
cd nahpu/
```
Buat branch baru untuk perubahan Anda.
Terminal window
```
git checkout -b nama-branch-anda
```

Lakukan perubahan dan commit.

git add .
git commit -m "Pesan commit Anda"

Push perubahan Anda ke repositori fork Anda.
Buat pull request ke repositori utama NAHPU.
Jika Anda mengerjakan perubahan antarmuka pengguna (UI), pastikan untuk menyertakan tangkapan layar atau video demo untuk mengilustrasikan perubahan Anda. Beberapa contoh perubahan antarmuka pengguna yang baik dapat ditemukan di NAHPU GitHub issues.

Perubahan Skema Database

NAHPU menggunakan Drift untuk manajemen database SQLite. Anda dapat menemukan definisi skema database di direktori db_schemas/.

Usulkan perubahan skema dalam GitHub issue terlebih dahulu.
Setelah perubahan disetujui, tambahkan definisi skema baru pada berkas /lib/services/database/table.drift.
Tingkatkan versi database pada berkas /lib/services/database/database.dart.
Sebagai contoh, untuk meningkatkan dari versi 6 ke 7, perbarui konstanta kSchemaVersion:
```
const int kSchemaVersion = 7;
```

Tulis fungsi migrasi baru pada berkas yang sama untuk menangani perubahan skema. Contohnya:

Future<void> _migrateFromVersion7(Migrator m) async {
  await m.addColumn(specimens, specimens.newColumn);
  // Tambahkan langkah migrasi tambahan apa pun di sini
}

Setelah memperbarui skema, jalankan pembuat kode (code generator) untuk memperbarui kode Dart yang dihasilkan:
Terminal window
```
flutter pub run build_runner build --delete-conflicting-outputs
```
Dump skema akhir ke berkas baru di db_schemas/ dengan nomor versi berikutnya.
Gunakan perintah bawaan drift_dev untuk membuat dump skema:
Terminal window
```
dart run drift_dev schema dump lib/services/database/database.dart db_schemas/drift_schema_v7.json
```
Jalankan pengujian.
Terminal window
```
flutter test
```
Commit perubahan Anda dan buka pull request dengan deskripsi yang jelas mengenai perubahan skema, alasan dilakukannya perubahan tersebut, dan dampak apa pun pada data yang sudah ada.

Pemecahan Masalah

Berikut adalah beberapa masalah umum dan solusinya:

`flutter_rust_bridge_codegen` tidak ditemukan

Penyebab: flutter_rust_bridge_codegen tidak ada dalam PATH Anda.
Solusi: Pastikan Anda telah menginstalnya dengan cargo install flutter_rust_bridge_codegen dan direktori cargo bin ada dalam PATH Anda.

Kesalahan pada macOS: `flutter_rust_bridge_codegen` gagal dengan "Please supply one or more path/to/llvm..."

Penyebab: Pembuat kode tidak dapat menemukan instalasi LLVM Anda.
Solusi: Instal LLVM dengan Homebrew (brew install llvm).

Kesalahan pada Windows: gagal dengan "nudget" atau kesalahan linker

Penyebab: MSVC build tools atau Windows SDK hilang atau tidak dikonfigurasi dengan benar, menyebabkan Rust toolchain gagal saat proses linking.
Solusi: Instal Visual Studio Build Tools dan pastikan beban kerja Desktop development with C++ dipilih. Kemudian atur Rust toolchain ke MSVC:
Terminal window
```
rustup default stable-x86_64-pc-windows-msvc
```

Pembahasan Mendalam

Arsitektur Kode

NAHPU adalah aplikasi lintas platform yang dibangun dengan Flutter, framework berperforma tinggi untuk membangun aplikasi yang dikompilasi secara asli. Flutter menggunakan bahasa pemrograman Dart, yang dioptimalkan untuk membangun antarmuka pengguna yang cepat dan indah. Pendekatan ini menyederhanakan proses pengembangan dan merupakan resep kami untuk memastikan bahwa NAHPU memiliki performa tinggi dan mendukung sistem operasi seluler serta desktop.

Penyimpanan Data: Di sisi backend, NAHPU sangat bergantung pada SQLite untuk penyimpanan lokal yang mengutamakan mode offline. Karena kerja lapangan sering kali dilakukan di daerah terpencil tanpa akses internet, manajemen data lokal yang tangguh sangatlah penting.

Integrasi Rust: Sejak awal 2024, kami telah memigrasikan operasi yang membutuhkan komputasi berat ke Rust. Rust adalah bahasa pemrograman sistem yang berfokus pada performa, keandalan, dan keamanan memori. Dengan mengintegrasikan Rust dengan Flutter melalui flutter_rust_bridge, kami mencapai yang terbaik dari kedua dunia:

Flutter/Dart menangani manajemen status, perutean, dan rendering UI dengan lancar pada 60-120fps. Rust menangani pekerjaan berat: memproses kumpulan data besar, transformasi data yang kompleks, I/O file, dan algoritma khusus yang jika tidak dilakukan akan menghambat Dart isolate.

Antarmuka Pengguna dan Desain

NAHPU menggunakan sistem Material Design 3 sebagai fondasi identitas visualnya.

Konsistensi: Material Design terintegrasi secara mendalam dengan Flutter. Kapan pun memungkinkan, kami menggunakan widget Material standar untuk memastikan pengalaman pengguna yang konsisten, mudah diakses, dan intuitif di semua sistem operasi.

Responsivitas: NAHPU sering digunakan pada tablet lapangan dan perangkat seluler. Saat berkontribusi pada komponen UI, selalu pertimbangkan tata letak yang responsif. Gunakan alat seperti LayoutBuilder, MediaQuery, atau sistem grid fleksibel untuk memastikan perubahan Anda terlihat bagus di layar ponsel kecil maupun tampilan tablet atau desktop yang besar.

Aksesibilitas: Pastikan teks memiliki kontras yang cukup, target sentuh berukuran memadai (setidaknya 48x48 piksel logis), dan label semantik disediakan untuk pembaca layar.

Struktur Direktori

Directoryandroid/ Kode khusus platform Android dan konfigurasi build
- …
Directoryassets/ Aset statis seperti gambar, font, dan ikon
- …
Directorydb_schemas/ Definisi skema database dan file migrasi
- …
Directoryinstaller/ Skrip installer dan konfigurasi untuk pengemasan aplikasi
- …
Directoryintegration_test/ Pengujian integrasi end-to-end
- …
Directoryios/ Kode khusus platform iOS dan konfigurasi build
- …
Directorylib/ Kode sumber Dart utama untuk aplikasi Flutter
- …
Directorylinux/ Kode khusus platform Linux dan konfigurasi build
- …
Directorymacos/ Kode khusus platform macOS dan konfigurasi build
- …
Directoryrust/ Kode sumber Rust untuk komponen asli yang mementingkan performa
- …
Directoryrust_builder/ Skrip build dan konfigurasi untuk mengompilasi kode Rust
- …
Directoryscripts/ Skrip utilitas untuk tugas pengembangan dan otomatisasi
- …
Directorysnap/ Konfigurasi paket Snap untuk distribusi Linux
- …
Directorytest/ Pengujian unit dan widget
- …
Directorytest_driver/ Pengujian Flutter driver untuk pengujian UI otomatis
- …
Directoryweb/ Kode khusus platform Web dan konfigurasi build
- …
Directorywindows/ Kode khusus platform Windows dan konfigurasi build
- …

Meskipun Anda mengeksekusi flutter run, terminal akan mencetak jalur database secara persis dalam beberapa baris pertama pada output.

Sebagai contoh:

========================================
App database path: /home/[user]/Documents/nahpu/nahpu.db
Directory exists: true
Database exists: false
========================================

Gunakan jalur ini untuk mengonfirmasi berkas (file) yang tepat sebelum menghapus. Database exists: false hal yang normal pada peluncuran perdana — berkas akan otomatis terbuat saat aplikasi dibuka.

Mendapatkan Bantuan

Jika Anda mengalami kesulitan saat menyiapkan lingkungan atau memahami arsitektur, jangan ragu untuk menghubungi kami! Periksa NAHPU GitHub Issues untuk diskusi yang sedang berlangsung, atau buka utas diskusi baru jika Anda memiliki proposal arsitektur.