# PANDUAN ADAPTASI PERUBAHAN FORMAT RKA & DPA SIPD
**Aplikasi Konversi RKA / DPA Non-Database (`konversirka_nodb`)**

Dokumen ini adalah buku panduan teknis dan **Master Prompt Siap Pakai** yang dirancang agar AI (Antigravity, Claude, ChatGPT, Gemini, dll) atau pengembang dapat langsung menyesuaikan sistem ketika format ekspor **RKA** (Rencana Kerja dan Anggaran) maupun **DPA** (Dokumen Pelaksanaan Anggaran) dari **SIPD / SIPD-RI** mengalami perubahan struktur, tata letak, kolom, atau format file.

---

## DAFTAR ISI
1. [Arsitektur Pemrosesan File di Sistem Ini](#1-arsitektur-pemrosesan-file)
2. [Peta File & Tanggung Jawab Kode](#2-peta-file--tanggung-jawab-kode)
3. [Pola Perubahan Format SIPD yang Sering Terjadi](#3-pola-perubahan-format-sipd-yang-sering-terjadi)
4. [MASTER PROMPT SIAP PAKAI (Salin & Tempel ke AI)](#4-master-prompt-siap-pakai)
   - [Prompt 1: Master Prompt Universal (Semua Jenis Perubahan)](#prompt-1-master-prompt-universal-semua-jenis-perubahan)
   - [Prompt 2: Perubahan Struktur Kolom Excel SIPD Baru](#prompt-2-perubahan-struktur-kolom-excel-sipd-baru)
   - [Prompt 3: Perubahan Layout / Format Cetak PDF SIPD](#prompt-3-perubahan-layout--format-cetak-pdf-sipd)
   - [Prompt 4: Diagnosis Cepat & Perbaikan Error Parsing](#prompt-4-diagnosis-cepat--perbaikan-error-parsing)
5. [SOP Penyesuaian Kode Langkah demi Langkah](#5-sop-penyesuaian-kode-langkah-demi-langkah)
6. [Kaidah Emas: Prinsip Backward Compatibility](#6-kaidah-emas-prinsip-backward-compatibility)

---

## 1. ARSITEKTUR PEMROSESAN FILE

Aplikasi ini memproses dua jenis input utama:
1. **File Excel (`.xlsx`)**: Berasal dari ekspor langsung rincian belanja sub kegiatan di SIPD/SIPD-RI.
2. **File PDF (`.pdf`)**: Berasal dari cetak digital resmi RKA/DPA SKPD dari SIPD-RI.

Alur pemrosesan data:
```
[File Input: Excel / PDF SIPD]
             │
             ▼
[Sanitasi & Pembacaan Buffer] (JSZip / PDF.js)
             │
             ▼
[Ekstraksi Metadata & Header Dokumen] (SKPD, Sub Kegiatan, Indikator, Pagu)
             │
             ▼
[Deteksi Dinamis Kolom & Baris Awal] (Cari 'BELANJA DAERAH', Koefisien, Satuan, Harga, dll)
             │
             ▼
[Normalisasi Rekening Belanja & BAS] (Kode Rekening 6 Segmen, Paket [#], Subpaket [-], Spesifikasi)
             │
             ▼
[Penyusunan Model Data Internal] (Array belanjaRows terstandarisasi)
             │
             ▼
[Pembangkitan Output Excel Resmi]
  ├─ Format 2026 P (Perubahan - 18 Kolom: Sebelum, Sesudah, Selisih, Formula)
  └─ Format 2027 (Murni - 12 Kolom: Koefisien, Satuan, Harga, PPN, Jumlah)
```

---

## 2. PETA FILE & TANGGUNG JAWAB KODE

Apabila format SIPD berubah, file-file berikut yang menjadi target penyesuaian:

| File | Lokasi | Bagian yang Menangani |
|---|---|---|
| `js/converter.js` | [`c:/xampp/htdocs/konversirka_nodb/js/converter.js`](file:///c:/xampp/htdocs/konversirka_nodb/js/converter.js) | **Logika Utama Ekstraksi Excel**: `extractDataFromExcel()`, deteksi jenis dokumen `detectDocumentMeta()`, normalisasi uraian & spesifikasi `cleanProportionalUraian()`, pencocokan kode BAS `resolveStandardBasAccount()`, dan penulisan lembar Excel `generateRkaWorkbook()`. |
| `js/pdfParser.js` | [`c:/xampp/htdocs/konversirka_nodb/js/pdfParser.js`](file:///c:/xampp/htdocs/konversirka_nodb/js/pdfParser.js) | **Logika Ekstraksi PDF**: `parsePdfRka()`, pemindaian teks per koordinat X/Y, deteksi pembagi kolom (boundary), rekonstruksi tabel multi-halaman, dan penanganan header halaman berulang (*page break repeat*). |
| `js/parser.js` | [`c:/xampp/htdocs/konversirka_nodb/js/parser.js`](file:///c:/xampp/htdocs/konversirka_nodb/js/parser.js) | **Utilitas Parsing Teks & Angka**: `parseNumber()` (format Rupiah Indo ke float), `extractString()`, `cleanPrefix()`, `splitCode()` (pemecah segmen kode rekening). |
| `js/formatSettings.js` | [`c:/xampp/htdocs/konversirka_nodb/js/formatSettings.js`](file:///c:/xampp/htdocs/konversirka_nodb/js/formatSettings.js) | Konfigurasi SQLite/JSON untuk master template kolom, pemetaan program sasaran, dan standar honor PPTK. |
| `js/app.js` | [`c:/xampp/htdocs/konversirka_nodb/js/app.js`](file:///c:/xampp/htdocs/konversirka_nodb/js/app.js) | Handler UI upload file, dispatch parsing ke converter/PDF parser, penanganan antrean batch file. |

---

## 3. POLA PERUBAHAN FORMAT SIPD YANG SERING TERJADI

1. **Perubahan Posisi Header & Baris Belanja:**
   - Baris "BELANJA DAERAH" bergeser (misal dari baris 33 menjadi baris 45 atau 60 karena penambahan baris indikator kinerja).
2. **Perubahan Posisi Kolom Rincian:**
   - Urutan kolom diubah Kemendagri: misal kolom PPN dihilangkan, atau digabung ke kolom Harga, atau penambahan kolom TKDN (Tingkat Komponen Dalam Negeri) / Sumber Dana di kolom tersendiri.
3. **Format Kode Rekening Diubah:**
   - Kode rekening dipisah menjadi 6 kolom berbeda (Kolom 1: Akun, Kolom 2: Kelompok, Kolom 3: Jenis, dst.) alih-alih digabung bertitik `5.1.02.01.001.00080`.
   - Kode rekening digabung dalam satu kolom bersama nama rekening (misal: `"5.1.02.01.001.00080 - Belanja Alat Tulis Kantor"`).
4. **Perubahan Format Nama Tahap / Dokumen:**
   - Label diubah dari `RKA-SKPD` menjadi `DPA-SKPD`, `DPPA-SKPD`, `RKA Perubahan`, `RKA Parsial`, atau `DPA Lanjutan`.
5. **Perubahan Pemecah Item / Spesifikasi:**
   - Tanda paket `[#]` atau `[-]` diganti dengan format indentasi baris, penomoran romawi, atau kolom level khusus.

---

## 4. MASTER PROMPT SIAP PAKAI

> **Petunjuk Penggunaan:**  
> Salin salah satu prompt di bawah ini dan berikan langsung kepada AI (misal: Antigravity IDE Chat) saat Anda mendapati format SIPD mengalami pembaruan.

---

### PROMPT 1: MASTER PROMPT UNIVERSAL (SEMUA JENIS PERUBAHAN)

```markdown
Halo AI, format file ekspor (RKA / DPA) dari SIPD-RI mengalami perubahan.
Tolong sesuaikan algoritma parsing dan konversi di proyek `konversirka_nodb` ini agar dapat membaca format baru tersebut dengan sempurna tanpa merusak format sebelumnya.

Berikut informasi dan contoh file/struktur format baru:
1. Jenis File: [Sebutkan: Excel .xlsx / PDF]
2. Jenis Dokumen: [Sebutkan: RKA Murni / RKA Perubahan / DPA / DPPA / dll]
3. Perubahan yang Terjadi:
   - [Jelaskan ringkas perubahannya, contoh: urutan kolom berubah, ada kolom baru, posisi kode rekening bergeser, atau baris indikator bertambah]
4. Contoh Baris Header / Baris Data Baru:
   [Lampirkan cuplikan teks header tabel, baris akun, baris paket [#], baris item belanja, atau nama file]

Instruksi Tugas untuk Anda:
1. Buka dan periksa `js/converter.js` (untuk Excel) atau `js/pdfParser.js` (untuk PDF) serta utilitas di `js/parser.js`.
2. Analisis bagaimana fungsi `extractDataFromExcel()` atau `parsePdfRka()` saat ini mendeteksi:
   - Baris metadata & indikator
   - Baris awal rincian belanja (`startR` / kata kunci 'BELANJA DAERAH')
   - Indeks kolom dinamis (koefisien, satuan, harga, PPN, jumlah untuk Sebelum & Sesudah)
   - Pemisahan kode rekening, paket [#], subpaket [-], dan uraian item/spesifikasi.
3. Modifikasi logika deteksi agar fleksibel (gunakan dynamic heuristic / fallback matching) sehingga BISA membaca format baru ini SEKALIGUS TETAP KOMPATIBEL dengan format lama (backward-compatible).
4. Pastikan data yang dihasilkan tetap tersusun rapi menjadi struktur `belanjaRows` standar yang siap diekspor ke format template output (2026 P 18 kolom & 2027 Murni 12 kolom).
5. Jelaskan bagian kode mana saja yang Anda ubah dan sertakan uji coba verifikasinya.
```

---

### PROMPT 2: PERUBAHAN STRUKTUR KOLOM EXCEL SIPD BARU

```markdown
Halo AI, format kolom tabel Excel hasil unduhan SIPD mengalami perubahan susunan kolom.
File target yang perlu disesuaikan adalah `js/converter.js` pada fungsi `extractDataFromExcel()`.

Detail format baru dari SIPD:
- Judul Header Kolom Utama: [Contoh: Kode Rekening | Uraian | Koefisien | Satuan | Harga | PPN | TKDN | Sub Total]
- Susunan Kolom Rincian: [Jelaskan urutan kolom Sebelum dan/atau Sesudah jika dokumen perubahan]
- Ciri Khas Baris Header: Baris header rincian berada di sekitar baris: [contoh: 25 s.d 40]

Instruksi:
1. Perbarui logika pemindaian header di `converter.js` (bagian `mainRow` dan `subRow`):
   - Deteksi kolom `colKode`, `colUraian`, `colStartSeb`, `colStartSes`, `colStartDiff`.
   - Deteksi subkolom: `colKSeb`, `colSSeb`, `colHSeb`, `colPSeb`, `colJSeb` dan `colKSes`, `colSSes`, `colHSes`, `colPSes`, `colJSes`.
2. Jika ada kolom tambahan seperti "TKDN", "Keterangan", atau "Sumber Dana" di kolom terpisah, tangkap nilainya dan integrasikan ke metadata baris uraian.
3. Pastikan pencarian kolom menggunakan pencocokan kata kunci toleran huruf besar-kecil (`.toLowerCase()`) dan wildcard kata kunci (misal: kata "bertambah/berkurang", "selisih", "perubahan", "sesudah", "setelah").
4. Jamin tidak terjadi *offset index* (-1) atau nilai `NaN` pada pembacaan koefisien/harga.
5. Pertahankan kompatibilitas dengan format ekspor SIPD lama (12, 13, 15, 20, dan 22 kolom).
```

---

### PROMPT 3: PERUBAHAN LAYOUT / FORMAT CETAK PDF SIPD

```markdown
Halo AI, cetakan PDF resmi RKA/DPA dari SIPD-RI mengalami perubahan tata letak (layout/koordinat teks).
File target penyesuaian adalah `js/pdfParser.js`.

Kendala/Perubahan yang terjadi pada PDF baru:
- Gejala: [Contoh: teks kolom terpotong / kolom harga tertukar dengan PPN / baris header berulang di halaman 2+ ikut terbaca sebagai item belanja / kode rekening tidak terdeteksi]
- Orientasi Dokumen: [Landscape / Portrait]
- Jumlah Kolom Fisik: [Contoh: 7 kolom untuk Murni / 13 kolom untuk Perubahan / Format baru lainnya]

Instruksi:
1. Periksa fungsi ekstraksi baris & kolom di `js/pdfParser.js` (khususnya clustering baris horizontal berdasarkan koordinat Y dan clustering kolom berdasarkan koordinat X).
2. Perbarui regex pembersih teks header berulang (*page header rejection*) agar baris kop SKPD di setiap lembar tidak bocor menjadi rincian belanja.
3. Perbaiki toleransi batas kolom (X-boundaries) agar angka volume/koefisien, satuan, harga satuan, dan total jumlah tidak saling tumpang tindih.
4. Pastikan parser dapat mengenali pembatas paket `[#]` dan sub-paket `[-]` dengan benar.
5. Verifikasi bahwa output akhir yang dikembalikan oleh `parsePdfRka()` memiliki format objek yang identik dengan hasil `extractDataFromExcel()`.
```

---

### PROMPT 4: DIAGNOSIS CEPAT & PERBAIKAN ERROR PARSING

```markdown
Halo AI, file SIPD berikut ini gagal dikonversi atau menghasilkan nilai yang keliru saat diproses di aplikasi:
- Nama File: [Tulis nama file contoh]
- Error di Browser Console: [Tempel teks error jika ada, misal: Cannot read properties of undefined...]
- Masalah Tampilan: [Contoh: Total Belanja menjadi Rp 0, atau baris uraian belanja kosong, atau kode rekening hilang]

Instruksi:
1. Identifikasi pada tahap apa parsing gagal:
   - Apakah sanitasi JSZip di awal `extractDataFromExcel`?
   - Apakah penentuan baris awal `startR` (pencarian kata 'BELANJA DAERAH')?
   - Apakah deteksi nama kolom (`colUraian`, `colStartSes`, dll)?
   - Apakah pembersihan regex di `cleanProportionalUraian` atau `parseNumber`?
2. Buka file sumber contoh di folder workspace jika tersedia (misal file .xlsx atau .pdf yang diunggah) dan periksa struktur baris/kolomnya.
3. Terapkan *safety guard* / *null check* pada baris yang menyebabkan crash.
4. Buat fallback cerdas: jika kata kunci tertentu tidak ditemukan, gunakan pemindaian heuristik alternatif.
5. Jalankan verifikasi dan laporkan solusinya.
```

---

## 5. SOP PENYESUAIAN KODE LANGKAH DEMI LANGKAH

Jika Anda atau AI melakukan modifikasi kode secara mandiri, ikuti urutan langkah berikut:

### Langkah 1: Diagnosis File Input Baru
1. Buka file `.xlsx` menggunakan Excel atau inspeksi lewat skrip Node.js / Python scratch.
2. Catat nomor baris:
   - Di baris ke berapa nama Sub Kegiatan dan OPD berada?
   - Di baris ke berapa teks tabel dimulai?
   - Di baris ke berapa kata **"BELANJA DAERAH"** atau kode **"5"** muncul?
3. Catat indeks kolom (A, B, C, ... atau 1, 2, 3, ...):
   - Kolom Kode Rekening: Kolom berapa? Apakah terpisah atau digabung?
   - Kolom Uraian: Kolom berapa?
   - Kolom Koefisien / Volume: Kolom berapa?
   - Kolom Satuan: Kolom berapa?
   - Kolom Harga Satuan: Kolom berapa?
   - Kolom PPN: Kolom berapa?
   - Kolom Jumlah / Total: Kolom berapa?

### Langkah 2: Sesuaikan Deteksi Header di `js/converter.js`
Periksa blok pencarian baris awal di `extractDataFromExcel`:
```javascript
// Lokasi: js/converter.js
for (let r = 15; r <= 80; r++) { // Naikkan batas pencarian jika baris indikator bertambah
  let rowTxt = '';
  for (let c = 1; c <= 8; c++) {
    rowTxt += ' ' + extractString(srcWs.getCell(r, c).value);
  }
  // Tambahkan kata kunci variasi baru jika SIPD mengubah sebutan belanja
  if (/\bBELANJA\s+DAERAH\b/i.test(rowTxt) || /\b5\s+BELANJA\b/i.test(rowTxt) || ...) {
    startR = r;
    break;
  }
}
```

### Langkah 3: Sesuaikan Deteksi Kolom Dinamis
Pastikan pencarian kata kunci kolom mencakup variasi penamaan baru dari SIPD:
```javascript
// Lokasi: js/converter.js
for (let c = colStartSes; c <= endSes; c++) {
  const v = extractString(subRow.getCell(c).value).toLowerCase();
  if ((v.includes('koefisien') || v.includes('volume')) && colKSes === -1) colKSes = c;
  else if (v.includes('satuan') && colSSes === -1) colSSes = c;
  else if ((v.includes('harga') || v.includes('tarif')) && colHSes === -1) colHSes = c;
  else if (v.includes('ppn') && colPSes === -1) colPSes = c;
  else if ((v.includes('jumlah') || v.includes('total')) && colJSes === -1) colJSes = c;
}
```

### Langkah 4: Sesuaikan Pembacaan Kode Rekening & Hierarki Akun
Jika SIPD memisahkan segmen rekening ke dalam kolom bertingkat (misal kolom 1 s/d 6 masing-masing berisi 5, 1, 02, 01, dst.), pastikan `activeAccountStack` menyusunnya kembali:
```javascript
// Lokasi: js/converter.js
if (/^[0-9]+$/.test(val)) {
  segParts.push({ col: c, val: val });
}
```

### Langkah 5: Validasi Rumus Output & Format Akhir
Pastikan baris yang dihasilkan tetap mematuhi struktur data internal:
```javascript
{
  type: 'item',          // 'header' | 'paket' | 'subpaket' | 'item'
  kode: '5.1.02.01...',
  uraian: 'Kertas HVS A4 80gr',
  spek: 'Spesifikasi : Putih 80 gsm',
  sumberDana: 'DAU',
  // Data Sebelum (jika perubahan)
  kSeb: '10 Rim',
  hSeb: 55000,
  jSeb: 550000,
  // Data Sesudah
  kSes: '15 Rim',
  hSes: 55000,
  pSes: 0,
  jSes: 825000
}
```

---

## 6. KAIDAH EMAS: PRINSIP BACKWARD COMPATIBILITY

Saat memodifikasi kode untuk format baru, **PATUHI 4 KAIDAH INI**:

1. **JANGAN PERNAH MENGHAPUS LOGIKA FORMAT LAMA:**
   - Gunakan pendekatan bertingkat (*chain of fallbacks*). Contoh: periksa format baru terlebih dahulu, jika pola kolom tidak cocok, otomatis gunakan logika format lama.
2. **GUNAKAN REGEX / PENCOCOKAN YANG TOLERAN:**
   - Hindari *hardcoded* nomor kolom statis (seperti `getCell(r, 7)`). Selalu cari kolom melalui nama header (`v.includes('koefisien')`).
3. **PEMBERSIHAN SPASI DAN KARAKTER KHUSUS:**
   - Ekspor SIPD sering mengandung spasi non-breaking (`\u00A0`), karakter enter ganda (`\r\n`), atau tag HTML tersembunyi. Selalu gunakan `extractString()` dan pembersih spasi regex `/\s+/g`.
4. **UJI DENGAN FILE FORMAT LAMA & BARU:**
   - Setelah kode diperbarui, selalu uji kembali konversi dengan file sampel tahun sebelumnya (format 2026 P dan 2027 Murni) untuk memastikan tidak terjadi regresi (*regression bug*).

---

*Dokumen ini dibuat secara otomatis untuk repository `konversirka_nodb`. Simpan file ini di root repository agar siap digunakan sewaktu-waktu format SIPD berubah.*