Dokumentasi Fitur Photo GeoTagging BUMDes ERP

Dokumen ini memuat Arsitektur, Blueprint, Roadmap Pengembangan, serta Panduan Penggunaan untuk fitur Photo GeoTagging yang ada di dalam ekosistem BUMDes ERP.

---

1. Blueprint & Visi (Blueprint)#

Visi Utama: Menyediakan bukti autentik, akurat, dan terverifikasi secara geografis (location-aware) untuk setiap aktivitas fisik di lapangan yang dilakukan oleh unit-unit BUMDes.

Tujuan Implementasi:

1. Transparansi & Akuntabilitas: Setiap foto aset, laporan operasional (seperti kandang peternakan, kondisi gudang, absensi kehadiran) memiliki bukti lokasi dan waktu nyata yang tertanam (watermark) secara visual.
2. Efisiensi: Pengguna dapat mengambil foto dari antarmuka web (browser smartphone) tanpa perlu memasang aplikasi native (APK/iOS app) khusus.
3. Fleksibilitas (Reusable Component): Fitur ini dirancang sebagai komponen antarmuka mandiri (<GeoTagCamera />) yang dapat disisipkan pada formulir (form) mana pun di dalam sistem ERP.

Use Case Utama (Contoh):

• Unit Aset: Foto barang inventaris saat akuisisi/pencatatan.
• Unit Peternakan: Foto kondisi kandang harian, hewan ternak, atau dokumentasi kematian hewan.
• Unit SDM (Kehadiran): Absensi pegawai lapangan dengan bukti foto lokasi.

---

2. Arsitektur Teknis (Architecture)#

Fitur ini mengedepankan arsitektur Client-Side Processing, di mana beban pemrosesan gambar dan lokasi dilakukan sepenuhnya di sisi klien (browser pengguna) untuk menghemat beban server (serverless rendering) dan biaya (bandwidth/storage overhead).

Komponen Kunci

• Teknologi Dasar: React (Next.js App Router Client Component).
• Input Perangkat Keras: Menggunakan elemen HTML5 standar <input type="file" accept="image/*" capture="environment" />. Ini memaksa browser seluler (Android Chrome / iOS Safari) untuk otomatis memicu aplikasi Kamera bawaan.
• Lokasi & Waktu:
  • navigator.geolocation.getCurrentPosition() dari Geolocation API HTML5 untuk menarik latitude dan longitude presisi tinggi.
  • Date API untuk menangkap timestamp presisi milidetik saat foto selesai dirender.
• Pemrosesan Gambar (Watermarking):
  • HTMLCanvasElement dan CanvasRenderingContext2D digunakan untuk memuat foto, melakukan modifikasi ukuran, lalu menyematkan watermark canggih langsung di atas foto tersebut (overlay).
  • Desain Watermark: Menggunakan gaya Modern HUD (Head-Up Display) bergaya Light Translucent Glassmorphism. Panel melayang (floating card) dibingkai dengan garis tepi (outline) berwarna hijau solid identik dengan warna utama aplikasi (ERP BUMDes Bolulango). Tipografi menampilkan Koordinat GPS (berwarna gelap), Tanggal, Logo resmi "BUMDes Bolulango", serta Mini Map bersudut melengkung dengan titik merah sentral. Desain ini secara profesional mengawinkan elemen fiksi ilmiah bersih dengan identitas korporat BUMDes.
• Output Data: Menghasilkan base64 DataURL (JPEG, quality 0.85). Output ini siap dikirimkan ke server/API, cloud storage (seperti Supabase Storage), atau langsung diunduh secara luring oleh pengguna (Simpan ke Galeri).

Flow (Alur Sistem)

1. Trigger: User mengklik komponen UI "Ambil Foto".
2. Permintaan Izin: Browser memicu izin Hardware Camera dan izin Location/GPS.
3. Pengambilan (Capture): Kamera sistem terbuka, pengguna menjepret gambar, dan mengonfirmasi.
4. Eksekusi Canvas: Skrip membaca file/blob, melukis piksel gambar ke dalam Canvas.
5. Overlapping Data: Koordinat lokasi (Lat, Lng) dan string waktu ditempel di bagian bawah canvas.
6. Ekspor: Gambar dengan watermark di-export. Callback (onCapture) memberikan data foto hasil kepada sistem form/induk komponen untuk disimpan.

---

3. Roadmap Pengembangan (Roadmap)#

Pengembangan sistem Photo GeoTagging terbagi dalam beberapa fase. Saat ini kita berada di penyelesaian Fase 1.

Fase 1: Inti/Dasar (Selesai)

• Pembuatan UI Komponen Mandiri (GeoTagCamera).
• Ekstraksi koordinat GPS langsung di browser (Client-Side).
• Penerapan Watermark (Lat/Lng dan Waktu).
• Fitur unduh lokal (Simpan ke Galeri).
• Halaman Demo Interaktif (/dashboard/demo-geotag).

Fase 2: Integrasi Cloud Storage & Form Ekosistem (Jangka Pendek)

