Skip to main content

Contratti

🚧 BOZZA

I contratti rappresentano contratti effettivi generati a partire da contratti template.

🤔 Dubbi/Cose nuove da considerare​

  • Capire come gestire il riversamento delle variabili verso le anagrafiche.
  • Capire come mostrare le variabili che sono allegati da mostrare nel contratto.

🧠 Concetti chiave​

I contratti rappresentano contratti effettivi generati a partire da contratti template.

Ogni contratto è composto da titolo, nome progetto, tipo di firma, stato, firmatari, variabili, corpo del contratto e allegati:

  • Il titolo è il nome identificativo del contratto.
  • Il nome progetto è il nome del progetto/commessa a cui è associato il contratto.
  • Il tipo di firma definisce la modalità di firma del contratto (digitale o manoscritta).
  • Lo stato indica lo stato corrente del contratto (da firmare, in attesa, firmato, fallito).
  • I firmatari sono i soggetti che devono firmare il contratto. Ogni firmatario ha come dati di riferimento:
    • nome: nome del firmatario
    • cognome: cognome del firmatario
    • email: email del firmatario
    • telefono: numero di telefono del firmatario
    • tipo: tipologia del firmatario (cliente, fornitore, impresa, professionista, ecc.)
    • entità correlata: riferimento all'entità del sistema (User o Company) associata al firmatario
    • data firma: timestamp di quando il firmatario ha firmato il contratto
  • Le variabili sono campi dinamici utilizzati nel corpo del contratto. Le variabili sono ereditate dal contratto template e cristallizzate al momento della creazione. Ogni variabile ha:
    • categoria: indica la provenienza/tipologia della variabile (core, project, customer, company, ecc.)
    • tipo: tipo di input della variabile (text, email, date, fiscal_code, ecc.)
    • valore: il valore effettivo della variabile per il contratto specifico
  • Il corpo del contratto è il testo del contratto, che può essere modificato utilizzando un editor WYSIWYG. Esiste anche un corpo computato (computed_body) che è il corpo con le variabili sostituite dai loro valori.
  • Gli allegati sono i file associati al contratto (documenti firmati, non firmati, allegati vari).

In piattaforma è possibile creare e modificare i contratti effettivi, selezionando il contratto template da cui generare il contratto effettivo e modificando il corpo del contratto utilizzando un editor WYSIWYG:

  • All'interno del contratto è possibile utilizzare una toolbar completa con opzioni di formattazione e richiamare le variabili associate al contratto utilizzando il simbolo @.
  • Le variabili vengono gestite in modo diverso in base alla loro categoria:
    • Variabili CORE: Sono variabili di sistema (categoria core) il cui valore viene fornito automaticamente dal modulo core al momento della creazione del contratto. Queste variabili contengono dati fondamentali del sistema e non sono modificabili manualmente dall'utente che gestisce il contratto.
    • Variabili UTENTE: Sono tutte le altre variabili (categorie come project, customer, company, professional, attachments, ecc.) che possono essere precompilate dal modulo core ma sono modificabili dall'utente che gestisce il contratto. L'utente può completare o modificare il contenuto di queste variabili prima dell'invio in firma.
  • I firmatari sono precompilati con i dati passati dal modulo core, ma è possibile modificare i dati dei firmatari a cui inviare il contratto.
  • V2: È possibile riversare le variabili selezionate nel contratto effettivo verso le anagrafiche legate alle variabili stesse.

Una volta compilato il contratto effettivo e verificati i dati dei firmatari, è possibile mandare in firma il contratto. A quel punto il contratto passa allo stato "In attesa" e viene inviato ai firmatari tramite il sistema di firma digitale.

Logiche rilevanti
  • Le variabili disponibili per il contratto sono quelle presenti nel template, cristallizzate al momento della creazione del contratto effettivo. Se successivamente il template viene modificato, le variabili disponibili per il contratto effettivo non vengono aggiornate automaticamente.
  • Alla creazione del contratto effettivo, i dati delle variabili sono precompilati con i dati passati dal modulo core. Nel caso in cui i dati delle anagrafiche cambiano, il cambiamento non verrà riflesso nel contratto effettivo.
  • La logica di estrazione/lettura dei dati necessari per precompilare le variabili risiede nel modulo core, il modulo contratti è all'oscuro di questa logica.
  • Le variabili di categoria CORE sono read-only per l'utente che gestisce il contratto, mentre le altre categorie sono modificabili.
  • Il corpo computato (computed_body) viene generato al momento della richiesta sostituendo i placeholder delle variabili (es. @nome_variabile) con i valori effettivi salvati in contract_variables.value.
  • Quando un contratto viene resettato, vengono salvati i campi reset_at (timestamp) e reset_by (user che ha effettuato il reset), e lo stato torna a "Da firmare".
  • Se un contratto viene rifiutato, viene salvato il campo refused_at e lo stato passa a "Fallito".
  • V2: Una volta modificati i dati delle variabili, è possibile riversare i dati delle variabili selezionate nelle anagrafiche legate alle variabili stesse.

