Integrazione Liturgia: accordioni, navigazione date, proxy CORS, alto contrasto e piano AI

2026-05-16 18:50:15 +02:00
parent ff992daa58
commit 9982441c3c
11 changed files with 732 additions and 2 deletions
@@ -0,0 +1,224 @@
+# 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