## Capitolo 1: Introduzione e Panoramica

ChiFaCosa è una piattaforma multi-utente che permette a chiunque di creare la propria pagina pubblica ("Link in Bio") per centralizzare la propria presenza online. **La piattaforma è pensata per essere generica e utilizzabile da tutti**, non solo da musicisti, come dimostra la roadmap che prevede un wizard di installazione stile WordPress per renderla un prodotto clonabile e indipendente.

### Concetti Chiave
- **Utente**: Chiunque si registri alla piattaforma.
- **Pagina Pubblica**: Ogni utente ha un proprio spazio all'indirizzo `tuodominio.it/nomepagina` dove può pubblicare contenuti.
- **Contenuti**: Link, brani audio, eventi, post del blog, e un modulo di contatto.
- **Amministratore**: Utente con privilegi speciali per gestire la piattaforma.

---

## Capitolo 2: Installazione e Configurazione Iniziale

Questa sezione descrive come installare ChiFaCosa su un server.

### 2.1 Prerequisiti
Prima di iniziare, assicurati che il tuo server Linux soddisfi i seguenti requisiti:
- **Docker Engine** e **Docker Compose** installati e funzionanti (`docker compose version` deve funzionare).
- Un **dominio** (es. `tuodominio.it`) con i record DNS A/AAAA che puntano all'IP del server.
- Porte **80** e **443** libere (o un reverse proxy configurato per gestirle).

### 2.2 Passi per l'Installazione
Segui questi passaggi per avviare la piattaforma:

1. **Copia il progetto sul server**:
```bash
cd /opt/chifacosa
```

2. **Crea il file di configurazione `.env`**:
```bash
cp .env.example .env
nano .env
```
All'interno del file, imposta `DB_PASSWORD` e `DB_ROOT_PASSWORD` con password forti e sicure.

3. **Build e avvio dei container**:
```bash
docker compose up -d --build
```

4. **Verifica che i container siano attivi**:
```bash
docker compose ps
docker compose logs -f app
```
Al primo avvio, MySQL importa automaticamente lo schema del database (`database/schema.sql`) e crea tutte le tabelle necessarie.

5. **Accesso iniziale**:
Una volta avviata, l'app sarà raggiungibile all'indirizzo `http://IP-DEL-SERVER:8080` (porta interna mappata nel `docker-compose.yml`).

### 2.3 Collegare il Dominio
Per servire il sito sul tuo dominio, hai due opzioni.

