# 📱 SISTEMA NOTIFICHE PUSH MULTI-AZIENDA
## Relazione Tecnica Completa - 29 Gennaio 2026

---

## 🎯 OBIETTIVO DEL PROGETTO

Creare un sistema centralizzato di notifiche push che permetta di gestire **fino a 100 attività commerciali diverse**, ognuna con:
- Sistema prenotazioni
- Agenda vocale clienti
- Notifiche push promozionali (max 15/giorno per attività)
- Messaggi 1-to-1 tra cliente e titolare attività

---

## 🏢 PRIMA ATTIVITÀ PILOTA: DOG STYLE

**Nome attività:** Dog Style (toelettatura cani)  
**Dominio:** consulenticaniegatti.com  
**Clienti stimati:** ~300 clienti  
**Tecnologie:** PHP + SQLite + Firebase Cloud Messaging  

---

## ❌ PROBLEMA ATTUALE

Sul **vecchio hosting Aruba condiviso**:
- ✅ PWA funziona e si installa correttamente
- ✅ Service Worker registrato
- ✅ VAPID keys configurate nell'app
- ✅ Notifiche promozionali funzionano (inviate dal server)
- ❌ Notifiche 1-to-1 **NON funzionano**
- Causa: Limitazioni hosting condiviso per librerie web-push-php

---

## ✅ SOLUZIONE ADOTTATA

**VPS Ubuntu 22.04** su Aruba Cloud
- IP: 185.58.193.190
- Accesso SSH: root con chiave privata
- Sistema: Ubuntu 22.04 LTS

---

## 🏗️ ARCHITETTURA DEL SISTEMA

### HOSTING ARUBA (Condiviso) - consulenticaniegatti.com
```
/
├── WordPress (pannello gestionale per titolari attività)
│   └── /wp-admin/ → Dashboard gestore
│       ├── Visualizza calendario prenotazioni
│       ├── Legge messaggi clienti
│       ├── Risponde ai clienti
│       └── Invia promozioni massive
│
└── /app/ristorantemimmo1/PRENOTAZIONI/
    │
    ├── /dogstyle/
    │   ├── database.db (300 clienti Dog Style)
    │   ├── register.php (registrazione clienti)
    │   ├── send_promo.php (invia promozioni)
    │   ├── send_1to1.php (messaggi cliente↔gestore)
    │   ├── prenota.php (prenotazioni da app)
    │   └── calendario.php (calendario aziendale)
    │
    ├── /ristorante1/
    │   ├── database.db (clienti Ristorante1)
    │   └── ... (stessa struttura)
    │
    └── ... (fino a 100 attività)
```

### VPS UBUNTU (185.58.193.190)
```
/var/www/push-api/
│
├── composer.json (dipendenze)
├── vendor/ (librerie installate)
│   └── minishlink/web-push (libreria Web Push)
│
├── push_endpoint.php (API per ricevere richieste push)
├── vapid_keys.php (VAPID public + private keys)
│
└── .htaccess (protezione API)
```

**Funzione VPS:**
- Riceve richieste POST dal hosting Aruba
- Usa VAPID keys per autenticare
- Invia notifiche push tramite Web Push API
- NON salva dati personali (solo inoltro)

---

## 📊 FLUSSO COMPLETO DEL SISTEMA

### 👤 CLIENTE (Ha l'APP mobile)
L'app del cliente contiene:
- **Agenda personale** (suoi appuntamenti)
- **Chat con l'attività** (messaggi 1-to-1)
- **Ricezione notifiche push** (promo + risposte)

### 🏢 GESTORE ATTIVITÀ (Titolare Dog Style, Ristorante, ecc.)
Gestisce tutto da:
- **WordPress** (consulenticaniegatti.com/wp-admin/)
- Vede calendario prenotazioni
- Legge messaggi clienti
- Risponde ai clienti
- Invia promozioni

---

## 📱 FLUSSI OPERATIVI

### 1️⃣ CLIENTE PRENOTA APPUNTAMENTO
```
[📱 PWA Cliente] 
Seleziona data/ora → Popup conferma
        ↓
HTTP POST → [Hosting Aruba] prenota.php
        ↓
Salva in database.db (agenda cliente + calendario attività)
        ↓
HTTP POST → [VPS] push_endpoint.php
        ↓
Web Push (VAPID) → Notifica push al gestore
        ↓
[🏢 WordPress Gestore] Vede nuova prenotazione
```

### 2️⃣ CLIENTE INVIA MESSAGGIO AL GESTORE
```
[📱 PWA Cliente]
Scrive messaggio → Popup invio
        ↓
HTTP POST → [Hosting Aruba] send_1to1.php
        ↓
Salva messaggio in database.db
        ↓
HTTP POST → [VPS] push_endpoint.php
        ↓
Web Push (VAPID) → Notifica push al gestore
        ↓
[🏢 WordPress Gestore] Vede messaggio e risponde
```

