Ciclo di vita delle offerte e macchina a stati

Ogni offerta in QuoteNode segue un lifecycle rigoroso e validato. Il sistema consente solo transizioni valide e rifiuta qualsiasi tentativo di portare un’offerta in uno stato non ammesso.

Definizioni di stato

Stato	Descrizione	Modificabile	Terminale
DRAFT	L’offerta e in preparazione. Non ancora visibile al cliente.	Si	No
SENT	L’offerta e stata consegnata al cliente via email o link pubblico.	No	No
OPENED	Il cliente ha aperto il link pubblico almeno una volta.	No	No
NEGOTIATION	Il cliente ha inviato una domanda o controproposta.	No	No
ACCEPTED	Il cliente ha confermato l’ordine.	No	Si
REJECTED	Il cliente ha rifiutato l’offerta.	No	Si
EXPIRED	Il periodo di validita e scaduto senza decisione.	No	Si
ARCHIVED	Archiviata manualmente dal commerciale.	No	Si

Regole di transizione

DRAFT ──────────► SENT
  │                 │
  │                 ▼
  │              OPENED
  │                 │
  │                 ├──► NEGOTIATION
  │                 │        │
  │                 ├──► ACCEPTED (terminal)
  │                 ├──► REJECTED (terminal)
  │                 └──► EXPIRED  (terminal)
  │
  └──► ARCHIVED (terminal)

Transizioni valide

• DRAFT → SENT - quando il commerciale invia l’offerta o genera un link pubblico
• SENT → OPENED - quando il cliente apre il link pubblico per la prima volta
• OPENED → NEGOTIATION - quando il cliente invia una risposta
• OPENED → ACCEPTED - quando il cliente fa clic su Accept
• OPENED → REJECTED - quando il cliente fa clic su Decline
• SENT/OPENED/NEGOTIATION → EXPIRED - quando scade valid_until
• DRAFT → ARCHIVED - quando il commerciale archivia una bozza mai inviata
• NEGOTIATION → ACCEPTED - quando il cliente accetta dopo una fase di trattativa
• NEGOTIATION → REJECTED - quando il cliente rifiuta dopo la trattativa

Transizioni non valide

• SENT → DRAFT
• ACCEPTED → qualsiasi altro stato
• REJECTED → qualsiasi altro stato
• EXPIRED → qualsiasi altro stato
• ARCHIVED → qualsiasi altro stato

Cosa succede a ogni transizione

DRAFT → SENT

1. Il sistema valida che l’offerta contenga almeno una riga
2. Viene creato uno snapshot immutabile in JSON con lo stato completo dell’offerta
3. Se l’invio e via email, viene accodata una mail con PDF e/o link pubblico
4. Se viene generato un link pubblico, si crea un token casuale a 256 bit e si memorizza solo l’hash SHA-256
5. Lo stato cambia in SENT
6. Viene registrato un evento nella timeline cliente
7. Viene scritta una voce nell’audit log

SENT → OPENED

1. Il cliente accede all’URL pubblica
2. L’hash del token viene verificato nel database
3. Lo stato passa a OPENED solo alla prima visualizzazione
4. Viene registrato l’evento web con timestamp, IP, user agent e paese GeoIP
5. Il commerciale riceve una notifica se configurata

OPENED → ACCEPTED

1. Il cliente fa clic su Accept nella pagina pubblica
2. Vengono verificati rate limiting e bot detection
3. Possono essere raccolti dati opzionali di order intent
4. Lo stato passa a ACCEPTED
5. Il commerciale riceve una notifica immediata
6. L’evento viene registrato in timeline

Snapshot

Uno snapshot e un record completo e immutabile dell’offerta al momento dell’invio:

• dati cliente
• tutte le righe con prodotti, quantita, prezzi, sconti e aliquote IVA
• totali calcolati, inclusi spedizione e breakdown IVA
• tasso di cambio utilizzato
• configurazione branding
• impostazioni template

Gli snapshot non vengono mai modificati. Se un’offerta viene reinviata dopo modifiche, viene creata una nuova versione di snapshot con numero incrementale.

I PDF vengono sempre generati dagli snapshot, mai dai dati live. Questo garantisce che il PDF corrisponda esattamente a quanto visto dal cliente.

Audit trail

Ogni transizione di stato scrive una voce immutabile nell’audit log con utente o sistema attore, IP di origine, stato precedente, stato successivo, timestamp e commento opzionale.

Operazioni dopo stati terminali

Le offerte terminali come ACCEPTED, REJECTED, EXPIRED e ARCHIVED non sono modificabili, ma possono essere riusate come base per nuove offerte tramite clone, estensione validita, aggiornamento prezzi o uso come template.