Files
Khaemhat/docs/DATA-MODEL.md
T
Alby96andClaude Opus 5.5 b341ade9e9 feat: attachments, file store and in-house PDF/CSV/XLSX/ZIP writers (#34)
Documents need attachments and generated files (SPEC 9.4) before the UI of
M3 can show them, and the spec forbids external libraries for PDF and
spreadsheets.

- VolumeFileStore keeps files under <data>/files/<COMPANY>/<yyyy>/<guid>,
  writing a .part file in the same folder with size limit and SHA-256, then
  quota and scanner checks (IFileScanner hook, no-op by default).
- attachments table (migration 007) with kind, version series, lock, trash
  and the uploading user; AttachmentService uploads, adds generated files as
  the next version, lists, opens, zips, locks, trashes, restores and purges
  after 30 days (new system job system.attachments-trash).
- FileGenerationService runs IFileGenerator implementations into the store;
  three generators for the fictitious test document (PDF, CSV, XLSX).
- CsvWriter (Italian Excel defaults, formula-injection guard), XlsxWriter,
  ZipStreamWriter and PdfWriter (standard Type1 fonts, WinAnsi, AFM widths,
  JPEG, Flate, xref) only write asynchronously, so they can stream to an
  HTTP response.
- ADR 0021 records versioning, storage layout, PDF scope and CSV defaults.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:06:48 +01:00

48 KiB

Modello dati

Stato: in corso · Revisione 2026-11-11 (M1) · Fonte: SPEC §5, §7, §8, §9, §11, §12, §13, §14, §21

Due parti. La sezione 8. Schema attuale è generata da scripts/gen-datamodel.sh leggendo le migrazioni: non si modifica a mano e un test fallisce se non è aggiornata. Le sezioni 3-4 sono la pianificazione ricavata dalla specifica: nomi e colonne sono indicativi e vengono confermati (o corretti) dalla migrazione che crea ciascuna tabella, milestone dopo milestone. I nomi di tabella contrassegnati con † non compaiono letteralmente in SPEC: sono derivati dal nome dell'entità di SPEC §21 secondo la convenzione snake_case plurale.

Documenti collegati: ARCHITECTURE.md · MODULES.md · API.md.


1. Convenzioni (SPEC §5.2)

1.1 Nomi e colonne comuni

  • Tabelle e colonne in snake_case. Tabelle del database di sistema con prefisso sys_.
  • Chiave primaria id BIGINT identity (su SQLite INTEGER PRIMARY KEY).
  • Colonne di audit su ogni tabella (sottintese nelle tabelle sotto): created_at, created_by, updated_at, updated_by.
  • row_version per l'optimistic locking: UPDATE … SET …, row_version = row_version + 1 WHERE id = @id AND row_version = @v; se nessuna riga è aggiornata il repository solleva ConcurrencyException (API: 409/412, vedi API.md).
  • is_demo (IDemoMarkable) sulle righe create dal seeder demo, per poterle rimuovere (SPEC §14).
  • Le chiavi esterne si chiamano <entità>_id (es. party_id, item_id, gl_account_id).
  • Nessun company_id nelle tabelle aziendali: l'isolamento è dato dal database (SPEC §1.4).

1.2 Tipi logici ColumnType e mappatura

ColumnType PostgreSQL SQLite Note
String(n) varchar(n) TEXT + CHECK (length(col) <= n) la lunghezza è imposta dal database su entrambi i motori
Text text TEXT
Int32 integer INTEGER
Int64 bigint INTEGER chiavi primarie ed esterne
Decimal(19,6) numeric(19,6) INTEGER scalato x10⁶ vedi §1.3
Bool boolean INTEGER + CHECK (col IN (0, 1))
Date date TEXT yyyy-MM-dd DateOnly in C#
DateTimeUtc timestamptz TEXT yyyy-MM-ddTHH:mm:ss.ffffffZ DateTime UTC al microsecondo su entrambi i motori; conversione a Europe/Rome solo in presentazione
Guid uuid TEXT
Bytes bytea BLOB
Json jsonb TEXT diff di audit, payload dei canali, dati di log

Le tabelle SQLite sono STRICT: un valore del tipo sbagliato è rifiutato invece di essere convertito. Le enumerazioni sono memorizzate per nome (String(40)), così un riordino dei valori in C# non altera i dati.

1.3 Decimali scalati su SQLite

SQLite non ha un tipo decimale esatto: i valori Decimal(19,6) sono memorizzati come interi moltiplicati per 10⁶ (SqliteDecimalConverter). Conseguenze per chi scrive query:

  • ISqlDialect.ToDbValue / FromDbValue convertono in scrittura e in lettura; i parametri passano già scalati;
  • l'arrotondamento al sesto decimale è half away from zero (1,2345675 diventa 1,234568), come numeric(19,6) su PostgreSQL; un valore oltre l'intervallo solleva OverflowException invece di essere troncato;
  • le somme in SQL (SUM, GROUP BY) operano sugli interi scalati e vengono riscalate in lettura: niente aritmetica in virgola mobile;
  • prodotti e divisioni fra due colonne decimali non vanno fatti in SQL su SQLite (il fattore di scala si moltiplica): si calcolano in C# con decimal o si usa un SqlFragment per dialetto;
  • intervallo utile: ±9,2 x 10¹² con 6 decimali, ampiamente sufficiente per importi e quantità di una PMI.

1.4 Mappe, query e accesso

  • Ogni entità ha una mappa XxxMap : EntityMap<Xxx> (tabella, colonne, chiave, indici, FK, conversioni); nessuna riflessione a runtime oltre la costruzione iniziale (MapRegistry).
  • Query.For<T>().Where(x => ...): uguaglianza, confronto, == null, Contains/StartsWith/EndsWith (LIKE senza distinzione di maiuscole e accenti compresi, con % e _ dell'utente protetti), lista.Contains(x.Col) (IN), &&/||/!, string.IsNullOrEmpty; il resto come SqlFragment parametrizzato. Un'espressione fuori da questo insieme solleva NotSupportedException, non viene valutata in memoria. Mai concatenare input utente in SQL: in SqlFragment.Of($"... {valore}") ogni valore interpolato diventa un parametro.
  • IRepository<T, TKey> compila le colonne di audit, imposta row_version = 1 all'inserimento e la incrementa a ogni modifica; IUnitOfWork.AcquireLockAsync(chiave) prende un lock di transazione (pg_advisory_xact_lock o il lock di scrittura di SQLite) per numeratori e chiusure.
  • SQLite: journal_mode=WAL; foreign_keys=ON; busy_timeout=5000; scritture serializzate da SqliteWriteLock.
  • PostgreSQL: pool separato per database (MaxPoolSize da impostazioni), statement_timeout per sessione, pg_advisory_xact_lock per numeratori, chiusure e scheduler.

2. Migrazioni (SPEC §5.3)

[Migration(20261013_001, "create_parties")]               // Target = MigrationTarget.Company se omesso
public sealed class M20261013_001_CreateParties : IMigration
{
    public void Up(ISchemaBuilder schema) { /* tabelle, colonne, indici, FK in forma neutra */ }
    public string? UpSql(ISqlDialect dialect) => null;     // SQL specifico del dialetto, se serve
}
Regola Dettaglio
Due cataloghi MigrationCatalog.ForSystem() (database di sistema) e MigrationCatalog.ForCompany(assembly dei moduli)
Versioni yyyymmdd_nnn (11 cifre, data valida, nnn da 001), uniche per modulo; schema_version(module, version, name, applied_at, checksum) in ogni database, checksum = SHA-256 delle istruzioni generate
Esecuzione MigrationRunner applica una migrazione per transazione sotto lock (più istanze che partono insieme non si pestano i piedi), è idempotente e restituisce un MigrationReport; la registrazione nella sezione di log Migrazioni arriva con il log (M2)
Checksum diverso una migrazione già applicata e poi modificata produce un avviso, non un errore: le migrazioni applicate non si cambiano, se ne scrive una nuova
Downgrade non supportato: se trova versioni applicate non note rifiuta di partire (MigrationException)
Avvio il sistema è migrato all'avvio; le aziende all'avvio (impostazione) o dal pannello (SPEC §12.1) in modalità manutenzione
Nuova migrazione scripts/new-migration.sh <system|company> <nome_snake_case> [cartella] [modulo]
Documentazione scripts/gen-datamodel.sh rigenera la sezione 8; --check verifica soltanto
Test obbligatorio tutte le migrazioni da zero su SQLite e PostgreSQL, schema_version coerente, riapplicazione senza effetti

3. Database di sistema (khaemhat_system)

Tabella Colonne principali Relazioni / note Entità
schema_version module, version, name, applied_at, checksum presente in ogni database —
sys_companies code, name (ragione sociale), engine, connection_string (cifrata), status (attiva/manutenzione/sola lettura/disattivata), is_default, notes registro letto da CompanyRegistry Company
sys_users username, email, level (SuperUser/Administrator), password_hash, totp_secret (cifrato), must_change_password, locked_until, disabled un solo SuperUser, non eliminabile SystemUser
sys_roles_templates code, name, permessi del modello copiati nelle aziende come roles —
sys_settings key, value, is_secret segreti cifrati con SecretProtector SystemSetting
sys_licenses licensee, instance_id, issued_at, expires_at, max_concurrent_users, max_companies, modules (Json), grace_period_days, raw licenza .khl firmata ECDSA P-256 License
sys_license_activations module_code, activation_code, activated_at, activated_by, expires_at, revoked_at storico attivazioni (mockup 080) LicenseActivation
sys_scheduled_tasks name, kind (backup/procedura/report/notifica/import-export/verifica/manutenzione), company_code, run_as, cron, time_zone, timeout, retries, parameters (Json), enabled, next_run_at definite dagli amministratori (mockup 083) ScheduledTask
sys_job_runs task_id →, started_at, ended_at, duration_ms, status, trace_id, message storico esecuzioni JobRun
sys_backup_policies scope (istanza/database), database, schedule, retention giornalieri/settimanali/mensili, targets, encrypt, verify, max_age_hours GFS BackupPolicy
sys_backup_sets database, kind (BackupKind), file_path, size, sha256, encrypted, status (BackupStatus), verified_at, copie remote BackupSet
sys_log at, level, section, source, message, exception, user, company, trace_id, request, entity, entity_id, data (Json) tabella grande; indici per data e sezione LogEntry
sys_security_audit at, actor, action, target, company, ip, data (Json) immutabile: login, permessi, licenze, backup, ripristini, database, manutenzione SecurityAuditEntry
sys_data_protection_keys friendly_name, xml chiavi DataProtection dei cookie DataProtectionKey
sys_api_keys prefix, key_hash (SHA-256), name, permissions, companies, expires_at, allowed_ips, last_used_at chiavi di istanza —
sys_notifications recipient →, kind, title, body, link, read_at notifiche agli amministratori SystemNotification
sys_sessions user_id →, token_hash, device, ip, created_at, last_seen_at, expires_at, revoked_at sessioni degli account di istanza SystemSession
sys_login_attempts † at, username, ip, success, reason rate limiting e blocco LoginAttempt

4. Database aziendale (khaemhat_<codice>)

4.1 Utenti, sicurezza e infrastruttura aziendale (CORE)

Tabella Colonne principali Relazioni / note Entità
company_profile riga singola: ragione sociale, denominazione fiscale, P.IVA, codice fiscale, REA, capitale sociale, socio unico, stato liquidazione, indirizzo, contatti, PEC, tax_regime (RF01…RF19), codice destinatario, IBAN predefinito, valuta, country (IT), periodicità IVA, pro-rata %, IVA per cassa, trasmittente/intermediario, note in calce logo come allegato; country sceglie il pacchetto fiscale CompanyProfile
users username, email, kind (Human/Technical), password_hash, totp_secret, flag (solo propri clienti, vede costi e margini, può esportare, può usare le API), expires_at, disabled User
roles code, name, is_template_copy copiati da sys_roles_templates, clonabili Role
role_permissions role_id →, permission codici modulo.entità.azione RolePermission
user_roles user_id →, role_id → UserRole
user_permission_overrides user_id →, permission, granted override per utente UserPermissionOverride
user_sessions user_id →, token_hash, device, ip, last_seen_at, expires_at, revoked_at UserSession
user_settings user_id →, key, value (Json) tema, accento, densità, menu, pagina iniziale, layout griglie, filtri UserSetting
dashboard_layouts † user_id → oppure role_id →, layout (Json) layout predefinito per ruolo DashboardLayout
api_keys prefix, key_hash, user_id → (utente tecnico), permissions, expires_at, allowed_ips, last_used_at ApiKey
notifications user_id →, kind, title, body, link, read_at Notification
attachments entity, entity_id, kind (uploaded/generated/einvoice/notification), file_name, mime, size, sha256, version, generated_by, user_id, at, locked, storage_path un allegato appartiene a un solo documento; cestino 30 giorni Attachment
audit_log entity, entity_id, action, user, at, diff (Json) tabella grande AuditEntry
settings key, value preferenze azienda e versione del pacchetto dati (IT 2026.2) —
code_rules † entity, mask, scope (globale/categoria/anno), allow_manual codici automatici (mockup 074) CodeRule
code_sequences rule_id →, scope_key, last_value assegnazione atomica CodeSequence

4.2 Azienda e tabelle di base (Company, CORE)

Tabella Colonne principali Relazioni / note
fiscal_years start_date, end_date, status (aperto/in chiusura/chiuso), prima pagina libro giornale, ultima registrazione definitiva
fiscal_periods fiscal_year_id →, start_date, end_date, kind (mese/trimestre), status (aperto/liquidato/bloccato) date ammesse solo in periodi aperti
countries codice ISO 3166-1, nome, is_eu, codice SDI (XXXXXXX per l'estero)
provinces sigla, nome, regione
municipalities nome, province_id →, CAP, codice catastale codice fiscale, compilazione da CAP
currencies, exchange_rates codice, decimali; currency_id →, data, cambio (BCE)
units_of_measure codice, descrizione, codice SDI
tax_codes codice, descrizione, aliquota, nature (N1…N7 con sotto-codici), riferimento normativo, esigibilità I/D/S, tipo, indetraibilità %, conti IVA →, validità mockup 076
payment_methods codice, descrizione, codice SDI MP01…MP23
payment_terms (+ payment_term_lines †) codice, descrizione, TP01/02/03; righe: rata, giorni, fine mese, giorno fisso, %, IVA sulla prima rata
bank_accounts IBAN, BIC, gl_account_id →, SIA/CUC
salespeople nome, provvigione, ENASARCO
carriers, shipping_terms, transport_means, goods_appearances, delivery_terms, transport_reasons codice, descrizione (Incoterms per delivery_terms)
document_numerators tipo, sezionale, anno, formato {prefix}/{anno}/{number:D6}, ultimo numero assegnazione atomica alla conferma; nessun buco per fatture, NC e registrazioni definitive
inventory_reasons codice, descrizione, effetti su giacenza/impegnato/ordinato
warehouses codice, descrizione, indirizzo
item_categories codice, descrizione, parent_id → (3 livelli)
party_categories codice, descrizione
price_lists codice, descrizione, valuta, IVA inclusa, listino padre → listini derivati
discount_policies codice, descrizione, formula sconto
document_types kind, numeratore →, causale magazzino →, causale contabile →, registro IVA →, TD SDI, modello stampa catalogo statico
cost_centers, jobs codice, descrizione centri di costo, commesse

4.3 Anagrafiche (Parties, CORE)

Tabella Colonne principali Relazioni / note
parties code (automatico), kind (cliente/fornitore/prospect/lead), ragione sociale o nome/cognome, P.IVA, codice fiscale, party_type (azienda/privato/PA/UE/extra-UE/forfettario), sede, contatti, lingua, country_id →, category_id →, salesperson_id →, note, disabled, is_demo, conti cliente/fornitore → disabilitazione al posto della cancellazione se esistono documenti
party_addresses party_id →, tipo (destinazione), indirizzo
party_contacts party_id →, nome, ruolo, telefono, e-mail
party_bank_accounts party_id →, IBAN, BIC, banca
party_sales_terms party_id →, listino →, sconti, pagamento →, banca RiBa, agente →, vettore →, porto, deposito →, fido, blocco, raggruppa DDT, giorno fatturazione, invio documenti e-mail/PEC
party_purchase_terms party_id →, pagamento →, lead time, minimo, sconti
party_fiscal party_id →, codice destinatario, PEC, split payment, reverse charge, ritenuta e aliquota, causale, cassa previdenza, ENASARCO, EORI, GLN, forfettario, esito VIES
intent_declarations † party_id →, direzione (ricevuta/emessa), protocollo, anno, plafond, utilizzato, residuo, validità mockup 061
party_item_codes party_id →, item_id →, codice e descrizione del cliente/fornitore

4.4 Articoli e listini (Items, CORE)

Tabella Colonne principali Relazioni / note
items code (automatico), descrizioni, item_type (merce/servizio/spesa/testo/cespite), category_id →, UM →, IVA vendita/acquisto →, EAN, NC8, produttore, marca, pesi, deposito →, scorta minima, punto/lotto di riordino, costi (standard/ultimo/medio), gestione a magazzino, conti ricavo/costo → immagine come allegato
item_uoms item_id →, UM →, fattore di conversione
item_barcodes item_id →, codice, tipo
item_prices item_id →, price_list_id →, prezzo, validità, party_id → (prezzo netto cliente) griglia listino x articolo (mockup 018)
item_suppliers item_id →, party_id →, codice fornitore, prezzo, lead time, minimo
item_substitutes item_id →, substitute_item_id →

4.5 Documenti, vendite e acquisti (Sales, Purchases, CORE)

Ogni famiglia di documenti ha testata + _lines + _tax_summary + _installments (SPEC §11.3).

Tabella Contenuto Note
sale_quotations (+ _lines, sale_quotation_revisions †) preventivi/offerte con revisioni collegamento CRM
sale_orders (+ _lines, …) ordini clienti consegne, impegnato, CIG/CUP
sale_documents (+ _lines, _tax_summary, _installments) DDT, fatture (TD01…TD27), NC/ND, pro-forma, parcelle, autofatture
purchase_orders (+ _lines, …) ordini fornitori
purchase_documents (+ _lines, _tax_summary, _installments) DDT di carico, fatture di acquisto, NC fornitore, autofatture TD16-TD29 protocollo IVA
inventory_documents (+ _lines) documenti di magazzino
document_links riga destinazione → riga sorgente, quantità evasione ordine → DDT → fattura; residui

Testata (colonne principali comuni): tipo, sezionale, numero, data, anno, party_id →, destinazione →, riferimenti, valuta/cambio, listino →, pagamento →, metodo, banca →, agente →, deposito →, causale, status, flag (stampato, inviato, contabilizzato, scadenze generate, XML generato), totali (imponibile, imposta, totale, sconto piede, spese, bollo, ritenuta, cassa, netto), note, trasporto, is_demo, gl_entry_id →, protocollo IVA.

Righe: progressivo, tipo riga (LineType), item_id →, descrizione, UM, quantità, prezzo, sconti, formula sconto, tax_code_id →, imponibile, deposito →, consegna, evasa/residua, riga origine →, conto →, centro di costo →, commessa →, note, ordinamento.

Stati (DocumentStatus, EInvoiceStatus): Draft → Confirmed → (PartiallyFulfilled | Fulfilled) → Closed, Cancelled; fatture Draft → Issued → SdiGenerated → SdiSent → (SdiDelivered | SdiRejected | SdiNotDelivered).

4.6 Magazzino (Inventory, CORE)

Tabella Colonne principali Note
inventory_entries data, causale →, documento origine, deposito →, is_demo
inventory_entry_lines entry_id →, item_id →, deposito →, quantità, valore, effetti tabella grande
item_balances item_id →, warehouse_id →, giacenza (OnHand), impegnato (Committed), ordinato (OnOrder), in transito, valore medio aggiornata transazionalmente; disponibilità = giacenza - impegnato
stock_takes † (+ stock_take_lines †) inventario fisico: liste, conteggi, rettifiche mockup 038

4.7 Contabilità e IVA (Ledger, Vat, ACCT; Assets, ASSET; Intrastat, INTRA)

Tabella Colonne principali Note
gl_accounts codice MM.CC.SSS, descrizione, natura (AccountNature), tipo (AccountKind), parent_id →, voce CEE (art. 2424/2425), voce riclassificata, partitario clienti/fornitori, rilevante IVA, chiusura automatica, movimentabile, attivo piano standard PMI precaricato
gl_journal_templates (+ righe †) causale: codice, descrizione; righe con ruolo, dare/avere, registro IVA, genera partita causali di base FV, NCV, FA, …
gl_entries numero per esercizio, data registrazione, competenza, causale →, descrizione, documento origine, registro IVA → e protocollo, status (provvisoria/definitiva), periodo →, fonte, storno di → definitive immutabili
gl_entry_lines entry_id →, gl_account_id →, dare, avere, controparte →, centro di costo →, commessa →, partita →, valuta tabella grande
gl_entry_vat entry_id →, codice IVA →, imponibile, imposta, indetraibile
recurring_entry_templates † modelli di registrazione ricorrente
vat_registers tipo (vendite, acquisti, corrispettivi, vendite RC, acquisti RC, sezionali), codice, ultimo protocollo
vat_settlements (+ righe †) periodo, debito, credito, differita/per cassa, indetraibile, pro-rata, credito precedente, acconto, interessi, importo da versare, stato conferma che blocca il periodo
stamp_duty_entries † documento, importo, trimestre, addebito, versato mockup 060
withholding_taxes †, social_security_charges † ritenute operate/subite, casse previdenziali, ENASARCO mockup 047
fixed_asset_categories †, fixed_assets †, fixed_asset_movements † categorie con coefficienti, beni, acquisti/ammortamenti/dismissioni mockup 048
intrastat_declarations † (+ righe †) periodo, tipo (cessioni/acquisti, bis-quater), righe con NC8, natura transazione, consegna, trasporto mockup 049
accrual_deferrals † ratei e risconti
closing_runs † (+ closing_run_steps †) passi della chiusura esercizio mockup 050
financial_statement_lines † voci di bilancio CEE e riclassificati mockup 051

4.8 Scadenzario e tesoreria (Finance, FIN)

Tabella Colonne principali Note
open_items controparte →, documento, rata, scadenza, importo, pagato, residuo, metodo →, banca →, status (aperta/parziale/chiusa/insoluta/in distinta/contestata), registrazione →
payments (+ payment_lines †) incassi e pagamenti con righe su partite, abbuoni, differenze cambio, spese, storno registrazione automatica
remittances † (+ righe †) distinte RiBa, SDD, bonifici SEPA
sdd_mandates † mandati SDD core/B2B
bank_statements † (+ righe †), bank_match_rules † estratti conto importati, regole di abbinamento mockup 057
dunning_levels †, dunning_runs † (+ righe †) livelli 1-3, esecuzioni di sollecito mockup 056

4.9 Fatturazione elettronica (EInvoicing, EINV)

Tabella Colonne principali Note
e_invoices † documento →, direzione, nome file IT<PIVA>_<progressivo>.xml, formato (FPR12/FPA12/FSM10), stato, canale →, identificativo SDI XML come allegato locked
sdi_notifications † e_invoice_id →, tipo (RC, NS, MC, NE, DT, AT), data, esito, errori
e_invoice_inbox_files † file ricevuti (XML/P7M), stato di importazione inbox /data/inbox/sdi/<azienda>
sdi_channels † tipo (SdiChannelKind: Pec, SdiCoop, IntermediaryA, IntermediaryB), credenziali cifrate, stato mockup 059
sdi_routing_rules † condizione, canale →
conservation_packages † periodo, file, indice export per conservatore

4.10 CRM (Crm, CRM)

Tabella Colonne principali
crm_leads fonte, interesse, punteggio, responsabile, stato, conversione in cliente (party_id →)
crm_pipelines, crm_stages pipeline; fasi con ordine e probabilità
crm_opportunities fase →, probabilità, valore, ponderato, chiusura, responsabile, fonte, concorrenti, motivo perdita, preventivo →, ordine →
crm_activities tipo (chiamata/e-mail/riunione/attività/nota/visita), scadenza, esito, promemoria, collegamenti
crm_campaigns (+ membri †) tipo, segmento →, modello →, budget, costo, statistiche
crm_tickets priorità, stato, SLA, assegnatario, intervento → (Servizi), NC →
crm_email_templates, crm_segments modelli e-mail, segmenti

4.11 Servizi e canali (Services, SVC; Channels, CHAN)

Tabella Colonne principali
service_contracts † (+ righe †) cliente →, sede →, validità, rinnovo tacito, canone e periodicità, servizi inclusi, impianti e matricole
service_teams †, service_technicians † squadre, tecnici con costo orario
service_interventions † (+ righe †) tipo (programmato/a chiamata/garanzia), stato, pianificazione, ore e materiali, rapportino, firma
sales_channels tipo (generico o connettore dedicato), credenziali cifrate, cliente cassa →, sezionale, pagamento →, deposito →, mappature
channel_items, channel_customers corrispondenze articoli e clienti
channel_orders payload (Json), stato, ordine generato →

4.12 Automazioni (Automation, AUTO; Integrazioni, API)

Tabella Colonne principali
automation_rules † evento (AutomationTrigger), condizioni (Json), azioni (Json, AutomationActionKind), attiva, errori consecutivi
automation_runs † regola →, at, esito, trace id, messaggio
webhooks † URL, eventi, segreto HMAC (cifrato), attivo

5. Relazioni principali

parties ─┬─< party_addresses / party_contacts / party_bank_accounts
         ├── party_sales_terms / party_purchase_terms / party_fiscal
         ├─< sale_* / purchase_* (testate) ─< *_lines >── items
         │                                    └─< document_links (riga → riga)
         ├─< open_items >── payments (righe)
         └─< crm_leads (conversione) / crm_opportunities

sale_documents ──► gl_entries ─< gl_entry_lines >── gl_accounts
                       └─< gl_entry_vat >── tax_codes
inventory_entries ─< inventory_entry_lines ──► item_balances (item x warehouse)
qualunque documento ─< attachments (entity, entity_id)
qualunque modifica ──► audit_log

6. Tabelle grandi e partizionamento

Tabella Database Indici previsti
gl_entry_lines azienda esercizio/data, conto, partita
inventory_entry_lines azienda data, articolo x deposito
audit_log azienda entity/entity_id, data
sys_log sistema data, sezione, livello, trace_id, azienda
  • Su PostgreSQL il SchemaBuilder (PostgresPartitioning) predispone il partizionamento per anno, attivabile con una migrazione quando la tabella supera i 50 milioni di righe.
  • Su SQLite non c'è partizionamento: SQLite è previsto per test, demo, prova e archivi in sola lettura.
  • La retention di sys_log per livello (365/180/90/7 giorni) e la compattazione limitano la crescita del log.
  • Obiettivi di prestazione di riferimento (SPEC §18): bilancio di verifica su 2 M righe < 10 s, pagina log con 1 M righe < 1 s per filtro.

6.1 Misure di riferimento dello strato dati (M1)

PerformanceBaselineTests inserisce righe con tutti i tipi di colonna tramite IRepository in una sola transazione, poi le legge tutte e legge una pagina filtrata con il conteggio totale. Con KHAEMHAT_PERF=1 usa 100.000 righe, altrimenti 2.000 (prova di fumo, sempre eseguita anche in CI).

KHAEMHAT_PERF=1 scripts/test.sh --filter TestCategory=Performance --logger "console;verbosity=detailed"
Data Motore Macchina Inserimenti Lettura di tutte le righe Pagina filtrata + conteggio
2026-11-11 SQLite (file in memoria) Ryzen 5 2600X, Windows 11, .NET 10.0.403 100.000 in 5,6 s (circa 17.800/s) 0,9 s 17 ms

Le misure servono a riconoscere un peggioramento, non come soglia: il test non fallisce sui tempi. Le misure su PostgreSQL si aggiungono dal job postgres della CI alla chiusura della milestone.

7. Segreti nel database

Cifrati con AES-256-GCM e chiave derivata da KHAEMHAT_SECRET_KEY (SecretProtector): connection string delle aziende (sys_companies), password SMTP/PEC/S3/WebDAV (sys_settings), token degli intermediari e credenziali dei canali SDI (sdi_channels), credenziali dei canali e-commerce (sales_channels), segreti dei webhook. La rotazione avviene con KHAEMHAT_SECRET_KEY_NEW (SPEC §12.9). Gli hash (password, chiavi API) non sono cifrati ma irreversibili.

8. Schema attuale (generato)

Questa sezione è scritta da scripts/gen-datamodel.sh a partire dalle migrazioni presenti nel codice; il test DataModelDocumentTests fallisce se non è aggiornata. Comprende schema_version, presente in ogni database.

Database di sistema

Migrazioni applicate in ordine:

  • core 20261111001 create_sys_companies (M20261111_001_CreateSysCompanies)
  • core 20261111002 create_sys_settings (M20261111_002_CreateSysSettings)
  • core 20261111003 create_sys_users (M20261111_003_CreateSysUsers)
  • core 20261111004 create_sys_sessions (M20261111_004_CreateSysSessions)
  • core 20261111005 create_sys_roles_templates (M20261111_005_CreateSysRolesTemplates)
  • core 20261111006 create_sys_licenses (M20261111_006_CreateSysLicenses)
  • core 20261111007 create_sys_data_protection_keys (M20261111_007_CreateSysDataProtectionKeys)
  • core 20261111008 create_sys_log (M20261111_008_CreateSysLog)
  • core 20261111009 create_sys_security_audit (M20261111_009_CreateSysSecurityAudit)
  • core 20261111010 create_sys_scheduler (M20261111_010_CreateSysScheduler)
  • core 20261111011 create_sys_notifications (M20261111_011_CreateSysNotifications)
  • core 20261111012 create_sys_user_settings (M20261111_012_CreateSysUserSettings)

schema_version

Colonna Tipo Null Default Note
module String(50) no chiave primaria
version Int64 no chiave primaria
name String(200) no
applied_at DateTimeUtc no
checksum String(64) no

Chiave primaria: module, version.

sys_companies

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
code String(20) no
name String(200) no
engine String(20) no
connection_string Text no
status String(40) no 'Active'
is_default Bool no false
notes Text sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_companies_code su code

sys_data_protection_keys

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
friendly_name String(200) no
xml Text no
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_data_protection_keys_friendly_name su friendly_name

sys_job_locks

Colonna Tipo Null Default Note
id String(100) no chiave primaria
owner String(100) no
acquired_at DateTimeUtc no
expires_at DateTimeUtc no

sys_job_runs

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
task_code String(100) no
started_at DateTimeUtc no
finished_at DateTimeUtc sì
outcome String(40) no
attempt Int32 no 1
message Text sì
trace_id String(64) sì
  • indice ix_sys_job_runs_task_code_started_at su task_code, started_at

sys_license_activations

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
action String(40) no
source String(40) no
modules String(400) sì
outcome String(60) no
message Text sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1

sys_licenses

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
source String(40) no
payload Text no
licensee String(200) sì
modules String(400) no
max_concurrent_users Int32 no 0
max_companies Int32 no 0
issued_at DateTimeUtc sì
expires_at DateTimeUtc sì
grace_period_days Int32 no 0
is_active Bool no true
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1

sys_log

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
at DateTimeUtc no
level String(20) no
section String(40) no
source String(200) no
message Text no
exception Text sì
user_name String(100) sì
company_code String(20) sì
trace_id String(64) sì
request String(400) sì
entity String(100) sì
entity_id String(100) sì
data Json sì
  • indice ix_sys_log_at su at
  • indice ix_sys_log_section_at su section, at
  • indice ix_sys_log_trace_id su trace_id

sys_notifications

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
recipient_user_id Int64 sì
category String(40) no
severity String(40) no
title String(200) no
body Text sì
link String(400) sì
read_at DateTimeUtc sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice ix_sys_notifications_recipient_user_id su recipient_user_id

sys_roles_templates

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
code String(50) no
name String(100) no
description Text sì
permissions Json no
sort_order Int32 no 0
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_roles_templates_code su code

sys_scheduled_tasks

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
code String(100) no
name String(200) no
job_type String(100) no
company_code String(20) sì
cron String(100) no
time_zone String(64) no
timeout_seconds Int32 no 600
max_retries Int32 no 0
is_enabled Bool no true
is_system Bool no false
parameters Json sì
last_run_at DateTimeUtc sì
next_run_at DateTimeUtc sì
last_outcome String(40) sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_scheduled_tasks_code su code

sys_security_audit

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
at DateTimeUtc no
action String(100) no
user_name String(100) sì
company_code String(20) sì
ip_address String(64) sì
target String(200) sì
details Json sì
previous_hash String(64) no
hash String(64) no
  • indice ix_sys_security_audit_at su at

sys_sessions

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
token_hash String(64) no
user_id Int64 no -> sys_users (Cascade)
state String(40) no
company_code String(20) sì
ip_address String(64) sì
user_agent String(400) sì
persistent Bool no false
last_seen_at DateTimeUtc no
expires_at DateTimeUtc no
revoked_at DateTimeUtc sì
revoked_reason String(100) sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice ix_sys_sessions_user_id su user_id
  • indice unico ux_sys_sessions_token_hash su token_hash

sys_settings

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
key String(200) no
value Text sì
is_secret Bool no false
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_settings_key su key

sys_user_settings

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
user_id Int64 no
key String(200) no
value Text sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_user_settings_user_id_key su user_id, key

sys_users

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
user_name String(100) no
display_name String(200) no
email String(254) sì
level String(40) no
password_hash String(200) sì
password_history Json sì
password_changed_at DateTimeUtc sì
must_change_password Bool no false
temporary_password_expires_at DateTimeUtc sì
failed_login_count Int32 no 0
locked_until DateTimeUtc sì
totp_secret Text sì
totp_enabled Bool no false
totp_last_step Int64 sì
totp_recovery_codes Json sì
recovery_token_hash String(64) sì
recovery_token_expires_at DateTimeUtc sì
is_active Bool no true
last_login_at DateTimeUtc sì
linked_company_code String(20) sì
linked_user_id Int64 sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_sys_users_user_name su user_name

Database aziendale

Migrazioni applicate in ordine:

  • core 20261111001 create_users (M20261111_001_CreateUsers)
  • core 20261111002 create_user_sessions (M20261111_002_CreateUserSessions)
  • core 20261111003 create_roles (M20261111_003_CreateRoles)
  • core 20261111004 create_audit_log (M20261111_004_CreateAuditLog)
  • core 20261111005 create_notifications (M20261111_005_CreateNotifications)
  • core 20261111006 create_user_settings (M20261111_006_CreateUserSettings)
  • core 20261111007 create_attachments (M20261111_007_CreateAttachments)

attachments

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
entity String(100) no
entity_id Int64 no
kind String(40) no
name String(255) no
mime String(150) no
size Int64 no
sha256 String(64) no
version Int32 no
version_key String(300) no
generated_by String(100) sì
storage_key String(60) no
user_name String(100) sì
locked Bool no false
deleted_at DateTimeUtc sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice ix_attachments_deleted_at su deleted_at
  • indice ix_attachments_entity_entity_id su entity, entity_id
  • indice unico ux_attachments_entity_entity_id_version_key_version su entity, entity_id, version_key, version

audit_log

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
at DateTimeUtc no
entity String(100) no
entity_id String(100) no
action String(20) no
user_name String(100) sì
diff Json sì
trace_id String(64) sì
  • indice ix_audit_log_at su at
  • indice ix_audit_log_entity_entity_id su entity, entity_id

notifications

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
recipient_user_id Int64 sì
category String(40) no
severity String(40) no
title String(200) no
body Text sì
link String(400) sì
read_at DateTimeUtc sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice ix_notifications_recipient_user_id su recipient_user_id

role_permissions

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
role_id Int64 no -> roles (Cascade)
permission String(100) no
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_role_permissions_role_id_permission su role_id, permission

roles

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
code String(50) no
name String(100) no
description Text sì
is_predefined Bool no false
template_code String(50) sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_roles_code su code

schema_version

Colonna Tipo Null Default Note
module String(50) no chiave primaria
version Int64 no chiave primaria
name String(200) no
applied_at DateTimeUtc no
checksum String(64) no

Chiave primaria: module, version.

user_permission_overrides

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
user_id Int64 no -> users (Cascade)
permission String(100) no
allowed Bool no
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_user_permission_overrides_user_id_permission su user_id, permission

user_roles

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
user_id Int64 no -> users (Cascade)
role_id Int64 no -> roles (Cascade)
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_user_roles_user_id_role_id su user_id, role_id

user_sessions

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
token_hash String(64) no
user_id Int64 no -> users (Cascade)
state String(40) no
company_code String(20) sì
ip_address String(64) sì
user_agent String(400) sì
persistent Bool no false
last_seen_at DateTimeUtc no
expires_at DateTimeUtc no
revoked_at DateTimeUtc sì
revoked_reason String(100) sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice ix_user_sessions_user_id su user_id
  • indice unico ux_user_sessions_token_hash su token_hash

user_settings

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
user_id Int64 no
key String(200) no
value Text sì
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_user_settings_user_id_key su user_id, key

users

Colonna Tipo Null Default Note
id Int64 no chiave primaria, identity
user_name String(100) no
display_name String(200) no
email String(254) sì
kind String(40) no
password_hash String(200) sì
password_history Json sì
password_changed_at DateTimeUtc sì
must_change_password Bool no false
temporary_password_expires_at DateTimeUtc sì
failed_login_count Int32 no 0
locked_until DateTimeUtc sì
totp_secret Text sì
totp_enabled Bool no false
totp_required Bool no false
totp_last_step Int64 sì
totp_recovery_codes Json sì
recovery_token_hash String(64) sì
recovery_token_expires_at DateTimeUtc sì
is_active Bool no true
last_login_at DateTimeUtc sì
own_customers_only Bool no false
can_see_costs Bool no false
can_export Bool no false
can_use_api Bool no false
created_at DateTimeUtc no
created_by String(100) sì
updated_at DateTimeUtc sì
updated_by String(100) sì
row_version Int64 no 1
  • indice unico ux_users_user_name su user_name