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

140 KiB
Raw Blame History

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

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

002 · Accesso · verifica in due passaggi (TOTP)

002

003 · Primo accesso · cambio password obbligatorio

003

004 · Dashboard · da fare, fatto, da evadere, scadenze (widget)

004

005 · Dashboard in tema scuro

005

006 · Dashboard · modalità personalizzazione (widget attivabili, pagina iniziale)

006

007 · Menu laterale compresso (solo icone, sottomenu a comparsa)

007

008 · Preferenze utente · tema notturno e 8 colori di accento

008

009 · Ricerca globale (Ctrl+K)

009

010 · Pannello notifiche in app

010

011 · Aiuto in app (F1) con la pagina wiki della maschera

011

Anagrafiche e articoli

012 · Clienti · radar (ricerca, filtri, selezione)

012

013 · Clienti · radar con menu compresso e sottomenu a comparsa

013

014 · Cliente · scheda anagrafica a gruppi

014

015 · Cliente · fiscale, SDI, dichiarazione d'intento

015

016 · Fornitore · scheda con condizioni di acquisto e ritenute

016

017 · Articolo · scheda con prezzi, riordino e giacenze

017

018 · Listini · griglia listino × articolo con aggiornamento massivo

018

Vendite e documenti

020 · Fattura di vendita · righe (toolbar a icone, intestazione documento)

020

021 · Fattura di vendita · testata a gruppi di campi

021

022 · Fattura di vendita · tema scuro, accento Malachite

022

023 · Hotlink · ricerca articolo (F4) sopra la fattura

023

024 · Allegati del documento e generazione file (PDF, XML, XLSX, ZIP)

024

025 · Anteprima di stampa / PDF della fattura

025

026 · Preventivo / offerta con revisioni e collegamento CRM

026

027 · Ordine cliente · evasione, residui, documenti collegati

027

028 · DDT · dati di trasporto, colli, firme

028

029 · Nota di credito TD04 con riferimento alla fattura

029

030 · Fatturazione differita · procedura guidata

030

Acquisti

031 · Ordine fornitore generato dalla proposta di riordino

031

032 · DDT di carico con controllo quantità ricevute

032

033 · Fattura di acquisto da XML con conti e centri di costo per riga

033

034 · Acquisti · import fatture passive XML/P7M

034

035 · Autofattura / integrazione reverse charge (TD16–TD29)

035

Magazzino

036 · Magazzino · giacenze, disponibilità, sottoscorta

036

037 · Movimento di magazzino manuale (trasferimento)

037

038 · Inventario fisico con conteggi e rettifiche

038

039 · Proposta di riordino fornitori dal sottoscorta

039

Contabilità

040 · Contabilità · prima nota (partita doppia con IVA)

040

041 · Prima nota manuale con controllo di quadratura

041

042 · Contabilità · piano dei conti e mastrino

042

043 · Contabilità · causali contabili e modelli di registrazione

043

044 · Contabilità · partitario / estratto conto cliente

044

045 · Contabilità · registri IVA con protocolli e stampe definitive

045

046 · Contabilità · liquidazione IVA, F24, LIPE

046

047 · Contabilità · ritenute, casse previdenza, prospetto F24

047

048 · Cespiti · registro beni ammortizzabili e piano di ammortamento

048

049 · Intrastat · elenchi cessioni/acquisti UE

049

050 · Contabilità · chiusura esercizio guidata

050

051 · Contabilità · bilancio CEE con confronto e drill-down

051

052 · Esercizi contabili e blocco periodi

052

Scadenzario e tesoreria

053 · Scadenzario · partite aperte e aging

053

054 · Scadenzario · dialogo Registra incasso

054

055 · Scadenzario · distinte RiBa / SDD / bonifici SEPA

055

056 · Scadenzario · solleciti a livelli

056

057 · Scadenzario · riconciliazione bancaria

057

Fatturazione elettronica

058 · Fatturazione elettronica · cruscotto SDI

058

059 · Fatturazione elettronica · canali SDI (PEC integrata, SdICoop, intermediari)

059

060 · Fatturazione elettronica · bollo virtuale trimestrale

060

061 · Fatturazione elettronica · dichiarazioni d'intento e plafond

061

CRM

062 · CRM · dashboard con imbuto, previsione e fonti

062

063 · CRM · lead con punteggio e conversione

063

064 · CRM · pipeline opportunità (kanban)

064

065 · CRM · scheda opportunità con cronologia e attività

065

066 · CRM e Servizi · agenda settimanale

066

067 · CRM · ticket di assistenza collegati a interventi

067

068 · CRM · campagne e segmenti

068

Servizi, canali, report, automazioni, tabelle

069 · Servizi · contratto di assistenza e interventi

069

070 · Canali e-commerce · ordini web importati e connettori

070

071 · Report · fatturato per cliente con export e pianificazione

071

072 · Automazioni · regole quando → se → allora

072

073 · Automazioni · catalogo procedure

073

074 · Tabelle azienda · codici automatici e compilazione automatica

074

075 · Tabelle azienda · profilo azienda

075

076 · Tabelle azienda · codici IVA con nature SDI

076

077 · Import/Export · procedura guidata CSV/XLSX/JSON

077

Amministrazione

078 · Amministrazione · istanza, database di sistema e per azienda

078

079 · Amministrazione · dettaglio database: backup, cloud, ripristino, manutenzione

079

080 · Amministrazione · licenze e moduli attivabili con codice

080

081 · Amministrazione · utenti a tre livelli e per azienda

081

082 · Amministrazione · matrice ruoli × permessi

082

083 · Amministrazione · attività programmate (scheduler)

083

084 · Amministrazione · log avanzato per sezioni con filtri e dettaglio

084

085 · Amministrazione · stato sistema e aggiornamenti

085

086 · Amministrazione · impostazioni di sistema (sicurezza, SMTP)

086

087 · Amministrazione · archiviazione e copie remote (S3, WebDAV)

087

088 · Amministrazione · chiavi API, MCP e webhook

088

089 · Amministrazione · dati di base, pacchetti e dati di esempio

089

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.

/* 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 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 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 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 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:

# 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:

# 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:

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):

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:

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):

#!/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"