Lewati ke konten utama

Troubleshooting (Decision Tree)

Gunakan format ini saat incident: Gejala → Kemungkinan Sebab → Langkah Cek → Fix.

1) Gejala: API return 403 Forbidden​

Kemungkinan sebab:

  • Role user tidak sesuai middleware access:*.
  • Entitas terkait sudah soft-delete.

Langkah cek:

  1. Cek role user di DB.
  2. Cek middleware route endpoint.
  3. Cek entitas terkait soft-delete.

Contoh query verifikasi:

SELECT id, role FROM users WHERE id = :user_id;
SELECT id, deleted_at FROM projects WHERE id = :project_id;

Fix:

  • Koreksi mapping role-permission.
  • Pulihkan data soft-delete jika memang seharusnya aktif.

2) Gejala: PO tidak bisa update ke status tertentu​

Kemungkinan sebab:

  • Rule transisi status membatasi per role.
  • Payload status tidak valid.

Langkah cek:

  1. Cek role user pelaku update.
  2. Cek state PO saat ini.
  3. Cek validator status di service/controller.

Contoh query verifikasi:

SELECT id, status, updated_at FROM purchase_orders WHERE id = :po_id;

Fix:

  • Sesuaikan role/flow transisi di kode.
  • Jika status baru ditambahkan, update state machine + validator.

3) Gejala: SPB tidak bisa diubah​

Kemungkinan sebab:

  • Status SPB sudah approved dan dikunci sistem.

Langkah cek:

  1. Ambil status SPB terkini.
  2. Cek log request perubahan terakhir.

Contoh query verifikasi:

SELECT id, status, approved_at FROM spb WHERE id = :spb_id;

Fix:

  • Ikuti flow revisi resmi (buat entitas revisi jika diperlukan).
  • Jangan bypass lock tanpa approval senior.

4) Gejala: Notifikasi push tidak terkirim​

Kemungkinan sebab:

  • Token FCM tidak valid/expired.
  • Credential Firebase invalid.
  • Queue worker tidak berjalan.

Langkah cek:

  1. Cek token user target.
  2. Cek log error FCM.
  3. Cek antrean job.

Contoh query verifikasi:

SELECT user_id, token, updated_at
FROM fcm_tokens
WHERE user_id = :user_id
ORDER BY updated_at DESC
LIMIT 5;

Fix:

  • Refresh token FCM.
  • Perbaiki credential.
  • Restart worker setelah root cause jelas.

5) Gejala: Export/PDF tidak muncul​

Kemungkinan sebab:

  • Permission storage bermasalah.
  • Job export gagal.
  • Dependency PDF/Excel tidak lengkap.

Langkah cek:

  1. Cek log job export.
  2. Cek file hasil di storage.
  3. Cek status queue.

Fix:

  • Benahi permission direktori.
  • Retry job yang aman diulang.
  • Pastikan dependency terpasang.

6) Gejala: Payment stuck di waiting_confirmation​

Kemungkinan sebab:

  • Tahap approve/verify belum dieksekusi role yang tepat.
  • Rule transisi status payment tertahan.

Langkah cek:

  1. Cek histori approval payment.
  2. Cek role aktor terakhir.

Contoh query verifikasi:

SELECT id, status, approved_by, verified_by, updated_at
FROM payments
WHERE id = :payment_id;

Fix:

  • Lengkapi tahapan approval sesuai role matrix.
  • Perbaiki rule transisi jika ada bug.

7) Gejala: Error migration saat deploy​

Kemungkinan sebab:

  • Konflik schema existing.
  • Data legacy tidak kompatibel dengan constraint baru.
  • Locking/timeout saat migrasi.

Langkah cek:

  1. Cek migration yang gagal + SQL error detail.
  2. Cek kondisi data sebelum constraint diterapkan.
  3. Cek durasi/lock query di DB.

Contoh query verifikasi:

-- contoh: cek data yang melanggar NOT NULL baru
SELECT COUNT(*)
FROM target_table
WHERE target_column IS NULL;

Fix:

  • Terapkan pendekatan expand/contract.
  • Jalankan backfill dulu sebelum constraint ketat.
  • Jika dampak besar: rollback sesuai playbook.

Quick Triage Flow​

Catatan​

  • Nama tabel/kolom query di atas bisa berbeda antar environment: perlu verifikasi dengan schema aktual.