Il modello dei dati

L'app Gestione Clienti esiste ed è vuota. Questa tappa le dà le fondamenta: il database dove vivono i record, le tabelle contas, contactos e oportunidades, e il modello che collega tutto — la mappa che le API, le schermate e gli script leggeranno da qui in avanti.

Alla fine di questa pagina hai dati veri: tre tabelle create, collegate fra loro, e una console dove le query restituiscono righe.

#Due strati, e vale la pena non confonderli

Keplin lavora con i dati su due strati sovrapposti. Fanno cose diverse e si toccano in posti diversi:

Strato	Che cos'è	Dove si tocca
Datasource	Il database in sé — la connessione, le tabelle, le colonne, le righe.	Pannello Dati ▸ Origini dati
Modello	Il ritratto di quel database dentro la piattaforma: entità, campi con nomi descrittivi e relazioni.	La scheda del datasource, nel canvas del modello

La distinzione è pratica. Creare una colonna tocca il database. Importare una tabella nel modello non tocca niente nel database — dice soltanto alla piattaforma "questa tabella mi interessa, ed è così che si legge". È il modello ad alimentare l'API GraphQL dell'app, le API di tabella e, attraverso di esse, le schermate.

#Creare il datasource Dados CRM

Il primo passo è registrare il database dell'app. Dato che non collegheremo niente di esterno, usiamo il tipo che la piattaforma crea e conserva insieme all'app: non chiede server, porta, utente né password.

1. Nello spazio di lavoro dell'app, scegli il pannello Dati alla base della barra laterale.

2. Nella sezione Origini dati, clicca sul pulsante + (Nuovo datasource). Si apre la finestra Nuovo datasource — "Collega un database a questa app. Tutto è cifrato a riposo."

3. In Nome interno, scrivi Dados CRM. È con questo nome — esattamente questo — che le API e gli script si riferiranno alla connessione più avanti nella guida.

4. Apri l'elenco Tipo. Mostra tutti i motori supportati; scegli quello del database locale, quello che resta salvato con l'app. Guarda che cosa succede dopo: i campi di server, porta, utente e password scompaiono — non c'è niente da collegare.

   

5. Resta un campo, Importa database (opzionale). Lascialo vuoto: "Senza file, viene creato un database vuoto." È quello che vogliamo.

6. Clicca su Prova connessione per confermare — la risposta è Connessione OK.

7. Clicca su Crea. Il datasource appare nell'albero e la sua scheda si apre subito, con il canvas del modello — ancora vuoto.

#Creare la tabella contas

Con il datasource creato, le tabelle si fanno senza uscire dalla piattaforma.

1. Nell'albero, apri il menu ⋯ del datasource Dados CRM e scegli Nuova tabella.
2. In Nome della tabella, scrivi contas. Lascia Schema (opzionale) in bianco.
3. In Descrizione della tabella, scrivi Aziende clienti e potenziali clienti. È opzionale, ma è quello che leggerai fra un anno.
4. L'elenco Colonne porta già una colonna id, di tipo integer, con Chiave primaria (PK) e Incremento automatico attivi. Lasciala com'è — è l'identità di ogni record.
5. Clicca sul + di Colonne per ogni colonna nuova e compila Nome, Tipo e gli interruttori. La tabella qui sotto dice che cosa scrivere.
6. Conferma con Crea tabella. La tabella nasce nel database e comincia ad apparire nell'albero degli oggetti.

Le colonne della tabella contas:

Colonna	Tipo	Consente NULL	A che cosa serve
id	integer	no	Chiave primaria, con incremento automatico
nome	text	no	Il nome dell'azienda
nif	text	sì	Partita IVA
sector	text	sì	Agroalimentare, Tecnologia, Sanità…
cidade	text	sì	Dove si trova l'azienda
telefone	text	sì	Contatto generale
email	text	sì	Contatto generale
estado	text	no	ativo, prospeto o inativo

#Creare le tabelle contactos e oportunidades

Ripeti il gesto — menu ⋯ del datasource ▸ Nuova tabella — altre due volte.

contactos (descrizione: Persone di contatto di ogni account):

Colonna	Tipo	Consente NULL	A che cosa serve
id	integer	no	Chiave primaria, con incremento automatico
nome	text	no	Nome della persona
cargo	text	sì	Direttore Generale, Responsabile Acquisti…
email	text	sì
telefone	text	sì
conta_id	integer	no	L'account a cui la persona appartiene

oportunidades (descrizione: Affari in corso, per fase):

Colonna	Tipo	Consente NULL	A che cosa serve
id	integer	no	Chiave primaria, con incremento automatico
titulo	text	no	Il nome dell'affare
conta_id	integer	no	L'account dell'affare
valor	real	sì	Valore in euro — numero con decimali
fase	text	no	La fase dell'affare (vedi sotto)
data_fecho	text	sì	Data prevista di chiusura, in AAAA-MM-GG
responsavel	text	sì	Chi segue l'affare

La colonna fase è un elenco chiuso di valori. Si conserva come testo, e i valori possibili sono sempre questi sei:

Valore salvato	Che cosa significa
prospecao	Non c'è ancora stata una conversazione seria
qualificacao	C'è interesse e stiamo capendo se combacia
proposta	Proposta consegnata
negociacao	Si discutono le condizioni
fechada_ganha	Affare chiuso
fechada_perdida	Affare perso

