# Piano di Azione: Suggerimento Canti con AI (cantiletture.json)

## Obiettivo

Generare automaticamente, una volta a settimana, un file JSON con i canti suggeriti per ogni messa della settimana, analizzati da Gemini Flash a partire dalle letture liturgiche. La PWA scarica questo file statico e mostra i suggerimenti istantaneamente, senza alcun calcolo lato client.

---

## Architettura

```
CRON Settimanale (Lunedì ore 6:00)
        │
        ├─ 1. Fetch RSS liturgia.silvestrini.org/rss
        │      → Estrae le letture di tutta la settimana (7 giorni)
        │
        ├─ 2. Fetch canti.json dal server
        │      → Carica il database completo dei canti con testi e momenti liturgici
        │
        ├─ 3. Chiamata API Gemini Flash
        │      → Invia prompt strutturato con letture + lista canti
        │      → Riceve suggerimenti ragionati con score e motivazione
        │
        └─ 4. Salva cantiletture.json
               → Upload sul server web (stessa posizione di canti.json)
```

---

## Struttura del File cantiletture.json

```json
{
  "generated_at": "2026-05-19T06:00:00Z",
  "week_start": "2026-05-17",
  "week_end": "2026-05-24",
  "masses": {
    "2026-05-17": {
      "title": "Ascensione del Signore",
      "day": "Domenica",
      "moments": {
        "Ingresso": [
          {
            "id_canti": 42,
            "titolo": "Cristo è risorto veramente",
            "score": 95,
            "motivo": "Il tema dell'ascensione e della gloria di Cristo risorto è centrale in questo canto."
          },
          {
            "id_canti": 118,
            "titolo": "Alleluia, è risorto",
            "score": 88,
            "motivo": "Il tono gioioso e la proclamazione pasquale si collegano al mistero celebrato."
          },
          {
            "id_canti": 205,
            "titolo": "Canto di lode al Signore",
            "score": 82,
            "motivo": "Richiama il tema della lode che accompagna l'ascensione di Gesù."
          }
        ],
        "Offertorio": [
          { "...": "3 canti suggeriti" }
        ],
        "Comunione": [
          { "...": "3 canti suggeriti" }
        ],
        "Finale": [
          { "...": "3 canti suggeriti" }
        ]
      }
    },
    "2026-05-18": {
      "title": "Lunedì della VII settimana di Pasqua",
      "day": "Lunedì",
      "moments": { "...": "stessa struttura" }
    }
  }
}
```

### Campi per ogni canto suggerito:
| Campo | Tipo | Descrizione |
|-------|------|-------------|
| `id_canti` | number | ID del canto nel database (per collegamento diretto al player) |
| `titolo` | string | Titolo del canto (per visualizzazione rapida) |
| `score` | number (0-100) | Grado di affinità/affidabilità del suggerimento |
| `motivo` | string | Spiegazione testuale del perché il canto è adatto |

---

## Componenti da Sviluppare

### 1. Script di Generazione (`scripts/generate-cantiletture.ts`)

Script Node.js/TypeScript che:

- **Input**: RSS feed + canti.json
- **Elaborazione**:
  1. Parsing XML del feed RSS (estrazione letture per data)
  2. Preparazione del prompt per Gemini con: testo letture + lista canti (id, titolo, testo, momenti liturgici)
  3. Chiamata API Gemini Flash con output JSON strutturato
  4. Validazione della risposta (verifica che gli ID canti esistano, score nel range)
- **Output**: File `cantiletture.json`

**Prompt di esempio per Gemini:**
```
Sei un esperto liturgista cattolico. Ti fornisco le letture della messa 
e un database di canti liturgici con i relativi momenti (Ingresso, 
Offertorio, Comunione, Finale, ecc.).

Per ogni giorno della settimana e per ogni momento liturgico, suggerisci
i 3 canti più adatti. Per ogni suggerimento indica:
- L'ID del canto (id_canti)
- Uno score da 0 a 100 che indica il grado di attinenza
- Una breve motivazione (max 1 frase)

Considera: temi teologici, periodo liturgico, tono emotivo, 
corrispondenze tra letture e testi dei canti.

LETTURE DELLA SETTIMANA:
[...testo letture...]

DATABASE CANTI:
[...lista canti con id, titolo, testo, momenti...]

Rispondi SOLO con JSON valido nel formato specificato.
```

