open-isp/docs/ADMIN_SETTINGS_USAGE.md

Admin Settings - Multi-Router Configuration

Status: ✅ SELESAI - Siap Digunakan

Saat edit pengaturan di /admin/settings, Anda BISA langsung menyimpan tanpa NULL lagi. Sistem sudah handle semuanya.

---

Akses Settings

1. Login ke admin portal → menu ⚙️ Pengaturan
2. Atau langsung akses: http://localhost:3001/admin/settings

---

Section: Pengaturan MikroTik

Scroll ke bawah, cari bagian "MULTI-ROUTER & MIKROTIK"

Field 1: Mode Multi-Router

☑ Mode Multi-Router: [Dropdown]
  - Aktif (Multiple Router)
  - Nonaktif (Single Router Mode)

Apa artinya?

Mode	Artinya	Untuk Apa
Aktif	Pelanggan HARUS memilih router saat dibuat	Multi-ISP / Multi-lokasi dengan routers berbeda
Nonaktif	Pelanggan tanpa router_id otomatis pakai default	Setup sederhana, satu router utama

Default: Aktif

Field 2: Default Router ID (Opsional)

□ Default Router ID: [Input Number]
  Placeholder: "Kosongkan untuk auto-detect"
  Hint: "Opsional - jika kosong, sistem auto-detect router pertama yang aktif"

Kapan perlu diisi?

• Jika mode = Nonaktif dan punya multiple routers di database

  • Isi dengan ID router utama (misal: 1)
  • Pelanggan lama (router_id = NULL) akan pakai router ini

• Jika mode = Aktif

  • TIDAK perlu diisi (tidak akan dipakai)

• Jika hanya punya satu router

  • Kosongkan saja, sistem auto-detect

---

Contoh Konfigurasi

Setup 1: Single Router (Simple)

Mode Multi-Router: Nonaktif
Default Router ID: [kosongkan]

Apa yang terjadi:

• Aplikasi pakai router pertama dari database / settings.json
• Pelanggan lama (NULL router) otomatis menggunakan router itu
• Semua isolir/activate berjalan normal ✅

Setup 2: Multi Router (Main + Backup)

Mode Multi-Router: Nonaktif
Default Router ID: 1

Database routers:

ID | name         | is_active
---|--------------|----------
1  | Main Router  | 1
2  | Backup       | 0  (disabled)

Apa yang terjadi:

• Pelanggan baru dibuat: harus pilih router (1 atau 2)
• Pelanggan lama (NULL router): auto-assign ke router 1
• Isolir/activate pakai router masing-masing ✅

Setup 3: Full Multi-Router Mode

Mode Multi-Router: Aktif
Default Router ID: [kosongkan]

Apa yang terjadi:

• Pelanggan WAJIB pilih router saat dibuat
• Tidak ada auto-assign (semua harus eksplisit)
• Lebih aman untuk lingkungan kompleks

---

Alur Kerja: Saat Anda Simpan Setting

Langkah 1: Form Submission

Anda klik "Simpan Pengaturan" di /admin/settings

Langkah 2: Backend Processing

POST /admin/settings
  ├─ Parse form data (multi_router_mode, default_router_id)
  ├─ Validasi format (mode = string, router_id = number)
  └─ Cek apakah ada mode switch (disabled → active)

Langkah 3: Auto-Assignment (Jika Mode Berubah)

Jika dulu: "Aktif" → Sekarang: "Nonaktif"
  ├─ Cari pelanggan dengan router_id = NULL
  │  AND (pppoe_username != '' OR hotspot_username != '' OR static_ip != '')
  ├─ Assign router_id = default_router_id (atau auto-detect first router)
  └─ Log: "[Settings] Auto-assigned router X to Y customers"

Langkah 4: Save to settings.json

{
  "multi_router_mode": "nonaktif",
  "default_router_id": "1",
  ...
}

Langkah 5: Update In-Memory Cache

Aplikasi langsung reload setting tanpa restart

Langkah 6: Redirect

Browser redirect ke /admin/settings → tampil pesan "✅ Pengaturan berhasil disimpan"

---

Testing: Verifikasi Konfigurasi Bekerja

Test 1: Mode Switch Active → Disabled

Persiapan:

1. Buat pelanggan dengan router_id = NULL (manual edit database atau via old export)
2. Set mode = "Aktif", default_router_id kosong

