Modulo Tecnico Monitor RAS V1¶

Obiettivo: introdurre un modulo tecnico semplice e leggibile per verificare lo stato reale delle pratiche RAS, evidenziare incoerenze di workflow e consentire riallineamenti sicuri solo agli utenti autorizzati.

Perche serve¶

Nel flusso RAS le informazioni operative sono distribuite tra piu oggetti:

commerciale_richiesta_servizio
commerciale_trattativa
commerciale_offerta
documento preventivo/modulo ordine
documento firmato
ticket
documento RAS tecnico
draft/libretto/finale del compila

Questo rende difficile capire rapidamente se una pratica e:

coerente
bloccata
chiusa solo commercialmente
chiusa anche operativamente
consegnabile

La V1 del modulo non deve sostituire i flussi esistenti. Deve essere una vista unica di controllo e riallineamento.

Nome Proposto¶

menu: Monitor RAS
route base: /commerciale-ras-monitor
view class proposta: CommercialeRasMonitorView

Target Utenti¶

ids_extra: read/write
extra: read-only

Vincolo operativo:

gli utenti extra possono aprire la pratica, leggere timeline, documenti e warning
gli utenti ids_extra possono anche eseguire azioni di riallineamento esplicite

Implementazione suggerita:

menu protetto con lo stesso criterio ids_extra_only gia presente in app/init.py
permesso vista separato per show/list
permesso azioni mutative separato, assegnato solo a ids_extra

Scope V1¶

La V1 deve coprire solo il monitoraggio e 5 azioni correttive sicure.

In scope¶

lista pratiche RAS con semaforo stato
dettaglio pratica con timeline fasi
diagnostica incoerenze
collegamenti rapidi ai documenti principali
azioni manuali sicure con audit

Out of scope¶

editor completo della pratica
modifica libera di importi o dati commerciali
modifica libera del compila tecnico
automazioni massive multi-pratica
wizard di chiusura completo

Modello Logico Della Pratica¶

Ogni riga del monitor deve essere una pratica RAS aggregata per trattativa o cliente, con risoluzione del record piu recente per:

richiesta RAS
offerta
documento preventivo/modulo ordine
documento firmato
ticket
documento RAS tecnico
output libretto/finale se presenti

Chiave raccomandata V1:

pivot principale: commerciale_trattativa.id

Motivo:

e il punto in cui si agganciano offerta, richiesta e cliente
permette di vedere subito duplicazioni offerta sulla stessa trattativa

Lista Monitor¶

Campi minimi:

trattativa_id
cliente
offerta_id
richiesta_id
service_code
stato aggregato
fase corrente
warning_count
updated_at

Filtri minimi:

cliente
trattativa_id
offerta_id
richiesta_id
stato aggregato
solo incoerenti
solo bloccate
solo chiudibili

Semaforo raccomandato:

verde: pratica coerente nel punto in cui si trova
giallo: pratica coerente ma incompleta
rosso: pratica incoerente o bloccata

Dettaglio Pratica¶

Il dettaglio deve essere leggibile in verticale, con blocchi chiari.

1. Testata¶

cliente
indirizzo
trattativa
offerta
richiesta
ticket
documento RAS tecnico

2. Timeline Workflow¶

Step minimi:

richiesta creata
trattativa aperta
offerta creata
modulo ordine/preventivo generato
modulo ordine inviato
firmato caricato
offerta accettata
ticket creato
incarico tecnico / documento RAS aperto
compila avviato
libretto generato
finale generato
firmato finale caricato
consegna completata

Ogni step deve mostrare:

stato: ok, missing, incoerente, non applicabile
data/ora ultimo evento
id oggetto collegato
eventuale link Apri

3. Diagnostica¶

La diagnostica deve essere la parte centrale della vista.

Categorie:

commerciale
documentale
tecnico
finalizzazione

Warning minimi V1:

firmato presente ma offerta in bozza
firmato presente ma offerta senza documento_id
trattativa chiusa_vinta con offerta non accettata
offerta accettata senza firmato
offerta con documento_id ma trattativa senza preventivo_documento_id
offerta collegata a trattativa senza richiesta RAS
richiesta RAS in modulo_ordine_generato senza offerta
ticket presente ma offerta non accettata
compila presente ma richiesta commerciale assente
finale presente ma pratica non in stato coerente

Ogni warning deve avere:

codice
messaggio leggibile
severita high|medium|low
azione suggerita

4. Documenti¶

Sezione documenti con link rapidi:

preventivo/modulo ordine
firmato commerciale
contratto se presente
ticket
compila RAS
libretto DOCX/PDF
finale PDF

5. Azioni¶

Le azioni vanno mostrate solo a ids_extra.

Azioni Mutative V1¶