### 2. Configurazione API Key

- Ottenere API Key gratuita da [Google AI Studio](https://aistudio.google.com/apikey)
- Salvarla come variabile d'ambiente `GEMINI_API_KEY`
- Non committarla nel repository (usare `.env` in `.gitignore`)

### 3. Aggiornamento PWA

#### 3.1 Nuovo Service: `CantiLettureService`
```typescript
// Logica semplificata:
// - Scarica cantiletture.json dal server (con cache)
// - Espone i suggerimenti per data selezionata
// - Fallback al keyword matching se il JSON non è disponibile
```

#### 3.2 Aggiornamento LiturgiaPage
- Rimuovere il tasto "Analizza e Suggerisci Canti" (non serve più)
- Rimuovere la sezione "Parole Chiave Rilevate" (non serve più)
- Mostrare automaticamente i suggerimenti raggruppati per momento liturgico
- Ogni card mostra: titolo, score (barra o badge), motivazione dell'AI
- Click sulla card → apre il canto nel player

#### 3.3 Fallback
Se `cantiletture.json` non è disponibile o la data non è coperta:
- Mostrare un messaggio "Suggerimenti AI non disponibili per questa data"
- Opzionalmente, offrire il keyword matching come alternativa

### 4. Automazione (CRON)

#### Opzione A: Script locale con crontab
```bash
# Ogni lunedì alle 6:00
0 6 * * 1 cd /path/to/canti && node scripts/generate-cantiletture.js
```

#### Opzione B: GitHub Action (se il repo viene messo su GitHub)
```yaml
# .github/workflows/generate-suggestions.yml
name: Generate Canti Suggestions
on:
  schedule:
    - cron: '0 6 * * 1'  # Ogni lunedì alle 6:00 UTC
  workflow_dispatch: # Esecuzione manuale
```

#### Opzione C: Script manuale
```bash
# Eseguibile a mano quando si vuole aggiornare
./scripts/generate-cantiletture.sh
```

---

## Stima Costi

| Voce | Valore |
|------|--------|
| Chiamate API/settimana | 1 (una sola chiamata copre tutta la settimana) |
| Token input (letture + ~500 canti) | ~15.000 token |
| Token output (JSON suggerimenti) | ~3.000 token |
| Costo per chiamata (Gemini Flash) | ~0.001€ |
| **Costo mensile stimato** | **< 0.01€** |
| Rientra nell'abbonamento Google One | ✅ Sì |

---

## Piano di Esecuzione (Step by Step)

### Fase 1: Script di Generazione
1. [ ] Creare `scripts/generate-cantiletture.ts`
2. [ ] Implementare il parsing RSS
3. [ ] Implementare la chiamata Gemini con prompt ottimizzato
4. [ ] Testare con le letture della settimana corrente
5. [ ] Validare il JSON generato

### Fase 2: Integrazione PWA
6. [ ] Creare `CantiLettureService` che scarica e gestisce il JSON
7. [ ] Aggiornare `LiturgiaPage` per mostrare i suggerimenti AI
8. [ ] Implementare il fallback al keyword matching
9. [ ] Testare l'interfaccia completa

### Fase 3: Automazione
10. [ ] Configurare il cron/script di esecuzione automatica
11. [ ] Testare il ciclo completo (generazione → upload → visualizzazione)
12. [ ] Documentare la procedura nel README

---

## Note Tecniche

- **Dimensione stimata del JSON**: ~50-100 KB per settimana (7 giorni × 4-5 momenti × 3 canti)
- **Cache**: Il JSON viene cachato in localStorage con TTL di 24 ore
- **Compatibilità**: Il file viene servito dallo stesso server HTTP della PWA, nessun problema CORS
- **Retrocompatibilità**: Se il file non esiste, la PWA continua a funzionare con il keyword matching
