Het gegevensmodel

De app Klantenbeheer bestaat en is leeg. Deze etappe geeft haar het fundament: de database waarin de records leven, de tabellen contas, contactos en oportunidades, en het model dat alles verbindt — de kaart die de API's, de schermen en de scripts vanaf nu gaan lezen.

Aan het einde van deze pagina hebt u echte gegevens: drie tabellen aangemaakt, aan elkaar gekoppeld, en een console waarin de query's rijen teruggeven.

#Twee lagen, en het loont om ze niet te verwarren

Keplin werkt met gegevens in twee lagen over elkaar. Zij doen verschillende dingen en worden op verschillende plekken aangeraakt:

Laag	Wat het is	Waar u eraan werkt
Datasource	De database zelf — de verbinding, de tabellen, de kolommen, de rijen.	Paneel Data ▸ Datasources
Model	Het portret van die database binnen het platform: entiteiten, velden met weergavenamen en relaties.	Het tabblad van de datasource, op het canvas van het model

Het onderscheid is praktisch. Een kolom aanmaken raakt de database aan. Een tabel naar het model importeren raakt niets aan in de database — het zegt het platform alleen "deze tabel interesseert mij, en zo wordt zij gelezen". Het is het model dat de GraphQL-API van de app voedt, de tabel-API's en, via die, de schermen.

#De datasource Dados CRM aanmaken

De eerste stap is de database van de app vastleggen. Omdat we niets externs gaan koppelen, gebruiken we het type dat het platform samen met de app zelf aanmaakt en bewaart: het vraagt geen server, poort, gebruiker of wachtwoord.

1. Kies in de werkruimte van de app het paneel Data onderaan de zijbalk.

2. Klik in de sectie Datasources op de knop + (Nieuwe datasource). Het dialoogvenster Nieuwe datasource opent — "Verbind een database met deze app. Alles wordt versleuteld opgeslagen."

3. Schrijf bij Interne naam Dados CRM. Onder deze naam — precies deze — zullen de API's en de scripts verderop in de handleiding naar de verbinding verwijzen.

4. Open de lijst Type. Zij toont alle ondersteunde engines; kies die van de lokale database, die samen met de app wordt bewaard. Let op wat er daarna gebeurt: de velden voor server, poort, gebruiker en wachtwoord verdwijnen — er valt niets te verbinden.

   

5. Er blijft één veld over, Database importeren (optioneel). Laat het leeg: "Zonder bestand wordt er een lege database aangemaakt." Dat is wat we willen.

6. Klik op Verbinding testen om het te bevestigen — het antwoord is Verbinding OK.

7. Klik op Aanmaken. De datasource verschijnt in de boom en haar tabblad opent meteen, met het canvas van het model — nog leeg.

#De tabel contas aanmaken

Met de datasource aangemaakt maakt u de tabellen zonder het platform te verlaten.

1. Open in de boom het menu ⋯ van de datasource Dados CRM en kies Nieuwe tabel.
2. Schrijf bij Naam van de tabel contas. Laat Schema (optioneel) leeg.
3. Schrijf bij Beschrijving van de tabel Klanten en potentiële klanten. Het is optioneel, maar het is wat u over een jaar gaat lezen.
4. De lijst Kolommen bevat al een kolom id, van het type integer, met Primaire sleutel (PK) en Auto-increment aan. Laat haar zoals zij is — zij is de identiteit van elk record.
5. Klik op de + van Kolommen voor elke nieuwe kolom en vul Naam, Type en de schakelaars in. De tabel hieronder zegt wat u moet schrijven.
6. Bevestig met Tabel aanmaken. De tabel wordt in de database geboren en verschijnt voortaan in de objectenboom.

De kolommen van de tabel contas:

