# Guida admin — setup e pannello

Guida operativa per chi gestisce il bot (super-admin e admin aggiunti).

## Avvio rapido

1. Compila `config.php`:
   - `bot_token`
   - `bot_username` (senza `@`)
   - `admin_ids` → i tuoi ID numerici (**super-admin**)
2. Avvia in locale:

```bash
cd /Applications/MAMP/htdocs/bot
php poll.php
```

3. In privato col bot: `/start` → `/settings`
4. Nel supergruppo: bot **amministratore** con:
   - limita membri
   - elimina messaggi (consigliato)
   - ban utenti (se usi ban/kick)
5. Nel gruppo: `/setgroup` (il comando viene cancellato; conferma in privato)
6. Per collegare **altri gruppi**: ripeti il passo 5 in ciascun gruppo — ogni gruppo ha impostazioni indipendenti

### Multi-gruppo

Una sola installazione può gestire più gruppi contemporaneamente, **ognuno con un proprietario indipendente**:

| Cosa | Comportamento |
|------|----------------|
| `/setgroup` | **Registra** (o aggiorna) il gruppo corrente senza rimuovere gli altri. Chi lo esegue ne diventa **proprietario** |
| `/unsetgroup` | Disattiva il gruppo (**proprietario del gruppo** o super-admin); non cancella i dati |
| `/settings` → 🏘 Gruppi | Scegli il **gruppo attivo**: tutte le impostazioni del pannello si applicano a quel gruppo |
| Blacklist, VIP, whitelist link, scam, reviewer | Separati per gruppo |
| Super-admin (`config.php`) | Globali su **tutti** i gruppi |
| Proprietario del gruppo | Admin **solo del proprio** gruppo: vede e modifica solo i suoi settings |
| Reviewer aggiunti | Solo sul gruppo in cui li aggiungi |

Il gruppo attivo resta memorizzato per admin: cambia quando selezioni un altro gruppo o fai `/setgroup` in un gruppo.

#### Onboarding self-serve (ogni cliente gestisce il suo gruppo)

Non serve che tu sia in `config.php` per collegare un gruppo: **chiunque sia creatore o amministratore Telegram del gruppo** può fare `/setgroup` e diventa automaticamente **admin del proprio gruppo** (e solo di quello). Così ogni cliente:

- aggiunge il bot al suo gruppo, si rende amministratore, esegue `/setgroup`;
- apre `/settings` in privato col bot e gestisce **solo il suo gruppo**, in totale isolamento dagli altri clienti;
- il **primo** che collega un gruppo ne resta proprietario (non può essere sostituito da un altro con un secondo `/setgroup`).

Tu (super-admin in `config.php`) resti comunque admin globale su tutti i gruppi.

### Free vs Pro / Business

Il bot si installa e funziona in **modalità Free senza passare dal sito**: basta aggiungerlo al gruppo e fare `/setgroup`.

| Piano | Come si attiva | Cosa include |
|-------|----------------|--------------|
| **Free** | Solo Telegram (`/setgroup`) — nessun sito | Verifica videobolla, approvazione manuale, messaggi personalizzati, blacklist (fino a 20), ban/unmute |
| **Pro / Business** | Dal **sito** (checkout) → poi `/setgroup` | Tutto il Free + approvazione automatica/ibrida, media, filtro link, 🔐 Sicurezza, captcha, VIP, ⚠️ Warn, 🔁 Ripetuti, 📊 Sondaggi, 🚫 Parole vietate, blacklist illimitata, più gruppi (Business: gruppi illimitati, export/backup/webhook/dashboard) |

Le funzioni Pro nel pannello mostrano un **lucchetto** 🔒: toccandole appare l’offerta con i pulsanti per acquistare/aprire il catalogo. Il **super-admin** (proprietario del bot in `config.php`) le usa sempre, anche senza abbonamento.

#### Prova Free a tempo (7 giorni)

La **videobolla + approvazione manuale** funzionano come **prova di 7 giorni**. Allo scadere si bloccano **solo queste due funzioni**: **tutte le altre sezioni Free restano attive** (messaggi personalizzati, blacklist, ban/unmute, ecc.). Il proprietario del gruppo e gli admin ricevono su Telegram un avviso con i pulsanti per passare a un piano a pagamento (max un avviso al giorno).

