sibedas/OPTIMIZED_TABLE_STRUCTURE.md

Struktur Tabel Retribusi PBG yang Dioptimalkan

Ringkasan Optimasi

Struktur tabel baru ini lebih sederhana, fokus pada perhitungan, dan menghilangkan redundansi dari struktur sebelumnya.

Perbandingan Struktur

SEBELUM (Kompleks)

• building_functions - 8 kolom + relationship kompleks
• building_function_parameters - 12 kolom dengan mismatch model/migration
• retribution_formulas - Menyimpan formula sebagai string
• retribution_proposals - 15+ kolom dengan banyak redundansi
• floor_height_indices - OK, tidak berubah

SESUDAH (Sederhana)

• building_types - 7 kolom, hierarki sederhana
• retribution_indices - 6 kolom, parameter calculation saja
• height_indices - 3 kolom, sama seperti sebelumnya
• retribution_configs - 5 kolom, konfigurasi global
• retribution_calculations - 8 kolom, hasil perhitungan saja

---

Detail Struktur Tabel Baru

1. building_types

Fungsi: Menyimpan jenis fungsi bangunan dengan hierarki sederhana

Kolom	Tipe	Keterangan
id	bigint	Primary key
code	varchar(10)	Kode unik (UMKM, KEAGAMAAN, dll)
name	varchar(100)	Nama fungsi bangunan
parent_id	bigint	ID parent (untuk hierarki)
level	tinyint	Level hierarki (1=parent, 2=child)
coefficient	decimal(8,4)	Koefisien untuk perhitungan
is_free	boolean	Apakah gratis (keagamaan, MBR)

2. retribution_indices

Fungsi: Menyimpan parameter indeks untuk perhitungan (1:1 dengan building_types)

Kolom	Tipe	Keterangan
id	bigint	Primary key
building_type_id	bigint	FK ke building_types
ip_permanent	decimal(8,4)	Indeks Permanensi
ip_complexity	decimal(8,4)	Indeks Kompleksitas
locality_index	decimal(8,4)	Indeks Lokalitas
infrastructure_factor	decimal(8,4)	Faktor prasarana (default 50%)

3. height_indices

Fungsi: Indeks ketinggian per lantai (sama seperti sebelumnya)

Kolom	Tipe	Keterangan
id	bigint	Primary key
floor_number	tinyint	Nomor lantai (1,2,3,4,5,6)
height_index	decimal(8,6)	IP Ketinggian (1.0, 1.09, 1.12, dst)

4. retribution_configs

Fungsi: Konfigurasi global untuk perhitungan (menggantikan hard-coded values)

Kolom	Tipe	Keterangan
id	bigint	Primary key
key	varchar(50)	Kunci konfigurasi
value	decimal(15,2)	Nilai konfigurasi
description	varchar(200)	Deskripsi

Data yang disimpan:

• BASE_VALUE = 70350 (nilai dasar)
• INFRASTRUCTURE_MULTIPLIER = 0.5 (50% prasarana)
• HEIGHT_MULTIPLIER = 0.5 (pengali indeks ketinggian)

5. retribution_calculations

Fungsi: Hasil perhitungan retribusi (history)

Kolom	Tipe	Keterangan
id	bigint	Primary key
calculation_id	varchar(20)	ID unik perhitungan
building_type_id	bigint	FK ke building_types
floor_number	tinyint	Lantai yang dipilih
building_area	decimal(12,2)	Luas bangunan input
retribution_amount	decimal(15,2)	Hasil perhitungan
calculation_detail	json	Detail breakdown perhitungan
calculated_at	timestamp	Waktu perhitungan

---

Formula Perhitungan

Formula Excel yang Diimplementasikan:

H13 = coefficient * (ip_permanent + ip_complexity + (0.5 * height_index))

Main Calculation = building_area * (locality_index * BASE_VALUE * H13)

Infrastructure = INFRASTRUCTURE_MULTIPLIER * Main Calculation

Total Retribution = Main Calculation + Infrastructure

Implementasi dalam Service:

// Step 1: Calculate H13 coefficient
$h13 = $buildingType->coefficient * (
    $indices->ip_permanent +
    $indices->ip_complexity +
    (0.5 * $heightIndex)
);

// Step 2: Main calculation
$mainCalculation = $buildingArea * ($indices->locality_index * $baseValue * $h13);

// Step 3: Infrastructure (50% additional)
$infrastructureCalculation = 0.5 * $mainCalculation;

// Step 4: Total
$totalRetribution = $mainCalculation + $infrastructureCalculation;

---

Keuntungan Struktur Baru

✅ Simplicity

• 5 tabel vs 8+ tabel sebelumnya
• Kolom minimal hanya yang diperlukan untuk perhitungan
• No redundant data seperti ip_ketinggian di proposals

✅ Performance

• Proper indexes untuk query yang sering digunakan
• Normalized structure mengurangi storage
• Cached configs untuk values yang jarang berubah

✅ Maintainability

• Clear separation antara master data dan calculation results
• Configurable values tidak hard-coded lagi
• Single responsibility setiap tabel punya tujuan jelas

✅ Flexibility

• Easy to extend untuk fungsi bangunan baru
• Configurable formulas lewat RetributionConfig
• Audit trail lewat calculation history

✅ Data Integrity

• Proper constraints untuk validasi data
• Foreign key relationships yang benar
• No model-migration mismatch

---

Migration Guide

Langkah Implementasi:

1. Run Migration: php artisan migrate untuk tabel baru
2. Seed Data: Data master berdasarkan Excel akan otomatis ter-seed
3. Update Code: Ganti penggunaan model lama dengan model baru
4. Test Calculation: Verifikasi hasil perhitungan sama dengan Excel
5. Deploy: Struktur siap production

Data Migration (Optional):

Jika ada data existing di tabel lama yang perlu dipindahkan, buat script migration untuk transfer data dari struktur lama ke struktur baru.

---

Usage Example

// Initialize service
$calculator = new RetributionCalculatorService();

// Calculate retribution
$result = $calculator->calculate(
    buildingTypeId: 8, // UMKM
    floorNumber: 2,    // 2 lantai
    buildingArea: 100.50, // 100.5 m2
    saveResult: true   // Simpan ke database
);

// Result structure
[
    'building_type' => [...],
    'total_retribution' => 31658.25,
    'formatted_amount' => 'Rp 31,658.25',
    'calculation_steps' => [...],
    'calculation_id' => 'RTB-20250130140530-123'
]

Struktur ini jauh lebih clean, mudah dipahami, dan optimal untuk perhitungan retribusi PBG!