modificato deploy verso contabo

2026-06-17 01:04:27 +02:00
parent 2d23dcae83
commit 97a11d5074
24 changed files with 1063 additions and 64 deletions
@@ -0,0 +1,84 @@
+# 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.