Solo azioni esplicite, atomiche e auditabili.

1. Riallinea Documento Offerta¶

Uso:

quando la trattativa ha preventivo_documento_id ma l’offerta ha documento_id nullo

Effetto:

copia trattativa.preventivo_documento_id su offerta.documento_id

2. Marca Offerta Accettata¶

Uso:

quando esiste signed_documento_id reale ma l’offerta e ancora bozza o inviata

Effetto:

imposta offerta.stato = accettata

Vincolo:

disponibile solo se esiste signed_documento_id

3. Chiudi Trattativa Come Vinta¶

Uso:

quando l’offerta e accettata ma la trattativa e ferma a offerta

Effetto:

imposta trattativa.stato = chiusa_vinta

4. Aggancia Richiesta RAS A Trattativa¶

Uso:

quando esiste richiesta RAS del cliente ma non e agganciata alla trattativa corretta

Effetto:

valorizza richiesta.trattativa_id

Vincolo:

richiede selezione esplicita della richiesta candidata

5. Rigenera/Riallinea Modulo Ordine¶

Uso:

quando il documento commerciale esiste ma i link sono incoerenti

Effetto:

richiama la logica di _ensure_richiesta_order_document(...) o _ensure_trattativa_preventivo_document(...)

Vincolo:

preferire riuso della logica applicativa esistente, non query SQL grezze

Azioni Non Ammesse In V1¶

cancellare ticket
cancellare documenti
cambiare importi
cambiare cliente
cambiare firmato su storage
forzare chiusura tecnica finale

Audit¶

Ogni azione mutativa deve produrre audit esplicito.

Campi minimi:

user_id
username
tenant_key
action_code
target_type
target_id
before_json
after_json
note
created_at

Soluzione consigliata V1:

riuso di un audit log esistente se gia disponibile
altrimenti tabella dedicata tipo commerciale_ras_monitor_audit_log

Algoritmo Stato Aggregato¶

La pratica deve esporre un solo stato sintetico.

Proposta V1:

NUOVA
richiesta presente, niente offerta
OFFERTA
offerta presente, niente firmato
FIRMATO_DA_RIALINEARE
firmato presente ma offerta/trattativa incoerenti
ACCETTATA
offerta accettata, nessun ticket/operativo
OPERATIVA
ticket o presa in carico tecnica esistente
IN_COMPILA
documento RAS aperto / draft presente
IN_FINALIZZAZIONE
libretto/finale in corso
CHIUSA
fascicolo finale coerente e consegna completata
BLOCCATA
warning severi incompatibili col passo successivo

Query/Resolver Raccomandati¶

Resolver principali:

latest_offerta_for_trattativa(trattativa_id)
latest_richiesta_ras_for_trattativa(trattativa_id)
current_signed_document_for_offerta(offerta_id)
current_preventivo_for_trattativa(trattativa_id)
current_ras_doc_for_cliente(cliente_id)
current_final_pdf_for_ras(documento_id)

Regola:

la vista non deve dedurre lo stato da un solo record
deve aggregare i record principali e poi calcolare status, phase, warnings

UI V1¶

UI semplice, leggibile, non tecnica per eccesso.

Pattern raccomandato:

lista con semaforo
dettaglio con:
header compatto
timeline verticale
box warning
box documenti
box azioni

No in V1:

dashboard grafici
kanban
flowchart interattivi

Criteri Di Accettazione¶

La V1 e accettata se permette di:

aprire una pratica e capire in meno di 30 secondi dove si e fermata
distinguere subito dato mancante da incoerenza
correggere in sicurezza i casi piu comuni senza query SQL manuali
vedere audit di ogni correzione

Casi Reali Da Usare In Collaudo¶

Usare almeno questi casi:

offerta con firmato ma bozza
offerta con documento_id nullo ma preventivo_documento_id presente
trattativa con offerta duplicata
richiesta RAS senza trattativa agganciata
pratica tecnica con compila aperto ma commerciale incoerente

Casi gia emersi utili per collaudo iniziale:

#72 Condominio Gardenia
#70 Condominio Primula C

Piano Implementativo V1¶

Step 1¶

introdurre resolver aggregato pratica RAS
introdurre view list/show
introdurre calcolo warning

Step 2¶

introdurre permessi ids_extra write / extra read
introdurre audit log

Step 3¶

introdurre 5 azioni mutative V1
bloccare le azioni se i pre-requisiti non sono soddisfatti

Step 4¶

collaudo su casi reali incoerenti
verifica audit
verifica visibilita menu e permessi

Decisione Raccomandata¶

Procedere con questo modulo in V1.

Motivo:

abbassa il costo di diagnosi
riduce interventi manuali su DB
rende controllabile il flusso RAS end-to-end
separa bene lettura da correzione operativa