WebGIS_Project/04/README.md

# 🗺️ WebGIS Persebaran Penduduk Miskin

**Sistem Pemetaan Geospasial berbasis React + Node.js + PostgreSQL/PostGIS**

---

## 📋 DAFTAR ISI

1. [Prasyarat](#prasyarat)
2. [Instalasi PostgreSQL + PostGIS di XAMPP](#instalasi-postgresql--postgis)
3. [Setup Database](#setup-database)
4. [Setup Backend (Node.js)](#setup-backend)
5. [Setup Frontend (React)](#setup-frontend)
6. [Menjalankan Aplikasi](#menjalankan-aplikasi)
7. [Struktur Folder](#struktur-folder)
8. [API Endpoint Reference](#api-endpoint-reference)
9. [Troubleshooting](#troubleshooting)

---

## ✅ PRASYARAT

Sebelum mulai, pastikan sudah terinstal:

| Software | Versi Minimum | Link Download |
|----------|--------------|---------------|
| **XAMPP** | 8.0+ | https://www.apachefriends.org |
| **Node.js** | 18.x LTS | https://nodejs.org |
| **PostgreSQL** | 14+ | https://www.postgresql.org/download |
| **PostGIS** | 3.x | Diinstal via Stack Builder |
| **Git** (opsional) | any | https://git-scm.com |

> ⚠️ **PENTING**: PostgreSQL dan PostGIS TIDAK termasuk dalam XAMPP standar.
> XAMPP hanya menyediakan MySQL/MariaDB. Kita install PostgreSQL secara terpisah.

---

## 🐘 INSTALASI POSTGRESQL + POSTGIS

### Langkah 1: Install PostgreSQL

1. Download PostgreSQL dari https://www.postgresql.org/download/windows/
2. Jalankan installer, ikuti wizard:
   - Port: **5432** (default)
   - Password superuser: catat dengan baik (contoh: `postgres123`)
   - Locale: sesuaikan (Indonesian)
3. ✅ Centang "Stack Builder" di akhir instalasi

### Langkah 2: Install PostGIS via Stack Builder

1. Stack Builder otomatis terbuka setelah instalasi PostgreSQL
2. Pilih server PostgreSQL Anda
3. Expand kategori **Spatial Extensions**
4. Centang **PostGIS** (versi terbaru)
5. Klik Next dan ikuti proses download + instalasi
6. Saat diminta "Create spatial database", **LEWATI** (kita buat manual)

### Langkah 3: Verifikasi Instalasi

Buka **SQL Shell (psql)** dari Start Menu:
```sql
-- Login dengan user postgres
Password: [password yang Anda buat]

-- Cek PostGIS
SELECT PostGIS_version();
-- Output: "3.x USE_GEOS=1 ..."
```

---

## 🗄️ SETUP DATABASE

### Langkah 1: Buat Database

Buka **pgAdmin 4** (tersedia di Start Menu setelah install PostgreSQL):

1. Klik kanan **Databases** → **Create** → **Database**
2. Isi nama: `webgis_kemiskinan`
3. Klik **Save**

**ATAU** via SQL Shell (psql):
```sql
CREATE DATABASE webgis_kemiskinan;
\c webgis_kemiskinan
```

### Langkah 2: Jalankan Script SQL

**Via pgAdmin 4:**
1. Klik dua kali database `webgis_kemiskinan`
2. Klik kanan → **Query Tool**
3. Buka file: `database/schema.sql` (dari folder project)
4. Klik tombol **▶ Execute** (F5)

**Via psql:**
```bash
# Pastikan Anda ada di folder project
psql -U postgres -d webgis_kemiskinan -f database/schema.sql
```

**Via Command Prompt:**
```cmd
cd C:\xampp\htdocs\webgis-kemiskinan
"C:\Program Files\PostgreSQL\14\bin\psql.exe" -U postgres -d webgis_kemiskinan -f database\schema.sql
```

### Langkah 3: Verifikasi Database

```sql
-- Di pgAdmin Query Tool atau psql:
\c webgis_kemiskinan

-- Cek tabel
\dt

-- Output yang diharapkan:
-- tabel_rumah_ibadah
-- tabel_penduduk
-- tabel_anggota_keluarga

-- Cek data dummy
SELECT nama, jenis FROM tabel_rumah_ibadah;
SELECT nama_kepala_keluarga FROM tabel_penduduk;

-- Cek PostGIS aktif
SELECT PostGIS_version();
```

---

## ⚙️ SETUP BACKEND

### Langkah 1: Masuk ke Folder Backend

```bash
cd webgis-kemiskinan\backend
```

### Langkah 2: Install Dependensi

```bash
npm install
```

### Langkah 3: Konfigurasi Environment

Salin file `.env.example` menjadi `.env`:

```bash
# Windows
copy .env.example .env

# Linux/Mac
cp .env.example .env
```

Edit file `.env` sesuai konfigurasi Anda:

```env
# Server
PORT=5000
NODE_ENV=development

# Database PostgreSQL
DB_HOST=localhost
DB_PORT=5432
DB_NAME=webgis_kemiskinan
DB_USER=postgres
DB_PASSWORD=postgres123    ← GANTI dengan password Anda

# CORS
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Upload
UPLOAD_DIR=uploads
MAX_FILE_SIZE=5242880

# Nominatim
NOMINATIM_URL=https://nominatim.openstreetmap.org
NOMINATIM_USER_AGENT=WebGIS-Kemiskinan/1.0
```

### Langkah 4: Buat Folder Upload

```bash
mkdir uploads
```

### Langkah 5: Test Koneksi

```bash
npm run dev
```

Output yang diharapkan:
```
🚀 Server berjalan di http://localhost:5000
✅ Terhubung ke PostgreSQL + PostGIS
📡 Mode: development
```

Test via browser atau Postman:
```
GET http://localhost:5000/api/health
```
Response: `{"status":"ok","timestamp":"..."}`

---

## 🎨 SETUP FRONTEND

### Langkah 1: Masuk ke Folder Frontend

Buka terminal/CMD **baru**:

```bash
cd webgis-kemiskinan\frontend
```

### Langkah 2: Install Dependensi

```bash
npm install
```

### Langkah 3: Jalankan Development Server

```bash
npm run dev
```

Output:
```
  VITE v5.x.x  ready in 800ms

  ➜  Local:   http://localhost:3000/
  ➜  Network: http://192.168.x.x:3000/
```

### Langkah 4: Buka di Browser

Buka: **http://localhost:3000**

---

## 🚀 MENJALANKAN APLIKASI (RINGKASAN)

Setiap kali ingin menjalankan aplikasi, buka **2 terminal terpisah**:

### Terminal 1 – Backend
```bash
cd webgis-kemiskinan\backend
npm run dev
```

### Terminal 2 – Frontend
```bash
cd webgis-kemiskinan\frontend
npm run dev
```

Lalu buka browser: **http://localhost:3000**

---

## 📁 STRUKTUR FOLDER

```
webgis-kemiskinan/
│
├── 📂 database/
│   └── schema.sql              # Script SQL lengkap (jalankan pertama kali)
│
├── 📂 backend/
│   ├── package.json
│   ├── .env.example            # Salin ke .env dan isi konfigurasi
│   ├── .env                    # Konfigurasi lokal Anda (jangan di-commit)
│   └── src/
│       ├── server.js           # Entry point Express
│       ├── config/
│       │   └── database.js     # Koneksi PostgreSQL Pool
│       ├── controllers/
│       │   ├── rumahIbadahController.js    # CRUD + geospasial ibadah
│       │   ├── pendudukController.js       # CRUD + auto-assign ibadah
│       │   ├── geocodeController.js        # Reverse geocoding Nominatim
│       │   └── dashboardController.js      # Statistik & agregasi
│       ├── routes/
│       │   ├── rumahIbadah.js
│       │   ├── penduduk.js
│       │   ├── geocode.js
│       │   ├── upload.js
│       │   └── dashboard.js
│       ├── middleware/
│       │   └── upload.js       # Multer file upload config
│       └── uploads/            # Folder penyimpanan file upload
│
└── 📂 frontend/
    ├── package.json
    ├── vite.config.js          # Proxy API ke backend
    ├── index.html
    └── src/
        ├── main.jsx            # React entry point
        ├── App.jsx             # Router + Layout utama
        ├── index.css           # Global styles (dark theme)
        ├── services/
        │   └── api.js          # Axios API client
        └── pages/
            ├── DashboardPage.jsx   # Statistik & grafik
            ├── MapPage.jsx         # Peta interaktif Leaflet
            ├── RumahIbadahPage.jsx # CRUD rumah ibadah
            └── PendudukPage.jsx    # CRUD penduduk miskin
```

---

## 📡 API ENDPOINT REFERENCE

### Rumah Ibadah

| Method | Endpoint | Deskripsi |
|--------|----------|-----------|
| GET | `/api/rumah-ibadah` | Semua rumah ibadah. Query: `?jenis=Masjid` |
| GET | `/api/rumah-ibadah/:id` | Detail + statistik penduduk |
| GET | `/api/rumah-ibadah/terdekat` | Query: `?lat=X&lng=Y&limit=5` |
| POST | `/api/rumah-ibadah` | Tambah baru |
| PUT | `/api/rumah-ibadah/:id` | Update |
| DELETE | `/api/rumah-ibadah/:id` | Hapus |

### Penduduk Miskin

| Method | Endpoint | Deskripsi |
|--------|----------|-----------|
| GET | `/api/penduduk` | Semua. Query: `?status_bantuan=true&limit=50` |
| GET | `/api/penduduk/:id` | Detail + anggota keluarga |
| POST | `/api/penduduk` | Tambah (multipart/form-data, auto-assign ibadah) |
| PUT | `/api/penduduk/:id` | Update (multipart/form-data) |
| PATCH | `/api/penduduk/:id/status` | Update status bantuan saja |
| DELETE | `/api/penduduk/:id` | Hapus |

### Lainnya

| Method | Endpoint | Deskripsi |
|--------|----------|-----------|
| GET | `/api/geocode/reverse` | Query: `?lat=X&lng=Y` |
| POST | `/api/upload` | Upload file (form field: `file`) |
| GET | `/api/dashboard/statistik` | Data statistik dashboard |
| GET | `/api/health` | Health check server |

---

## 🔧 TROUBLESHOOTING

### ❌ Error: "ECONNREFUSED – Cannot connect to database"

**Penyebab:** PostgreSQL tidak berjalan atau password salah.

**Solusi:**
1. Buka **Services** Windows (services.msc)
2. Cari **postgresql-x64-14** → Klik **Start**
3. Atau di Command Prompt: `net start postgresql-x64-14`
4. Periksa password di file `.env`

---

### ❌ Error: "extension 'postgis' does not exist"

**Penyebab:** PostGIS belum terinstal atau belum diaktifkan di database.

**Solusi:**
```sql
-- Di pgAdmin, koneksi ke database webgis_kemiskinan
CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
```

---

### ❌ Error: "npm: command not found"

**Penyebab:** Node.js belum terinstal atau belum ada di PATH.

**Solusi:**
1. Download Node.js LTS dari https://nodejs.org
2. Install dengan pilih "Add to PATH"
3. Restart Command Prompt / terminal
4. Test: `node --version` dan `npm --version`

---

### ❌ Error: "Port 5000 already in use"

**Solusi:**
```cmd
# Temukan proses yang menggunakan port 5000
netstat -ano | findstr :5000

# Kill proses (ganti XXXX dengan PID)
taskkill /PID XXXX /F
```
ATAU ganti port di `.env`: `PORT=5001`

---

### ❌ Peta tidak muncul (blank/grey)

**Penyebab:** Leaflet CSS tidak termuat dengan benar.

**Solusi:**
Pastikan di file yang menggunakan Leaflet ada:
```js
import 'leaflet/dist/leaflet.css';
```

---

### ❌ Reverse Geocoding gagal

**Penyebab:** Nominatim rate limit (max 1 request/detik) atau tidak ada internet.

**Solusi:**
- Tunggu beberapa detik lalu coba kembali
- Nominatim memerlukan koneksi internet aktif
- Isi alamat secara manual jika offline

---

### ❌ Upload file gagal

**Penyebab:** Folder `uploads` tidak ada.

**Solusi:**
```bash
cd backend
mkdir uploads
```

---

## 🌐 INTEGRASI XAMPP (Apache sebagai Reverse Proxy Opsional)

Jika ingin mengakses via `http://localhost/webgis` (tanpa port):

1. Aktifkan **mod_proxy** di XAMPP:
   Edit `C:\xampp\apache\conf\httpd.conf`, hilangkan tanda `#` dari:
   ```
   LoadModule proxy_module modules/mod_proxy.so
   LoadModule proxy_http_module modules/mod_proxy_http.so
   ```

2. Tambahkan konfigurasi di `httpd-vhosts.conf`:
   ```apache
   <VirtualHost *:80>
     ProxyPass /api http://localhost:5000/api
     ProxyPassReverse /api http://localhost:5000/api
     DocumentRoot "C:/xampp/htdocs/webgis-kemiskinan/frontend/dist"
   </VirtualHost>
   ```

3. Build frontend: `cd frontend && npm run build`

4. Restart Apache di XAMPP Control Panel

---

## 📦 BUILD UNTUK PRODUCTION

### Frontend (Build Statis)
```bash
cd frontend
npm run build
# Output: folder dist/ siap di-deploy
```

### Backend (Jalankan Tanpa nodemon)
```bash
cd backend
npm start
# Atau dengan PM2: pm2 start src/server.js --name webgis-backend
```

---

## 💡 TIPS PENGGUNAAN

1. **Menambah Rumah Ibadah**: Masuk ke menu "Rumah Ibadah" → Klik "Tambah" → Klik peta untuk memilih lokasi → Alamat otomatis terisi → Simpan

2. **Menambah Penduduk**: Masuk ke menu "Penduduk Miskin" → Klik "Tambah" → Klik peta untuk memilih lokasi rumah → Sistem otomatis menentukan rumah ibadah terdekat

3. **Melihat di Peta**: Masuk ke menu "Peta Interaktif" → Gunakan filter untuk menyaring tampilan → Klik marker untuk melihat detail

4. **Update Status Bantuan**: Di tabel Penduduk, klik tombol ✓ untuk toggle status sudah/belum dibantu

5. **Lokasi Saya**: Di halaman peta, klik tombol kompas 📍 untuk menampilkan posisi Anda

---

## 📄 LISENSI

MIT License – Bebas digunakan untuk keperluan pendidikan dan sosial.

---

*Dibuat dengan ❤️ untuk membantu pemetaan dan penanganan kemiskinan di Indonesia*