### 3️⃣ GESTORE RISPONDE AL CLIENTE
```
[🏢 WordPress Gestore]
Scrive risposta → Click "Invia"
        ↓
[Hosting Aruba] send_1to1.php
        ↓
Salva risposta in database.db
        ↓
HTTP POST → [VPS] push_endpoint.php
        ↓
Web Push (VAPID) → Notifica push al cliente
        ↓
[📱 PWA Cliente] Riceve risposta (popup notifica)
```

### 4️⃣ GESTORE INVIA PROMOZIONE
```
[🏢 WordPress Gestore]
Scrive promozione → Seleziona destinatari → Click "Invia a tutti"
        ↓
[Hosting Aruba] send_promo.php
        ↓
Loop su tutti i token clienti nel database.db
        ↓
HTTP POST → [VPS] push_endpoint.php (per ogni cliente)
        ↓
Web Push (VAPID) → Notifiche push massive
        ↓
[📱 PWA Clienti] Ricevono promozione (popup notifica)
```

### 5️⃣ CLIENTE RICEVE PROMOZIONE
```
[📱 PWA Cliente]
Popup notifica: "Offerta speciale bagno cane -20%!"
        ↓
Cliente clicca notifica
        ↓
PWA si apre sulla sezione promo
        ↓
(Opzionale) Cliente prenota usando l'offerta
```

---

## 🔐 GESTIONE PRIVACY

### Database Separati
- ✅ Ogni azienda ha il **proprio database SQLite**
- ✅ Dog Style NON può vedere dati di Ristorante1
- ✅ Isolamento totale tra attività

### VPS: Solo Inoltro Push
- ✅ VPS **NON salva** dati personali
- ✅ VPS **NON salva** messaggi
- ✅ VPS riceve solo: token + messaggio → invia → dimentica

### Token Firebase
- Salvati nei database delle singole attività
- Passati al VPS solo al momento dell'invio
- Mai condivisi tra attività diverse

---

## 👥 CHI USA COSA

### 📱 CLIENTI (300 per attività)
**Hanno:** PWA (Progressive Web App) installata dal browser

**Come funziona:**
- App si apre da link: consulenticaniegatti.com/app/ristorantemimmo1/PRENOTAZIONI/agenda-cliente-toilet-001.html
- Si installa come app nativa (icona su home screen)
- Service Worker riceve notifiche push in background
- Usa VAPID keys per autenticazione push

**Possono:**
- ✅ Vedere la loro agenda personale
- ✅ Prenotare appuntamenti (popup conferma)
- ✅ Inviare messaggi al gestore (popup invio)
- ✅ Ricevere risposte dal gestore (notifica push VAPID)
- ✅ Ricevere promozioni (notifica push VAPID, max 15/giorno)

**NON hanno:** Accesso a WordPress
**NON vedono:** Dati di altri clienti

---

### 🏢 GESTORE ATTIVITÀ (1 per attività)
**Hanno:** Accesso WordPress su consulenticaniegatti.com/wp-admin/

**Possono:**
- ✅ Vedere calendario con tutte le prenotazioni
- ✅ Leggere tutti i messaggi dei clienti
- ✅ Rispondere ai clienti (invio notifica push)
- ✅ Inviare promozioni massive (max 15/giorno)
- ✅ Gestire anagrafica clienti

**NON hanno:** App mobile (gestiscono tutto da browser)
**NON vedono:** Dati di altre attività

---

## 🔐 COME FUNZIONANO LE NOTIFICHE VAPID

### Cos'è VAPID?
**VAPID** (Voluntary Application Server Identification) è uno standard per autenticare le notifiche push web.

### Componenti Necessari:

