webgis/poverty-mapping/README.md

WebGIS

Aplikasi peta lokasi bantuan dan tempat ibadah berbasis PHP, MySQL, dan Leaflet.

Gambaran Singkat

Guest bisa melihat peta dan daftar data. Pengelola mendaftar lewat formulir yang langsung memverifikasi email, lalu menunggu persetujuan admin. Setelah akun aktif, pengelola bisa menambah, mengubah, dan menghapus data miliknya sendiri. Admin bisa menyetujui atau menolak akun pengelola yang menunggu aktivasi.

Yang Dibutuhkan

• PHP 8.1 atau lebih baru
• MySQL atau MariaDB
• Composer
• Browser modern seperti Chrome, Edge, atau Firefox
• Koneksi internet untuk Leaflet, tile peta, dan email SMTP

Langkah Instalasi

Ikuti urutan ini dari awal jika Anda belum pernah menjalankan proyek ini.

1. Salin folder proyek ke komputer Anda.
2. Buka terminal di folder proyek.
3. Pasang dependensi PHP:

composer install

4. Buat file konfigurasi lingkungan:

cp .env.example .env

5. Isi file .env dengan kredensial database, SMTP, dan secret aplikasi.
6. Buat database MySQL, misalnya bernama webgis.
7. Import skema database:

mysql -u root -p webgis < sql/migrations/001_init_schema.sql

8. Jalankan server PHP bawaan untuk uji lokal:

php -S localhost:8000 -t .

9. Buka aplikasi di browser:

http://localhost:8000/index.html

Jika Anda memakai Apache atau Nginx, arahkan document root ke folder proyek ini dan sesuaikan URL aksesnya.

Isi File .env

Contoh nilai yang perlu diisi:

• DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_NAME
• SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_ENCRYPTION
• MAIL_FROM, MAIL_FROM_NAME
• API_KEY, JWT_SECRET, INTERNAL_AUTH_KEY
• BASIC_API_USER, BASIC_API_PASS
• DEBUG_MODE=0 untuk produksi atau 1 jika ingin menampilkan kode verifikasi saat pengembangan lokal

Cara Pakai

1. Buka peta

Setelah aplikasi terbuka, tampilan awal adalah peta. Guest tetap bisa melihat marker dan daftar data.

2. Daftar pengelola

Klik tombol masuk/daftar, lalu pilih daftar pengelola. Isi semua field yang diminta, kirim kode verifikasi ke email, masukkan kode 6 digit, lalu klik daftar.

3. Login

Gunakan email dan password yang sudah terdaftar. Setelah login, bar atas akan menampilkan nama pengguna.

4. Kelola data

Pengelola yang sudah aktif bisa menambah data baru dari peta, mengubah data miliknya sendiri, dan mengunggah foto bukti jika diperlukan. Admin bisa mengelola seluruh data.

5. Lihat daftar data

Klik tombol Daftar Data untuk melihat data dalam bentuk tabel. Guest hanya melihat data yang aman untuk publik.

Akun Admin Awal

Seed database menyediakan akun admin awal:

• Email: admin@example.com
• Password: Admin123!

Segera ganti kredensial ini jika Anda menjalankan aplikasi di lingkungan yang tidak pribadi.

Endpoint Utama

• src/api/auth/register.php - daftar pengelola
• src/api/auth/send_verification_code.php - kirim kode verifikasi email
• src/api/auth/login.php - login
• src/api/auth/logout.php - logout
• src/api/auth/me.php - status pengguna aktif
• src/api/get_lokasi.php - ambil data lokasi
• src/api/tambah_lokasi.php - tambah lokasi baru
• src/api/update_lokasi.php - ubah lokasi
• src/api/hapus_lokasi.php - hapus lokasi
• src/api/upload_photo.php - unggah foto lokasi
• src/api/admin/list_pending_managers.php - daftar akun pengelola menunggu persetujuan
• src/api/admin/approve_user.php - setujui akun
• src/api/admin/reject_user.php - tolak akun

File Penting

• index.html - frontend utama
• src/config/koneksi.php - koneksi database
• src/config/config.php - secret dan autentikasi
• sql/migrations/001_init_schema.sql - skema database utama
• webgis.sql - dump SQL yang sejalan dengan skema utama
• .env.example - contoh konfigurasi environment

Perawatan Berkala

Jika Anda ingin menandai bantuan yang sudah lewat masa berlakunya, jalankan:

php scripts/expire_assistance.php

Troubleshooting

• Jika database gagal terhubung, cek isi .env dan pastikan MySQL berjalan.
• Jika email tidak terkirim, pastikan kredensial SMTP benar dan memakai app password, bukan password akun biasa.
• Jika peta kosong, cek koneksi internet dan pastikan endpoint get_lokasi.php mengembalikan JSON.
• Jika login berhasil tetapi data tidak muncul, buka DevTools browser dan cek respons API serta status token JWT.

Catatan Pengembangan

Arsitektur aplikasi ini sengaja dibuat sederhana agar mudah dipelihara: frontend vanilla JavaScript, backend PHP, dan database MySQL. Bila Anda menambah kolom database baru, perbarui file migrasi, dump SQL, dan dokumentasi dalam satu perubahan agar semuanya tetap sinkron.