David Frassi
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# 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.
|