Vai al contenuto

SafeTecnico Mobile Pilot 1.ST

Scopo

SafeTecnico e' l'APK Android produzione per accompagnare Compila v3 sul campo. Non sostituisce il runtime web: apre e usa le schede dinamiche Compila v3 pubblicate sul portale SafeOps.

Aprire dal tablet:

https://safeops.nxt-sense.eu/compila-v3/mobile/app

Il portale richiede login. Dopo il login mostra APK, versione, SHA-256 e note operative.

Versione Corrente

  • App: SafeTecnico
  • Package: it.safeops.safetecnico
  • Versione: 1.ST.74
  • Version code: 75
  • Profilo: offline_sync_contract

Uso Tecnico

  1. Installare l'APK dal portale.
  2. Aprire SafeTecnico.
  3. Toccare Accedi / cambia.
  4. Effettuare login.
  5. Se l'utente ha piu' tenant, selezionare il tenant corretto.
  6. Usare Aggiorna RAS per caricare i RAS dinamici assegnati.
  7. Toccare un RAS per aprirlo nel runtime Compila v3.
  8. Usare Home in alto a destra per tornare alla home tecnica dell'APK.

Limiti Offline

SafeTecnico 1.ST.4 include Offline Fase 1.

Disponibile offline:

  • ultima lista RAS/metadati gia' scaricata dal tecnico;
  • visualizzazione read-only del riepilogo RAS in cache;
  • indicazione eta' cache.

Offline Fase 2 e' preparata a livello di contratto API, ma le scritture native restano disattivate.

Endpoint contratto per documento:

GET /api/compila-v3/mobile/documents/<document_id>/offline-contract

Il contratto espone:

  • GET /api/ras/v2/documents/<document_id>/export
  • GET /api/ras/v2/documents/<document_id>/draft
  • PUT /api/ras/v2/documents/<document_id>/draft
  • GET /api/ras/v2/documents/<document_id>/lease
  • POST /api/ras/v2/documents/<document_id>/lease/acquire
  • POST /api/ras/v2/documents/<document_id>/lease/renew
  • POST /api/ras/v2/documents/<document_id>/lease/release
  • POST /api/ras/v2/documents/<document_id>/media

Le scritture native offline dovranno usare lease, base_rev e policy conflitti server_rev_required.

Da 1.ST.5 l'APK esegue preflight lease prima di aprire un RAS:

  • scarica il contratto offline del documento;
  • controlla lo stato checkout tramite RAS API v2;
  • blocca l'apertura se il documento risulta in checkout da un altro utente.

Da 1.ST.6 l'APK registra un audit locale diagnostico degli ultimi eventi sync/preflight:

  • contratto offline salvato;
  • lease preflight OK;
  • apertura bloccata per checkout;
  • apertura offline bloccata;
  • preflight non disponibile.

L'audit non contiene password, token lease, foto o payload compilati.

Da 1.ST.7 l'APK mantiene anche una coda bozze locale diagnostica:

  • documento;
  • tenant;
  • stato preflight/lease;
  • URL relativi draft/lease dal contratto offline;
  • nessun payload compilato;
  • nessuna foto;
  • nessun invio automatico.

Da 1.ST.8 l'apertura manuale o da ultimo documento non parte piu' direttamente dal control-plane se il tenant non e' selezionato. L'app sceglie o richiede il tenant operativo e apre il RAS tramite tenant launch/handoff.

Da 1.ST.9 il dialog di scelta tenant mostra direttamente le opzioni tenant cliccabili.

Da 1.ST.10 l'APK usa login nativo mobile con access token breve e refresh token a 90 giorni salvato cifrato tramite Android Keystore. Il tenant launch usa bearer token mobile.

