Files
Khaemhat/docs/ARCHITECTURE.md
T
Alby96andClaude Opus 5.5 a9eda510f2 feat: postal codes from GeoNames for the ISTAT municipalities (#45)
The municipalities now come with their postal codes, so the lookup from
postal code works on a new company without loading anything. GeoNames
(CC BY 4.0) lists places rather than municipalities: a postal code goes
to a municipality only when the name and the province abbreviation match
exactly one of them (the name alone within Sardinia, whose abbreviations
changed), which covers 7,750 of 7,894 municipalities; the rest are mostly
renamed or merged ones that users complete by hand.

tools/Khaemhat.PlacesTool rebuilds both lists from the ISTAT sheet and
the GeoNames file, framework only, so the yearly update is repeatable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:16:07 +01:00

524 lines
41 KiB
Markdown

# 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:<versione>` | 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<T>`, `QueryBuilder<T>`, 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 |
| `tools/Khaemhat.PlacesTool` | rigenera province e comuni del pacchetto italiano dall'elenco ISTAT e dai CAP GeoNames (non distribuito, ADR 0028) | M4 |
| `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/<Nome>/` con struttura fissa (SPEC §4):
```
Modules/Sales/
├── Services/ casi d'uso (SaleDocumentService, …)
├── Dtos/ record di input/output
├── Validators/ Validator<T> 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/<Pagina>.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_<codice>` (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<T,TKey>` | 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: <codice>`; 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] ──► <Modulo>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.<Paese>`.
- 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/<azienda>/<yyyy>/<guid>` 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/<db>/bk-<db>-<timestamp>.dump` | `pg_restore --list` (`BackupVerifier`) | `PgRestoreRunner` in `khaemhat_restore_<ts>` + 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<Xxx>`, `QueryBuilder<T>` 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/<Modulo>/, Shared/) Localization/ wwwroot/
├── tests/ Core, Data, Infrastructure, Fiscal.Italy, Application, Web
├── tools/ Khaemhat.LicenseTool, Khaemhat.DataModelTool, Khaemhat.PlacesTool
└── 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<TKey>`, `IEntity<TKey>`, `IAuditable`, `IDemoMarkable`, `Result`/`Result<T>`, `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<T>`, `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<T>`, `ColumnMap`, `ColumnType`, `MapRegistry`, `QueryBuilder<T>`, `Query<T>`, `PagedResult<T>`, `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 | `<Modulo>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<T>` |
| 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<T>` 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). |