#Rivedere e modificare la struttura di una tabella

Hai sbagliato un tipo, manca una colonna, il nome non è il migliore. Niente di tutto ciò è definitivo:

1. Nell'albero, apri il menu ⋯ della tabella e scegli Modifica struttura.
2. La finestra ha due schede: Colonne e Indici. In alto ci sono il Nome nel DB, il Nome descrittivo (app) — il nome che le schermate mostreranno — e la descrizione.
3. Clicca su una colonna a sinistra per modificarla a destra, o usa il + per aggiungerne una. Le colonne nuove sono contrassegnate "Colonna nuova — viene creata applicando le modifiche"; le colonne eliminate restano "Contrassegnata per l'eliminazione (DROP) all'applicazione", e l'eliminazione si annulla finché non applichi.
4. Clicca su Applica modifiche.

#Vedere e seminare i dati

L'albero degli oggetti ha una console sotto il modello, ed è da lì che si sbirciano (o si seminano) i dati:

1. Apri il menu ⋯ di una tabella e scegli Visualizza dati. La Console SQL si apre in basso, già con un select pronto per quella tabella.
2. Clicca su Esegui. I risultati appaiono a destra, con il numero di righe e un campo Filtra….
3. Per inserire le prime righe, scrivi nella console gli insert che vuoi ed esegui. È il modo più rapido di avere dati di esempio prima che ci siano schermate per crearli.

#Importare le tabelle nel modello

Le tabelle esistono, ma la piattaforma non sa ancora di volerle usare. È quello che fa l'importazione:

1. Nell'albero, espandi Dados CRM ▸ Tabelle. Ci sono tutte e tre.
2. Per ognuna, apri il menu ⋯ e scegli Importa nel modello — oppure trascina la tabella dall'albero al canvas del modello, che è lo stesso.
3. Ogni tabella diventa un cartoncino nel canvas: l'entità. Il cartoncino mostra i campi, il tipo di ciascuno e il segno PK sulla chiave primaria.

I nomi delle entità restano con l'iniziale maiuscola — contas diventa Contas — perché è così che appaiono nelle API e nelle schermate. La tabella nel database continua a chiamarsi contas.

#Collegare le entità — le due relazioni

Un CRM senza relazioni è tre elenchi scollegati. Mancano due collegamenti: ogni contatto appartiene a un account, ogni opportunità appartiene a un account.

Per creare una relazione, trascina il campo conta_id dell'entità Contactos sul campo id dell'entità Contas — il suggerimento sul cartoncino lo ricorda: "Trascina su un campo di un'altra tabella per collegare". Si apre la finestra Nuova relazione, già con le entità e le colonne compilate:

Campo	Che cosa scegliere	Perché
Cardinalità	Uno a molti (1:N)	Un account ha molti contatti; ogni contatto ha un account.
Parent (referenziata)	Contas ▸ id	Il lato "uno".
Child (ha la FK)	Contactos ▸ conta_id	Il lato "molti" — è lui a conservare il riferimento.
Tipo di relazione	Fisica — crea la FK nel database	Il database si prende l'incarico di garantire che non ci siano contatti orfani.
Navigator su Contactos → Contas	conta	Il campo virtuale che, a partire da un contatto, dà il suo account.
Navigator su Contas → Contactos	contactos	Il campo virtuale che, a partire da un account, dà i suoi contatti.
Quando si elimina il padre (ON DELETE)	Niente (blocca se ci sono figli)	Eliminare un account con contatti viene rifiutato — meglio un errore che un buco.

Conferma con Crea relazione e ripeti il gesto fra Oportunidades ▸ conta_id e Contas ▸ id, con il navigator inverso oportunidades.

I navigator sono la parte che rende di più. Sono campi che non esistono nel database ma esistono nel modello: con loro, una query sulle opportunità restituisce conta.nome senza che nessuno scriva un join. È esattamente questo che farà la tabella della dashboard nella tappa successiva, nella colonna Conta.

#Che cosa si è sbloccato

Con il modello pronto, l'app ha guadagnato cose gratis:

• L'API GraphQL dell'app conosce già Contas, Contactos e Oportunidades, con le relazioni — vedi L'API GraphQL del modello.
• Le API di tabella possono ora puntare a un'entità e generare lettura e scrittura senza una riga di SQL. È il primo passo della tappa successiva.
• Le schermate leggeranno da queste API attraverso i datastore.

#Perché non…?

• Perché non appare la mia tabella nell'albero? L'albero degli oggetti viene letto dal database — usa Aggiorna oggetti nel menu ⋯ del datasource dopo aver messo le mani fuori dalla piattaforma.
• Perché non riesco a creare la relazione? Le due colonne devono essere compatibili: una chiave primaria integer si collega a un integer. Se hai trascinato sul campo sbagliato, annulla e ripeti — la finestra dice che manca la scelta delle colonne.
• Perché il campo conta non appare nei miei dati? I navigator non sono colonne: esistono solo attraverso il modello. Se stai facendo query dalla Console SQL vedi le colonne reali; è nelle API e nelle schermate che i navigator appaiono.
• Perché la piattaforma non mi lascia eliminare un account? Hai scelto Niente (blocca se ci sono figli) nell'ON DELETE — e ci sono contatti o opportunità che puntano a lui. Eliminali prima, oppure cambia la regola della relazione.

Le fondamenta sono fatte. Prossima tappa: le schermate.