Da 1.ST.11 anche lista RAS, dettaglio, launch e contratto offline usano endpoint bearer mobile. Da 1.ST.12 la selezione tenant resta nel flusso nativo APK: aggiorna tenant/lista RAS senza aprire la pagina web di scelta tenant. Da 1.ST.13 il logout revoca anche il refresh token server-side quando presente e la WebView non accetta cookie terze parti. Da 1.ST.24 gli strumenti principali sono compattati in riga nella home APK. Da 1.ST.25 la home mostra i condomini gestiti/visibili al tecnico. Da 1.ST.26 il tap su un condominio filtra la lista RAS su quel condominio. Da 1.ST.27 la home tecnico carica i condomini assegnati via API e mostra i documenti caricati online del condominio selezionato, escludendo i RAS dinamici dalla lista documenti. Da 1.ST.28 la ricarica home tecnico aggiorna in modo coerente RAS, clienti e stato documenti caricati, evitando residui del cliente precedente. Da 1.ST.29 l'esperienza viene generalizzata da condomini a clienti assegnati e introduce il concetto di moduli tecnico attivi/selezionabili. Da 1.ST.30 la lista clienti assegnati puo' essere compressa/espansa dalla home per recuperare spazio verticale su tablet. Da 1.ST.31 l'API mobile espone il contratto generico assigned-clients, mantenendo compatibile l'endpoint storico condomini-managed. Da 1.ST.32 la home introduce un menu moduli piu' professionale e compatto, con moduli attivi e moduli in preparazione. Da 1.ST.33 il download aggiornamento APK apre automaticamente l'installer Android e guida l'utente al permesso installazione se richiesto.

Vincolo Offline

L'offline operativo deve rimanere circoscritto alla compilazione del RAS dinamico in Compila v3.

Fuori dal runtime RAS dinamico, le viste native dell'APK devono essere online-only:

  • lista clienti assegnati al tecnico;
  • lista documenti caricati per cliente;
  • cambio tenant;
  • login e refresh sessione;
  • download aggiornamenti APK;
  • upload, allegati, foto e sync.

Queste viste non devono mantenere cache operativa persistente autonoma. Se la rete non e' validata, devono mostrare un messaggio esplicito e non presentare dati vecchi come se fossero correnti.

Richiedono rete validata:

  • login;
  • selezione tenant;
  • lista RAS assegnati;
  • apertura scheda Compila v3;
  • salvataggio dati;
  • upload foto o allegati;
  • controllo aggiornamenti APK.

Non sono ancora attivi:

  • bozze locali operative con payload;
  • coda foto offline;
  • sync differito;
  • gestione conflitti tra copia locale e server.

Errori Operativi Attesi

  • Login richiesto: la sessione e' scaduta o non presente. Usare Accedi / cambia.
  • Rete non ancora pronta: Android non ha ancora validato la connessione. Se esiste cache locale, viene mostrata in sola lettura.
  • RAS disponibile offline: il RAS e' visibile come metadato/cache, ma non puo' essere aperto o salvato senza rete.
  • Tenant non disponibile: l'utente non ha accesso al tenant richiesto o deve cambiare tenant.
  • Apertura che torna al login: sessione tenant non valida. Rifare login e riaprire il RAS.

Distribuzione Pilota

Distribuire inizialmente a pochi tecnici.

Prima del pilota verificare:

  • tecnico abilitato al portale corretto;
  • tenant visibile nella home APK;
  • lista RAS filtrata sui RAS dinamici;
  • apertura RAS dal tenant corretto;
  • camera e posizione autorizzate sul tablet;
  • ritorno alla home APK con pulsante Home;
  • update APK visibile quando il portale pubblica una versione superiore.

Moduli Tecnico

La home SafeTecnico deve mostrare solo i moduli attivi per utente, tenant e cliente.

Moduli attivi nella fase corrente:

  • RAS dinamici;
  • documenti cliente online.

Moduli pianificati:

  • checklist;
  • rapportini tecnico/IT;
  • ticket/interventi;
  • lavori in altezza;
  • scadenze e attivita' programmate.

Ogni modulo deve dichiarare se e' online-only o se dispone di un contratto offline esplicito. In assenza di contratto offline, il modulo deve restare online-only.

Endpoint contratto clienti:

GET /api/mobile/auth/assigned-clients

L'endpoint ritorna clients, paginazione, online_only e payload modules. L'endpoint storico condomini-managed resta disponibile e ritorna anche condomini per compatibilita'.

Da 1.ST.34 il menu moduli dell'APK viene alimentato dal payload modules dell'endpoint assigned-clients, con fallback locale se l'API non invia moduli.

Da 1.ST.35 il flusso aggiornamento conserva il download APK completato, mostra Installa aggiornamento e riprova l'apertura installer dopo il ritorno dalla schermata permessi Android.

