[pandigresik]

Description

Menambahkan alur lengkap Bantuan Pengisian DataSpasial pada halaman dataspasial/impor agar operator kabupaten/Dinas dapat membantu desa yang belum memakai Modul DataSpasial dengan mengunggah data dari file. Fitur mencakup tiga langkah: unduh templat Excel per sektor & wilayah, unggah file yang sudah diisi, serta pratinjau via API-06 sebelum menyimpan. Template yang dihasilkan berformat XLSX dengan dropdown kode desa untuk meminimalkan kesalahan penulisan kode desa.

Changes made:

1. Exporter (Baru): app/Exports/ImporDataSpasialTemplateExport.php — membangun templat XLSX dari skema terbit: sheet Petunjuk, Data Impor (kolom kode_desa, nama_desa, kode_fasilitas, nama_fasilitas, plus satu kolom per item isian skema; baris konteks berisi Sektor & Periode), dan Daftar Desa. Menyuntikkan Excel data validation (dropdown) pada kolom kode_desa via olahan XML ZipArchive, dengan formula otomatis mengisi nama_desa sebagai konfirmasi.
2. Controller: app/Http/Controllers/DataSpasial/ImporDataController.php — mengimplementasikan index, downloadTemplate, upload, preview, dan save. upload memparse XLSX (OpenSpout) dengan deteksi header dinamis, menormalisasi kode_desa dari format Kode - Nama, dan menandai validitas kode desa. preview mengirim payload ke API-06 (membuang key internal _kode_valid) dan menormalisasi respons JSON:API menjadi struktur flat (ringkasan, baris[]).
3. Request Validation (Baru): DownloadTemplateRequest, PreviewImporRequest, UploadImporRequest — validasi sektor wajib, kecamatan opsional, serta jenis & ukuran file (xlsx, maks 10MB).
4. Service: app/Services/DataSpasialApiService.php — menambah imporPratinjau() (POST impor/pratinjau) dan imporSimpan() (POST impor/{impor_id}/simpan).
5. Routes: routes/web.php — menambah route GET/POST impor/template, POST impor/upload, POST impor/pratinjau, POST impor/simpan/{impor_id}, semuanya ber-permission dataspasial-impor-read.
6. View: resources/views/dataspasial/impor/index.blade.php — halaman impor tiga langkah dengan form filter (sektor, kecamatan/semua, periode), form unggah, tabel pratinjau dengan header dinamis (termasuk kolom isian), ringkasan Siap/Menimpa/Konflik/Galat, badge status per baris, tombol unduh laporan galat, dan tombol simpan kondisional (aktif hanya jika bisa_disimpan). Halaman reload otomatis setelah simpan berhasil.
7. Tests: tests/Feature/DataSpasial/ImporDataTest.php dan ImporDataTemplateTest.php — cakupan unduh templat XLSX, upload/parse, pratinjau ringkasan & baris galat, pembuangan key internal, dan kondisi tombol simpan.
8. Chore: .gitignore — menambahkan .gemini/.

Reason for change:

• Point 1: Desa yang belum memakai Modul DataSpasial sebelumnya tidak terdata, sehingga tidak muncul di peta/dasbor. Fitur ini memungkinkan kabupaten mengisi data mereka lewat file.
• Point 2: Template XLSX dengan dropdown kode desa dan kolom nama_desa otomatis mengurangi kesalahan input kode desa oleh pengguna.
• Point 3: Pratinjau dua tahap (OpenKab memvalidasi format, API memvalidasi isi terhadap skema) memastikan tidak ada data tersimpan sebelum operator menekan simpan, serta memberikan umpan balik galat per baris yang dapat diunduh.

Impact of change:

✅ Data lengkap: Desa tanpa Modul DataSpasial tetap terdata dan muncul di peta & dasbor.
✅ Akurasi input: Dropdown desa + auto-fill nama desa meminimalkan salah kode desa.
✅ Aman & terkontrol: Tidak ada tulis ke database sebelum simpan; akses dibatasi permission dataspasial-impor-read.
✅ Verifikasi jelas: Ringkasan + tabel galat dinamis + unduh laporan galat memudahkan pengguna memperbaiki file.

Related Issue

• Solution for feature related to issue [KAB-06] Impor data desa dari file: templat, unggah & pratinjau #1301 (Epic: Bantuan Pengisian, KAB-06)

#1301

Steps to Reproduce

Before (problem):

1. Buka menu Impor Data (dataspasial/impor).
2. Halaman hanya menampilkan kerangka menu / daftar fasilitas tanpa alur impor.
3. ❌ Tidak ada cara mengunduh templat, mengunggah, maupun pratinjau impor.

After (solution):

