canti/implementazione_servizio_miei.md

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)

[
  {
    "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:

     {
       "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.