# 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`:

```json
{
  "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à. |