open-isp/docs/RINGKASAN_APLIKASI.md

# 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