Compila RAS v2 - Specifica gestione foto¶

Data: 2026-07-31

Obiettivo¶

Rendere la gestione foto della v2 stabile, prevedibile e adatta all'uso offline. La foto deve essere un oggetto persistente del RAS, non un riferimento fragile dentro una singola risposta.

Principi¶

Una foto aggiunta dall'utente deve essere visibile subito.
Una foto non deve sparire al refresh se e ancora recuperabile localmente o lato server.
Una cancellazione deve rimuovere la foto dalla domanda, ma non distruggerla senza possibilita di recupero.
Offline e rete lenta sono casi normali, non eccezioni.
La stampa tecnica non deve essere bloccata dalla presenza di foto locali o pending.
La stessa foto puo essere usata in piu punti, ma le operazioni devono agire sulla singola tessera/logica di assegnazione.

Stati foto¶

Locale¶

Foto presente sul dispositivo/browser e non ancora consolidata sul server.

Comportamento atteso:

visibile subito nella domanda;
visibile dopo refresh se il blob locale e ancora disponibile;
marcata chiaramente come locale/in attesa;
caricata automaticamente quando torna la connettivita.

Server¶

Foto caricata e disponibile via riferimento remoto.

Comportamento atteso:

visibile nella domanda;
persistente dopo refresh e da altri dispositivi;
usabile in stampa/preview.

Pending¶

Foto o operazione in attesa di allineamento.

Comportamento atteso:

non deve bloccare la compilazione;
deve essere visibile in UI;
deve avere retry automatico;
deve mostrare errore solo se il retry fallisce o il blob locale non e piu recuperabile.

Orfana locale¶

Riferimento locale presente nel RAS, ma blob non recuperabile dal browser.

Comportamento atteso:

non deve essere eliminata silenziosamente;
va mostrata come "foto da sistemare";
l'utente deve poterla sostituire, rimuovere, o recuperare se possibile.

Upload¶

Quando l'utente aggiunge una foto:

La tessera appare immediatamente nella domanda.
Il blob viene salvato localmente.
Se online, parte upload verso server/MinIO.
Se upload riesce, il riferimento locale viene sostituito o collegato al riferimento server.
Se upload fallisce o rete lenta/offline, la foto resta visibile come locale/pending.
Al ritorno online, la coda riprova senza azione manuale obbligatoria.

Refresh pagina¶

Dopo ricarica pagina devono essere visibili:

foto server;
foto locali ancora presenti nel browser;
foto pending;
placeholder espliciti per foto orfane locali.

Non e accettabile che una foto caricata sparisca senza messaggio.

Cancellazione¶

Quando l'utente cancella una foto da una domanda:

La foto sparisce subito dalla domanda.
Viene creato un record nel cestino del RAS.
Il record conserva:
documento/RAS;
domanda origine;
sezione origine;
riferimento foto;
stato al momento della cancellazione: locale, server, pending;
timestamp;
utente/dispositivo se disponibili.
Se la foto e server e siamo online, la rimozione della relazione domanda-foto viene sincronizzata subito.
Se siamo offline, viene creata una operazione delete_pending.
Al ritorno online, la cancellazione si allinea automaticamente.

La cancellazione non deve rimuovere altre occorrenze della stessa foto.

Cestino RAS¶

Ogni RAS deve avere un cestino foto.

Il cestino serve a recuperare errori operativi e a non perdere evidenze importanti.

Azioni previste:

ripristina nella domanda originale;
sposta in parcheggio;
elimina definitivamente, eventualmente solo per profili autorizzati;
visualizza riferimento origine.

Parcheggio¶

Il parcheggio resta fondamentale.

Uso previsto:

spostare foto tra domande;
depositare foto non ancora classificate;
recuperare foto dal cestino senza rimetterle subito nella domanda originale.

Il parcheggio e diverso dal cestino:

parcheggio: foto valida da ricollocare;
cestino: foto rimossa da una domanda, recuperabile.

Duplicati¶

Regola base:

operazioni su una tessera agiscono su quella tessera.

Casi:

stessa foto duplicata nella stessa domanda: cancellare una tessera lascia l'altra;
stessa foto usata in domande diverse: cancellarla da una domanda non tocca le altre;
per eliminare definitivamente il blob server serve verificare che non sia piu referenziato da nessuna domanda, parcheggio, cestino o bozza.

Stampa e preview¶

La stampa/PDF e una visione tecnica e deve essere sempre consentita.

Comportamento atteso:

foto server: render normale;
foto locali disponibili: render da browser/cache se tecnicamente possibile;
foto pending non disponibili al renderer: placeholder con indicazione;
foto orfane: placeholder "foto non disponibile / da sistemare";
nessun blocco totale della stampa per il solo fatto che esistano foto locali o pending.

Offline¶

Offline deve essere supportato come scenario reale.

Serve una coda operazioni con almeno:

upload_pending;
delete_pending;
restore_pending;
move_pending;
park_pending;
trash_pending.

La UI deve distinguere chiaramente:

definitivo;
locale;
in sincronizzazione;
errore;
orfano;
cancellato recuperabile.

Direzione tecnica proposta¶

Introdurre un registro foto per RAS, o "photo ledger", che diventi la fonte autorevole degli stati foto.

Le domande non dovrebbero gestire direttamente tutta la complessita foto. Dovrebbero riferirsi a record del registro o a assegnazioni domanda-foto.

Entita concettuali:

photo_asset: foto/blob e metadati;
photo_assignment: uso della foto in una domanda/parcheggio/cestino;
photo_operation: operazioni pending/offline da sincronizzare.

Criterio di stabilita¶

La gestione foto v2 puo essere considerata stabile solo quando questi flussi passano:

upload online, refresh, foto ancora visibile;
upload offline, refresh offline, foto ancora visibile;
ritorno online, upload automatico, refresh da secondo dispositivo;
cancellazione online, foto in cestino, ripristino;
cancellazione offline, refresh, ritorno online, allineamento;
spostamento tramite parcheggio;
duplicato stessa domanda, cancellazione singola tessera;
stessa foto in due domande, cancellazione su una sola;
stampa con foto server;
stampa con foto locali/pending/orfane senza blocco totale.