Kolom	Type	NULL toegestaan	Waarvoor zij dient
id	integer	nee	Primaire sleutel, met auto-increment
nome	text	nee	De naam van het bedrijf
nif	text	ja	Btw-nummer
sector	text	ja	Agrovoeding, Technologie, Zorg…
cidade	text	ja	Waar het bedrijf zit
telefone	text	ja	Algemeen contact
email	text	ja	Algemeen contact
estado	text	nee	ativo, prospeto of inativo

#De tabellen contactos en oportunidades aanmaken

Herhaal het gebaar — menu ⋯ van de datasource ▸ Nieuwe tabel — nog twee keer.

contactos (beschrijving: Contactpersonen van elke account):

Kolom	Type	NULL toegestaan	Waarvoor zij dient
id	integer	nee	Primaire sleutel, met auto-increment
nome	text	nee	Naam van de persoon
cargo	text	ja	Algemeen directeur, Inkoopverantwoordelijke…
email	text	ja
telefone	text	ja
conta_id	integer	nee	De account waar de persoon bij hoort

oportunidades (beschrijving: Lopende deals, per fase):

Kolom	Type	NULL toegestaan	Waarvoor zij dient
id	integer	nee	Primaire sleutel, met auto-increment
titulo	text	nee	De naam van de deal
conta_id	integer	nee	De account van de deal
valor	real	ja	Waarde in euro's — getal met decimalen
fase	text	nee	De fase van de deal (zie hieronder)
data_fecho	text	ja	Verwachte sluitingsdatum, in JJJJ-MM-DD
responsavel	text	ja	Wie de deal opvolgt

De kolom fase is een gesloten lijst van waarden. Zij wordt als tekst opgeslagen, en de mogelijke waarden zijn altijd deze zes:

Opgeslagen waarde	Wat zij betekent
prospecao	Er is nog geen echt gesprek geweest
qualificacao	Er is interesse en we onderzoeken of het past
proposta	Voorstel afgeleverd
negociacao	Voorwaarden worden besproken
fechada_ganha	Deal gesloten
fechada_perdida	Deal verloren

#De structuur van een tabel nazien en wijzigen

U hebt een type verkeerd gekozen, er ontbrak een kolom, de naam is niet de beste. Niets daarvan is definitief:

1. Open in de boom het menu ⋯ van de tabel en kies Structuur bewerken.
2. Het dialoogvenster heeft twee tabbladen: Kolommen en Indexen. Bovenaan staan de Naam in de database, de Weergavenaam (apps) — de naam die de schermen gaan tonen — en de beschrijving.
3. Klik links op een kolom om haar rechts te bewerken, of gebruik de + om er een toe te voegen. Nieuwe kolommen worden gemarkeerd met "Nieuwe kolom — wordt aangemaakt zodra de wijzigingen worden toegepast"; verwijderde kolommen krijgen "Gemarkeerd om te verwijderen (DROP) bij toepassen", en de verwijdering kan ongedaan worden gemaakt zolang u niet toepast.
4. Klik op Wijzigingen toepassen.

#De gegevens bekijken en zaaien

De objectenboom heeft een console onder het model, en daarmee gluurt u naar de gegevens (of zaait u ze):

1. Open het menu ⋯ van een tabel en kies Gegevens bekijken. De SQL-console opent onderaan, al met een select klaar voor die tabel.
2. Klik op Uitvoeren. De resultaten verschijnen rechts, met het aantal rijen en een veld Filteren….
3. Om de eerste rijen erin te zetten, schrijft u de insert-opdrachten die u wilt in de console en voert u ze uit. Het is de snelste manier om voorbeeldgegevens te hebben voordat er schermen zijn om ze aan te maken.

#De tabellen naar het model importeren

De tabellen bestaan, maar het platform weet nog niet dat het ze wil gebruiken. Dat is wat het importeren doet:

1. Klap in de boom Dados CRM ▸ Tabellen uit. Alle drie staan er.
2. Open voor elk van hen het menu ⋯ en kies Naar model importeren — of sleep de tabel uit de boom naar het canvas van het model, wat op hetzelfde neerkomt.
3. Elke tabel wordt een kaart op het canvas: de entiteit. De kaart toont de velden, het type van elk veld en de markering PK op de primaire sleutel.