Da 1.ST.36 e' stata pubblicata una build di collaudo per verificare l'aggiornamento in-app da 1.ST.35.

Da 1.ST.37 l'aggiornamento in-app usa PackageInstaller invece dell'apertura diretta del file APK scaricato.

Da 1.ST.38 la home include Help con i passaggi di aggiornamento APK e il chiarimento sulla conferma manuale richiesta da Android.

Da 1.ST.39 il callback PackageInstaller viene ricevuto con receiver esportato, per compatibilita' con dispositivi Android/Samsung che non consegnano il pending user action a receiver non esportati.

Da 1.ST.40 il modulo Rapportini e' attivo online-only e apre la lista rapportini esistente.

Da 1.ST.41 il modulo Rapportini apre un menu nativo con Lista rapportini, Nuovo rapportino e Rapportini periodo.

Da 1.ST.42, se PackageInstaller fallisce, l'app prova automaticamente anche l'apertura ACTION_VIEW del file APK scaricato.

Da 1.ST.43 i moduli web APK, inclusi Rapportini, passano dal tenant-launch mobile prima di aprire la pagina del tenant.

Da 1.ST.44 il modulo Rapportini usa le route tecnico Interventi e rapportini e Rapportini periodo, evitando le view admin intervento-rapportino-admin che non sono abilitate al tecnico.

Da 1.ST.45 il modulo Rapportini carica una lista nativa online-only degli interventi assegnati tramite API mobile e apre direttamente il rapportino del ticket selezionato.

Da 1.ST.46 il modulo Rapportini include Nuovo, con scelta nativa dell'intervento assegnato e apertura del rapportino in modalita' nuova compilazione.

Da 1.ST.47 Nuovo rapportino e' la prima voce della lista nativa Rapportini, per renderlo visibile anche sui tablet dove i pulsanti del dialog sono poco evidenti.

Da 1.ST.48 la lista nativa Rapportini include gli interventi assegnati direttamente al tecnico e quelli collegati ai clienti assegnati al tecnico.

Da 1.ST.48 Nuovo rapportino puo' creare online un intervento per un cliente assegnato e aprire subito il rapportino nuovo.

Da 1.ST.49, se non ci sono interventi, Rapportini apre direttamente la scelta cliente per creare un nuovo rapportino.

Da 1.ST.50 il nuovo rapportino usa un primo form nativo APK online-only per compilare e salvare i campi base prima di aprire il dettaglio web.

Da 1.ST.51 il form nativo puo' salvare bozze rapportino offline dei campi base e sincronizzarle quando torna la rete, usando un identificativo bozza per evitare duplicati.

Da 1.ST.52 il form nativo rapportino e' organizzato in sezioni compatte con campi obbligatori evidenziati e validazione minima prima del salvataggio.

Da 1.ST.53 il rapportino ha una colonna dedicata richiesta_cliente, compilata dal form APK e distinta dall'attivita svolta dal tecnico. Il form usa calendario per la data, orari a step di 15 minuti e dettato Android sui campi descrittivi.

Da 1.ST.54 la home APK e' piu compatta: accesso, moduli, clienti e RAS restano in primo piano; strumenti, stato, ultimo documento e apertura manuale sono raccolti in Avanzate, chiuso di default.

Da 1.ST.55 la selezione portale/tenant e' compressa di default: mostra solo il portale attivo e il numero di portali disponibili, con pulsante Cambia. Le label non espongono piu le chiavi tecniche tenant_....

Da 1.ST.56 la lista Interventi e rapportini usa card native con titolo, cliente, stato, priorita', conteggio rapportini e ultimo aggiornamento, piu' il comando Nuovo rapportino sempre visibile in alto.

Da 1.ST.57 le card Interventi e rapportini includono piu' contesto quando disponibile: tipo richiesta, categoria intervento, ore registrate, ultimo stato/esito rapportino e coda di lavoro.

Da 1.ST.58 il tap su una card Interventi e rapportini apre il form nativo APK precompilato per modificare l'ultimo rapportino disponibile, senza entrare nel template web per la modifica ordinaria.

Da 1.ST.59 il portale attivo viene integrato nel badge Sessione attiva; il blocco portale chiuso non occupa piu' una card dedicata e resta solo il comando Cambia portale.

