# SIPIUTANG

**Sistem Informasi Piutang, Average Collection Period, Monitoring Penagihan, dan Pelaporan Keuangan Fleksibel**

Versi 1.0.0 · PHP 8.1+ · MySQL 5.7+ / MariaDB 10.4+ · Berjalan di shared hosting cPanel tanpa Node.js

---

## Ringkasan

SIPIUTANG adalah aplikasi web yang menggantikan pengelolaan piutang berbasis workbook Excel
`AR RPP 2026.xlsx` milik PT Roto-Rooter Indonesia. Sistem ini tidak sekadar memindahkan isi
Excel ke basis data — ia **menghitung ulang seluruh nilai turunan di sisi server** memakai
aturan bisnis yang terdokumentasi, sehingga kesalahan rumus yang ada pada workbook lama
tidak ikut terbawa.

### Yang diperbaiki dari workbook Excel

| Temuan | Dampak | Penanganan |
|---|---|---|
| Rumus umur piutang mengacu ke kolom teks (OUTLET) | 3.446 sel rusak, Rp 306.751.504 hilang dari aging | Umur piutang dihitung ulang oleh server |
| Invoice lama dan penggantinya sama-sama dihitung | Rp 152.794.500 pendapatan ganda | Tautan revisi lama–baru; hanya pengganti yang dihitung |
| Empat invoice ditandai LUNAS padahal bersaldo | Rp 9.557.300 tidak tertagih | Status ditentukan dari saldo, bukan ketikan manual |
| Saldo hilang dari bucket 46–120 hari | 133 invoice, Rp 214.717.017 | Dipulihkan ke bucket yang benar |
| Nilai error `#REF!`, `#VALUE!`, `#DIV/0!` | Perhitungan gagal | Dinormalkan menjadi nol dan ditandai |
| Penulisan area/jenis pekerjaan tidak seragam | Pengelompokan salah | Tabel pemetaan nilai |

Selisih total bruto sistem (Rp 8.949.764.840) terhadap Excel (Rp 8.951.353.970) adalah
tepat Rp 1.589.130 — dua invoice yang tercatat ganda pada dua lembar berbeda.
Setiap rupiah selisih dapat ditelusuri melalui menu **Kualitas Data → Rekonsiliasi Excel**.

---

## Fitur Utama

- **Dashboard** — 16 kartu KPI, 13 grafik, 13 filter, dan drill-down ke rincian invoice.
- **Piutang & Aging** — bucket bawaan 0–45 / 46–90 / 91–120 / >120 hari ditambah bucket
  yang dapat dikonfigurasi sendiri, dihitung terhadap saldo yang masih terutang.
- **ACP / DSO** — dua metode (standar finansial dan operasional penagihan), target per
  periode dan lingkup, indikator hijau/kuning/merah, tren bulanan, dan perbandingan periode.
- **Pembayaran** — tabel transaksi tersendiri yang mendukung pembayaran bertahap, uang muka,
  retensi, pelunasan, refund, pembalikan, dan penyesuaian, dengan alokasi ke banyak invoice.
- **Revisi Invoice (RF)** — tautan lama–baru, pencegahan pendapatan ganda, pencocokan otomatis,
  penerapan yang dapat dibatalkan, dan deteksi celah penomoran.
- **Import Excel** — wizard 10 langkah, 24 validasi, uji coba tanpa menyimpan, riwayat batch,
  unduh baris gagal, dan pembatalan batch.
- **Pembuat Laporan Fleksibel** — 7 sumber data, 15 operator filter, 9 fungsi agregasi,
  pengelompokan, subtotal, grand total, pivot, 8 jenis grafik, dan template yang dapat dibagikan.
- **25 laporan siap pakai** untuk kebutuhan rutin.
- **Penagihan** — worklist 7 kategori, tindak lanjut, janji bayar dengan evaluasi otomatis,
  dan 10 status penagihan.
- **Kualitas Data** — 20 pemeriksaan otomatis beserta saran tindakan dan rekonsiliasi
  terhadap nilai Excel asli.
- **RBAC** — 6 peran, 99 hak akses per modul dan tindakan, serta pembatasan cakupan data
  per pengguna.
- **Persetujuan & Audit** — 9 alur persetujuan, jejak audit lengkap dengan nilai lama dan baru.
- **Ekspor** — Excel, CSV, PDF, dan cetak, selalu menghormati filter dan kolom yang aktif.
- **Antarmuka sepenuhnya berbahasa Indonesia**, format Rupiah dan tanggal Indonesia,
  zona waktu Asia/Jakarta.

---

## Prinsip Teknis

