Debugging & Troubleshooting Guide
Panduan bagi pengembang (developer) ketika menemui kendala dalam pengembangan maupun investigasi bug.
1. Sinkronisasi CloudKit Tidak Berfungsi
Gejala: Data anotasi atau bookmark tidak muncul di perangkat lain.
- Buka Xcode dan jalankan aplikasi. Periksa log konsol untuk kata kunci:
CloudKitSyncManageratauCKError. - Pastikan akun pengembang (developer account) telah masuk (login) ke akun iCloud pada Simulator atau perangkat pengujian.
- Periksa dasbor CloudKit untuk memastikan skema Custom Zone telah di-deploy ke lingkungan Production/Development.
2. Inspeksi SQLite Lokal
Gejala: Ingin memeriksa struktur tabel atau data secara manual.
-
Seluruh basis data pengguna tersimpan di direktori:
~/Library/Application Support/Maktabah/ -
Gunakan aplikasi pihak ketiga (seperti DB Browser for SQLite) untuk membuka berkas
.sqlite. - Jika isi tabel
b{id}tampak seperti karakter acak, teks tersebut dikompresi menggunakan format LZString atau Zstandard (zstd).
3. Sorotan Teks (Highlight) Bergeser / Misaligned
Gejala: Pengguna menyorot kalimat tertentu, namun antarmuka menyorot rentang kata di sebelahnya.
- Masalah ini umumnya terjadi akibat ketidaksesuaian kalkulasi di
ArabicRangeCalculator. - Pastikan logika pemetaan
Source ↔ Display Rangememperhitungkan edge case karakter harakat dan tasykil berurutan (misalnya: Syaddah + Fathah/Kasrah).
4. Kueri FTS Sangat Lambat
Gejala: Pencarian global memakan waktu lebih dari 5 detik.
- Periksa apakah
SQLiteConnectionPoolberhasil mendistribusikan koneksi pembacaan secara merata. - Pastikan tidak ada basis data yang terkunci (database lock contention). Periksa penggunaan
MutexatauNSLockpada modul akses data.