Eksekusi:

1. Ke /admin/settings
2. Set mode = "Nonaktif", default_router_id = 1
3. Klik "Simpan Pengaturan"

Verifikasi:

# Cek logs
tail -f logs/combined.log | grep "Auto-assigned"

# Cek database
sqlite3 database/billing.db "SELECT id, name, router_id FROM customers WHERE router_id = 1 LIMIT 5;"

✅ Harus ada: "Auto-assigned router 1 to X customers"

Test 2: Isolir dengan Custom Default Router

Persiapan:

1. Set mode = "Nonaktif", default_router_id = 2
2. Buat pelanggan baru dengan router_id = NULL (atau pakai pelanggan lama)

Eksekusi:

1. Admin isolir pelanggan itu
2. Cek MikroTik router 2

Verifikasi:

# Cek logs
tail -f logs/combined.log | grep -i "isolir\|suspend"

# Harus ada: "Using default router from database: Router2"

✅ Profile di router 2 berubah ke "isolir"

Test 3: Settings Reload Tanpa Restart

Persiapan:

1. App sedang berjalan (pm2)
2. Edit /admin/settings dan ubah mode

Verifikasi:

# Check if app still running
pm2 status

# NEW: Tidak perlu restart! Setting langsung aktif di memory
# (Hanya perlu restart jika ada bug atau edit langsung settings.json)

✅ Aplikasi tetap berjalan, tidak crash

---

Troubleshooting

Problem: Ubah setting tapi isolir masih error

Solusi:

1. Cek logs: tail logs/error.log
2. Pastikan router_id di database benar-benar ada
3. Test koneksi ke MikroTik: node -e "const m = require('./services/mikrotikService'); m.checkConnection(1).then(ok => console.log('OK:', ok));"

Problem: Mode Aktif → Nonaktif tapi NULL router tidak ter-assign

Solusi:

1. Cek database, apakah ada routers yang is_active = 1

   SELECT * FROM routers WHERE is_active = 1;
   

2. Cek logs saat simpan: grep -i "Auto-assigned" logs/combined.log
3. Verifikasi default_router_id benar-benar tersimpan:

   node -e "const {getSetting} = require('./config/settingsManager'); console.log(getSetting('default_router_id'));"
   

Problem: Setting berubah tapi pelanggan isolir di router lama

Solusi:

1. Ini normal! Setting hanya berlaku untuk operasi baru setelah perubahan
2. Pelanggan yang sudah isolir di router lama tetap pakai router lama (itu yang disimpan di database)
3. Untuk reset, dapat pakai "Aktivasi" dulu, lalu isolir lagi

---

Fitur Bonus: Real-Time Settings Update

Anda TIDAK perlu restart app setelah ubah settings.

Mengapa?

• settingsManager.js cache setting setiap kali dibaca
• Saat form disubmit, saveSettings() langsung update cache
• Operasi berikutnya akan pakai setting baru

Exception: Jika langsung edit settings.json di file (tidak via UI), perlu restart app.

---

Quick Reference: Setting Values

Setting Key	Type	Default	Valid Values
multi_router_mode	String	"active"	"active", "disabled"
default_router_id	Number	null	> 0 atau null (untuk auto-detect)

---

Workflow Rekomendasi

Fase 1: Setup Single Router

1. settings.json: sudah ada MikroTik credentials
2. /admin/settings: mode = "Nonaktif", default_router_id kosong
3. Test isolir via admin
4. Test isolir via WhatsApp bot

Fase 2: Tambah Multi-Router (Nanti)

1. /admin/routers: tambah router 2, 3, dst
2. /admin/settings: mode = "Aktif" atau "Nonaktif" + default_router_id = 1
3. Pelanggan lama auto-assign (jika switch ke Nonaktif)
4. Pelanggan baru HARUS pilih router saat dibuat

---

Kesimpulan

✅ Saat edit pengaturan di web admin (/admin/settings), sekarang sudah TIDAK NULL lagi:

• Mode Multi-Router: Pilih "Aktif" atau "Nonaktif"
• Default Router ID: Opsional, biarkan kosong untuk auto-detect
• Simpan: Langsung tersimpan, tidak perlu restart
• Auto-Assignment: Jika mode berubah, pelanggan NULL auto-assign ke router yang sesuai

Mulai sekarang, setup semua lewat UI web admin - sudah production-ready! 🎉