SALONUP - CORE + SETUP WIZARD + SUPER ADMIN + PLUGIN (Clienti, Servizi)
=========================================================================

NOVITA' IN QUESTA VERSIONE
----------------------------
1. Setup wizard automatico: se il sistema non e' ancora configurato
   (manca un account Super Admin), qualsiasi pagina ti reindirizza da sola
   a /setup/ invece di darti un errore.
2. Pannello Super Admin (/admin/): dashboard con statistiche piattaforma
   ed elenco/creazione negozi, separato dal gestionale dei negozi.
3. Login intelligente: se sei Super Admin vai in /admin/, se sei owner
   di un negozio vai nel gestionale come prima.
4. Prefisso tabelle configurabile (stile WordPress): nel Passo 1 del setup
   puoi scegliere un prefisso (es. salonup_) per condividere il database
   con altre applicazioni senza collisioni di nomi tabella. Se lo lasci
   vuoto, le tabelle restano senza prefisso.
5. Plugin collegati tra Super Admin e pannello negozio: un plugin puo'
   avere una pagina di impostazioni globali (admin_settings) gestita SOLO
   dal Super Admin, che cambia davvero cosa vede l'owner del negozio.
   Esempio incluso: da /admin/plugins.php -> Clienti -> Impostazioni,
   attivi/disattivi il campo "Data di nascita" nella scheda cliente.
   E' lo stesso meccanismo che useremo per Servizi, Operatori e Agenda.