**Nol dependensi wajib.** Seluruh fungsi berjalan tanpa Composer, tanpa Node.js, dan tanpa
CDN. Sistem memiliki implementasi internal untuk:

| Kebutuhan | Implementasi internal | Alternatif opsional |
|---|---|---|
| Membaca `.xlsx` | `ExcelReader` — ZipArchive + XMLReader, termasuk perluasan *shared formula* | PhpSpreadsheet |
| Menulis `.xlsx` | `ExcelWriter` — styles, freeze pane, autofilter, format Rupiah | PhpSpreadsheet |
| Membuat PDF | `PdfWriter` — PDF 1.4, header berulang, subtotal, blok tanda tangan | Dompdf |
| Menulis CSV | `CsvWriter` — BOM UTF-8, pencegahan injeksi formula | — |

Bila PhpSpreadsheet atau Dompdf terpasang melalui Composer, sistem mendeteksi dan
memakainya secara otomatis. Aset front-end (Bootstrap 5.3.3, Bootstrap Icons 1.11.3,
Chart.js 4.4.3) disertakan langsung di `public/assets/vendor/`.

**Perhitungan di sisi server.** Tidak ada perhitungan piutang yang dilakukan di peramban.
Seluruh nilai turunan dihitung oleh `ArCalculator` dan disimpan, sehingga laporan,
ekspor, dan tampilan selalu memakai angka yang sama.

**Keamanan.** PDO dengan *prepared statement* dan `ATTR_EMULATE_PREPARES=false`;
pembuat laporan memakai daftar putih kolom dan operator; token CSRF pada setiap formulir;
kata sandi bcrypt cost 12; pembatasan percobaan login; sesi terikat sidik peramban;
header keamanan HTTP; validasi ketat pada unggahan berkas; penghapusan lunak pada
seluruh tabel finansial.

---

## Struktur Proyek

```
sipiutang/
├── app/
│   ├── Core/          20 kelas inti (Router, Database, Auth, Acl, Dates, Num, ...)
│   ├── Services/      18 layanan (ArCalculator, AgingService, AcpService, ImportService, ...)
│   ├── Models/        32 model data
│   ├── Controllers/   21 controller
│   ├── Views/         55 berkas tampilan
│   ├── Helpers/       fungsi pembantu global
│   ├── routes.php     ~140 rute beserta metadata hak akses
│   └── bootstrap.php
├── config/
│   ├── config.sample.php
│   └── config.php     dibuat oleh wizard instalasi
├── database/
│   ├── 01_schema.sql        49 tabel
│   ├── 02_seed_master.sql   peran, 99 hak akses, 66 pengaturan, data master
│   ├── 03_seed_data.sql     3.072 invoice hasil konversi Excel (2,5 MB)
│   ├── import_excel.php     import dari baris perintah
│   └── backup.php           pencadangan untuk cron
├── docs/
│   ├── 01_ANALISIS_EXCEL.md          analisis workbook & 33 temuan kualitas data
│   ├── 02_ARSITEKTUR_DAN_ATURAN.md   arsitektur, skema, aturan R-01..R-14, validasi V-01..V-24
│   ├── MANUAL_PENGGUNA.md
│   ├── PANDUAN_INSTALASI_CPANEL.md
│   ├── CHECKLIST_PENGUJIAN.md
│   └── PANDUAN_BACKUP_RESTORE.md
├── install/index.php   wizard instalasi 5 langkah — HAPUS setelah selesai
├── public/             document root
│   ├── index.php
│   ├── .htaccess
│   └── assets/         css, js, dan vendor lokal
├── storage/            uploads, exports, logs, backups, tmp
├── tests/              pengujian otomatis
├── composer.json
└── README.md
```

---

## Instalasi Cepat

1. Unggah dan ekstrak paket ke hosting.
2. Arahkan *document root* domain ke folder `public/`.
3. Buat basis data MySQL beserta penggunanya, berikan hak *ALL PRIVILEGES*.
4. Pastikan folder `storage/*` dan `config/` dapat ditulis (izin `755`).
5. Buka `https://domainanda.com/install/` dan ikuti 5 langkah wizard.
6. **Hapus folder `install/`** setelah instalasi selesai.

Panduan lengkap beserta pemecahan masalah: [`docs/PANDUAN_INSTALASI_CPANEL.md`](docs/PANDUAN_INSTALASI_CPANEL.md).

### Menjalankan secara lokal

```bash
php -S localhost:8000 -t public
```

---

## Akun Demo

Tersedia hanya bila memasang dengan data contoh. Seluruh akun demo dipaksa mengganti
kata sandi pada login pertama.

