# Specifiche Tecniche: Integrazione Servizio `/miei` con PWA Canti

Questo documento descrive le specifiche dell'endpoint `/miei` implementato sul server Node.js e fornisce le linee guida per implementare la sincronizzazione e l'invio delle playlist locali e dei canti personalizzati ("canti miei") dalla PWA.

---

## 🌐 Dettagli dell'Endpoint `/miei`

- **Metodo HTTP**: `POST`
- **URL di Sviluppo**: `http://localhost:3000/miei` (o l'IP/porta del tuo server in produzione)
- **Content-Type**: `application/json`
- **Limite Dimensione Body**: `10MB` (per supportare liste e testi completi di canti)

### 🔑 Identificazione Utente (`uid`)
L'endpoint richiede l'identificativo unico dell'utente (`uid`). Può essere trasmesso in tre modi (in ordine di priorità):
1. **Header HTTP**: `x-user-uid` (scelta consigliata) o `uid`
2. **Query Parameter**: `?uid=<user_uid>`
3. **Wrapper nel Body**: Se il corpo è un oggetto del tipo `{ "uid": "...", "canti": [...] }`

> [!WARNING]
> L'UID dell'utente deve essere una stringa valida e sicura. Sono accettati solo caratteri alfanumerici, trattini e trattini bassi (`^[a-zA-Z0-9_\-]+$`). Qualsiasi tentativo di path traversal (es. contenente `.` o `/`) restituirà un errore `400 Bad Request`.

---

## 📦 Formato dei Dati Richiesto (Payload)

L'endpoint si aspetta di ricevere un **array JSON** contenente la lista dei canti dell'utente (formato analogo a `canti.json`). 

### Esempio di Payload (Array di Canti)
```json
[
  {
    "id_canti": 9001,
    "titolo": "Mio Canto Personalizzato 1",
    "momenti": ["Ingresso"],
    "periodi": ["Lode"],
    "testo": "Testo del mio canto personalizzato...\nRit: Alleluia!"
  },
  {
    "id_canti": 9002,
    "titolo": "Mio Canto Personalizzato 2",
    "momenti": ["Comunione"],
    "periodi": [],
    "testo": "Testo del secondo canto..."
  }
]
```

---

## 🔄 Comportamento del Server

1. **Ricezione e Validazione**:
   - Estrae l'UID ed il payload dei canti.
   - Valida l'UID (sicurezza path traversal) e verifica che il payload sia un array JSON. In caso contrario, risponde con `400 Bad Request`.
2. **Logica di Backup**:
   - Se nella cartella `data/` del server esiste già un file associato all'utente (`data/<uid>.json`), ne crea automaticamente una copia di backup rinominandola o copiandola in `data/<uid>.bak.json`.
3. **Salvataggio**:
   - Scrive il nuovo JSON in `data/<uid>.json`.
   - Risponde con `200 OK` e un JSON di conferma:
     ```json
     {
       "success": true,
       "message": "File salvato con successo.",
       "uid": "utente_test_123",
       "backupCreated": true
     }
     ```

---

## 🛠️ Requisiti per l'Implementazione nella PWA (Client Locale Mac M1)

L'istanza di Antigravity che lavora sul codice della PWA locale dovrà implementare una funzione di sincronizzazione (es. `syncLocalDataToServer`) che esegua i seguenti passi:

1. **Recupero dei dati locali**:
   - Estrarre le playlist locali e i canti personalizzati creati dall'utente (solitamente salvati in `localStorage`, `IndexedDB`, o altro database locale).
2. **Normalizzazione e Formattazione**:
   - Formattare e unire queste informazioni in un unico array JSON strutturato con i campi chiave per ciascun canto (`id_canti`, `titolo`, `momenti`, `periodi`, `testo`).
3. **Invio al Server**:
   - Effettuare una chiamata `fetch` (POST) verso l'endpoint `/miei`.
   - Passare l'UID dell'utente autenticato (es. da Firebase Auth o altro sistema di sessione) tramite l'header `x-user-uid`.
4. **Gestione del Feedback**:
   - Mostrare all'utente una notifica di successo o gestire eventuali errori di rete o validazione.