KaKaPP (Kertas Kerja Perencanaan Pajak)

Domain: Pendapatan Asli Daerah — Pemerintah Kota Palembang

Ruang Lingkup Domain

Aplikasi ini mengelola 14 jenis pajak daerah sesuai regulasi yang berlaku, antara lain: PBB-P2, BPHTB, PBJT (Makanan & Minuman, Listrik PLN/Non-PLN, Perhotelan, Parkir, Hiburan), Pajak Reklame, Pajak Air Tanah, Pajak MBLB, Pajak Sarang Burung Walet, serta Opsen PKB dan Opsen BBN-KB.

Data historis yang dikelola mencakup realisasi tahunan 2019–2024 dan realisasi bulanan kumulatif 2024–2026, yang menjadi dasar seluruh perhitungan proyeksi.

Arsitektur dan Stack Teknis

Aplikasi dibangun di atas stack PHP klasik tanpa framework — sebuah pilihan deliberate untuk kompatibilitas maksimal dengan shared hosting instansi pemerintah yang umumnya tidak mendukung Composer, Node.js, atau dependency manager modern.

Struktur aplikasi diorganisasikan ke dalam beberapa lapisan: konfigurasi dan autentikasi, mesin kalkulasi, halaman UI utama, aset frontend, dan kumpulan modul fungsional (manajemen user, workflow approval, upload bukti, ekspor laporan, dan panduan pengguna).

Database: MySQL 5.7+ / MariaDB 10.3+, dengan skema yang dikelola melalui migration file bertahap. Semua query menggunakan PDO dengan prepared statements.

Database Schema

Skema utama terdiri dari beberapa tabel inti:

tax_types — master data 14 jenis pajak daerah dengan slug sebagai identifier (misal: pbb_p2, bphtb, opsen_pkb).

realisasi — data target dan realisasi tahunan per jenis pajak per tahun. Unique constraint pada (tax_type_id, tahun) mencegah duplikasi.

proyeksi — hasil perhitungan proyeksi tersimpan, dengan kolom metode, nilai, dan sumber_data untuk traceability (apakah proyeksi berbasis data tahunan atau bulanan).

realisasi_bulanan (baru di v1.0.2) — realisasi kumulatif bulanan dengan field target_apbd_p untuk mengakomodasi perubahan anggaran di tengah tahun. Unique constraint pada (tax_type_id, tahun, bulan).

