Files
Khaemhat/docs/SPEC.md
T
Alby96andClaude Opus 5.5 e746d99dab docs: add specification, design docs, mockups, wiki and deploy files
Prepare everything needed before development starts on Khaemhat, the
ERP + CRM for Italian SMEs:

- docs/SPEC.md: the original project specification, unchanged, plus
  CLAUDE.md with operational rules and amendments (Gitea instead of
  GitHub/GHCR, Docker image as the only deliverable).
- ADR 0001-0011 for the baseline decisions.
- Mockups: 22 high-resolution screens, the full gallery, 88 thumbnails
  cropped from it, mockup.css and an index.
- Technical docs (architecture, data model, modules, API, MCP, deploy,
  security, development process, status with open spec questions).
- Full draft wiki in docs/wiki (already published to the Gitea wiki).
- Icons in assets/ and deploy files for Docker Compose and Unraid,
  pointing to the Gitea package registry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 22:26:58 +01:00

1324 lines
140 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# KHAEMHAT — Prompt di progetto per Claude Code (CLAUDE.md)
> **Come usare questo file.** È il primo messaggio da incollare in Claude Code (VS Code) in una cartella vuota **e** il file `CLAUDE.md` da tenere nella root del repository: è la memoria di progetto e vale per ogni sessione. Le sezioni sono normative: dove dicono "deve" non c'è margine di interpretazione. Insieme a questo file vengono consegnati: le **88 schermate PNG** dei mockup (da copiare in `docs/mockups/png/`), il foglio di stile `mockup.css` (da copiare in `docs/mockups/`), le icone (`assets/`), i file di deploy per Unraid (`deploy/`). I riferimenti alle immagini in questo documento (`![…](docs/mockups/png/…)`) presuppongono quella posizione.
---
## 0. Missione
Sei l'architetto e lo sviluppatore principale di **Khaemhat**, un gestionale **ERP + CRM** per PMI italiane, da costruire **da zero** in questo repository, senza prendere a modello nessun software esistente: le specifiche sono tutte qui e nei mockup. Il nome viene da Khaemhat, scriba reale e sovrintendente ai granai dell'Alto e Basso Egitto sotto Amenhotep III (tomba TT57 a Tebe): un contabile dell'antichità. Namespace radice: `Khaemhat`. Immagine Docker: `khaemhat`. Prefisso variabili d'ambiente: `KHAEMHAT_`. Icona ufficiale: `assets/icon.svg` (§16.6).
L'aspetto da realizzare è quello dei **mockup in `docs/mockups/`** (§10): sono la specifica visiva vincolante; `docs/mockups/mockup.css` è il contratto dei token di design e dei componenti.
Lavori in autonomia. Non chiedere conferme: quando un punto è ambiguo decidi secondo questo documento, registra la scelta in `docs/adr/NNNN-titolo.md` (contesto, decisione, conseguenze) e prosegui. Fermati solo per blocchi reali (SDK mancante, credenziali assenti).
---
## 1. Vincoli non negoziabili
1. **Linguaggio e piattaforma:** C# 14 su .NET 10 (LTS). Un solo runtime, nessun altro linguaggio server-side. JavaScript solo dove Blazor non basta (interop minimo in `wwwroot/js`, senza framework né bundler).
2. **Nessuna libreria o componente esterno.** Tutta la logica applicativa è scritta nel repository. Sono ammessi esclusivamente:
- runtime e framework condivisi Microsoft (`Microsoft.NETCore.App`, `Microsoft.AspNetCore.App`): Blazor, Kestrel, Minimal API, autenticazione cookie, DataProtection, rate limiting, `Microsoft.Extensions.*` di piattaforma, `System.Text.Json`, `System.Security.Cryptography` (incl. `Pkcs` se in-box), `System.Formats.Asn1`, `System.IO.Compression`, `System.Xml`, `System.Net.Mail`, `System.Net.Http`, `System.Net.Sockets`;
- i due provider ADO.NET: `Npgsql` (PostgreSQL) e `Microsoft.Data.Sqlite` (SQLite, che porta con sé il motore nativo `e_sqlite3`);
- solo nei progetti di test (mai nell'immagine): `Microsoft.NET.Test.Sdk` + `MSTest`.
Qualunque altro pacchetto NuGet è vietato (ORM, mapper, validatori, logger, librerie UI/CSS, PDF, Redis, mail, OpenAPI, retry, scheduler, SDK cloud…): se ti serve una funzionalità coperta da una libreria, la scrivi tu in `Khaemhat.Infrastructure` o `Khaemhat.Data`. Niente CDN, font scaricati, script di terze parti nel browser.
Gli **strumenti di sistema operativo nell'immagine** (`postgresql-client` per `pg_dump`/`pg_restore`, `curl` per l'healthcheck, `tzdata`) sono ammessi: non sono componenti dell'applicazione. L'allowlist è codificata in `Directory.Packages.props` (Central Package Management) e verificata da `scripts/check-packages.sh`, che fa fallire la build se compare un `PackageReference` non ammesso.
3. **Database indifferente per il codice applicativo.** SQLite per test, demo, prova e archivi in sola lettura; PostgreSQL (versione minima **16**, consigliata 17) per le installazioni reali, fino a centinaia di GB. Nessun codice sopra lo strato dati conosce il motore in uso.
4. **Un database di sistema + un database per azienda** (§5.4). Più aziende possono essere collegate alla stessa istanza: condividono solo l'amministrazione (configurazione, super utente e amministratori, licenze, log di istanza). Utenti, preferenze per utente, dati e documenti di un'azienda stanno nel suo database. Le tabelle operative non hanno `company_id`.
5. **Distribuzione in Docker**, interfaccia via browser, configurazione iniziale solo tramite variabili d'ambiente; tutto il resto dal pannello di amministrazione. **Nessun file temporaneo con impostazioni o dati utente**: preferenze nel database, chiavi DataProtection nel database di sistema, log su stdout e nel database, niente `appsettings.<Env>.json` con segreti, nessuna scrittura fuori da `KHAEMHAT_DATA_DIR`. Cookie ammessi (sessione, tema prima del login).
6. **Redis opzionale.** Se `KHAEMHAT_REDIS` è valorizzata la cache distribuita usa Redis tramite un client RESP scritto nel progetto; altrimenti cache in memoria. Comportamento funzionale identico.
7. **Non personalizzabile** in questa versione: niente plugin, campi custom, scripting utente o editor di layout. L'architettura resta modulare internamente (registro moduli statico); la configurabilità ammessa è quella delle preferenze (§11.12) e della dashboard (§10.3).
8. **Moduli attivabili tramite licenza** (§8): ogni modulo funzionale è dietro un codice di licenza attivabile solo dalla pagina di amministrazione dell'istanza (super utente). In sviluppo e test valgono le licenze fittizie fisse di §8.3.
9. **Codice in inglese** (identificatori, commenti, commit), **interfaccia in italiano** tramite risorse (`it-IT` unica lingua fornita; infrastruttura pronta per altre).
10. **Fiscalità per paese isolata in un pacchetto.** Tutto ciò che è specifico dell'Italia sta in `Khaemhat.Fiscal.Italy` dietro le interfacce di `Khaemhat.Fiscal.Abstractions`; il resto del gestionale non conosce l'Italia. Altri paesi saranno nuovi pacchetti.
11. **Qualità:** `Nullable` abilitato, `TreatWarningsAsErrors`, analyzer .NET di piattaforma, `.editorconfig`, nessun `#pragma warning disable` senza motivazione.
12. **Documentazione sempre aggiornata.** Ogni funzione nuova o modificata aggiorna, nella stessa unità di lavoro: la pagina wiki in `docs/wiki/`, i file in `docs/` toccati, `CHANGELOG.md` e, se l'interfaccia cambia, gli screenshot (§17). Una funzione senza documentazione non è finita (§20).
13. **Repository e CI su GitHub** con **minuti di CI contati** (§16.3): i workflow girano solo quando serve, le immagini si costruiscono di norma in locale con lo script fornito.
---
## 2. Decisioni tecnologiche
| Area | Decisione | Motivo |
|---|---|---|
| Host | ASP.NET Core 10 su Kestrel, un processo per istanza | Un container serve più aziende; nessuno scale-out orizzontale |
| UI | **Blazor Web App, render mode Interactive Server** su tutta l'app, componenti scritti in casa secondo `docs/mockups/mockup.css` | Modello a componenti ricco senza librerie JS; SignalR è di piattaforma. Con più repliche servirebbero sessioni sticky: non è il caso d'uso |
| API | Minimal API REST `/api/v1` + endpoint MCP `/mcp` | Integrazioni (sito web, e-commerce, agenti AI) senza dipendere dall'UI |
| Accesso dati | Micro-ORM interno (`Khaemhat.Data`): mappe esplicite per entità, query builder tipizzato, migrazioni in C# con DDL generato per dialetto | Nessun ORM esterno; controllo su SQL e prestazioni |
| Database | Sistema (`khaemhat_system`) + uno per azienda; registry nel sistema; segreti cifrati con chiave da `KHAEMHAT_SECRET_KEY` | Multi-azienda con amministrazione condivisa |
| Autenticazione | Cookie ASP.NET Core; account di istanza (super utente, amministratori) nel DB di sistema; utenti nel DB dell'azienda; PBKDF2-SHA256 (600.000 iterazioni, salt 16 byte), lockout, TOTP (RFC 6238 in casa) | Nessuna dipendenza da Identity/EF |
| Licenze | Codici modulo firmati ECDSA P-256 (file `.khl` / stringa); modalità test con codici fissi | §8 |
| Cache | `ICacheProvider` → `MemoryCacheProvider` / `RedisCacheProvider` (client RESP2 su `TcpClient`/`SslStream`, pool, pub/sub) | Redis opzionale |
| Scheduler | `JobRunner` in-process con cron (sottoinsieme) + **attività programmate** definite dagli amministratori da UI, persistite nel DB di sistema con lock | §12.5 |
| Backup | `pg_dump`/`pg_restore` (`-Fc`) come processo dal container + backup logico JSON Lines portabile + `VACUUM INTO` per SQLite; pianificati, verificati, retention GFS, copie su S3 compatibile (SigV4 in casa) e WebDAV | §13 |
| Log | Log strutturato per **sezione** su stdout (JSON) e nel DB di sistema, con filtri, dettaglio, retention per livello e regole di avviso | §9.5 |
| PDF e file | `PdfWriter` interno (font Type1 standard, testo, linee, rettangoli, JPEG, PDF/A-3 per allegati XML); XLSX/CSV/ZIP/XML generati in casa; ogni file generato o caricato è un **allegato del solo documento** a cui appartiene | §9.4 |
| Stampe | Template HTML/CSS stampabili dal browser + PDF con `PdfWriter`, un solo modello dati per report | Doppio canale |
| E-mail / PEC | `System.Net.Mail.SmtpClient` con STARTTLS/SSL; **client IMAP minimale in casa** per leggere le notifiche SDI dalla PEC | Canale SDI via PEC integrato |
| SDI | `ISdiTransport` con 4 implementazioni: PEC (integrata), SdICoop (web service AdE), intermediario A, intermediario B | §11.9 |
| Firma/verifica | ECDSA P-256 (licenze), SHA-256 (backup, allegati), verifica CAdES dei P7M | In-box |
| Test | MSTest; SQLite in-memory sempre; PostgreSQL con `KHAEMHAT_TEST_PG`; Redis con `KHAEMHAT_TEST_REDIS` | Entrambi i dialetti |
| Versioning | SemVer da git tag in `Directory.Build.props`; `--build-arg VERSION` nel Dockerfile; versione mostrata nell'icona versionata e nella barra | Nessun pacchetto |
---
## 3. Architettura a livelli
```
┌───────────────────────────────────────────────────────────────────────┐
│ Khaemhat.Web UI Blazor · REST API · MCP · Auth · Host · Help │
├───────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Application Casi d'uso per modulo · DTO · Permessi · │
│ Motore documenti · Motore contabile · Procedure · │
│ Automazioni · Seeder · Report · Backup orchestr. │
├───────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Fiscal.Abstractions interfacce paese (IVA, e-invoice, ...) │
│ Khaemhat.Fiscal.Italy FatturaPA · TD · F24 · LIPE · Intrastat │
│ · ritenute · cespiti · bilancio CEE │
├───────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Core Entità · Value object · Enum · Regole di dominio │
│ · Calcoli · Validatori · Partita doppia │
├───────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Infrastructure Cache/Redis · Crypto · Licenze · Mail/IMAP · │
│ PDF · XLSX/CSV · Job · File · Backup (pg_dump, │
│ S3, WebDAV) · MCP protocol · Http (VIES, BCE, │
│ GitHub packages, intermediari SDI) │
├───────────────────────────────────────────────────────────────────────┤
│ Khaemhat.Data Astrazioni DB · Query builder · Mappe · │
│ Migrazioni · Unit of work · Registry database │
│ Khaemhat.Data.Sqlite │ Khaemhat.Data.PostgreSql │
└───────────────────────────────────────────────────────────────────────┘
```
Regole di dipendenza (verificate da test di architettura in `Khaemhat.Core.Tests`):
- `Core` non dipende da nulla. `Fiscal.Abstractions` dipende da `Core`. `Fiscal.Italy` dipende da `Core`, `Fiscal.Abstractions`, `Infrastructure` (solo XML/PDF/crypto/HTTP).
- `Data` dipende da `Core` e `System.Data.Common`; `Data.Sqlite`/`Data.PostgreSql` da `Data` e dal rispettivo provider; nessun altro progetto referenzia i provider.
- `Infrastructure` dipende da `Core` e `Data`. `Application` dipende da `Core`, `Data`, `Infrastructure`, `Fiscal.Abstractions` (mai da `Fiscal.Italy`: il pacchetto paese è registrato in `Program.cs` e risolto per `company_profile.country`).
- `Web` dipende da `Application` e registra i provider concreti in `Program.cs`.
Ogni modulo implementa `IModule` (in `Application.Modules`): codice modulo per la licenza (§8), nome, ordine, voci di menu, permessi, migrazioni, seeder *base* e *demo*, endpoint API, tool MCP, procedure, eventi per le automazioni, sezione di log, pagine wiki. `ModuleRegistry` li enumera staticamente e li filtra per licenza attiva.
---
## 4. Struttura del repository
```
khaemhat/
├── CLAUDE.md ← questo file
├── 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 (versionata), icon-mono.svg, icon-{512,256,128,64,32,16}.png,
│ icon-v1.0-{512,256,128,64}.png, favicon.ico
├── deploy/
│ ├── docker-compose.yml ← app + postgres + redis (profili)
│ ├── docker-compose.sqlite.yml ← demo autonoma SQLite
│ ├── docker-compose.unraid.yml ← etichette net.unraid.docker.* (icona e WebUI)
│ ├── .env.example
│ └── unraid/khaemhat.xml ← template Community Applications
├── docker/
│ ├── Dockerfile ← multi-stage, non root, HEALTHCHECK, postgresql-client
│ ├── entrypoint.sh ← attesa DB, migrazioni di sistema, bootstrap, avvio
│ └── postgres/init.sql
├── .github/workflows/
│ ├── ci.yml ← build + test, solo su PR verso main e push di tag (minuti contati)
│ ├── release.yml ← solo manuale (workflow_dispatch) o tag v*: immagine → GHCR
│ └── wiki.yml ← solo quando cambia docs/wiki: sincronizza il wiki GitHub (job da pochi secondi)
├── scripts/
│ ├── build.sh test.sh run-dev.sh check-packages.sh new-migration.sh
│ ├── publish-image.sh ← build locale + push su GHCR (percorso normale di rilascio)
│ ├── publish-wiki.sh ← push di docs/wiki nel repo <repo>.wiki.git
│ ├── gen-datamodel.sh ← DATA-MODEL.md dalle mappe
│ └── 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/ (PEC, SdICoop, intermediari) Withholding/ F24/ Intrastat/
│ │ StampDuty/ FixedAssets/ FinancialStatements/ ChartOfAccounts/ Resources/
│ ├── Khaemhat.Data/ Khaemhat.Data.Sqlite/ Khaemhat.Data.PostgreSql/
│ ├── Khaemhat.Infrastructure/ ← Caching/ Security/ Licensing/ Mail/ (Smtp, Imap) 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/ (ognuno: Services/ Dtos/ Validators/ Migrations/
│ │ Seed/Base/ Seed/Demo/ Reports/ Api/ Mcp/ Procedures/ Permissions.cs Menu.cs <Nome>Module.cs)
│ └── Khaemhat.Web/ ← Program.cs Configuration/ Auth/ Api/ Mcp/ Help/ Components/ (App, Routes, Layout/,
│ Ui/ = componenti Kh*, Pages/<Modulo>/, Shared/) Localization/ wwwroot/
├── tests/ (Core, Data, Infrastructure, Fiscal.Italy, Application, Web)
├── tools/Khaemhat.LicenseTool/ ← CLI: coppia chiavi, emissione/verifica licenze (chiave privata mai nel repo)
└── docs/
├── ARCHITECTURE.md DATA-MODEL.md MODULES.md API.md MCP.md DEPLOY.md DEVELOPMENT.md SECURITY.md STATUS.md
├── adr/
├── mockups/ ← mockup.css + png/ (88 schermate + galleria) + README.md (indice, §10.1)
└── wiki/ ← Home.md, _Sidebar.md, una pagina per argomento (sincronizzata nel wiki GitHub)
```
---
## 5. Strato dati (`Khaemhat.Data`)
### 5.1 Contratti
```csharp
public interface IDbProvider {
DbEngine Engine { get; } ISqlDialect Dialect { get; } ISchemaBuilder SchemaBuilder { get; }
DbConnection CreateConnection(string connectionString);
Task EnsureDatabaseExistsAsync(string connectionString, CancellationToken ct); // CREATE DATABASE se manca
Task DropDatabaseAsync(string connectionString, CancellationToken ct); // solo da RestoreService/CompanyRegistry
Task<DbServerInfo> GetServerInfoAsync(string connectionString, CancellationToken ct); // versione, dimensioni, connessioni
}
public interface ISqlDialect {
string Quote(string identifier); string Parameter(string name); string Paging(int offset, int limit);
string InsertReturningId(string table, ...); string Upsert(...); string CaseInsensitiveLike(string column);
string CurrentTimestampUtc { get; } string AdvisoryLock(string key);
object ToDbValue(object? value, ColumnType type); object? FromDbValue(object? value, ColumnType type);
string SqlType(ColumnType type, int? length, int? scale);
}
public interface IUnitOfWork : IAsyncDisposable {
DbConnection Connection { get; } DbTransaction? Transaction { get; }
Task BeginAsync(); Task CommitAsync(); Task RollbackAsync();
IRepository<T, TKey> Repository<T, TKey>() where T : class, IEntity<TKey>;
Task<int> ExecuteAsync(SqlFragment sql); Task<T?> QuerySingleAsync<T>(SqlFragment sql);
Task<IReadOnlyList<T>> QueryAsync<T>(SqlFragment sql); Task<DbDataReader> StreamAsync(SqlFragment sql);
}
public interface IRepository<T, TKey> {
Task<T?> GetAsync(TKey id); Task<T?> FindAsync(Query<T> query); Task<PagedResult<T>> ListAsync(Query<T> query);
Task<TKey> InsertAsync(T entity); Task UpdateAsync(T entity); // controllo row_version
Task DeleteAsync(TKey id); Task<int> CountAsync(Query<T> query);
}
public interface IUnitOfWorkFactory { Task<IUnitOfWork> CreateAsync(DatabaseScope scope); } // System oppure Company(code)
```
### 5.2 Convenzioni
- Tabelle e colonne `snake_case`; PK `id BIGINT` identity; colonne di audit `created_at`, `created_by`, `updated_at`, `updated_by`, `row_version` (optimistic locking: `UPDATE … WHERE id=@id AND row_version=@v`; su conflitto `ConcurrencyException`). Tabelle del database di sistema con prefisso `sys_`.
- Tipi logici `ColumnType`: `String(n)`, `Text`, `Int32`, `Int64`, `Decimal(19,6)`, `Bool`, `Date`, `DateTimeUtc`, `Guid`, `Bytes`, `Json`. Mappatura: PostgreSQL `varchar(n)/text/int/bigint/numeric(19,6)/boolean/date/timestamptz/uuid/bytea/jsonb`; SQLite `TEXT/TEXT/INTEGER/INTEGER/INTEGER (scalato ×10⁶)/INTEGER 0-1/TEXT yyyy-MM-dd/TEXT ISO 8601 UTC/TEXT/BLOB/TEXT`. Le somme in SQL su SQLite operano su interi scalati e vengono riscalate in lettura.
- Ogni entità ha `XxxMap : EntityMap<Xxx>` (tabella, colonne, chiave, indici, FK, conversioni). Nessuna riflessione a runtime oltre la costruzione iniziale.
- `QueryBuilder<T>`: sottoinsieme sicuro di espressioni (uguaglianza, confronto, `Contains`/`StartsWith`, `In`, `And/Or/Not`, `IsNull`); il resto come `SqlFragment` parametrizzato. Mai concatenazione di input utente in SQL.
- SQLite: `journal_mode=WAL; foreign_keys=ON; busy_timeout=5000`; scritture serializzate da `SqliteWriteLock`. PostgreSQL: pooling (pool separato per database, `MaxPoolSize` per database da impostazioni), `statement_timeout` per sessione, `pg_advisory_xact_lock` per numeratori, chiusure e scheduler.
- Tabelle grandi (`gl_entry_lines`, `inventory_entry_lines`, `audit_log`, `sys_log`) con indici per data/esercizio; partizionamento per anno su PostgreSQL predisposto dal `SchemaBuilder` e attivabile da migrazione oltre i 50 M righe.
### 5.3 Migrazioni
- Classi `[Migration(20261013_001, "create_parties")] class M20261013_001 : IMigration` con `Up(ISchemaBuilder sb)` e `UpSql(ISqlDialect d)`. Due cataloghi: **sistema** e **azienda**. Ogni database ha la propria tabella `schema_version(module, version, name, applied_at, checksum)`.
- `MigrationRunner` applica in transazione, è idempotente, rifiuta di partire se trova versioni applicate non note (downgrade non supportato) e registra l'esito nel log di sistema (sezione *Migrazioni*). All'avvio migra il database di sistema; le aziende vengono migrate all'avvio (impostazione) o dal pannello (§12.1), con modalità manutenzione per quell'azienda.
- Test obbligatorio: tutte le migrazioni da zero su SQLite e PostgreSQL, `schema_version` coerente, riapplicazione senza effetti.
### 5.4 Database di sistema e database aziendali
- **`khaemhat_system`** (`KHAEMHAT_SYSTEM_DB`): `sys_companies` (codice, ragione sociale, motore, connection string **cifrata**, stato *attiva/manutenzione/sola lettura/disattivata*, predefinita, note), `sys_users` (super utente e amministratori), `sys_roles_templates`, `sys_settings`, `sys_licenses` e `sys_license_activations`, `sys_scheduled_tasks`, `sys_job_runs`, `sys_backup_policies`, `sys_backup_sets`, `sys_log`, `sys_security_audit`, `sys_data_protection_keys`, `sys_api_keys` (istanza), `sys_notifications` (amministratori), `sys_sessions` (account di istanza).
- **`khaemhat_<codice>`** per azienda: tutte le tabelle operative + `users`, `roles`, `role_permissions`, `user_roles`, `user_permission_overrides`, `user_sessions`, `user_settings`, `api_keys`, `notifications`, `attachments`, `audit_log`, `company_profile`.
- `ICompanyRegistry` (sistema) risolve `companyCode → (IDbProvider, connection string decifrata)`; `ICompanyContext` è per-circuito Blazor e per-richiesta API (header `X-Company`). Un utente di istanza sceglie l'azienda dalla barra superiore; un utente aziendale è vincolato alla sua.
- Segreti (connection string delle aziende, password SMTP/PEC/S3/WebDAV, token degli intermediari, credenziali canali) cifrati con AES-256-GCM e chiave derivata da **`KHAEMHAT_SECRET_KEY`** (obbligatoria, ≥ 32 byte base64); senza chiave l'app non parte. Le chiavi DataProtection (cookie) stanno in `sys_data_protection_keys`.
- Bootstrap al primo avvio: migra il sistema → crea il super utente da env → crea la prima azienda da `KHAEMHAT_COMPANY_CODE/NAME` (CREATE DATABASE sul server di `KHAEMHAT_DB_SERVER` o SQLite) → migra → tabelle di base → (demo se richiesto). Le variabili vengono rilette solo se la tabella corrispondente è vuota.
---
## 6. Configurazione (variabili d'ambiente)
| Variabile | Obbl. | Esempio / default | Note |
|---|---|---|---|
| `KHAEMHAT_SYSTEM_DB` | sì | `postgres://khaemhat:secret@khaemhat-db:5432/khaemhat_system` oppure `sqlite:///data/system.db` | Database di sistema. Variante `_FILE` per Docker secrets |
| `KHAEMHAT_DB_SERVER` | sì con PostgreSQL | `postgres://khaemhat:secret@khaemhat-db:5432/` | Server su cui creare i database aziendali (ruolo con `CREATEDB`); se assente, usa host/credenziali del sistema |
| `KHAEMHAT_SECRET_KEY` | sì | base64 di 32+ byte | Cifratura dei segreti nel DB di sistema; cambiarla richiede la procedura di rotazione (§12.9) |
| `KHAEMHAT_SUPERUSER` `KHAEMHAT_SUPERUSER_PASSWORD` `KHAEMHAT_SUPERUSER_EMAIL` | sì al primo avvio | `root` / … | Usate **solo al primo avvio** per creare il super utente (hash nel DB); poi ignorate; cambio password obbligatorio al primo accesso; varianti `_FILE` |
| `KHAEMHAT_COMPANY_CODE` `KHAEMHAT_COMPANY_NAME` | sì al primo avvio | `DEMO` / `Khaemhat Demo S.r.l.` | Prima azienda (database `khaemhat_demo`); le altre dal pannello |
| `KHAEMHAT_COUNTRY` | no | `IT` | Pacchetto fiscale della prima azienda |
| `KHAEMHAT_LICENSE_MODE` | no | `production` | `test` abilita i codici fittizi di §8.3 (mai in produzione) |
| `KHAEMHAT_LICENSE` | no | testo licenza `.khl` | Assente = *Trial* (moduli CORE+ACCT, 3 utenti, 60 giorni, banner) |
| `KHAEMHAT_REDIS` | no | `redis://:pwd@khaemhat-redis:6379/0` (`rediss://` TLS) | Assente = cache in memoria |
| `KHAEMHAT_DATA_DIR` | no | `/data` | SQLite, allegati (`/data/files/<azienda>`), backup (`/data/backups/<db>`), inbox SDI (`/data/inbox/sdi/<azienda>`), export in streaming |
| `KHAEMHAT_URLS` | no | `http://0.0.0.0:8080` | TLS terminato dal reverse proxy |
| `KHAEMHAT_PUBLIC_URL` | no | `https://gestionale.example.com` | Link nelle e-mail e nelle notifiche |
| `KHAEMHAT_SMTP_*` | no | `HOST PORT USER PASSWORD FROM SECURITY` | Sovrascrivibili dalle Impostazioni (cifrate) |
| `KHAEMHAT_LOG_LEVEL` | no | `Information` | Livello minimo su stdout; il DB segue la retention per sezione |
| `KHAEMHAT_SEED_BASE` / `KHAEMHAT_SEED_DEMO` | no | `true` / `false` | Tabelle di base alla creazione; dati dimostrativi solo su database vuoto |
| `KHAEMHAT_UPDATE_FEED` `KHAEMHAT_UPDATE_TOKEN` | no | `https://api.github.com/users/<owner>/packages/container/khaemhat/versions` + token `read:packages` | Controllo aggiornamenti (sola lettura) |
| `TZ` `PUID` `PGID` | no | `Europe/Rome` `99` `100` | Fuso orario; utente/gruppo per i file in `/data` |
| `KHAEMHAT_TEST_PG` `KHAEMHAT_TEST_REDIS` | solo test | URL | Test d'integrazione |
`Program.cs` valida tutto all'avvio con `KhaemhatOptions.Validate()` e termina con messaggio esplicito se manca qualcosa. Nessun valore è scritto su disco.
---
## 7. Utenti, livelli, permessi e sicurezza
### 7.1 Tre livelli
| Livello | Dove vive | Può | Non può |
|---|---|---|---|
| **Super utente** (`SuperUser`) | DB di sistema; uno solo, creato dalle variabili del container; non eliminabile né degradabile | tutto: creare/eliminare **amministratori**, attivare moduli e licenze, creare/eliminare/clonare database aziendali, cambiare impostazioni critiche (SMTP, chiavi, cloud backup), ripristinare backup, modalità manutenzione, rimuovere dati demo, rotazione segreti, vedere ogni log | — |
| **Amministratore** (`Administrator`) | DB di sistema; creati dal super utente | istanza e database (migrazioni, manutenzione, backup e copie remote, verifica; **ripristino solo con conferma del super utente**), utenti di ogni azienda, ruoli (mai superiori ai propri), attività programmate, impostazioni azienda e sistema non critiche, log, stato sistema, dati di base | creare amministratori, toccare il super utente, attivare moduli/licenze, eliminare database |
| **Utente** (`Standard`) | DB dell'azienda; creati dagli amministratori (o da un utente con permesso `company.users.manage`) | operare entro i permessi dei ruoli; profilo, preferenze e sessioni proprie | qualunque funzione di istanza |
Modello: `sys_users` (istanza, `level`) e `users` (azienda, `kind = Human | Technical` per API). Un amministratore può essere "collegato" a un utente aziendale per operare come tale senza secondo login. La pagina di accesso (mockup 001) chiede azienda, utente e password: gli account di istanza vengono riconosciuti dal DB di sistema e, se scelgono un'azienda, entrano con i permessi completi su di essa.
### 7.2 Permessi
Codici `modulo.entità.azione` (es. `sales.invoice.issue`, `ledger.entry.finalize`, `vat.settlement.confirm`, `inventory.entry.post`, `crm.opportunity.write`, `attachments.delete`, `items.cost.read`, `company.users.manage`). Azioni standard: `read`, `write`, `delete`, `post`/`issue`/`finalize`, `reopen`, `export`, `print`, `override_*`. Ruoli predefiniti (modelli nel DB di sistema, copiati nelle aziende; clonabili, non modificabili): Amministrazione, Contabilità, Vendite, Acquisti, Magazzino, CRM, Servizi, Sola lettura. Flag per utente: vede solo i propri clienti (agenti), vede costi e margini, può esportare, può usare le API. L'UI nasconde ciò che non è permesso; il server verifica sempre (`[RequirePermission]`, `[RequireLevel]`, `PermissionAuthorizationHandler`). Un modulo non licenziato è equivalente a permesso negato (`module_not_licensed`).
### 7.3 Sessioni, password, API
- Cookie `HttpOnly; Secure; SameSite=Lax`, id 256 bit, riga di sessione (revoca, elenco per utente, dispositivo, IP, avviso nuovi dispositivi), scadenza scorrevole; il circuito Blazor verifica la sessione a ogni riconnessione. Limite utenti concorrenti da licenza, conteggiato sulle sessioni attive di tutte le aziende.
- Password: policy (default 10 caratteri, 3 classi), storico 5, scadenza opzionale, blocco 5 tentativi/15 min, rate limiting IP su `/login` e `/api`; **TOTP obbligatorio per super utente e amministratori** (configurabile per gli utenti); recupero via e-mail con token monouso; password provvisorie monouso.
- API: chiavi `kh_…` (hash SHA-256, prefisso visibile), legate a utente tecnico, permessi propri, azienda, scadenza, IP consentiti.
- Audit: ogni insert/update/delete su anagrafiche, documenti, registrazioni e impostazioni → `audit_log` dell'azienda (`entity, entity_id, action, user, at, diff JSON`), visibile dal record ("Storico"); azioni di sicurezza e di istanza (login, permessi, licenze, backup, ripristini, database, manutenzione) → `sys_security_audit` immutabile.
- Header: CSP (self + nonce per Blazor), `X-Frame-Options: DENY`, `Referrer-Policy`, HSTS dal proxy. Antiforgery sui form statici.
---
## 8. Licenze e moduli
### 8.1 Moduli
| Codice | Modulo | Contenuto |
|---|---|---|
| `CORE` | Base | anagrafiche, articoli e listini, preventivi/ordini/DDT/fatture, acquisti base, magazzino, tabelle, report base, amministrazione, allegati |
| `ACCT` | Contabilità | piano dei conti, causali, prima nota, partitari, registri IVA, liquidazioni, LIPE/F24 dati, ritenute e casse, bollo, chiusura esercizio, bilancio CEE |
| `ASSET` | Cespiti | registro beni ammortizzabili, ammortamenti, dismissioni |
| `FIN` | Tesoreria | scadenzario, incassi/pagamenti, RiBa/SDD/SEPA, riconciliazione bancaria, solleciti, flusso di cassa |
| `EINV` | Fatturazione elettronica | XML attivo/passivo, canali SDI (PEC integrata, SdICoop, intermediari), notifiche, autofatture, dichiarazioni d'intento, bollo virtuale |
| `INTRA` | Intrastat | elenchi cessioni/acquisti e file Agenzia Dogane |
| `CRM` | CRM | lead, pipeline/opportunità, attività e agenda, campagne, ticket |
| `SVC` | Servizi | contratti di assistenza, squadre, interventi, rapportini |
| `CHAN` | Canali e-commerce | connettore generico, ordini web, sincronizzazione giacenze/prezzi |
| `AUTO` | Automazioni | regole quando→se→allora, procedure pianificabili oltre quelle di sistema |
| `API` | Integrazioni | API REST, MCP, webhook, chiavi API |
| `MULTI` | Multi-azienda | aziende oltre la prima sulla stessa istanza |
| `REPORT` | Report avanzati | margini, analisi, report pianificati, export per il commercialista |
Senza modulo attivo: voci di menu nascoste, API/MCP del modulo non registrati, procedure non eseguibili, dati conservati.
### 8.2 Formato e verifica
- Licenza di istanza: JSON firmato ECDSA P-256 in file `.khl` (`licensee`, `instanceId` opzionale, `issuedAt`, `expiresAt`, `maxConcurrentUsers`, `maxCompanies`, `modules[]`, `gracePeriodDays`), chiave pubblica nel binario, privata solo in `tools/Khaemhat.LicenseTool` (mai nel repository).
- Codice di attivazione singolo modulo: `KH<v>-<MODULO>-<AAAAMM>-<payload base32>-<firma>`; verificato offline. In futuro `ILicenseActivationService` userà un server di attivazione (attiva/disattiva da remoto, tracciamento, heartbeat): già previsto come interfaccia, implementazione `OfflineActivationService` oggi.
- Attivazione **solo** dalla pagina *Amministrazione › Licenze e moduli* del super utente (mockup 080); storico attivazioni in `sys_license_activations`; verifica all'avvio, al login e ogni ora; oltre scadenza + grazia: sola lettura con banner.
### 8.3 Licenze fittizie per test (valide solo con `KHAEMHAT_LICENSE_MODE=test`)
`KH-TEST-CORE-0000-0001` · `KH-TEST-ACCT-0000-0002` · `KH-TEST-ASSET-0000-0003` · `KH-TEST-FIN-0000-0004` · `KH-TEST-EINV-0000-0005` · `KH-TEST-INTRA-0000-0006` · `KH-TEST-CRM-0000-0007` · `KH-TEST-SVC-0000-0008` · `KH-TEST-CHAN-0000-0009` · `KH-TEST-AUTO-0000-0010` · `KH-TEST-API-0000-0011` · `KH-TEST-MULTI-0000-0012` · `KH-TEST-REPORT-0000-0013` · tutti i moduli: `KH-TEST-ALL-0000-9999` · 25 utenti concorrenti: `KH-TEST-USERS-0025-0014` · proroga trial 60 giorni: `KH-TEST-TRIAL-0060-0015`. In modalità test la pagina mostra il banner "licenze fittizie"; in produzione questi codici sono rifiutati con `license_test_only`. I test automatici usano `KH-TEST-ALL-0000-9999`.
---
## 9. Cache, notifiche, scheduler, allegati e file, log
- `ICacheProvider` (`GetAsync`, `SetAsync` con TTL, `RemoveAsync`, `RemoveByPrefixAsync`, `GetOrCreateAsync`, `PublishInvalidationAsync`). Chiavi `kh:{azienda}:{area}:{key}`. In cache: tabelle di base, permessi, menu, piano dei conti, listini, licenze, ricerche recenti. Se Redis cade l'app continua in memoria e lo segnala.
- **Notifiche in app** (`notifications` per azienda, `sys_notifications` per istanza; mockup 010): generate da automazioni, attività programmate, SDI, scadenze, sicurezza; campanella, pannello laterale, digest e-mail opzionale.
- **Scheduler** (`JobRunner`): job di sistema (pulizia, licenza, cambi BCE, inbox e canali SDI, coda e-mail, verifica giacenze, backup) e **attività programmate** degli amministratori (§12.5), esecuzione singola per attività con lock nel DB di sistema anche tra riavvii, timeout, retry, log, notifica esito.
### 9.4 Allegati e generazione di file (mockup 024)
- `attachments` (per azienda): `entity`, `entity_id`, `kind` (*uploaded/generated/einvoice/notification*), nome, mime, dimensione, sha256, versione, generato-da (modello/procedura), utente, data, `locked` (es. XML inviato). Un allegato appartiene **a un solo documento**: non esistono allegati "sciolti"; cancellare un documento (quando ammesso) archivia i suoi allegati nel cestino dell'azienda per 30 giorni.
- File su volume `/data/files/<azienda>/<yyyy>/<guid>`; upload in streaming, limite configurabile (25 MB), antivirus non incluso (hook predisposto). Anteprima in app per PDF, immagini, XML (formattato), CSV/XLSX (griglia).
- **Generazione**: da ogni documento → *Stampa PDF* (modelli, copie, lingua), *XML FatturaPA*, *righe in XLSX/CSV*, *copia di cortesia PDF+XML (ZIP)*, *etichette colli*, *estratti conto*, *rapportini*; ogni generazione produce un allegato versionato (`v1`, `v2`…) scaricabile o inviabile; "Rigenera" crea una nuova versione. I report producono file scaricabili (XLSX/CSV/PDF) e, se pianificati, allegati e-mail. Le stampe massive producono uno ZIP scaricabile in streaming (mai file temporanei su disco fuori da `/data`).
- `IFileStore` (volume) con quota per azienda e statistiche; i backup includono `/data/files` per azienda.
### 9.5 Log applicativo avanzato (mockup 084)
- Un solo pipeline: `ILogger` → **console JSON** (una riga per evento) + **`DbLogSink`** nel DB di sistema (`sys_log`: `at`, `level`, `section`, `source`, `message`, `exception`, `user`, `company`, `trace_id`, `request`, `entity`, `entity_id`, `data` JSON). Ogni modulo scrive nella propria **sezione**: Sistema, Autenticazione, Database, Migrazioni, Documenti, Contabilità, Magazzino, SDI/e-invoicing, CRM, Automazioni, Attività programmate, Backup, API/MCP, E-mail/PEC, Integrazioni (VIES, BCE, intermediari), UI/circuiti (errori Blazor con stack), Prestazioni (query > 500 ms, richieste lente, GC).
- Pagina *Amministrazione › Log* con navigazione per sezione e contatori, filtri (periodo, livello, azienda, utente, trace, testo, origine, entità), dettaglio evento (contesto, stack, suggerimento, documento collegato con link), export CSV, **regole di avviso** (es. ≥ 1 errore in SDI → notifica amministratori; > 20 avvisi/ora in Autenticazione → e-mail), retention per livello (errori 365 gg, avvisi 180, info 90, debug 7) e compattazione.
- Correlazione: ogni richiesta/operazione ha `trace_id`; le attività programmate e le procedure loggano inizio/fine/durata/esito; gli errori mostrati all'utente riportano il `trace_id` ("Codice errore") per ritrovarli nel log.
---
## 10. Interfaccia utente
### 10.1 I mockup sono la specifica
`docs/mockups/png/` contiene **88 schermate** (più la galleria `000-galleria-mockup.png`); `docs/mockups/mockup.css` contiene tutti i token (`--kh-*`) e le classi dei componenti usati per disegnarle. Regole:
1. Prima della milestone 3 leggi `mockup.css` per intero e guarda almeno le schermate 004, 006, 007, 008, 012, 014, 020, 021, 024, 040, 064, 078, 084. Riproduci le classi come componenti Razor con gli stessi nomi semantici (`toolbar.icons`, `ib`, `ctx`, `dochead`, `fgroup`, `panel`, `form`/`f`, `grid`, `badge`, `tile`, `widget`, `tabs`, `dialog`, `drawer`, `kanban`, `timeline`, `tree`, `cal`, `att`, `strip`, `vsteps`).
2. `wwwroot/css/tokens.css` nasce da `mockup.css`: stessi nomi e valori dei token (temi `light`/`dark`/`auto`/`high-contrast`, otto accenti, densità). Non cambiare i nomi; aggiungi token solo se servono.
3. I dati nelle schermate sono esempio (seed demo), non vanno nel markup.
4. Le maschere senza mockup si compongono con gli stessi mattoni della più simile (tutte le tabelle di base seguono 012 + 076; tutti i documenti seguono 020/021).
5. Ogni cambiamento visivo aggiorna lo screenshot corrispondente e `docs/wiki/Design-UI.md` nella stessa unità di lavoro.
### 10.1.1 Indice delle schermate (`docs/mockups/png/`)
La galleria completa è `000-galleria-mockup.png`. Ogni voce indica il numero, cosa mostra e i mattoni da riprodurre.
#### Accesso e shell
**001 · Accesso con scelta azienda**
![001](docs/mockups/png/001-accesso.png)
**002 · Accesso · verifica in due passaggi (TOTP)**
![002](docs/mockups/png/002-accesso-2fa.png)
**003 · Primo accesso · cambio password obbligatorio**
![003](docs/mockups/png/003-primo-accesso-cambio-password.png)
**004 · Dashboard · da fare, fatto, da evadere, scadenze (widget)**
![004](docs/mockups/png/004-dashboard.png)
**005 · Dashboard in tema scuro**
![005](docs/mockups/png/005-dashboard-tema-scuro.png)
**006 · Dashboard · modalità personalizzazione (widget attivabili, pagina iniziale)**
![006](docs/mockups/png/006-dashboard-personalizza.png)
**007 · Menu laterale compresso (solo icone, sottomenu a comparsa)**
![007](docs/mockups/png/007-menu-compresso.png)
**008 · Preferenze utente · tema notturno e 8 colori di accento**
![008](docs/mockups/png/008-preferenze-tema-colori.png)
**009 · Ricerca globale (Ctrl+K)**
![009](docs/mockups/png/009-ricerca-globale.png)
**010 · Pannello notifiche in app**
![010](docs/mockups/png/010-notifiche.png)
**011 · Aiuto in app (F1) con la pagina wiki della maschera**
![011](docs/mockups/png/011-aiuto-in-app-wiki.png)
#### Anagrafiche e articoli
**012 · Clienti · radar (ricerca, filtri, selezione)**
![012](docs/mockups/png/012-clienti-radar.png)
**013 · Clienti · radar con menu compresso e sottomenu a comparsa**
![013](docs/mockups/png/013-clienti-radar-menu-compresso.png)
**014 · Cliente · scheda anagrafica a gruppi**
![014](docs/mockups/png/014-cliente-scheda.png)
**015 · Cliente · fiscale, SDI, dichiarazione d'intento**
![015](docs/mockups/png/015-cliente-fiscale-sdi.png)
**016 · Fornitore · scheda con condizioni di acquisto e ritenute**
![016](docs/mockups/png/016-fornitore-scheda.png)
**017 · Articolo · scheda con prezzi, riordino e giacenze**
![017](docs/mockups/png/017-articolo-scheda.png)
**018 · Listini · griglia listino × articolo con aggiornamento massivo**
![018](docs/mockups/png/018-listini.png)
#### Vendite e documenti
**020 · Fattura di vendita · righe (toolbar a icone, intestazione documento)**
![020](docs/mockups/png/020-fattura-vendita-righe.png)
**021 · Fattura di vendita · testata a gruppi di campi**
![021](docs/mockups/png/021-fattura-vendita-testata.png)
**022 · Fattura di vendita · tema scuro, accento Malachite**
![022](docs/mockups/png/022-fattura-vendita-tema-scuro.png)
**023 · Hotlink · ricerca articolo (F4) sopra la fattura**
![023](docs/mockups/png/023-hotlink-ricerca-articolo-f4.png)
**024 · Allegati del documento e generazione file (PDF, XML, XLSX, ZIP)**
![024](docs/mockups/png/024-allegati-e-file-generati.png)
**025 · Anteprima di stampa / PDF della fattura**
![025](docs/mockups/png/025-anteprima-stampa-pdf.png)
**026 · Preventivo / offerta con revisioni e collegamento CRM**
![026](docs/mockups/png/026-preventivo-offerta.png)
**027 · Ordine cliente · evasione, residui, documenti collegati**
![027](docs/mockups/png/027-ordine-cliente.png)
**028 · DDT · dati di trasporto, colli, firme**
![028](docs/mockups/png/028-ddt-trasporto.png)
**029 · Nota di credito TD04 con riferimento alla fattura**
![029](docs/mockups/png/029-nota-di-credito.png)
**030 · Fatturazione differita · procedura guidata**
![030](docs/mockups/png/030-fatturazione-differita.png)
#### Acquisti
**031 · Ordine fornitore generato dalla proposta di riordino**
![031](docs/mockups/png/031-ordine-fornitore.png)
**032 · DDT di carico con controllo quantità ricevute**
![032](docs/mockups/png/032-ddt-di-carico.png)
**033 · Fattura di acquisto da XML con conti e centri di costo per riga**
![033](docs/mockups/png/033-fattura-di-acquisto.png)
**034 · Acquisti · import fatture passive XML/P7M**
![034](docs/mockups/png/034-import-xml-sdi.png)
**035 · Autofattura / integrazione reverse charge (TD16–TD29)**
![035](docs/mockups/png/035-autofattura-integrazione.png)
#### Magazzino
**036 · Magazzino · giacenze, disponibilità, sottoscorta**
![036](docs/mockups/png/036-giacenze.png)
**037 · Movimento di magazzino manuale (trasferimento)**
![037](docs/mockups/png/037-movimento-magazzino.png)
**038 · Inventario fisico con conteggi e rettifiche**
![038](docs/mockups/png/038-inventario-fisico.png)
**039 · Proposta di riordino fornitori dal sottoscorta**
![039](docs/mockups/png/039-proposta-di-riordino.png)
#### Contabilità
**040 · Contabilità · prima nota (partita doppia con IVA)**
![040](docs/mockups/png/040-prima-nota.png)
**041 · Prima nota manuale con controllo di quadratura**
![041](docs/mockups/png/041-prima-nota-manuale-non-quadrata.png)
**042 · Contabilità · piano dei conti e mastrino**
![042](docs/mockups/png/042-piano-dei-conti.png)
**043 · Contabilità · causali contabili e modelli di registrazione**
![043](docs/mockups/png/043-causali-contabili.png)
**044 · Contabilità · partitario / estratto conto cliente**
![044](docs/mockups/png/044-partitario-estratto-conto.png)
**045 · Contabilità · registri IVA con protocolli e stampe definitive**
![045](docs/mockups/png/045-registri-iva.png)
**046 · Contabilità · liquidazione IVA, F24, LIPE**
![046](docs/mockups/png/046-liquidazione-iva.png)
**047 · Contabilità · ritenute, casse previdenza, prospetto F24**
![047](docs/mockups/png/047-ritenute-parcelle-f24.png)
**048 · Cespiti · registro beni ammortizzabili e piano di ammortamento**
![048](docs/mockups/png/048-cespiti-registro.png)
**049 · Intrastat · elenchi cessioni/acquisti UE**
![049](docs/mockups/png/049-intrastat.png)
**050 · Contabilità · chiusura esercizio guidata**
![050](docs/mockups/png/050-chiusura-esercizio.png)
**051 · Contabilità · bilancio CEE con confronto e drill-down**
![051](docs/mockups/png/051-bilancio-cee.png)
**052 · Esercizi contabili e blocco periodi**
![052](docs/mockups/png/052-esercizi-periodi.png)
#### Scadenzario e tesoreria
**053 · Scadenzario · partite aperte e aging**
![053](docs/mockups/png/053-scadenzario-partite.png)
**054 · Scadenzario · dialogo Registra incasso**
![054](docs/mockups/png/054-scadenzario-incasso.png)
**055 · Scadenzario · distinte RiBa / SDD / bonifici SEPA**
![055](docs/mockups/png/055-distinte-riba-sdd-sepa.png)
**056 · Scadenzario · solleciti a livelli**
![056](docs/mockups/png/056-solleciti-pagamento.png)
**057 · Scadenzario · riconciliazione bancaria**
![057](docs/mockups/png/057-riconciliazione-bancaria.png)
#### Fatturazione elettronica
**058 · Fatturazione elettronica · cruscotto SDI**
![058](docs/mockups/png/058-cruscotto-sdi.png)
**059 · Fatturazione elettronica · canali SDI (PEC integrata, SdICoop, intermediari)**
![059](docs/mockups/png/059-canali-trasmissione-sdi.png)
**060 · Fatturazione elettronica · bollo virtuale trimestrale**
![060](docs/mockups/png/060-bollo-virtuale.png)
**061 · Fatturazione elettronica · dichiarazioni d'intento e plafond**
![061](docs/mockups/png/061-dichiarazioni-intento.png)
#### CRM
**062 · CRM · dashboard con imbuto, previsione e fonti**
![062](docs/mockups/png/062-crm-dashboard.png)
**063 · CRM · lead con punteggio e conversione**
![063](docs/mockups/png/063-crm-lead.png)
**064 · CRM · pipeline opportunità (kanban)**
![064](docs/mockups/png/064-crm-pipeline-kanban.png)
**065 · CRM · scheda opportunità con cronologia e attività**
![065](docs/mockups/png/065-crm-opportunita.png)
**066 · CRM e Servizi · agenda settimanale**
![066](docs/mockups/png/066-crm-agenda.png)
**067 · CRM · ticket di assistenza collegati a interventi**
![067](docs/mockups/png/067-crm-ticket-assistenza.png)
**068 · CRM · campagne e segmenti**
![068](docs/mockups/png/068-crm-campagne.png)
#### Servizi, canali, report, automazioni, tabelle
**069 · Servizi · contratto di assistenza e interventi**
![069](docs/mockups/png/069-servizi-contratto-interventi.png)
**070 · Canali e-commerce · ordini web importati e connettori**
![070](docs/mockups/png/070-canali-ecommerce-ordini.png)
**071 · Report · fatturato per cliente con export e pianificazione**
![071](docs/mockups/png/071-report-fatturato-clienti.png)
**072 · Automazioni · regole quando → se → allora**
![072](docs/mockups/png/072-automazioni-regole.png)
**073 · Automazioni · catalogo procedure**
![073](docs/mockups/png/073-procedure-catalogo.png)
**074 · Tabelle azienda · codici automatici e compilazione automatica**
![074](docs/mockups/png/074-preferenze-codici-automatici.png)
**075 · Tabelle azienda · profilo azienda**
![075](docs/mockups/png/075-profilo-azienda.png)
**076 · Tabelle azienda · codici IVA con nature SDI**
![076](docs/mockups/png/076-codici-iva.png)
**077 · Import/Export · procedura guidata CSV/XLSX/JSON**
![077](docs/mockups/png/077-import-export-wizard.png)
#### Amministrazione
**078 · Amministrazione · istanza, database di sistema e per azienda**
![078](docs/mockups/png/078-admin-istanza-database.png)
**079 · Amministrazione · dettaglio database: backup, cloud, ripristino, manutenzione**
![079](docs/mockups/png/079-admin-database-backup-ripristino.png)
**080 · Amministrazione · licenze e moduli attivabili con codice**
![080](docs/mockups/png/080-admin-licenze-moduli.png)
**081 · Amministrazione · utenti a tre livelli e per azienda**
![081](docs/mockups/png/081-admin-utenti.png)
**082 · Amministrazione · matrice ruoli × permessi**
![082](docs/mockups/png/082-admin-ruoli-permessi.png)
**083 · Amministrazione · attività programmate (scheduler)**
![083](docs/mockups/png/083-admin-attivita-programmate.png)
**084 · Amministrazione · log avanzato per sezioni con filtri e dettaglio**
![084](docs/mockups/png/084-admin-log-avanzato.png)
**085 · Amministrazione · stato sistema e aggiornamenti**
![085](docs/mockups/png/085-admin-stato-sistema.png)
**086 · Amministrazione · impostazioni di sistema (sicurezza, SMTP)**
![086](docs/mockups/png/086-admin-impostazioni-sicurezza.png)
**087 · Amministrazione · archiviazione e copie remote (S3, WebDAV)**
![087](docs/mockups/png/087-admin-impostazioni-cloud-backup.png)
**088 · Amministrazione · chiavi API, MCP e webhook**
![088](docs/mockups/png/088-admin-chiavi-api-mcp.png)
**089 · Amministrazione · dati di base, pacchetti e dati di esempio**
![089](docs/mockups/png/089-admin-dati-base-esempio.png)
### 10.2 Shell (mockup 004, 007)
- **Barra superiore** scura: marca (icona 4 tessere + nome + versione), selettore azienda (solo account di istanza o utenti multi-azienda), ricerca globale (Ctrl+K, mockup 009: clienti, fornitori, articoli, documenti, registrazioni, conti, azioni, comandi con `>`, documenti con `#`, persone con `@`), nuovo, recenti, notifiche (010), cambio tema rapido, aiuto (F1 → pagina wiki della maschera, 011), menu utente.
- **Menu laterale comprimibile** (007, 013): stato espanso (icona + testo, sotto-voci del modulo attivo, contatori) o compresso a 60 px (sole icone, tooltip, sotto-voci in un pannello a comparsa al passaggio o al clic). Il pulsante "Comprimi menu" in fondo e la scorciatoia `Ctrl+B`; lo stato è ricordato per utente; sotto 1100 px il menu è compresso di default. Ordine voci: Home; Anagrafiche, CRM, Vendite, Acquisti, Magazzino, Contabilità, Scadenzario, Fatturazione elettronica, Cespiti, Servizi, Canali e-commerce, Report; Tabelle azienda, Automazioni, Amministrazione (solo account di istanza). Le voci compaiono solo con modulo licenziato e permessi.
- **Area a schede** (`TabHost`): ogni maschera aperta è una scheda mantenuta in vita; pallino arancione se modificata; avviso alla chiusura con modifiche; massimo 12; `Ctrl+W` chiude, `Ctrl+Tab` passa.
- **Barra di stato**: azienda, esercizio, utente·livello, deposito, stato connessione/latenza, Redis, versione.
### 10.3 Dashboard (004, 005, 006)
- Griglia a **widget** (12 colonne, larghezze 3/4/6/8/12), ciascuno disattivabile, ordinabile per trascinamento e ridimensionabile in modalità *Personalizza* (pannello laterale 006). Widget disponibili: **KPI** (indicatori scelti dall'utente), **Da fare oggi** (generato da: scarti SDI, liquidazioni e scadenze fiscali, procedure in attesa, attività CRM, approvazioni), **Fatto oggi** (azioni completate dall'utente e dal team: documenti emessi, incassi, backup, attività programmate), **Scadenze prossimi 30 giorni** (fiscali, vendite, tesoreria, contratti, con etichetta area), **Da evadere** (ordini e DDT con residuo), **Fatturato 12 mesi**, **Attività CRM**, **Promemoria personali** (note libere per utente), **Scorciatoie** (pulsanti configurabili), Sottoscorta, Pipeline CRM, Ultimi documenti, Stato sistema (amministratori).
- La dashboard è **disattivabile**: in *Preferenze › Pagina iniziale* l'utente sceglie se mostrarla e quale pagina aprire all'accesso (ultima scheda aperta, un radar, la prima nota, l'agenda…). Layout e scelte sono in `user_settings`; gli amministratori possono definire un layout predefinito per ruolo.
### 10.4 Toolbar a sole icone (020)
- Comandi standard **solo icone** (32×32) con tooltip al passaggio (nome + scorciatoia) e senza etichette: `+` Nuovo (Ctrl+N), Salva (Ctrl+S, evidenziato), Annulla (Esc), Elimina (Ctrl+Canc) · Duplica, Stampa (Ctrl+P), Invia e-mail, Genera file/esporta · Allegati, Storico, Collegamenti · a destra Radar (F9), precedente/successivo, menu `⋯` con tutto il resto.
- Le **azioni contestuali** del documento (Conferma ed emetti, XML SDI, Contabilizza, Evadi da…, Genera DDT, Rendi definitiva…) sono "chip" icona + **etichetta sintetica** (massimo tre parole); la principale è piena (accento). Mai più di 4 chip: le altre finiscono nel menu `⋯`. La toolbar sta **sempre su una riga**: quando lo spazio manca, le icone meno usate scivolano nel menu `⋯`, le etichette non vanno mai a capo né si sovrappongono. Le toolbar delle liste (012, 036) seguono la stessa regola: icone + 1–2 chip.
### 10.5 Maschera documento (020, 021, 027, 028, 033, 040)
1. Toolbar a icone (§10.4).
2. **Intestazione documento** (`dochead`) in tre blocchi: a sinistra tipo (icona in riquadro + etichetta "Fattura immediata · TD01"), numero grande, riga meta (data, sezionale, registro) e badge di stato; al centro **controparte** (iniziali, nome con codice, indirizzo/P.IVA/PEC) e **chip** riassuntivi delle condizioni (pagamento, listino, agente, destinazione, banca, avvisi come scaduto/fido); a destra **totale** grande e tre sotto-valori (imponibile, IVA, bollo / residuo / margine). Per le anagrafiche lo stesso blocco mostra identità, contatti, chip delle condizioni e KPI (014, 016, 017).
3. **Schede con icone** (`tabs.i`): per i documenti la prima scheda è *Righe* (si apre lì), poi *Testata*, *Totali*, *Trasporto*, *Scadenze*, *Dati SDI/PA*, *Note*, *Allegati (n)*, *Collegamenti (n)*, *Storico*; per le anagrafiche *Dati principali*, *Indirizzi*, *Contatti*, *Condizioni*, *Fiscale e SDI*, *Banche*, *Articoli e codici*, *Note e allegati*, *CRM*, *Storico*. `Alt+1..9` cambia scheda.
4. La scheda *Testata* raggruppa i campi in **gruppi** (`fgroup`: Documento, Controparte, Condizioni, Magazzino e trasporto…) su griglia 12 colonne, etichette sopra i campi, obbligatori con asterisco, suggerimenti sotto, hotlink con codice evidenziato + descrizione + icone ricerca/apri.
5. La scheda *Righe*: griglia a tutta larghezza con editing inline (Invio cella successiva, Tab, frecce, `F4` ricerca, `Ctrl+↓` nuova riga, riga vuota in coda con placeholder), righe descrittive, menu riga `⋯`; sotto la griglia **castelletto IVA**, **scadenze/revisioni/partite** e **totali** in tre pannelli.
6. Stati e azioni contestuali; validazione a lato campo + riepilogo; una fattura emessa è in sola lettura (chip e campi disabilitati).
7. Scorciatoie globali: `Ctrl+S` salva, `Ctrl+N` nuovo, `Ctrl+P` stampa, `F4` lookup, `F9` radar, `Esc` annulla, `Ctrl+↑/↓` naviga record, `Ctrl+D` quadra (prima nota), `Ctrl+B` menu, `Ctrl+K` ricerca, `F1` aiuto.
### 10.6 Temi, colori, densità (008)
Tema **chiaro**, **scuro (notturno)**, **automatico** (segue il sistema), **alto contrasto**; otto **accenti** (`nilo` default, `lapislazzuli`, `malachite`, `turchese`, `ocra`, `corniola`, `ametista`, `grafite`) con varianti per tema in `mockup.css`; **densità** comoda/compatta, dimensione testo, carattere numerico tabellare, animazioni ridotte, tooltip on/off, stato del menu. Tutto in `user_settings`, applicato con `data-theme`, `data-accent`, `data-density` sulla radice; prima del login vale il tema di sistema; stampe sempre in chiaro (`print.css`).
### 10.7 Libreria componenti (`Components/Ui`, prefisso `Kh`)
`KhIconToolbar`, `KhIconButton` (tooltip, badge contatore), `KhContextAction`, `KhDocHead`, `KhFieldGroup`, `KhForm`/`KhField`, `KhTextBox`, `KhNumberBox` (it-IT, calcolo inline `=10*3`), `KhDateBox` (gg/mm/aaaa, +/- giorno, T oggi, F fine mese), `KhSelect`, `KhCheck`, `KhSwitch`, `KhTextArea`, `KhHotlink` (codice + descrizione, ricerca incrementale, F4 radar, Ctrl+Invio apre, crea al volo), `KhGrid` (colonne tipizzate, ordinamento, filtri, paginazione server, virtualizzazione, selezione multipla, editing inline, riga totali, layout colonne salvato, export, evidenziazioni, menu riga), `KhLinesGrid`, `KhTabs` (con icone e contatori), `KhPanel`, `KhTile`, `KhStrip`, `KhWidget` + `KhWidgetGrid` (personalizzabile), `KhDialog`, `KhDrawer`, `KhConfirm`, `KhToast`, `KhBadge`, `KhChip`, `KhMoney`, `KhRadar`, `KhSteps`/`KhVSteps`, `KhTree`, `KhKanban`, `KhTimeline`, `KhCalendar`, `KhAttachmentList` (con *Genera file*), `KhAuditList`, `KhPrintPreview`, `KhCommandPalette`, `KhNotificationBell`, `KhHelpLink`, `KhLogViewer`, `KhSideMenu` (comprimibile), `KhTabHost`, `KhStatusBar`.
### 10.8 Accessibilità, stile, localizzazione
Font di sistema (`Inter` se presente sul sistema dell'utente, altrimenti `Segoe UI`/`system-ui`; nessun font scaricato), icone SVG proprie in `icons/sprite.svg` (riprendi i tracciati dei mockup), focus visibile, etichette collegate, contrasto AA (AAA in alto contrasto), tutto operabile da tastiera, desktop-first usabile da tablet ≥ 768 px. `ITexts` risolve chiavi `Sales.Invoice.Title` da `Resources/it-IT/*.json`; formati con `CultureInfo("it-IT")`; nessun testo hard-coded nei componenti (test di architettura).
---
## 11. Moduli funzionali
Per ogni modulo: entità (tabella → colonne principali), regole, maschere, stampe. Colonne di audit e `row_version` sottintese. `→` indica chiave esterna. Ogni modulo documenta se stesso in `docs/wiki/<Modulo>.md` (§17) e dichiara il proprio codice di licenza (§8.1).
### 11.1 Azienda e tabelle di base (`Company`, modulo CORE) — mockup 052, 074, 075, 076
- `company_profile` (riga singola, 075): ragione sociale, denominazione fiscale, P.IVA, codice fiscale, REA, capitale sociale, socio unico, stato liquidazione, indirizzo, contatti, PEC, **regime fiscale** `RF01…RF19`, codice destinatario proprio, logo (allegato), IBAN predefinito, valuta, paese (`IT` → `ItalyFiscalPack`), periodicità IVA, pro-rata %, IVA per cassa, dati del trasmittente/intermediario, note in calce.
- `fiscal_years` (esercizio: inizio, fine, stato *aperto/in chiusura/chiuso*, prima pagina libro giornale, ultima registrazione definitiva) e `fiscal_periods` (mese/trimestre: *aperto/liquidato/bloccato*; 052). Date ammesse solo in periodi aperti.
- `countries` (ISO 3166-1, UE, codice SDI `XXXXXXX`), `provinces`, `municipalities` (CAP, codice catastale: per codice fiscale e compilazione da CAP), `currencies` + `exchange_rates` (BCE), `units_of_measure` (codice SDI), `tax_codes` (076: aliquota, **natura SDI** `N1…N7` con sotto-codici, riferimento normativo, esigibilità `I/D/S`, tipo, indetraibilità %, conti IVA →, validità), `payment_methods` (`MP01…MP23`), `payment_terms` (+ righe: rata, giorni, fine mese, giorno fisso, %, IVA sulla prima rata, `TP01/02/03`), `bank_accounts` (IBAN, BIC, conto →, SIA/CUC), `salespeople` (provvigione, ENASARCO), `carriers`, `shipping_terms`, `transport_means`, `goods_appearances`, `delivery_terms` (Incoterms), `transport_reasons`, `document_numerators` (tipo, sezionale, anno, formato `{prefix}/{anno}/{number:D6}`, assegnazione atomica alla conferma, buchi non ammessi per fatture/NC/registrazioni definitive), `inventory_reasons`, `warehouses`, `item_categories` (3 livelli), `party_categories`, `price_lists`, `discount_policies`, `document_types` (catalogo statico: kind, numeratore, causale magazzino, **causale contabile**, registro IVA, TD SDI, modello stampa), `cost_centers`, `jobs` (commesse).
- Maschere: una per tabella (modello 012 + 076), import/export CSV.
### 11.2 Anagrafiche (`Parties`) e articoli (`Items`, CORE) — mockup 012–018
- `parties` (clienti/fornitori/prospect/lead come `kind`): `code` automatico (§11.12), ragione sociale o nome/cognome, P.IVA, codice fiscale (calcolabile), tipo soggetto (*azienda/privato/PA/UE/extra-UE/forfettario*), sede, contatti, lingua, paese, categoria, agente, note, `disabled`, `is_demo`, conti contabili cliente/fornitore → (sottoconti del partitario creati alla prima registrazione); `party_addresses`, `party_contacts`, `party_bank_accounts`, `party_sales_terms` (listino, sconti, pagamento, banca RiBa, agente, vettore, porto, deposito, fido, blocco, raggruppa DDT, giorno fatturazione, invio documenti e-mail/PEC), `party_purchase_terms` (pagamento, lead time, minimo, sconti), `party_fiscal` (codice destinatario, PEC, split payment, reverse charge, **dichiarazione d'intento** con plafond/utilizzato/residuo, ritenuta e aliquota, causale, cassa previdenza, ENASARCO, EORI, GLN, forfettario), `party_item_codes`.
- Regole (014, 015): validazione P.IVA, codice fiscale (check char), IBAN (mod 97), VIES per P.IVA UE (HTTP, esito salvato), PA → codice IPA 6 caratteri, estero `XXXXXXX`, privato `0000000`; disabilitazione invece di cancellazione se esistono documenti; conversione lead/prospect → cliente con assegnazione codice.
- `items` (017): `code` automatico, descrizioni, tipo (*merce/servizio/spesa/testo/cespite*), categoria, UM, IVA vendita/acquisto, EAN, NC8, produttore, marca, pesi, deposito, scorta minima, punto/lotto di riordino, prezzi, costi (standard/ultimo/medio), gestione a magazzino, conti ricavo/costo →, immagine; `item_uoms`, `item_barcodes`, `item_prices`, `item_suppliers`, `item_substitutes`. Listini (018): griglia listino × articolo, aggiornamento massivo %, arrotondamenti, validità, listini derivati, prezzi netti per cliente.
### 11.3 Motore documenti (`Application/Documents`, CORE)
- `DocumentDefinition` (codice, kind, direzione, numeratore, causale magazzino, effetti, sorgenti per evasione, TD SDI, causale contabile, registro IVA, template stampa). Tabelle per famiglia: `sale_quotations`, `sale_orders`, `sale_documents` (DDT, fatture, NC/ND, pro-forma, parcelle, autofatture), `purchase_orders`, `purchase_documents`, `inventory_documents`; ognuna con `_lines`, `_tax_summary`, `_installments`. Testata: tipo, sezionale, numero, data, anno, controparte →, destinazione →, riferimenti, valuta/cambio, listino, pagamento, metodo, banca, agente, deposito, causale, stato, 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, articolo →, descrizione, UM, q.tà, prezzo, sconti, formula sconto, IVA →, imponibile, deposito, consegna, evasa/residua, riga origine, conto →, centro di costo, commessa, note, ordinamento.
- `document_links` (target riga → sorgente riga, quantità): evasione ordine → DDT → fattura differita; DDT fornitore → fattura acquisto; residui; riapertura; `DatiOrdineAcquisto`/`DatiDDT` nell'XML (027).
- Stati: `Draft → Confirmed → (PartiallyFulfilled | Fulfilled) → Closed`, `Cancelled`; fatture `Draft → Issued → SdiGenerated → SdiSent → (SdiDelivered | SdiRejected | SdiNotDelivered)`. Fattura emessa immutabile (NC o annullamento con motivo se XML non inviato).
- `DocumentTotalsCalculator`: imponibile riga = q.tà × prezzo × (1−s1)(1−s2)…, 2 decimali `AwayFromZero`; castelletto per codice IVA; imposta per aliquota; spese con IVA propria; sconto piede ripartito; **bollo** €2,00 se esenti/non imponibili/fuori campo > €77,47; **ritenuta** e **cassa previdenza** per parcelle; **split payment**; **reverse charge**; **IVA per cassa**. `InstallmentGenerator`: condizione di pagamento, fine mese, giorno fisso, %, IVA sulla prima rata, sconto cassa, arrotondamento sull'ultima. Prezzi: netto cliente-articolo → listino cliente → listino base → prezzo articolo, con `price_source`.
- Numerazione alla conferma; data non anteriore all'ultimo numerato del sezionale per fatture/NC; periodo fiscale aperto. **Contabilizzazione** (§11.7) alla conferma (immediata o batch). Stampa HTML/PDF (025) con diciture di legge; copie; e-mail/PEC con PDF (+XML). Duplicazione, trasformazione (026), evasione guidata, fatturazione differita (030).
### 11.4 Vendite (`Sales`, CORE) — mockup 020–030
Preventivi con revisioni e collegamento CRM · Ordini clienti (consegne, impegnato, blocco fido/scaduto con override, CIG/CUP) · DDT (scarico, trasporto, 3 copie, resi) · Fatture immediate TD01, accompagnatorie, differite TD24/TD25, pro-forma, acconto TD02/TD03, NC TD04 e ND TD05, parcelle TD06, semplificate TD07/TD08/TD09, cessione cespiti TD26, autoconsumo/omaggi TD27 · corrispettivi registrati manualmente · report: giornale vendite, fatturato per cliente/agente/categoria/articolo (071), DDT da fatturare, ordini aperti, provvigioni, margini.
### 11.5 Acquisti (`Purchases`, CORE) — mockup 031–035
Ordini fornitori (da proposte di riordino, 031) · DDT di carico con controllo quantità (032) · Fatture di acquisto con protocollo, conti e centri di costo per riga, ritenute (033) · note di credito fornitore · **import XML/P7M** (034: fornitore per P.IVA/CF, creazione al volo, mappatura righe, confronto con ordine, bozza con differenze, XML allegato, firma verificata) · **autofatture e integrazioni** (035): TD16 reverse charge interno, TD17 servizi estero, TD18 beni intra-UE, TD19 beni art. 17 c.2, TD20/TD29 regolarizzazione, TD21 splafonamento, TD22/TD23 depositi IVA, TD28 San Marino cartacee/irregolari da non residenti; registri RC vendite+acquisti (IVA neutra); XML entro il 15 del mese successivo con promemoria · fatture da forfettari.
### 11.6 Magazzino (`Inventory`, CORE) — mockup 036–039
`inventory_entries` + `_lines`, `item_balances` (articolo × deposito: giacenza, impegnato, ordinato, in transito, valore medio) aggiornati transazionalmente; disponibilità = giacenza − impegnato; movimenti manuali e trasferimenti (037), inventario fisico con liste, conteggi e rettifiche (038), costo medio ponderato (FIFO/LIFO predisposti), rimanenze finali per chiusura e libro inventari, scritture ausiliarie di magazzino, ricostruzione; giacenze/disponibilità con sottoscorta (036), proposta di riordino → ordini fornitore (039), scheda articolo, valorizzazione a data, ABC.
### 11.7 Contabilità generale (`Ledger`, ACCT) — mockup 040–052
- **Piano dei conti** (042) `gl_accounts`: codice gerarchico `MM.CC.SSS`, descrizione, natura, tipo, padre →, **voce CEE** (art. 2424/2425), voce riclassificata, partitario clienti/fornitori, rilevante IVA, chiusura automatica, movimentabile, attivo. Piano standard PMI **precaricato** (`Fiscal.Italy/ChartOfAccounts`) e **importabile**: non esiste uno standard italiano per lo scambio del piano dei conti, quindi si accettano `CSV` (`;`, colonne `codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag`) e `XLSX` con lo stesso tracciato, più `JSON` per export/import completo (`khaemhat-coa.json`: conti, voci di bilancio, causali e mappature); importazione guidata (077) con anteprima e verifica di coerenza gerarchica.
- **Causali contabili** (043) `gl_journal_templates`: righe modello con *ruolo* (cliente, fornitore, ricavo, costo, IVA vendite, IVA acquisti, banca, cassa, Erario ritenute, cassa previdenza, bollo, abbuoni, contropartita), dare/avere, registro IVA, genera partita; causali di base: FV, NCV, FA, NCA, AFRC, CORR, INC, PAG, INS, GIRO, AMM, RAT, RIM, chiusura/apertura, F24, ritenute versate, stipendi (import), interessi/commissioni.
- **Prima nota** (040, 041) `gl_entries` (numero per esercizio, data registrazione, competenza, causale, descrizione, documento origine, registro IVA → e protocollo, stato *provvisoria/definitiva*, periodo, fonte, storno di →) + `gl_entry_lines` (conto, dare/avere, controparte, centro di costo, commessa, partita →, valuta) + `gl_entry_vat`. Quadratura obbligatoria (bozza ammessa se non quadra, mai definitiva); registrazioni da documento modificabili solo stornando il documento; **definitive immutabili** con numerazione continua sul libro giornale; blocco per periodo liquidato e per esercizio chiuso; storno collegato; registrazioni ricorrenti; registrazioni in valuta con differenze cambio.
- **Partitari e mastrini** (044) con drill-down fino al documento; estratti conto.
- **Registri IVA** (045) `vat_registers` (vendite, acquisti, corrispettivi, vendite RC, acquisti RC, sezionali) con protocollo; stampe provvisorie e definitive (pagine numerate, totali per aliquota/natura). **Liquidazione IVA** (046) `vat_settlements`: debito/credito, esigibilità differita e per cassa, indetraibile, pro-rata, credito precedente, acconto di dicembre (storico/previsionale/analitico), interessi 1% trimestrali, minimo €25,82 con riporto, **dati F24** (6001–6012, 6031–6034, 6013/6035, 6099) e **LIPE** XML (tracciato AdE), controlli preliminari, conferma che blocca il periodo.
- **Bollo virtuale** (060), **ritenute e contributi** (047: operate con F24 1040/1038 e CU export; subite; INPS 4%/casse; ENASARCO), **cespiti** (048, ASSET: categorie con coefficienti DM 31/12/1988, primo anno 50%, limiti autovetture, < €516,46, dismissioni con plus/minusvalenza TD26, rivalutazioni, piano simulato, registro beni ammortizzabili, contabilizzazione annuale), **Intrastat** (049, INTRA: INTRA-1/2 bis-quater, periodicità da soglie, NC8, natura transazione, consegna, trasporto, file nel tracciato Agenzia Dogane), **dichiarazioni d'intento** ricevute ed emesse (061).
- **Chiusura esercizio** (050): controlli, ammortamenti, ratei/risconti, rimanenze, accantonamenti, chiusura CE e SP, apertura con riporto partite e saldi, stampe definitive (libro giornale, libro inventari, registri IVA, registro cespiti); blocco → sola lettura. **Bilancio** (051): verifica, CEE (ordinario/abbreviato/micro) con confronto e drill-down, riclassificati, indici, situazione infrannuale, nota integrativa in bozza, export XLSX/PDF; XBRL in fase 2.
- Report: libro giornale, mastrini, bilancini per C.d.C./commessa, registri IVA, liquidazioni, scadenziario IVA, elenco clienti/fornitori per fatturato, riepilogo per natura, quadri VE/VF (dati), estratti conto, **export per il commercialista** (pacchetto ZIP mensile: giornale, registri, partitari, bilancio in XLSX/CSV/PDF).
### 11.8 Scadenzario e tesoreria (`Finance`, FIN) — mockup 053–057
`open_items` (partite: controparte, documento, rata, scadenza, importo, pagato, residuo, metodo, banca, stato *aperta/parziale/chiusa/insoluta/in distinta/contestata*, registrazione →), `payments` con righe su partite, abbuoni, differenze cambio, spese, storno, registrazione contabile automatica (054). **Effetti e distinte** (055): RiBa (file CBI), SDD core/B2B (mandati, `pain.008`), bonifici SEPA (`pain.001`), MAV/RAV come scadenze; insoluti con riapertura e spese; anticipi s.b.f. **Riconciliazione bancaria** (057): import CSV/CBI/CAMT.053, abbinamento con confidenza, regole salvate, registrazione delle righe non abbinate. **Solleciti** (056): livelli 1–3, modelli e-mail/PEC/lettera, interessi di mora (D.Lgs. 231/2002), registro invii, blocco cliente; eseguibili da attività programmata. Report: scadenzario, aging (053), estratto conto, flusso di cassa 90 gg, insoluti, posizione bancaria.
### 11.9 Fatturazione elettronica (`EInvoicing` + `Fiscal.Italy`, EINV) — mockup 058–061
- `FatturaPaWriter`: XML `FPR12`/`FPA12`/`FSM10` secondo le specifiche tecniche correnti dell'Agenzia delle Entrate (alla stesura la v1.9 in vigore dal 1° aprile 2025, con TD29 e TD20 ridefinito; registra la versione supportata in `FatturaPaCodeLists.SpecVersion` e verifica sempre l'ultima pubblicata): `DatiTrasmissione`, `CedentePrestatore`, `CessionarioCommittente`, `DatiGenerali` (TD, DatiRitenuta, DatiBollo, DatiCassaPrevidenziale, ScontoMaggiorazione, Causale, Art73), `DatiOrdineAcquisto`/`DatiContratto`/`DatiConvenzione`/`DatiRicezione`/`DatiFattureCollegate` (CIG/CUP), `DatiDDT`, `DatiTrasporto`, `DettaglioLinee`, `DatiRiepilogo`, `DatiPagamento`, `Allegati`; nome file `IT<PIVA>_<progressivo base36>.xml`.
- `FatturaPaValidator` (code list, lunghezze, totali ±0,01, nature e riferimenti normativi, destinatario/PEC, PA con CIG/CUP, codice fiscale gruppi IVA, bollo); `FatturaPaReader` (passive, P7M/CAdES, allegati); `SdiNotificationReader` (RC, NS, MC, NE/EC01-EC02, DT, AT, metadati).
- **Canali di trasmissione** (`ISdiTransport`, mockup 059), tutti con la stessa interfaccia (invia, stato, notifiche, scarica passive): **PEC integrata** (nessun servizio esterno: invio dell'XML come allegato alla PEC dello SDI via SMTP della PEC aziendale, lettura delle notifiche e delle fatture passive dalla casella PEC con il client IMAP in casa, filtro per mittente/oggetto, archivio in cartelle); **SdICoop** (web service dell'Agenzia, accreditamento e certificato dell'azienda, SOAP costruito a mano con `HttpClient` e certificato client, notifiche in tempo reale); **Intermediario A** e **Intermediario B** (connettori REST ai due servizi di intermediazione scelti dal titolare del progetto, credenziali cifrate, mappatura stati/errori, conservazione a norma se inclusa nel servizio). Regole di instradamento (canale per cliente PA, per volumi, predefinito). Lo SDI non si può "inglobare": è il sistema dell'Agenzia; il canale PEC è il massimo dell'integrazione senza terzi.
- **Conservazione**: pacchetto di esportazione per periodo (XML + notifiche + indice) da affidare a un conservatore o al servizio dell'Agenzia; dichiarato nella wiki. `IEInvoiceFormat` consente EN 16931/UBL (Peppol) come implementazione futura.
- Cruscotto (058): contatori per stato, elenco prioritizzato, genera/valida/invia/scarica, correggi e rigenera, importa notifiche/passive, bollo virtuale, autofatture da inviare, canale usato per documento.
### 11.10 CRM (`Crm`, CRM) — mockup 062–068
`crm_leads` (fonte, interesse, punteggio da regola, responsabile, stato, conversione in cliente), `crm_pipelines` + `crm_stages`, `crm_opportunities` (fase, probabilità, valore, ponderato, chiusura, responsabile, fonte, concorrenti, motivo perdita, preventivo →, ordine →), `crm_activities` (chiamata/e-mail/riunione/attività/nota/visita, scadenza, esito, promemoria, collegamenti), `crm_campaigns` (tipo, segmento, modello, budget, costo, membri, statistiche), `crm_tickets` (priorità, stato, SLA, assegnatario, collegamento a intervento Servizi e a NC), `crm_email_templates`, `crm_segments`. Funzioni: dashboard con imbuto e previsione (062), lead (063), kanban trascinabile (064), scheda opportunità con cronologia (065), agenda condivisa con gli interventi (066), ticket (067), campagne (068), scheda controparte a 360°, e-mail inviate archiviate, import lead da CSV/API (form sito web).
### 11.11 Servizi (`Services`, SVC) e Canali e-commerce (`Channels`, CHAN) — mockup 069, 070
- Contratti di assistenza (cliente, sede, validità, rinnovo tacito, canone e periodicità, servizi inclusi, impianti e matricole), squadre e tecnici (costo orario), interventi (*programmato/a chiamata/garanzia*, stato, pianificazione, ore e materiali, rapportino, firma), generazione interventi periodici e rate/canoni, fatturazione dei rapportini tramite il motore documenti, calendario.
- Canali: `sales_channels` (tipo *generico* o connettore dedicato, credenziali cifrate, cliente cassa, sezionale, pagamento, deposito, mappature pagamenti/spedizioni), `channel_items`, `channel_orders` (payload JSON, stato), `channel_customers`; connettore **generico** (JSON/CSV + `POST /api/v1/channels/{code}/orders`, sincronizzazione giacenze/prezzi in uscita); connettori dedicati ai singoli marketplace/piattaforme come implementazioni successive di `IChannelConnector`.
### 11.12 Automazioni, procedure e preferenze (`Automation`, `UserSettings`, AUTO) — mockup 072–074
- **Codici automatici** (074, `CodeRule` per entità): maschere `C{seq:000000}`, `F{seq:000000}`, `{categoria}-{seq:0000}`, `L{anno}-{seq:0000}`, `CESP-{seq:0000}`, `OPP-{anno}-{seq:0000}`, `TK-{anno}-{seq:0000}`, `SVC-{seq:0000}`, `MAN-{anno}-{seq:0000}`; progressivo globale o per categoria/anno; codice manuale ammesso o no; anteprima del prossimo codice; numeratori in `code_sequences` con assegnazione atomica.
- **Compilazione automatica**: comune/provincia/regione da CAP, codice fiscale calcolato, VIES, cambi BCE, banca/BIC da IBAN (tabella ABI), descrizione articolo nelle righe, ultimo prezzo praticato, proposta ultimo documento simile, date consegna = data + lead time, destinazione/listino/pagamento/agente dal cliente, causale/deposito dal tipo documento, conti da articolo/categoria/causale.
- **Regole** (072) `automation_rules` quando → se → allora: eventi (`DocumentCreated/Confirmed/Issued/Cancelled`, `SdiNotificationImported`, `OpenItemOverdue`, `StockBelowReorder`, `LeadCreated`, `OpportunityStageChanged`, `TicketOpened`, `InterventionClosed`, `Schedule`), condizioni (filtri semplici e soglie %), azioni (e-mail/PEC con modello, notifica in app, crea attività, imposta campo/stato, blocca con permesso, aggiungi a proposta riordino, genera documento collegato, esegui procedura, webhook). Log esecuzioni, prova su documento, disattivazione dopo N errori.
- **Procedure** (073, `ProcedureCatalog`): fatturazione differita, contabilizzazione batch, generazione scadenze, solleciti, stampa/invio massivo, proposta riordino, aggiornamento listini, liquidazione IVA, ammortamenti, ratei/risconti, chiusura esercizio (passi), ricostruzioni, import inbox e canali SDI, cambi, export commercialista, pulizie; tutte idempotenti, con log, eseguibili a mano, da regola o da attività programmata.
- **Preferenze** a tre livelli: utente (tema, accento, densità, menu, pagina iniziale e dashboard, layout griglie, filtri salvati, scorciatoie, notifiche), azienda (numerazioni, codici, default documenti, arrotondamenti, controlli, modelli e-mail, testi di stampa, periodicità IVA), sistema (sicurezza, backup, retention, SMTP/PEC, cloud, licenze).
### 11.13 Report (`Reports`, CORE/REPORT) — mockup 071
`ReportDefinition` (parametri, query per dialetto, colonne, totali, raggruppamenti) resa con `KhGrid` + grafico, export CSV/XLSX/PDF, stampa, **pianificazione come attività programmata** (invio e-mail, salvataggio come allegato). Catalogo minimo: tutti i report citati nei moduli + ABC, statistiche per periodo, registro DDT, fatture per registro IVA, margini (REPORT), provvigioni, report CRM, report servizi, export per il commercialista.
---
## 12. Amministrazione (account di istanza) — mockup 078–089
1. **Istanza e database** (078, 079; super utente per le azioni distruttive): elenco dei database (sistema e aziende) con motore, dimensione, stato schema, ultimo backup, stato (*attiva/manutenzione/sola lettura/disattivata*); **nuova azienda** (CREATE DATABASE sul server configurato o file SQLite, migrazioni, tabelle di base, licenza MULTI richiesta oltre la prima); **collega database esistente** (connection string); **clona** (ambiente di prova da un backup, nome `khaemhat_<codice>_test`); **elimina** (solo super utente: backup automatico preventivo, conferma scrivendo il nome, cestino 30 giorni del file di backup); applica migrazioni; manutenzione per database (`VACUUM ANALYZE`, `REINDEX`, `integrity_check`); verifica integrità; ricostruzioni; statistiche tabelle; modalità manutenzione per azienda (utenti disconnessi, API 503); informazioni sul server PostgreSQL (versione, ruolo, connessioni, spazio, estensioni) con avviso se la versione è inferiore alla minima (16).
2. **Licenze e moduli** (080, §8).
3. **Utenti** (081): account di istanza (amministratori, solo super utente) e utenti di ogni azienda; livello, ambito (istanza/azienda), ruoli, flag, sessioni, scadenza, reset password, invito, 2FA, utenti tecnici per API.
4. **Ruoli e permessi** (082): matrice, cloni, override per utente, confronto, "chi ha questo permesso".
5. **Attività programmate** (083): tipi *backup*, *procedura* (dal catalogo, con parametri), *report via e-mail*, *notifica*, *import/export*, *verifica*, *script di manutenzione* (dal catalogo interno, mai shell libera); azienda, esegui come, preset di pianificazione o cron, fuso orario, timeout, retry, notifiche; storico con durata, esito, log; esegui ora, sospendi, duplica.
6. **Backup e ripristino** (079, §13).
7. **Log** (084, §9.5).
8. **Stato sistema** (085): stato, latenza DB, Redis, spazio disco, memoria, utenti collegati, controlli (migrazioni per database, licenza, SMTP, canali SDI, scheduler, backup, integrità, disco), versione/commit/immagine, **controllo aggiornamenti** su GHCR (nessun aggiornamento automatico; link alle note di rilascio), diagnostica scaricabile (zip con log, versioni, configurazione senza segreti).
9. **Impostazioni** (086, 087): SMTP con prova, PEC, sicurezza (password, 2FA per livello, sessioni, rate limit, upload, CSP), archiviazione e cloud (volume, S3 compatibile, WebDAV, retention copie remote), cache/Redis, notifiche, rete/URL, retention log; **rotazione di `KHAEMHAT_SECRET_KEY`** guidata (ri-cifra i segreti con la nuova chiave fornita via env `KHAEMHAT_SECRET_KEY_NEW`, poi si rimuove la vecchia).
10. **Chiavi API, MCP e webhook** (088).
11. **Dati di base e di esempio** (089): pacchetti dati con versione, *Aggiorna tabelle di base* (idempotente), *Carica dati di esempio* (solo azienda senza documenti reali), *Rimuovi dati di esempio* (super utente).
12. **Import/Export** (077): procedura guidata CSV/XLSX/JSON per anagrafiche, articoli, listini, giacenze iniziali, piano dei conti, saldi iniziali e partite di apertura; mappatura colonne, anteprima, validazione, report errori.
Ogni utente ha **Il mio profilo** (008): dati, password, 2FA, sessioni, tema/accento/densità/menu, pagina iniziale e dashboard, layout salvati, notifiche.
---
## 13. Backup e ripristino (integrati; per ogni database)
- **PostgreSQL**: l'immagine include `postgresql-client-17` (`pg_dump` deve essere ≥ versione del server: server 16 o 17; per 18 aggiornare l'immagine). `PgDumpRunner` esegue `pg_dump -Fc --no-owner --no-privileges` verso `/data/backups/<db>/bk-<db>-<timestamp>.dump` in streaming, con `sha256`, cifratura AES-256-GCM (chiave da `KHAEMHAT_SECRET_KEY`) e copie remote su **S3 compatibile** (`S3Client` SigV4 in casa, multipart) e **WebDAV** (NAS/cloud personali). Verifica con `pg_restore --list`. Allegati dell'azienda inclusi come tar.
- **SQLite**: `VACUUM INTO` (copia consistente) + stessa pipeline. **Backup logico** portabile (JSON Lines per tabella + manifest): indipendente dal motore, per migrare SQLite → PostgreSQL e per disaster recovery.
- **Politica** per database o per istanza (`sys_backup_policies`): pianificazione, retention giornalieri/settimanali/mensili (GFS), destinazioni, cifratura, verifica, notifica errori, avviso se l'ultimo backup riuscito è più vecchio di N ore; il database di sistema è sempre incluso.
- **Ripristino** (`PgRestoreRunner`): (1) manutenzione per l'azienda, (2) backup di sicurezza dello stato corrente, (3) ripristino in `khaemhat_restore_<ts>` con `pg_restore -Fc --no-owner`, (4) controllo versione schema e migrazioni mancanti, (5) verifica integrità, (6) scambio atomico (rinomina; richiede proprietà del database e `CREATEDB`; in alternativa ripristino in-place con `--clean --if-exists` dopo terminazione delle connessioni), (7) fine manutenzione, log e audit. Avviato da un amministratore, **confermato dal super utente** (notifica + TOTP). *Prova di ripristino* su database temporaneo senza scambio. Ripristino da backup logico su database vuoto. Ripristino del database di sistema solo da CLI (`scripts/restore-system.sh`) con l'istanza ferma.
- Documentazione in `docs/wiki/Backup-e-ripristino.md` con la procedura manuale equivalente (`docker exec … pg_dump`) e la strategia consigliata (backup app + snapshot volume Unraid/EBS).
---
## 14. Dati di base e dati di esempio (`Seeding`)
- `ISeeder { Module; SeedKind (Base|Demo); Order; RunAsync(SeedContext) }`; dati in C# o CSV incorporati (`EmbeddedResource`); versione del pacchetto dati (`IT 2026.2`) in `settings`.
- **Base**: paesi ISO; province e comuni (CAP, codice catastale); valute; UM; **codici IVA** con nature (22, 10, 5, 4, ESE10 N4, NI8 N3.1, NI41 N3.2, NI71 N3.3, NI8C N3.5, FC7 N2.1, fuori campo altre N2.2, ESC15 N1, RC17 N6.x, SPLIT, NS, indetraibili 50%/100%, forfettari); `MP01–MP23`; condizioni di pagamento; causali magazzino; depositi; trasporti; categorie; numeratori; **piano dei conti standard PMI** con voci CEE; **causali contabili**; registri IVA; **categorie cespiti** con coefficienti; **codici tributo F24**; code list SDI; regime RF01; tipi documento; pipeline e fasi CRM; modelli e-mail; ruoli; regole di automazione predefinite; attività programmate di sistema; tabella ABI/CAB.
- **Demo** (solo azienda vuota, righe `is_demo`): "Khaemhat Demo S.r.l." con dati **fittizi** (mai nomi di aziende, banche, marchi o prodotti reali): 3 depositi, 2 listini, 40 clienti (aziende, PA con split, privati, UE, extra-UE, forfettario, con dichiarazione d'intento, bloccato per fido), 15 fornitori (professionista con ritenuta, agente ENASARCO, estero per TD17/TD18), 120 articoli, 3 agenti, 5 vettori, 12 mesi di documenti coerenti (ordini → DDT → differite, immediate, accompagnatorie, NC, pro-forma, parcelle, ordini fornitore → carichi → fatture acquisto, autofatture, inventario, movimenti, trasferimenti), **contabilità completa** (registrazioni da documenti, incassi/pagamenti parziali, insoluto RiBa, giroconti, liquidazioni confermate fino al mese precedente, ritenute, 58 cespiti con ammortamenti, esercizio precedente chiuso con bilancio), XML SDI con stati diversi e notifiche, estratto conto da riconciliare, CRM (23 lead, 18 opportunità, attività, 3 campagne, 2 ticket), 2 contratti di servizio con interventi, 1 canale generico con ordini, allegati e file generati di esempio, utenti demo per ogni ruolo (password mostrata nella pagina admin), voci di log di esempio in tutte le sezioni.
- Il seeder demo usa i motori (documenti, contabile) e diventa un test end-to-end: `Khaemhat.Application.Tests` esegue base+demo su SQLite e verifica quadrature (giacenze = movimenti; partite = scadenze − incassi; totali documento = righe + castelletto; ogni registrazione quadra; saldi partitari = partite aperte; bilancio di verifica a zero).
---
## 15. REST API e MCP (modulo API) — mockup 088
- `/api/v1/{modulo}/{risorsa}` JSON `camelCase`, API key (`Authorization: Bearer kh_…`) o cookie; header `X-Company`; paginazione `?page&pageSize&sort&filter`; errori RFC 9457 con `trace_id`; ETag/`If-Match`; idempotenza (`Idempotency-Key`); rate limiting per chiave. Risorse: parties, items, price-lists, sale-orders, delivery-notes, invoices, purchase-orders, purchase-invoices, inventory/balances, inventory/entries, ledger/accounts, ledger/entries, open-items, payments, e-invoices, attachments (`GET` download, `POST` upload su un documento), crm/leads, crm/opportunities, crm/activities, channels/{code}/orders, reports/{code}, admin/status (sola lettura). OpenAPI 3.1 generato in-house su `/api/v1/openapi.json` + pagina `/api/docs`.
- **MCP** (Streamable HTTP, JSON-RPC 2.0) su `/mcp` con API key: `initialize`, `tools/list`, `tools/call`, `ping`; tool in lettura `search_parties`, `get_party`, `search_items`, `get_item_stock`, `get_document`, `list_documents`, `get_open_items`, `sales_summary`, `get_account_balance`, `trial_balance`, `vat_settlement_preview`, `crm_pipeline_summary`, `get_log_errors` (amministratori); in scrittura opzionali per chiave: `create_sale_order`, `create_party`, `create_crm_activity`. Documentazione in `docs/wiki/MCP.md`.
- Webhook in uscita (eventi delle automazioni) con firma HMAC e retry.
---
## 16. Docker, CI su GitHub, GHCR, Unraid, icona
### 16.1 Dockerfile
Stage `build`: `mcr.microsoft.com/dotnet/sdk:10.0` → restore con cache, `scripts/check-packages.sh`, test opzionali (`--build-arg RUN_TESTS=true`), `dotnet publish src/Khaemhat.Web -c Release -o /app /p:Version=$VERSION /p:SourceRevisionId=$GIT_SHA`. Stage `runtime`: `mcr.microsoft.com/dotnet/aspnet:10.0` + `postgresql-client-17 curl tzdata` (repository PGDG) + utente `app` non root con `PUID/PGID`; `VOLUME /data`; `EXPOSE 8080`; `HEALTHCHECK CMD curl -fs http://localhost:8080/health/live || exit 1`; `ENTRYPOINT ["/app/entrypoint.sh"]`. Etichette OCI (`org.opencontainers.image.*`) e **`net.unraid.docker.icon`**, **`net.unraid.docker.webui="http://[IP]:[PORT:8080]/"`**. Architetture: `linux/amd64` di default; `linux/arm64` con `publish-image.sh --arm64`.
### 16.2 Compose e template (`deploy/`, Appendice C)
`docker-compose.yml` (app + `postgres:17` + `redis:7` profilo), `docker-compose.sqlite.yml` (demo), **`docker-compose.unraid.yml`** (etichette `net.unraid.docker.managed/webui/icon`, volumi in `/mnt/user/appdata/khaemhat`, `PUID 99`/`PGID 100`), **`unraid/khaemhat.xml`** (template Community Applications con `<Icon>`, `<WebUI>`, porte, volumi, variabili mascherate). L'icona dei template deve essere raggiungibile senza autenticazione: `https://raw.githubusercontent.com/<owner>/khaemhat-assets/main/icon-256.png` (repository pubblico `khaemhat-assets`, anche se il repository principale è privato).
### 16.3 GitHub con minuti di CI contati
- Remote `origin` = GitHub (`GITHUB_REPO_URL` fornito dall'utente); `git init -b main`, Conventional Commits, tag `vX.Y.Z` a ogni milestone, `CHANGELOG.md` (Keep a Changelog); note di rilascio dal CHANGELOG.
- **Il rilascio normale non usa Actions**: `scripts/publish-image.sh` costruisce in locale (`docker buildx build`) e fa push su **GHCR** (`ghcr.io/<owner>/khaemhat:<versione>` e `:latest`) con un token `write:packages`; lo script tagga anche il repository e aggiorna il CHANGELOG. Da Unraid si tira l'immagine con `docker login ghcr.io` (token `read:packages`) se il package è privato.
- `.github/workflows/ci.yml`: **solo** `pull_request` verso `main` e `push` di tag; `paths-ignore: ["docs/**", "*.md", "assets/**", "deploy/**"]`; un solo job su `ubuntu-latest`; cache NuGet (`actions/cache` sulla cartella `~/.nuget/packages` con chiave da `Directory.Packages.props`); `dotnet build -warnaserror` + test su SQLite; PostgreSQL come `services:` solo quando il tag inizia con `v`; `timeout-minutes: 15`; `concurrency` con cancellazione delle esecuzioni superate. Niente matrix, niente esecuzione su ogni push di branch.
- `.github/workflows/release.yml`: solo `workflow_dispatch` (facoltativo, per chi non può costruire in locale): build + push su GHCR `linux/amd64`; arm64 opzionale via input.
- `.github/workflows/wiki.yml`: su `push` a `main` con `paths: ["docs/wiki/**"]`: clona `<repo>.wiki.git`, sincronizza, commit e push (durata sotto il minuto). In alternativa `scripts/publish-wiki.sh` da locale.
- `docs/DEPLOY.md` e wiki *Installazione*: host Docker generico (VPS, istanza cloud), un progetto compose per istanza (più aziende dentro), reverse proxy TLS a scelta dell'installatore, dimensionamento, backup (app + `pg_dump` host + snapshot), aggiornamento (`docker compose pull && up -d` su tag esplicito, mai `latest` in produzione), rollback (tag precedente + ripristino backup se le migrazioni sono cambiate), rotazione segreti.
### 16.4 Unraid
`docs/wiki/Installazione-Unraid.md`: rete docker personalizzata (`khaemhat-net`), container PostgreSQL dal template ufficiale o dal compose, template CA importato o compose con il plugin di gestione compose, cartelle `appdata`, `PUID/PGID` 99/100, reverse proxy e TLS, backup (plugin di backup appdata + backup applicativo), aggiornamento dall'icona del container (tag esplicito), icona e WebUI dalle etichette.
### 16.5 Versione nel prodotto
La versione SemVer (`major.minor.patch`, con `+sha`) compare: nella barra superiore (solo `major.minor` accanto al nome), nella barra di stato (completa), in *Stato sistema*, nel `manifest.webmanifest`, nelle etichette OCI e nell'**icona versionata** (§16.6) generata al build per la versione `major.minor`.
### 16.6 Icona
`assets/icon.svg` è l'icona ufficiale: quattro tessere dorate su fondo blu notte, ognuna con un glifo di una funzione del gestionale — **documento con €** (vendite/fatture), **collo** (magazzino), **istogramma con trend** (contabilità/analisi), **persone** (CRM/anagrafiche). Varianti fornite: `icon-v1.0.svg` con la fascia dorata "v 1.0" in basso (le tessere sono ridotte per far posto al numero), `icon-mono.svg` (solo tessere, per favicon 16–32 px), PNG 16–512, `favicon.ico`. Regole: la variante versionata mostra solo `major.minor`; `scripts/build.sh` rigenera `icon-v<major.minor>.svg/png` sostituendo il testo nel template SVG (nessuna libreria: è una sostituzione di stringa) e l'immagine Docker usa quella versionata come `net.unraid.docker.icon` quando pubblicata in `khaemhat-assets` (`icon-v1.0-256.png`), altrimenti quella semplice. Usala per favicon, manifest PWA, marca nella barra, pagina di accesso, e-mail. Sorgente SVG in Appendice B; colori `--kh-brand` (#C8962E/#E0B04A) e `--kh-topbar` (#17243A) sono quelli di `tokens.css`.
---
## 17. Documentazione (wiki) — obbligatoria e sempre aggiornata
- **Sorgente di verità: `docs/wiki/`** nel repository, pubblicata nel **wiki del repository GitHub** (`<repo>.wiki.git`) da `wiki.yml` o `publish-wiki.sh`. Convenzioni: `Home.md`, `_Sidebar.md`, `_Footer.md`, link `[Pagina](Nome-Pagina)`, immagini in `docs/wiki/img/` (gli screenshot reali sostituiscono progressivamente i mockup), stato in testa (`bozza/completa/da aggiornare`), ultima revisione e versione software.
- Struttura: Installazione (Unraid, Docker/cloud, Aggiornamento, Backup e ripristino), Primi passi, Guida utente per modulo (Interfaccia e scorciatoie, Dashboard, Anagrafiche, Articoli e listini, Vendite, Acquisti, Magazzino, Contabilità, IVA, Cespiti, Scadenzario, Fatturazione elettronica e canali SDI, CRM, Servizi, Canali, Report, Automazioni, Allegati e file), Amministrazione (Istanza e database, Licenze e moduli, Utenti e permessi, Attività programmate, Backup, Log, Impostazioni, API e MCP), Riferimenti (Fiscalità italiana: TD/nature/MP/RF/tributi/scadenze; API; MCP; Glossario; FAQ), Sviluppo (Architettura, Modello dati, Design UI, Contribuire, Changelog).
- **Aiuto in app** (011): F1 e "?" aprono la pagina wiki della maschera (`HelpLink` per pagina; URL base configurabile; copia della wiki servita su `/help` per installazioni offline).
- **Regole di aggiornamento** (parte della Definition of Done §20): ogni milestone porta le pagine dei moduli consegnati da *bozza* a *completa*; ogni modifica funzionale, di schema o di API aggiorna wiki + `docs/DATA-MODEL.md`/`docs/API.md` + `CHANGELOG.md` nello **stesso commit**; ogni cambiamento visivo aggiorna screenshot e `Design-UI.md`; decisioni negli ADR; `docs/STATUS.md` a fine sessione.
- Documentazione tecnica in `docs/`: `ARCHITECTURE.md`, `DATA-MODEL.md` (generato da `scripts/gen-datamodel.sh`), `MODULES.md`, `API.md`, `MCP.md`, `DEPLOY.md`, `DEVELOPMENT.md`, `SECURITY.md`, `STATUS.md`, `adr/`.
---
## 18. Test e verifica
- `scripts/test.sh` verde a ogni milestone: unit (`Core`), dialetti/migrazioni (`Data`, SQLite + PostgreSQL con `KHAEMHAT_TEST_PG`), infrastruttura (RESP, IMAP contro un server fittizio in-process, PDF, XLSX, backup/ripristino SQLite, S3 SigV4 su vettori noti, WebDAV contro server fittizio), `Fiscal.Italy` (FatturaPA writer vs golden file + round-trip, validator con scarti noti 00311/00423/00327, LIPE, F24, Intrastat), licenze (codici test accettati solo in modalità test; firma ECDSA), applicazione (flussi documentali, autofattura TD17, incasso con abbuono, insoluto, liquidazione che blocca il periodo, chiusura esercizio completa su demo, seed base+demo con quadrature, permessi per livello, multi-azienda con due database, allegati e generazione file, log per sezione, concorrenza ottimistica, automazioni), web (login/livelli, cookie, API key, health, MCP handshake, menu compresso e dashboard persistite).
- Test di architettura: dipendenze tra progetti, nessun `PackageReference` fuori allowlist, nessun testo UI hard-coded, nessun accesso al pacchetto fiscale fuori dalle interfacce, nessun `Process.Start` fuori da `Infrastructure/Backup`.
- Checklist manuale per milestone in `docs/DEVELOPMENT.md` con `docker compose -f deploy/docker-compose.sqlite.yml up`: login super utente e cambio password, creazione amministratore e seconda azienda, utente standard, tema scuro + accento, menu compresso, dashboard personalizzata, carica base/demo, fattura → PDF allegato → XML, prima nota, liquidazione, backup → prova di ripristino, attività programmata, log con filtro.
- Prestazioni con demo ×10: radar < 300 ms/pagina su PostgreSQL, salvataggio fattura 50 righe con contabilizzazione < 700 ms, liquidazione mensile < 5 s, bilancio di verifica su 2 M righe < 10 s, ricostruzione giacenze 100k movimenti < 60 s, backup 2 GB < 5 min, pagina log con 1 M righe < 1 s per filtro.
---
## 19. Regole di codice
`record` per DTO/value object, `sealed` di default, `decimal` per importi e quantità (mai `double`), `DateOnly`/`DateTime` UTC con conversione a `Europe/Rome` solo in presentazione; async con `CancellationToken`; `Result<T>` per gli esiti attesi ed eccezioni di dominio localizzabili; validazione in `Core`/`Application` (l'UI mostra, non decide); niente logica in `.razor` (code-behind + servizi); ogni servizio applicativo è transazionale per operazione; motore documenti e contabile garantiscono atomicità documento + magazzino + partite + registrazione + numerazione + allegati; ogni modulo logga nella propria sezione con `trace_id`; commenti solo per i *perché*; XML doc sui tipi pubblici di `Core`, `Data`, `Fiscal.Abstractions`; ogni file appartiene a un modulo; nessuna cartella "Utils".
---
## 20. Piano di esecuzione (milestone) e Definition of Done
| # | Milestone | Contenuto | Tag |
|---|---|---|---|
| 0 | Bootstrap | Soluzione, progetti, `Directory.*.props`, allowlist + `check-packages.sh`, copia di `assets/`, `deploy/`, `docs/mockups/`, `docs/wiki/`; Dockerfile e compose con pagina "in costruzione" e favicon; `/health`; `ci.yml`, `wiki.yml`, `release.yml`; `publish-image.sh`; README; ADR 0001–0008 (stack, no-external-libs, Blazor Server, micro-ORM, multi-DB, sistema+aziende, pacchetto fiscale, licenze a moduli) | `v0.0.1` |
| 1 | Strato dati | `Khaemhat.Data`, provider SQLite/PostgreSQL, migrazioni (sistema e azienda), query builder, registry database, segreti cifrati, test | `v0.1.0` |
| 2 | Sistema e sicurezza | DB di sistema, super utente dal container, amministratori, aziende (crea/collega), utenti per azienda, ruoli/permessi, login/2FA, sessioni, **licenze e moduli con codici test**, DataProtection su DB, cache memoria+Redis, scheduler base, **log avanzato per sezioni**, audit, notifiche | `v0.2.0` |
| 3 | Framework UI | Layout con menu comprimibile, TabHost, libreria `Kh*` dai mockup, toolbar a icone, intestazione documento e gruppi di campi, temi/accenti/densità, preferenze, **dashboard a widget personalizzabile e disattivabile**, localizzazione, radar, ricerca globale, scorciatoie, aiuto F1, stampa HTML/PDF di prova, **allegati e generazione file** sul primo documento | `v0.3.0` |
| 4 | Tabelle, anagrafiche, articoli | Company, pacchetto `Fiscal.Italy` (codici IVA, nature, code list, comuni), Parties, Items, listini, codici automatici, VIES, import/export (incl. piano dei conti CSV/XLSX/JSON), seed base | `v0.4.0` |
| 5 | Motore documenti e Vendite | Numeratori, totali, scadenze, flussi, stampe, allegati per documento; preventivi, ordini, DDT, fatture (tutti i TD), parcelle, NC/ND, pro-forma, differita | `v0.5.0` |
| 6 | Acquisti e Magazzino | Ordini/carichi/fatture fornitore con protocollo, import XML/P7M, autofatture TD16–TD29, movimenti, giacenze, inventario, riordino, ricostruzioni | `v0.6.0` |
| 7 | Contabilità generale | Piano dei conti (precaricato + import), causali, prima nota, contabilizzazione automatica, partitari, registri IVA, liquidazione + F24 + LIPE, bollo, ritenute, bilancio di verifica | `v0.7.0` |
| 8 | Scadenzario e tesoreria | Partite, incassi/pagamenti, abbuoni, insoluti, RiBa/SDD/SEPA, riconciliazione, solleciti, flusso di cassa | `v0.8.0` |
| 9 | Fatturazione elettronica | FatturaPA writer/validator/reader, notifiche, **canale PEC integrato (SMTP + IMAP in casa)**, SdICoop, connettori intermediari A e B, cruscotto, instradamento, conservazione export, inbox; seed demo completo | `v0.9.0` |
| 10 | Cespiti, Intrastat, chiusura, bilancio | Registro cespiti, Intrastat, dichiarazioni d'intento, ratei/risconti, chiusura/apertura, libri definitivi, bilancio CEE e riclassificati, export commercialista | `v0.10.0` |
| 11 | CRM | Lead, pipeline, attività e agenda, campagne, ticket, scheda 360°, dashboard CRM, import lead API | `v0.11.0` |
| 12 | Amministrazione, automazioni, API | Istanza e database (clona/elimina/manutenzione), attività programmate da UI, **backup/ripristino PostgreSQL + logico + S3 + WebDAV**, impostazioni e rotazione segreti, stato sistema e aggiornamenti GHCR, chiavi API, REST+OpenAPI, MCP, webhook, regole/procedure, import saldi/partite | `v0.12.0` |
| 13 | Consolidamento e rilascio | Hardening, prestazioni, accessibilità, wiki completa, `publish-image.sh` e prima immagine su GHCR, template Unraid verificato, icona versionata, PWA | `v1.0.0` |
| 14 | Fase 2 | Servizi (contratti/interventi), Canali e-commerce (generico + primi connettori), EN 16931/Peppol, XBRL, regime del margine, ventilazione corrispettivi, IVA per cassa completa, SFTP per backup | `v1.1.0`+ |
**Definition of Done per milestone:** compila senza warning; `check-packages.sh` e `test.sh` verdi su SQLite (e PostgreSQL se disponibile); maschere raggiungibili dal menu, protette da permessi e licenza, localizzate, coerenti con i mockup (toolbar a icone, intestazione documento, gruppi di campi); migrazioni da zero e idempotenti; seed base e demo estesi; log per sezione dei nuovi moduli; **wiki delle funzioni consegnate completa** e `docs/*.md` aggiornati; `CHANGELOG.md`; commit e tag; l'immagine si costruisce in locale e la demo SQLite parte da zero.
---
## 21. Elenco delle classi principali
### `Khaemhat.Core`
`Entity<TKey>`, `IEntity<TKey>`, `IAuditable`, `IDemoMarkable`, `Result`, `Result<T>`, `Error`, `DomainException`, `ConcurrencyException`, `ModuleNotLicensedException`, `Money`, `Quantity`, `Percentage`, `DiscountFormula`, `IClock`, `SystemClock`, `ICurrentUser`, `ICompanyContext`, `IEventBus`, `DomainEvent`, `Guard`.
Entità azienda/tabelle: `CompanyProfile`, `FiscalYear`, `FiscalPeriod`, `Country`, `Province`, `Municipality`, `Currency`, `ExchangeRate`, `UnitOfMeasure`, `TaxCode`, `PaymentMethod`, `PaymentTerm(+Line)`, `BankAccount`, `Salesperson`, `Carrier`, `ShippingTerm`, `TransportMean`, `GoodsAppearance`, `DeliveryTerm`, `TransportReason`, `DocumentNumerator`, `InventoryReason`, `Warehouse`, `ItemCategory`, `PartyCategory`, `PriceList`, `DiscountPolicy`, `DocumentType`, `CostCenter`, `Job`, `CodeSequence`, `CodeRule`.
Anagrafiche/articoli: `Party`, `PartyAddress`, `PartyContact`, `PartyBankAccount`, `PartySalesTerms`, `PartyPurchaseTerms`, `PartyFiscal`, `PartyItemCode`, `IntentDeclaration`; `Item`, `ItemUom`, `ItemBarcode`, `ItemPrice`, `ItemSupplier`, `ItemSubstitute`.
Documenti: `SaleQuotation(+Line,+Revision)`, `SaleOrder(+Line)`, `SaleDocument(+Line,+TaxSummary,+Installment)`, `PurchaseOrder(+Line)`, `PurchaseDocument(+Line,+TaxSummary,+Installment)`, `InventoryDocument(+Line)`, `DocumentLink`, `InventoryEntry(+Line)`, `ItemBalance`, `StockTake(+Line)`, `Attachment`.
Contabilità: `GlAccount`, `JournalTemplate(+Line)`, `GlEntry`, `GlEntryLine`, `GlEntryVat`, `VatRegister`, `VatSettlement(+Line)`, `StampDutyEntry`, `WithholdingTax`, `SocialSecurityCharge`, `FixedAsset`, `FixedAssetCategory`, `FixedAssetMovement`, `IntrastatDeclaration(+Line)`, `AccrualDeferral`, `ClosingRun(+Step)`, `FinancialStatementLine`, `RecurringEntryTemplate`.
Finanza: `OpenItem`, `Payment(+Line)`, `Remittance(+Line)`, `SddMandate`, `BankStatement(+Line)`, `BankMatchRule`, `DunningRun(+Line)`, `DunningLevel`.
E-invoicing: `EInvoice`, `SdiNotification`, `EInvoiceInboxFile`, `SdiChannel`, `SdiRoutingRule`, `ConservationPackage`.
CRM/Servizi/Canali: `Lead`, `Pipeline`, `PipelineStage`, `Opportunity`, `CrmActivity`, `Campaign(+Member)`, `Ticket`, `EmailTemplate`, `Segment`; `ServiceContract(+Line)`, `ServiceTeam`, `ServiceTechnician`, `ServiceIntervention(+Line)`; `SalesChannel`, `ChannelItem`, `ChannelOrder`, `ChannelCustomer`.
Azienda (utenti): `User` (`Kind`), `Role`, `Permission`, `RolePermission`, `UserRole`, `UserPermissionOverride`, `UserSession`, `UserSetting`, `ApiKey`, `Notification`, `AuditEntry`, `DashboardLayout`, `AutomationRule`, `AutomationRun`, `Webhook`.
Sistema: `Company` (registry), `SystemUser` (`Level`), `License`, `LicenseActivation`, `SystemSetting`, `DataProtectionKey`, `LogEntry` (con `Section`), `SecurityAuditEntry`, `ScheduledTask`, `JobRun`, `BackupSet`, `BackupPolicy`, `SystemNotification`, `SystemSession`, `LoginAttempt`.
Enum: `DbEngine`, `DatabaseScope`, `UserLevel` (SuperUser/Administrator/Standard), `UserKind`, `CompanyStatus`, `ModuleCode`, `LicenseMode`, `PartyKind`, `PartyType`, `ItemType`, `DocumentKind`, `DocumentStatus`, `EInvoiceStatus`, `SdiChannelKind` (Pec, SdiCoop, IntermediaryA, IntermediaryB), `LineType`, `TaxNature`, `TaxExigibility`, `VatRegisterType`, `EntryStatus`, `AccountNature`, `AccountKind`, `OpenItemStatus`, `RemittanceKind`, `AssetMovementKind`, `LeadStatus`, `ActivityKind`, `TicketStatus`, `AttachmentKind`, `LogSection`, `SeedKind`, `ThemeMode`, `AccentColor`, `Density`, `MenuState`, `AutomationTrigger`, `AutomationActionKind`, `BackupKind`, `BackupStatus`, `BackupTarget` (Local, S3, WebDav).
Regole: `DocumentTotalsCalculator`, `TaxSummaryBuilder`, `InstallmentGenerator`, `StampDutyRule`, `WithholdingCalculator`, `SocialSecurityCalculator`, `PriceResolver`, `DiscountResolver`, `StockEffectMatrix`, `UomConverter`, `NumberFormatter`, `DocumentNumberFormat`, `CodeMaskFormatter`, `JournalPostingRules`, `VatSettlementCalculator`, `ProRataCalculator`, `DepreciationCalculator`, `AccrualDeferralCalculator`, `ExchangeDifferenceCalculator`, `AgingCalculator`, `LeadScoring`, `DunningRules`, `BankMatcher`, `TodoAggregator` (widget *Da fare*), `DoneAggregator` (widget *Fatto oggi*), `DeadlineAggregator`.
Validatori: `ItalianVatNumberValidator`, `FiscalCodeValidator` (+ `FiscalCodeCalculator`), `IbanValidator`, `EanValidator`, `SdiRecipientCodeValidator`, `EmailValidator`, `JournalEntryValidator`, `ChartOfAccountsImportValidator`, `Validator<T>`, `ValidationResult`.
### `Khaemhat.Fiscal.Abstractions` / `Khaemhat.Fiscal.Italy`
`IFiscalPack`, `ITaxEngine`, `ITaxCodeCatalog`, `IEInvoiceFormat`, `IEInvoiceNotificationReader`, `ISdiTransport`, `IFiscalReports`, `IFiscalCalendar`, `IWithholdingRules`, `IFixedAssetRules`, `IFinancialStatementsSchema`, `IChartOfAccountsTemplate`, `IIntrastatExporter`, `ITaxPaymentFormExporter`; `ItalyFiscalPack`, `ItalianTaxEngine`, `ItalianTaxCodeCatalog`, `VatNatures`, `ReverseChargeRules`, `SplitPaymentRules`, `CashVatRules`, `VatSettlementRules`, `VatAdvanceCalculator`, `LipeWriter`, `FatturaPaWriter`, `FatturaPaReader`, `FatturaPaValidator`, `FatturaPaDocument`, `FatturaPaCodeLists`, `SdiFileNaming`, `SdiNotificationParser`, `P7mExtractor`, `CadesVerifier`, `PecSdiTransport` (SMTP + IMAP), `SdiCoopTransport` (SOAP + certificato client), `IntermediaryATransport`, `IntermediaryBTransport`, `SdiRouter`, `WithholdingRulesIt`, `EnasarcoRules`, `CuExporter`, `F24Model`, `F24Codes`, `F24Exporter`, `IntrastatModel`, `IntrastatExporterIt`, `CombinedNomenclature`, `StampDutyRulesIt`, `FixedAssetRulesIt`, `MinisterialCoefficients`, `CeeSchema2424`, `CeeSchema2425`, `FinancialRatios`, `ItalianChartOfAccountsTemplate`, `ChartOfAccountsCsvFormat`, `ChartOfAccountsJsonFormat`, `MunicipalitiesDataset`, `AbiCabDataset`.
### `Khaemhat.Data` (+ provider) e `Khaemhat.Infrastructure`
`IDbProvider`, `ISqlDialect`, `ISchemaBuilder`, `IUnitOfWork(+Factory)`, `IRepository<,>`, `Repository<,>`, `ICompanyRegistry`, `CompanyRegistry`, `DatabaseScope`, `EntityMap<T>`, `ColumnMap`, `ColumnType`, `MapRegistry`, `QueryBuilder<T>`, `Query<T>`, `PagedResult<T>`, `SqlFragment`, `ExpressionTranslator`, `DbExecutor`, `ReaderMapper<T>`, `CommandCache`, `TransientRetryPolicy`, `IMigration`, `MigrationAttribute`, `MigrationRunner`, `MigrationCatalog` (System/Company), `SchemaVersionStore`, `TableDefinition`/`ColumnDefinition`/`IndexDefinition`/`ForeignKeyDefinition`, `DdlGenerator`, `SqliteProvider`/`Dialect`/`SchemaBuilder`/`WriteLock`/`DecimalConverter`, `PostgresProvider`/`Dialect`/`SchemaBuilder`/`DatabaseCreator`/`AdvisoryLocks`/`Partitioning`/`ServerInfo`;
`ICacheProvider`, `MemoryCacheProvider`, `RedisCacheProvider`, `RespClient`, `RespReader`, `RespWriter`, `RedisConnectionPool`, `RedisSubscriber`; `PasswordHasher`, `PasswordPolicy`, `TotpGenerator`, `SecureTokenGenerator`, `ApiKeyHasher`, `DataProtectionDbXmlRepository`, `SecretProtector` (AES-256-GCM con `KHAEMHAT_SECRET_KEY`), `SecretRotation`; `LicenseKey`, `LicenseDocument`, `LicenseVerifier`, `ModuleActivationCode`, `TestLicenseCatalog`, `ILicenseActivationService`, `OfflineActivationService`, `LicenseMonitor`; `IMailSender`, `SmtpMailSender`, `MailQueue`, `MailTemplateRenderer`, `ImapClient` (minimo: LOGIN, SELECT, SEARCH, FETCH, STORE, LOGOUT, TLS), `MimeParser`; `PdfWriter`, `PdfDocument`, `PdfPage`, `PdfFont`, `PdfTextLayout`, `PdfImage`, `PdfA3Embedder`; `CsvWriter`, `CsvReader`, `XlsxWriter`, `XlsxReader`, `ZipStreamWriter`; `IJobScheduler`, `JobRunner`, `JobDefinition`, `JobContext`, `CronExpression`, `JobLock`; `IFileStore`, `VolumeFileStore`, `StoredFile`, `AttachmentStore`, `GeneratedFileFactory`; `PgDumpRunner`, `PgRestoreRunner`, `SqliteBackup`, `LogicalBackupWriter`, `LogicalBackupReader`, `BackupEncryptor`, `S3Client`, `SigV4Signer`, `WebDavClient`, `RetentionPolicy`, `BackupVerifier`; `ViesClient`, `EcbRatesClient`, `GhcrPackagesClient`, `OutboundWebhookClient`; `McpServer`, `JsonRpc*`, `McpTool`, `McpToolRegistry`, `McpSchemaGenerator`; `DbLogSink`, `DbLoggerProvider`, `JsonConsoleFormatter`, `LogSectionScope`, `SlowQueryLogger`, `LogAlertRules`; `NotificationDispatcher`.
### `Khaemhat.Application`
`IModule`, `ModuleRegistry`, `ModuleInfo`, `MenuItem`, `PermissionDefinition`, `HelpLink`, `LicenseGate`; `DocumentDefinition(s)`, `DocumentService<,>`, `Sale*`/`Purchase*`/`Inventory*Service`, `DocumentFlowService`, `DocumentFlowWizard`, `FulfillmentCalculator`, `DocumentPostingService`, `InventoryPoster`, `InstallmentPoster`, `LedgerPoster`, `DocumentNumberingService`, `DocumentStateMachine`, `DocumentCopyService`, `DeferredInvoicingService`, `DocumentPrintService`, `IDocumentPrinter`, `HtmlDocumentPrinter`, `PdfDocumentPrinter`, `DocumentMailService`, `SelfInvoiceService`, `AttachmentService`, `FileGenerationService`; `JournalService`, `PostingEngine`, `PeriodLockService`, `LedgerQueries`, `PartitarioService`, `VatRegisterService`, `VatSettlementService`, `StampDutyService`, `WithholdingService`, `FixedAssetService`, `DepreciationService`, `IntrastatService`, `IntentDeclarationService`, `AccrualDeferralService`, `ClosingProcedure` (+ `ClosingStep`), `TrialBalanceService`, `FinancialStatementsService`, `RecurringEntriesService`, `ExchangeDifferenceService`, `ChartOfAccountsImportService`; `OpenItemService`, `PaymentService`, `RemittanceService`, `SddMandateService`, `BankStatementImportService`, `BankReconciliationService`, `DunningService`, `CashFlowForecastService`, `AgingReportService`; `EInvoiceService`, `EInvoiceExportService`, `SdiChannelService`, `SdiInboxService`, `SdiNotificationImportService`, `PurchaseInvoiceImportService`, `ConservationExportService`; `LeadService`, `OpportunityService`, `PipelineService`, `ActivityService`, `CampaignService`, `TicketService`, `Party360Service`, `CrmDashboardService`, `SalesForecastService`; `ContractService`, `InterventionService`, `InterventionSchedulingService`, `ServiceBillingService`; `IChannelConnector`, `GenericChannelConnector`, `ChannelOrderImportService`, `ChannelSyncService`; `ReportDefinition`, `ReportRunner`, `ReportCatalog`, `ScheduledReportService`; `DashboardService`, `WidgetCatalog`; `SystemUserService`, `UserService`, `RoleService`, `PermissionService`, `SessionService`, `LicenseService`, `ModuleActivationService`, `CompanyService` (crea/collega/clona/elimina/migra), `MaintenanceModeService`, `DatabaseMaintenanceService`, `IntegrityCheckService`, `RebuildService`, `ScheduledTaskService`, `BackupService`, `RestoreService`, `SystemSettingsService`, `SecretRotationService`, `LogQueryService`, `LogAlertService`, `SystemStatusService`, `UpdateCheckService`, `ApiKeyService`, `WebhookService`, `ImportWizardService`, `CsvImportMapper`, `OpeningBalancesImportService`; `CodeRuleService`, `CodeSequenceService`, `AutoFillService`, `RuleEngine`, `TriggerCatalog`, `ConditionEvaluator`, `ActionExecutor`, `ProcedureCatalog`, `IProcedure`, `ProcedureRunner`; `UserSettingsService`, `CompanySettingsService`; `ISeeder`, `SeedRunner`, `SeedContext`, `BaseDataSeeder`/`DemoDataSeeder` per area, `DemoDataRemover`; `GlobalSearchService`; `AuditTrailService`.
### `Khaemhat.Web`
`Program`, `KhaemhatOptions`, `EnvironmentConfigurationReader`, `StartupOrchestrator`, `HealthEndpoints`, `MetricsEndpoint`, `MaintenanceMiddleware`, `TraceIdMiddleware`; `CookieSessionAuthenticationHandler`, `ApiKeyAuthenticationHandler`, `SessionStore`, `CurrentUserAccessor`, `CompanyContextAccessor`, `PermissionAuthorizationHandler`, `RequirePermissionAttribute`, `RequireLevelAttribute`, `RequireModuleAttribute`, `LoginRateLimiter`, `SecurityHeadersMiddleware`, `ProblemDetailsMiddleware`; `<Modulo>Endpoints`, `AttachmentEndpoints`, `OpenApiWriter`, `ApiDocsPage`, `McpEndpoint`, `WebhookEndpoints`; componenti: `App`, `Routes`, `MainLayout`, `TopBar`, `CompanySwitcher`, `GlobalSearch`, `NotificationBell`, `UserMenu`, `KhSideMenu`, `KhTabHost`, `KhStatusBar`, `Dashboard` + `DashboardCustomizer` + widget (`KpiWidget`, `TodoWidget`, `DoneTodayWidget`, `DeadlinesWidget`, `FulfillmentWidget`, `RevenueChartWidget`, `CrmActivitiesWidget`, `PersonalNotesWidget`, `ShortcutsWidget`, …), tutti i `Kh*` (§10.7), `DocumentPage<,>`, `MasterDataPage<T>`, pagine per modulo (`PartyPage`, `SupplierPage`, `ItemPage`, `PriceListPage`, `QuotationPage`, `SaleOrderPage`, `DeliveryNotePage`, `SaleDocumentPage`, `CreditNotePage`, `DeferredInvoicingWizard`, `PurchaseOrderPage`, `GoodsReceiptPage`, `PurchaseDocumentPage`, `PurchaseInvoiceImportPage`, `SelfInvoicePage`, `InventoryBalancesPage`, `InventoryEntryPage`, `StockTakePage`, `ReorderProposalPage`, `JournalEntryPage`, `ChartOfAccountsPage`, `JournalTemplatesPage`, `PartitarioPage`, `VatRegistersPage`, `VatSettlementPage`, `WithholdingPage`, `FixedAssetsPage`, `IntrastatPage`, `ClosingWizard`, `FinancialStatementsPage`, `FiscalYearsPage`, `OpenItemsPage`, `PaymentDialog`, `RemittancePage`, `DunningPage`, `BankReconciliationPage`, `EInvoiceDashboard`, `SdiChannelsPage`, `StampDutyPage`, `IntentDeclarationsPage`, `CrmDashboard`, `LeadsPage`, `PipelineBoard`, `OpportunityPage`, `AgendaPage`, `TicketsPage`, `CampaignsPage`, `ServiceContractPage`, `ChannelOrdersPage`, `ReportPage`, `AutomationRulesPage`, `ProceduresPage`, `CompanyPreferencesPage`, `CompanyProfilePage`, `TaxCodesPage`, `Admin*Page` (Instance, Database, Licenses, Users, Roles, ScheduledTasks, Backup, Log, Status, Settings, Cloud, ApiKeys, Seed, Import), `ProfilePage`, `LoginPage`, `TwoFactorPage`, `ChangePasswordPage`, `HelpPage`, `PrintPreviewPage`, `AttachmentsDrawer`); `ITexts`, `JsonTextProvider`; `KeyboardShortcutService`, `ToastService`, `DialogService`, `DrawerService`, `TabService`, `PrintService`, `ThemeService`, `MenuStateService`, `HelpService`.
---
## 22. Glossario (UI italiana → identificatori)
| UI | Codice |
|---|---|
| Super utente / Amministratore / Utente | `UserLevel.SuperUser / Administrator / Standard` |
| Istanza / Azienda / Database di sistema | `Instance` / `Company` / `SystemDb` |
| Modulo / Licenza / Codice di attivazione | `Module` (`ModuleCode`) / `License` / `ActivationCode` |
| Cliente / Fornitore / Prospect / Lead | `Party` (`PartyKind`) / `Lead` |
| Destinazione, Articolo, Listino, Deposito, Giacenza/Impegnato/Ordinato/Disponibile | `PartyAddress`, `Item`, `PriceList`, `Warehouse`, `OnHand/Committed/OnOrder/Available` |
| Causale di magazzino / Movimento / Inventario fisico / Proposta di riordino | `InventoryReason` / `InventoryEntry` / `StockTake` / `ReorderProposal` |
| Preventivo / Ordine / DDT / Fattura / NC / ND / Pro-forma / Parcella / Autofattura | `SaleQuotation` / `SaleOrder` / `DeliveryNote` / `Invoice` / `CreditNote` / `DebitNote` / `ProFormaInvoice` / `FeeNote` / `SelfInvoice` |
| Ordine fornitore / DDT di carico / Fattura di acquisto / Protocollo | `PurchaseOrder` / `GoodsReceipt` / `PurchaseInvoice` / `ProtocolNumber` |
| Piano dei conti / Mastro-Conto-Sottoconto / Causale contabile / Prima nota / Registrazione | `ChartOfAccounts` / `GlAccount` (`AccountKind`) / `JournalTemplate` / `Journal` / `GlEntry` |
| Dare / Avere / Quadratura / Provvisoria / Definitiva / Storno | `Debit` / `Credit` / `Balanced` / `Provisional` / `Final` / `Reversal` |
| Registro IVA / Liquidazione / Esigibilità / Natura / Pro-rata / Acconto | `VatRegister` / `VatSettlement` / `TaxExigibility` / `TaxNature` / `ProRata` / `VatAdvance` |
| Ritenuta / Cassa previdenza / Bollo / Split payment / Reverse charge | `WithholdingTax` / `SocialSecurityCharge` / `StampDuty` / `SplitPayment` / `ReverseCharge` |
| Cespite / Ammortamento / Fondo / Dismissione | `FixedAsset` / `Depreciation` / `AccumulatedDepreciation` / `Disposal` |
| Esercizio / Periodo / Chiusura / Apertura / Libro giornale / Libro inventari | `FiscalYear` / `FiscalPeriod` / `Closing` / `Opening` / `GeneralJournal` / `InventoryBook` |
| Partita / Scadenza / Incasso / Pagamento / Insoluto / Abbuono / Distinta / Sollecito | `OpenItem` / `DueDate` / `Receipt` / `Disbursement` / `Unpaid` / `Allowance` / `Remittance` / `Dunning` |
| Fattura elettronica / SDI / Canale / Codice destinatario / Notifica | `EInvoice` / `Sdi` / `SdiChannel` / `RecipientCode` / `SdiNotification` |
| Opportunità / Fase / Attività / Campagna / Ticket | `Opportunity` / `PipelineStage` / `CrmActivity` / `Campaign` / `Ticket` |
| Allegato / File generato / Anteprima | `Attachment` / `GeneratedFile` / `Preview` |
| Attività programmata / Regola / Procedura / Backup / Copia remota | `ScheduledTask` / `AutomationRule` / `Procedure` / `BackupSet` / `RemoteCopy` |
| Log / Sezione / Traccia | `LogEntry` / `LogSection` / `TraceId` |
| Radar / Hotlink / Scheda / Widget / Tema / Accento / Menu compresso | `Radar` / `Hotlink` / `Tab` / `Widget` / `ThemeMode` / `AccentColor` / `MenuState.Collapsed` |
---
## 23. Avvio della prima sessione
1. Verifica prerequisiti: `dotnet --version` (10.0.x), `docker --version`, `git --version`. Se manca l'SDK 10, fermati e chiedilo.
2. Crea la struttura di §4: `dotnet new sln`, `dotnet new classlib -f net10.0` per ogni libreria, `dotnet new blazor --interactivity Server --all-interactive --empty` per `Khaemhat.Web`, `dotnet new mstest` per i test; normalizza i `.csproj` (rimuovi pacchetti non ammessi, imposta `Directory.Packages.props`). Copia nel repository i file consegnati: `docs/mockups/png/*.png`, `docs/mockups/mockup.css`, `assets/*`, `deploy/*`; crea `docs/wiki/` con `Home.md`, `_Sidebar.md` e una pagina stub per ogni voce di §17.
3. Scrivi `README.md`, `docs/STATUS.md` e gli ADR iniziali; esegui la milestone 0 fino al tag `v0.0.1`; prosegui con la milestone 1 senza attendere conferme.
4. Ad ogni riavvio di sessione: leggi `CLAUDE.md`, `docs/STATUS.md`, `docs/mockups/README.md` (se lavori sull'UI) e l'ultimo `git log -20`, poi continua dal punto esatto indicato.
---
## Appendice A — Token di design (estratto di `docs/mockups/mockup.css`)
Il file completo `mockup.css` (consegnato a parte, da copiare in `docs/mockups/`) contiene anche tutte le classi dei componenti usate nei mockup. Qui i soli token, che `tokens.css` deve riprendere alla lettera.
```css
/* Khaemhat — mockup design tokens & components (reference for src/Khaemhat.Web/wwwroot/css/tokens.css) */
:root{
--kh-font: "Inter", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif;
--kh-mono: "JetBrains Mono", "Cascadia Mono", "DejaVu Sans Mono", monospace;
--kh-fs: 13px; --kh-fs-sm: 11.5px; --kh-fs-lg: 15px; --kh-fs-xl: 20px;
--kh-radius: 6px; --kh-radius-lg: 10px;
--kh-topbar-h: 46px; --kh-tabs-h: 36px; --kh-status-h: 24px; --kh-sidebar-w: 228px;
--kh-gap: 12px; --kh-row-h: 30px;
--kh-shadow: 0 1px 2px rgba(16,24,40,.06), 0 1px 3px rgba(16,24,40,.08);
--kh-shadow-lg: 0 12px 32px rgba(16,24,40,.22);
/* brand */
--kh-brand: #C8962E; --kh-brand-deep: #8B6318; --kh-papyrus: #F1E6C8;
/* semantic */
--kh-ok: #1E8E5A; --kh-ok-soft: #DDF3E6; --kh-warn: #C27A1A; --kh-warn-soft: #FBEFD9;
--kh-err: #C2453A; --kh-err-soft: #FADEDC; --kh-info: #1F5FA8; --kh-info-soft: #E3ECF8;
}
/* ---- accents (per-user) ---- */
:root[data-accent="nilo"] { --kh-accent:#1F5FA8; --kh-accent-strong:#174A85; --kh-accent-soft:#E3ECF8; --kh-accent-text:#174A85; }
:root[data-accent="lapislazzuli"]{ --kh-accent:#3F51B5; --kh-accent-strong:#303F9F; --kh-accent-soft:#E6E9F7; --kh-accent-text:#303F9F; }
:root[data-accent="malachite"] { --kh-accent:#1E8E5A; --kh-accent-strong:#167347; --kh-accent-soft:#DDF3E6; --kh-accent-text:#167347; }
:root[data-accent="turchese"] { --kh-accent:#0F8A96; --kh-accent-strong:#0B6D77; --kh-accent-soft:#D9F0F2; --kh-accent-text:#0B6D77; }
:root[data-accent="ocra"] { --kh-accent:#C27A1A; --kh-accent-strong:#9A6013; --kh-accent-soft:#FBEFD9; --kh-accent-text:#8B5511; }
:root[data-accent="corniola"] { --kh-accent:#C2453A; --kh-accent-strong:#9E362D; --kh-accent-soft:#FADEDC; --kh-accent-text:#9E362D; }
:root[data-accent="ametista"] { --kh-accent:#7E57C2; --kh-accent-strong:#65449C; --kh-accent-soft:#ECE4F8; --kh-accent-text:#65449C; }
:root[data-accent="grafite"] { --kh-accent:#4B5563; --kh-accent-strong:#374151; --kh-accent-soft:#E5E7EB; --kh-accent-text:#374151; }
/* ---- light theme ---- */
:root, :root[data-theme="light"]{
--kh-bg:#F3F5F8; --kh-surface:#FFFFFF; --kh-surface-2:#F8FAFC; --kh-surface-3:#EEF2F6;
--kh-border:#DDE3EA; --kh-border-strong:#C5CDD7;
--kh-text:#1E2733; --kh-text-2:#5B6776; --kh-text-3:#8A95A3;
--kh-topbar:#17243A; --kh-topbar-text:#E8EDF5; --kh-topbar-muted:#9FB0C8;
--kh-sidebar:#FFFFFF; --kh-input:#FFFFFF; --kh-input-ro:#F3F5F8;
--kh-row-alt:#FAFBFD; --kh-row-hover:#F1F5FB; --kh-row-sel: var(--kh-accent-soft);
}
/* ---- dark theme ---- */
:root[data-theme="dark"]{
--kh-bg:#12161C; --kh-surface:#1B2028; --kh-surface-2:#20262F; --kh-surface-3:#262D37;
--kh-border:#2E3744; --kh-border-strong:#3C4756;
--kh-text:#E7ECF2; --kh-text-2:#A5B0BD; --kh-text-3:#73808F;
--kh-topbar:#0E131A; --kh-topbar-text:#E7ECF2; --kh-topbar-muted:#8391A3;
--kh-sidebar:#171C23; --kh-input:#12161C; --kh-input-ro:#1B2028;
--kh-row-alt:#1E242D; --kh-row-hover:#252D38; --kh-row-sel:#24354D;
--kh-ok-soft:#163B2A; --kh-warn-soft:#3E2E13; --kh-err-soft:#44201D; --kh-info-soft:#1C2F4A;
--kh-shadow: 0 1px 2px rgba(0,0,0,.4);
--kh-shadow-lg: 0 12px 32px rgba(0,0,0,.6);
}
:root[data-theme="dark"][data-accent="nilo"] { --kh-accent:#4C8EDB; --kh-accent-strong:#6AA3E6; --kh-accent-soft:#1C2F4A; --kh-accent-text:#8DB8EE; }
:root[data-theme="dark"][data-accent="lapislazzuli"]{ --kh-accent:#7986CB; --kh-accent-strong:#9FA8DA; --kh-accent-soft:#232A4D; --kh-accent-text:#AAB3E6; }
:root[data-theme="dark"][data-accent="malachite"] { --kh-accent:#3DBB7E; --kh-accent-strong:#62CC97; --kh-accent-soft:#163B2A; --kh-accent-text:#8ADBB1; }
:root[data-theme="dark"][data-accent="turchese"] { --kh-accent:#30B4C1; --kh-accent-strong:#5BC8D3; --kh-accent-soft:#143A3E; --kh-accent-text:#8EDBE3; }
:root[data-theme="dark"][data-accent="ocra"] { --kh-accent:#E09A3A; --kh-accent-strong:#EBB266; --kh-accent-soft:#3E2E13; --kh-accent-text:#F0C27A; }
:root[data-theme="dark"][data-accent="corniola"] { --kh-accent:#E0665A; --kh-accent-strong:#EA8A80; --kh-accent-soft:#44201D; --kh-accent-text:#F0A39B; }
:root[data-theme="dark"][data-accent="ametista"] { --kh-accent:#A98BE0; --kh-accent-strong:#BFA8EA; --kh-accent-soft:#2E2345; --kh-accent-text:#CBB8F0; }
:root[data-theme="dark"][data-accent="grafite"] { --kh-accent:#9CA3AF; --kh-accent-strong:#B9C0CC; --kh-accent-soft:#2A3038; --kh-accent-text:#C9D0DA; }
/* density */
:root[data-density="compact"]{ --kh-row-h:26px; --kh-fs:12.5px; --kh-gap:8px; }
```
## Appendice B — Icona (sorgenti SVG)
`assets/icon.svg` (semplice):
```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512"><defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#243A5E"/><stop offset="1" stop-color="#0F1826"/></linearGradient><linearGradient id="gold" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F0C86A"/><stop offset="1" stop-color="#C8962E"/></linearGradient></defs><rect width="512" height="512" rx="112" fill="url(#bg)"/><rect x="16" y="16" width="480" height="480" rx="100" fill="none" stroke="#FFFFFF" stroke-opacity=".07" stroke-width="2"/><g transform="translate(0 0) scale(1.0)"><rect x="76" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="76" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><path d="M110 104h36l20 20v68a6 6 0 0 1-6 6h-50a6 6 0 0 1-6-6V110a6 6 0 0 1 6-6z" fill="#17243A"/><path d="M146 104v20h20" fill="#2A4472"/><path d="M122 142h28" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 158h34" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 174h20" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><text x="194" y="204" text-anchor="middle" font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="800" font-size="46" fill="#17243A">€</text><path d="M361 107l44 22-44 22-44-22z" fill="#2A4472"/><path d="M317 129l44 22v52l-44-22z" fill="#17243A"/><path d="M405 129l-44 22v52l44-22z" fill="#1D3155"/><path d="M339 118l44 22" stroke="#E0B04A" stroke-width="5" stroke-linecap="round" opacity=".9"/><rect x="116" y="358" width="22" height="48" rx="5" fill="#17243A"/><rect x="148" y="330" width="22" height="76" rx="5" fill="#17243A"/><rect x="180" y="302" width="22" height="104" rx="5" fill="#17243A"/><path d="M120 340L152 326L184 308" fill="none" stroke="#E0B04A" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/><circle cx="184" cy="308" r="7" fill="#E0B04A"/><circle cx="378" cy="344" r="13" fill="#2A4472"/><path d="M354 398a24 22 0 0 1 48 0z" fill="#2A4472"/><circle cx="346" cy="340" r="19" fill="#17243A"/><path d="M310 406a36 30 0 0 1 72 0z" fill="#17243A"/></g></svg>
```
`assets/icon-v1.0.svg` (versionata: stesso disegno ridotto all'80% con fascia "v 1.0"; `scripts/build.sh` sostituisce il testo `v 1.0` con `v <major.minor>`):
```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512"><defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#243A5E"/><stop offset="1" stop-color="#0F1826"/></linearGradient><linearGradient id="gold" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F0C86A"/><stop offset="1" stop-color="#C8962E"/></linearGradient></defs><rect width="512" height="512" rx="112" fill="url(#bg)"/><rect x="16" y="16" width="480" height="480" rx="100" fill="none" stroke="#FFFFFF" stroke-opacity=".07" stroke-width="2"/><g transform="translate(51 10) scale(0.8)"><rect x="76" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="76" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><path d="M110 104h36l20 20v68a6 6 0 0 1-6 6h-50a6 6 0 0 1-6-6V110a6 6 0 0 1 6-6z" fill="#17243A"/><path d="M146 104v20h20" fill="#2A4472"/><path d="M122 142h28" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 158h34" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 174h20" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><text x="194" y="204" text-anchor="middle" font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="800" font-size="46" fill="#17243A">€</text><path d="M361 107l44 22-44 22-44-22z" fill="#2A4472"/><path d="M317 129l44 22v52l-44-22z" fill="#17243A"/><path d="M405 129l-44 22v52l44-22z" fill="#1D3155"/><path d="M339 118l44 22" stroke="#E0B04A" stroke-width="5" stroke-linecap="round" opacity=".9"/><rect x="116" y="358" width="22" height="48" rx="5" fill="#17243A"/><rect x="148" y="330" width="22" height="76" rx="5" fill="#17243A"/><rect x="180" y="302" width="22" height="104" rx="5" fill="#17243A"/><path d="M120 340L152 326L184 308" fill="none" stroke="#E0B04A" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/><circle cx="184" cy="308" r="7" fill="#E0B04A"/><circle cx="378" cy="344" r="13" fill="#2A4472"/><path d="M354 398a24 22 0 0 1 48 0z" fill="#2A4472"/><circle cx="346" cy="340" r="19" fill="#17243A"/><path d="M310 406a36 30 0 0 1 72 0z" fill="#17243A"/></g><rect x="126" y="414" width="260" height="62" rx="31" fill="url(#gold)"/><text x="256" y="459" text-anchor="middle" font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="800" font-size="40" fill="#17243A" letter-spacing="1">v 1.0</text></svg>
```
`assets/icon-mono.svg` (favicon 16–32 px):
```svg
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><rect width="512" height="512" rx="112" fill="#17243A"/><rect x="76" y="76" width="150" height="150" rx="34" fill="#E0B04A"/><rect x="286" y="76" width="150" height="150" rx="34" fill="#E0B04A"/><rect x="76" y="286" width="150" height="150" rx="34" fill="#E0B04A"/><rect x="286" y="286" width="150" height="150" rx="34" fill="#E0B04A"/></svg>
```
## Appendice C — Deploy (`deploy/`)
`deploy/unraid/khaemhat.xml`:
```xml
<?xml version="1.0"?>
<!-- Template Unraid (formato Community Applications) per Khaemhat.
Importalo da Docker › Add Container › Template. Sostituisci <owner> con il tuo utente GitHub.
L'icona deve essere raggiungibile senza autenticazione: usa il repository pubblico khaemhat-assets. -->
<Container version="2">
<Name>khaemhat</Name>
<Repository>ghcr.io/&lt;owner&gt;/khaemhat:1.0.0</Repository>
<Registry>https://github.com/&lt;owner&gt;/khaemhat/pkgs/container/khaemhat</Registry>
<Network>khaemhat-net</Network>
<Privileged>false</Privileged>
<Support>https://github.com/&lt;owner&gt;/khaemhat/wiki</Support>
<Project>https://github.com/&lt;owner&gt;/khaemhat</Project>
<Overview>Khaemhat — gestionale ERP + CRM per PMI italiane: anagrafiche, vendite, acquisti, magazzino, contabilità generale e IVA, cespiti, scadenzario, fatturazione elettronica SDI, CRM, più aziende sulla stessa istanza. Richiede un container PostgreSQL 16+ nella stessa rete docker. Interfaccia web sulla porta 8080.</Overview>
<Category>Productivity: Tools:</Category>
<WebUI>http://[IP]:[PORT:8080]/</WebUI>
<TemplateURL>https://raw.githubusercontent.com/&lt;owner&gt;/khaemhat-assets/main/unraid/khaemhat.xml</TemplateURL>
<Icon>https://raw.githubusercontent.com/&lt;owner&gt;/khaemhat-assets/main/icon-v1.0-256.png</Icon>
<ExtraParams>--health-cmd="curl -fs http://localhost:8080/health/live || exit 1" --health-interval=30s --health-timeout=5s --health-retries=3</ExtraParams>
<Requires>Un database PostgreSQL 16 o 17 raggiungibile (consigliato il template ufficiale postgres sulla rete khaemhat-net) e un ruolo con permesso CREATEDB.</Requires>
<Config Name="Porta web" Target="8080" Default="8080" Mode="tcp" Description="Interfaccia web (dietro reverse proxy TLS)" Type="Port" Display="always" Required="true" Mask="false">8080</Config>
<Config Name="Dati (allegati, backup, inbox SDI, SQLite)" Target="/data" Default="/mnt/user/appdata/khaemhat/data" Mode="rw" Description="Volume persistente" Type="Path" Display="always" Required="true" Mask="false">/mnt/user/appdata/khaemhat/data</Config>
<Config Name="KHAEMHAT_SYSTEM_DB" Target="KHAEMHAT_SYSTEM_DB" Default="postgres://khaemhat:cambiami@khaemhat-db:5432/khaemhat_system" Mode="" Description="Database di sistema (configurazione, amministratori, licenze, log)" Type="Variable" Display="always" Required="true" Mask="true">postgres://khaemhat:cambiami@khaemhat-db:5432/khaemhat_system</Config>
<Config Name="KHAEMHAT_DB_SERVER" Target="KHAEMHAT_DB_SERVER" Default="postgres://khaemhat:cambiami@khaemhat-db:5432/" Mode="" Description="Server su cui creare i database delle aziende (ruolo con CREATEDB)" Type="Variable" Display="always" Required="true" Mask="true">postgres://khaemhat:cambiami@khaemhat-db:5432/</Config>
<Config Name="KHAEMHAT_SECRET_KEY" Target="KHAEMHAT_SECRET_KEY" Default="" Mode="" Description="Chiave base64 (32+ byte) per cifrare i segreti nel database di sistema. Generala con: openssl rand -base64 48" Type="Variable" Display="always" Required="true" Mask="true"></Config>
<Config Name="KHAEMHAT_SUPERUSER" Target="KHAEMHAT_SUPERUSER" Default="root" Mode="" Description="Nome del super utente (creato al primo avvio)" Type="Variable" Display="always" Required="true" Mask="false">root</Config>
<Config Name="KHAEMHAT_SUPERUSER_PASSWORD" Target="KHAEMHAT_SUPERUSER_PASSWORD" Default="" Mode="" Description="Password iniziale: usata SOLO al primo avvio, poi va cambiata al primo accesso" Type="Variable" Display="always" Required="true" Mask="true"></Config>
<Config Name="KHAEMHAT_SUPERUSER_EMAIL" Target="KHAEMHAT_SUPERUSER_EMAIL" Default="" Mode="" Description="E-mail del super utente" Type="Variable" Display="always" Required="false" Mask="false"></Config>
<Config Name="KHAEMHAT_COMPANY_CODE" Target="KHAEMHAT_COMPANY_CODE" Default="DEMO" Mode="" Description="Codice della prima azienda (database khaemhat_&lt;codice&gt;)" Type="Variable" Display="always" Required="true" Mask="false">DEMO</Config>
<Config Name="KHAEMHAT_COMPANY_NAME" Target="KHAEMHAT_COMPANY_NAME" Default="La mia azienda S.r.l." Mode="" Description="Ragione sociale della prima azienda" Type="Variable" Display="always" Required="true" Mask="false">La mia azienda S.r.l.</Config>
<Config Name="KHAEMHAT_PUBLIC_URL" Target="KHAEMHAT_PUBLIC_URL" Default="" Mode="" Description="URL pubblico usato nei link delle e-mail" Type="Variable" Display="always" Required="false" Mask="false"></Config>
<Config Name="KHAEMHAT_REDIS" Target="KHAEMHAT_REDIS" Default="" Mode="" Description="Opzionale: redis://:password@khaemhat-redis:6379/0" Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
<Config Name="KHAEMHAT_LICENSE_MODE" Target="KHAEMHAT_LICENSE_MODE" Default="production" Mode="" Description="production oppure test (abilita i codici di licenza fittizi)" Type="Variable" Display="advanced" Required="false" Mask="false">production</Config>
<Config Name="KHAEMHAT_LICENSE" Target="KHAEMHAT_LICENSE" Default="" Mode="" Description="Licenza firmata (.khl, testo). Vuoto = Trial" Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
<Config Name="KHAEMHAT_SEED_DEMO" Target="KHAEMHAT_SEED_DEMO" Default="false" Mode="" Description="true = dati dimostrativi al primo avvio (solo database vuoto)" Type="Variable" Display="advanced" Required="false" Mask="false">false</Config>
<Config Name="KHAEMHAT_UPDATE_FEED" Target="KHAEMHAT_UPDATE_FEED" Default="" Mode="" Description="Opzionale: URL API GHCR per il controllo aggiornamenti" Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
<Config Name="TZ" Target="TZ" Default="Europe/Rome" Mode="" Description="Fuso orario" Type="Variable" Display="advanced" Required="false" Mask="false">Europe/Rome</Config>
<Config Name="PUID" Target="PUID" Default="99" Mode="" Description="UID per i file in /data" Type="Variable" Display="advanced" Required="false" Mask="false">99</Config>
<Config Name="PGID" Target="PGID" Default="100" Mode="" Description="GID per i file in /data" Type="Variable" Display="advanced" Required="false" Mask="false">100</Config>
</Container>
```
`deploy/docker-compose.unraid.yml`:
```yaml
# Khaemhat su Unraid (plugin di gestione compose) o su qualunque host Docker.
# Le etichette net.unraid.docker.* mostrano icona e link WebUI nella pagina Docker di Unraid.
services:
khaemhat:
image: ghcr.io/<owner>/khaemhat:1.0.0
container_name: khaemhat
restart: unless-stopped
depends_on:
khaemhat-db:
condition: service_healthy
ports:
- "8080:8080"
environment:
KHAEMHAT_SYSTEM_DB: postgres://khaemhat:${POSTGRES_PASSWORD}@khaemhat-db:5432/khaemhat_system
KHAEMHAT_DB_SERVER: postgres://khaemhat:${POSTGRES_PASSWORD}@khaemhat-db:5432/
KHAEMHAT_SECRET_KEY: ${KHAEMHAT_SECRET_KEY}
KHAEMHAT_SUPERUSER: ${KHAEMHAT_SUPERUSER:-root}
KHAEMHAT_SUPERUSER_PASSWORD: ${KHAEMHAT_SUPERUSER_PASSWORD}
KHAEMHAT_SUPERUSER_EMAIL: ${KHAEMHAT_SUPERUSER_EMAIL:-}
KHAEMHAT_COMPANY_CODE: ${KHAEMHAT_COMPANY_CODE:-DEMO}
KHAEMHAT_COMPANY_NAME: ${KHAEMHAT_COMPANY_NAME:-La mia azienda S.r.l.}
KHAEMHAT_PUBLIC_URL: ${KHAEMHAT_PUBLIC_URL:-http://localhost:8080}
KHAEMHAT_REDIS: ${KHAEMHAT_REDIS:-}
KHAEMHAT_LICENSE_MODE: ${KHAEMHAT_LICENSE_MODE:-production}
KHAEMHAT_SEED_DEMO: ${KHAEMHAT_SEED_DEMO:-false}
TZ: Europe/Rome
PUID: "99"
PGID: "100"
volumes:
- /mnt/user/appdata/khaemhat/data:/data
labels:
net.unraid.docker.managed: composeman
net.unraid.docker.webui: "http://[IP]:[PORT:8080]/"
net.unraid.docker.icon: "https://raw.githubusercontent.com/<owner>/khaemhat-assets/main/icon-v1.0-256.png"
healthcheck:
test: ["CMD", "curl", "-fs", "http://localhost:8080/health/live"]
interval: 30s
timeout: 5s
retries: 3
networks: [khaemhat-net]
khaemhat-db:
image: postgres:17
container_name: khaemhat-db
restart: unless-stopped
environment:
POSTGRES_DB: khaemhat_system
POSTGRES_USER: khaemhat
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
TZ: Europe/Rome
volumes:
- /mnt/user/appdata/khaemhat/postgres:/var/lib/postgresql/data
labels:
net.unraid.docker.managed: composeman
healthcheck:
test: ["CMD-SHELL", "pg_isready -U khaemhat -d khaemhat_system"]
interval: 10s
timeout: 5s
retries: 10
networks: [khaemhat-net]
khaemhat-redis:
image: redis:7
container_name: khaemhat-redis
restart: unless-stopped
profiles: ["redis"]
command: ["redis-server", "--requirepass", "${REDIS_PASSWORD:-cambiami}", "--save", "", "--appendonly", "no"]
labels:
net.unraid.docker.managed: composeman
networks: [khaemhat-net]
networks:
khaemhat-net:
name: khaemhat-net
```
`deploy/.env.example`:
```ini
# Copia in .env accanto a docker-compose.unraid.yml (mai committare .env)
POSTGRES_PASSWORD=cambiami-subito
KHAEMHAT_SECRET_KEY= # openssl rand -base64 48
KHAEMHAT_SUPERUSER=root
KHAEMHAT_SUPERUSER_PASSWORD=cambiami-al-primo-accesso
KHAEMHAT_SUPERUSER_EMAIL=alberto@example.com
KHAEMHAT_COMPANY_CODE=DEMO
KHAEMHAT_COMPANY_NAME=La mia azienda S.r.l.
KHAEMHAT_PUBLIC_URL=https://gestionale.example.com
KHAEMHAT_LICENSE_MODE=production
KHAEMHAT_SEED_DEMO=false
# KHAEMHAT_REDIS=redis://:cambiami@khaemhat-redis:6379/0
# REDIS_PASSWORD=cambiami
```
## Appendice D — Workflow GitHub a minuti contati e script di rilascio
`.github/workflows/ci.yml`:
```yaml
name: ci
on:
pull_request:
branches: [main]
paths-ignore: ["docs/**", "*.md", "assets/**", "deploy/**"]
push:
tags: ["v*"]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
jobs:
build-test:
runs-on: ubuntu-latest
timeout-minutes: 15
services:
postgres:
image: ${{ startsWith(github.ref, 'refs/tags/v') && 'postgres:17' || '' }}
env: { POSTGRES_PASSWORD: test, POSTGRES_DB: khaemhat_test }
ports: ["5432:5432"]
options: >-
--health-cmd "pg_isready -U postgres" --health-interval 5s --health-timeout 5s --health-retries 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-dotnet@v4
with: { dotnet-version: "10.0.x" }
- uses: actions/cache@v4
with:
path: ~/.nuget/packages
key: nuget-${{ hashFiles('Directory.Packages.props', '**/*.csproj') }}
- run: scripts/check-packages.sh
- run: dotnet build -c Release -warnaserror
- run: dotnet test -c Release --no-build
env:
KHAEMHAT_TEST_PG: ${{ startsWith(github.ref, 'refs/tags/v') && 'postgres://postgres:test@localhost:5432/khaemhat_test' || '' }}
KHAEMHAT_LICENSE_MODE: test
```
`.github/workflows/release.yml` (solo manuale):
```yaml
name: release-image
on:
workflow_dispatch:
inputs:
version: { description: "Tag (es. v1.0.2)", required: true }
arm64: { description: "Costruisci anche linux/arm64", type: boolean, default: false }
jobs:
image:
runs-on: ubuntu-latest
timeout-minutes: 30
permissions: { contents: read, packages: write }
steps:
- uses: actions/checkout@v4
with: { ref: ${{ inputs.version }} }
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with: { registry: ghcr.io, username: ${{ github.actor }}, password: ${{ secrets.GITHUB_TOKEN }} }
- uses: docker/build-push-action@v6
with:
context: .
file: docker/Dockerfile
push: true
platforms: ${{ inputs.arm64 && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
build-args: VERSION=${{ inputs.version }},GIT_SHA=${{ github.sha }}
tags: |
ghcr.io/${{ github.repository_owner }}/khaemhat:${{ inputs.version }}
ghcr.io/${{ github.repository_owner }}/khaemhat:latest
```
`.github/workflows/wiki.yml`:
```yaml
name: wiki
on:
push:
branches: [main]
paths: ["docs/wiki/**"]
jobs:
sync:
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v4
- run: |
git clone "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.wiki.git" wiki
rsync -a --delete --exclude .git docs/wiki/ wiki/
cd wiki && git add -A && git -c user.name=ci -c user.email=ci@users.noreply.github.com commit -m "wiki: sync from ${{ github.sha }}" || exit 0
git push
```
`scripts/publish-image.sh` (percorso normale, nessun minuto di CI):
```bash
#!/usr/bin/env bash
set -euo pipefail
VERSION="${1:?uso: publish-image.sh vX.Y.Z [--arm64]}"; PLATFORMS="linux/amd64"; [[ "${2:-}" == "--arm64" ]] && PLATFORMS="linux/amd64,linux/arm64"
OWNER="${GITHUB_OWNER:?}"; IMAGE="ghcr.io/$OWNER/khaemhat"; SHA="$(git rev-parse --short HEAD)"; MM="${VERSION#v}"; MM="${MM%.*}"
echo "$GITHUB_TOKEN" | docker login ghcr.io -u "$OWNER" --password-stdin
sed "s/v 1.0/v $MM/" assets/icon-v1.0.svg > "assets/icon-v$MM.svg" # icona versionata (sostituzione di stringa)
docker buildx build --platform "$PLATFORMS" -f docker/Dockerfile --build-arg VERSION="$VERSION" --build-arg GIT_SHA="$SHA" \
-t "$IMAGE:$VERSION" -t "$IMAGE:latest" --push .
git tag -a "$VERSION" -m "Khaemhat $VERSION" && git push origin "$VERSION"
echo "Pubblicata $IMAGE:$VERSION"
```