Da 1.ST.60 il badge Sessione attiva mostra un logo tenant piccolo e non invasivo quando il portale ha un brand_logo_url configurato.

Da 1.ST.61 la modifica nativa rapportino evita i null visibili, mostra scrollbar verticale nei dialog lunghi e risolve il 404 quando il cliente va ricavato da ticket/rapportino.

Da 1.ST.62 il form nativo rapportino ha una finestra scroll ad altezza vincolata e campi disposti in colonna, evitando sormonti in verticale su tablet.

Da 1.ST.63 il form nativo rapportino puo' allegare una immagine online al rapportino salvato, usando storage dedicato intervento_rapportino_allegato.

Da 1.ST.64 il form nativo rapportino puo' scattare foto dall'APK e allegare fino a 4 immagini totali per rapportino.

Da 1.ST.65 lo scatto foto usa un URI MediaStore passato alla fotocamera Android, migliorando apertura e rientro nel form.

Da 1.ST.66 l'APK conserva la foto scattata anche quando la camera rientra con stato annullato ma il file immagine e' stato scritto.

Da 1.ST.67 il form rapportino mostra l'anteprima delle immagini selezionate/scattate e chiarisce che l'upload avviene con Salva e allega.

Da 1.ST.68 nuovo e modifica rapportino restano nel flusso nativo APK; le immagini vengono preparate in cache privata prima dell'upload per ridurre errori da URI temporanei.

Da 1.ST.69 il collaudo APK usa http://10.50.0.200 come base API unica, evitando il gateway pubblico non allineato durante upload immagini rapportino.

Da 1.ST.70 cache, ultimi RAS e documenti sono isolati per utente/tenant; la lista clienti APK richiede fino a 50 clienti assegnati, includendo Docks Cereali nello scope tenant_netopen di roem.

Da 1.ST.71 il form nativo rapportino puo' creare rapportini per piu' giorni consecutivi, la lista Interventi e rapportini mostra l'ultima modifica dell'ultimo rapportino disponibile e il filtro Periodo resta dentro l'APK senza aprire la pagina web.

Da 1.ST.72 i comandi Nuovo e Periodo sono visibili in alto nella lista Interventi e rapportini, evitando il pulsante neutro del dialog Android che su tablet risultava poco evidente. Da 1.ST.73 la home APK mostra un indicatore compatto durante login, cambio portale, caricamento liste, salvataggio rapportino, apertura RAS e download/installazione aggiornamenti. Da 1.ST.74 i comandi Home e Ricarica nel runtime web sono compatti, affiancati e spostati in alto a destra per ridurre l'ingombro verticale.

Evoluzione Desktop

E' segnata come roadmap una futura app desktop Windows, sulla falsa riga SafeTecnico ma non come copia dell'APK.

Obiettivo:

  • esperienza interattiva tra web e app;
  • profilo tecnico;
  • profilo amministratore condominio;
  • riuso delle API mobile/tecnico gia' introdotte;
  • apertura Compila v3 in finestra dedicata quando serve compilare un RAS;
  • gestione piu' comoda di documenti, allegati, download, upload e cartelle locali;
  • nessuna sostituzione del portale web SafeOps.

Separazione prevista:

  • Android: campo, tablet verticale, RAS, foto/GPS, operativita' rapida.
  • Windows: postazione tecnica/amministratore, documenti, allegati, controlli, upload/download, interazione con cartelle locali.
  • Web: runtime principale e amministrazione portale.

La decisione architetturale e' di far convergere APK, desktop e web sulle stesse API e sugli stessi permessi, evitando logiche tenant o autorizzative duplicate nei client.

Rollback

In caso di blocco sul pilota:

  1. Rimuovere SafeTecnico dal tablet.
  2. Usare temporaneamente il browser web del tablet sul portale SafeOps.
  3. Ripubblicare sul portale l'APK precedente se serve rollback applicativo.
  4. Riavviare safeops-web.service e safeops-control-plane.service dopo cambio release backend.

Note Release

La build 1.ST.6 e' firmata con keystore release SafeOps dedicato. Il keystore deve essere conservato: senza la stessa chiave non sara' possibile aggiornare l'app installata sui tablet.