# Manuale amministratore - HOME SERVICES By CHANEL

Questo manuale spiega come usare l'area amministratore del portale HOME SERVICES By CHANEL per gestire disponibilita, richieste, prenotazioni, incassi, spese, backup ed email di conferma.

## 1. Accesso al pannello amministratore

### Indirizzo area admin

Aprire il sito e cliccare su `Admin`, oppure visitare direttamente:

```text
https://hschanel.com/admin.html
```

Se il dominio non e ancora collegato, usare l'indirizzo Render:

```text
https://hsc-422z.onrender.com/admin.html
```

### Login

1. Inserire la password amministratore.
2. Premere `Entra`.
3. Dopo il login si apre il pannello di gestione.

La password non e scritta nel sito pubblico: viene configurata nelle variabili ambiente del servizio Render come `ADMIN_PASSWORD`.

## 2. Struttura del pannello

L'area amministratore contiene queste sezioni:

- `Calendario`: vista globale delle prenotazioni e richieste.
- `Prenotazioni`: inserimento, conferma, pagamento ed eliminazione prenotazioni.
- `Movimenti`: gestione incassi, spese, filtri ed esportazione.
- `Backup dati`: esportazione e importazione dei dati del portale.

In alto sono mostrati anche i riepiloghi:

- numero totale prenotazioni;
- numero richieste in attesa;
- totale incassi;
- totale importi da pagare;
- saldo tra incassi e spese.

## 3. Calendario amministratore

Il calendario amministratore mostra tutte le prenotazioni dei quattro appartamenti:

- `BOARA-15`
- `BOARA-16`
- `BASSANO`
- `SANTO DOMINGO`

### Colori del calendario

- `Libero`: nessuna prenotazione o richiesta.
- `Richiesto`: richiesta ricevuta ma non ancora confermata.
- `Prenotato`: prenotazione confermata.

### Filtro appartamento

Il menu `Filtro` permette di vedere:

- tutti gli appartamenti;
- un singolo appartamento.

### Dettagli giorno

Cliccando su un giorno del calendario, a destra appare il pannello `Dettagli giorno`.

Il pannello mostra:

- nome cliente;
- email;
- cellulare;
- appartamento;
- periodo;
- arrivo, soggiorno o partenza;
- numero persone;
- stato prenotazione;
- stato pagamento;
- note;
- importo.

### Giorno di arrivo e partenza

Se un cliente parte lo stesso giorno in cui un altro cliente arriva, il calendario amministratore mostra entrambi.

Esempio:

- Cliente A: partenza 07/06/2026.
- Cliente B: arrivo 07/06/2026.

Nel dettaglio del 07/06/2026 devono comparire entrambi, uno come `Partenza` e uno come `Arrivo`.

## 4. Nuova prenotazione dall'amministratore

La sezione `Nuova prenotazione` serve per inserire manualmente una prenotazione o una richiesta.

### Campi disponibili

- `Appartamento`: scegliere l'appartamento.
- `Arrivo`: data ingresso.
- `Partenza`: data uscita.
- `Numero persone`: da 1 a 3.
- `Ospite`: nome cliente o nomi persone.
- `Email cliente`: email del cliente.
- `Prefisso`: prefisso internazionale.
- `Cellulare`: numero telefonico.
- `Stato`: `Prenotato` o `Richiesto`.
- `Incasso previsto`: importo previsto.
- `Annotazioni`: note interne o richieste dell'ospite.
- `Pagamento`: `Pagato` o `Da pagare`.

### Salvataggio

Premere `Salva prenotazione`.

Il sistema controlla automaticamente se lo stesso appartamento e lo stesso periodo sono gia occupati.

Se il periodo e occupato, appare un avviso e la prenotazione non viene salvata.

### Regola anti doppia prenotazione

Non e possibile prenotare lo stesso appartamento nello stesso periodo per due clienti diversi.

E' invece possibile avere:

- cliente che parte il giorno 10;
- nuovo cliente che arriva il giorno 10.

