canti/parametri_canti_comunita.md

Parametri letti da canti.json e da Comunità

Questo documento elenca tutti i parametri e i campi strutturati che vengono letti, elaborati e salvati dall'applicazione a partire dal file globale canti.json e dalle API/file di configurazione delle Comunità.

---

1. Parametri da canti.json

Il file canti.json rappresenta il database globale dei canti dell'applicazione. Viene scaricato dall'endpoint configurato in CantiService (es. https://www.canticristiani.it/api/canti.json).

Struttura Principale del File

Il JSON restituito contiene diversi nodi chiave, ciascuno contenente un array data:

{
  "canti": { "data": [...] },
  "indice_liturgico": { "data": [...] },
  "indice_tematico": { "data": [...] },
  "tema": { "data": [...] },
  "canti_eseguiti": { "data": [...] }
}

Nodo canti.data (Lista dei Canti)

Ciascun elemento rappresenta un canto e viene mappato nell'interfaccia Canto:

Parametro Originale	Tipo	Descrizione
id_canti	number	Identificativo univoco del canto (usato internamente anche come stringa id).
titolo	string	Titolo del canto.
testo	string	Testo del canto (può includere indicazioni di accordi).
accordi	string (opzionale)	Accordi musicali associati al canto.
autore	string (opzionale)	Autore o autori del canto.
link_youtube	string (opzionale)	URL o ID del video di YouTube associato al canto.
data_update	string (opzionale)	Data dell'ultimo aggiornamento (formato YYYY-MM-DD HH:mm:ss, formattata a schermo in DD/MM/YYYY).
nonValidato	boolean (opzionale)	Indica se il canto è in attesa di validazione.
isPersonal	boolean (opzionale)	Flag locale per identificare se si tratta di un canto personale dell'utente.

Nota: Durante l'importazione, viene aggiunto un array id_momenti: number[] ricavato dalla tabella pivot tema.data.

Nodo indice_liturgico.data e indice_tematico.data (Indici/Tag)

Mappati nell'interfaccia Indice:

Parametro Originale	Tipo	Descrizione
id_indice_liturgico / id_indice_tematico	number	Identificativo dell'indice/momento.
tag_name	string	Nome visualizzato del tag (es. "Ingresso", "Offertorio").
slug	string	Versione ottimizzata per URL del tag.

Nota: A livello applicativo viene aggiunto il campo type con valore 'liturgico' o 'tematico'.

Nodo tema.data (Relazione Pivot Canti-Indici)

Utilizzato per associare a ogni canto i rispettivi momenti liturgici o tematici:

Parametro Originale	Tipo	Descrizione
id_canti	number	ID del canto associato.
id_momento	number	ID del momento liturgico/tematico.

Nodo canti_eseguiti.data

Informazioni sull'esecuzione dei canti:

Parametro Originale	Tipo	Descrizione
id_canti	number	ID del canto eseguito.
num	number	Numero di esecuzioni o indicatore di frequenza.

---

2. Parametri dalle Comunità

I dati di una comunità vengono letti in due modi: tramite l'API di produzione (v3) oppure tramite un file JSON statico di fallback.

Opzione A: API di Produzione (get_all_app_tables)

Endpoint: https://libretto.mmcinet.eu/canti/api/v3/get_all_app_tables

L'API risponde con un oggetto contenente diverse tabelle relazionali:

1. parrocchia.data (Dettagli della Comunità)

Parametro Originale	Tipo	Descrizione
id_parrocchia	number	ID interno della parrocchia/comunità.
nome	string	Nome della comunità (es. "Parrocchia S. Maria").
codice	string	Codice alfanumerico della comunità.
mail	string	Email di riferimento della comunità.
guid_parrocchia	string	GUID univoco.

2. parrocchia_canti.data (Associazione Canti-Comunità)

Indica quali canti del database generale appartengono al repertorio della comunità:

Parametro Originale	Tipo	Descrizione
id_parrocchia	number	ID della parrocchia.
id_canti	number	ID del canto associato.
num_canto	number	Numero progressivo o di classificazione del canto all'interno della comunità.

3. canti_settings.data (Impostazioni di Esecuzione personalizzate)

Configurazioni specifiche per l'esecuzione del canto in comunità:

Parametro Originale	Tipo	Descrizione
id_canti	number	ID del canto.
speed	number	Velocità di scorrimento (auto-scroll) consigliata.
tonalita	number	Semitoni di trasposizione (trasporto tonalità) consigliati.

4. canti_personali.data (Canti personalizzati/inediti della Comunità)

Canti inseriti direttamente dalla comunità e non presenti nel database globale:

Parametro Originale	Tipo	Descrizione / Mapping Applicativo
id_canti	number	ID del canto personale.
titolo	string	Titolo del canto.
accordi	string	Testo con gli accordi del canto.
autore	string	Autore del canto.
link_youtube	string	Link YouTube.
data_update	string	Data dell'ultimo aggiornamento.
stato	number	Se uguale a 10, il canto viene contrassegnato come nonValidato = true.

Nota: Vengono impostati automaticamente isPersonal = true e id_momenti = [].

5. Scalette della Comunità (lista_nome + lista_esecuzione)

L'applicazione ricostruisce l'elenco delle scalette (ComunitaScaletta):

• lista_nome.data (Testate delle scalette):
  • id_lista (string/number): ID della scaletta.
  • nome (string): Nome della scaletta (es. "Domenica delle Palme").
  • progr (string): Data o stringa di ordinamento (mappata in date).
• lista_esecuzione.data (Canti contenuti nelle scalette):
  • id_lista (string/number): Associazione alla scaletta.
  • id_canti (number): ID del canto.
  • progr (number): Ordine progressivo del canto all'interno della scaletta (usato per l'ordinamento).

---

Opzione B: Fallback Statico (comunita_[codice].json)

Se l'API di produzione non è raggiungibile, viene tentato il download di un file statico (es. comunita_123456.json) dall'origine del sito.

La struttura attesa per questo file è molto più semplice:

Parametro JSON	Tipo	Descrizione
id_comunita	string	Codice identificativo della comunità.
nome_comunita	string	Nome leggibile della comunità.
canti	(number | string)[]	Array contenente gli ID di tutti i canti associati a questa comunità.