CREATE TABLE `realisasi_bulanan` (
  `id`                  INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  `tax_type_id`         INT UNSIGNED NOT NULL,
  `tahun`               YEAR NOT NULL,
  `bulan`               TINYINT UNSIGNED NOT NULL COMMENT '1=Jan s/d 12=Des',
  `target_tahunan`      DECIMAL(20,2) NOT NULL DEFAULT 0,
  `target_apbd_p`       DECIMAL(20,2) DEFAULT NULL,
  `realisasi_kumulatif` DECIMAL(20,2) NOT NULL DEFAULT 0,
  UNIQUE KEY `uq_bulanan` (`tax_type_id`, `tahun`, `bulan`),
  FOREIGN KEY (`tax_type_id`) REFERENCES `tax_types`(`id`) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

proyeksi_bulanan (baru di v1.0.2) — menyimpan hasil proyeksi per bulan per metode, memungkinkan perbandingan antar metode side-by-side di UI.

Mesin Proyeksi Statistik

Seluruh algoritma proyeksi diimplementasikan dalam PHP murni tanpa library eksternal. Semua fungsi kalkulasi terpusat dalam satu modul (~45 KB).

Metode Proyeksi Tahunan

1. Regresi Linear (OLS)
Menghitung slope dan intercept dari deret historis menggunakan formula Ordinary Least Squares. Cocok untuk pajak dengan tren pertumbuhan yang stabil dan linear.

2. Rata-rata Bergerak (3 Tahun)
Simple Moving Average dari tiga tahun terakhir. Berguna sebagai baseline konservatif ketika data historis terlalu pendek untuk regresi yang andal.

3. Pemulusan Eksponensial
Exponential Smoothing dengan α=0.3, memberikan bobot lebih besar pada data terkini dibanding data lama.

4. CAGR (Compound Annual Growth Rate)
Menghitung laju pertumbuhan majemuk dari data awal dan akhir periode historis. Berguna untuk pajak dengan pertumbuhan yang konsisten secara persentase.

5. Holt-Winters (Holt Linear)
Double Exponential Smoothing dengan parameter α=0.3 dan β=0.1 — mengestimasi level (komponen baseline) dan trend secara bersamaan. Lebih responsif terhadap perubahan tren dibanding metode lainnya.

6. Rata-rata Tertimbang (WMA)
Bobot 50% untuk tahun terbaru, 30% untuk tahun sebelumnya, dan 20% untuk tahun sebelumnya lagi. Hybrid antara recency bias dan kestabilan historis.

7. Baseline Rekomendasi ⭐
Ensemble dari rata-rata Linear, CAGR, dan WMA. Ini adalah metode default yang direkomendasikan sistem karena menyeimbangkan tiga pendekatan yang saling melengkapi.

Metode Proyeksi Musiman (Baru di v1.0.2)

Metode musiman diperkenalkan untuk menghasilkan proyeksi bulanan yang memperhitungkan pola musiman historis — misalnya, pajak parkir yang cenderung tinggi di bulan-bulan liburan, atau PBB-P2 yang punya pola penerimaan khas menjelang akhir tahun.

Dekomposisi Faktor Musiman
Menghitung proporsi kontribusi setiap bulan terhadap total tahunan dari data historis 3 tahun. Hasilnya berupa array 12 faktor (Jan–Des) yang masing-masing mewakili "berat" musiman bulan tersebut.

8. Holt-Winters Musiman
Proyeksi tahunan HW × faktor musiman per bulan. Menggabungkan estimasi tren dari HW dengan distribusi musiman historis.

9. Regresi Musiman
Proyeksi tahunan OLS × faktor musiman. Baseline tren yang lebih stabil dengan distribusi musiman.

10. CAGR Musiman
Proyeksi tahunan CAGR × faktor musiman. Cocok untuk pajak dengan pertumbuhan persentase yang konsisten.

11. Ensemble Musiman ⭐
Rata-rata sederhana dari metode 8, 9, dan 10 per bulan. Metode rekomendasi untuk proyeksi musiman karena meredam noise dari masing-masing metode individual.

Semua proyeksi musiman dapat dihitung untuk n+1 (2027) dan n+2 (2028) sekaligus dalam satu request.

Fitur Aplikasi

Dashboard

Ringkasan realisasi vs. target seluruh jenis pajak dengan progress bar dan persentase pencapaian. Menampilkan total pendapatan pajak daerah secara agregat. Tersedia dalam tampilan admin (edit) dan viewer (read-only).

Data Realisasi Tahunan

CRUD lengkap untuk data realisasi per jenis pajak per tahun. Validasi duplikasi dilakukan di backend sebelum INSERT. Tabel dilengkapi kolom target APBD, target APBD-P (perubahan), dan realisasi aktual, beserta otomatis kalkulasi persentase pencapaian.

Data Realisasi Bulanan

Modul baru di v1.0.2 dengan empat tab navigasi:

• Tabel — realisasi kumulatif per bulan dalam format grid, color-coded berdasarkan persentase pencapaian
• Grafik — trend line 3 tahun sekaligus untuk perbandingan visual
• Input — form input manual per baris
• Import — drag-and-drop CSV dengan format slug;target;target_APBD-P;Jan;Feb;...;Des

Fitur import CSV dilengkapi template siap pakai yang bisa diunduh, serta validasi format sebelum processing.

Proyeksi Tahunan

Pengguna memilih jenis pajak, tahun proyeksi (hingga n+5 dengan label n+1/n+2 untuk orientasi), dan metode. Sistem menampilkan preview hasil kalkulasi — termasuk perbandingan semua 7 metode — sebelum pengguna memutuskan untuk menyimpan ke database. Hanya role admin yang dapat menyimpan; viewer hanya mendapat preview.

Proyeksi Musiman

Menampilkan proyeksi bulanan n+1 dan n+2 dalam satu halaman:

• Grafik overlay: historis 3 tahun + proyeksi n+1 + proyeksi n+2
• Tabel faktor musiman per bulan dengan visualisasi bar
• Tabel perbandingan 4 metode side-by-side (HW, Regresi, CAGR, Ensemble)
• Tombol simpan proyeksi bulanan ke database

Analisis AI

Setelah kalkulasi proyeksi, pengguna dapat memicu analisis naratif otomatis. Sistem mengirimkan data proyeksi (3 skenario: konservatif, moderat, optimis) ke OpenRouter API dengan model qwen/qwen3-plus:free. Respons AI berupa insight profesional dalam Bahasa Indonesia.

Implementasi mencakup:

• Server-side API call — API key tidak pernah terekspos ke JavaScript
• File-based caching — hasil dicache 1 jam berdasarkan hash input, menghemat token dan mempercepat respons untuk query yang sama
• Timeout handling — 20 detik, dengan fallback message yang informatif
• Input sanitasi — sebelum dikirim ke API

Cetak & Export

Laporan realisasi dan proyeksi dapat dicetak langsung ke printer (via stylesheet print khusus yang menyembunyikan navigasi dan menyesuaikan layout untuk kertas) atau diekspor ke Excel.

Sistem Autentikasi dan Role

Autentikasi berbasis session PHP dengan hash password menggunakan fungsi bawaan PHP (password_hash / password_verify). Setiap halaman dilindungi oleh guard yang memeriksa session sebelum rendering konten apapun.

Empat role tersedia:

Pengecekan role dilakukan di dua lapisan: UI (tombol disembunyikan/dinonaktifkan) dan backend (validasi ulang sebelum eksekusi query).

Keamanan

• Akses langsung ke file konfigurasi dan direktori cache diblokir di level web server
• Semua query database menggunakan PDO prepared statements (mencegah SQL injection)
• CSRF token diimplementasikan pada form-form kritis
• API key AI disimpan sebagai environment variable server, tidak di-hardcode
• File-file setup dihapus dari server setelah proses instalasi selesai

Instalasi

Persyaratan: PHP 8.0+, MySQL 5.7+ / MariaDB 10.3+, Apache/Nginx, ekstensi PDO dan PDO_MySQL.

Proses instalasi mencakup: upload file ke web server, konfigurasi koneksi database, menjalankan migration SQL secara berurutan via phpMyAdmin, import data historis, lalu menghapus file-file setup dari server sebelum aplikasi digunakan.

Upgrade dari v1.0.x cukup dengan menimpa file lama dan menjalankan migration terbaru.

Catatan Pengembangan

Beberapa keputusan teknis yang layak dicatat:

Tidak ada framework. PHP murni dengan struktur include/require tradisional dipilih karena kebutuhan deployment ke shared hosting pemerintah yang sangat terbatas. Tidak ada Composer, tidak ada autoloader, tidak ada routing library.

Mesin kalkulasi sebagai monolith. Semua algoritma proyeksi ada dalam satu file besar (~45 KB). Ini memudahkan audit oleh pihak ketiga — semua logika bisnis kritis ada di satu tempat yang bisa dibuka dan dibaca tanpa harus menelusuri class hierarchy.

AJAX handler terpusat. Semua request asinkronus diarahkan ke satu endpoint dengan dispatch berbasis parameter action. Pola ini sederhana dan mudah di-trace saat debugging.

Migration file incremental. Skema database dikelola melalui tiga file SQL yang dijalankan berurutan, mencerminkan evolusi fitur dari v1.0.0 ke v1.0.2. Tidak ada migration runner otomatis — instruksi eksplisit di dokumentasi memandu admin untuk menjalankan secara manual via phpMyAdmin.

KaKaPP v1.0.2 — Dibuat untuk Pemerintah Kota Palembang.