**1. VAPID Keys (coppia chiavi pubblic/private)**
- **Public Key:** Condivisa con i browser (nell'app PWA)
- **Private Key:** Segreta, solo sul server VPS

**2. Service Worker (già nell'app PWA)**
- File JavaScript che gira in background
- Riceve e mostra le notifiche
- Registrato quando l'utente apre la PWA

**3. Subscription (per ogni cliente)**
```json
{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "chiave_crittografia_cliente",
    "auth": "token_autenticazione"
  }
}
```
Questo oggetto viene generato dal browser quando il cliente accetta le notifiche.

### Flusso Completo:

**REGISTRAZIONE CLIENTE:**
```
1. Cliente apre PWA
2. Service Worker si registra
3. Cliente clicca "Accetta notifiche"
4. Browser genera subscription (con endpoint + keys)
5. PWA invia subscription → Hosting Aruba → Salva in database.db
```

**INVIO NOTIFICA:**
```
1. Gestore scrive messaggio in WordPress
2. WordPress → send_1to1.php recupera subscription dal DB
3. send_1to1.php → POST al VPS con:
   - subscription (endpoint + keys cliente)
   - messaggio da inviare
   - VAPID private key per firmare
4. VPS → Usa web-push-php → Invia al browser push service
5. Browser push service → Consegna al Service Worker del cliente
6. Service Worker → Mostra notifica popup
```

---

## 📋 PIANO DI IMPLEMENTAZIONE

### ✅ FASE 1: SETUP VPS (IN CORSO)
- [x] VPS acquistato e attivato
- [x] Chiavi SSH configurate
- [x] Apache installato e attivo
- [ ] PHP 8.1 + estensioni installate
- [ ] Composer installato
- [ ] Firebase Admin SDK installato

### ⏳ FASE 2: API WEB PUSH
- [ ] Creare `/var/www/push-api/`
- [ ] Installare web-push-php via Composer
- [ ] Creare `push_endpoint.php` (API endpoint)
- [ ] Configurare VAPID keys (public + private)
- [ ] Testare invio push con cURL

### ⏳ FASE 3: INTEGRAZIONE DOG STYLE
- [ ] Modificare `send_1to1.php` per chiamare VPS
- [ ] Modificare `send_promo.php` per chiamare VPS (opzionale)
- [ ] Testare messaggi 1-to-1
- [ ] Verificare ricezione notifiche su app

### ⏳ FASE 4: SCALABILITÀ
- [ ] Documentare procedura
- [ ] Creare template per nuove attività
- [ ] Sistema per aggiungere aziende facilmente
- [ ] Monitoraggio e log

---

## 🛠️ TECNOLOGIE UTILIZZATE

### Backend
- **PHP 8.1** (linguaggio principale)
- **SQLite** (database leggero, 1 per azienda)
- **Apache 2.4** (web server VPS)
- **Composer** (gestione dipendenze PHP)

### Push Notifications
- **VAPID (Voluntary Application Server Identification)**
- **Web Push API** (standard W3C)
- **web-push-php** (libreria server-side)
- **Service Worker** (client-side, già nell'app PWA)

### Infrastruttura
- **Hosting Aruba Condiviso** (applicazioni + database)
- **VPS Aruba Ubuntu 22.04** (API Firebase)
- **SSH con chiavi** (accesso sicuro VPS)

---

## 📈 SCALABILITÀ

### Capacità Sistema
- **100 attività** gestibili
- **30.000 clienti totali** (300 per attività)
- **1.500 notifiche/giorno** (15 promo × 100 attività)
- **Messaggi 1-to-1 illimitati**

### Costi Stimati
- VPS Aruba: ~10-20€/mese
- Web Push: Gratuito (protocollo open standard)
- Hosting Aruba: Già attivo

---

## 🔄 VANTAGGI ARCHITETTURA

### ✅ Separazione Responsabilità
- Hosting Aruba → Logica business + database
- VPS → Solo invio notifiche

### ✅ Privacy e Sicurezza
- Database isolati per azienda
- Nessun dato personale sul VPS
- Comunicazione HTTPS tra hosting e VPS

### ✅ Manutenibilità
- Aggiornare Firebase = solo VPS
- Aggiungere azienda = duplicare cartella + nuovo DB
- Un problema Firebase non blocca tutto

### ✅ Performance
- VPS dedicato per push (nessun limite)
- Database SQLite veloci e leggeri
- Web Push nativo nei browser moderni

---

## 📞 CONFIGURAZIONE ATTUALE

### VPS
- **IP:** 185.58.193.190
- **OS:** Ubuntu 22.04 LTS
- **User:** root
- **SSH:** Chiave privata in `C:\Users\Admin\.ssh\id_rsa`
- **Apache:** ✅ Attivo (versione 2.4.52)
- **PHP:** ⏳ Da installare
- **Composer:** ⏳ Da installare

### Hosting Aruba
- **Dominio:** consulenticaniegatti.com
- **Path:** /www.consulenticaniegatti.com/app/ristorantemimmo1/PRENOTAZIONI/
- **Accesso:** File manager Aruba

---

## 🎯 PROSSIMO STEP IMMEDIATO

**Installare Composer globalmente e creare struttura API**

Comandi:
```bash
# Rendi Composer globale
mv composer.phar /usr/local/bin/composer

# Verifica installazione
composer --version

# Crea directory API
mkdir -p /var/www/push-api
cd /var/www/push-api

# Installa web-push-php
composer require minishlink/web-push
```

---

## 📝 NOTE FINALI

- Sistema progettato per crescere gradualmente
- Dog Style come test pilota
- Replicabile facilmente per altre attività
- Manutenzione centralizzata su VPS
- Privacy garantita con database separati

---

**Documento compilato il:** 29 Gennaio 2026  
**Stato progetto:** FASE 1 - PHP + Composer installati ✅  
**Prossima milestone:** Installare web-push-php e configurare API