De namen van de entiteiten krijgen een hoofdletter — contas wordt Contas — omdat zij zo in de API's en op de schermen verschijnen. De tabel in de database blijft contas heten.

#De entiteiten koppelen — de twee relaties

Een CRM zonder relaties is drie losse lijsten. Er ontbreken twee koppelingen: elke contactpersoon hoort bij één account, elke opportuniteit hoort bij één account.

Om een relatie aan te maken, sleept u het veld conta_id van de entiteit Contactos naar het veld id van de entiteit Contas — de tip op de kaart herinnert eraan: "Sleep naar een veld van een andere tabel om te koppelen". Het dialoogvenster Nieuwe relatie opent, met de entiteiten en de kolommen al ingevuld:

Veld	Wat u kiest	Waarom
Cardinaliteit	One-to-many (1:N)	Eén account heeft veel contactpersonen; elke contactpersoon heeft één account.
Parent (waarnaar verwezen wordt)	Contas ▸ id	De "één"-kant.
Child (heeft de FK)	Contactos ▸ conta_id	De "veel"-kant — die bewaart de verwijzing.
Type relatie	Fysiek — maakt de FK aan in de database	De database gaat voortaan garanderen dat er geen wezen zijn onder de contactpersonen.
Navigator in Contactos → Contas	conta	Het virtuele veld dat, vanaf een contactpersoon, zijn account geeft.
Navigator in Contas → Contactos	contactos	Het virtuele veld dat, vanaf een account, haar contactpersonen geeft.
Bij het verwijderen van de parent (ON DELETE)	Niets (blokkeert als er children zijn)	Een account met contactpersonen verwijderen wordt voortaan geweigerd — liever een fout dan een gat.

Bevestig met Relatie aanmaken en herhaal het gebaar tussen Oportunidades ▸ conta_id en Contas ▸ id, met de omgekeerde navigator oportunidades.

De navigators zijn het deel dat het meeste oplevert. Het zijn velden die niet in de database bestaan maar wel in het model: dankzij hen geeft een query op opportuniteiten conta.nome terug zonder dat iemand een join schrijft. Dat is precies wat de tabel van het dashboard in de volgende etappe gaat doen, in de kolom Conta.

#Wat er nu is vrijgekomen

Met het model klaar heeft de app gratis dingen erbij gekregen:

• De GraphQL-API van de app kent Contas, Contactos en Oportunidades al, met de relaties — zie De GraphQL-API van het model.
• De tabel-API's kunnen nu naar een entiteit wijzen en lezen en schrijven genereren zonder één regel SQL. Dat is de eerste stap van de volgende etappe.
• De schermen gaan uit deze API's lezen via datastores.

#Waarom niet…?

• Waarom verschijnt mijn tabel niet in de boom? De objectenboom wordt uit de database gelezen — gebruik Objecten vernieuwen in het menu ⋯ van de datasource nadat u buiten het platform iets hebt gewijzigd.
• Waarom lukt het niet om de relatie aan te maken? De twee kolommen moeten compatibel zijn: een primaire sleutel integer koppelt aan een integer. Hebt u naar het verkeerde veld gesleept, annuleer dan en herhaal — het dialoogvenster zegt dat de kolommen nog gekozen moeten worden.
• Waarom verschijnt het veld conta niet in mijn gegevens? Navigators zijn geen kolommen: zij bestaan alleen via het model. Bevraagt u de gegevens via de SQL-console, dan ziet u de echte kolommen; de navigators verschijnen in de API's en op de schermen.
• Waarom laat het platform mij een account niet verwijderen? U hebt Niets (blokkeert als er children zijn) gekozen bij ON DELETE — en er zijn contactpersonen of opportuniteiten die ernaar wijzen. Verwijder die eerst, of wijzig de regel van de relatie.

Het fundament staat. Volgende etappe: de schermen.