- La durata si imposta per bot in **Admin → (bot) → Prezzi → colonna "Prova (giorni)"** sul piano Free (`0` = illimitato).
- L'admin può **estendere** una singola licenza in **Admin → (bot) → Licenze → Estendi** (l'utente riceve notifica automatica).
- Il conteggio parte dall'attivazione Free sul sito, oppure — per i gruppi collegati senza attivazione — dalla data del primo `/setgroup` (`platform.free_trial_days` in `config.php`, default 7).

**Cosa succede dopo i 7 giorni quando un membro apre il bot:** i nuovi ingressi non vengono più messi in verifica (l'utente entra senza videobolla), e se un utente apre "Video Bolla CHECK" dalla lista membri e preme *Avvia*, il bot **non lo muta** e gli mostra un messaggio che la verifica non è attiva (invitandolo a contattare gli admin). Nel frattempo al proprietario/admin arriva l'avviso di upgrade. Durante la prova (o con un piano attivo), invece, aprendo il bot parte regolarmente la richiesta di videobolla.

#### Sconti / codici promo

In **Admin → Sconti** crei e gestisci i **codici sconto** applicati al checkout: percentuale o importo fisso, validi per tutti i bot o per un bot/piano specifico, con finestra temporale e limiti d'uso (totali e per utente). L'utente inserisce il codice nella pagina di checkout.

### Produzione (webhook)

```bash
php set_webhook.php https://TUO-DOMINIO/bot/webhook.php
```

Non usare insieme `poll.php` e webhook.

## Ruoli

| Ruolo | Dove | Cosa può fare |
|-------|------|----------------|
| **Super-admin** | `config.php` → `admin_ids` | Tutto, inclusi toggle **🔐 Sicurezza**, svuota blacklist/whitelist, VIP, scam list, riverifica massiva |
| **Admin aggiunto** | `/settings` → 👥 Admin | Approvare/rifiutare videobolle, messaggi/media, pending/stats. Blacklist solo se "Reviewer ban" è ON |
| **VIP** | Sicurezza → VIP | Salta la verifica se "VIP skip" è ON |

---

## Lingue

Il bot è multilingua: **IT, EN, ES, DE, FR, RU**.

| Chi | Come |
|-----|------|
| **Utente** | `/lang` oppure pulsante 🌐 Lingua in `/start` / `/help` / `/settings` |
| **Default bot** (gruppo / nuovi) | Super-admin: `/settings` → 🌐 Lingua bot |
| **Messaggi custom** | In 💬 Messaggi puoi scegliere la lingua di editing; ogni testo si salva per lingua |

Al primo `/start` il bot prova a usare il `language_code` Telegram dell'utente se supportato.

I testi di default (istruzioni, ok, rifiuto, benvenuto, note qualità, avviso link) vivono in `lang/*.php`. Se li personalizzi dal pannello, l'override vale per quella lingua.

---

# Il pannello `/settings` in dettaglio

Il pannello principale mostra un riepilogo dello stato (verifica ON/OFF, modalità, gruppo collegato, numero admin, blacklist, filtro link) e i pulsanti sotto. Ogni sezione è spiegata qui.

## Pannello principale

| Pulsante | Funzione |
|----------|----------|
| 🏘 Gruppi | Scegli il **gruppo attivo** (impostazioni indipendenti per gruppo) |
| 🟢 Attiva / 🔴 Disattiva | Accende o spegne **tutta la verifica**. Se OFF, i nuovi membri non vengono mutati né verificati |
| 🔄 Modalità | Cicla tra le 3 modalità di approvazione (vedi sotto) |
| ⏱ Min − / + | Durata **minima** della videobolla in secondi (passi da 5s, range 1–120). Video più corti vengono rifiutati automaticamente dal bot |
| ⏱ Max − / + | Durata **massima** in secondi (passi da 5s, range 5–300). Video più lunghi vengono rifiutati automaticamente |
| ⏳ Timeout − / + | Minuti a disposizione dell'utente per completare la verifica (passi da 5, range 5–1440). Allo scadere la verifica diventa "expired" e scatta l'azione timeout (vedi 🛡 Ban / azioni) |
| 🔔 Notifiche | ON/OFF notifiche agli admin per le verifiche in modalità ibrida. In modalità manuale la notifica arriva sempre |
| 📋 In attesa | Elenco delle verifiche in `pending_review` (ID, nome, durata video) |
| 👥 Admin | Reviewer e destinatari notifiche |
| 💬 Messaggi | Testi verifica / benvenuto |
| 🔁 Ripetuti | Messaggi automatici nel gruppo a intervallo |
| 🖼 Media | Foto allegate ai messaggi |
| 📊 Sondaggi | Crea e pubblica sondaggi nel gruppo (opzioni + durata) — *Pro* |
| 🚫 Parole vietate | Rimuove i messaggi con parole/frasi in lista — *Pro* |
| ⛔ Blacklist | Utenti bloccati |
| 🔗 Link | Filtro link |
| 🛡 Ban / azioni | Azioni su rifiuto/timeout |
| ⚠️ Warn | Warn/strike del gruppo attivo |
| 🔐 Sicurezza | Moduli avanzati (+ 🛡 Anti-spam) — dettagli in `SICUREZZA.md` |
| 👁 Anteprima bot | Invia a te, in sequenza, i messaggi come li vede un utente reale: istruzioni → approvato → benvenuto (con nome di esempio "Mario Rossi" e foto se impostate) |
| 📊 Stats | Contatori per stato: in attesa video, in review, approvate, rifiutate, scadute, revocate |
| 🔄 Aggiorna | Ridisegna il pannello con i valori correnti |
| 🌐 Lingua | Lingua UI; super-admin anche 🌐 Lingua bot |

### Le 3 modalità di approvazione

| Modalità | Comportamento |
|----------|----------------|
| **Manuale** | Ogni videobolla valida va in coda: gli admin ricevono video + pulsanti ✅ Approva / ❌ Rifiuta. L'utente resta mutato finché un admin decide |
| **Automatica** | Se la durata è nel range min–max, l'utente viene sbloccato subito, senza intervento umano |
| **Ibrida** | Come l'automatica, ma gli admin ricevono comunque il video con un pulsante 🚫 **Revoca accesso**: se qualcosa non va, l'utente viene rimutato |

---

## 👥 Admin

Gestisce chi può approvare le videobolle e chi riceve le notifiche.

| Pulsante | Funzione | Chi |
|----------|----------|-----|
| ➕ Aggiungi admin | Il bot ti chiede l'**ID numerico** dell'utente oppure di **inoltrargli un messaggio**. L'utente diventa "admin aggiunto" (reviewer) | Solo super-admin |
| 🔔 Tutti gli admin / Solo admin aggiunti | Cambia i **destinatari** delle notifiche videobolla: tutti (principali + aggiunti) oppure solo gli aggiunti. Se non ci sono aggiunti, la notifica va comunque ai principali | Solo super-admin |
| 🗑 (per ogni admin aggiunto) | Rimuove quell'admin | Solo super-admin |
| ⬅️ Impostazioni | Torna al pannello principale | Tutti |

**Anti-conflitto:** quando un admin approva o rifiuta, gli altri ricevono un avviso ("Verifica #X già approvata da …") e i pulsanti sulla loro copia si disattivano. Se cliccano comunque, appare l'alert "Già gestito da …".

Gli admin principali (`config.php`) non compaiono tra i rimovibili: si modificano solo dal file.

---

## 🔁 Messaggi ripetuti

Messaggi che il bot pubblica **nel gruppo** a intervallo, in rotazione (regolamento, promo, avvisi).

| Impostazione | Funzione |
|--------------|----------|
| 🟢/🔴 Attiva | Accende/spegne l’invio automatico per il gruppo attivo |
| ⏱ Intervallo | Cicla tra 15 / 30 / 60 / 120 / 180 / 360 / 720 / 1440 minuti |
| 🗑 Cancella precedente | Se ON, elimina l’ultimo messaggio ripetuto prima di postarne uno nuovo |
| ➕ Aggiungi | Invia testo oppure foto (+ didascalia opzionale) |
| ▶️ Invia ora | Forza subito il prossimo messaggio della coda (test) |
| 🟢/⏸ + 🗑 su ogni item | Attiva/disattiva o elimina un messaggio dalla coda |

I messaggi sono **per gruppo** (multi-gruppo indipendente). Serve che il bot possa scrivere nel gruppo (permesso “Invia messaggi”).

---

## 📊 Sondaggi *(Pro)*

Crea sondaggi nativi Telegram con opzioni predefinite e pubblicali nel **gruppo attivo** (`/settings` → 📊 Sondaggi).

| Pulsante | Funzione |
|----------|----------|
| ➕ Nuovo sondaggio | Il bot chiede la **domanda**, poi le **opzioni** (una per riga o separate da “;”, da 2 a 10) |
| 📣 Pubblica | Invia il sondaggio nel gruppo |
| ⏱ (durata) | Cicla la durata: ∞ / 5m / 10m / 30m / 1h / 3h / 6h / 12h / 1g. A scadenza il sondaggio si chiude |
| 🕶 / 👁 | Anonimo oppure a voto pubblico |
| 1️⃣ / ☑️ | Risposta singola oppure a scelta multipla |
| 🗑 | Elimina il sondaggio salvato |

**Durata:** fino a 10 minuti usa la chiusura nativa di Telegram; oltre i 10 minuti il bot chiude il sondaggio automaticamente al momento giusto (serve che resti in esecuzione — `poll.php`/webhook). Le opzioni sono **editabili** in fase di creazione (basta ricrearlo con le nuove opzioni).

---

## 🚫 Parole vietate *(Pro)*

Rimuove i messaggi che contengono parole o frasi della lista, nel **gruppo attivo** (`/settings` → 🚫 Parole vietate). Gli admin sono esentati.

| Pulsante | Funzione |
|----------|----------|
| 🟢/🔴 Attiva | Accende/spegne il filtro per il gruppo attivo |
| ⚙️ Azione | Cicla: Elimina · Elimina + avviso · + mute · + espelli · + ban |
| ➕ Aggiungi | Invia una o più parole/frasi (una per riga o separate da virgola) |
| 🧹 Svuota | Cancella tutta la lista del gruppo |
| 🗑 (per parola) | Rimuove una singola voce |

**Match:** una **parola singola** fa match “a parola intera” (`spam` non blocca `class`); una **frase** (con spazi) fa match come sottostringa. Tutto è case-insensitive e per-gruppo.

---

## ⚠️ Warn

Gestione warn/strike del **gruppo attivo** (`/settings` → ⚠️ Warn).

| Pulsante | Funzione | Chi |
|----------|----------|-----|
| ➕ Warn | Assegna un warn (`ID motivo` oppure ID/inoltro + motivo) | Admin |
| 🧹 Azzera | Elimina tutti i warn di un utente | Admin |
| ↩️ Rimuovi ultimo | Toglie solo l’ultimo warn | Admin |
| 📋 Recenti | Ultimi warn registrati | Admin |
| 🏆 Classifica | Utenti con più warn | Admin |
| 🟢/🔴 Strike ON/OFF | Attiva la scala automatica (flood/forward/scam) | Solo super-admin |
| Max ± | Soglia ban (2–10) | Solo super-admin |

Scala se strike ON: 1 avviso → 2 mute → 3 kick → max+ ban+blacklist.

Anche da comando: `/warn ID motivo` (privato o reply nel gruppo).

---

## 💬 Messaggi

Tutti i testi che il bot invia, modificabili da Telegram senza toccare il codice.

| Messaggio | Quando viene inviato |
|-----------|----------------------|
| **Benvenuto nel gruppo** | Nel gruppo, quando un utente viene approvato |
| **Istruzioni verifica (DM)** | In privato, quando parte la verifica |
| **Verifica approvata (DM)** | In privato, all'approvazione |
| **Verifica rifiutata (DM)** | In privato, al rifiuto |

Per ogni messaggio hai due pulsanti:

- **✏️ (modifica)** — il bot ti mostra il testo attuale e ti chiede il nuovo: scrivilo come messaggio normale e viene salvato. `/annulla` per uscire senza salvare
- **👁 (anteprima)** — ti invia il messaggio renderizzato come lo vedrebbe l'utente

Altri pulsanti:

| Pulsante | Funzione |
|----------|----------|
| 🟢/🔴 Attiva/Disattiva benvenuto | ON/OFF del messaggio di benvenuto nel gruppo (gli altri messaggi sono sempre attivi) |
| 🖼 Gestisci immagini | Scorciatoia al menu Media |

**Segnaposto disponibili nei testi:**

| Segnaposto | Sostituito con |
|------------|----------------|
| `{name}` | Nome dell'utente (nel benvenuto è cliccabile) |
| `{group}` | Nome del gruppo collegato |
| `{timeout}` | Minuti di timeout correnti |

---

## 🖼 Media

Associa una **foto** a ciascuno dei 4 messaggi: il testo diventa la didascalia della foto.

Per ogni messaggio (Benvenuto, Istruzioni, Approvato, Rifiutato):

| Pulsante | Funzione |
|----------|----------|
| 📷 | Il bot ti chiede una foto: inviala **come foto** (non come file/documento). Viene salvato il `file_id` Telegram, nessun file sul server |
| 👁 | Anteprima foto + testo insieme |
| 🗑 | Rimuove la foto (il messaggio torna solo testo) |

Se la foto è impostata ma il testo è vuoto, viene inviata solo la foto. Se Telegram rifiuta la foto (es. `file_id` scaduto), il bot ripiega sul solo testo.

---

## ⛔ Blacklist

Utenti bloccati: se rientrano nel gruppo vengono **bannati o espulsi automaticamente** (a seconda di "Rientro" in 🛡 Ban / azioni).

| Pulsante | Funzione | Chi |
|----------|----------|-----|
| ➕ Aggiungi | Invia ID numerico o inoltra un messaggio dell'utente. Se "Rientro → Ban" è ON, il bot lo banna subito dal gruppo | Admin (aggiunti solo se "Reviewer ban" ON) |
| ➖ Rimuovi | Invia l'ID da togliere dalla lista | Admin |
| 📋 Elenco | Mostra fino a 25 voci: ID, nome, motivo | Admin |
| 🗑 Svuota tutto | Cancella **tutta** la blacklist, con conferma Sì/No | Solo super-admin |

Come si finisce in blacklist:
- aggiunta manuale (qui)
- rifiuto/timeout verifica se "BL rifiuto/BL timeout" sono ON (🛡 Ban / azioni)
- azione "ban" del filtro link
- 4° strike (se strike attivi)

---

## 🔗 Link

Filtro antispam sui messaggi del gruppo. Agisce **solo sui non-admin** e solo nel gruppo collegato.

| Pulsante | Funzione |
|----------|----------|
| 🟢/🔴 Attiva/Disattiva filtro | Interruttore generale: se OFF, nessun controllo |
| Invite TG | Blocca i link di invito `t.me/+...` e `t.me/joinchat/...` |
| Canali/@ | Blocca link a canali/gruppi (`t.me/nome`) e menzioni `@username` |
| URL esterni | Blocca gli URL http/https verso siti esterni |
| ⚡ Azione | Cicla cosa fare quando trova un link vietato (vedi sotto) |
| ➕ Whitelist | Aggiungi un dominio/pattern **sempre permesso** (es. `youtube.com`, `t.me/tuocanale`) |
| 📋 Lista WL | Elenco whitelist con 🗑 per rimuovere le singole voci |
| 🗑 Svuota whitelist | Cancella tutta la whitelist, con conferma (solo super-admin) |

Le 5 azioni (in ordine di severità):

| Azione | Effetto |
|--------|---------|
| **Solo elimina** | Cancella il messaggio e basta |
| **Elimina + avviso** | Cancella e posta l'avviso configurato nel gruppo |
| **Elimina + mute** | Cancella e muta l'utente |
| **Elimina + kick** | Cancella ed espelle (può rientrare) |
| **Elimina + ban** | Cancella, banna e mette in **blacklist** |

La whitelist vince sempre: un link che contiene un pattern in whitelist non viene mai bloccato.

---

## 🛡 Ban / azioni

Cosa succede all'utente quando la verifica **fallisce**.

| Pulsante | Funzione |
|----------|----------|
| Rifiuto: Nessuna/Kick/Ban | Azione quando un admin **rifiuta** la videobolla. Cicla tra le 3 |
| Timeout: Nessuna/Kick/Ban | Azione quando il tempo **scade** senza videobolla valida |
| BL rifiuto ON/OFF | Se ON, il rifiuto aggiunge l'utente anche in **blacklist** |
| BL timeout ON/OFF | Come sopra ma per il timeout |
| Rientro → Ban / Kick | Cosa fare se un utente **in blacklist** rientra nel gruppo: ban permanente oppure solo espulsione |

Significato delle azioni:

| Azione | Effetto |
|--------|---------|
| **Nessuna** | L'utente resta nel gruppo ma mutato (può riprovare con `/start`) |
| **Kick** | Espulso; può rientrare con un nuovo link e riprovare |
| **Ban** | Bannato da Telegram **e** aggiunto in blacklist |

---

## 🔐 Sicurezza

Sezione riservata: **tutti possono vederla, solo il super-admin può modificarla**.

In cima al menu c’è **🛡 Anti-spam** (flood, forward, scam, soglie msg/finestra, scorciatoie a Link e Warn). Gli altri moduli restano nella griglia principale (captcha, attesa, probation, retention, VIP, report, riverifica…).

Ogni modulo è documentato in dettaglio in [`SICUREZZA.md`](SICUREZZA.md), incluso:

- cosa fa ogni toggle e i valori regolabili (attesa ±5s, probation ±15min, flood msg/finestra)
- la gestione VIP e scam domains
- la **riverifica massiva** (🔄 Riverifica tutti) con conferma e riepilogo
- l'audit log delle azioni

---

## Review videobolla (come decidere)

Quando arriva una verifica ricevi:

1. La **videobolla**
2. Un testo con nome, username, ID, durata, numero verifica
3. La **checklist qualità** (se "Note qualità" è ON):
   - troppo scuro / sfocato → rifiuta
   - volto non riconoscibile → rifiuta
   - nessuna presentazione / sospetto bot → rifiuta

Pulsanti principali:

| Pulsante | Funzione |
|----------|----------|
| ✅ Approva | Sblocca l'utente, manda il messaggio OK e il benvenuto |
| ❌ Rifiuta | Rifiuta con motivo generico |
| 🙋 Prendo io | Assegna la review a te: utile quando ci sono più admin |
| ✅ Con riserva | Approva ma applica una probation estesa: l'utente può scrivere testo ma non media/link |
| 🌑 Scuro | Rifiuto con motivo “video troppo scuro/controluce” |
| 🌫 Sfocato | Rifiuto con motivo “sfocato / volto non riconoscibile” |
| 👤 Volto | Rifiuto con motivo “volto non visibile” |
| 🔇 Voce | Rifiuto con motivo “presentazione vocale assente/non chiara” |
| 🚫 Fake | Rifiuto con motivo “video sospetto, riciclato o di terzi” |

Se esiste una videobolla precedente per lo stesso utente, il bot la invia agli admin prima della nuova, così puoi fare un **confronto**.

Effetto di Approva: unmute + DM di conferma + benvenuto nel gruppo (+ eventuale probation).
Effetto di Rifiuta: DM di rifiuto + azione configurata in 🛡 Ban / azioni.

---

## Funzioni utente extra

| Funzione | Comando | Dettaglio |
|----------|---------|-----------|
| Stato verifica | `/status` | L'utente vede lo stato corrente, verifica ID e tempo rimasto |
| Storico personale | `/history` | Mostra le ultime verifiche dell'utente |
| Privacy | `/privacy` | Spiega dati salvati, retention e `file_id` Telegram |
| Forget | `/forget` | Pulisce preferenze/captcha/probation e riferimenti video locali |
| Report privato | `/report ID motivo` in privato | Invia report agli admin senza scriverlo nel gruppo |
| Promemoria timeout | automatico | DM a metà timeout e prima della scadenza |
| Retry post-rifiuto | automatico | Se attivo, un utente rifiutato può reinviare entro la finestra configurata |

---

## Comandi admin avanzati

Puoi usarli in privato col bot oppure nel gruppo rispondendo a un messaggio.

| Comando | Dove | Funzione |
|---------|------|----------|
| `/dashboard` | privato | Statistiche avanzate: approvati/rifiutati oggi, coda, tempo medio review, top admin |
| `/whois ID` | privato/gruppo | Scheda utente: ultima verifica, VIP, blacklist, strike, report, note interne |
| `/note ID testo` | privato/gruppo | Aggiunge una nota interna visibile agli admin con `/whois` |
| `/warn ID motivo` | privato/gruppo | Registra uno strike/manual warning |
| `/mute ID minuti motivo` | privato/gruppo | Muta temporaneamente l'utente |
| `/ban ID motivo` | privato/gruppo | Banna e aggiunge in blacklist |
| `/unban ID` | privato/gruppo | Sblocca e rimuove da blacklist |
| `/export` | privato | Super-admin: invia CSV delle verifiche |
| `/backup` | privato | Super-admin: invia copia `bot.sqlite` |
| `/templates` | privato | Mostra i template rapidi dei comandi admin |

Nel gruppo puoi evitare l'ID usando una reply:

```text
(rispondi al messaggio)
/mute 60 spam
```

---

## Automazioni e integrazioni

| Funzione | Setting / Dove | Cosa fa |
|----------|----------------|---------|
| Promemoria verifica | `reminders_enabled` | Invia reminder agli utenti che non hanno ancora mandato la videobolla |
| Alert ingressi | `alerts_enabled`, `alert_join_threshold_hour` | Avvisa gli admin se ci sono troppi ingressi/verifiche in 1 ora |
| Orari verifica | `verification_hours_enabled`, `verification_hours_start`, `verification_hours_end` | Fuori orario il bot avvisa l'utente di riprovare più tardi |
| Auto VIP | `auto_vip_enabled`, `auto_vip_days` | Utenti approvati da molto tempo, senza strike/blacklist, diventano VIP |
| Webhook esterno | `webhook_notify_enabled`, `webhook_notify_url` | Invia eventi JSON verso Slack/Discord/email bridge o altro endpoint |
| Pannello web read-only | `admin_view.php?key=WEB_PANEL_KEY` | Dashboard browser con pending, report, event log. La chiave è `web_panel_key` nei settings |

### Pannello web read-only

Apri:

```text
https://TUO-DOMINIO/bot/admin_view.php?key=CHIAVE
```

La chiave viene generata automaticamente nel database (`web_panel_key`). Non condividerla pubblicamente. Il pannello è solo lettura: non approva, non banna, non modifica dati.

---

## Comandi admin

| Comando | Dove | Nota |
|---------|------|------|
| `/settings` | privato | pannello completo |
| `/setgroup` | gruppo | registra/aggiorna il gruppo (non sostituisce gli altri). Chi lo esegue ne diventa proprietario; può eseguirlo anche il creatore/amministratore Telegram del gruppo |
| `/unsetgroup` | gruppo | disattiva il gruppo (proprietario del gruppo o super-admin) |
| `/pending` | privato | verifiche in attesa |
| `/stats` | privato | contatori |
| `/dashboard` | privato | statistiche avanzate |
| `/whois ID` | privato/gruppo | scheda utente |
| `/note ID testo` | privato/gruppo | nota interna |
| `/warn ID motivo` | privato/gruppo | warning/strike |
| `/mute ID minuti motivo` | privato/gruppo | mute temporaneo |
| `/ban ID motivo` | privato/gruppo | ban + blacklist |
| `/unban ID` | privato/gruppo | sblocco + rimozione blacklist |
| `/export` | privato | CSV verifiche, super-admin |
| `/backup` | privato | backup SQLite, super-admin |
| `/templates` | privato | template comandi rapidi |
| `/annulla` | privato | esce da qualsiasi modalità di modifica (testo, foto, ID…) |
| `/unvip ID` | privato | rimuove un VIP (super-admin) |
| `/unscam ID` | privato | rimuove un dominio scam (super-admin) |
| `/guida` | privato | indice delle guide |

## Checklist go-live

- [ ] Token nuovo e non condiviso in chat pubbliche
- [ ] Super-admin ID corretti
- [ ] `/setgroup` fatto (e altri gruppi se serve)
- [ ] In `/settings` → 🏘 Gruppi il gruppo attivo è quello giusto
- [ ] Modalità approvazione scelta
- [ ] Messaggi + eventuali foto impostati
- [ ] (Opzionale) 🔁 Ripetuti: coda e intervallo
- [ ] (Opzionale, Pro) 📊 Sondaggi e 🚫 Parole vietate
- [ ] Ban/azioni e ⚠️ Warn configurati
- [ ] Sicurezza / 🛡 Anti-spam: solo i moduli che ti servono
- [ ] Test con account secondario
- [ ] In produzione: webhook HTTPS + `storage/` non scaricabile dal web

## File utili

- `docs/GUIDA_UTENTI.md` — da condividere coi membri
- `docs/SICUREZZA.md` — dettaglio moduli sicurezza
- `README.md` — overview tecnica
- `storage/bot.sqlite` — dati
- `storage/logs/bot.log` — log