# HotspotPro v4 — Mwongozo wa Vipengele Vipya

## 1. Voucher Generator (Prefix-based)

### Usakinishaji
```bash
# Weka dompdf kwa PDF export nzuri
composer require dompdf/dompdf
```

Kama hauna composer, pakua dompdf moja kwa moja:
```bash
cd hotspot-v3
wget https://github.com/dompdf/dompdf/releases/download/v2.0.4/dompdf_2-0-4.zip
unzip dompdf_2-0-4.zip -d vendor_temp
mv vendor_temp/dompdf-2.0.4 vendor/dompdf
```

### Jinsi Inavyofanya Kazi
- Admin anaandika prefix (mf. `Luxtech`) na idadi (mf. 50)
- Mfumo unaangalia namba ya mwisho iliyotumika kwa prefix hiyo kwenye DB
- Inatengeneza: `Luxtech000`, `Luxtech001`, `Luxtech002`... mfululizo bila mgongano
- Kila password ni random na haijirudii kamwe (inacheki DB kabla ya kutumia)
- Kila batch inapata `batch_id` ya kipekee na `batch_month` kwa ajili ya kuchuja
- Export: PDF (cards au table, na watermark ya jina la WiFi) au CSV

### Database Mpya
Tekeleza `alter_v4.sql` kwenye database iliyopo:
```bash
mysql -u root -p hotspot_v3 < alter_v4.sql
```

---

## 2. Live Monitor — ISP-Grade Dashboard

Ukurasa mpya: `admin/live_monitor.php`

### Summary Bar (juu kabisa)
Inaonyesha idadi ya: Online, Active (🟢), Idle (🟡), Expired (🔴) kwa wakati halisi.

### Kila User Card Inaonyesha
- Status badge (Active/Idle/Expired) — kipengele cha kwanza
- Remaining time kama "2h 30m left" badala ya tarehe ghafi
- Live speed (Mbps) ya download/upload
- Device type (📱 Android/iPhone, 💻 Laptop) — inatambuliwa kutoka User-Agent au MAC OUI
- Connection source (RADIUS Live / RouterOS API / Database)
- IP + MAC address
- Data usage na progress bar
- Package name, simu ya mteja, session uptime, NAS IP
- Quick Actions: **Extend** (ongeza muda), **Limit** (punguza speed), **Disconnect** (toa mtandaoni)

### Jinsi "Active vs Idle" Inavyopimwa
Mfumo unatumia `last_seen` timestamp:
- **Active** 🟢 — heartbeat/data ya hivi karibuni (chini ya dakika 5)
- **Idle** 🟡 — amekaa connected lakini hakuna mwendo wa data zaidi ya dakika 5
- **Expired** 🔴 — muda wa voucher umeisha

### Weka Heartbeat kwenye MikroTik (Active/Idle detection)

Ongeza scheduler ya MikroTik inayotuma heartbeat kila dakika kwa kila active user:

```
/system scheduler add name=hotspot-heartbeat interval=1m on-event={
  :foreach i in=[/ip hotspot active find] do={
    :local uname [/ip hotspot active get $i user]
    :local bin [/ip hotspot active get $i bytes-in]
    :local bout [/ip hotspot active get $i bytes-out]
    /tool fetch url="https://DOMAIN_YAKO/hotspot-system/api/hotspot_event.php?event=heartbeat&user=$uname&bytes-up=$bin&bytes-down=$bout" keep-result=no
  }
}
```

### Device Detection (User-Agent)
Kwa utambuzi sahihi zaidi wa device, ongeza JS kwenye `hotspot.php` (au login page ya MikroTik) inayotuma User-Agent wakati wa login:

```javascript
// Tuma User-Agent pamoja na taarifa za login
fetch('/api/hotspot_event.php?event=login&user='+username+'&ua='+encodeURIComponent(navigator.userAgent));
```

### Disconnect / Extend / Limit — Jinsi Zinavyofanya Kazi
- **Disconnect**: Inatuma RADIUS Disconnect-Request (CoA, port 3799) NA kuondoa moja kwa moja kwenye RouterOS API active list
- **Extend**: Inaongeza `expires_at` ya voucher kwenye DB na kusasisha `Session-Timeout` ya RADIUS
- **Limit**: Inaweka `Mikrotik-Rate-Limit` mpya kwenye RADIUS attributes (CoA inahitajika kwa MikroTik kutekeleza papo hapo bila mtumiaji kuingia tena)

### RADIUS CoA — Weka MikroTik Kupokea Disconnect/Limit
```
/radius incoming add accept=yes port=3799
```

---

## Usalama
- Quick actions (disconnect/extend/limit) zinacheki kwanza kama voucher ni ya admin anayeomba — hauwezi kudhibiti vouchers za admin mwingine
- Speed snapshots zinafutwa kiotomatiki baada ya session kufungwa (hazikui bila mpaka)