Every later milestone stores its data through this layer, so it has to behave the same on both engines and be safe by construction: - Khaemhat.Data: explicit entity maps, typed queries over a safe expression subset, SqlFragment where every interpolated value becomes a parameter, unit of work with transactions, repositories with audit columns and optimistic concurrency on row_version, retries on transient errors. - SQLite provider (STRICT tables, WAL, exact decimals as integers scaled by 10^6, Unicode case-insensitive LIKE, serialised writes) and PostgreSQL 16+ provider (numeric(19,6), timestamptz, jsonb, advisory locks, database creation and server info). Databases are configured from postgres:// and sqlite:// URLs whose password never appears in messages. - C# migrations with system and company catalogues, schema_version with checksums, one transaction per migration under a lock, refusal of unknown applied versions; first system tables sys_companies and sys_settings. - CompanyRegistry stores each company's database URL encrypted with the instance key (AES-256-GCM, HKDF-derived key, purpose as associated data), so a copied row cannot be read for another company. - tools/Khaemhat.DataModelTool, scripts/gen-datamodel.sh and scripts/new-migration.sh: the current schema section of docs/DATA-MODEL.md is generated from the migrations and a test fails when it is stale. - C# 14 binds array.Contains to MemoryExtensions over spans; the query translator unwraps the span conversion. - Tests run every data scenario on SQLite and PostgreSQL (PostgreSQL in CI); ADR 0018 records where the contracts differ from SPEC 5.1. Docs, wiki, changelog and status updated. Closes #7, #8, #9, #10, #11, #12, #13, #14 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
5.6 KiB
Modello dati
Stato: bozza · Ultima revisione: 2026-11-11 · Versione software: 0.1.0 (strato dati, M1); le tabelle funzionali arrivano con le milestone successive Specifica: SPEC §5, §11, §13, §14
Come Khaemhat organizza i dati, in sintesi. L'elenco completo di tabelle e colonne è in docs/DATA-MODEL.md. La sua sezione Schema attuale è generata automaticamente dalle migrazioni del programma, quindi è sempre allineata a ciò che il programma crea davvero nei database; le altre sezioni descrivono le tabelle pianificate, che compaiono nello schema attuale man mano che le milestone le realizzano.
Due tipi di database
| Database | Nome | Contenuto |
|---|---|---|
| Sistema | khaemhat_system |
aziende collegate, super utente e amministratori, licenze, impostazioni, attività programmate, backup, log, registro di sicurezza |
| Azienda | khaemhat_<codice> (es. khaemhat_demo) |
profilo azienda, tabelle, anagrafiche, articoli, documenti, magazzino, contabilità, scadenzario, fatture elettroniche, CRM, utenti e preferenze, allegati, storico modifiche |
Le tabelle del database di sistema hanno il prefisso sys_. Nelle tabelle aziendali non c'è un campo "azienda":
ogni azienda ha il suo database, quindi i dati non possono mescolarsi. Gli allegati veri e propri (i file) stanno nel
volume /data/files/<azienda>; nel database c'è la loro scheda (nome, tipo, dimensione, impronta, versione).
Le aree principali del database aziendale
| Area | Esempi di tabelle | Pagina |
|---|---|---|
| Profilo e tabelle | company_profile, fiscal_years, tax_codes, payment_methods, warehouses, document_numerators |
Tabelle-azienda |
| Anagrafiche | parties (clienti, fornitori, prospect, lead), indirizzi, contatti, condizioni, dati fiscali |
Anagrafiche |
| Articoli e listini | items, item_prices, price_lists |
Articoli-e-listini |
| Documenti | sale_quotations, sale_orders, sale_documents, purchase_orders, purchase_documents, ciascuno con righe, castelletto IVA e rate; document_links per l'evasione |
Vendite, Acquisti |
| Magazzino | inventory_entries e righe, item_balances (giacenza, impegnato, ordinato per articolo e deposito) |
Magazzino |
| Contabilità e IVA | gl_accounts, gl_entries e righe, vat_registers, vat_settlements |
Contabilita, IVA |
| Scadenzario | open_items (partite), payments |
Scadenzario |
| CRM | crm_leads, crm_opportunities, crm_activities, crm_campaigns, crm_tickets |
CRM |
| Canali | sales_channels, channel_orders |
Canali-e-commerce |
| Utenti e sicurezza | users, roles, role_permissions, user_sessions, api_keys |
Utenti-e-permessi |
| Servizi trasversali | attachments, audit_log, notifications, user_settings |
Allegati-e-file |
Regole che valgono per tutti i dati
- Storico delle modifiche. Ogni tabella registra chi ha creato e modificato il record e quando; anagrafiche, documenti, registrazioni e impostazioni hanno anche lo Storico dettagliato con le differenze.
- Nessuna sovrascrittura silenziosa. Ogni record ha un numero di versione: se due persone modificano lo stesso record, la seconda viene avvisata invece di cancellare il lavoro della prima.
- Importi esatti. Importi e quantità sono numeri decimali con 6 cifre dopo la virgola, mai approssimati; anche su SQLite vengono conservati come interi per non perdere precisione.
- Date. Le date di documento sono date pure; gli orari sono salvati in UTC e mostrati nell'ora italiana.
- Dati riservati cifrati. Password di PEC, SMTP, cloud, intermediari e connessioni ai database sono cifrate con la chiave dell'istanza.
- Dati di esempio riconoscibili. I record creati dai dati dimostrativi sono marcati e si possono rimuovere in blocco (Dati-di-base-e-esempio).
- Niente cancellazioni che rompono la storia. Un cliente con documenti si disabilita, non si cancella; una fattura emessa non si modifica, si rettifica con una nota di credito.
Crescita del database
Le tabelle che crescono di più sono le righe contabili, le righe di magazzino, lo storico delle modifiche e il log. Su PostgreSQL sono predisposte per essere suddivise per anno quando superano i 50 milioni di righe; il log ha una durata di conservazione diversa per livello (errori un anno, avvisi sei mesi, informazioni tre mesi, debug una settimana).
Aggiornamenti dello schema
Quando una nuova versione cambia la struttura dei dati, Khaemhat applica da solo le migrazioni: il database di sistema all'avvio, le aziende all'avvio o dal pannello Amministrazione → Istanza e database, mettendo l'azienda in manutenzione per il tempo necessario. Ogni migrazione è applicata per intero o per niente, e più copie del programma avviate insieme non la applicano due volte. Non è possibile tornare a una versione precedente dello schema: se il database contiene una migrazione che il programma non conosce (per esempio dopo aver rimesso un'immagine più vecchia) Khaemhat si rifiuta di partire invece di rischiare i dati. Per questo prima di ogni aggiornamento conviene un backup (Aggiornamento, Backup-e-ripristino).
Pagine correlate
Architettura · Istanza-e-database · Import-Export · Glossario