# AITax Starter Kit — skrip replikasi untuk Bapenda/BPKAD

Enam skrip Python untuk mereplikasi dua jalur kerja AITax di daerah Anda. Semua skrip
**hanya memakai pustaka bawaan Python 3.9+**, jadi tidak perlu `pip install` apa pun.
Cocok dijalankan di laptop kantor biasa.

> **Data contoh di folder `contoh/` seluruhnya fiktif.** Nama usaha, kecamatan, dan angka
> dibuat untuk latihan, bukan data pemerintah daerah mana pun.

Panduan lengkap (tim, dasar hukum, langkah per jalur, jadwal 12 minggu):
https://aitax-sanggabiz.vercel.app/panduan

Alur kerja tiap langkah diperagakan di https://aitax-sanggabiz.vercel.app/wp-baru (Jalur B)
dan https://aitax-sanggabiz.vercel.app/proyeksi (Jalur A).

## Isi kit

| Berkas | Jalur | Fungsi |
| --- | --- | --- |
| `1_panen_places.py` | B | Panen data usaha lewat Google Places API (resmi, berbayar per panggilan) |
| `2_bersihkan.py` | B | Buang duplikat, verifikasi wilayah, saring kategori 3 keranjang |
| `3_cocokkan_register.py` | B | Pisahkan yang sudah terdaftar dari kandidat WP baru |
| `4_skor_prioritas.py` | B | Skor 0–100 dan daftar survei berperingkat + cakupan per kecamatan |
| `5_backtest_proyeksi.py` | A | Adu 7 metode proyeksi, pilih lewat MAPE, keluarkan rentang target |
| `6_rfm_wp.py` | A | Segmentasi kepatuhan WP (Andalan, Patuh, Mulai Renggang, Hilang) |
| `kamus_kategori.csv` | B | Aturan tipe/kata kunci → sektor dan keranjang (inti / abu-abu / luar) |
| `template_data_transaksi.csv` | A | Format data setoran yang diminta dari SIMPATDA/e-PAD |
| `template_register_wp.csv` | B | Format register WP untuk pencocokan |

## Coba dulu dengan data contoh (5 menit)

Buka Terminal (macOS/Linux) atau Command Prompt (Windows), masuk ke folder kit, lalu:

```bash
python3 2_bersihkan.py --masukan contoh/contoh_panen.csv --batas contoh/contoh_batas_kecamatan.geojson --keluaran bersih.csv
python3 3_cocokkan_register.py --objek bersih.csv --register contoh/contoh_register.csv --keluaran hasil_cocok.csv
python3 4_skor_prioritas.py --masukan hasil_cocok.csv --keluaran daftar_survei.csv
python3 5_backtest_proyeksi.py --masukan contoh/contoh_transaksi.csv
python3 6_rfm_wp.py --masukan contoh/contoh_transaksi.csv
```

Di Windows, ganti `python3` dengan `python` atau `py`.

## Memakai data daerah Anda

### Jalur B — WP baru dari jejak digital

1. **Siapkan API key.** Buat proyek di Google Cloud Console, aktifkan *Places API (New)*,
   aktifkan penagihan, buat API key, dan batasi key itu hanya untuk Places API.
   Cek harga dan kuota gratis bulanan terbaru di halaman harga Google Maps Platform.
2. **Rencanakan panen** tanpa biaya:
   ```bash
   python3 1_panen_places.py --bbox LAT_MIN,LNG_MIN,LAT_MAKS,LNG_MAKS --kata-kunci hotel restoran kafe karaoke --rencana
   ```
3. **Panen:**
   ```bash
   export GOOGLE_PLACES_API_KEY="api-key-anda"      # Windows: set GOOGLE_PLACES_API_KEY=api-key-anda
   python3 1_panen_places.py --bbox ... --kata-kunci ... --keluaran panen.csv
   ```
4. **Batas wilayah:** minta GeoJSON batas kecamatan ke Bappeda, atau unduh dari Ina-Geoportal (BIG).
   Pastikan tiap poligon punya properti `kecamatan` (atau sebutkan nama propertinya lewat `--properti-nama`).
5. **Register WP:** ekspor dari SIMPATDA/e-PAD mengikuti `template_register_wp.csv`. Nama kolom boleh
   berbeda — sebutkan lewat `--kolom-npwpd`, `--kolom-nama`, `--kolom-kecamatan`.
6. Jalankan langkah 2 → 3 → 4 seperti contoh di atas.
7. **Periksa manual** baris berstatus `PERLU_CEK`, lalu **uji petik lapangan** 30–50 kandidat teratas
   sebelum hasilnya dipakai untuk penetapan.

### Jalur A — proyeksi target

1. Minta ekspor setoran **level transaksi** dari SIMPATDA/e-PAD mengikuti `template_data_transaksi.csv`:
   satu baris per setoran, dengan **tanggal bayar asli** (bukan tanggal ketetapan) dan nominal.
   Jangan pakai data rekap per tahun atau per kecamatan.
2. Minimal 5 tahun lengkap per jenis pajak. Jangan ikutkan tahun berjalan yang belum genap:
   ```bash
   python3 5_backtest_proyeksi.py --masukan transaksi.csv --tahun-akhir 2025
   ```
3. Baca hasilnya sebagai **rentang**. Titik rekomendasi untuk usulan APBD; batas atas sebagai
   sasaran kerja internal, bukan pagu formal.

## Kustomisasi yang paling sering

- **Kamus kategori** — sesuaikan `kamus_kategori.csv` dengan Perda PDRD daerah Anda,
  terutama keranjang `abu-abu` (kos harian, angkringan, tempat wisata).
- **Ambang pencocokan** — `--ambang-dekat`, `--ambang-kecamatan`, `--ambang-lintas`.
  Naikkan bila terlalu banyak salah cocok; turunkan bila terlalu banyak WP lama muncul sebagai baru.
- **Bobot skor** — `--bobot ULASAN RATING HARGA KATEGORI CELAH`, mis. `--bobot 40 10 20 10 20`.

## Rambu yang wajib dipatuhi

- **Jangan scraping halaman Google Maps, OTA, atau aplikasi pesan-antar** secara langsung.
  Itu melanggar ketentuan layanan platform. Gunakan API resmi atau kerja sama data.
- **Data register dan transaksi WP adalah data pribadi/rahasia jabatan.** Simpan di perangkat dinas,
  jangan unggah ke layanan publik, dan perhatikan UU No. 27 Tahun 2022 tentang Pelindungan Data Pribadi.
- **Hasil skrip adalah daftar kerja, bukan dasar penetapan.** Penetapan NPWPD tetap melalui
  verifikasi lapangan sesuai prosedur daerah.

---
Kit ini disediakan apa adanya oleh sanggabiz sebagai bahan belajar. Bebas dipakai dan diubah
untuk keperluan pemerintah daerah.