1. Buka menu Impor Data (dataspasial/impor).
2. Pilih Sektor, Kecamatan (atau "Semua Kecamatan"), dan Periode, lalu klik Unduh Templat → terunduh file .xlsx berisi sheet Petunjuk, Data Impor, dan Daftar Desa (dengan dropdown).
3. Isi templat (pilih kode desa dari dropdown), lalu unggah kembali lewat form Unggah → tabel pratinjau lokal muncul menampilkan baris hasil parsing dengan status validitas kode desa.
4. Klik Kirim ke Pratinjau (API) → ringkasan Siap/Menimpa/Konflik/Galat dan tabel laporan per baris tampil.
5. Jika ada galat, klik Unduh Laporan Galat.
6. Klik Simpan (aktif hanya jika dapat disimpan) → data tersimpan dan halaman reload otomatis.
7. ✅ Data desa berhasil diimpor lewat bantuan kabupaten.

Testing on related features:

• Unduh templat XLSX + dropdown desa ✅
• Unggah & parse XLSX ✅
• Pratinjau API-06 + ringkasan & laporan galat ✅
• Simpan kondisional ✅
• Kontrol akses permission ✅

Checklist

• I have complied with script writing rules
• I have followed pull request review process
• I have created [unit test/integration test] to verify the fix
• Manual testing has been done in development environment
• No console errors or warnings
• Code has been reviewed by [at least 1 person]

Technical Details

Technical Explanation

Alur tiga langkah dengan validasi berlapis:

Unduh Templat (XLSX)
  → ImporDataSpasialTemplateExport: sheet Petunjuk + Data Impor + Daftar Desa
  → Data validation dropdown pada kolom A (kode_desa) + formula VLOOKUP nama_desa
        │
Unggah XLSX
  → OpenSpout Reader → deteksi baris header (kode_desa + kode_fasilitas)
  → normalisasi kode_desa ("Kode - Nama" → kode), tandai _kode_valid
  → simpan sementara di Session (impor_parsed)
        │
Pratinjau (API-06)
  → POST /dataspasial/impor/pratinjau (payload dibersihkan dari key internal)
  → normalizePreview(): JSON:API attributes → { impor_id, ringkasan, baris[] }
        │
Simpan (API-06)
  → POST /impor/{impor_id}/simpan
  → Session dibersihkan, halaman reload

• Parsing & validasi format dilakukan di OpenKab (ImporDataController::parseFile).
• Validasi isi terhadap skema dilakukan di API Satu Data.
• Semua panggilan tulis ke API melalui server-side (DataSpasialApiService), token tidak terekspos ke browser.

Configuration changes

Tidak ada perubahan konfigurasi wajib (menggunakan app.databaseGabunganUrl dan API key yang sudah ada).

Dependencies added

Tidak ada dependency baru. Memakai openspout/openspout yang sudah tersedia untuk menulis/membaca XLSX.

Testing

Manual Testing

• Unduh templat XLSX dengan pilihan satu kecamatan dan semua kecamatan
• Dropdown kode desa tampil & nama_desa terisi otomatis
• Unggah file hasil templat dan tampilkan pratinjau lokal
• Kirim ke pratinjau API dan tampilkan ringkasan + laporan per baris
• Unduh laporan galat saat terdapat baris galat
• Tombol simpan nonaktif sebelum pratinjau dan saat bisa_disimpan=false
• Halaman reload setelah simpan berhasil
• Akses menu ditolak untuk peran tanpa permission

Automated Testing

• Feature Test — test_menu_impor_bisa_diakses_oleh_user_dengan_permission
• Feature Test — test_upload_file_xlsx_diparse
• Feature Test — test_preview_mengembalikan_ringkasan_dan_baris_galat
• Feature Test — test_payload_pratinjau_membuang_key_internal
• Feature Test — test_preview_simpan_diizinkan_saat_bisa_disimpan_true
• Feature Test — test_template_download_xlsx_with_desa_list_and_dropdown

Menjalankan: php artisan test tests/Feature/DataSpasial/ImporDataTest.php tests/Feature/DataSpasial/ImporDataTemplateTest.php

Screenshots / Video

simplescreenrecorder-2026-10-21_08.31.49.mp4

Before:

Halaman dataspasial/impor hanya kerangka menu/daftar fasilitas tanpa alur impor.

After:

Halaman impor tiga langkah sesuai acuan OpenKab-1301_KAB-06_impor-data.png:

• Form filter Sektor / Kecamatan / Periode + tombol Unduh Templat
• Form unggah file XLSX
• Tabel pratinjau dengan penanda baris (siap/menimpa/galat) + ringkasan + tombol unduh laporan galat
• Tombol simpan kondisional

Breaking Changes

None

Migration Guide

Not required

References

• Issue: [KAB-06] Impor data desa dari file: templat, unggah & pratinjau #1301
• Dependency KAB-01: [KAB-01] Klien API Satu Data, menu & peran #1296
• Dependency API-06: https://github.com/OpenSID/API-Database-Gabungan/issues/472
• Terkait SID-06: https://github.com/OpenSID/modul_dataspasial/issues/6
• Spec: specs/007-bantuan-pengisian/spec.md

---

Additional notes: Template memakai sheet terpisah Daftar Desa sebagai sumber dropdown; jika daftar desa kosong, dropdown tidak disuntikkan agar file tetap valid. Parsing XLSX mendeteksi baris header secara dinamis sehingga tahan terhadap baris konteks tambahan di atas header.

[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 #1313