SE PARTI DA ZERO
-----------------
1. Estrai "salonup" dentro C:\xampp\htdocs\
2. Crea il database salonup_dev su phpMyAdmin (vuoto, non serve importare nulla a mano)
3. Avvia Apache e MySQL da XAMPP
4. Apri http://localhost/salonup/public/
5. Il sistema ti portera' automaticamente al setup:
   - Passo 1: conferma i dati del database (default gia' pronti per XAMPP)
   - Passo 2: crea il tuo account Super Admin (nome, email, password)
6. Fatto: vai al login, entra con le credenziali Super Admin -> ti porta in /admin/
7. Da /admin/businesses.php crea i negozi veri
8. Chi si registra da /register.php sceglie il negozio e diventa Owner di quel negozio

SE HAI GIA' UN'INSTALLAZIONE PRECEDENTE (Clienti/Servizi gia' funzionanti)
-----------------------------------------------------------------------------
Non serve toccare il database: le tabelle esistenti restano SENZA prefisso,
e il sistema continua a funzionare esattamente come prima anche se il file
config/database.php che hai gia' non contiene il campo 'prefix' (il prefisso
e' opzionale e retrocompatibile: se manca, viene trattato come vuoto).
Basta sovrascrivere i file con extract.php o manualmente.
La prima volta che apri il sito ti portera' al setup per creare il tuo
account Super Admin (perche' finora non ne esisteva uno) - e' un passaggio
UNICO, i tuoi clienti/servizi/utenti gia' creati restano intatti.
NON serve rifare il Passo 1 del setup (database) in questo caso: se il
sistema rileva che il config esiste gia' e si connette, salta direttamente
al Passo 2 (crea Super Admin).

IMPORTANTE - se il tuo database esisteva GIA' prima di questa versione:
importa anche database/004_admin_settings.sql (leggi le istruzioni dentro
il file su come gestire il prefisso), altrimenti il campo Data di nascita
e le impostazioni Super Admin dei plugin non funzionano.

STRUTTURA
---------
core/            -> PluginManager, layout gestionale, layout admin
includes/        -> database, autenticazione, controllo installazione
plugins/clienti/ -> anagrafica clienti
plugins/servizi/ -> catalogo servizi
public/setup/    -> installer automatico
public/admin/    -> pannello Super Admin
public/          -> login, registrazione, dashboard negozio, logout

PROSSIMO PASSO
---------------
Plugin Operatori/Dipendenti, poi Agenda.

=========================================================================
VERSIONE CON DESIGN SYSTEM + UPLOAD PLUGIN + STAFF ADMIN
=========================================================================

NOVITA':
1. Tema chiaro (bianco/blu) e scuro (nero/grigio) - interruttore in alto
   a destra (icona sole/luna), salvato in un cookie, valido per 1 anno.
2. Layout responsive: su schermi piccoli il menu laterale diventa un
   menu a scomparsa (icona hamburger in alto).
3. CSS unico globale (assets/style.css) + possibilita' per ogni plugin
   di avere un proprio assets/style.css che si aggiunge (non sostituisce)
   quello del Core. Va servito tramite public/plugin-asset.php perche'
   la cartella plugins/ sta fuori dalla webroot per sicurezza.
4. Super Admin -> Plugin: ora puoi CARICARE/AGGIORNARE plugin da file ZIP
   direttamente dal browser, stile WordPress. Basta che lo ZIP contenga
   plugin.json, routes.php, views/. Se lo slug esiste gia', sovrascrive.
   NOTA ONESTA: questa v1 non fa backup automatico prima di sovrascrivere
   e non controlla firme/hash di sicurezza - va bene per uso tuo/pilot,
   andra' irrobustito prima di aprire l'installazione a terzi.
5. Super Admin -> Staff Admin: puoi creare altri account Super Admin.
   Il campo "Ruolo" e' per ora solo etichetta (base per permessi
   differenziati futuri, non ancora applicati/limitati davvero).

SE IL TUO DATABASE ESISTEVA GIA':
- Importa database/005_staff_role.sql (aggiunge il campo ruolo)
- Gli altri file (001-004) valgono come prima, importali solo se non
  li avevi gia' importati in precedenza

=========================================================================
VERSIONE CON AVATAR, ICONE OVUNQUE, LINK RAPIDI SUPER ADMIN
=========================================================================

NOVITA':
1. Avatar utente stile Google: cerchio colorato con iniziali (colore
   coerente per nome, calcolato automaticamente). Ogni utente puo'
   cambiarlo dalla pagina "Il mio profilo" (clic su avatar/nome nella
   sidebar): caricare una foto propria (JPG/PNG/WEBP, max 2MB) o
   scegliere tra 6 avatar preimpostati colorati.
2. Icone SVG ovunque: sidebar (icona + nome voce), pulsanti principali
   (Nuovo/Salva/Annulla/Modifica/Elimina/Archivia), form. Le icone sono
   incluse nel codice stesso (core/icons.php), nessuna libreria esterna,
   e seguono automaticamente il colore del tema chiaro/scuro.
3. Super Admin -> 3 pulsanti rapidi in alto nella sidebar (Sito web,
   Sito clienti, Gestionale), configurabili da Impostazioni. Si aprono
   in una nuova scheda. Finche' non configuri Sito web/Sito clienti
   (non ancora costruiti) restano visibili ma disattivati; il pulsante
   Gestionale punta gia' di default al login del gestionale negozi.
4. Nuova pagina Super Admin "Impostazioni" per configurare quei 3 link.
5. Footer sidebar rifatto: avatar + nome + icona logout separata.
   Cliccando su avatar o nome si va al profilo personale.

SE IL TUO DATABASE ESISTEVA GIA':
- Importa database/006_avatar.sql (aggiunge i campi avatar_type/avatar_value)
- Assicurati che la cartella public/uploads/avatars/ sia scrivibile
  (permessi 755 o 775) se vuoi permettere il caricamento foto profilo

=========================================================================
VERSIONE CON MODELLO DATI A 3 LIVELLI (identita' globale delle persone)
=========================================================================

CAMBIO ARCHITETTURALE IMPORTANTE:
Non esiste piu' una tabella "clients" separata. Ogni persona (titolare,
staff, cliente) e' una riga nella tabella globale "users". Il ruolo che
ha in un negozio specifico (owner/manager/staff/client) e' nella tabella
"business_user" - una persona puo' avere piu' righe li' (es. cliente in
un negozio E dipendente in un altro, o entrambi i ruoli nello stesso
negozio).

I 4 livelli:
1. users            -> identita' globale: nome, email, telefono, password
                       (nulla se la persona non ha accesso al pannello)
2. user_meta        -> dati opzionali globali (es. data di nascita)
3. business_user    -> la relazione: quale ruolo ha in QUEL negozio
4. business_user_meta -> dati privati di QUELLA relazione (es. le note
                       che un negozio scrive su un cliente) - MAI visibili
                       da un altro negozio, anche se e' la stessa persona

NOVITA' VISIBILI:
1. Plugin Clienti riscritto su questo modello. Se durante la creazione
   inserisci un'email gia' presente in piattaforma (es. quella persona
   e' gia' cliente altrove), il sistema collega automaticamente la stessa
   identita' invece di duplicarla.
2. Super Admin -> nuova sezione "Utenti": vede TUTTE le persone della
   piattaforma, puo' modificarle o eliminarle. NON vede le note private
   che i singoli negozi scrivono sui clienti.

SE IL TUO DATABASE ESISTEVA GIA':
IMPORTANTE - leggi bene prima di procedere:
- Importa database/007_people_model.sql
- Questo script NON migra automaticamente i dati della vecchia tabella
  "clients" (se ne avevi una) - resta li' intatta come backup, ma il
  plugin Clienti non la usa piu'. Se avevi clienti veri da conservare,
  serve una migrazione dati dedicata (richiedila prima di procedere se
  e' il tuo caso). Se stavi ancora testando senza dati da conservare,
  procedi pure e riparti con clienti puliti.

=========================================================================
VERSIONE CON CAMPI PERSONALIZZATI, IMPOSTAZIONI A SCHEDE, SETUP MIGLIORATO
=========================================================================

1. SETUP PIU' ROBUSTO
----------------------
- Il file config/database.php NON viene piu' distribuito precompilato
  (evita tentativi di connessione lenti a indirizzi finti). Se manca,
  il sistema va dritto al setup, istantaneamente.
- Nuovo pulsante "Verifica e continua" nel Passo 1: si connette e
  controlla se esistono gia' tabelle con il prefisso scelto.
- Se le tabelle esistono gia': compare un pulsante "Esporta database"
  (scarica un .sql di backup) e due opzioni:
    - "Elimina le tabelle... e reinstalla pulito" (richiede conferma)
    - "Ignora le tabelle esistenti" (non le tocca, usa quelle gia' li')

2. CAMPI PERSONALIZZATI (Super Admin -> Plugin -> Campi personalizzati)
-------------------------------------------------------------------------
Per ogni plugin (per ora implementato su Clienti) il Super Admin puo'
aggiungere/rimuovere/riordinare campi extra nel form SENZA toccare il
codice e SENZA che i campi di default vengano mai intaccati.
Ogni campo ha un "ambito": Globale (vero ovunque per la persona, es.
allergie) o Di questo negozio (privato, es. "come ci ha conosciuto").
I dati vanno automaticamente in user_meta o business_user_meta a
seconda dell'ambito scelto - stesso meccanismo gia' usato per
Data di nascita e Note.

3. IMPOSTAZIONI A SCHEDE (Super Admin -> Impostazioni)
---------------------------------------------------------
- Generale: nome della piattaforma (mostrato ovunque al posto di
  "SalonUp") e logo (mostrato in sidebar Super Admin e Gestionale)
- Link rapidi: gli stessi di prima (Sito web, Sito clienti, Gestionale)
- Backup e Ripristino: esporta un .sql completo delle tabelle SalonUp,
  o ripristina da un .sql caricato (con conferma obbligatoria, e'
  un'operazione che sovrascrive dati)

SE IL TUO DATABASE ESISTEVA GIA':
- Importa database/008_custom_fields.sql
- Il tuo config/database.php ESISTENTE non viene toccato da questo zip
  (non lo sovrascrive piu' con valori finti) - continua a funzionare
  con i tuoi dati reali gia' inseriti

=========================================================================
VERSIONE CON BACKLOG, NEGOZI ESTESI, PAGINAZIONE/GRIGLIA
=========================================================================

1. PAGINA BACKLOG (Super Admin -> Backlog)
--------------------------------------------
Pagina temporanea che elenca tutto quello che abbiamo individuato come
utile/mancante (sicurezza, GDPR, permessi, ecc.), organizzato per area
con stato (da fare/in corso/fatto). Da eliminare quando il grosso sara'
completato - serve solo a non perdere traccia delle idee.

2. NEGOZI: DATI COMPLETI + MODIFICA + ATTIVA/DISATTIVA
----------------------------------------------------------
Il form di creazione/modifica negozio ora include: referente (nome+email,
obbligatori), ragione sociale, P.IVA/CF, indirizzo completo (via, CAP,
citta', provincia, nazione), note private del Super Admin, e operatore
SalonUp assegnato (scelto tra lo Staff Admin).
E' stata aggiunta la vista/modifica di un negozio esistente (prima
mancava del tutto) e il pulsante Attiva/Disattiva.
NOTA: l'autocompletamento citta' da CAP non e' incluso (richiederebbe
un servizio esterno con elenco CAP italiani) - i campi indirizzo si
inseriscono a mano.

3. PAGINAZIONE + VISTA LISTA/GRIGLIA (componente riusabile)
---------------------------------------------------------------
Nuovo componente core/ListView.php usato da Negozi, Utenti e Clienti:
un pulsante in alto a destra passa da vista tabella a vista a card,
e sotto la lista compare "Pagina X di Y" con Precedente/Successiva.
Lo stesso componente puo' essere riusato da qualsiasi plugin futuro
(Operatori, Servizi, ecc.) semplicemente chiamando paginate_query(),
render_pagination_links() e render_view_toggle().

CORREZIONI DI BUG TROVATI TESTANDO DAVVERO IL CODICE (non solo lettura):
----------------------------------------------------------------------------
Questa volta ogni funzionalita' e' stata provata su un ambiente PHP+MySQL
vero (non solo controllata leggendo il codice), ed emersi/corretti:
- mysqli lanciava eccezioni non gestite su errori di connessione/query
  (comportamento di default da PHP 8.1), causando pagine bianche nel
  setup. Corretto con mysqli_report(MYSQLI_REPORT_OFF).
- L'avatar usava mb_substr(), che richiede l'estensione mbstring non
  garantita su tutti gli hosting - mandava in crash OGNI pagina con un
  avatar (quindi quasi tutto il pannello dopo il login). Aggiunto un
  fallback automatico a substr() se mbstring non e' disponibile.
- Creare un negozio con un nome che genera uno slug gia' esistente
  causava un errore 500 invece di gestirlo - ora aggiunge un suffisso
  automatico e non perde mai i dati che avevi inserito nel form.
- La modifica cliente cercava una colonna "user_id" che la query non
  restituiva (bug di battitura nella query SQL) - sistemato.

=========================================================================
VERSIONE CON RAGIONE SOCIALE, CAMPI FISSI, ANTI-DUPLICATI
=========================================================================

1. Rimosso il campo separato "Nome negozio": ora l'identita' del negozio
   e' la Ragione Sociale (internamente il campo "name" esiste ancora per
   compatibilita' con slug/visualizzazioni, ma coincide sempre con la
   ragione sociale - non serve piu' compilarlo a parte).

2. Campi fissi obbligatori per ogni negozio: Ragione Sociale, Email,
   Partita IVA / Codice Fiscale. Nome referente resta ma non e' piu'
   obbligatorio.

3. Blocco duplicati: non si puo' creare (ne' modificare) un negozio con
   una email o una Partita IVA gia' usate da un ALTRO negozio - anche se
   solo uno dei due coincide. Doppio livello di protezione: controllo
   applicativo (messaggio chiaro) + vincolo UNIQUE nel database (rete di
   sicurezza in caso di richieste simultanee).

4. Aggiunta voce in Backlog: "Onboarding negozio al primo accesso"
   (setup guidato per indirizzo, orari, eventuali dipendenti) - annotato
   ma NON ancora costruito, come richiesto, per farlo dopo aver
   completato i plugin principali (Operatori, Agenda).

SE IL TUO DATABASE ESISTEVA GIA':
- IMPORTANTE: prima di importare database/010_business_unique.sql,
  controlla di non avere gia' email o P.IVA duplicate tra i negozi
  esistenti (le query di controllo sono scritte come commento dentro
  il file stesso) - altrimenti la creazione del vincolo UNIQUE fallisce.

=========================================================================
VERSIONE CON INVITO ATTIVAZIONE, RESET PASSWORD, TEMPLATE EMAIL
=========================================================================

1. NESSUN DATO DEMO: il setup ora crea un database completamente vuoto
   (a parte i template email di default, necessari per far funzionare
   le email). Nessun salone/cliente finto pre-caricato.

2. INVITO ATTIVAZIONE ACCOUNT NEGOZIO
   Quando il Super Admin crea un negozio, il referente (email inserita)
   riceve un'email con un link per attivare l'account: cliccandolo,
   imposta la propria password e viene loggato automaticamente nel
   gestionale del suo negozio. Il link scade dopo 7 giorni.
   Se l'email corrisponde a una persona gia' esistente sulla piattaforma
   CON password gia' impostata, non viene inviato un nuovo invito (viene
   solo collegata come owner del nuovo negozio).

3. PASSWORD DIMENTICATA (chiude anche la voce gia' in Backlog)
   Nuovo link "Password dimenticata?" nel login. Il flusso invia
   un'email con link di reset (valido 2 ore) e non rivela se un indirizzo
   email esiste o meno sulla piattaforma (sicurezza).

4. SEZIONE "ASPETTO" NEL SUPER ADMIN
   Template email modificabili: Benvenuto negozio, Registrazione cliente
   (predisposto per il futuro sito prenotazioni), Reset password,
   Newsletter (solo il template, nessun sistema di invio massivo ancora).
   Ogni template mostra i segnaposto disponibili (es. {{saas_name}},
   {{activation_link}}).

NOTA IMPORTANTE SULL'INVIO EMAIL:
Il sistema usa la funzione mail() nativa di PHP. Su molti hosting
condivisi funziona, ma la consegna (specialmente finire nello spam)
non e' sempre affidabile senza una configurazione SMTP dedicata.
Se in pratica le email non arrivano, e' il primo posto da controllare -
segnato in Backlog come miglioramento da valutare quando si passa a
traffico reale.

SE IL TUO DATABASE ESISTEVA GIA':
Importa database/011_email_activation.sql (crea le tabelle account_tokens
ed email_templates, con i 4 template di default gia' pronti).

=========================================================================
VERSIONE CON SMTP AFFIDABILE + LOG EMAIL + REINVIA INVITO
=========================================================================

PROBLEMA RISOLTO: le email non arrivavano perche' mail() nativa di PHP
manda a nome di un dominio non autorizzato a inviare (niente SPF/DKIM),
quindi Gmail/Outlook le buttano nello spam o le rifiutano silenziosamente.

SOLUZIONE: client SMTP scritto in PHP puro (nessuna libreria esterna),
in Impostazioni -> Email (SMTP). Usa una casella email VERA che hai gia'
(es. creata dal pannello OVH sul tuo dominio) con autenticazione, esattamente
come fa Outlook quando invii tu stesso una mail - questo risolve il problema
alla radice perche' il messaggio parte davvero autorizzato da quel dominio.

COME CONFIGURARLA:
1. Vai su Impostazioni -> Email (SMTP)
2. Inserisci host, porta, crittografia, username e password della tua
   casella email (su OVH li trovi nel pannello di gestione email del
   dominio - di solito host tipo ssl0.ovh.net, porta 587 TLS)
3. Salva, poi usa subito "Invia email di prova" per verificare che
   funzioni DAVVERO prima di creare negozi veri
4. Sotto trovi il log degli ultimi invii, con l'errore esatto se qualcosa
   fallisce (niente piu' "forse e' partita, forse no")

NOVITA' AGGIUNTIVE:
- Se l'invio fallisce quando crei un negozio, ora te lo dice chiaramente
  a schermo (non finge piu' che sia andato tutto bene)
- Nuovo pulsante "Reinvia invito" su ogni negozio, per rimandare l'email
  di attivazione senza dover ricreare il negozio (utile se hai configurato
  SMTP DOPO aver gia' creato negozi con mail() nativa fallita)
- Se non configuri SMTP, il sistema ripiega comunque su mail() nativa
  (meglio di niente, ma il log ti mostrera' chiaramente se fallisce)

TESTATO IN QUESTA VERSIONE:
Ho scritto un piccolo server SMTP finto per verificare che il client SMTP
parli davvero il protocollo corretto (connessione, autenticazione, invio,
formato email) - non solo letto il codice, provato per davvero fino alla
ricezione del messaggio.

SE IL TUO DATABASE ESISTEVA GIA':
Importa database/012_email_log.sql (aggiunge la tabella per il log invii).

=========================================================================
VERSIONE CON FIX MENU MOBILE, HEADER FISSO, FOOTER
=========================================================================

1. RISOLTO: il menu mobile non si chiudeva. Causa reale: quando si apriva,
   copriva anche il pulsante hamburger (nessun modo di richiuderlo).
   Ora: l'header resta sempre sopra il menu (si vede e si puo' ricliccare
   per chiudere), e in piu' toccando fuori dal menu (l'area scura) si
   chiude da solo.
2. Tolto il pulsante chiaro/scuro dall'header mobile (resta nella sidebar).
3. Header fisso in alto su mobile (non scorre piu' via con la pagina).
4. Aggiunto un footer con copyright, presente sia nel gestionale negozio
   che nel Super Admin.

Nessuna modifica al database, solo file di interfaccia (CSS + i due layout).
