Abbiamo trascorso i primi sei mesi di “VenduSys” a modellare ogni cosa. Al quarto mese avevamo già diciassette entità, otto tabelle di join, tre oggetti “di contesto” che nessuno riusciva a definire con precisione e un modello di autorizzazioni che richiedeva venti minuti per essere spiegato. Un classico.
A quel punto abbiamo accantonato tutto e siamo partiti da una domanda: qual è l’insieme più piccolo di entità in grado di modellare ogni forma di commercio che ci interessa?
La risposta si è rivelata essere quattro.
Festa
Una persona, un'organizzazione o un agente. Acquirenti, venditori, operatori, partner: tutte rappresentazioni dello stesso record. La differenza tra "acquirente" e "venditore" non è una tipologia, ma un ruolo all'interno di una transazione. Un acquirente in un'operazione è un venditore in quella successiva.
Una volta accettato questo, l’identità diventa un problema di grafo piuttosto che un problema di tipizzazione. KYB, KYC, ruoli, audit, configurazione dei pagamenti: tutto dipende dallo stesso nodo.
Cosa
Qualsiasi cosa offerta o posseduta. Prodotti, licenze, servizi, abbonamenti, risorse, tempo. Le varianti e i pacchetti sono proiezioni di questo concetto: uno SKU è una “Cosa” in una forma particolare, un piano di abbonamento è una “Cosa” con una dimensione temporale, un’ora di servizio è una “Cosa” con una dimensione di capacità.
La maggior parte delle piattaforme commerciali le modella come entità separate (Prodotto, Piano, Servizio, Risorsa) e poi impiega anni a colmare le lacune. Considerarle come un’unica entità dotata di attributi — perpetua o a tempo determinato, fisica o digitale, trasferibile o meno — riduce in modo sorprendente la complessità.
Sposta
Un evento che comporta il trasferimento di valore o di diritti tra le parti. Ordini, resi, rinnovi, trasferimenti, rimborsi, contestazioni: tutte queste operazioni sono considerate “mosse”. Una “mossa” è costituita da un pagatore, un beneficiario, un oggetto (o un insieme di oggetti), un importo e uno stato.
Considerare "ordine" e "rimborso" come lo stesso tipo di oggetto — con segni diversi — elimina un'intera categoria di bug.
Voce
Una riga nel libro mastro a partita doppia. Ogni operazione genera delle registrazioni; i report e i saldi ne derivano in modo deterministico. Si tratta dell’entità più importante del sistema, nonché quella che la maggior parte delle piattaforme commerciali nasconde.
Se la tua piattaforma è un sistema di registrazione delle transazioni finanziarie, ma il tuo registro è stato aggiunto solo in un secondo momento, la tua piattaforma è un sistema di negabilità plausibile.
Perché funziona
Il trucco non sta nelle quattro entità. Il trucco sta in ciò che ti impediscono di avere:
- Non esistono tipi distinti di "ordine sul mercato" e "ordine diretto"
- Non esistono "abbonamento" e "acquisto una tantum" distinti: entrambi sono sequenze di mosse
- Non esiste un "portafoglio" separato: il saldo è la somma delle registrazioni relative a un conto
- Non esiste un "motore di rimborso" separato: un rimborso è un'operazione di storno con registrazioni di storno
- Non esiste un “registro dei soci” separato: i pagamenti ai soci sono semplicemente registrazioni a carico dei conti dei soci
La forma nel codice
In linea di massima, in TypeScript:
type Party = { id; kind: 'person' | 'org' | 'machine'; profile; trust };
type Thing = { id; kind; attrs; rights?; meter? };
type Move = { id; kind; from: PartyId; to: PartyId; thing: ThingId[];
at; state; reverses?: MoveId };
type Entry = { id; account; move: MoveId;
side: 'debit' | 'credit'; amount; ccy };Tutto il resto — ordini, fatture, abbonamenti, programmi per i partner, marketplace — è costituito da un flusso di lavoro che li integra. La libreria dei flussi di lavoro è argomento di un altro post.
A cosa abbiamo rinunciato
Un po' di chiarezza, onestamente. "Ordine" e "Abbonamento" sono termini utili nelle conversazioni con chi non è un ingegnere. Li manteniamo come proiezioni nell'interfaccia API, ma sotto sotto sono sequenze di operazioni. Quel divario rappresenta il costo.
In cambio, abbiamo ottenuto un sistema che non va in tilt quando viene introdotta una nuova forma. Sapremo di aver realizzato il modello giusto se non dovremo mai aggiungere una quinta entità. Chiedicelo di nuovo tra tre anni.
Edwin Korver is the founder and systems architect behind VenduSys and RoundMap®. His work focuses on regenerative business, value orchestration, and the systems that help organizations move from extraction toward shared value and healthier ecosystems.