Vai al contenuto

Workflow RAS Mapping Tecnico

Scopo

Mappare il flusso RAS target sulle entita' gia presenti in SafeOps, per capire:

  • cosa esiste gia';
  • cosa va riusato;
  • cosa va introdotto senza rompere il modello attuale.

Questo documento va letto insieme a:

Entita' da Riutilizzare

1. CommercialeRichiestaServizio

Ruolo corretto:

  • ingresso del flusso;
  • contenitore della richiesta amministratore;
  • stato operativo principale lato richiesta;
  • payload dei dati precompilati e completati dal portale;
  • allegati iniziali;
  • log degli eventi.

Campi gia utili:

  • workflow_type
  • stato
  • payload_json
  • attachments_json
  • assigned_agente_id
  • trattativa_id
  • documento_id
  • ticket_id

Uso consigliato:

  • mantenere qui lo stato di avanzamento alto livello della richiesta;
  • non spostare qui la logica di preventivazione dettagliata;
  • usare il record come "contenitore master" del flusso RAS.

2. CommercialeTrattativa

Ruolo corretto:

  • contenitore commerciale;
  • presa in carico commerciale;
  • collegamento a listino, agente e offerta.

Uso consigliato:

  • usarla quando la richiesta passa da richiesta_inviata a in_carico_commerciale;
  • mantenerla come layer commerciale, non come contenitore di documenti firmati o pagamento.

3. CommercialeOfferta

Ruolo corretto:

  • documento commerciale economico;
  • calcolo del prezzo da listino;
  • breakdown economico;
  • eventuale conversione ad attivazione.

Uso consigliato:

  • riusarla come base per il modulo d'ordine;
  • non duplicare un secondo modello economico parallelo.

Nota:

  • oggi e' gia il punto piu vicino al "preventivo/prezzo da listino";
  • il modulo d'ordine va trattato come documento governato prodotto a partire dall'offerta.

4. Documento

Ruolo corretto:

  • repository dei file del flusso;
  • upload/download e versioning;
  • documenti firmati;
  • template renderizzati.

Uso consigliato:

  • usare Documento per:
  • modulo d'ordine inviato al portale;
  • modulo firmato ricaricato dall'amministratore;
  • conferma d'ordine;
  • lettera di incarico;
  • documento tecnico finale firmato dal tecnico.

Nota:

  • non serve un nuovo storage model dedicato al RAS;
  • serve solo classificare bene i documenti e agganciarli alla richiesta giusta.

5. CommercialeTecnicoIncarico

Ruolo corretto:

  • assegnazione tecnica;
  • incarico al tecnico;
  • pubblicazione incarico;
  • perimetro operativo del tecnico.

Uso consigliato:

  • usarlo per il tratto:
  • lettera_incarico_emessa
  • tecnico_assegnato
  • appuntamento_da_fissare
  • intervento_in_esecuzione

Nota:

  • e' gia il modello migliore per l'assegnazione al tecnico;
  • non conviene introdurre un secondo modello "ordine operativo" separato.

Mappa Stato Target -> Entita' Attuale

Stato target Entita' primaria Stato/campo attuale Esito
richiesta_bozza_admin portale/admin form non persistito formalmente da introdurre solo lato UI/sessione
richiesta_inviata CommercialeRichiestaServizio nuova gia coperto
in_carico_commerciale CommercialeRichiestaServizio + CommercialeTrattativa presa_in_carico / trattativa.stato=richiesta|contatto da consolidare
modulo_ordine_generato CommercialeOfferta + Documento nessuno da introdurre
modulo_ordine_inviato Documento nessuno da introdurre
modulo_ordine_firmato_admin Documento + CommercialeRichiestaServizio nessuno da introdurre
modulo_ordine_confermato_commerciale CommercialeRichiestaServizio nessuno da introdurre
in_carico_operativo CommercialeRichiestaServizio in_lavorazione possibile riuso da consolidare
conferma_ordine_generata Documento nessuno da introdurre
inviato_a_fatturazione CommercialeRichiestaServizio nessuno da introdurre
in_attesa_pagamento CommercialeRichiestaServizio nessuno da introdurre
pronto_per_lettera_incarico CommercialeRichiestaServizio nessuno da introdurre
lettera_incarico_emessa Documento + CommercialeTecnicoIncarico parziale tramite incarico da consolidare
tecnico_assegnato CommercialeTecnicoIncarico stato incarico gia parziale
appuntamento_da_fissare CommercialeTecnicoIncarico nessuno esplicito da introdurre
intervento_in_esecuzione CommercialeTecnicoIncarico parziale da consolidare
intervento_completato CommercialeTecnicoIncarico / Documento parziale da consolidare
documento_tecnico_generato Documento gia possibile da governare
documento_tecnico_firmato Documento gia possibile da governare
documento_tecnico_ricaricato Documento gia possibile da governare

Mappa per Blocco di Flusso

Blocco 1. Richiesta Amministratore

Punto di ingresso corretto:

  • ClienteView.request_ras
  • alternativa backoffice da CommercialeAmministratoreClienteView.new_ras_request

