# Architettura di Khaemhat > Stato: bozza · Revisione 2026-11-11 · Fonte: SPEC §1, §2, §3, §4, §5, §7, §9, §13, §15, §19, §21; ADR 0009-0018 Questo documento descrive l'architettura **prevista** del gestionale: livelli, progetti, regole di dipendenza, composizione dei moduli, gestione multi-database, ciclo di una richiesta e servizi trasversali. Il codice non esiste ancora: ogni sezione indica la milestone (SPEC §20) in cui la parte viene realizzata. Quando il codice cambia questo file va aggiornato nello stesso commit (SPEC §17). Documenti collegati: [DATA-MODEL.md](DATA-MODEL.md) (tabelle), [MODULES.md](MODULES.md) (moduli e licenze), [API.md](API.md) (REST), [MCP.md](MCP.md) (agenti AI), [SPEC.md](SPEC.md) (specifica normativa), [adr/](adr/) (decisioni). --- ## 1. Principi | Principio | Conseguenza pratica | Fonte | |---|---|---| | Un solo runtime: C# 14 su .NET 10 | nessun altro linguaggio lato server; JavaScript solo come interop minimo in `wwwroot/js` | SPEC §1.1 | | Nessuna libreria esterna | ammessi solo framework condivisi Microsoft, `Npgsql`, `Microsoft.Data.Sqlite` e, nei soli test, `Microsoft.NET.Test.Sdk` + `MSTest`; allowlist in `Directory.Packages.props` verificata da `scripts/check-packages.sh` | SPEC §1.2 | | Codice indifferente al motore | sopra `Khaemhat.Data` nessuno sa se il database è SQLite o PostgreSQL | SPEC §1.3 | | Un database di sistema + uno per azienda | le tabelle operative non hanno `company_id` | SPEC §1.4, §5.4 | | Configurazione iniziale solo da variabili `KHAEMHAT_*` | nessun file di impostazioni con segreti, scritture solo in `KHAEMHAT_DATA_DIR` | SPEC §1.5, §6 | | Fiscalità isolata | tutto ciò che è italiano vive in `Khaemhat.Fiscal.Italy` dietro `Khaemhat.Fiscal.Abstractions` | SPEC §1.10 | | Moduli dietro licenza | un modulo non licenziato non registra menu, API, tool MCP né procedure | SPEC §1.8, §8 | | Distribuzione solo Docker | unico artefatto: `gitea.encke-hake.ts.net/balbosoft/khaemhat:` | ADR 0010 | ## 2. Livelli e progetti ``` ┌───────────────────────────────────────────────────────────────────────────┐ │ Khaemhat.Web UI Blazor (Interactive Server) · REST /api/v1 · │ │ MCP /mcp · autenticazione · host · aiuto /help │ ├───────────────────────────────────────────────────────────────────────────┤ │ Khaemhat.Application casi d'uso per modulo · DTO · permessi · │ │ motore documenti · motore contabile · procedure ·│ │ automazioni · seeder · report · orchestrazione │ │ backup · registro moduli │ ├──────────────────────────────────────┬────────────────────────────────────┤ │ Khaemhat.Fiscal.Abstractions │ Khaemhat.Fiscal.Italy │ │ interfacce paese (IVA, e-invoice, │ FatturaPA · TD · nature · F24 · │ │ calendario, ritenute, cespiti, CEE) │ LIPE · Intrastat · ritenute · │ │ │ cespiti · bilancio CEE · SDI │ ├──────────────────────────────────────┴────────────────────────────────────┤ │ Khaemhat.Core entità · value object · enum · regole di dominio │ │ · calcoli · validatori · partita doppia │ ├───────────────────────────────────────────────────────────────────────────┤ │ Khaemhat.Infrastructure cache/Redis (RESP) · crypto · licenze · SMTP/IMAP│ │ · PDF · XLSX/CSV/ZIP · job · file · backup │ │ (pg_dump, S3, WebDAV) · protocollo MCP · HTTP │ │ (VIES, BCE, registro pacchetti Gitea, interm.) │ ├───────────────────────────────────────────────────────────────────────────┤ │ Khaemhat.Data astrazioni DB · query builder · mappe · │ │ migrazioni · unit of work · registro database │ │ ├─ Khaemhat.Data.Sqlite └─ Khaemhat.Data.PostgreSql │ └───────────────────────────────────────────────────────────────────────────┘ ``` Nota: nella figura di SPEC §3 il livello Infrastructure cita "GitHub packages"; per l'emendamento E1 (ADR 0009) il client degli aggiornamenti è `GiteaPackagesClient`. ### 2.1 Progetti della soluzione | Progetto | Ruolo | Milestone | |---|---|---| | `Khaemhat.Core` | dominio puro: entità, value object (`Money`, `Quantity`, `Percentage`), regole e calcoli, validatori | M1 → M10 | | `Khaemhat.Fiscal.Abstractions` | contratti del pacchetto paese (`IFiscalPack`, `ITaxEngine`, `IEInvoiceFormat`, `ISdiTransport`, …) | M4 | | `Khaemhat.Fiscal.Italy` | implementazione italiana (`ItalyFiscalPack`, `FatturaPaWriter`, `F24Exporter`, `LipeWriter`, …) | M4 → M10 | | `Khaemhat.Data` | micro-ORM interno: `IDbProvider`, `ISqlDialect`, `EntityMap`, `QueryBuilder`, migrazioni | M1 | | `Khaemhat.Data.Sqlite` | provider SQLite (`SqliteProvider`, `SqliteDialect`, `SqliteWriteLock`, `SqliteDecimalConverter`) | M1 | | `Khaemhat.Data.PostgreSql` | provider PostgreSQL ≥ 16 (`PostgresProvider`, `PostgresDatabaseCreator`, `PostgresAdvisoryLocks`, `PostgresPartitioning`) | M1 | | `Khaemhat.Infrastructure` | servizi tecnici scritti in casa (cache, crypto, PDF, mail, job, backup, MCP, log) | M1 → M12 | | `Khaemhat.Application` | casi d'uso, moduli (`IModule`), motore documenti e contabile, seeding, report | M2 → M12 | | `Khaemhat.Web` | host ASP.NET Core 10, Blazor Interactive Server, Minimal API, MCP, autenticazione | M0 → M13 | | `tools/Khaemhat.LicenseTool` | CLI per chiavi ed emissione licenze (chiave privata mai nel repository; non distribuito) | M2 | | `tools/Khaemhat.DataModelTool` | rigenera la sezione generata di `docs/DATA-MODEL.md` dalle migrazioni (non distribuito, ADR 0018) | M1 | | `tests/*` | `Core`, `Data`, `Infrastructure`, `Fiscal.Italy`, `Application`, `Web` (MSTest) | ogni milestone | ## 3. Regole di dipendenza Le regole sono **verificate da test di architettura** in `Khaemhat.Core.Tests` (SPEC §3, §18): un riferimento non ammesso fa fallire la build di test. | Progetto | Può dipendere da | Non può dipendere da | |---|---|---| | `Core` | nulla (solo BCL) | qualunque altro progetto | | `Fiscal.Abstractions` | `Core` | tutto il resto | | `Fiscal.Italy` | `Core`, `Fiscal.Abstractions`, `Infrastructure` (solo XML/PDF/crypto/HTTP) | `Application`, `Web`, `Data.*` | | `Data` | `Core`, `System.Data.Common` | provider concreti, `Infrastructure`, `Application` | | `Data.Sqlite` | `Data`, `Microsoft.Data.Sqlite` | tutto il resto | | `Data.PostgreSql` | `Data`, `Npgsql` | tutto il resto | | `Infrastructure` | `Core`, `Data` | `Application`, `Web`, `Fiscal.*`, provider concreti | | `Application` | `Core`, `Data`, `Infrastructure`, `Fiscal.Abstractions` | **`Fiscal.Italy`**, provider concreti, `Web` | | `Web` | `Application` (e transitivamente il resto); registra in `Program.cs` i provider concreti e i pacchetti paese | — | Altri controlli di architettura (SPEC §18): - nessun `PackageReference` fuori dall'allowlist di `Directory.Packages.props`; - nessun testo dell'interfaccia scritto direttamente nei componenti (tutto passa da `ITexts`); - nessun accesso al pacchetto fiscale se non tramite le interfacce di `Fiscal.Abstractions`; - nessun `Process.Start` fuori da `Infrastructure/Backup` (unico uso: `pg_dump` / `pg_restore`). ``` Web ──────────────► Application ──────► Fiscal.Abstractions ──► Core │ │ │ ▲ │ (solo Program.cs) │ └──► Infrastructure ───┼──► Data ──► Core ▼ ▼ ▲ │ Data.Sqlite / Data.PostgreSql │ │ Fiscal.Italy ────────────────────────────┴─────────────┘ ``` ## 4. Moduli: `IModule` e `ModuleRegistry` Ogni area funzionale è un modulo dentro `Khaemhat.Application/Modules//` con struttura fissa (SPEC §4): ``` Modules/Sales/ ├── Services/ casi d'uso (SaleDocumentService, …) ├── Dtos/ record di input/output ├── Validators/ Validator applicativi ├── Migrations/ migrazioni del catalogo azienda (o sistema) ├── Seed/Base/ seeder dati di base ├── Seed/Demo/ seeder dati dimostrativi ├── Reports/ ReportDefinition del modulo ├── Api/ endpoint REST del modulo ├── Mcp/ tool MCP del modulo ├── Procedures/ IProcedure del modulo ├── Permissions.cs PermissionDefinition del modulo ├── Menu.cs MenuItem del modulo └── SalesModule.cs implementazione di IModule ``` `IModule` (in `Application.Modules`) dichiara, per ogni modulo: | Membro (indicativo) | Contenuto | |---|---| | codice licenza (`ModuleCode`) | uno dei 13 codici di SPEC §8.1 (`CORE`, `ACCT`, …) | | nome, ordine | nome localizzato e posizione nel menu | | voci di menu (`MenuItem`) | percorso, icona, contatori, permesso richiesto | | permessi (`PermissionDefinition`) | codici `modulo.entità.azione` | | migrazioni | classi `IMigration` del catalogo **sistema** o **azienda** | | seeder | `ISeeder` *base* e *demo* | | endpoint API | mappatura Minimal API sotto `/api/v1` | | tool MCP | `McpTool` registrati in `McpToolRegistry` | | procedure | `IProcedure` per `ProcedureCatalog` | | eventi per le automazioni | trigger esposti a `TriggerCatalog` | | sezione di log | valore di `LogSection` | | pagine wiki | `HelpLink` verso `docs/wiki/.md` (F1) | `ModuleRegistry` enumera i moduli **staticamente** (nessuna scoperta per riflessione o plugin: SPEC §1.7) e li filtra con `LicenseGate` in base alle licenze attive. Effetti di un modulo non licenziato (SPEC §8.1): voci di menu nascoste, endpoint API e tool MCP **non registrati**, procedure non eseguibili, dati conservati; ogni accesso residuo equivale a permesso negato con codice `module_not_licensed` (`ModuleNotLicensedException`). Elenco dei moduli, codici licenza e milestone: [MODULES.md](MODULES.md). ## 5. Multi-database ### 5.1 Database di sistema e database aziendali | Database | Nome | Contenuto | |---|---|---| | Sistema | `khaemhat_system` (da `KHAEMHAT_SYSTEM_DB`) | registro aziende, account di istanza (super utente e amministratori), modelli di ruolo, impostazioni, licenze, attività programmate, esecuzioni, politiche e set di backup, log, audit di sicurezza, chiavi DataProtection, chiavi API di istanza, notifiche e sessioni di istanza (tabelle `sys_*`) | | Azienda | `khaemhat_` (es. `khaemhat_demo`) | tutte le tabelle operative + utenti, ruoli, permessi, sessioni, preferenze, chiavi API, notifiche, allegati, audit, `company_profile` | Con SQLite ogni database è un file sotto `KHAEMHAT_DATA_DIR`; con PostgreSQL i database aziendali vengono creati (`CREATE DATABASE`) sul server indicato da `KHAEMHAT_DB_SERVER` con un ruolo dotato di `CREATEDB`. Il dettaglio delle tabelle è in [DATA-MODEL.md](DATA-MODEL.md). ### 5.2 Contratti principali | Tipo | Progetto | Responsabilità | |---|---|---| | `IDbProvider` | Data | motore (`DbEngine`), dialetto, generatore DDL (`Ddl`), connection string da `DatabaseUrl`, creazione connessioni, `EnsureDatabaseExistsAsync`, `DatabaseExistsAsync`, `DropDatabaseAsync`, `GetServerInfoAsync`, `IsTransient`, `EnterWriteScopeAsync` (ADR 0018) | | `ISqlDialect` | Data | quoting, parametri, paginazione, `InsertReturningId`, `Upsert`, `CaseInsensitiveLike` e `AdvisoryLock` come `SqlFragment`, conversioni `ColumnType` | | `IUnitOfWorkFactory` | Data | `CreateAsync(DatabaseScope scope)` dove lo scope è `System` oppure `Company(code)` | | `IUnitOfWork` / `IRepository` | Data | transazione, repository tipizzati, `ExecuteAsync`/`QueryAsync`/`StreamAsync` su `SqlFragment` | | `ICompanyRegistry` (`CompanyRegistry`) | Data | registra le aziende e risolve `companyCode → DatabaseTarget` (provider + connection string) decifrando l'URL salvato in `sys_companies` | | `ICompanyContext` | Core (interfaccia), Web (`CompanyContextAccessor`) | azienda corrente: **per circuito Blazor** e **per richiesta API** (header `X-Company`) | | `SecretProtector` | Infrastructure | AES-256-GCM con chiave derivata da `KHAEMHAT_SECRET_KEY` per connection string e credenziali | ### 5.3 Risoluzione dell'azienda 1. Un **utente aziendale** è vincolato alla propria azienda (scelta nella pagina di accesso, mockup 001). 2. Un **account di istanza** (super utente o amministratore) sceglie l'azienda dalla barra superiore (`CompanySwitcher`) ed entra con permessi completi su di essa. 3. Un client API indica l'azienda con l'header `X-Company: `; una chiave aziendale è già legata a un'azienda (vedi [API.md](API.md)). 4. `ICompanyContext` espone il codice; `IUnitOfWorkFactory` lo usa per aprire il database giusto tramite `ICompanyRegistry`. Le chiavi di cache sono prefissate con l'azienda (`kh:{azienda}:{area}:{key}`). 5. Lo stato dell'azienda in `sys_companies` (*attiva / manutenzione / sola lettura / disattivata*) è applicato da `MaintenanceMiddleware`: in manutenzione gli utenti vengono disconnessi e le API rispondono `503`. ### 5.4 Bootstrap al primo avvio `docker/entrypoint.sh` attende il database e avvia l'app; `StartupOrchestrator` esegue (SPEC §5.4): 1. validazione delle variabili con `KhaemhatOptions.Validate()` (termina con messaggio esplicito se manca qualcosa, in particolare `KHAEMHAT_SECRET_KEY`); 2. migrazione del database di sistema; 3. creazione del super utente da `KHAEMHAT_SUPERUSER*` (solo se `sys_users` è vuota; cambio password obbligatorio); 4. creazione della prima azienda da `KHAEMHAT_COMPANY_CODE` / `KHAEMHAT_COMPANY_NAME` (`CREATE DATABASE` o file SQLite), migrazione, tabelle di base (`KHAEMHAT_SEED_BASE`), dati demo se `KHAEMHAT_SEED_DEMO=true`; 5. le variabili di bootstrap vengono rilette solo se la tabella corrispondente è vuota. ## 6. Flusso di una richiesta ### 6.1 Interfaccia Blazor (circuito interattivo) ``` Browser ──HTTP──► Kestrel ──► SecurityHeadersMiddleware ──► TraceIdMiddleware ──► CookieSessionAuthenticationHandler (cookie HttpOnly, riga in user_sessions/sys_sessions) ──► MaintenanceMiddleware ──► pagina Razor prerender ──► circuito SignalR Circuito: CurrentUserAccessor + CompanyContextAccessor (azienda del circuito) ──► componente pagina (es. SaleDocumentPage) ── code-behind ──► servizio applicativo ──► PermissionAuthorizationHandler / [RequirePermission] / LicenseGate ──► IUnitOfWorkFactory.CreateAsync(Company(code)) ──► transazione ──► commit ──► audit_log · log di sezione · notifiche · invalidazione cache ``` - Il circuito verifica la sessione a ogni riconnessione (SPEC §7.3). - Nessuna logica nei `.razor`: code-behind + servizi (SPEC §19). L'interfaccia nasconde ciò che non è permesso, il server verifica sempre. - Ogni servizio applicativo è transazionale per operazione; motore documenti e contabile garantiscono atomicità di documento + magazzino + partite + registrazione + numerazione + allegati. ### 6.2 REST API ``` Client ──► /api/v1/... ──► TraceIdMiddleware ──► rate limiter per chiave ──► ApiKeyAuthenticationHandler (Bearer kh_…, hash SHA-256, IP consentiti, scadenza) oppure CookieSessionAuthenticationHandler ──► risoluzione X-Company ──► MaintenanceMiddleware (503 se in manutenzione) ──► [RequireModule] + [RequirePermission] ──► Endpoints ──► servizio applicativo ──► risposta JSON camelCase · ETag · errori RFC 9457 (ProblemDetailsMiddleware) con trace id ``` Il dettaglio dei contratti HTTP è in [API.md](API.md); MCP segue lo stesso percorso di autenticazione su `/mcp` ([MCP.md](MCP.md)). ## 7. Servizi trasversali ### 7.1 Cache (SPEC §9, M2) - `ICacheProvider`: `GetAsync`, `SetAsync` (TTL), `RemoveAsync`, `RemoveByPrefixAsync`, `GetOrCreateAsync`, `PublishInvalidationAsync`. - Implementazioni: `MemoryCacheProvider` (predefinita) e `RedisCacheProvider` (se `KHAEMHAT_REDIS` è valorizzata), con client RESP2 scritto in casa (`RespClient`, `RespReader`, `RespWriter`, `RedisConnectionPool`, `RedisSubscriber`) su `TcpClient`/`SslStream`. - Contenuto: tabelle di base, permessi, menu, piano dei conti, listini, licenze, ricerche recenti. Chiavi `kh:{azienda}:{area}:{key}`. - Se Redis cade l'app prosegue in memoria e lo segnala (barra di stato, *Stato sistema*, log). ### 7.2 Scheduler (SPEC §9, §12.5; base in M2, attività da UI in M12) - `JobRunner` in-process con `CronExpression` (sottoinsieme di cron) e `JobLock` nel database di sistema: ogni attività gira una sola volta anche tra riavvii. - Job di sistema: pulizia, verifica licenza, cambi BCE, inbox e canali SDI, coda e-mail, verifica giacenze, backup. - **Attività programmate** degli amministratori (`sys_scheduled_tasks`): tipi *backup*, *procedura*, *report via e-mail*, *notifica*, *import/export*, *verifica*, *script di manutenzione* dal catalogo interno (mai shell libera); timeout, retry, notifica esito, storico in `sys_job_runs`. ### 7.3 Log (SPEC §9.5, M2) - Un solo pipeline `ILogger` → `JsonConsoleFormatter` (una riga JSON su stdout) + `DbLogSink` in `sys_log`. - Ogni modulo scrive nella propria **sezione** (`LogSection`, `LogSectionScope`): Sistema, Autenticazione, Database, Migrazioni, Documenti, Contabilità, Magazzino, SDI/e-invoicing, CRM, Automazioni, Attività programmate, Backup, API/MCP, E-mail/PEC, Integrazioni, UI/circuiti, Prestazioni (`SlowQueryLogger`: query > 500 ms). - Correlazione con `trace_id` (generato da `TraceIdMiddleware`): compare negli errori mostrati all'utente ("Codice errore") e nelle risposte API. - Retention per livello (errori 365 gg, avvisi 180, info 90, debug 7) e regole di avviso (`LogAlertRules`). - Azioni di sicurezza e di istanza → `sys_security_audit` (immutabile); modifiche ai dati aziendali → `audit_log`. ### 7.4 Pacchetto fiscale (SPEC §1.10, M4 → M10) - `Application` conosce solo `Fiscal.Abstractions`: `IFiscalPack`, `ITaxEngine`, `ITaxCodeCatalog`, `IEInvoiceFormat`, `IEInvoiceNotificationReader`, `ISdiTransport`, `IFiscalReports`, `IFiscalCalendar`, `IWithholdingRules`, `IFixedAssetRules`, `IFinancialStatementsSchema`, `IChartOfAccountsTemplate`, `IIntrastatExporter`, `ITaxPaymentFormExporter`. - `Program.cs` registra `ItalyFiscalPack`; il pacchetto attivo per un'azienda è scelto da `company_profile.country` (`IT` → `ItalyFiscalPack`). Un altro paese sarà un nuovo progetto `Khaemhat.Fiscal.`. - Canali SDI: `ISdiTransport` con quattro implementazioni (`PecSdiTransport`, `SdiCoopTransport`, `IntermediaryATransport`, `IntermediaryBTransport`) e `SdiRouter` per le regole di instradamento. ### 7.5 Allegati e file generati (SPEC §9.4, M3) - Tabella `attachments` per azienda; un allegato appartiene **a un solo documento** (`entity`, `entity_id`). - File su volume: `/data/files///` tramite `IFileStore` (`VolumeFileStore`) con quota per azienda; upload in streaming, limite configurabile (25 MB), hook antivirus predisposto. - `FileGenerationService` + `GeneratedFileFactory`: ogni generazione (PDF, XML FatturaPA, XLSX/CSV, ZIP di cortesia, etichette, estratti conto, rapportini) crea un allegato **versionato** (`v1`, `v2`, …); "Rigenera" crea una nuova versione. Gli XML inviati sono `locked`. - Formati scritti in casa: `PdfWriter` (con `PdfA3Embedder`), `XlsxWriter`/`XlsxReader`, `CsvWriter`/`CsvReader`, `ZipStreamWriter`. Le stampe massive producono ZIP in streaming, mai file temporanei fuori da `/data`. ### 7.6 Backup e ripristino (SPEC §13, M12) | Motore | Backup | Verifica | Ripristino | |---|---|---|---| | PostgreSQL | `PgDumpRunner`: `pg_dump -Fc --no-owner --no-privileges` in streaming verso `/data/backups//bk--.dump` | `pg_restore --list` (`BackupVerifier`) | `PgRestoreRunner` in `khaemhat_restore_` + scambio atomico | | SQLite | `SqliteBackup`: `VACUUM INTO` | apertura e `integrity_check` | sostituzione del file in manutenzione | | Entrambi | backup logico JSON Lines + manifest (`LogicalBackupWriter`) | manifest + hash | `LogicalBackupReader` su database vuoto (anche SQLite → PostgreSQL) | - Ogni set ha `sha256`, cifratura AES-256-GCM (`BackupEncryptor`), copie remote su S3 compatibile (`S3Client`, `SigV4Signer`) e WebDAV (`WebDavClient`); retention GFS (`RetentionPolicy`); gli allegati dell'azienda sono inclusi. - Ripristino: manutenzione → backup di sicurezza → ripristino su database temporaneo → controllo schema e migrazioni → integrità → scambio → fine manutenzione; avviato da un amministratore e **confermato dal super utente** (notifica + TOTP). Il database di sistema si ripristina solo da CLI (`scripts/restore-system.sh`) a istanza ferma. ### 7.7 Sicurezza (SPEC §7, M2) - Cookie `HttpOnly; Secure; SameSite=Lax`, sessioni in tabella (revoca, dispositivi, IP), DataProtection con chiavi in `sys_data_protection_keys` (`DataProtectionDbXmlRepository`). - Password PBKDF2-SHA256 600.000 iterazioni (`PasswordHasher`), policy, storico, lockout, TOTP RFC 6238 (`TotpGenerator`) obbligatorio per account di istanza. - Chiavi API `kh_…` con hash SHA-256 (`ApiKeyHasher`), prefisso visibile, utente tecnico, permessi propri. - Header di sicurezza (`SecurityHeadersMiddleware`): CSP con nonce, `X-Frame-Options: DENY`, `Referrer-Policy`; HSTS dal reverse proxy. ## 8. Strato dati in breve - Micro-ORM interno: mappe esplicite `XxxMap : EntityMap`, `QueryBuilder` con un sottoinsieme sicuro di espressioni, il resto come `SqlFragment` parametrizzato; mai concatenazione di input utente. - Optimistic locking su `row_version` (`ConcurrencyException`). - SQLite: WAL, `foreign_keys=ON`, `busy_timeout=5000`, scritture serializzate da `SqliteWriteLock`, decimali come interi scalati x10⁶. - PostgreSQL: pool per database, `statement_timeout` per sessione, `pg_advisory_xact_lock` per numeratori, chiusure e scheduler; partizionamento annuale predisposto per le tabelle grandi. - Migrazioni in C# con due cataloghi (sistema, azienda) e `schema_version` per database. Convenzioni, tipi e tabelle: [DATA-MODEL.md](DATA-MODEL.md). ## 9. Struttura del repository Adattata da SPEC §4 con gli emendamenti E1 (Gitea) ed E2 (solo Docker). ``` Khaemhat/ ├── CLAUDE.md memoria di progetto ed emendamenti ├── README.md LICENSE CHANGELOG.md ├── Khaemhat.sln global.json Directory.Build.props Directory.Packages.props ├── .editorconfig .gitignore .dockerignore .gitattributes ├── assets/ icon.svg, icon-v1.0.svg, icon-mono.svg, PNG 16-512, favicon.ico ├── deploy/ │ ├── docker-compose.yml app + postgres + redis (profilo) │ ├── docker-compose.sqlite.yml demo autonoma SQLite │ ├── docker-compose.unraid.yml etichette net.unraid.docker.* │ ├── .env.example │ └── unraid/khaemhat.xml template Community Applications ├── docker/ │ ├── Dockerfile multi-stage, non root, HEALTHCHECK, postgresql-client-17 │ ├── entrypoint.sh attesa DB, migrazioni di sistema, bootstrap, avvio │ └── postgres/init.sql ├── .gitea/workflows/ │ ├── ci.yml build + test: PR verso main, push su main che toccano codice, tag v*, manuale │ ├── release.yml tag v* e manuale: immagine → registro pacchetti Gitea, release con note │ └── wiki.yml push su main che tocca docs/wiki/**: sincronizza Khaemhat.wiki.git ├── scripts/ │ ├── build.sh test.sh run-dev.sh check-packages.sh new-migration.sh │ ├── publish-image.sh build locale + push nel registro Gitea (alternativa a release.yml) │ ├── publish-wiki.sh push di docs/wiki nel wiki Gitea │ ├── gen-datamodel.sh genera docs/DATA-MODEL.md dalle mappe │ ├── restore-system.sh ripristino del database di sistema a istanza ferma │ └── seed.sh CLI: --base / --demo [--scale N] [--company CODE] ├── src/ │ ├── Khaemhat.Core/ Common/ Entities/ Enums/ Rules/ Validation/ Abstractions/ │ ├── Khaemhat.Fiscal.Abstractions/ │ ├── Khaemhat.Fiscal.Italy/ Vat/ FatturaPa/ Sdi/ Withholding/ F24/ Intrastat/ StampDuty/ │ │ FixedAssets/ FinancialStatements/ ChartOfAccounts/ Resources/ │ ├── Khaemhat.Data/ Khaemhat.Data.Sqlite/ Khaemhat.Data.PostgreSql/ │ ├── Khaemhat.Infrastructure/ Caching/ Security/ Licensing/ Mail/ Pdf/ Export/ Jobs/ Files/ │ │ Backup/ Http/ Mcp/ Logging/ Notifications/ │ ├── Khaemhat.Application/ Modules/ Documents/ Ledger/ Automation/ Seeding/ Search/ Audit/ │ │ │ Backup/ Licensing/ │ │ └── Modules/ Company/ Parties/ Items/ Sales/ Purchases/ Inventory/ Ledger/ Vat/ │ │ Assets/ Finance/ EInvoicing/ Crm/ Services/ Channels/ Reports/ │ │ Admin/ UserSettings/ │ └── Khaemhat.Web/ Program.cs Configuration/ Auth/ Api/ Mcp/ Help/ Components/ │ (App, Routes, Layout/, Ui/, Pages//, Shared/) Localization/ wwwroot/ ├── tests/ Core, Data, Infrastructure, Fiscal.Italy, Application, Web ├── tools/Khaemhat.LicenseTool/ └── docs/ ├── SPEC.md ARCHITECTURE.md DATA-MODEL.md MODULES.md API.md MCP.md ├── DEPLOY.md DEVELOPMENT.md SECURITY.md STATUS.md ├── adr/ ├── mockups/ mockup.css, png/ (22 + galleria), thumbs/ (88 miniature), README.md └── wiki/ sorgente della wiki Gitea ``` Differenze rispetto a SPEC §4: `.gitea/workflows/` al posto di `.github/workflows/`; registro pacchetti Gitea al posto di GHCR; nessun repository `khaemhat-assets` (icona servita come file raw del repository pubblico); `docs/SPEC.md` contiene la specifica e `CLAUDE.md` è breve (ADR 0011); `docs/mockups/thumbs/` aggiunta; `scripts/restore-system.sh` è citato in SPEC §13 e qui riportato nell'albero; è copiato nell'immagine in `/app/scripts/` (ADR 0017). Nessun installer né binario distribuito (ADR 0010). In più `.vscode/` (debug e attività di Visual Studio Code) e `.gitea/scripts/check-yaml.rb` (controllo YAML della CI). Le regole di dipendenza della §3 e l'allowlist dei pacchetti sono verificate da test: `Khaemhat.Core.Tests`, cartella `Architecture/`, legge i file di progetto e fallisce su ogni riferimento non ammesso. ## 10. Classi principali per progetto Riassunto per area dell'elenco normativo di SPEC §21 (che resta il riferimento completo). Le entità sono elencate in [DATA-MODEL.md](DATA-MODEL.md) accanto alle tabelle. ### 10.1 `Khaemhat.Core` | Area | Classi | |---|---| | Fondamenta | `Entity`, `IEntity`, `IAuditable`, `IDemoMarkable`, `Result`/`Result`, `Error`, `DomainException`, `ConcurrencyException`, `ModuleNotLicensedException`, `Guard` | | Value object | `Money`, `Quantity`, `Percentage`, `DiscountFormula` | | Contesto | `IClock`/`SystemClock`, `ICurrentUser`, `ICompanyContext`, `IEventBus`, `DomainEvent` | | Entità | tabelle azienda, anagrafiche, documenti, contabilità, finanza, e-invoicing, CRM/servizi/canali, utenti aziendali, sistema (vedi DATA-MODEL) | | Enum | `DbEngine`, `DatabaseScope`, `UserLevel`, `ModuleCode`, `DocumentKind`, `DocumentStatus`, `EInvoiceStatus`, `SdiChannelKind`, `TaxNature`, `LogSection`, `BackupTarget`, … | | Regole documenti | `DocumentTotalsCalculator`, `TaxSummaryBuilder`, `InstallmentGenerator`, `StampDutyRule`, `WithholdingCalculator`, `SocialSecurityCalculator`, `PriceResolver`, `DiscountResolver`, `StockEffectMatrix`, `UomConverter` | | Regole contabili | `JournalPostingRules`, `VatSettlementCalculator`, `ProRataCalculator`, `DepreciationCalculator`, `AccrualDeferralCalculator`, `ExchangeDifferenceCalculator` | | Regole finanza/CRM | `AgingCalculator`, `DunningRules`, `BankMatcher`, `LeadScoring` | | Formati e codici | `NumberFormatter`, `DocumentNumberFormat`, `CodeMaskFormatter` | | Dashboard | `TodoAggregator`, `DoneAggregator`, `DeadlineAggregator` | | Validatori | `ItalianVatNumberValidator`, `FiscalCodeValidator`/`FiscalCodeCalculator`, `IbanValidator`, `EanValidator`, `SdiRecipientCodeValidator`, `EmailValidator`, `JournalEntryValidator`, `ChartOfAccountsImportValidator`, `Validator`, `ValidationResult` | Nota: alcuni validatori di Core hanno nome "italiano" (`ItalianVatNumberValidator`, `FiscalCodeValidator`) pur stando fuori dal pacchetto fiscale: è la collocazione indicata da SPEC §21. ### 10.2 `Khaemhat.Fiscal.Abstractions` / `Khaemhat.Fiscal.Italy` | Area | Classi | |---|---| | Contratti | `IFiscalPack`, `ITaxEngine`, `ITaxCodeCatalog`, `IEInvoiceFormat`, `IEInvoiceNotificationReader`, `ISdiTransport`, `IFiscalReports`, `IFiscalCalendar`, `IWithholdingRules`, `IFixedAssetRules`, `IFinancialStatementsSchema`, `IChartOfAccountsTemplate`, `IIntrastatExporter`, `ITaxPaymentFormExporter` | | IVA | `ItalyFiscalPack`, `ItalianTaxEngine`, `ItalianTaxCodeCatalog`, `VatNatures`, `ReverseChargeRules`, `SplitPaymentRules`, `CashVatRules`, `VatSettlementRules`, `VatAdvanceCalculator`, `LipeWriter` | | FatturaPA | `FatturaPaWriter`, `FatturaPaReader`, `FatturaPaValidator`, `FatturaPaDocument`, `FatturaPaCodeLists` (con `SpecVersion`), `SdiFileNaming`, `SdiNotificationParser`, `P7mExtractor`, `CadesVerifier` | | Canali SDI | `PecSdiTransport`, `SdiCoopTransport`, `IntermediaryATransport`, `IntermediaryBTransport`, `SdiRouter` | | Ritenute e F24 | `WithholdingRulesIt`, `EnasarcoRules`, `CuExporter`, `F24Model`, `F24Codes`, `F24Exporter` | | Intrastat | `IntrastatModel`, `IntrastatExporterIt`, `CombinedNomenclature` | | Bollo, cespiti | `StampDutyRulesIt`, `FixedAssetRulesIt`, `MinisterialCoefficients` | | Bilancio | `CeeSchema2424`, `CeeSchema2425`, `FinancialRatios` | | Piano dei conti e dataset | `ItalianChartOfAccountsTemplate`, `ChartOfAccountsCsvFormat`, `ChartOfAccountsJsonFormat`, `MunicipalitiesDataset`, `AbiCabDataset` | ### 10.3 `Khaemhat.Data` e provider | Area | Classi | |---|---| | Contratti | `IDbProvider`, `ISqlDialect`, `ISchemaBuilder`, `IUnitOfWork`, `IUnitOfWorkFactory`, `IRepository<,>`, `Repository<,>`, `DatabaseUrl`, `DatabaseTarget`, `DbProviderCatalog` | | Registro database | `ICompanyRegistry`, `CompanyRegistry`, `IDatabaseLocator`, `DatabaseLocator`, `DatabaseScope`, `CompanyCodes` | | Mappe e query | `EntityMap`, `ColumnMap`, `ColumnType`, `MapRegistry`, `QueryBuilder`, `Query`, `PagedResult`, `SqlFragment`, `ExpressionTranslator` | | Esecuzione | `UnitOfWork`, `UnitOfWorkFactory`, `DataAccessContext` (orologio, utente, tentativi), `DbExecutor`, `ReaderMapper`, `CommandCache`, `TransientRetryPolicy` | | Migrazioni | `IMigration`, `MigrationAttribute`, `MigrationRunner`, `MigrationReport`, `MigrationCatalog` (`ForSystem`/`ForCompany`), `SchemaVersionStore`, `SchemaModel`, `DataModelDocument`, `TableDefinition`, `ColumnDefinition`, `IndexDefinition`, `ForeignKeyDefinition`, `DdlGenerator` | | SQLite | `SqliteProvider`, `SqliteDialect`, `SqliteSchemaBuilder`, `SqliteWriteLock`, `SqliteDecimalConverter` | | PostgreSQL | `PostgresProvider`, `PostgresDialect`, `PostgresSchemaBuilder`, `PostgresDatabaseCreator`, `PostgresAdvisoryLocks`, `PostgresPartitioning`, `PostgresServerInfo` | ### 10.4 `Khaemhat.Infrastructure` | Area | Classi | |---|---| | Cache | `ICacheProvider`, `MemoryCacheProvider`, `RedisCacheProvider`, `RespClient`, `RespReader`, `RespWriter`, `RedisConnectionPool`, `RedisSubscriber` | | Sicurezza | `PasswordHasher`, `PasswordPolicy`, `TotpGenerator`, `SecureTokenGenerator`, `ApiKeyHasher`, `DataProtectionDbXmlRepository`, `SecretProtector`, `SecretRotation` | | Licenze | `LicenseKey`, `LicenseDocument`, `LicenseVerifier`, `ModuleActivationCode`, `TestLicenseCatalog`, `ILicenseActivationService`, `OfflineActivationService`, `LicenseMonitor` | | Mail | `IMailSender`, `SmtpMailSender`, `MailQueue`, `MailTemplateRenderer`, `ImapClient`, `MimeParser` | | PDF ed export | `PdfWriter`, `PdfDocument`, `PdfPage`, `PdfFont`, `PdfTextLayout`, `PdfImage`, `PdfA3Embedder`, `CsvWriter`, `CsvReader`, `XlsxWriter`, `XlsxReader`, `ZipStreamWriter` | | Job | `IJobScheduler`, `JobRunner`, `JobDefinition`, `JobContext`, `CronExpression`, `JobLock` | | File | `IFileStore`, `VolumeFileStore`, `StoredFile`, `AttachmentStore`, `GeneratedFileFactory` | | Backup | `PgDumpRunner`, `PgRestoreRunner`, `SqliteBackup`, `LogicalBackupWriter`, `LogicalBackupReader`, `BackupEncryptor`, `S3Client`, `SigV4Signer`, `WebDavClient`, `RetentionPolicy`, `BackupVerifier` | | HTTP | `ViesClient`, `EcbRatesClient`, `GiteaPackagesClient` (al posto di `GhcrPackagesClient`, ADR 0009), `OutboundWebhookClient` | | MCP | `McpServer`, `JsonRpc*`, `McpTool`, `McpToolRegistry`, `McpSchemaGenerator` | | Log e notifiche | `DbLogSink`, `DbLoggerProvider`, `JsonConsoleFormatter`, `LogSectionScope`, `SlowQueryLogger`, `LogAlertRules`, `NotificationDispatcher` | ### 10.5 `Khaemhat.Application` | Area | Classi | |---|---| | Moduli | `IModule`, `ModuleRegistry`, `ModuleInfo`, `MenuItem`, `PermissionDefinition`, `HelpLink`, `LicenseGate` | | Motore documenti | `DocumentDefinition(s)`, `DocumentService<,>`, `DocumentFlowService`, `DocumentFlowWizard`, `FulfillmentCalculator`, `DocumentNumberingService`, `DocumentStateMachine`, `DocumentCopyService`, `DeferredInvoicingService`, `SelfInvoiceService` | | Contabilizzazione | `DocumentPostingService`, `InventoryPoster`, `InstallmentPoster`, `LedgerPoster`, `PostingEngine` | | Stampa, mail, file | `DocumentPrintService`, `IDocumentPrinter`, `HtmlDocumentPrinter`, `PdfDocumentPrinter`, `DocumentMailService`, `AttachmentService`, `FileGenerationService` | | Contabilità | `JournalService`, `PeriodLockService`, `LedgerQueries`, `PartitarioService`, `TrialBalanceService`, `FinancialStatementsService`, `RecurringEntriesService`, `ExchangeDifferenceService`, `ChartOfAccountsImportService`, `ClosingProcedure`/`ClosingStep`, `AccrualDeferralService` | | IVA e adempimenti | `VatRegisterService`, `VatSettlementService`, `StampDutyService`, `WithholdingService`, `IntrastatService`, `IntentDeclarationService` | | Cespiti | `FixedAssetService`, `DepreciationService` | | Tesoreria | `OpenItemService`, `PaymentService`, `RemittanceService`, `SddMandateService`, `BankStatementImportService`, `BankReconciliationService`, `DunningService`, `CashFlowForecastService`, `AgingReportService` | | E-invoicing | `EInvoiceService`, `EInvoiceExportService`, `SdiChannelService`, `SdiInboxService`, `SdiNotificationImportService`, `PurchaseInvoiceImportService`, `ConservationExportService` | | CRM | `LeadService`, `OpportunityService`, `PipelineService`, `ActivityService`, `CampaignService`, `TicketService`, `Party360Service`, `CrmDashboardService`, `SalesForecastService` | | Servizi e canali | `ContractService`, `InterventionService`, `InterventionSchedulingService`, `ServiceBillingService`, `IChannelConnector`, `GenericChannelConnector`, `ChannelOrderImportService`, `ChannelSyncService` | | Report e dashboard | `ReportDefinition`, `ReportRunner`, `ReportCatalog`, `ScheduledReportService`, `DashboardService`, `WidgetCatalog` | | Amministrazione | `SystemUserService`, `UserService`, `RoleService`, `PermissionService`, `SessionService`, `LicenseService`, `ModuleActivationService`, `CompanyService`, `MaintenanceModeService`, `DatabaseMaintenanceService`, `IntegrityCheckService`, `RebuildService`, `ScheduledTaskService`, `BackupService`, `RestoreService`, `SystemSettingsService`, `SecretRotationService`, `LogQueryService`, `LogAlertService`, `SystemStatusService`, `UpdateCheckService`, `ApiKeyService`, `WebhookService` | | Import | `ImportWizardService`, `CsvImportMapper`, `OpeningBalancesImportService` | | Automazioni | `CodeRuleService`, `CodeSequenceService`, `AutoFillService`, `RuleEngine`, `TriggerCatalog`, `ConditionEvaluator`, `ActionExecutor`, `ProcedureCatalog`, `IProcedure`, `ProcedureRunner` | | Preferenze | `UserSettingsService`, `CompanySettingsService` | | Seeding | `ISeeder`, `SeedRunner`, `SeedContext`, `BaseDataSeeder`/`DemoDataSeeder` per area, `DemoDataRemover` | | Trasversali | `GlobalSearchService`, `AuditTrailService` | ### 10.6 `Khaemhat.Web` | Area | Classi | |---|---| | Host | `Program`, `KhaemhatOptions`, `EnvironmentConfigurationReader`, `StartupOrchestrator`, `HealthEndpoints`, `MetricsEndpoint` | | Middleware | `MaintenanceMiddleware`, `TraceIdMiddleware`, `SecurityHeadersMiddleware`, `ProblemDetailsMiddleware` | | Autenticazione e autorizzazione | `CookieSessionAuthenticationHandler`, `ApiKeyAuthenticationHandler`, `SessionStore`, `CurrentUserAccessor`, `CompanyContextAccessor`, `PermissionAuthorizationHandler`, `RequirePermissionAttribute`, `RequireLevelAttribute`, `RequireModuleAttribute`, `LoginRateLimiter` | | API e MCP | `Endpoints`, `AttachmentEndpoints`, `OpenApiWriter`, `ApiDocsPage`, `McpEndpoint`, `WebhookEndpoints` | | Shell | `App`, `Routes`, `MainLayout`, `TopBar`, `CompanySwitcher`, `GlobalSearch`, `NotificationBell`, `UserMenu`, `KhSideMenu`, `KhTabHost`, `KhStatusBar` | | Dashboard | `Dashboard`, `DashboardCustomizer`, `KpiWidget`, `TodoWidget`, `DoneTodayWidget`, `DeadlinesWidget`, `FulfillmentWidget`, `RevenueChartWidget`, `CrmActivitiesWidget`, `PersonalNotesWidget`, `ShortcutsWidget`, … | | Componenti `Kh*` | libreria di SPEC §10.7 (`KhIconToolbar`, `KhDocHead`, `KhGrid`, `KhHotlink`, `KhKanban`, `KhLogViewer`, …) | | Pagine generiche | `DocumentPage<,>`, `MasterDataPage` | | Pagine per modulo | `PartyPage`, `ItemPage`, `SaleDocumentPage`, `PurchaseInvoiceImportPage`, `JournalEntryPage`, `VatSettlementPage`, `EInvoiceDashboard`, `PipelineBoard`, `Admin*Page`, … (elenco completo in SPEC §21) | | Servizi UI | `ITexts`, `JsonTextProvider`, `KeyboardShortcutService`, `ToastService`, `DialogService`, `DrawerService`, `TabService`, `PrintService`, `ThemeService`, `MenuStateService`, `HelpService` | ## 11. Regole di codice rilevanti per l'architettura (SPEC §19) - `record` per DTO e value object, `sealed` di default, `decimal` per importi e quantità (mai `double`). - Date: `DateOnly` / `DateTime` UTC; conversione a `Europe/Rome` solo in presentazione. - Async ovunque con `CancellationToken`; `Result` per esiti attesi, eccezioni di dominio localizzabili. - Validazione in `Core`/`Application`: l'interfaccia mostra, non decide. - Ogni file appartiene a un modulo; nessuna cartella `Utils`. Commenti solo per i *perché*; XML doc sui tipi pubblici di `Core`, `Data`, `Fiscal.Abstractions`. - Codice, commenti e commit in inglese; testi dell'interfaccia in italiano tramite `Resources/it-IT/*.json`. ## 12. Punti aperti | Punto | Nota | |---|---| | Modulo *Automation* | SPEC §4 colloca il motore in `Application/Automation/` e non elenca `Modules/Automation/`; serve comunque un `IModule` con codice `AUTO` per filtrare menu e procedure. Da fissare con un ADR in M12. | | Sezioni di log per anagrafiche, servizi e report | SPEC §9.5 non prevede sezioni dedicate; vedi le proposte in [MODULES.md](MODULES.md). | | Client aggiornamenti | `GhcrPackagesClient` di SPEC §21 è sostituito da `GiteaPackagesClient` (ADR 0009). |