⚙️ Logiche sotto il cofano​

Entità coinvolte​

Le entità strettamente coinvolte nei contratti sono:

  • contracts: in questa entità vengono salvati i contratti effettivi. I campi principali sono:
    • contract_template_id: riferimento al template da cui è stato generato
    • name: titolo del contratto
    • project_name: nome del progetto/commessa associato
    • signature_type: tipo di firma (digital/handwritten)
    • status: stato del contratto (to_sign/awaiting/signed/failed)
    • body: corpo del contratto con placeholder delle variabili
    • signed_at: timestamp di quando il contratto è stato firmato
    • reset_at: timestamp di quando il contratto è stato resettato
    • reset_by: user_id di chi ha resettato il contratto
    • refused_at: timestamp di quando il contratto è stato rifiutato
  • contract_variables: in questa entità vengono salvate le variabili associate al contratto. I dati importanti salvati in questa entità sono:
    • contract_id: id del contratto legato alla variabile
    • name: nome della variabile
    • slug: slug identificativo della variabile
    • category: categoria della variabile (core, project, customer, company, ecc.)
    • type: tipo di input della variabile (text, email, date, fiscal_code, ecc.)
    • value: valore effettivo della variabile per il contratto
    • placeholder: testo di esempio per la variabile
  • contract_signatories: in questa entità vengono salvati i firmatari associati al contratto. I campi principali sono:
    • contract_id: id del contratto
    • name: nome del firmatario
    • surname: cognome del firmatario
    • email: email del firmatario
    • phone_number: telefono del firmatario
    • type: tipologia del firmatario (customer, platform, company, supplier, district_manager, local_manager, hd, subcontractor, professional)
    • signed_at: timestamp di quando ha firmato
  • contract_signatory_related_entities: in questa entità viene salvata la relazione tra firmatari e entità del sistema (User o Company). Usa una relazione polimorfica con:
    • contract_signatory_id: id del firmatario
    • entity_id: id dell'entità correlata
    • entity_type: tipo dell'entità (User o Company)

Generazione del contratto effettivo​

La generazione del contratto effettivo prevede la creazione di un contratto a partire da un contratto template. Il contratto viene precompilato con i dati (titolo, firmatari, variabili, corpo del contratto) del contratto template. Le variabili del contratto sono precompilate con i dati che vengono passati dal modulo core. Ogni modifica del valore della variabile nel contratto effettivo non modifica il valore del dato nelle anagrafiche legate alla variabile stessa.

Il processo di generazione:

  1. Viene selezionato un contratto template
  2. Le variabili del template vengono cristallizzate nel contratto effettivo
  3. Il modulo core fornisce i valori per le variabili (in particolare quelle di categoria core)
  4. Vengono creati i record in contract_variables con i valori iniziali
  5. Vengono creati i firmatari in contract_signatories con i dati passati dal modulo core
  6. Il corpo del contratto viene salvato con i placeholder delle variabili (es. @nome_variabile)

Replace delle variabili e corpo computato​

Il corpo computato (computed_body) è una versione del corpo del contratto in cui tutti i placeholder delle variabili sono stati sostituiti con i valori effettivi.

Il processo di sostituzione funziona così:

  1. Si parte dal campo body che contiene il corpo con placeholder (es. @customer_name, @project_address)
  2. Per ogni variabile in contract_variables:
    • Si cerca il placeholder corrispondente allo slug della variabile
    • Si sostituisce il placeholder con il value della variabile
  3. Il risultato è il corpo computato con tutti i valori effettivi

Gestione delle variabili per categoria:

  • Variabili CORE (categoria core):

    • Vengono popolate automaticamente dal modulo core durante la creazione del contratto
    • Contengono dati di sistema fondamentali
    • Sono read-only per l'utente che gestisce il contratto
    • Non possono essere modificate manualmente attraverso l'interfaccia utente

  • Variabili UTENTE (tutte le altre categorie: project, customer, company, professional, supplier, attachments, date, signatures, ecc.):

    • Possono essere precompilate dal modulo core con dati delle anagrafiche
    • Sono modificabili dall'utente che gestisce il contratto
    • L'utente può completare campi vuoti o correggere valori esistenti
    • Le modifiche sono salvate nel campo value di contract_variables
Esempio di flusso
  1. Il modulo core crea un contratto per una commessa
  2. Passa le variabili CORE (es. @platform_name, @platform_vat) con valori fissi
  3. Passa alcune variabili UTENTE precompilate (es. @customer_name = "Mario Rossi")
  4. L'utente che gestisce il contratto può:
    • Visualizzare le variabili CORE ma non modificarle
    • Modificare @customer_name se necessario
    • Compilare variabili vuote come @customer_fiscal_code
  5. Quando richiede l'anteprima, vede il computed_body con tutti i valori sostituiti
  6. Quando manda in firma, il PDF viene generato usando il computed_body

Salvataggio dei dati nelle anagrafiche​

V2: DA APPROFONDIRE - Possibile funzionalità futura per riversare i dati modificati nelle variabili verso le anagrafiche del sistema.