| Nama pengguna | Kata sandi awal | Peran | Cakupan data |
|---|---|---|---|
| `superadmin` | `Admin#2026` | SUPERADMIN | Seluruh data |
| `finance` | `Finance#2026` | FINANCE_AR | Seluruh data |
| `collection` | `Collect#2026` | COLLECTION | Penugasan sendiri |
| `sales` | `Sales#2026` | SALES | Portofolio sendiri |
| `manajemen` | `Manage#2026` | MANAGEMENT | Seluruh data (baca) |
| `auditor` | `Audit#2026` | AUDITOR | Seluruh data (baca) |

> **Nonaktifkan seluruh akun demo sebelum digunakan di lingkungan produksi.**
> Wizard instalasi menyediakan pilihan untuk melakukannya secara otomatis.

---

## Import Data dari Baris Perintah

```bash
php database/import_excel.php "AR RPP 2026.xlsx"                # seluruh worksheet
php database/import_excel.php "AR RPP 2026.xlsx" --sheet=JULI   # satu worksheet
php database/import_excel.php "AR RPP 2026.xlsx" --dry-run      # uji coba tanpa menyimpan
```

---

## Pengujian

```bash
php tests/test_excel_reader.php    # pembacaan workbook Excel
php tests/test_writers.php         # penulisan XLSX, CSV, PDF
php tests/test_scenarios.php       # 19 skenario bisnis + 12 verifikasi integritas
bash tests/smoke.sh superadmin     # seluruh rute HTTP untuk satu peran
```

Status terakhir: **seluruh pengujian lulus**. 270 URL × 6 peran = 1.620 permintaan HTTP
tanpa satu pun galat, mencakup seluruh halaman, 25 laporan, dan tiga format ekspor. Rincian ada pada [`docs/CHECKLIST_PENGUJIAN.md`](docs/CHECKLIST_PENGUJIAN.md).

---

## Pencadangan

Dari antarmuka: menu **Pencadangan Data → Cadangkan Sekarang**.

Terjadwal melalui cron cPanel:

```
0 2 * * * /usr/local/bin/php /home/namaakun/sipiutang/database/backup.php --quiet
```

Panduan lengkap: [`docs/PANDUAN_BACKUP_RESTORE.md`](docs/PANDUAN_BACKUP_RESTORE.md).

---

## Aturan Perhitungan

```
DPP            = Bruto ÷ 1,11
PPN            = Bruto − DPP
PPh 23         = DPP × tarif        (bukan dari bruto)
Nilai Bersih   = Bruto − Total Potongan
Saldo          = Nilai Bersih − Terbayar − Nota Kredit disetujui
Jatuh Tempo    = Tanggal Kirim (fallback Tanggal Invoice) + Termin
Umur Piutang   = Tanggal Pelaporan − Jatuh Tempo      (invoice bersaldo)
Hari Penagihan = Tanggal Bayar Terakhir − Tanggal Dasar (invoice lunas)

ACP Metode 1 = (Rata-rata Piutang ÷ Penjualan Kredit Bersih) × Jumlah Hari
ACP Metode 2 = Rata-rata Hari Penagihan invoice yang lunas pada periode
```

Uraian lengkap aturan R-01 sampai R-14 dan validasi V-01 sampai V-24 ada pada
[`docs/02_ARSITEKTUR_DAN_ATURAN.md`](docs/02_ARSITEKTUR_DAN_ATURAN.md).

---

## Dokumentasi

| Berkas | Isi |
|---|---|
| [`docs/01_ANALISIS_EXCEL.md`](docs/01_ANALISIS_EXCEL.md) | Analisis workbook sumber, 33 temuan kualitas data, pemetaan kolom, 15 asumsi |
| [`docs/02_ARSITEKTUR_DAN_ATURAN.md`](docs/02_ARSITEKTUR_DAN_ATURAN.md) | Arsitektur, skema 49 tabel, ERD, aturan perhitungan, validasi import |
| [`docs/MANUAL_PENGGUNA.md`](docs/MANUAL_PENGGUNA.md) | Panduan pemakaian seluruh modul |
| [`docs/PANDUAN_INSTALASI_CPANEL.md`](docs/PANDUAN_INSTALASI_CPANEL.md) | Instalasi, pengamanan, pemecahan masalah, pemutakhiran |
| [`docs/CHECKLIST_PENGUJIAN.md`](docs/CHECKLIST_PENGUJIAN.md) | Hasil pengujian otomatis dan ceklis UAT |
| [`docs/PANDUAN_BACKUP_RESTORE.md`](docs/PANDUAN_BACKUP_RESTORE.md) | Strategi pencadangan dan prosedur pemulihan |

---

## Lisensi

Proprietary — dikembangkan untuk PT Roto-Rooter Indonesia.