Questo e considerato cambio ospite nello stesso giorno ed e permesso.

## 5. Elenco prenotazioni

La tabella `Prenotazioni` mostra tutte le prenotazioni e richieste.

### Colonne

- `Periodo`: arrivo e partenza.
- `Appartamento`: nome appartamento.
- `Cliente`: nome, email e cellulare.
- `Persone`: numero persone.
- `Prezzo`: importo.
- `Annotazioni`: note.
- `Pagamento`: pagato o da pagare.
- `Stato`: richiesto o prenotato.
- `Azioni`: pulsanti operativi.

### Azioni disponibili

#### Accetta

Visibile solo per le richieste.

Quando si preme `Accetta`:

1. la richiesta diventa prenotazione confermata;
2. lo stato passa da `Richiesto` a `Prenotato`;
3. se SMTP e configurato, il cliente riceve una email di conferma.

#### Segna pagato / Segna da pagare

Permette di cambiare lo stato pagamento.

Usare:

- `Segna pagato` quando il cliente ha pagato;
- `Segna da pagare` se l'importo deve ancora essere incassato.

#### Elimina

Elimina la prenotazione.

Usare con attenzione: l'eliminazione rimuove la prenotazione dall'elenco e libera il periodo.

## 6. Movimenti, incassi e spese

La sezione `Movimenti` serve per controllare la contabilita.

### Inserire un movimento

Nel modulo `Spese e incassi` compilare:

- `Tipo`: incasso o spesa.
- `Appartamento`: appartamento collegato.
- `Data ingresso`: data di riferimento iniziale.
- `Data uscita`: data di riferimento finale.
- `Nome persona`: cliente o fornitore.
- `Numero persone`: numero persone, se applicabile.
- `Importo`: importo del movimento.
- `Pagamento`: pagato o da pagare.
- `Descrizione`: descrizione del movimento.
- `Annotazioni`: note aggiuntive.

Premere `Aggiungi movimento`.

### Incassi automatici

Quando l'amministratore inserisce una prenotazione con importo maggiore di zero, il sistema crea anche un movimento di incasso.

La descrizione include anche la data incasso.

Nel pannello `Prenotazioni` il pulsante `Esporta Excel prenotazioni` scarica l'elenco completo.

Il pulsante `Crea incasso` genera un movimento collegato alla prenotazione. Se l'incasso e gia presente, il pulsante non viene piu mostrato.

## 7. Filtri movimenti

La tabella `Movimenti` puo essere filtrata per:

- appartamento;
- data ingresso da;
- data uscita a;
- nome persona;
- importo minimo;
- stato pagamento.

### Azzera filtri

Il pulsante `Azzera filtri` rimuove tutti i filtri e mostra nuovamente tutti i movimenti.

## 8. Esportazione movimenti

Sono disponibili due formati:

- `Esporta CSV`
- `Esporta Excel`

### Quando usare CSV

Usare CSV per:

- importazione in gestionali;
- archivi leggeri;
- elaborazioni semplici.

### Quando usare Excel

Usare Excel per:

- apertura diretta in Microsoft Excel;
- controllo visivo;
- invio a commercialista o collaboratori.

L'esportazione rispetta i filtri impostati: se prima filtri per appartamento o periodo, viene esportato solo cio che e visibile.

## 8.1 Database indirizzi

La sezione `Indirizzi` crea automaticamente una rubrica clienti partendo da richieste e prenotazioni.

Per ogni contatto vengono salvati:

- nome in maiuscolo;
- email;
- cellulare;
- indirizzo;
- citta;
- nazione;
- appartamenti collegati;
- primo soggiorno;
- ultimo soggiorno;
- numero prenotazioni;
- annotazioni.

Premere `Esporta Excel indirizzi` per scaricare la rubrica in formato Excel.

## 8.2 Log amministratore

La sezione `Log` registra:

- richieste inviate dai clienti;
- accettazioni prenotazioni;
- aggiornamenti dati;
- ripristini backup.

## 9. Backup e ripristino dati

Questa sezione e fondamentale.