Gia coperto:

  • controllo contratto amministratore;
  • risoluzione servizio da listino;
  • prefill dati condominio;
  • raccolta payload e allegati;
  • creazione CommercialeRichiestaServizio;
  • assegnazione commerciale;
  • apertura CommercialeTrattativa per workflow_type = ras_quote.

Da fare:

  • distinguere in modo formale campi:
  • precompilati;
  • richiesti;
  • mancanti;
  • notificare anche la rete oltre al commerciale;
  • formalizzare richiesta_inviata come stato di business e non solo come logica implicita.

Blocco 2. Commerciale e Modulo d'Ordine

Punto corretto:

  • CommercialeRichiestaServizio
  • CommercialeTrattativa
  • CommercialeOfferta

Gia coperto:

  • aggancio a listino;
  • apertura offerta/preventivo RAS;
  • pricing da servizio/listino.

Da fare:

  • generare modulo d'ordine come Documento derivato dall'offerta;
  • segnare quando il documento e' stato:
  • generato;
  • inviato all'amministratore;
  • ricaricato firmato;
  • confermato dal commerciale.

Scelta consigliata:

  • non introdurre un nuovo modello ordine;
  • usare CommercialeOfferta per il contenuto economico;
  • usare Documento per il file firmabile;
  • usare CommercialeRichiestaServizio.stato per il checkpoint di flusso.

Blocco 3. Operativo e Fatturazione

Punto corretto:

  • CommercialeRichiestaServizio come stato master;
  • Documento per conferma d'ordine;
  • integrazione fatturazione come evento/dispatch;
  • CommercialeTecnicoIncarico per l'esecuzione.

Da fare:

  • introdurre stato in_carico_operativo;
  • generare conferma d'ordine;
  • tracciare inviato_a_fatturazione;
  • gestire flag tenant:
  • incarico immediato
  • incarico dopo pagamento

Scelta consigliata:

  • il pagamento non deve vivere in CommercialeTecnicoIncarico;
  • deve vivere come checkpoint sulla richiesta master o su una integrazione dedicata.

Blocco 4. Lettera di Incarico e Tecnico

Punto corretto:

  • CommercialeTecnicoIncarico
  • Documento

Gia coperto:

  • struttura incarico tecnico;
  • perimetro tecnico attivo;
  • pubblicazione incarico.

Da fare:

  • legare formalmente l'incarico alla richiesta RAS;
  • generare lettera di incarico come documento;
  • tracciare:
  • tecnico selezionato;
  • lettera emessa;
  • appuntamento richiesto;
  • intervento avviato;
  • intervento completato.

Stati da Introdurre con Priorita'

Priorita' 1: richiesta/commerciale

Da introdurre su CommercialeRichiestaServizio.stato:

  • richiesta_inviata
  • in_carico_commerciale
  • modulo_ordine_generato
  • modulo_ordine_inviato
  • modulo_ordine_firmato_admin
  • modulo_ordine_confermato_commerciale

Priorita' 2: operativo/fatturazione

  • in_carico_operativo
  • conferma_ordine_generata
  • inviato_a_fatturazione
  • in_attesa_pagamento
  • pronto_per_lettera_incarico

Priorita' 3: tecnico

  • lettera_incarico_emessa
  • tecnico_assegnato
  • appuntamento_da_fissare
  • intervento_in_esecuzione
  • intervento_completato
  • documento_tecnico_generato
  • documento_tecnico_firmato
  • documento_tecnico_ricaricato

Decisioni Tecniche Consigliate

1. Stato master unico

Lo stato principale del flusso deve vivere su CommercialeRichiestaServizio.

Motivo:

  • e' l'entita' che nasce dal portale amministratore;
  • e' gia il contenitore della richiesta;
  • e' il punto piu naturale per dashboard e code operative.

2. Nessun nuovo modello "ordine"

Non conviene introdurre subito una nuova tabella dedicata a:

  • modulo d'ordine;
  • conferma d'ordine;
  • lettera di incarico.

Conviene invece usare:

  • CommercialeOfferta per il lato economico;
  • Documento per i file;
  • metadati/document type per distinguere i documenti del workflow.

3. Payment gate come regola tenant

La biforcazione:

  • incarico subito;
  • incarico dopo pagamento;

va modellata come configurazione tenant, non come logica hardcoded nella view.

4. Audit eventi obbligatorio

Ogni passaggio di stato deve generare log su:

  • CommercialeRichiestaServizioLog
  • piu eventuali note documento/incarico

Questo evita di perdere il filo tra commerciale, operativo e tecnico.

Sequenza di Implementazione Consigliata

  1. consolidare CommercialeRichiestaServizio.stato con i nuovi stati RAS;
  2. agganciare CommercialeOfferta alla generazione del modulo d'ordine;
  3. aggiungere upload/validazione del modulo firmato dall'amministratore;
  4. introdurre in_carico_operativo + conferma d'ordine;
  5. introdurre il gate after_payment;
  6. agganciare CommercialeTecnicoIncarico alla richiesta RAS con lettera di incarico.

Questa e' la sequenza piu prudente:

  • massimizza il riuso del codice esistente;
  • evita nuove tabelle inutili;
  • rende il flusso governabile per step.