[pandigresik]

Description

Implementasi fitur Monitoring Pengisian & Kualitas Data Desa (KAB-07) sesuai OpenSID/OpenKab#1303. Fitur ini menyediakan dasbor monitoring terpusat bagi Bappeda/Dinas Kabupaten untuk memantau status pengisian data spasial seluruh desa, mendeteksi desa yang belum pernah mengirim atau tertinggal versi skema, memantau persentase kelengkapan dan skor kualitas data, serta mengekspor laporan bulanan desa dalam format CSV.

Halaman ini dibangun dengan konsep skeleton initial load (tanpa memuat seluruh data desa di awal untuk menjaga performa), di mana data diambil secara asinkron (AJAX) berdasarkan filter sektor dan kecamatan yang dipilih. Seluruh data dikonsolidasikan langsung dari API Satu Data (adopsi #468, skema & riwayat #468, nilai & ringkasan #469) tanpa menambah tabel database lokal baru.

Changes made:

1. [Backend] Controller (app/Http/Controllers/DataSpasial/MonitoringController.php)

   • Memperluas kerangka controller untuk menangani alur monitoring: index() (skeleton view dengan dropdown sektor yang di-cache 30 menit), data() (respons JSON kartu, tabel, dan metadata paginasi), serta ekspor() (stream download berkas CSV laporan bulanan).
   • Menegakkan keamanan berbasis permission dataspasial-monitoring-read.

2. [Backend] Service (app/Services/MonitoringDataSpasialService.php - Baru)

   • Pipeline tunggal perhitungan monitoring desa (memastikan konsistensi data antara kartu, tabel, dan ekspor CSV).
   • Integrasi data dari API Satu Data via DataSpasialApiService dan reuse AdopsiDesaService.
   • Mengagregasikan status adopsi seluruh desa (termasuk desa yang belum pernah mengirim data).
   • Menghitung persentase kelengkapan isian berdasarkan isian aktif versi terbit terbaru (isianAktif).
   • Mengidentifikasi status versi skema (mutakhir vs tertinggal) dan sumber data (desa, impor, pemetaan).
   • Menghitung 3 kartu ringkasan: Sudah mengisi, Belum pernah mengirim, dan Perlu diperiksa (desa dengan versi skema tertinggal / perlu tindakan).
   • Mengurutkan data secara default dengan mendahulukan desa yang membutuhkan tindakan (perlu_tindakan = true), diikuti abjad nama desa.
   • Mengimplementasikan ekspor CSV via StreamedResponse (hingga 5.000 baris) lengkap dengan metadata header komentar # (periode, tanggal pembuatan, filter).

3. [Backend] Validation Request

   • app/Http/Requests/DataSpasial/MonitoringDataRequest.php (Baru): Validasi parameter filter query (sektor wajib string max:50, kode_kecamatan opsional, periode opsional format YYYY-MM, page & per_page).

4. [Frontend & View] Komponen Reusable & Halaman Monitoring

   • resources/views/components/dataspasial-filter-konteks.blade.php (Baru): Komponen Blade pakai-ulang pembungkus filter sektor dan kecamatan.
   • resources/views/components/dataspasial-dropdown-sektor.blade.php (Baru): Komponen dropdown sektor.
   • resources/views/components/dataspasial-dropdown-kecamatan.blade.php (Baru): Komponen dropdown kecamatan dengan opsi "Semua Kecamatan".
   • resources/views/dataspasial/monitoring/index.blade.php (Diperbarui): Tampilan monitoring dengan 3 kartu ringkasan, penanganan state (loading spinner, validasi filter, data kosong, dan layanan tidak tersedia), tabel data desa (kolom: Desa, Kecamatan, Kelengkapan, Kualitas, Status), paginasi, dan tombol Ekspor CSV.
   • public/js/dataspasial/monitoring.js (Baru): Script interaktif client-side untuk memuat data via AJAX, menangani perubahan filter & sinkronisasi URL query string, merender kartu ringkasan dan bilah progres kelengkapan, penanganan paginasi, serta ekspor CSV tanpa reload halaman.

5. [Routing] (routes/web.php)

   • Mendaftarkan endpoint monitoring di bawah middleware permission dataspasial-monitoring-read:
     • GET /dataspasial/monitoring/data (dataspasial.monitoring.data)
     • GET /dataspasial/monitoring/ekspor (dataspasial.monitoring.ekspor)

6. [Testing & Fixtures]

   • tests/Feature/DataSpasial/Fixtures.php: Menambahkan fixtures lengkap untuk kebutuhan KAB-07 (adopsi desa, ringkasan per desa, nilai per desa dengan beragam sumber, skema dan isian aktif, serta daftar wilayah kecamatan).
   • tests/Feature/DataSpasial/MonitoringDataTest.php (Baru): Rangkaian feature test komprehensif mencakup proteksi autentikasi & permission, skeleton render, validasi filter, penampilan seluruh desa (termasuk belum mengisi), kalkulasi kartu ringkasan & semantik baris, paginasi, filter kecamatan, penanganan periode, fallback graceful error saat API unavailable, dan urutan prioritas tindakan desa.

Reason for change:

• Bappeda memerlukan visibilitas pendampingan: Memastikan program Satu Data Spasial tidak berhenti di peluncuran. Kabupaten perlu mengetahui secara cepat desa mana yang pasif (belum pernah mengisi) atau tertinggal versi skemanya agar pendampingan lapangan dapat dialokasikan tepat sasaran.
• Transparansi status & sumber data: Mengetahui apakah data suatu desa diisi mandiri oleh operator desa, hasil impor bantuan kabupaten, atau hasil pemetaan.
• Kemandirian operasional & pelaporan: Menyediakan laporan bulanan CSV siap unduh untuk kebutuhan rapat koordinasi dan evaluasi rutin dinas/Bappeda.

Impact of change:

✅ Cakupan Lengkap: Semua desa di wilayah kabupaten terpantau, termasuk desa yang belum pernah mengirimkan data sama sekali.
✅ Ringkasan Cepat: Tiga kartu ringkasan langsung memberikan gambaran makro kepatuhan desa tanpa perlu kalkulasi manual.
✅ Prioritas Jelas: Tabel otomatis mengurutkan desa yang membutuhkan perhatian/tindakan di baris teratas.
✅ Performa Optimal: Menggunakan pagination dan rendering AJAX; data upstream di-cache sesuai standar.
✅ Aman & Non-destruktif: Hanya operasi baca (read-only), tidak memutasi data desa maupun skema database OpenKab.

---

Masalah Terkait (Related Issue)

• Solusi untuk implementasi fitur sesuai issue OpenSID/OpenKab#1303 (Epic: Monitoring, KAB-07).
• Terkait di sistem lain: OpenSID/API-Database-Gabungan#469 (API-04).
• Bergantung pada: OpenSID/OpenKab#1298 (KAB-03) & OpenSID/OpenKab#1300 (KAB-05).

---

Langkah untuk mereproduksi (Steps to Reproduce)

Sebelum implementasi:

1. Masuk ke halaman /dataspasial/monitoring.
2. Halaman hanya menampilkan kerangka kosong / belum terintegrasi dengan data riil desa.
3. ❌ Tidak ada informasi status desa, tidak ada kartu ringkasan, dan tidak ada fitur ekspor laporan.

Setelah implementasi:

1. Masuk ke halaman /dataspasial/monitoring dengan akun yang memiliki hak akses dataspasial-monitoring-read.
2. Pilih Sektor (misal: "Kesehatan") dan Kecamatan (atau "Semua Kecamatan").
3. ✅ Tiga kartu ringkasan menampilkan angka agregat:
   • Desa sudah mengisi (misal: 12/25)
   • Belum pernah mengirim (misal: 10)
   • Perlu diperiksa (misal: 3 desa dengan versi skema tertinggal)
4. ✅ Tabel menampilkan daftar seluruh desa lengkap dengan:
   • Bilah persentase kelengkapan isian
   • Skor kualitas
   • Badge status pengisian, versi skema, dan asal sumber data (desa/impor/pemetaan)
5. Ubah halaman melalui pagination atau pilih kecamatan tertentu untuk mempersempit lingkup.
6. Klik tombol Ekspor CSV → berkas monitoring-laporan-{periode}-{timestamp}.csv terunduh dengan metadata lengkap.

Testing pada fitur lain yang terkait:

• Halaman dasbor indikator spasial (KAB-05) ✅ Tetap berfungsi normal
• Halaman bantuan pengisian / impor data (KAB-06) ✅ Tetap berfungsi normal
• Integrasi API Satu Data & Session ✅ Stabil

---

Daftar Periksa (Checklist)

• Saya telah mematuhi aturan penulisan script.
• Saya telah mengikuti proses review pull request.
• Saya telah membuat unit test / feature test untuk memverifikasi fitur baru (MonitoringDataTest.php).
• Testing manual telah dilakukan di environment development.
• Tidak ada console error atau warning pada JavaScript (monitoring.js).
• Code sudah di-review oleh minimal 1 orang reviewer.

---

Teknis Detail

Penjelasan Teknis

Arsitektur aliran data fitur monitoring:

[ Browser / Client ]
       │  (1) GET /dataspasial/monitoring (Skeleton + List Sektor di-cache)
       │  (2) AJAX GET /dataspasial/monitoring/data?sektor=...&kode_kecamatan=...&periode=...
       ▼
[ MonitoringController ]
       │  Validasi via MonitoringDataRequest
       ▼
[ MonitoringDataSpasialService ]
       │  ├── AdopsiDesaService::ambilSemua() (Cakupan semua desa & status adopsi)
       │  ├── DataSpasialApiService::listSkema() (Ambil isian aktif versi terbit terbaru)
       │  ├── DataSpasialApiService::ringkasan() (Keberadaan desa ber-data per periode)
       │  └── DataSpasialApiService::nilai() (Rincian per desa: isian, sumber_data, kelengkapan)
       ▼
[ Kompilasi & Agregasi ]
       │  ├── Hitung kelengkapan (%) & status versi skema
       │  ├── Hitung kartu ringkasan (sudah mengisi / belum mengirim / perlu tindakan)
       │  ├── Sorting (prioritas: perlu_tindakan DESC, nama_desa ASC)
       │  └── Server-side pagination
       ▼
[ JSON Response / Streamed CSV ]

• Peta status per desa: Berdasarkan klarifikasi analisis teknis, monitoring peta berada di luar lingkup (peta gabungan terpusat di KAB-04/dasbor).
• Ekspor CSV: Menggunakan response()->streamDownload() dan native PHP fputcsv untuk efisiensi memori (memory footprint rendah) dengan batas pengamanan hingga 5.000 baris.

Konfigurasi yang berubah:

• Tidak ada penambahan konfigurasi .env baru. Menggunakan koneksi dan token database_gabungan_api_key yang sudah ada di Setting.

Dependencies yang ditambahkan:

• Tidak ada dependensi Composer atau NPM baru.

---

Testing

Manual Testing

• Buka /dataspasial/monitoring sebagai pengguna tanpa izin dataspasial-monitoring-read → 403 Forbidden.
• Buka /dataspasial/monitoring sebagai pengguna terotorisasi → skeleton dan filter ter-render tanpa me-load data desa sebelum filter dipilih.
• Pilih sektor tanpa kecamatan → otomatis memilih "Semua Kecamatan" dan memuat seluruh desa se-kabupaten.
• Verifikasi kemunculan desa yang belum pernah mengisi (status belum_pernah_mengirim).
• Verifikasi perhitungan 3 kartu ringkasan sesuai jumlah baris agregat.
• Verifikasi bilah kelengkapan data desa dan badge asal data (desa, impor, pemetaan).
• Uji paginasi tabel (per halaman 25 baris) dan pengurutan desa prioritas tindakan di posisi awal.
• Klik tombol Ekspor CSV dan verifikasi header metadata # serta kecocokan baris data dengan tabel.
• Simulasi API Satu Data unavailable → muncul banner peringatan ramah pengguna tanpa crash/500 error.

Automated Testing (Pest / PHPUnit)

• tests/Feature/DataSpasial/MonitoringDataTest.php:
  • test_guest_is_redirected
  • test_user_without_permission_is_rejected
  • test_page_renders_without_data_desa
  • test_data_requires_sektor_but_kecamatan_is_optional
  • test_all_desa_appear_including_never_submitted
  • test_cards_and_row_semantics_match_fixtures
  • test_pagination_works_without_status_or_name_filters
  • test_kecamatan_scope_uses_wilayah_list_and_keeps_unregistered_desa
  • test_periods_default_from_adopsi_and_unknown_period_is_empty
  • test_unavailable_returns_generic_message
  • test_row_order_puts_action_needed_first

---

Screenshots / Video

Acuan Tampilan:

Mengacu pada tangkapan layar acuan: OpenKab-1303_KAB-07_monitoring-desa.png

Tampilan Hasil:

• Tiga kartu ringkasan di bagian atas: Desa sudah mengisi, Belum pernah mengirim, dan Perlu diperiksa.
• Filter sektor dan kecamatan di atas tabel.
• Tabel kelengkapan dengan kolom Desa, Kecamatan, Kelengkapan (progress bar), Kualitas, dan Status.
• Tombol aksi Ekspor CSV di header tabel.

---

Breaking Changes

• Tidak ada (None). Fitur ini menambahkan fungsionalitas baru pada menu monitoring yang sebelumnya masih berupa kerangka kosong.

Migration Guide

• Tidak diperlukan. Tidak ada migrasi tabel baru atau perubahan struktur database MySQL lokal.

References

• Issue GitHub: OpenSID/OpenKab#1303
• API Satu Data: OpenSID/API-Database-Gabungan#469

[github-actions]

🔄 AI PR Review sedang antri di server...

Proses review akan segera dimulai di background — hasil akan muncul sebagai komentar setelah selesai.
Powered by CrewAI · PR #1314