Cara Migrasi dari Instalasi Lawas
Panduan ini mengimpor data yang sudah ada dari instalasi HandyCafe V3 atau V4 yang lebih lama ke server HandyCafe modern. Migrasi ini tidak merusak sumber: file asli tidak diubah atau dihapus.
Migrasi database hanya berjalan di Windows. Dukungan runtime untuk klien lawas agar bisa terhubung lewat protokol asli bekerja di semua platform (lihat Pengaturan Klien Lawas).
Yang Anda Butuhkan
- Mesin Windows dengan instalasi lawas dan server HandyCafe modern pada sistem yang sama, atau akses ke file database lawas.
- Akses admin ke HandyCafe Server.
- Server lawas dihentikan. Database sumber tidak boleh sedang ditulis selama migrasi.
- Ruang disk kosong setidaknya sama dengan ukuran database lawas (untuk salinan database HandyCafe yang baru).
- Waktu 10 sampai 30 menit tanpa gangguan. Migrasi pada dataset besar bisa memakan beberapa menit. Jangan tutup HandyCafe selama proses berjalan.
Langkah 1: Hentikan Server Lawas
Buka aplikasi server HandyCafe lawas. Hentikan semua sesi dan keluar dari aplikasi. Jika server lawas berjalan sebagai layanan Windows, hentikan layanannya dari services.msc.
Hasil yang Diharapkan: Proses server lawas tidak lagi berjalan. File database tidak sedang dibuka.
Langkah 2: Buka Halaman Pengaturan Klien Lawas
- Jalankan HandyCafe.
- Buka Pengaturan di bilah samping.
- Klik Klien Lawas.
- Scroll ke bagian Migrasi Database.
Hasil yang Diharapkan: Jika sistem mendeteksi instalasi lawas, halaman menampilkan jalur instalasi, jalur database, versi server, dan jumlah file INI. Jika tidak ada yang terdeteksi, halaman menampilkan "Tidak ada instalasi lawas yang terdeteksi.". Dalam kasus itu, verifikasi bahwa file lawas ada di lokasi standar seperti Program Files\HandyCafe atau C:\HandyCafe.
Langkah 3: Tinjau Instalasi yang Terdeteksi
Pastikan nilai yang terdeteksi cocok dengan instalasi lawas yang Anda ketahui:
| Kolom | Yang Dicek |
|---|---|
| Jalur Instalasi | Mengarah ke folder HandyCafe yang benar. |
| Jalur Database | Mengarah ke file database lawas di dalam folder instalasi. |
| Versi Server | Cocok dengan versi server lawas Anda (misalnya 3.4.01 atau 4.0.10). |
| Jumlah File INI | Bukan nol. Instalasi yang sehat memiliki beberapa file INI untuk konfigurasi yang berbeda. |
Jika ada kolom yang salah, tutup HandyCafe, perbaiki instalasinya, lalu buka lagi.
Langkah 4: Periksa Kolom Encoding
Sebelum menjalankan migrasi, pastikan kolom Encoding di bagian Protokol Runtime sudah disetel dengan benar untuk data sumber Anda. Kolom ini ada di halaman pengaturan yang sama, di bagian atas.
| Locale Sumber | Encoding yang Disarankan |
|---|---|
| Turkish | cp1254 |
| Western European (English, French, German, Spanish, Italian, Portuguese) | cp1252 |
| Other | cp1254 (server menerima ini sebagai fallback default) |
Jika Anda mengubah encoding, klik Simpan sebelum melanjutkan.
Hasil yang Diharapkan: String sumber akan ter-decode dengan bersih selama migrasi, sehingga menghindari hasil completed_with_warnings.
Langkah 5: Mulai Migrasi
- Klik Mulai Migrasi.
- Modal progres terbuka. Modal menampilkan fase saat ini dan jumlah baris yang sudah diproses.
- Jangan tutup HandyCafe atau membuat komputer tidur.
- Tunggu sampai selesai. Dataset kecil selesai dalam waktu kurang dari satu menit. Dataset yang lebih besar bisa memakan 5 sampai 10 menit.
Hasil yang Diharapkan: Modal progres menutup dan status berubah menjadi completed atau completed_with_warnings. Notifikasi muncul untuk mengonfirmasi run tersebut.
Langkah 6: Tinjau Jumlah Migrasi
Setelah selesai, halaman menampilkan jumlah catatan yang dimigrasikan:
| Jumlah | Arti |
|---|---|
| Anggota | Catatan pelanggan yang diimpor. |
| Harga | Tabel harga dan entri jadwal yang diimpor. |
| Produk | Entri katalog produk yang diimpor. |
| Pesanan | Riwayat pesanan yang diimpor. |
| Transaksi | Entri buku besar yang diimpor. |
| Log | Log audit dan peringatan yang diimpor. |
| Peringatan | Catatan yang dilewati selama impor. Hanya muncul ketika status completed_with_warnings. |
Klik expander Detail untuk melihat rincian lengkap. Verifikasi bahwa jumlahnya masuk akal dibandingkan ekspektasi Anda.
Hasil yang Diharapkan: Keempat kategori utama (anggota, produk, pesanan, transaksi) menampilkan jumlah tidak nol jika sumber Anda memang punya data di tabel tersebut.
Langkah 7: Tangani Peringatan (Jika Ada)
Jika statusnya completed_with_warnings, buka daftar peringatan dan tinjau catatan yang dilewati.
Peringatan umum dan perbaikannya:
| Peringatan | Penyebab | Perbaikan |
|---|---|---|
| Encoding decode error | Teks sumber mengandung byte yang tidak bisa di-decode pada encoding yang dikonfigurasi. | Jalankan Undo, ubah kolom Encoding agar cocok dengan locale sumber, lalu jalankan migrasi ulang. |
| Malformed date | Ada catatan lawas dengan cap waktu invalid (misalnya 0000-00-00). |
Ini dilewati dengan aman. Tidak perlu tindakan. |
| Duplicate key | Ada catatan dengan pengenal yang sama yang sudah ada di HandyCafe. | Jika ini migrasi kedua yang tidak disengaja, jalankan Urungkan lalu Jalankan Ulang. Jika Anda sedang menggabungkan database, terima skip tersebut. |
Hasil yang Diharapkan: Anda menerima peringatan yang memang bisa diterima atau memperbaiki masalah dasarnya lalu menjalankan ulang.
Langkah 8: Cek Sampel Data yang Diimpor
Sebelum memensiunkan server lawas, verifikasi secara manual sampel dari setiap tipe catatan.
- Buka Anggota di bilah samping. Cari anggota yang Anda kenal dari sistem lawas. Konfirmasi nama, saldo, dan info kontak.
- Buka Pengaturan > Harga. Konfirmasi tarif per jam cocok dengan jadwal lawas.
- Buka Produk. Konfirmasi nama dan harga produk.
- Buka Laporan Kas untuk hari historis yang baru. Konfirmasi total cocok dengan yang Anda harapkan dari sistem lawas.
Hasil yang Diharapkan: Sampel acak cocok dengan sumber lawas. Jika ada catatan tertentu yang salah, catat masalahnya. Perbedaan format kecil itu normal. Ketidaksesuaian nilai yang besar menunjukkan masalah encoding atau integritas data yang perlu diselidiki sebelum live.
Langkah 9: Aktifkan Dukungan Runtime Klien Lawas (Opsional)
Jika Anda ingin mesin klien V3 atau V4 yang ada tetap bisa terhubung selama masa transisi, aktifkan protokol runtime sekarang.
- Scroll ke bagian atas halaman pengaturan Klien Lawas.
- Aktifkan Aktifkan Dukungan Klien Lawas.
- Pastikan port listener (UDP 710, TCP 712, file transfer 717) tidak bentrok dengan apa pun di jaringan Anda.
- Klik Simpan.
Hasil yang Diharapkan: Klien lawas di LAN muncul di Panel Admin dalam 5 sampai 10 detik. Lihat Klien Lawas untuk cara mengelolanya dari panel.
Cara Mengurungkan Migrasi
Jika migrasi menghasilkan hasil yang tidak terduga, Anda bisa membatalkannya sepenuhnya. Database lawas asli tetap tidak tersentuh.
- Buka Pengaturan > Klien Lawas.
- Scroll ke bagian Migrasi Database.
- Klik Urungkan Migrasi.
- Konfirmasi di dialog.
Setiap baris yang dimigrasikan dihapus dari HandyCafe. Status kembali ke never. Anda kemudian bisa memperbaiki masalah dasarnya (encoding, pembersihan data sumber, dan lain-lain) lalu menjalankan Mulai Migrasi lagi.
Cara Menjalankan Ulang Migrasi
Menjalankan ulang mengganti data yang dimigrasikan dengan data baru dari sumber.
- Buka Pengaturan > Klien Lawas.
- Klik Jalankan Ulang Migrasi (label tombol berubah dari Mulai Migrasi setelah eksekusi pertama selesai).
- Alurnya sama seperti eksekusi awal.
Jalankan ulang aman dipakai sebanyak yang Anda perlukan. Tidak akan menggandakan data karena mengganti output migrasi yang sudah ada.
Kesalahan Umum yang Perlu Dihindari
- Menjalankan migrasi saat server lawas masih aktif. Database sumber bisa terkunci atau berisi penulisan parsial. Selalu hentikan server lawas terlebih dahulu.
- Mengabaikan kolom Encoding. Menjalankan dengan encoding yang salah akan merusak nama anggota dan pesan log. Memperbaikinya setelah kejadian memerlukan Urungkan dan Jalankan Ulang.
- Menutup HandyCafe selama migrasi. Eksekusi terputus dan data parsial ditulis. Pemulihan memerlukan Urungkan. Selalu biarkan modal progres selesai.
- Melewati langkah spot-check. Mempercayai jumlah catatan tanpa memverifikasi sampel data bisa melewatkan masalah halus seperti mismatch locale atau kesalahan pembulatan.
- Terlalu cepat menghapus instalasi lawas. Simpan file sumber setidaknya satu siklus pembayaran penuh setelah migrasi. Jika ada selisih di laporan bulanan, Anda masih bisa merujuk catatan asli.
- Migrasi tanpa backup. Salin folder instalasi lawas sebelum migrasi pertama. Meskipun sumber tidak diubah oleh migrasi, masalah disk atau kecelakaan tetap bisa terjadi. Backup adalah asuransi yang murah.