**Opzione A: Reverse Proxy con Nginx/Apache** (consigliata se il server ospita altri siti)
Crea un file di configurazione per il reverse proxy. Ecco un esempio per Nginx:
```nginx
server {
listen 80;
server_name tuodominio.it www.tuodominio.it;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
Dopo aver configurato il proxy, attiva il certificato SSL con Certbot:
```bash
sudo certbot --nginx -d tuodominio.it -d www.tuodominio.it
```

**Opzione B: Traefik come Reverse Proxy Docker**
Se preferisci gestire tutto via container, è possibile configurare Traefik con Let's Encrypt automatico.

### 2.4 Comandi Utili per la Gestione
- **Visualizzare i log**:
- `docker compose logs -f app` (log dell'applicazione)
- `docker compose logs -f db` (log del database)
- **Accesso diretto al database**:
```bash
docker compose exec db mysql -u chifacosa_user -p chifacosa
```
- **Fermare i container** (i dati rimangono nel volume `db_data`):
```bash
docker compose down
```
- **Ricostruire dopo modifiche al codice**:
```bash
docker compose up -d --build
```

### 2.5 Backup del Database
Per eseguire un backup del database, usa il seguente comando:
```bash
docker compose exec db mysqldump -u root -p chifacosa > backup_$(date +%F).sql
```

---

## Capitolo 3: Configurazione Avanzata

### 3.1 Gestione degli Amministratori
La piattaforma permette di elevare un utente normale al ruolo di amministratore. La procedura dettagliata è descritta nel file `ADMIN_SETUP.md`.
- **Diventare admin**: La procedura prevede l'accesso al database per modificare il ruolo dell'utente.
- **Recuperare password DB**: Le istruzioni per il reset delle password sono disponibili nello stesso documento.
- **Verificare account**: È possibile verificare manualmente un account tramite database.

### 3.2 Configurazione delle Notifiche Email (SMTP)
Le email (verifica registrazione, notifiche contatto, reset password, ecc.) possono essere configurate tramite SMTP. Per farlo:
1. Consulta il file `SMTP.md` per i dettagli.
2. Interpreta gli errori più comuni seguendo le indicazioni fornite.

---

## Capitolo 4: Gestione degli Utenti e dei Contenuti

Questa sezione è dedicata alle operazioni che un utente (non amministratore) può svolgere.

### 4.1 Registrazione e Profilo
1. **Registrazione**: Un nuovo utente si registra alla piattaforma.
2. **Creazione della pagina**: Dopo la registrazione, l'utente può creare la propria pagina pubblica all'indirizzo `tuodominio.it/nomepagina`.
3. **Gestione profilo**: L'utente può modificare le informazioni del proprio profilo.

### 4.2 Pubblicazione di Contenuti
Dalla propria dashboard, l'utente può gestire:
- **Link**: Aggiungere, modificare o eliminare link a risorse esterne.
- **Brani Audio**: Caricare file audio.
- **Eventi**: Creare e gestire un calendario di eventi/concerti.
- **Blog**: Pubblicare articoli e notizie.
- **Modulo di Contatto**: Gestire le richieste ricevute tramite il form di contatto/booking.

### 4.3 Interazione tra Utenti
La piattaforma prevede un sistema per seguire altri utenti (fan engagement), creando una rete sociale.

---

## Capitolo 5: Funzionalità e Roadmap Future

ChiFaCosa ha un ampio piano di sviluppo futuro, che lo renderà ancora più potente e generico.

**5.1 Miglioramenti Pianificati**
- **Wizard di installazione stile WordPress** (`install.php`): Renderà l'installazione iniziale un processo guidato e automatizzato, verificando il database, applicando lo schema, creando il primo admin e configurando il dominio.
- **Sistema di Cache**: Miglioramento delle prestazioni con OPcache e cache di pagina intera per gli utenti anonimi.
- **Statistiche dettagliate**: Monitoraggio dei click sui link.
- **Modello Freemium**: Piano gratuito con limiti (es. numero di brani/eventi) e piano premium senza limiti.
- **Directory pubblica degli artisti**: Una vetrina di tutti i profili pubblici.
- **Classifica settimanale/mensile dei brani**: Basata sulle recensioni.
- **Formazione della band**: Sistema di inviti per gestire i profili dei singoli componenti.

**5.2 Integrazioni Esterne**
La piattaforma valuterà integrazioni con servizi esterni come Spotify, YouTube e SoundCloud, mantenendo un principio di **coerenza grafica**: i contenuti saranno mostrati con lo stile di ChiFaCosa, evitando widget esterni che ne rompano l'estetica.

---

## Capitolo 6: Linee Guida per lo Sviluppo e le Estensioni

### 6.1 Principio Guida per le Integrazioni
- **Coerenza Grafica**: Ogni integrazione deve rispettare il linguaggio visivo della piattaforma (card arrotondate, palette coerente, copertine quadrate).
- **Ordine di Preferenza**:
1. **Solo Dati**: Usare titolo, immagine, link, testo, renderizzati con lo stile di ChiFaCosa (es. Spotify per Music e Podcast).
2. **Player Nativo**: Solo se necessario per riprodurre audio/video e non c'è alternativa (es. YouTube).
3. **Widget Esterno**: Da evitare. Se non c'è un'alternativa "solo dati", è meglio non integrare il servizio (es. SoundCloud, scartato perché l'alternativa gratuita è solo il widget con il suo stile).

### 6.2 Contribuire al Progetto
ChiFaCosa è un progetto open source. Per contribuire, segui le linee guida descritte nei documenti `GITHUB.md` (per il push da Windows e l'autenticazione) e nei file di documentazione tecnica.

---

**Nota**: Questo manuale è stato creato sulla base della documentazione ufficiale del progetto (`README.md` e altri file `.md`) e della roadmap dichiarata. Per eventuali aggiornamenti o approfondimenti, consulta direttamente il repository.