Vai al contenuto

RAS Standalone Client Contract

Questo documento definisce il perimetro minimo del client standalone Windows/Android che dovra consumare RAS API v2.

Obiettivo

Consentire a un client standalone di: - autenticarsi su SafeOps - aprire un documento RAS - leggere schema, answers e draft - acquisire lease - salvare risposte - salvare bozza - caricare e visualizzare immagini/blob

La logica business resta in SafeOps. Il client non deve duplicare regole, workflow o storage.

Backend autorevole

SafeOps resta la sorgente di verita per: - tenant - documento - lease - validazioni - draft - answers - media su MinIO

Contratto minimo client

Apertura documento

Sequenza consigliata: 1. GET /api/ras/v2/documents/{document_id}/export 2. GET /api/ras/v2/documents/{document_id}/lease 3. se il client deve modificare: POST /api/ras/v2/documents/{document_id}/lease/acquire

Salvataggio

  • bozza completa/parziale:
  • PUT /api/ras/v2/documents/{document_id}/draft
  • risposte operative:
  • PUT /api/ras/v2/documents/{document_id}/answers

Media

  • upload:
  • POST /api/ras/v2/documents/{document_id}/media
  • resolve url:
  • GET /api/ras/v2/media/{object_key}/url
  • apertura oggetto:
  • GET /api/ras/v2/media/{object_key}

Modello locale consigliato

Il client dovrebbe mantenere solo uno stato locale leggero:

{
  "document_id": 171,
  "lease": {
    "token": "LEASE_TOKEN",
    "expires_at": "2026-03-15T19:29:25Z"
  },
  "schema": {
    "sections": []
  },
  "answers": {},
  "draft": {
    "rev": 3348,
    "payload": {}
  },
  "pending_uploads": [],
  "pending_changes": []
}

Scelte consigliate per i client

Windows

  • consigliato: Tauri
  • motivi:
  • footprint piu leggero di Electron
  • buon accesso filesystem locale
  • facile consumo API HTTP
  • UI moderna con frontend web riusabile

Android

  • consigliato: Flutter oppure React Native
  • se la priorita e il riuso UI web:
  • valutare un WebView solo per MVP interno
  • se la priorita e l’esperienza touch/offline:
  • meglio client nativo o quasi-nativo

Requisiti UX minimi

  • apertura documento
  • vista sezioni
  • modifica campi
  • salvataggio bozza
  • upload immagini
  • visualizzazione immagini
  • gestione conflitto lease
  • stato online/offline

Requisiti offline

Per il primo MVP standalone: - consentire cache locale di schema e draft - non fare ancora sync offline complesso - richiedere connettivita per save definitivo e upload media

Limiti iniziali accettabili

  • niente finalizzazione documento dal client standalone
  • niente stampa/PDF finale
  • niente workflow avanzato
  • niente editor template

Milestone consigliate

M1

  • login
  • open export
  • lease acquire/release
  • edit answers
  • draft save/load

M2

  • upload media
  • preview immagini
  • cache locale minima

M3

  • esperienza tablet migliorata
  • sync piu robusto
  • gestione conflitti e retry

Confine architetturale

  • SafeOps:
  • backend business
  • tenant
  • storage MinIO
  • validazioni

  • workflow

  • Standalone:

  • UX operativa
  • cache locale
  • eventuale lavoro offline limitato

Il client non deve conoscere MinIO direttamente: usa sempre RAS API v2.