Il portale salva prenotazioni e movimenti sul server. Prima di ogni aggiornamento importante e buona pratica scaricare un backup.

### Backup automatico settimanale

Il server crea automaticamente un backup al giorno nella cartella persistente:

```text
/var/data/backups
```

I file sono sette, uno per ogni giorno della settimana:

```text
backup-lunedi.json
backup-martedi.json
backup-mercoledi.json
backup-giovedi.json
backup-venerdi.json
backup-sabato.json
backup-domenica.json
```

Alla settimana successiva il file dello stesso giorno viene sovrascritto, cosi lo spazio occupato resta limitato. Il fuso orario predefinito e `Europe/Rome`.

Il pulsante `Scarica backup automatico` permette di salvare sul computer il backup selezionato.

### Ripristinare un backup automatico

Nella parte alta del pannello amministratore:

1. Aprire il menu `Backup automatico`.
2. Scegliere il file da ripristinare.
3. Premere `Ripristina backup automatico`.
4. Confermare l'operazione.
5. Inserire la password dedicata `Restore`.

Il ripristino sostituisce prenotazioni e movimenti attuali con quelli contenuti nel backup scelto.

### Esportare backup dati

1. Entrare nell'area amministratore.
2. Premere `Esporta backup dati`.
3. Il browser scarica un file JSON, ad esempio:

```text
backup-home-services-2026-05-28.json
```

Conservare questo file in una cartella sicura.

### Importare backup dati

1. Entrare nell'area amministratore.
2. Premere `Importa backup dati`.
3. Selezionare il file JSON salvato.
4. Attendere il messaggio di conferma.

Il ripristino sostituisce i dati presenti con quelli del backup.

### Regola pratica consigliata

Fare un backup:

- prima di ogni deploy;
- prima di modifiche importanti;
- dopo aver inserito molte prenotazioni;
- almeno una volta a settimana.

## 10. Persistenza dati su Render

Per non perdere prenotazioni e movimenti, Render deve usare un Disk persistente.

### Configurazione corretta

Nel servizio Render devono esserci:

```text
DATA_DIR=/var/data
```

e un Disk collegato con mount path:

```text
/var/data
```

### Controllo tecnico

Dopo il login admin, aprire:

```text
https://hsc-422z.onrender.com/api/admin/storage
```

Il risultato corretto deve indicare:

```text
dataDir: "/var/data"
renderDiskDetected: true
```

Se non e cosi, il Disk non e collegato correttamente oppure il servizio sta salvando ancora nel filesystem temporaneo.

## 11. Email di conferma prenotazione

Quando una richiesta viene accettata, il sistema puo inviare una email di conferma al cliente.

### Variabili SMTP richieste

Su Render, nella sezione `Environment`, configurare:

```text
SMTP_HOST=
SMTP_PORT=465
SMTP_USER=
SMTP_PASS=
SMTP_FROM=
```

Esempio Gmail:

```text
SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_USER=nome@gmail.com
SMTP_PASS=password-app-gmail
SMTP_FROM=HOME SERVICES By CHANEL <nome@gmail.com>
```

Per Gmail serve una password per app, non la password normale dell'account.

### Se SMTP non e configurato

Se SMTP non e configurato, il sistema non invia davvero l'email ma salva un file `.eml` nella cartella:

```text
data/outbox
```

Su Render questa cartella deve stare dentro `/var/data/outbox` se il Disk e configurato bene.

## 12. Calendario pubblico e disponibilita

Il calendario pubblico mostra ai visitatori lo stato degli appartamenti senza dati personali.

Il visitatore vede:

- giorni liberi;
- giorni richiesti;
- giorni prenotati.

Non vede:

- nome cliente;
- email;
- cellulare;
- importo;
- annotazioni interne.

Questi dettagli sono visibili solo all'amministratore.

## 13. Prenotazioni dal portale pubblico

Il visitatore puo inviare una richiesta dal portale compilando:

- appartamento;
- arrivo;
- partenza;
- numero persone;
- nomi persone;
- email;
- prefisso;
- cellulare;
- annotazioni.

