# PANDUAN PENCADANGAN & PEMULIHAN DATA SIPIUTANG

Versi 1.0.0

Data piutang adalah catatan keuangan. Kehilangan data berarti kehilangan bukti tagihan.
Dokumen ini menjelaskan cara mencadangkan, menjadwalkan, memverifikasi, dan memulihkan data
SIPIUTANG.

---

## Daftar Isi

1. [Apa Saja yang Perlu Dicadangkan](#1-apa-saja-yang-perlu-dicadangkan)
2. [Strategi Pencadangan yang Disarankan](#2-strategi-pencadangan-yang-disarankan)
3. [Pencadangan dari Antarmuka Web](#3-pencadangan-dari-antarmuka-web)
4. [Pencadangan Otomatis dengan Cron](#4-pencadangan-otomatis-dengan-cron)
5. [Pencadangan Berkas Lampiran](#5-pencadangan-berkas-lampiran)
6. [Pencadangan Penuh dari cPanel](#6-pencadangan-penuh-dari-cpanel)
7. [Memverifikasi Berkas Cadangan](#7-memverifikasi-berkas-cadangan)
8. [Menyimpan Salinan di Luar Server](#8-menyimpan-salinan-di-luar-server)
9. [Pemulihan Data](#9-pemulihan-data)
10. [Pemulihan Sebagian](#10-pemulihan-sebagian)
11. [Prosedur Pemulihan Darurat](#11-prosedur-pemulihan-darurat)
12. [Pemecahan Masalah](#12-pemecahan-masalah)
13. [Ceklis Pencadangan Bulanan](#13-ceklis-pencadangan-bulanan)

---

## 1. Apa Saja yang Perlu Dicadangkan

| Yang dicadangkan | Isi | Prioritas |
|---|---|---|
| **Basis data** | Seluruh invoice, pembayaran, revisi, master, pengaturan, log audit | Kritis |
| **`storage/uploads/`** | Berkas lampiran (bukti transfer, faktur pajak, surat) | Kritis |
| **`config/config.php`** | Kredensial basis data dan kunci aplikasi | Penting |
| `storage/exports/` | Berkas ekspor sementara | Tidak perlu |
| `storage/logs/` | Log aplikasi | Opsional (berguna untuk audit) |
| `app/`, `public/` | Kode program | Opsional (ada di paket rilis) |

**Kesimpulan:** yang wajib dicadangkan adalah **basis data**, **folder `storage/uploads/`**,
dan **berkas `config/config.php`**.

---

## 2. Strategi Pencadangan yang Disarankan

| Frekuensi | Cara | Retensi | Lokasi |
|---|---|---|---|
| Harian, pukul 02:00 | Cron `database/backup.php` | 10 berkas terakhir | Server |
| Mingguan | Unduh manual dari menu Pencadangan | 8 minggu | Komputer/Drive kantor |
| Bulanan | Full Backup cPanel | 12 bulan | Penyimpanan luar |
| Sebelum tindakan besar | Manual dari menu Pencadangan | Sampai tindakan terbukti aman | Server + unduh |

**Tindakan besar** yang wajib didahului pencadangan manual:

- import berkas Excel dalam jumlah besar;
- pembatalan batch import (*rollback*);
- Hitung Ulang Piutang menyeluruh;
- perubahan tarif pajak, termin bawaan, atau dasar jatuh tempo;
- pemutakhiran versi sistem;
- penghapusan data master.

> **Aturan 3-2-1:** simpan **3** salinan data, pada **2** jenis media berbeda,
> dengan **1** salinan berada di luar lokasi server.

---

## 3. Pencadangan dari Antarmuka Web

**Menu: Pencadangan Data**

1. Klik **Cadangkan Sekarang**.
2. Tunggu proses selesai (biasanya 5–30 detik, bergantung ukuran data).
3. Berkas muncul di tabel dengan nama
   `backup_namadatabase_YYYYMMDD_HHMMSS.sql`.
4. Klik **Unduh** untuk menyimpan salinan di komputer Anda.

**Metode yang dipakai sistem:**

- **`mysqldump`** bila tersedia di server — paling cepat dan paling lengkap.
- **PDO internal** bila `mysqldump` tidak dapat dijalankan (umum pada shared hosting
  yang menonaktifkan `exec()`). Metode ini membaca seluruh tabel melalui koneksi
  basis data biasa dan menghasilkan berkas SQL yang setara.

Metode yang dipakai ditampilkan pada kolom keterangan di tabel riwayat.

**Retensi otomatis:** setelah pencadangan berhasil, sistem menghapus berkas terlama
sehingga jumlahnya tidak melebihi nilai pada Pengaturan → Pencadangan →
*Jumlah Berkas Cadangan Disimpan* (bawaan: 10).

---

## 4. Pencadangan Otomatis dengan Cron

### Memasang cron di cPanel

1. cPanel → **Cron Jobs**.
2. **Common Settings** → pilih **Once Per Day (0 0 * * *)**.
3. Ubah kolom **Hour** menjadi `2` (pukul 02:00 waktu server).
4. Isi **Command**:

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

5. **Add New Cron Job**.

**Menemukan jalur PHP yang benar:** cPanel → **Select PHP Version**, atau coba
`/usr/local/bin/php`, `/usr/bin/php`, atau `/opt/cpanel/ea-php82/root/usr/bin/php`.

**Menemukan jalur folder:** cPanel → File Manager → klik folder `sipiutang` →
jalur lengkap tampil di bilah atas.

### Opsi skrip

| Opsi | Fungsi |
|---|---|
| `--quiet` | Hanya menampilkan kesalahan — gunakan untuk cron agar tidak mengirim email tiap hari |
| `--simpan=N` | Menyimpan N berkas terbaru, menimpa nilai pengaturan |
| `--tipe=manual` | Menandai jenis pencadangan pada log |

### Contoh jadwal lain

```
# Dua kali sehari (02:00 dan 14:00)
0 2,14 * * *  /usr/local/bin/php /home/namaakun/sipiutang/database/backup.php --quiet

# Setiap 6 jam
0 */6 * * *   /usr/local/bin/php /home/namaakun/sipiutang/database/backup.php --quiet

# Mingguan setiap Minggu pukul 03:00, menyimpan 52 berkas
0 3 * * 0     /usr/local/bin/php /home/namaakun/sipiutang/database/backup.php --quiet --simpan=52
```

### Memastikan cron berjalan

- Buka menu **Pencadangan Data** keesokan harinya; berkas baru bertipe *otomatis*
  seharusnya sudah muncul.
- Periksa juga **Log Aktivitas** → modul `backup`.
- Bila tidak ada, hapus sementara `--quiet` agar cPanel mengirimkan keluaran skrip
  ke email Anda dan pesan kesalahannya dapat dibaca.

---

## 5. Pencadangan Berkas Lampiran

Berkas cadangan `.sql` **tidak** memuat lampiran fisik. Lampiran tersimpan di
`storage/uploads/`.

**Cara termudah (File Manager cPanel):**

1. File Manager → masuk ke folder `storage`.
2. Klik kanan folder `uploads` → **Compress** → pilih **Zip Archive** →
   beri nama `uploads_YYYYMMDD.zip`.
3. Setelah selesai, klik kanan berkas ZIP → **Download**.
4. Hapus berkas ZIP dari server agar tidak memenuhi kuota.

**Bila memiliki akses SSH:**

```bash
cd /home/namaakun/sipiutang/storage
tar -czf ~/uploads_$(date +%Y%m%d).tar.gz uploads/
```

**Menjadwalkan lewat cron (mingguan, Sabtu pukul 03:00):**

```
0 3 * * 6 cd /home/namaakun/sipiutang/storage && tar -czf /home/namaakun/backups/uploads_$(date +\%Y\%m\%d).tar.gz uploads/
```

> Perhatikan tanda `\` sebelum `%` — cron memperlakukan `%` sebagai karakter khusus.

---

## 6. Pencadangan Penuh dari cPanel

Mencakup seluruh berkas, basis data, akun email, dan konfigurasi.

1. cPanel → **Backup** → **Download a Full Account Backup**.
2. **Backup Destination**: *Home Directory*.
3. Isi alamat email untuk pemberitahuan → **Generate Backup**.
4. Tunggu email pemberitahuan (bisa beberapa menit hingga beberapa jam).
5. Kembali ke **Backup**, unduh berkas `.tar.gz` yang dihasilkan.
6. **Hapus berkas tersebut dari server** setelah terunduh — ukurannya besar dan
   memakan kuota.

Alternatif yang lebih ringan: **Backup Wizard** → *Backup* → *MySQL Databases*
untuk mencadangkan basis data saja.

---

## 7. Memverifikasi Berkas Cadangan

Berkas cadangan yang tidak pernah diuji sama dengan tidak punya cadangan.
**Lakukan uji pemulihan minimal sekali dalam tiga bulan.**

### Pemeriksaan cepat

1. Unduh berkas `.sql`.
2. Periksa ukurannya wajar (untuk data contoh sekitar 4–6 MB). Berkas berukuran
   beberapa kilobyte hampir pasti gagal.
3. Buka dengan penyunting teks; bagian awal harus memuat baris seperti
   `-- SIPIUTANG` atau `CREATE TABLE` / `INSERT INTO`.
4. Bagian akhir harus lengkap, tidak terpotong di tengah perintah.

### Uji pemulihan penuh (disarankan)

1. Buat basis data baru di cPanel, misalnya `namaakun_ujicoba`.
2. phpMyAdmin → pilih basis data tersebut → **Import** → unggah berkas cadangan.
3. Setelah selesai, jalankan pemeriksaan berikut pada tab **SQL**:

   ```sql
   SELECT
     (SELECT COUNT(*) FROM invoices)  AS jumlah_invoice,
     (SELECT COUNT(*) FROM payments)  AS jumlah_pembayaran,
     (SELECT COUNT(*) FROM customers) AS jumlah_customer,
     (SELECT ROUND(SUM(outstanding_amount))
        FROM invoices WHERE doc_status = 'active') AS saldo_piutang;
   ```

4. Bandingkan hasilnya dengan angka pada dashboard sistem yang sedang berjalan.
   Angka harus sama (atau berbeda wajar sesuai transaksi setelah waktu pencadangan).
5. **Hapus basis data uji coba** setelah selesai.

---

## 8. Menyimpan Salinan di Luar Server

Cadangan yang hanya berada di server yang sama tidak melindungi dari kegagalan
server, peretasan, atau penutupan akun hosting.

**Pilihan penyimpanan luar:**

- Google Drive, OneDrive, atau Dropbox perusahaan — unduh manual mingguan,
  unggah ke folder khusus.
- Komputer kantor dengan folder tersinkronisasi.
- Layanan penyimpanan objek (S3 dan sejenisnya) bila tersedia.

**Ketentuan:**

- Folder cadangan harus dibatasi aksesnya — berkas ini memuat seluruh data keuangan
  dan NPWP customer.
- Beri nama berkas dengan tanggal agar mudah ditelusuri.
- Simpan salinan bulanan minimal 12 bulan untuk keperluan audit.
- Catat lokasi penyimpanan pada dokumen prosedur internal.

---

## 9. Pemulihan Data

> **Peringatan:** pemulihan **menimpa seluruh data** yang ada sekarang.
> Selalu buat pencadangan kondisi terkini sebelum memulihkan, agar Anda masih
> dapat kembali bila ternyata berkas cadangan yang dipilih keliru.

### Cara A — Dari menu Pencadangan Data (paling mudah)

1. Buat pencadangan kondisi saat ini terlebih dahulu.
2. Menu **Pencadangan Data** → cari berkas yang diinginkan → klik **Pulihkan**.
3. Konfirmasi peringatan yang muncul.
4. Sistem mengeksekusi berkas SQL dan menampilkan hasilnya.
5. Setelah selesai, **keluar dan masuk kembali**, lalu periksa dashboard.

### Cara B — Melalui phpMyAdmin

1. cPanel → **phpMyAdmin** → pilih basis data SIPIUTANG.
2. Tab **Operations** → **Drop the database (DROP)** untuk mengosongkan,
   lalu buat kembali dengan nama yang sama melalui **MySQL® Databases**.
   *(Atau, bila berkas cadangan memuat `DROP TABLE IF EXISTS`, langkah ini dapat dilewati.)*
3. Pilih basis data → tab **Import** → unggah berkas `.sql` → **Go**.
4. Bila berkas melebihi batas unggah, lihat bagian [Pemecahan Masalah](#12-pemecahan-masalah).

### Cara C — Melalui baris perintah (bila ada SSH)

```bash
# Cadangkan kondisi sekarang
mysqldump -u pengguna -p namadatabase > sebelum_pemulihan.sql

# Pulihkan
mysql -u pengguna -p namadatabase < backup_namadatabase_20260727_020000.sql
```

### Setelah pemulihan

1. Masuk kembali ke sistem.
2. Buka **Pengaturan → Hitung Ulang Piutang** dan jalankan sekali,
   untuk memastikan seluruh nilai turunan sesuai tanggal hari ini.
3. Periksa **Kualitas Data** — tidak boleh muncul temuan kritis baru.
4. Bandingkan angka dashboard dengan catatan terakhir yang Anda ketahui.
5. Pulihkan pula folder `storage/uploads/` bila lampiran ikut hilang.

---

## 10. Pemulihan Sebagian

Kadang yang perlu dipulihkan hanya sebagian data, misalnya satu tabel yang terhapus
tidak sengaja.

1. Unduh berkas cadangan dan buka dengan penyunting teks yang mampu menangani
   berkas besar (Notepad++, VS Code, Sublime Text).
2. Cari blok yang diawali `DELETE FROM \`namatabel\`;` atau
   `INSERT INTO \`namatabel\``.
3. Salin blok tersebut ke berkas baru, misalnya `pulihkan_customers.sql`.
4. Jalankan melalui phpMyAdmin → tab **SQL**, atau **Import** berkas tersebut.

**Memulihkan satu invoice yang terhapus:** SIPIUTANG memakai penghapusan lunak
(*soft delete*), sehingga data yang "dihapus" sebenarnya masih ada. Cukup jalankan:

```sql
UPDATE invoices SET deleted_at = NULL WHERE invoice_no = 'FA/26/1234';
```

lalu buka **Pengaturan → Hitung Ulang Piutang**.

---

## 11. Prosedur Pemulihan Darurat

Bila sistem tidak dapat diakses sama sekali.

### Situasi 1 — Halaman putih atau HTTP 500

1. Buka `storage/logs/app-YYYY-MM-DD.log` melalui File Manager, baca baris terakhir.
2. Sementara ubah `config/config.php`: `'env' => 'development'`, `'debug' => true`.
3. Muat ulang halaman untuk membaca pesan kesalahan.
4. Perbaiki penyebabnya, lalu kembalikan ke `production`.

### Situasi 2 — Basis data rusak atau hilang

1. Buat basis data baru di cPanel.
2. Sesuaikan `config/config.php` agar menunjuk ke basis data baru tersebut.
3. Pulihkan dari berkas cadangan terakhir (lihat bagian 9).
4. Pulihkan `storage/uploads/` dari arsip lampiran.
5. Masukkan kembali transaksi yang terjadi setelah waktu pencadangan.

### Situasi 3 — Akun hosting hilang seluruhnya

1. Siapkan hosting baru dengan spesifikasi setara.
2. Unggah dan ekstrak paket rilis SIPIUTANG.
3. Jalankan wizard instalasi, pilih **Struktur + master saja**.
4. Pulihkan basis data dari cadangan luar server, menimpa hasil instalasi.
5. Pulihkan `storage/uploads/`.
6. Sesuaikan `config/config.php` dengan kredensial hosting baru.
7. Arahkan domain ke server baru.
8. Jalankan **Hitung Ulang Piutang**, lalu verifikasi seluruh angka.

### Situasi 4 — Data salah akibat import keliru

1. **Jangan langsung memulihkan seluruh basis data.**
2. Buka **Import Data** → pilih batch yang keliru → **Batalkan Import**.
   Cara ini jauh lebih aman karena hanya menghapus data dari batch tersebut.
3. Bila pembatalan gagal karena datanya sudah diubah transaksi lain,
   barulah lakukan pemulihan penuh dari cadangan sebelum import.

---

## 12. Pemecahan Masalah

### Pencadangan gagal — "Permission denied"

Folder `storage/backups` tidak dapat ditulis. Ubah izinnya menjadi `755` (atau `775`).

### Pencadangan gagal — mysqldump tidak ditemukan

Normal pada banyak shared hosting. Sistem otomatis beralih ke metode PDO internal;
periksa kolom keterangan pada tabel riwayat. Bila keduanya gagal, gunakan
Backup Wizard cPanel sebagai gantinya.

### Berkas cadangan terlalu besar untuk phpMyAdmin

Pilihan penanganan:

1. Naikkan batas melalui cPanel → **MultiPHP INI Editor**:
   `upload_max_filesize = 128M`, `post_max_size = 128M`, `max_execution_time = 600`.
2. Kompres berkas menjadi `.sql.gz`; phpMyAdmin dapat mengimpor berkas terkompresi.
3. Pecah berkas dengan alat seperti *SQLDumpSplitter*, lalu impor bertahap.
4. Gunakan **Terminal** cPanel bila tersedia:
   `mysql -u pengguna -p namadatabase < backup.sql`

### Pemulihan berhenti dengan galat *foreign key constraint*

Jalankan di phpMyAdmin sebelum impor:

```sql
SET FOREIGN_KEY_CHECKS = 0;
```

dan setelahnya:

```sql
SET FOREIGN_KEY_CHECKS = 1;
```

Berkas cadangan yang dihasilkan SIPIUTANG sudah memuat kedua perintah ini.

### Setelah pemulihan, angka piutang terlihat aneh

Jalankan **Pengaturan → Hitung Ulang Piutang**. Nilai umur piutang dan status
pembayaran bergantung pada tanggal hari ini, sehingga perlu disegarkan setelah
data lama dipulihkan.

### Ruang disk penuh karena berkas cadangan

Turunkan nilai *Jumlah Berkas Cadangan Disimpan* di Pengaturan → Pencadangan,
lalu hapus berkas lama secara manual dari menu Pencadangan Data.

---

## 13. Ceklis Pencadangan Bulanan

| No | Butir | ✓ |
|---|---|---|
| 1 | Cron pencadangan harian masih berjalan (ada berkas baru setiap hari) | ☐ |
| 2 | Berkas cadangan terakhir berukuran wajar | ☐ |
| 3 | Satu berkas cadangan diunduh ke penyimpanan luar server | ☐ |
| 4 | Folder `storage/uploads/` diarsipkan dan diunduh | ☐ |
| 5 | Salinan `config/config.php` tersimpan di tempat aman | ☐ |
| 6 | Uji pemulihan ke basis data uji coba berhasil (minimal per triwulan) | ☐ |
| 7 | Jumlah invoice dan saldo hasil uji cocok dengan dashboard | ☐ |
| 8 | Basis data uji coba sudah dihapus | ☐ |
| 9 | Ruang disk hosting masih mencukupi | ☐ |
| 10 | Full Backup cPanel bulan ini sudah dibuat dan diunduh | ☐ |

---

*Dokumen ini merupakan bagian dari paket SIPIUTANG v1.0.0.*