Update besar apk finance

docs/database-cutover.md

@@ -0,0 +1,59 @@
+# Cutover database production lama ke V2
+
+Proses ini bersifat **satu arah**: database lama hanya dibaca, sedangkan database V2 wajib kosong saat bootstrap. ID dan seluruh isi tabel lama dipertahankan, kemudian migration aplikasi dijalankan hanya pada database V2.
+
+## Pengamanan
+
+- Jalankan melalui CLI; endpoint web ditolak.
+- Kredensial hanya melalui environment variable dan tidak disimpan di repository.
+- Kedua koneksi diuji sebelum target ditulis.
+- Bootstrap ditolak jika sumber dan target sama atau target sudah berisi objek.
+- Snapshot memakai consistent read-only transaction.
+- Backup dapat diberi SHA-256 agar file yang salah tidak dapat diimpor.
+- Kode akun dinormalisasi menjadi tepat empat digit oleh migration aplikasi.
+
+## Environment variable
+
+```text
+DBSYNC_ENABLED=true
+DBSYNC_SOURCE_HOST=
+DBSYNC_SOURCE_PORT=3306
+DBSYNC_SOURCE_USERNAME=
+DBSYNC_SOURCE_PASSWORD=
+DBSYNC_SOURCE_DATABASE=
+DBSYNC_TARGET_HOST=
+DBSYNC_TARGET_PORT=3306
+DBSYNC_TARGET_USERNAME=
+DBSYNC_TARGET_PASSWORD=
+DBSYNC_TARGET_DATABASE=
+DBSYNC_BACKUP_DIRECTORY=C:\xampp\private_backups\accounting_dev
+```
+
+Opsional untuk memakai snapshot yang sudah tersedia:
+
+```text
+DBSYNC_BACKUP_FILE=C:\path\snapshot.sql
+DBSYNC_BACKUP_SHA256=checksum_snapshot
+DBSYNC_MYSQL_BIN=C:\xampp\mysql\bin\mysql.exe
+```
+
+## Perintah
+
+```powershell
+php index.php databasesync check
+php index.php databasesync snapshot
+php index.php databasesync bootstrap
+php index.php databasesync verify
+```
+
+`bootstrap` otomatis membuat snapshot jika `DBSYNC_BACKUP_FILE` tidak diisi, mengimpor snapshot ke target kosong, menjalankan seluruh migration, dan melakukan audit akhir.
+
+## Cutover production sebenarnya
+
+1. Uji `check` dan pastikan target kosong.
+2. Aktifkan maintenance/read-only pada aplikasi lama agar tidak ada transaksi baru selama snapshot akhir.
+3. Jalankan `bootstrap` satu kali.
+4. Pastikan `verify` berhasil: migration terbaru, semua kode akun empat digit, jurnal balance, dan tidak ada orphan utama.
+5. Ubah konfigurasi aplikasi ke database V2, lakukan smoke test login/laporan/transaksi, lalu buka maintenance.
+
+Cron sinkronisasi tabel-ke-tabel tidak digunakan karena struktur lama dan V2 berbeda dan berisiko menimpa hasil normalisasi. Jika downtime nol benar-benar diperlukan, siapkan CDC/outbox sebagai proyek terpisah; jangan menjalankan kedua aplikasi menulis ke database berbeda tanpa mekanisme konflik.