Il sistema controlla la disponibilita e impedisce richieste sovrapposte.

La richiesta arriva come `Richiesto` e deve essere accettata dall'amministratore.

## 14. Lingue disponibili

Il portale pubblico supporta:

- italiano;
- spagnolo;
- inglese;
- russo.

Il selettore lingua e presente in home page e nelle schede appartamento.

La lingua scelta viene salvata nel browser del visitatore.

L'area amministratore resta in italiano.

## 15. Dominio hschanel.com

Il dominio deve essere collegato a Render tramite DNS, non tramite redirect mascherato.

### DNS consigliato

Per `www.hschanel.com`:

```text
Tipo: CNAME
Nome: www
Valore: hsc-422z.onrender.com
```

Per `hschanel.com`:

```text
Tipo: A
Nome: @
Valore: 216.24.57.1
```

Oppure usare `CNAME`, `ANAME` o `ALIAS` se il provider DNS lo consente.

Non usare redirect mascherato, URL frame o cloak, perche il sito blocca l'apertura dentro iframe per sicurezza.

## 16. Procedura consigliata prima di ogni aggiornamento

Prima di pubblicare una nuova versione:

1. Entrare in admin.
2. Premere `Esporta backup dati`.
3. Verificare che il file JSON sia stato scaricato.
4. Fare il deploy.
5. Controllare che prenotazioni e movimenti siano ancora presenti.
6. Se mancano dati, usare `Importa backup dati`.

## 17. Procedura di pubblicazione aggiornamenti

Dal computer di sviluppo, aprire Git Bash nella cartella del progetto:

```bash
cd "/c/Users/studi/Documents/Codex/2026-05-27/devo-sviluppare-un-portale-con-home"
```

Poi eseguire:

```bash
git add .
git commit -m "Aggiornamento portale"
git push origin render-deploy
```

Render pubblichera automaticamente la nuova versione se il deploy automatico e attivo.

Se non parte da solo:

1. aprire Render;
2. entrare nel servizio `HSC`;
3. premere `Manual Deploy`;
4. scegliere `Deploy latest commit`.

## 18. Problemi comuni

### Ho perso le prenotazioni dopo un deploy

Possibili cause:

- Disk Render non collegato;
- `DATA_DIR` non impostato su `/var/data`;
- servizio diverso da quello configurato;
- deploy fatto prima di creare il Disk.

Soluzione:

1. controllare `/api/admin/storage`;
2. verificare `dataDir`;
3. importare l'ultimo backup JSON.

### Il cliente non riceve email

Controllare:

- `SMTP_HOST`;
- `SMTP_PORT`;
- `SMTP_USER`;
- `SMTP_PASS`;
- `SMTP_FROM`;
- password per app se si usa Gmail;
- log Render.

### Il dominio mostra "connessione negata"

Probabile redirect mascherato.

Soluzione:

- eliminare redirect/iframe;
- configurare DNS diretto su Render.

### Il calendario pubblico sembra occupato nel giorno di partenza

E' normale: il calendario mostra che in quel giorno c'e una movimentazione.

Il sistema permette comunque un nuovo arrivo lo stesso giorno della partenza, se i periodi non si sovrappongono.

## 19. Buone pratiche

- Fare backup regolari.
- Non condividere la password admin.
- Controllare periodicamente i movimenti.
- Usare sempre email e cellulare reali del cliente.
- Inserire annotazioni utili per arrivo, orari, richieste speciali.
- Verificare il pagamento prima di segnare `Pagato`.
- Non cancellare prenotazioni se non si e sicuri.
- Prima di ogni deploy, esportare il backup.

## 20. Riepilogo rapido

Operazioni principali:

1. Controllare disponibilita dal calendario admin.
2. Inserire o accettare prenotazioni.
3. Verificare pagamenti.
4. Registrare incassi e spese.
5. Esportare movimenti in CSV o Excel.
6. Fare backup dati.
7. Verificare che Render usi `/var/data`.