Files
Khaemhat/docs/wiki/Modello-dati.md
T
Alby96andClaude Opus 5.5 738c43ba0a
CI / Build and test (SQLite) (pull_request) Successful in 45s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 3s
CI / Docker image (pull_request) Successful in 51s
feat: data layer with SQLite and PostgreSQL providers, migrations and encrypted company registry (M1)
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>
2026-11-11 13:11:34 +01:00

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