OPEN-ISP v0.5 (pickle-lime) — rilis open-source perdana

Aplikasi billing & manajemen ISP (fiber optic) — PWA pelanggan, portal teknisi & kolektor, admin panel lengkap, multi-vendor OLT, RADIUS, WhatsApp/Telegram, pembayaran QRIS. Kredit & lisensi (ISC): - Base kode & repo: alijayanet/billing-rtrw oleh Alijaya Net — terima kasih banyak atas base kode dan repo yang bermanfaat. - Add-on: GoWA, LibreSpeed/OpenSpeedTest, Uptime Kuma, notification-forwarder. - Dikembangkan menjadi OPEN-ISP oleh oxpoe — https://github.com/oxpoe/open-isp
2026-10-09 05:51:21 +07:00
commit eaf05f2811
@@ -0,0 +1,729 @@
+# RINGKASAN APLIKASI - RTRWNET BILLING & MANAGEMENT SYSTEM
+**Status:** ✅ FULLY EXPLORED & DOCUMENTED  
+**Tanggal:** 14 Agustus 2026  
+**Format:** Quick Reference untuk understanding aplikasi
+
+---
+
+## 🎯 APLIKASI OVERVIEW
+
+### What is RTRWNET?
+**RTRWNET** adalah sistem manajemen terintegrasi untuk **ISP/RTRW** yang mengelola:
+- ✅ Billing & invoicing otomatis
+- ✅ Manajemen pelanggan & paket
+- ✅ Jaringan fisik (MikroTik, OLT, ODP, cable routing)
+- ✅ Device management (CPE/ONU via TR-069/GenieACS)
+- ✅ Payment gateway integration (Midtrans, Tripay, Xendit, Duitku)
+- ✅ Agent/reseller management
+- ✅ WhatsApp automation
+- ✅ Support ticketing
+- ✅ Peta jaringan & GIS
+- ✅ Monitoring & health check
+
+**Single Platform:** Satu dashboard untuk admin, teknisi, agen, dan pelanggan.
+
+---
+
+## 📚 PORTAL UTAMA
+
+| Portal | URL | User | Fungsi Utama |
+|--------|-----|------|--------------|
+| **Customer** | `/customer` | Pelanggan | Cek tagihan, bayar, ubah Wi-Fi, lihat status |
+| **Admin** | `/admin` | Admin | Dashboard, billing, customer, MikroTik, settings |
+| **Teknisi** | `/tech` | Teknisi | Tiket, peta, device monitoring, support |
+| **Agen** | `/agent` | Reseller/Agent | Bayar tagihan pelanggan, jual voucher, jual pulsa |
+| **Kolektor** | `/collector` | Collector | Cek & ajukan pembayaran (pending approval) |
+| **Finance** | `/finance` | Admin/Finance | Laporan keuangan & pengeluaran |
+| **Public** | `/` | Publik | Cek tagihan tanpa login, halaman info |
+
+---
+
+## 🏗️ ARSITEKTUR TEKNIS
+
+### Backend Services (34 services)
+```
+1. billingService.js          → Invoice generation, promo, prorata
+2. customerService.js          → CRUD customer, paket, isolir
+3. mikrotikService.js         → PPPoE, hotspot, firewall, monitoring
+4. oltService.js              → OLT management via SNMP
+5. whatsappService.js         → WhatsApp gateway (Baileys)
+6. paymentService.js          → Payment gateway integration
+7. voucherPaymentService.js   → E-voucher & payment methods
+8. agentService.js            → Agent & Digiflazz integration
+9. cronService.js             → Scheduled tasks automation
+10. monitoringService.js      → System health & metrics
+11. ticketService.js          → Support ticketing
+12. inventoryService.js       → Stock & asset management
+13. auditTrailService.js      → Action logging
+14. backupService.js          → Database backup
+15. onuProvisionService.js    → ONU TR-069 provisioning
+... + 19 services lainnya (acsServerService, radiusServerService, dll)
+```
+
+### Database (SQLite)
+```
+Total: 50+ tables
+
+Kategori:
+- Master: packages, customers, routers, olts, odps
+- Billing: invoices, payments, payment_approvals
+- Network: pppoe_users, hotspot_users, vouchers
+- Device: acs_devices, onu_mapping
+- Internal: technicians, agents, collectors, audit_trail
+- Other: expenses, cash_in, tickets, inventory_items
+```
+
+### Routes/Endpoints (250+ endpoints)
+```
+/customer/*         → Customer portal (login, billing, device)
+/admin/*           → Admin panel (all management)
+/tech/*            → Technician portal (tickets, map, devices)
+/agent/*           → Agent portal (payment, voucher, pulsa)
+/collector/*       → Collector portal (approval workflow)
+/finance/*         → Finance reporting
+/acs/*             → Built-in TR-069 ACS server
+/api/webhook/*    → Payment webhooks
+```
+
+### Frontend (EJS Templates)
+```
+18 main views + partials:
+- customer/         → 6 views (billing, device, voucher, etc)
+- admin/           → Subdirectory dengan main routes
+- tech/            → 3 views (dashboard, tickets, monitoring)
+- agent/           → 3 views
+- collector/       → 2 views
+- Public pages     → login, register, check_billing, tos, privacy
+```
+
+---
+
+## 💰 FITUR BILLING
+
+### Invoice Cycle
+```
+1. Otomatis: Cron @ 1 Jan setiap bulan jam 00:01
+   - Generate invoice untuk semua customer
+   - Kalkulasi promo price (jika applicable)
+   - Kalkulasi prorata (bulan pertama)
+   - Kalkulasi tax (PPN 11%)
+   - Status: 'unpaid'
+
+2. Notifikasi WhatsApp otomatis ke customer
+
+3. Customer bayar via:
+   - Payment gateway (Midtrans, Tripay, Xendit, Duitku)
+   - QRIS static (QR fixed dengan nominal unik)
+   - Manual via admin/agen
+   - Kolektor (pending approval)
+
+4. Status berubah: 'unpaid' → 'paid'
+
+5. Notifikasi paid + auto-unisolir jika dalam suspend
+
+6. Late payment → Auto-isolir @ hari yang ditentukan
+```
+
+### Promo & Prorata
+```
+Promo:
+- Paket A: Rp 350rb/bulan, promo Rp 250rb (3 siklus)
+- Pelanggan baru: dapat promo 3 bulan pertama
+- Counter ditrack di customer.promo_cycles_used
+- Reset otomatis saat ganti paket
+
+Prorata:
+- Tanggal pasang: 15 Agustus
+- Invoice pertama: Rp 350rb * (16 hari / 31 hari) = Rp 180rb
+- Bulan berikutnya: Rp 350rb penuh
+```
+
+### Payment Gateway
+```
+Aktif (bisa kombinasi):
+- Midtrans    → CC, Transfer, E-wallet
+- Tripay      → Bank Transfer, QRIS, E-wallet
+- Xendit      → Virtual Account, QR
+- Duitku      → Aggregator
+- QRIS Static → Fixed QR code
+
+Webhook Generic:
+- Endpoint: POST /api/webhook/v1/payment-notif
+- Accept dari bank/e-wallet apapun
+- Auto-match nominal → mark paid
+- Log semua untuk audit
+```
+
+---
+
+## 👥 CUSTOMER MANAGEMENT
+
+### Data per Customer
+```
+Identitas:
+- Nama, HP, Email, NIK, Alamat
+- GPS Latitude/Longitude
+- Area/Kabupaten
+
+Jaringan:
+- Paket (Starter/Pro/Premium)
+- MikroTik Router assign
+- PPPoE username
+- Hotspot username (optional)
+- Static IP (optional)
+- OLT & ONU Port
+- GenieACS Tag
+
+Status & Billing:
+- Status: active/suspended/inactive
+- Isolir day (tanggal isolir otomatis)
+- Auto-isolir enable/disable
+- Promo cycles used
+```
+
+### Isolir Workflow
+```
+Manual Isolir:
+1. Admin klik "Isolir" di customer detail
+2. Sistem hapus/disable PPPoE user di MikroTik
+3. Status berubah: active → suspended
+4. Redirect ke page /isolated (jika online)
+
+Auto-Isolir:
+1. Cron job setiap hari jam 02:00
+2. Cek customer: status=active + unpaid invoices + today >= isolate_day
+3. Suspend PPPoE ke MikroTik
+4. Notifikasi WhatsApp
+
+Unisolir:
+1. Pelanggan bayar
+2. Admin klik "Buka Isolir"
+3. Restore PPPoE user
+4. Status: suspended → active
+5. Customer online lagi
+```
+
+---
+
+## 🌐 MIKROTIK INTEGRATION
+
+### PPPoE Workflow
+```
+1. Create customer dengan PPPoE username
+2. Sistem generate PPPoE secret (password)
+3. Connect ke MikroTik Router API
+4. Add user ke PPPoE service
+5. Customer bisa login dengan username/password
+
+Live Monitoring:
+- View active sessions
+- Bytes in/out per session
+- Session duration
+- IP address
+
+FUP (Fair Usage Policy):
+- Paket: limit 100GB/bulan
+- Cron setiap jam cek usage
+- Jika > 100GB: ganti profile ke 1Mbps
+- Reset 1 Jan bulan berikutnya
+
+Night Mode (Jam Kalong):
+- 00:00 - 06:00: Speed 20Mbps
+- 06:00 - 00:00: Speed 10Mbps
+- Cron @ 00:00 & 06:00 switch profile
+```
+
+### Hotspot
+```
+Similar ke PPPoE:
+- Create user dengan limit (uptime/data)
+- Monitor active sessions
+- Bandwidth limiting
+```
+
+### Voucher Hotspot
+```
+1. Admin create batch (qty 100, validity 30 hari)
+2. Sistem generate 100 kode voucher unik
+3. Sync ke MikroTik hotspot
+4. Customer pakai untuk login hotspot portal
+5. Agent bisa jual voucher ke pelanggan
+6. Track status: created/active/used/expired
+```
+
+---
+
+## 🎛️ GENIEACS & TR-069
+
+### Built-in ACS
+```
+Aplikasi punya ACS internal (lightweight):
+- Tidak perlu GenieACS eksternal
+- Support ZTE, Huawei, FiberHome, dll
+- Auto-detect device properties
+- Port: 7547 (configurable)
+```
+
+### Device Management
+```
+Features:
+- List semua ONU/CPE
+- View device status (online/offline)
+- Change SSID / Wi-Fi password
+- Bulk SSID change
+- Reboot device
+- Provision WAN (VLAN, bridge, PPPoE)
+- View device logs
+- Parameter configuration
+```
+
+### Workflow
+```
+1. ONU/CPE boot → connect ke ACS server
+2. Sistem auto-detect device properties
+3. Admin bisa configure via panel
+4. Change SSID → send ke device via TR-069
+5. Device update config otomatis
+6. Customer notif via WhatsApp
+```
+
+---
+
+## 🔌 OLT & ONU MANAGEMENT
+
+### OLT Setup
+```
+Konfigurasi:
+- IP address OLT
+- SNMP community string
+- Telnet credentials (untuk config WAN)
+- Web interface credentials
+
+Multi-OLT:
+- Bisa manage banyak OLT sekaligus
+- Per pelanggan assign ke OLT mana
+```
+
+### ONU Monitoring
+```
+Via SNMP query:
+- Status (online/offline)
+- Serial number
+- Optical signal (dBm)
+- Distance ke OLT
+- RX/TX power
+
+Operations:
+- Reboot ONU
+- Rename (friendly name)
+- Authorize ONU (EPON)
+- Configure WAN (via Telnet/TR-069/REST API)
+```
+
+---
+
+## 💳 PAYMENT FLOW
+
+### Customer Bayar Invoice
+```
+1. Customer login portal
+2. Lihat tagihan belum bayar
+3. Click "Bayar"
+4. Pilih metode pembayaran (dari gateway aktif)
+5. Redirect ke payment gateway
+6. Customer input data (CC/transfer/etc)
+7. Gateway proses
+8. Success → Webhook ke aplikasi
+9. Aplikasi verify amount & signature
+10. Mark invoice PAID
+11. Send WhatsApp confirmation
+12. Auto-unisolir jika customer dalam suspend
+13. Dashboard terupdate
+```
+
+### Webhook Payment
+```
+Generic endpoint untuk bank/e-wallet:
+POST /api/webhook/v1/payment-notif
+
+Bisa terima dari:
+- Bank (SMS gateway → webhook)
+- E-wallet (API callback)
+- QRIS (bank QRIS provider)
+
+Sistem:
+- Parse amount dari notifikasi
+- Find invoice / voucher dengan nominal cocok
+- Verify jika nominal sudah digunakan (duplikasi)
+- Mark as PAID
+- Log untuk audit
+```
+
+---
+
+## 🗺️ GIS MAPPING
+
+### Peta Admin
+```
+Features:
+- Leaflet map (OpenStreetMap + Satellite)
+- Marker customer (warna: hijau/merah/biru)
+- Marker ODP (orange)
+- Draw cable path (customer → ODP)
+- Popup detail (klik marker)
+- Zoom/pan/locate
+
+Interaksi:
+- Click customer → detail + isolir button
+- Click ODP → info + available ports
+- Draw polyline → cable path (simpan)
+- Real-time PPPoE traffic graph
+- Google Maps route (untuk tech)
+```
+
+### Cable Path
+```
+Simpan rute dari customer ke ODP:
+- Array of [lat, lng] coordinates
+- Calculate distance (KM)
+- Description (aerial/underground/etc)
+- Edit/delete existing path
+```
+
+### Tech GPS (Optional)
+```
+- Tech login portal dengan mobile
+- Sistem track GPS lokasi tech
+- Geofence alert (keluar/masuk area kantor)
+- Nearby customers di radius tertentu
+- Chat WhatsApp dari peta
+```
+
+---
+
+## 💬 WHATSAPP AUTOMATION
+
+### Setup
+```
+1. Admin buka /admin/whatsapp
+2. Scan QR code dengan WhatsApp app
+3. Verify & approve
+4. Bot siap mengirim pesan
+
+Gateway:
+- Baileys (Unofficial WebSocket)
+- Meta Cloud API (Official, jika setup)
+```
+
+### Automated Messages
+```
+Invoice Created:
+"Tagihan Anda bulan ini siap!
+Nominal: Rp 350.000
+Bayar di: [link]
+Due: 10 Agustus"
+
+Invoice Paid:
+"✅ Pembayaran diterima!
+Tagihan Rp 350.000 LUNAS
+Terima kasih!"
+
+Isolir Reminder (H-1):
+"⚠️ Reminder: Jatuh tempo BESOK
+Tagihan Rp 350.000
+Bayar untuk hindari isolir"
+
+Isolir Notice:
+"⚠️ Layanan Anda DIPUTUS
+Penyebab: Tagihan belum dibayar
+Hubungi [support]"
+
+Unisolir:
+"✅ Layanan Anda kembali AKTIF
+Terima kasih pembayarannya!"
+```
+
+### Admin Commands (via WhatsApp)
+```
+"BILLING" → Send laporan billing hari ini
+"PPPOE" → List active PPPoE sessions
+"BALANCE" → Cek saldo Digiflazz
+"TOPUP 1000000" → Top-up agent
+"INVOICE" → List unpaid invoices
+```
+
+### Broadcast
+```
+Select customers → Create message → Schedule → Send
+- Set delay antar pesan (3-5 detik)
+- Track delivery status
+- Pause/resume/stop anytime
+- Retry failed messages
+```
+
+---
+
+## 👔 AGENT MANAGEMENT
+
+### Agent Fitur
+```
+Dashboard:
+- Total saldo (Rp)
+- Today's transaction
+- Commission earned
+- Top customers
+
+Pembayaran:
+- Cari pelanggan
+- Lihat unpaid invoices
+- Bayar dari saldo agent
+- Print struk
+
+Voucher:
+- Lihat inventory
+- Jual ke customer
+- Print code
+- Track sale
+
+Digiflazz (Pulsa/Data):
+- Browse produk (Telkomsel, Indosat, dll)
+- Category → Brand → Nominal
+- Buy untuk customer
+- Webhook status update
+```
+
+### Admin Agent Control
+```
+- Create/edit agent
+- Top-up balance
+- Set commission %
+- View transaction history
+- Special pricing per agent
+- Performance report
+```
+
+---
+
+## 🎫 TICKETING SYSTEM
+
+### Ticket Status Flow
+```
+open → in_progress → resolved → closed
+
+Open:
+- Customer create di portal
+- Auto-assign ke admin/tech
+
+In Progress:
+- Tech ambil ticket
+- Add notes/photos
+- Update status
+
+Resolved:
+- Tech mark selesai
+- Notif ke customer
+
+Closed:
+- Customer confirm selesai
+- Optional: give rating (1-5)
+```
+
+### Admin Features
+```
+- Dashboard tickets (count per status)
+- Assign ke technician
+- Reassign jika perlu
+- View ticket history
+- SLA tracking
+- Performance report
+```
+
+### Tech Features
+```
+- Pool tickets (assigned to me)
+- View detail
+- Take ticket
+- Upload photos (before/after)
+- Add resolution notes
+- Mark resolved
+```
+
+### Customer Features
+```
+- Create ticket
+- View my tickets
+- See status update
+- Add comment/photo
+- Rate satisfaction
+```
+
+---
+
+## ⚙️ AUTOMATION (CRON JOBS)
+
+| Waktu | Tugas | Detail |
+|-------|-------|--------|
+| 1 Jan @ 00:01 | Generate invoices | Monthly billing untuk semua customer |
+| Setiap hari @ 02:00 | Auto-isolir | Suspend customer overdue |
+| Setiap hari @ 09:00 | Reminder tagihan | WhatsApp reminder H-1 isolir |
+| 00:00 & 06:00 | Night mode | Ganti profile PPPoE malam/siang |
+| Setiap jam | FUP check | Check usage vs limit, ganti profile |
+| Setiap 10 menit | Usage sync | Sinkron PPPoE traffic dari MikroTik |
+| Setiap hari @ 02:00 | Database backup | Auto-backup dengan retention |
+
+---
+
+## 📊 DATABASE OVERVIEW
+
+### Key Tables
+```
+customers
+├── Identitas (name, phone, email, nik)
+├── Jaringan (pppoe_username, hotspot_username, static_ip)
+├── Device (olt_id, onu_port, genieacs_tag)
+├── Billing (package_id, isolate_day, auto_isolate)
+└── Status (status, created_at, updated_at)
+
+invoices
+├── Amount (amount, status, qris_amount_unique)
+├── Period (period_month, period_year)
+├── Payment (paid_at, payment_method)
+└── Notes (promo/prorata info)
+
+payments
+├── Transaction data (gateway_id, signature, status)
+├── Customer info
+└── Invoice link
+
+pppoe_users
+├── Credentials (username, secret)
+├── Profile & limits
+└── Session tracking
+
+... + 40+ tables lainnya
+```
+
+---
+
+## 🎯 SUMMARY - FITUR UTAMA YANG BERJALAN
+
+✅ **Billing & Invoicing**
+- Auto generate bulanan
+- Promo cycles tracking
+- Prorata bulan pertama
+- Multi-gateway payment
+
+✅ **Customer Lifecycle**
+- CRUD pelanggan
+- Paket management
+- Auto-isolir/unisolir
+- Status tracking
+
+✅ **Network Management**
+- MikroTik PPPoE/Hotspot
+- Voucher hotspot
+- Firewall & rate limiting
+- Night mode automation
+
+✅ **Device Management**
+- Built-in TR-069 ACS
+- GenieACS integration
+- SSID/password change
+- Device provisioning
+
+✅ **OLT/ONU Management**
+- SNMP monitoring
+- Reboot/rename/authorize
+- WAN configuration
+- Multi-brand support
+
+✅ **Payment Processing**
+- 4 payment gateways
+- QRIS static
+- Generic webhook
+- Payment verification
+
+✅ **GIS Mapping**
+- Leaflet maps
+- Cable path tracking
+- GPS tech tracking
+- Real-time graphs
+
+✅ **WhatsApp Automation**
+- Invoice notification
+- Payment reminder
+- Isolir notice
+- Broadcast messaging
+
+✅ **Agent Management**
+- Pembayaran dari saldo
+- Voucher sales
+- Pulsa/data (Digiflazz)
+- Commission tracking
+
+✅ **Support Ticketing**
+- Create/assign/resolve
+- Photo upload
+- Rating system
+- History tracking
+
+✅ **Monitoring**
+- System health metrics
+- Service status
+- Alert system
+- Performance tracking
+
+✅ **Automation**
+- 7 scheduled jobs
+- Configurable timing
+- Error handling
+- Logging
+
+✅ **Multi-Portal**
+- Customer self-service
+- Admin full control
+- Technician field support
+- Agent sales
+- Collector approval
+
+✅ **Compliance**
+- Audit trail logging
+- Role-based access
+- Session management
+- Data validation
+
+---
+
+## 🚀 PRODUCTION STATUS
+
+**Aplikasi ini SUDAH BERJALAN** dan mencakup:
+- ✅ Complete billing system
+- ✅ Full customer management
+- ✅ Network device integration
+- ✅ Payment processing
+- ✅ Multi-user portals
+- ✅ Automation & scheduling
+- ✅ Monitoring & health check
+
+**Siap untuk:**
+- ✅ Production deployment
+- ✅ Scaling operasi ISP
+- ✅ Integration ke sistem existing
+- ✅ Customization per requirements
+
+---
+
+## 📖 DOKUMENTASI TERSEDIA
+
+1. **FITUR_APLIKASI_LENGKAP.md** ← Dokumentasi ini (16 fitur utama + detail)
+2. **AUDIT_LENGKAP.md** (Existing) ← Technical deep dive
+3. **DATABASE_SCHEMA.md** (Existing) ← Struktur data lengkap
+4. **QUICK_REFERENCE.md** (Existing) ← Common commands
+5. **AUDIT_SECURITY_2026.md** (Baru) ← Security audit findings
+6. **IMPLEMENTATION_GUIDE_SECURITY.md** (Baru) ← Fix guide
+7. **README.md** (Existing) ← Instalasi & setup
+
+---
+
+**Status:** ✅ Aplikasi komprehensif, well-documented, siap production  
+**Next Step:** Implementasi security fixes (bcrypt, .env, CSRF) sebelum production