Troubleshooting

Halaman ini berisi solusi untuk masalah umum yang mungkin ditemui saat mengoperasikan RetailOS.

Masalah POS

POS tidak bisa login

Gejala: Muncul error "Connection refused" atau "Network error" saat login.

Solusi:

1. Cek apakah Store Router berjalan:

   curl http://localhost:8081/health

2. Jika tidak merespons, restart Store Router:

   sudo systemctl restart store-router

3. Cek apakah POS mengarah ke URL Store Router yang benar
4. Cek firewall tidak memblokir port 8081

Barcode tidak terbaca

Solusi:

1. Cek koneksi USB barcode scanner
2. Test scanner di Notepad/TextEdit -- scan harus menghasilkan angka
3. Cek scanner dalam mode HID keyboard mode
4. Coba port USB yang berbeda
5. Restart aplikasi POS

Printer receipt tidak mencetak

Solusi:

1. Cek koneksi printer (USB/Network)
2. Cek ada kertas dan tidak macet
3. Cek pengaturan printer di POS Settings
4. Test print: Settings > Printer > Test Print
5. Restart printer (matikan 10 detik, nyalakan kembali)

POS lambat / hang

Solusi:

1. Cek penggunaan RAM dan CPU komputer
2. Tutup aplikasi lain yang tidak perlu
3. Restart aplikasi POS
4. Cek ukuran database SQLite (jika > 1GB, mungkin perlu optimize)

Masalah Sinkronisasi

Data tidak tersinkronisasi ke Cloud

Gejala: Transaksi di toko tidak muncul di HO Finance.

Solusi:

1. Cek status sync:

   curl http://localhost:8081/api/sync/status

2. Cek koneksi internet toko
3. Cek status Tailscale VPN:

   tailscale status

4. Jika VPN tidak terhubung, restart Tailscale:

   sudo systemctl restart tailscaled

5. Force sync:

   curl -X POST http://localhost:8081/api/sync/force

Sync error "conflict"

Solusi:

1. Biasanya terjadi jika toko offline lama lalu data diubah di kedua sisi
2. Sistem otomatis menangani konflik dengan aturan "last write wins"
3. Jika ada data penting yang hilang, hubungi admin IT

Masalah Jaringan

Tailscale tidak terhubung

Solusi:

1. Cek status: tailscale status
2. Cek log: journalctl -u tailscaled -f
3. Re-authenticate jika key expired: sudo tailscale up --authkey=tskey-auth-new-key
4. Pastikan port UDP 41641 tidak diblokir firewall

Internet toko putus

Tindakan:

1. POS tetap bisa beroperasi -- transaksi disimpan lokal
2. Store Admin tetap bisa diakses via jaringan lokal
3. Hubungi ISP untuk perbaikan
4. Setelah internet kembali, sync akan otomatis berjalan

Masalah Database

Database Cloud Hub penuh

Solusi:

1. Cek penggunaan disk: df -h
2. Cek ukuran database:

   sudo -u postgres psql -c "SELECT pg_database_size('retailos_cloud') / 1024 / 1024 AS size_mb;"

3. Vacuum database: sudo -u postgres vacuumdb --analyze retailos_cloud
4. Tambah disk space jika perlu
5. Arsipkan data lama (transaksi > 2 tahun)

SQLite toko corrupt

Solusi:

1. Stop Store Router
2. Coba repair: sqlite3 store.db "PRAGMA integrity_check;"
3. Jika corrupt, restore dari backup atau force sync dari Cloud Hub
4. Start Store Router

Masalah Performa

Cloud Hub API lambat

Solusi:

1. Cek load server: htop
2. Cek slow queries PostgreSQL
3. Cek jumlah koneksi database
4. Restart Cloud Hub jika perlu
5. Scale up server jika load terus tinggi

Kontak Support

Level	Kontak	Response Time
L1	Help desk internal	30 menit
L2	Tim IT	2 jam
L3	Developer / Vendor	1 hari kerja

Tips

Saat melaporkan masalah, sertakan: screenshot error, langkah sebelum error, toko/komputer yang bermasalah, waktu kejadian.