• Mengganti penyimpanan Data URL ke pengunggahan langsung ke Supabase Storage (seperti komponen PhotoUpload.tsx).
• Integrasi <GeoTagCamera /> ke form pencatatan Aset (Buku Inventaris).
• Integrasi ke formulir log harian Unit Peternakan (Laporan Kandang).

Fase 3: Pengayaan Metadata (Jangka Menengah)

• Reverse Geocoding: Alamat otomatis ditampilkan di watermark via server-side API route /api/geocode (Google Maps Geocoding API, cached 24 jam).
• Tamper-Proof Data: Menanamkan hash MD5/SHA dari timestamp dan koordinat langsung ke dalam EXIF Metadata file JPG sebelum di-upload untuk verifikasi orisinalitas di sisi server.
• Batasan Geofencing: Menolak pengambilan foto jika jarak koordinat pengguna lebih dari "X" meter dari lokasi proyek/BUMDes (sangat berguna untuk absensi atau inspeksi).

Fase 4: Optimasi Performa & UX (Jangka Panjang)

• Pemilihan kualitas output (Low 60%, Medium 75%, High 85%) via prop quality.
• Fitur Offline Mode: Menyimpan foto ter-watermark di Local Storage atau IndexedDB jika koneksi internet terputus, dan melakukan sinkronisasi (auto-upload) saat internet kembali normal (PWA Support).

Audit Juli 2025 (Selesai)

• Migrasi mini-map watermark dari CartoDB ke Google Maps Static API.
• Perbaikan keamanan: hapus client-side Google Maps API loading, gunakan server-side route.
• Validasi ukuran file (maks 15MB).
• Perbaikan memory leak (Object URL cleanup).
• Brand name dinamis via prop brandName.
• Toast notification menggantikan alert().
• Perbaikan timezone detection.
• Perbaikan logo timeout race condition.
• Perbaikan polyfill roundRect (closePath).
• Optimasi preview menggunakan Object URL.
• Hapus dead code (temp_old.tsx).

---

4. Panduan Penggunaan (User Guide)#

Panduan ini ditujukan bagi pengguna akhir (admin lapangan, petugas kandang, panitia inventaris) yang mengakses fitur melalui smartphone mereka.

Persiapan Pertama Kali

1. Buka aplikasi ERP BUMDes di browser web smartphone Anda (disarankan Google Chrome untuk Android, atau Safari untuk iPhone/iOS).
2. Lakukan proses Log In dengan akun Anda.
3. Masuk ke modul atau halaman yang membutuhkan dokumentasi foto (atau masuk ke halaman /dashboard/demo-geotag untuk latihan).

Langkah-langkah Mengambil Foto GeoTag

1. Cari kotak dengan ikon kamera bertuliskan Ambil Foto Lokasi (atau sejenisnya).
2. Ketuk kotak tersebut.
3. Peringatan Izin (Sangat Penting): Browser Anda akan memunculkan pop-up peringatan meminta akses ke Lokasi (Location) dan Kamera.
   • Anda wajib memilih "Allow" / "Izinkan". Jika ditolak, fitur koordinat GPS tidak akan berjalan.
4. Aplikasi kamera bawaan HP Anda akan otomatis terbuka. Arahkan kamera ke objek yang ingin Anda foto (contoh: bangunan aset, kondisi ternak, bukti serah terima).
5. Ambil foto seperti biasa, lalu ketuk tanda centang (OK) pada antarmuka kamera HP Anda.
6. Anda akan kembali ke layar web browser. Harap tunggu beberapa detik. Aplikasi sedang memproses penyematan watermark lokasi ke atas foto tersebut (akan ada indikator loading "Memproses foto & lokasi...").
7. Setelah berhasil, foto akan muncul sebagai pratinjau (Preview). Anda dapat melihat titik Koordinat, Tanggal, dan Waktu tercetak di pojok kiri bawah foto.

Opsi Setelah Foto Diambil

• Simpan ke Galeri: Menekan tombol ini (tombol biru) akan langsung mengunduh/menyimpan foto yang sudah memiliki teks GPS ke dalam memori internal handphone Anda.
• Ulangi (Tombol X / Putar Balik): Jika foto buram atau tidak pas, Anda dapat menekan tombol ini untuk menghapus foto dari sistem dan mengulangi pengambilan foto yang baru.
• Simpan ke Sistem/Submit: (Jika tergabung dalam form input data), klik tombol "Simpan Laporan" atau "Simpan Aset" di bagian paling bawah layar form agar foto ini diunggah ke server BUMDes.

Mengatasi Kendala (Troubleshooting)

• Teks Lokasi Bertuliskan "Tidak diketahui": Pastikan Anda telah menyalakan GPS / Location Services dari panel notifikasi HP Anda sebelum membuka browser. Pastikan Anda tidak secara tidak sengaja memblokir izin Lokasi di Chrome/Safari. Jika terblokir, buka pengaturan browser (Site Settings) dan Izinkan akses Lokasi untuk website BUMDes.
• Kamera Tidak Terbuka Otomatis: Jika menekan kotak "Ambil Foto" hanya memunculkan "File Picker" atau folder galeri (bukannya kamera langsung), pastikan Anda membukanya lewat perangkat seluler. Di laptop/PC (desktop), ini merupakan perilaku standar browser.