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>
1324 lines
140 KiB
Markdown
1324 lines
140 KiB
Markdown
# 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 (``) presuppongono quella posizione.
|
||
|
||
---
|
||
|
||
## 0. Missione
|
||
|
||
Sei l'architetto e lo sviluppatore principale di **Khaemhat**, un gestionale **ERP + CRM** per PMI italiane, da costruire **da zero** in questo repository, senza prendere a modello nessun software esistente: le specifiche sono tutte qui e nei mockup. Il nome viene da Khaemhat, scriba reale e sovrintendente ai granai dell'Alto e Basso Egitto sotto Amenhotep III (tomba TT57 a Tebe): un contabile dell'antichità. Namespace radice: `Khaemhat`. Immagine Docker: `khaemhat`. Prefisso variabili d'ambiente: `KHAEMHAT_`. Icona ufficiale: `assets/icon.svg` (§16.6).
|
||
|
||
L'aspetto da realizzare è quello dei **mockup in `docs/mockups/`** (§10): sono la specifica visiva vincolante; `docs/mockups/mockup.css` è il contratto dei token di design e dei componenti.
|
||
|
||
Lavori in autonomia. Non chiedere conferme: quando un punto è ambiguo decidi secondo questo documento, registra la scelta in `docs/adr/NNNN-titolo.md` (contesto, decisione, conseguenze) e prosegui. Fermati solo per blocchi reali (SDK mancante, credenziali assenti).
|
||
|
||
---
|
||
|
||
## 1. Vincoli non negoziabili
|
||
|
||
1. **Linguaggio e piattaforma:** C# 14 su .NET 10 (LTS). Un solo runtime, nessun altro linguaggio server-side. JavaScript solo dove Blazor non basta (interop minimo in `wwwroot/js`, senza framework né bundler).
|
||
2. **Nessuna libreria o componente esterno.** Tutta la logica applicativa è scritta nel repository. Sono ammessi esclusivamente:
|
||
- runtime e framework condivisi Microsoft (`Microsoft.NETCore.App`, `Microsoft.AspNetCore.App`): Blazor, Kestrel, Minimal API, autenticazione cookie, DataProtection, rate limiting, `Microsoft.Extensions.*` di piattaforma, `System.Text.Json`, `System.Security.Cryptography` (incl. `Pkcs` se in-box), `System.Formats.Asn1`, `System.IO.Compression`, `System.Xml`, `System.Net.Mail`, `System.Net.Http`, `System.Net.Sockets`;
|
||
- i due provider ADO.NET: `Npgsql` (PostgreSQL) e `Microsoft.Data.Sqlite` (SQLite, che porta con sé il motore nativo `e_sqlite3`);
|
||
- solo nei progetti di test (mai nell'immagine): `Microsoft.NET.Test.Sdk` + `MSTest`.
|
||
Qualunque altro pacchetto NuGet è vietato (ORM, mapper, validatori, logger, librerie UI/CSS, PDF, Redis, mail, OpenAPI, retry, scheduler, SDK cloud…): se ti serve una funzionalità coperta da una libreria, la scrivi tu in `Khaemhat.Infrastructure` o `Khaemhat.Data`. Niente CDN, font scaricati, script di terze parti nel browser.
|
||
Gli **strumenti di sistema operativo nell'immagine** (`postgresql-client` per `pg_dump`/`pg_restore`, `curl` per l'healthcheck, `tzdata`) sono ammessi: non sono componenti dell'applicazione. L'allowlist è codificata in `Directory.Packages.props` (Central Package Management) e verificata da `scripts/check-packages.sh`, che fa fallire la build se compare un `PackageReference` non ammesso.
|
||
3. **Database indifferente per il codice applicativo.** SQLite per test, demo, prova e archivi in sola lettura; PostgreSQL (versione minima **16**, consigliata 17) per le installazioni reali, fino a centinaia di GB. Nessun codice sopra lo strato dati conosce il motore in uso.
|
||
4. **Un database di sistema + un database per azienda** (§5.4). Più aziende possono essere collegate alla stessa istanza: condividono solo l'amministrazione (configurazione, super utente e amministratori, licenze, log di istanza). Utenti, preferenze per utente, dati e documenti di un'azienda stanno nel suo database. Le tabelle operative non hanno `company_id`.
|
||
5. **Distribuzione in Docker**, interfaccia via browser, configurazione iniziale solo tramite variabili d'ambiente; tutto il resto dal pannello di amministrazione. **Nessun file temporaneo con impostazioni o dati utente**: preferenze nel database, chiavi DataProtection nel database di sistema, log su stdout e nel database, niente `appsettings.<Env>.json` con segreti, nessuna scrittura fuori da `KHAEMHAT_DATA_DIR`. Cookie ammessi (sessione, tema prima del login).
|
||
6. **Redis opzionale.** Se `KHAEMHAT_REDIS` è valorizzata la cache distribuita usa Redis tramite un client RESP scritto nel progetto; altrimenti cache in memoria. Comportamento funzionale identico.
|
||
7. **Non personalizzabile** in questa versione: niente plugin, campi custom, scripting utente o editor di layout. L'architettura resta modulare internamente (registro moduli statico); la configurabilità ammessa è quella delle preferenze (§11.12) e della dashboard (§10.3).
|
||
8. **Moduli attivabili tramite licenza** (§8): ogni modulo funzionale è dietro un codice di licenza attivabile solo dalla pagina di amministrazione dell'istanza (super utente). In sviluppo e test valgono le licenze fittizie fisse di §8.3.
|
||
9. **Codice in inglese** (identificatori, commenti, commit), **interfaccia in italiano** tramite risorse (`it-IT` unica lingua fornita; infrastruttura pronta per altre).
|
||
10. **Fiscalità per paese isolata in un pacchetto.** Tutto ciò che è specifico dell'Italia sta in `Khaemhat.Fiscal.Italy` dietro le interfacce di `Khaemhat.Fiscal.Abstractions`; il resto del gestionale non conosce l'Italia. Altri paesi saranno nuovi pacchetti.
|
||
11. **Qualità:** `Nullable` abilitato, `TreatWarningsAsErrors`, analyzer .NET di piattaforma, `.editorconfig`, nessun `#pragma warning disable` senza motivazione.
|
||
12. **Documentazione sempre aggiornata.** Ogni funzione nuova o modificata aggiorna, nella stessa unità di lavoro: la pagina wiki in `docs/wiki/`, i file in `docs/` toccati, `CHANGELOG.md` e, se l'interfaccia cambia, gli screenshot (§17). Una funzione senza documentazione non è finita (§20).
|
||
13. **Repository e CI su GitHub** con **minuti di CI contati** (§16.3): i workflow girano solo quando serve, le immagini si costruiscono di norma in locale con lo script fornito.
|
||
|
||
---
|
||
|
||
## 2. Decisioni tecnologiche
|
||
|
||
| Area | Decisione | Motivo |
|
||
|---|---|---|
|
||
| Host | ASP.NET Core 10 su Kestrel, un processo per istanza | Un container serve più aziende; nessuno scale-out orizzontale |
|
||
| UI | **Blazor Web App, render mode Interactive Server** su tutta l'app, componenti scritti in casa secondo `docs/mockups/mockup.css` | Modello a componenti ricco senza librerie JS; SignalR è di piattaforma. Con più repliche servirebbero sessioni sticky: non è il caso d'uso |
|
||
| API | Minimal API REST `/api/v1` + endpoint MCP `/mcp` | Integrazioni (sito web, e-commerce, agenti AI) senza dipendere dall'UI |
|
||
| Accesso dati | Micro-ORM interno (`Khaemhat.Data`): mappe esplicite per entità, query builder tipizzato, migrazioni in C# con DDL generato per dialetto | Nessun ORM esterno; controllo su SQL e prestazioni |
|
||
| Database | Sistema (`khaemhat_system`) + uno per azienda; registry nel sistema; segreti cifrati con chiave da `KHAEMHAT_SECRET_KEY` | Multi-azienda con amministrazione condivisa |
|
||
| Autenticazione | Cookie ASP.NET Core; account di istanza (super utente, amministratori) nel DB di sistema; utenti nel DB dell'azienda; PBKDF2-SHA256 (600.000 iterazioni, salt 16 byte), lockout, TOTP (RFC 6238 in casa) | Nessuna dipendenza da Identity/EF |
|
||
| Licenze | Codici modulo firmati ECDSA P-256 (file `.khl` / stringa); modalità test con codici fissi | §8 |
|
||
| Cache | `ICacheProvider` → `MemoryCacheProvider` / `RedisCacheProvider` (client RESP2 su `TcpClient`/`SslStream`, pool, pub/sub) | Redis opzionale |
|
||
| Scheduler | `JobRunner` in-process con cron (sottoinsieme) + **attività programmate** definite dagli amministratori da UI, persistite nel DB di sistema con lock | §12.5 |
|
||
| Backup | `pg_dump`/`pg_restore` (`-Fc`) come processo dal container + backup logico JSON Lines portabile + `VACUUM INTO` per SQLite; pianificati, verificati, retention GFS, copie su S3 compatibile (SigV4 in casa) e WebDAV | §13 |
|
||
| Log | Log strutturato per **sezione** su stdout (JSON) e nel DB di sistema, con filtri, dettaglio, retention per livello e regole di avviso | §9.5 |
|
||
| PDF e file | `PdfWriter` interno (font Type1 standard, testo, linee, rettangoli, JPEG, PDF/A-3 per allegati XML); XLSX/CSV/ZIP/XML generati in casa; ogni file generato o caricato è un **allegato del solo documento** a cui appartiene | §9.4 |
|
||
| Stampe | Template HTML/CSS stampabili dal browser + PDF con `PdfWriter`, un solo modello dati per report | Doppio canale |
|
||
| E-mail / PEC | `System.Net.Mail.SmtpClient` con STARTTLS/SSL; **client IMAP minimale in casa** per leggere le notifiche SDI dalla PEC | Canale SDI via PEC integrato |
|
||
| SDI | `ISdiTransport` con 4 implementazioni: PEC (integrata), SdICoop (web service AdE), intermediario A, intermediario B | §11.9 |
|
||
| Firma/verifica | ECDSA P-256 (licenze), SHA-256 (backup, allegati), verifica CAdES dei P7M | In-box |
|
||
| Test | MSTest; SQLite in-memory sempre; PostgreSQL con `KHAEMHAT_TEST_PG`; Redis con `KHAEMHAT_TEST_REDIS` | Entrambi i dialetti |
|
||
| Versioning | SemVer da git tag in `Directory.Build.props`; `--build-arg VERSION` nel Dockerfile; versione mostrata nell'icona versionata e nella barra | Nessun pacchetto |
|
||
|
||
---
|
||
|
||
## 3. Architettura a livelli
|
||
|
||
```
|
||
┌───────────────────────────────────────────────────────────────────────┐
|
||
│ Khaemhat.Web UI Blazor · REST API · MCP · Auth · Host · Help │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ Khaemhat.Application Casi d'uso per modulo · DTO · Permessi · │
|
||
│ Motore documenti · Motore contabile · Procedure · │
|
||
│ Automazioni · Seeder · Report · Backup orchestr. │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ Khaemhat.Fiscal.Abstractions interfacce paese (IVA, e-invoice, ...) │
|
||
│ Khaemhat.Fiscal.Italy FatturaPA · TD · F24 · LIPE · Intrastat │
|
||
│ · ritenute · cespiti · bilancio CEE │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ Khaemhat.Core Entità · Value object · Enum · Regole di dominio │
|
||
│ · Calcoli · Validatori · Partita doppia │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ Khaemhat.Infrastructure Cache/Redis · Crypto · Licenze · Mail/IMAP · │
|
||
│ PDF · XLSX/CSV · Job · File · Backup (pg_dump, │
|
||
│ S3, WebDAV) · MCP protocol · Http (VIES, BCE, │
|
||
│ GitHub packages, intermediari SDI) │
|
||
├───────────────────────────────────────────────────────────────────────┤
|
||
│ Khaemhat.Data Astrazioni DB · Query builder · Mappe · │
|
||
│ Migrazioni · Unit of work · Registry database │
|
||
│ Khaemhat.Data.Sqlite │ Khaemhat.Data.PostgreSql │
|
||
└───────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
Regole di dipendenza (verificate da test di architettura in `Khaemhat.Core.Tests`):
|
||
- `Core` non dipende da nulla. `Fiscal.Abstractions` dipende da `Core`. `Fiscal.Italy` dipende da `Core`, `Fiscal.Abstractions`, `Infrastructure` (solo XML/PDF/crypto/HTTP).
|
||
- `Data` dipende da `Core` e `System.Data.Common`; `Data.Sqlite`/`Data.PostgreSql` da `Data` e dal rispettivo provider; nessun altro progetto referenzia i provider.
|
||
- `Infrastructure` dipende da `Core` e `Data`. `Application` dipende da `Core`, `Data`, `Infrastructure`, `Fiscal.Abstractions` (mai da `Fiscal.Italy`: il pacchetto paese è registrato in `Program.cs` e risolto per `company_profile.country`).
|
||
- `Web` dipende da `Application` e registra i provider concreti in `Program.cs`.
|
||
|
||
Ogni modulo implementa `IModule` (in `Application.Modules`): codice modulo per la licenza (§8), nome, ordine, voci di menu, permessi, migrazioni, seeder *base* e *demo*, endpoint API, tool MCP, procedure, eventi per le automazioni, sezione di log, pagine wiki. `ModuleRegistry` li enumera staticamente e li filtra per licenza attiva.
|
||
|
||
---
|
||
|
||
## 4. Struttura del repository
|
||
|
||
```
|
||
khaemhat/
|
||
├── CLAUDE.md ← questo file
|
||
├── README.md LICENSE CHANGELOG.md
|
||
├── Khaemhat.sln global.json Directory.Build.props Directory.Packages.props
|
||
├── .editorconfig .gitignore .dockerignore .gitattributes
|
||
├── assets/ ← icon.svg, icon-v1.0.svg (versionata), icon-mono.svg, icon-{512,256,128,64,32,16}.png,
|
||
│ icon-v1.0-{512,256,128,64}.png, favicon.ico
|
||
├── deploy/
|
||
│ ├── docker-compose.yml ← app + postgres + redis (profili)
|
||
│ ├── docker-compose.sqlite.yml ← demo autonoma SQLite
|
||
│ ├── docker-compose.unraid.yml ← etichette net.unraid.docker.* (icona e WebUI)
|
||
│ ├── .env.example
|
||
│ └── unraid/khaemhat.xml ← template Community Applications
|
||
├── docker/
|
||
│ ├── Dockerfile ← multi-stage, non root, HEALTHCHECK, postgresql-client
|
||
│ ├── entrypoint.sh ← attesa DB, migrazioni di sistema, bootstrap, avvio
|
||
│ └── postgres/init.sql
|
||
├── .github/workflows/
|
||
│ ├── ci.yml ← build + test, solo su PR verso main e push di tag (minuti contati)
|
||
│ ├── release.yml ← solo manuale (workflow_dispatch) o tag v*: immagine → GHCR
|
||
│ └── wiki.yml ← solo quando cambia docs/wiki: sincronizza il wiki GitHub (job da pochi secondi)
|
||
├── scripts/
|
||
│ ├── build.sh test.sh run-dev.sh check-packages.sh new-migration.sh
|
||
│ ├── publish-image.sh ← build locale + push su GHCR (percorso normale di rilascio)
|
||
│ ├── publish-wiki.sh ← push di docs/wiki nel repo <repo>.wiki.git
|
||
│ ├── gen-datamodel.sh ← DATA-MODEL.md dalle mappe
|
||
│ └── seed.sh ← CLI: --base / --demo [--scale N] [--company CODE]
|
||
├── src/
|
||
│ ├── Khaemhat.Core/ ← Common/ Entities/ Enums/ Rules/ Validation/ Abstractions/
|
||
│ ├── Khaemhat.Fiscal.Abstractions/
|
||
│ ├── Khaemhat.Fiscal.Italy/ ← Vat/ FatturaPa/ Sdi/ (PEC, SdICoop, intermediari) Withholding/ F24/ Intrastat/
|
||
│ │ StampDuty/ FixedAssets/ FinancialStatements/ ChartOfAccounts/ Resources/
|
||
│ ├── Khaemhat.Data/ Khaemhat.Data.Sqlite/ Khaemhat.Data.PostgreSql/
|
||
│ ├── Khaemhat.Infrastructure/ ← Caching/ Security/ Licensing/ Mail/ (Smtp, Imap) Pdf/ Export/ Jobs/ Files/
|
||
│ │ Backup/ Http/ Mcp/ Logging/ Notifications/
|
||
│ ├── Khaemhat.Application/ ← Modules/ Documents/ Ledger/ Automation/ Seeding/ Search/ Audit/ Backup/ Licensing/
|
||
│ │ └── Modules/Company/ Parties/ Items/ Sales/ Purchases/ Inventory/ Ledger/ Vat/ Assets/ Finance/ EInvoicing/
|
||
│ │ Crm/ Services/ Channels/ Reports/ Admin/ UserSettings/ (ognuno: Services/ Dtos/ Validators/ Migrations/
|
||
│ │ Seed/Base/ Seed/Demo/ Reports/ Api/ Mcp/ Procedures/ Permissions.cs Menu.cs <Nome>Module.cs)
|
||
│ └── Khaemhat.Web/ ← Program.cs Configuration/ Auth/ Api/ Mcp/ Help/ Components/ (App, Routes, Layout/,
|
||
│ Ui/ = componenti Kh*, Pages/<Modulo>/, Shared/) Localization/ wwwroot/
|
||
├── tests/ (Core, Data, Infrastructure, Fiscal.Italy, Application, Web)
|
||
├── tools/Khaemhat.LicenseTool/ ← CLI: coppia chiavi, emissione/verifica licenze (chiave privata mai nel repo)
|
||
└── docs/
|
||
├── ARCHITECTURE.md DATA-MODEL.md MODULES.md API.md MCP.md DEPLOY.md DEVELOPMENT.md SECURITY.md STATUS.md
|
||
├── adr/
|
||
├── mockups/ ← mockup.css + png/ (88 schermate + galleria) + README.md (indice, §10.1)
|
||
└── wiki/ ← Home.md, _Sidebar.md, una pagina per argomento (sincronizzata nel wiki GitHub)
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Strato dati (`Khaemhat.Data`)
|
||
|
||
### 5.1 Contratti
|
||
```csharp
|
||
public interface IDbProvider {
|
||
DbEngine Engine { get; } ISqlDialect Dialect { get; } ISchemaBuilder SchemaBuilder { get; }
|
||
DbConnection CreateConnection(string connectionString);
|
||
Task EnsureDatabaseExistsAsync(string connectionString, CancellationToken ct); // CREATE DATABASE se manca
|
||
Task DropDatabaseAsync(string connectionString, CancellationToken ct); // solo da RestoreService/CompanyRegistry
|
||
Task<DbServerInfo> GetServerInfoAsync(string connectionString, CancellationToken ct); // versione, dimensioni, connessioni
|
||
}
|
||
public interface ISqlDialect {
|
||
string Quote(string identifier); string Parameter(string name); string Paging(int offset, int limit);
|
||
string InsertReturningId(string table, ...); string Upsert(...); string CaseInsensitiveLike(string column);
|
||
string CurrentTimestampUtc { get; } string AdvisoryLock(string key);
|
||
object ToDbValue(object? value, ColumnType type); object? FromDbValue(object? value, ColumnType type);
|
||
string SqlType(ColumnType type, int? length, int? scale);
|
||
}
|
||
public interface IUnitOfWork : IAsyncDisposable {
|
||
DbConnection Connection { get; } DbTransaction? Transaction { get; }
|
||
Task BeginAsync(); Task CommitAsync(); Task RollbackAsync();
|
||
IRepository<T, TKey> Repository<T, TKey>() where T : class, IEntity<TKey>;
|
||
Task<int> ExecuteAsync(SqlFragment sql); Task<T?> QuerySingleAsync<T>(SqlFragment sql);
|
||
Task<IReadOnlyList<T>> QueryAsync<T>(SqlFragment sql); Task<DbDataReader> StreamAsync(SqlFragment sql);
|
||
}
|
||
public interface IRepository<T, TKey> {
|
||
Task<T?> GetAsync(TKey id); Task<T?> FindAsync(Query<T> query); Task<PagedResult<T>> ListAsync(Query<T> query);
|
||
Task<TKey> InsertAsync(T entity); Task UpdateAsync(T entity); // controllo row_version
|
||
Task DeleteAsync(TKey id); Task<int> CountAsync(Query<T> query);
|
||
}
|
||
public interface IUnitOfWorkFactory { Task<IUnitOfWork> CreateAsync(DatabaseScope scope); } // System oppure Company(code)
|
||
```
|
||
|
||
### 5.2 Convenzioni
|
||
- Tabelle e colonne `snake_case`; PK `id BIGINT` identity; colonne di audit `created_at`, `created_by`, `updated_at`, `updated_by`, `row_version` (optimistic locking: `UPDATE … WHERE id=@id AND row_version=@v`; su conflitto `ConcurrencyException`). Tabelle del database di sistema con prefisso `sys_`.
|
||
- Tipi logici `ColumnType`: `String(n)`, `Text`, `Int32`, `Int64`, `Decimal(19,6)`, `Bool`, `Date`, `DateTimeUtc`, `Guid`, `Bytes`, `Json`. Mappatura: PostgreSQL `varchar(n)/text/int/bigint/numeric(19,6)/boolean/date/timestamptz/uuid/bytea/jsonb`; SQLite `TEXT/TEXT/INTEGER/INTEGER/INTEGER (scalato ×10⁶)/INTEGER 0-1/TEXT yyyy-MM-dd/TEXT ISO 8601 UTC/TEXT/BLOB/TEXT`. Le somme in SQL su SQLite operano su interi scalati e vengono riscalate in lettura.
|
||
- Ogni entità ha `XxxMap : EntityMap<Xxx>` (tabella, colonne, chiave, indici, FK, conversioni). Nessuna riflessione a runtime oltre la costruzione iniziale.
|
||
- `QueryBuilder<T>`: sottoinsieme sicuro di espressioni (uguaglianza, confronto, `Contains`/`StartsWith`, `In`, `And/Or/Not`, `IsNull`); il resto come `SqlFragment` parametrizzato. Mai concatenazione di input utente in SQL.
|
||
- SQLite: `journal_mode=WAL; foreign_keys=ON; busy_timeout=5000`; scritture serializzate da `SqliteWriteLock`. PostgreSQL: pooling (pool separato per database, `MaxPoolSize` per database da impostazioni), `statement_timeout` per sessione, `pg_advisory_xact_lock` per numeratori, chiusure e scheduler.
|
||
- Tabelle grandi (`gl_entry_lines`, `inventory_entry_lines`, `audit_log`, `sys_log`) con indici per data/esercizio; partizionamento per anno su PostgreSQL predisposto dal `SchemaBuilder` e attivabile da migrazione oltre i 50 M righe.
|
||
|
||
### 5.3 Migrazioni
|
||
- Classi `[Migration(20261013_001, "create_parties")] class M20261013_001 : IMigration` con `Up(ISchemaBuilder sb)` e `UpSql(ISqlDialect d)`. Due cataloghi: **sistema** e **azienda**. Ogni database ha la propria tabella `schema_version(module, version, name, applied_at, checksum)`.
|
||
- `MigrationRunner` applica in transazione, è idempotente, rifiuta di partire se trova versioni applicate non note (downgrade non supportato) e registra l'esito nel log di sistema (sezione *Migrazioni*). All'avvio migra il database di sistema; le aziende vengono migrate all'avvio (impostazione) o dal pannello (§12.1), con modalità manutenzione per quell'azienda.
|
||
- Test obbligatorio: tutte le migrazioni da zero su SQLite e PostgreSQL, `schema_version` coerente, riapplicazione senza effetti.
|
||
|
||
### 5.4 Database di sistema e database aziendali
|
||
- **`khaemhat_system`** (`KHAEMHAT_SYSTEM_DB`): `sys_companies` (codice, ragione sociale, motore, connection string **cifrata**, stato *attiva/manutenzione/sola lettura/disattivata*, predefinita, note), `sys_users` (super utente e amministratori), `sys_roles_templates`, `sys_settings`, `sys_licenses` e `sys_license_activations`, `sys_scheduled_tasks`, `sys_job_runs`, `sys_backup_policies`, `sys_backup_sets`, `sys_log`, `sys_security_audit`, `sys_data_protection_keys`, `sys_api_keys` (istanza), `sys_notifications` (amministratori), `sys_sessions` (account di istanza).
|
||
- **`khaemhat_<codice>`** per azienda: tutte le tabelle operative + `users`, `roles`, `role_permissions`, `user_roles`, `user_permission_overrides`, `user_sessions`, `user_settings`, `api_keys`, `notifications`, `attachments`, `audit_log`, `company_profile`.
|
||
- `ICompanyRegistry` (sistema) risolve `companyCode → (IDbProvider, connection string decifrata)`; `ICompanyContext` è per-circuito Blazor e per-richiesta API (header `X-Company`). Un utente di istanza sceglie l'azienda dalla barra superiore; un utente aziendale è vincolato alla sua.
|
||
- Segreti (connection string delle aziende, password SMTP/PEC/S3/WebDAV, token degli intermediari, credenziali canali) cifrati con AES-256-GCM e chiave derivata da **`KHAEMHAT_SECRET_KEY`** (obbligatoria, ≥ 32 byte base64); senza chiave l'app non parte. Le chiavi DataProtection (cookie) stanno in `sys_data_protection_keys`.
|
||
- Bootstrap al primo avvio: migra il sistema → crea il super utente da env → crea la prima azienda da `KHAEMHAT_COMPANY_CODE/NAME` (CREATE DATABASE sul server di `KHAEMHAT_DB_SERVER` o SQLite) → migra → tabelle di base → (demo se richiesto). Le variabili vengono rilette solo se la tabella corrispondente è vuota.
|
||
|
||
---
|
||
|
||
## 6. Configurazione (variabili d'ambiente)
|
||
|
||
| Variabile | Obbl. | Esempio / default | Note |
|
||
|---|---|---|---|
|
||
| `KHAEMHAT_SYSTEM_DB` | sì | `postgres://khaemhat:secret@khaemhat-db:5432/khaemhat_system` oppure `sqlite:///data/system.db` | Database di sistema. Variante `_FILE` per Docker secrets |
|
||
| `KHAEMHAT_DB_SERVER` | sì con PostgreSQL | `postgres://khaemhat:secret@khaemhat-db:5432/` | Server su cui creare i database aziendali (ruolo con `CREATEDB`); se assente, usa host/credenziali del sistema |
|
||
| `KHAEMHAT_SECRET_KEY` | sì | base64 di 32+ byte | Cifratura dei segreti nel DB di sistema; cambiarla richiede la procedura di rotazione (§12.9) |
|
||
| `KHAEMHAT_SUPERUSER` `KHAEMHAT_SUPERUSER_PASSWORD` `KHAEMHAT_SUPERUSER_EMAIL` | sì al primo avvio | `root` / … | Usate **solo al primo avvio** per creare il super utente (hash nel DB); poi ignorate; cambio password obbligatorio al primo accesso; varianti `_FILE` |
|
||
| `KHAEMHAT_COMPANY_CODE` `KHAEMHAT_COMPANY_NAME` | sì al primo avvio | `DEMO` / `Khaemhat Demo S.r.l.` | Prima azienda (database `khaemhat_demo`); le altre dal pannello |
|
||
| `KHAEMHAT_COUNTRY` | no | `IT` | Pacchetto fiscale della prima azienda |
|
||
| `KHAEMHAT_LICENSE_MODE` | no | `production` | `test` abilita i codici fittizi di §8.3 (mai in produzione) |
|
||
| `KHAEMHAT_LICENSE` | no | testo licenza `.khl` | Assente = *Trial* (moduli CORE+ACCT, 3 utenti, 60 giorni, banner) |
|
||
| `KHAEMHAT_REDIS` | no | `redis://:pwd@khaemhat-redis:6379/0` (`rediss://` TLS) | Assente = cache in memoria |
|
||
| `KHAEMHAT_DATA_DIR` | no | `/data` | SQLite, allegati (`/data/files/<azienda>`), backup (`/data/backups/<db>`), inbox SDI (`/data/inbox/sdi/<azienda>`), export in streaming |
|
||
| `KHAEMHAT_URLS` | no | `http://0.0.0.0:8080` | TLS terminato dal reverse proxy |
|
||
| `KHAEMHAT_PUBLIC_URL` | no | `https://gestionale.example.com` | Link nelle e-mail e nelle notifiche |
|
||
| `KHAEMHAT_SMTP_*` | no | `HOST PORT USER PASSWORD FROM SECURITY` | Sovrascrivibili dalle Impostazioni (cifrate) |
|
||
| `KHAEMHAT_LOG_LEVEL` | no | `Information` | Livello minimo su stdout; il DB segue la retention per sezione |
|
||
| `KHAEMHAT_SEED_BASE` / `KHAEMHAT_SEED_DEMO` | no | `true` / `false` | Tabelle di base alla creazione; dati dimostrativi solo su database vuoto |
|
||
| `KHAEMHAT_UPDATE_FEED` `KHAEMHAT_UPDATE_TOKEN` | no | `https://api.github.com/users/<owner>/packages/container/khaemhat/versions` + token `read:packages` | Controllo aggiornamenti (sola lettura) |
|
||
| `TZ` `PUID` `PGID` | no | `Europe/Rome` `99` `100` | Fuso orario; utente/gruppo per i file in `/data` |
|
||
| `KHAEMHAT_TEST_PG` `KHAEMHAT_TEST_REDIS` | solo test | URL | Test d'integrazione |
|
||
|
||
`Program.cs` valida tutto all'avvio con `KhaemhatOptions.Validate()` e termina con messaggio esplicito se manca qualcosa. Nessun valore è scritto su disco.
|
||
|
||
---
|
||
|
||
## 7. Utenti, livelli, permessi e sicurezza
|
||
|
||
### 7.1 Tre livelli
|
||
| Livello | Dove vive | Può | Non può |
|
||
|---|---|---|---|
|
||
| **Super utente** (`SuperUser`) | DB di sistema; uno solo, creato dalle variabili del container; non eliminabile né degradabile | tutto: creare/eliminare **amministratori**, attivare moduli e licenze, creare/eliminare/clonare database aziendali, cambiare impostazioni critiche (SMTP, chiavi, cloud backup), ripristinare backup, modalità manutenzione, rimuovere dati demo, rotazione segreti, vedere ogni log | — |
|
||
| **Amministratore** (`Administrator`) | DB di sistema; creati dal super utente | istanza e database (migrazioni, manutenzione, backup e copie remote, verifica; **ripristino solo con conferma del super utente**), utenti di ogni azienda, ruoli (mai superiori ai propri), attività programmate, impostazioni azienda e sistema non critiche, log, stato sistema, dati di base | creare amministratori, toccare il super utente, attivare moduli/licenze, eliminare database |
|
||
| **Utente** (`Standard`) | DB dell'azienda; creati dagli amministratori (o da un utente con permesso `company.users.manage`) | operare entro i permessi dei ruoli; profilo, preferenze e sessioni proprie | qualunque funzione di istanza |
|
||
|
||
Modello: `sys_users` (istanza, `level`) e `users` (azienda, `kind = Human | Technical` per API). Un amministratore può essere "collegato" a un utente aziendale per operare come tale senza secondo login. La pagina di accesso (mockup 001) chiede azienda, utente e password: gli account di istanza vengono riconosciuti dal DB di sistema e, se scelgono un'azienda, entrano con i permessi completi su di essa.
|
||
|
||
### 7.2 Permessi
|
||
Codici `modulo.entità.azione` (es. `sales.invoice.issue`, `ledger.entry.finalize`, `vat.settlement.confirm`, `inventory.entry.post`, `crm.opportunity.write`, `attachments.delete`, `items.cost.read`, `company.users.manage`). Azioni standard: `read`, `write`, `delete`, `post`/`issue`/`finalize`, `reopen`, `export`, `print`, `override_*`. Ruoli predefiniti (modelli nel DB di sistema, copiati nelle aziende; clonabili, non modificabili): Amministrazione, Contabilità, Vendite, Acquisti, Magazzino, CRM, Servizi, Sola lettura. Flag per utente: vede solo i propri clienti (agenti), vede costi e margini, può esportare, può usare le API. L'UI nasconde ciò che non è permesso; il server verifica sempre (`[RequirePermission]`, `[RequireLevel]`, `PermissionAuthorizationHandler`). Un modulo non licenziato è equivalente a permesso negato (`module_not_licensed`).
|
||
|
||
### 7.3 Sessioni, password, API
|
||
- Cookie `HttpOnly; Secure; SameSite=Lax`, id 256 bit, riga di sessione (revoca, elenco per utente, dispositivo, IP, avviso nuovi dispositivi), scadenza scorrevole; il circuito Blazor verifica la sessione a ogni riconnessione. Limite utenti concorrenti da licenza, conteggiato sulle sessioni attive di tutte le aziende.
|
||
- Password: policy (default 10 caratteri, 3 classi), storico 5, scadenza opzionale, blocco 5 tentativi/15 min, rate limiting IP su `/login` e `/api`; **TOTP obbligatorio per super utente e amministratori** (configurabile per gli utenti); recupero via e-mail con token monouso; password provvisorie monouso.
|
||
- API: chiavi `kh_…` (hash SHA-256, prefisso visibile), legate a utente tecnico, permessi propri, azienda, scadenza, IP consentiti.
|
||
- Audit: ogni insert/update/delete su anagrafiche, documenti, registrazioni e impostazioni → `audit_log` dell'azienda (`entity, entity_id, action, user, at, diff JSON`), visibile dal record ("Storico"); azioni di sicurezza e di istanza (login, permessi, licenze, backup, ripristini, database, manutenzione) → `sys_security_audit` immutabile.
|
||
- Header: CSP (self + nonce per Blazor), `X-Frame-Options: DENY`, `Referrer-Policy`, HSTS dal proxy. Antiforgery sui form statici.
|
||
|
||
---
|
||
|
||
## 8. Licenze e moduli
|
||
|
||
### 8.1 Moduli
|
||
| Codice | Modulo | Contenuto |
|
||
|---|---|---|
|
||
| `CORE` | Base | anagrafiche, articoli e listini, preventivi/ordini/DDT/fatture, acquisti base, magazzino, tabelle, report base, amministrazione, allegati |
|
||
| `ACCT` | Contabilità | piano dei conti, causali, prima nota, partitari, registri IVA, liquidazioni, LIPE/F24 dati, ritenute e casse, bollo, chiusura esercizio, bilancio CEE |
|
||
| `ASSET` | Cespiti | registro beni ammortizzabili, ammortamenti, dismissioni |
|
||
| `FIN` | Tesoreria | scadenzario, incassi/pagamenti, RiBa/SDD/SEPA, riconciliazione bancaria, solleciti, flusso di cassa |
|
||
| `EINV` | Fatturazione elettronica | XML attivo/passivo, canali SDI (PEC integrata, SdICoop, intermediari), notifiche, autofatture, dichiarazioni d'intento, bollo virtuale |
|
||
| `INTRA` | Intrastat | elenchi cessioni/acquisti e file Agenzia Dogane |
|
||
| `CRM` | CRM | lead, pipeline/opportunità, attività e agenda, campagne, ticket |
|
||
| `SVC` | Servizi | contratti di assistenza, squadre, interventi, rapportini |
|
||
| `CHAN` | Canali e-commerce | connettore generico, ordini web, sincronizzazione giacenze/prezzi |
|
||
| `AUTO` | Automazioni | regole quando→se→allora, procedure pianificabili oltre quelle di sistema |
|
||
| `API` | Integrazioni | API REST, MCP, webhook, chiavi API |
|
||
| `MULTI` | Multi-azienda | aziende oltre la prima sulla stessa istanza |
|
||
| `REPORT` | Report avanzati | margini, analisi, report pianificati, export per il commercialista |
|
||
Senza modulo attivo: voci di menu nascoste, API/MCP del modulo non registrati, procedure non eseguibili, dati conservati.
|
||
|
||
### 8.2 Formato e verifica
|
||
- Licenza di istanza: JSON firmato ECDSA P-256 in file `.khl` (`licensee`, `instanceId` opzionale, `issuedAt`, `expiresAt`, `maxConcurrentUsers`, `maxCompanies`, `modules[]`, `gracePeriodDays`), chiave pubblica nel binario, privata solo in `tools/Khaemhat.LicenseTool` (mai nel repository).
|
||
- Codice di attivazione singolo modulo: `KH<v>-<MODULO>-<AAAAMM>-<payload base32>-<firma>`; verificato offline. In futuro `ILicenseActivationService` userà un server di attivazione (attiva/disattiva da remoto, tracciamento, heartbeat): già previsto come interfaccia, implementazione `OfflineActivationService` oggi.
|
||
- Attivazione **solo** dalla pagina *Amministrazione › Licenze e moduli* del super utente (mockup 080); storico attivazioni in `sys_license_activations`; verifica all'avvio, al login e ogni ora; oltre scadenza + grazia: sola lettura con banner.
|
||
|
||
### 8.3 Licenze fittizie per test (valide solo con `KHAEMHAT_LICENSE_MODE=test`)
|
||
`KH-TEST-CORE-0000-0001` · `KH-TEST-ACCT-0000-0002` · `KH-TEST-ASSET-0000-0003` · `KH-TEST-FIN-0000-0004` · `KH-TEST-EINV-0000-0005` · `KH-TEST-INTRA-0000-0006` · `KH-TEST-CRM-0000-0007` · `KH-TEST-SVC-0000-0008` · `KH-TEST-CHAN-0000-0009` · `KH-TEST-AUTO-0000-0010` · `KH-TEST-API-0000-0011` · `KH-TEST-MULTI-0000-0012` · `KH-TEST-REPORT-0000-0013` · tutti i moduli: `KH-TEST-ALL-0000-9999` · 25 utenti concorrenti: `KH-TEST-USERS-0025-0014` · proroga trial 60 giorni: `KH-TEST-TRIAL-0060-0015`. In modalità test la pagina mostra il banner "licenze fittizie"; in produzione questi codici sono rifiutati con `license_test_only`. I test automatici usano `KH-TEST-ALL-0000-9999`.
|
||
|
||
---
|
||
|
||
## 9. Cache, notifiche, scheduler, allegati e file, log
|
||
|
||
- `ICacheProvider` (`GetAsync`, `SetAsync` con TTL, `RemoveAsync`, `RemoveByPrefixAsync`, `GetOrCreateAsync`, `PublishInvalidationAsync`). Chiavi `kh:{azienda}:{area}:{key}`. In cache: tabelle di base, permessi, menu, piano dei conti, listini, licenze, ricerche recenti. Se Redis cade l'app continua in memoria e lo segnala.
|
||
- **Notifiche in app** (`notifications` per azienda, `sys_notifications` per istanza; mockup 010): generate da automazioni, attività programmate, SDI, scadenze, sicurezza; campanella, pannello laterale, digest e-mail opzionale.
|
||
- **Scheduler** (`JobRunner`): job di sistema (pulizia, licenza, cambi BCE, inbox e canali SDI, coda e-mail, verifica giacenze, backup) e **attività programmate** degli amministratori (§12.5), esecuzione singola per attività con lock nel DB di sistema anche tra riavvii, timeout, retry, log, notifica esito.
|
||
|
||
### 9.4 Allegati e generazione di file (mockup 024)
|
||
- `attachments` (per azienda): `entity`, `entity_id`, `kind` (*uploaded/generated/einvoice/notification*), nome, mime, dimensione, sha256, versione, generato-da (modello/procedura), utente, data, `locked` (es. XML inviato). Un allegato appartiene **a un solo documento**: non esistono allegati "sciolti"; cancellare un documento (quando ammesso) archivia i suoi allegati nel cestino dell'azienda per 30 giorni.
|
||
- File su volume `/data/files/<azienda>/<yyyy>/<guid>`; upload in streaming, limite configurabile (25 MB), antivirus non incluso (hook predisposto). Anteprima in app per PDF, immagini, XML (formattato), CSV/XLSX (griglia).
|
||
- **Generazione**: da ogni documento → *Stampa PDF* (modelli, copie, lingua), *XML FatturaPA*, *righe in XLSX/CSV*, *copia di cortesia PDF+XML (ZIP)*, *etichette colli*, *estratti conto*, *rapportini*; ogni generazione produce un allegato versionato (`v1`, `v2`…) scaricabile o inviabile; "Rigenera" crea una nuova versione. I report producono file scaricabili (XLSX/CSV/PDF) e, se pianificati, allegati e-mail. Le stampe massive producono uno ZIP scaricabile in streaming (mai file temporanei su disco fuori da `/data`).
|
||
- `IFileStore` (volume) con quota per azienda e statistiche; i backup includono `/data/files` per azienda.
|
||
|
||
### 9.5 Log applicativo avanzato (mockup 084)
|
||
- Un solo pipeline: `ILogger` → **console JSON** (una riga per evento) + **`DbLogSink`** nel DB di sistema (`sys_log`: `at`, `level`, `section`, `source`, `message`, `exception`, `user`, `company`, `trace_id`, `request`, `entity`, `entity_id`, `data` JSON). Ogni modulo scrive nella propria **sezione**: Sistema, Autenticazione, Database, Migrazioni, Documenti, Contabilità, Magazzino, SDI/e-invoicing, CRM, Automazioni, Attività programmate, Backup, API/MCP, E-mail/PEC, Integrazioni (VIES, BCE, intermediari), UI/circuiti (errori Blazor con stack), Prestazioni (query > 500 ms, richieste lente, GC).
|
||
- Pagina *Amministrazione › Log* con navigazione per sezione e contatori, filtri (periodo, livello, azienda, utente, trace, testo, origine, entità), dettaglio evento (contesto, stack, suggerimento, documento collegato con link), export CSV, **regole di avviso** (es. ≥ 1 errore in SDI → notifica amministratori; > 20 avvisi/ora in Autenticazione → e-mail), retention per livello (errori 365 gg, avvisi 180, info 90, debug 7) e compattazione.
|
||
- Correlazione: ogni richiesta/operazione ha `trace_id`; le attività programmate e le procedure loggano inizio/fine/durata/esito; gli errori mostrati all'utente riportano il `trace_id` ("Codice errore") per ritrovarli nel log.
|
||
|
||
---
|
||
|
||
## 10. Interfaccia utente
|
||
|
||
### 10.1 I mockup sono la specifica
|
||
`docs/mockups/png/` contiene **88 schermate** (più la galleria `000-galleria-mockup.png`); `docs/mockups/mockup.css` contiene tutti i token (`--kh-*`) e le classi dei componenti usati per disegnarle. Regole:
|
||
1. Prima della milestone 3 leggi `mockup.css` per intero e guarda almeno le schermate 004, 006, 007, 008, 012, 014, 020, 021, 024, 040, 064, 078, 084. Riproduci le classi come componenti Razor con gli stessi nomi semantici (`toolbar.icons`, `ib`, `ctx`, `dochead`, `fgroup`, `panel`, `form`/`f`, `grid`, `badge`, `tile`, `widget`, `tabs`, `dialog`, `drawer`, `kanban`, `timeline`, `tree`, `cal`, `att`, `strip`, `vsteps`).
|
||
2. `wwwroot/css/tokens.css` nasce da `mockup.css`: stessi nomi e valori dei token (temi `light`/`dark`/`auto`/`high-contrast`, otto accenti, densità). Non cambiare i nomi; aggiungi token solo se servono.
|
||
3. I dati nelle schermate sono esempio (seed demo), non vanno nel markup.
|
||
4. Le maschere senza mockup si compongono con gli stessi mattoni della più simile (tutte le tabelle di base seguono 012 + 076; tutti i documenti seguono 020/021).
|
||
5. Ogni cambiamento visivo aggiorna lo screenshot corrispondente e `docs/wiki/Design-UI.md` nella stessa unità di lavoro.
|
||
|
||
### 10.1.1 Indice delle schermate (`docs/mockups/png/`)
|
||
|
||
La galleria completa è `000-galleria-mockup.png`. Ogni voce indica il numero, cosa mostra e i mattoni da riprodurre.
|
||
|
||
#### Accesso e shell
|
||
|
||
**001 · Accesso con scelta azienda**
|
||
|
||

|
||
|
||
**002 · Accesso · verifica in due passaggi (TOTP)**
|
||
|
||

|
||
|
||
**003 · Primo accesso · cambio password obbligatorio**
|
||
|
||

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

|
||
|
||
**005 · Dashboard in tema scuro**
|
||
|
||

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

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

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

|
||
|
||
**009 · Ricerca globale (Ctrl+K)**
|
||
|
||

|
||
|
||
**010 · Pannello notifiche in app**
|
||
|
||

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

|
||
|
||
#### Anagrafiche e articoli
|
||
|
||
**012 · Clienti · radar (ricerca, filtri, selezione)**
|
||
|
||

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

|
||
|
||
**014 · Cliente · scheda anagrafica a gruppi**
|
||
|
||

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

|
||
|
||
**016 · Fornitore · scheda con condizioni di acquisto e ritenute**
|
||
|
||

|
||
|
||
**017 · Articolo · scheda con prezzi, riordino e giacenze**
|
||
|
||

|
||
|
||
**018 · Listini · griglia listino × articolo con aggiornamento massivo**
|
||
|
||

|
||
|
||
#### Vendite e documenti
|
||
|
||
**020 · Fattura di vendita · righe (toolbar a icone, intestazione documento)**
|
||
|
||

|
||
|
||
**021 · Fattura di vendita · testata a gruppi di campi**
|
||
|
||

|
||
|
||
**022 · Fattura di vendita · tema scuro, accento Malachite**
|
||
|
||

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

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

|
||
|
||
**025 · Anteprima di stampa / PDF della fattura**
|
||
|
||

|
||
|
||
**026 · Preventivo / offerta con revisioni e collegamento CRM**
|
||
|
||

|
||
|
||
**027 · Ordine cliente · evasione, residui, documenti collegati**
|
||
|
||

|
||
|
||
**028 · DDT · dati di trasporto, colli, firme**
|
||
|
||

|
||
|
||
**029 · Nota di credito TD04 con riferimento alla fattura**
|
||
|
||

|
||
|
||
**030 · Fatturazione differita · procedura guidata**
|
||
|
||

|
||
|
||
#### Acquisti
|
||
|
||
**031 · Ordine fornitore generato dalla proposta di riordino**
|
||
|
||

|
||
|
||
**032 · DDT di carico con controllo quantità ricevute**
|
||
|
||

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

|
||
|
||
**034 · Acquisti · import fatture passive XML/P7M**
|
||
|
||

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

|
||
|
||
#### Magazzino
|
||
|
||
**036 · Magazzino · giacenze, disponibilità, sottoscorta**
|
||
|
||

|
||
|
||
**037 · Movimento di magazzino manuale (trasferimento)**
|
||
|
||

|
||
|
||
**038 · Inventario fisico con conteggi e rettifiche**
|
||
|
||

|
||
|
||
**039 · Proposta di riordino fornitori dal sottoscorta**
|
||
|
||

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

|
||
|
||
**041 · Prima nota manuale con controllo di quadratura**
|
||
|
||

|
||
|
||
**042 · Contabilità · piano dei conti e mastrino**
|
||
|
||

|
||
|
||
**043 · Contabilità · causali contabili e modelli di registrazione**
|
||
|
||

|
||
|
||
**044 · Contabilità · partitario / estratto conto cliente**
|
||
|
||

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

|
||
|
||
**046 · Contabilità · liquidazione IVA, F24, LIPE**
|
||
|
||

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

|
||
|
||
**048 · Cespiti · registro beni ammortizzabili e piano di ammortamento**
|
||
|
||

|
||
|
||
**049 · Intrastat · elenchi cessioni/acquisti UE**
|
||
|
||

|
||
|
||
**050 · Contabilità · chiusura esercizio guidata**
|
||
|
||

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

|
||
|
||
**052 · Esercizi contabili e blocco periodi**
|
||
|
||

|
||
|
||
#### Scadenzario e tesoreria
|
||
|
||
**053 · Scadenzario · partite aperte e aging**
|
||
|
||

|
||
|
||
**054 · Scadenzario · dialogo Registra incasso**
|
||
|
||

|
||
|
||
**055 · Scadenzario · distinte RiBa / SDD / bonifici SEPA**
|
||
|
||

|
||
|
||
**056 · Scadenzario · solleciti a livelli**
|
||
|
||

|
||
|
||
**057 · Scadenzario · riconciliazione bancaria**
|
||
|
||

|
||
|
||
#### Fatturazione elettronica
|
||
|
||
**058 · Fatturazione elettronica · cruscotto SDI**
|
||
|
||

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

|
||
|
||
**060 · Fatturazione elettronica · bollo virtuale trimestrale**
|
||
|
||

|
||
|
||
**061 · Fatturazione elettronica · dichiarazioni d'intento e plafond**
|
||
|
||

|
||
|
||
#### CRM
|
||
|
||
**062 · CRM · dashboard con imbuto, previsione e fonti**
|
||
|
||

|
||
|
||
**063 · CRM · lead con punteggio e conversione**
|
||
|
||

|
||
|
||
**064 · CRM · pipeline opportunità (kanban)**
|
||
|
||

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

|
||
|
||
**066 · CRM e Servizi · agenda settimanale**
|
||
|
||

|
||
|
||
**067 · CRM · ticket di assistenza collegati a interventi**
|
||
|
||

|
||
|
||
**068 · CRM · campagne e segmenti**
|
||
|
||

|
||
|
||
#### Servizi, canali, report, automazioni, tabelle
|
||
|
||
**069 · Servizi · contratto di assistenza e interventi**
|
||
|
||

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

|
||
|
||
**071 · Report · fatturato per cliente con export e pianificazione**
|
||
|
||

|
||
|
||
**072 · Automazioni · regole quando → se → allora**
|
||
|
||

|
||
|
||
**073 · Automazioni · catalogo procedure**
|
||
|
||

|
||
|
||
**074 · Tabelle azienda · codici automatici e compilazione automatica**
|
||
|
||

|
||
|
||
**075 · Tabelle azienda · profilo azienda**
|
||
|
||

|
||
|
||
**076 · Tabelle azienda · codici IVA con nature SDI**
|
||
|
||

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

|
||
|
||
#### Amministrazione
|
||
|
||
**078 · Amministrazione · istanza, database di sistema e per azienda**
|
||
|
||

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

|
||
|
||
**080 · Amministrazione · licenze e moduli attivabili con codice**
|
||
|
||

|
||
|
||
**081 · Amministrazione · utenti a tre livelli e per azienda**
|
||
|
||

|
||
|
||
**082 · Amministrazione · matrice ruoli × permessi**
|
||
|
||

|
||
|
||
**083 · Amministrazione · attività programmate (scheduler)**
|
||
|
||

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

|
||
|
||
**085 · Amministrazione · stato sistema e aggiornamenti**
|
||
|
||

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

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

|
||
|
||
**088 · Amministrazione · chiavi API, MCP e webhook**
|
||
|
||

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

|
||
|
||
|
||
### 10.2 Shell (mockup 004, 007)
|
||
- **Barra superiore** scura: marca (icona 4 tessere + nome + versione), selettore azienda (solo account di istanza o utenti multi-azienda), ricerca globale (Ctrl+K, mockup 009: clienti, fornitori, articoli, documenti, registrazioni, conti, azioni, comandi con `>`, documenti con `#`, persone con `@`), nuovo, recenti, notifiche (010), cambio tema rapido, aiuto (F1 → pagina wiki della maschera, 011), menu utente.
|
||
- **Menu laterale comprimibile** (007, 013): stato espanso (icona + testo, sotto-voci del modulo attivo, contatori) o compresso a 60 px (sole icone, tooltip, sotto-voci in un pannello a comparsa al passaggio o al clic). Il pulsante "Comprimi menu" in fondo e la scorciatoia `Ctrl+B`; lo stato è ricordato per utente; sotto 1100 px il menu è compresso di default. Ordine voci: Home; Anagrafiche, CRM, Vendite, Acquisti, Magazzino, Contabilità, Scadenzario, Fatturazione elettronica, Cespiti, Servizi, Canali e-commerce, Report; Tabelle azienda, Automazioni, Amministrazione (solo account di istanza). Le voci compaiono solo con modulo licenziato e permessi.
|
||
- **Area a schede** (`TabHost`): ogni maschera aperta è una scheda mantenuta in vita; pallino arancione se modificata; avviso alla chiusura con modifiche; massimo 12; `Ctrl+W` chiude, `Ctrl+Tab` passa.
|
||
- **Barra di stato**: azienda, esercizio, utente·livello, deposito, stato connessione/latenza, Redis, versione.
|
||
|
||
### 10.3 Dashboard (004, 005, 006)
|
||
- Griglia a **widget** (12 colonne, larghezze 3/4/6/8/12), ciascuno disattivabile, ordinabile per trascinamento e ridimensionabile in modalità *Personalizza* (pannello laterale 006). Widget disponibili: **KPI** (indicatori scelti dall'utente), **Da fare oggi** (generato da: scarti SDI, liquidazioni e scadenze fiscali, procedure in attesa, attività CRM, approvazioni), **Fatto oggi** (azioni completate dall'utente e dal team: documenti emessi, incassi, backup, attività programmate), **Scadenze prossimi 30 giorni** (fiscali, vendite, tesoreria, contratti, con etichetta area), **Da evadere** (ordini e DDT con residuo), **Fatturato 12 mesi**, **Attività CRM**, **Promemoria personali** (note libere per utente), **Scorciatoie** (pulsanti configurabili), Sottoscorta, Pipeline CRM, Ultimi documenti, Stato sistema (amministratori).
|
||
- La dashboard è **disattivabile**: in *Preferenze › Pagina iniziale* l'utente sceglie se mostrarla e quale pagina aprire all'accesso (ultima scheda aperta, un radar, la prima nota, l'agenda…). Layout e scelte sono in `user_settings`; gli amministratori possono definire un layout predefinito per ruolo.
|
||
|
||
### 10.4 Toolbar a sole icone (020)
|
||
- Comandi standard **solo icone** (32×32) con tooltip al passaggio (nome + scorciatoia) e senza etichette: `+` Nuovo (Ctrl+N), Salva (Ctrl+S, evidenziato), Annulla (Esc), Elimina (Ctrl+Canc) · Duplica, Stampa (Ctrl+P), Invia e-mail, Genera file/esporta · Allegati, Storico, Collegamenti · a destra Radar (F9), precedente/successivo, menu `⋯` con tutto il resto.
|
||
- Le **azioni contestuali** del documento (Conferma ed emetti, XML SDI, Contabilizza, Evadi da…, Genera DDT, Rendi definitiva…) sono "chip" icona + **etichetta sintetica** (massimo tre parole); la principale è piena (accento). Mai più di 4 chip: le altre finiscono nel menu `⋯`. La toolbar sta **sempre su una riga**: quando lo spazio manca, le icone meno usate scivolano nel menu `⋯`, le etichette non vanno mai a capo né si sovrappongono. Le toolbar delle liste (012, 036) seguono la stessa regola: icone + 1–2 chip.
|
||
|
||
### 10.5 Maschera documento (020, 021, 027, 028, 033, 040)
|
||
1. Toolbar a icone (§10.4).
|
||
2. **Intestazione documento** (`dochead`) in tre blocchi: a sinistra tipo (icona in riquadro + etichetta "Fattura immediata · TD01"), numero grande, riga meta (data, sezionale, registro) e badge di stato; al centro **controparte** (iniziali, nome con codice, indirizzo/P.IVA/PEC) e **chip** riassuntivi delle condizioni (pagamento, listino, agente, destinazione, banca, avvisi come scaduto/fido); a destra **totale** grande e tre sotto-valori (imponibile, IVA, bollo / residuo / margine). Per le anagrafiche lo stesso blocco mostra identità, contatti, chip delle condizioni e KPI (014, 016, 017).
|
||
3. **Schede con icone** (`tabs.i`): per i documenti la prima scheda è *Righe* (si apre lì), poi *Testata*, *Totali*, *Trasporto*, *Scadenze*, *Dati SDI/PA*, *Note*, *Allegati (n)*, *Collegamenti (n)*, *Storico*; per le anagrafiche *Dati principali*, *Indirizzi*, *Contatti*, *Condizioni*, *Fiscale e SDI*, *Banche*, *Articoli e codici*, *Note e allegati*, *CRM*, *Storico*. `Alt+1..9` cambia scheda.
|
||
4. La scheda *Testata* raggruppa i campi in **gruppi** (`fgroup`: Documento, Controparte, Condizioni, Magazzino e trasporto…) su griglia 12 colonne, etichette sopra i campi, obbligatori con asterisco, suggerimenti sotto, hotlink con codice evidenziato + descrizione + icone ricerca/apri.
|
||
5. La scheda *Righe*: griglia a tutta larghezza con editing inline (Invio cella successiva, Tab, frecce, `F4` ricerca, `Ctrl+↓` nuova riga, riga vuota in coda con placeholder), righe descrittive, menu riga `⋯`; sotto la griglia **castelletto IVA**, **scadenze/revisioni/partite** e **totali** in tre pannelli.
|
||
6. Stati e azioni contestuali; validazione a lato campo + riepilogo; una fattura emessa è in sola lettura (chip e campi disabilitati).
|
||
7. Scorciatoie globali: `Ctrl+S` salva, `Ctrl+N` nuovo, `Ctrl+P` stampa, `F4` lookup, `F9` radar, `Esc` annulla, `Ctrl+↑/↓` naviga record, `Ctrl+D` quadra (prima nota), `Ctrl+B` menu, `Ctrl+K` ricerca, `F1` aiuto.
|
||
|
||
### 10.6 Temi, colori, densità (008)
|
||
Tema **chiaro**, **scuro (notturno)**, **automatico** (segue il sistema), **alto contrasto**; otto **accenti** (`nilo` default, `lapislazzuli`, `malachite`, `turchese`, `ocra`, `corniola`, `ametista`, `grafite`) con varianti per tema in `mockup.css`; **densità** comoda/compatta, dimensione testo, carattere numerico tabellare, animazioni ridotte, tooltip on/off, stato del menu. Tutto in `user_settings`, applicato con `data-theme`, `data-accent`, `data-density` sulla radice; prima del login vale il tema di sistema; stampe sempre in chiaro (`print.css`).
|
||
|
||
### 10.7 Libreria componenti (`Components/Ui`, prefisso `Kh`)
|
||
`KhIconToolbar`, `KhIconButton` (tooltip, badge contatore), `KhContextAction`, `KhDocHead`, `KhFieldGroup`, `KhForm`/`KhField`, `KhTextBox`, `KhNumberBox` (it-IT, calcolo inline `=10*3`), `KhDateBox` (gg/mm/aaaa, +/- giorno, T oggi, F fine mese), `KhSelect`, `KhCheck`, `KhSwitch`, `KhTextArea`, `KhHotlink` (codice + descrizione, ricerca incrementale, F4 radar, Ctrl+Invio apre, crea al volo), `KhGrid` (colonne tipizzate, ordinamento, filtri, paginazione server, virtualizzazione, selezione multipla, editing inline, riga totali, layout colonne salvato, export, evidenziazioni, menu riga), `KhLinesGrid`, `KhTabs` (con icone e contatori), `KhPanel`, `KhTile`, `KhStrip`, `KhWidget` + `KhWidgetGrid` (personalizzabile), `KhDialog`, `KhDrawer`, `KhConfirm`, `KhToast`, `KhBadge`, `KhChip`, `KhMoney`, `KhRadar`, `KhSteps`/`KhVSteps`, `KhTree`, `KhKanban`, `KhTimeline`, `KhCalendar`, `KhAttachmentList` (con *Genera file*), `KhAuditList`, `KhPrintPreview`, `KhCommandPalette`, `KhNotificationBell`, `KhHelpLink`, `KhLogViewer`, `KhSideMenu` (comprimibile), `KhTabHost`, `KhStatusBar`.
|
||
|
||
### 10.8 Accessibilità, stile, localizzazione
|
||
Font di sistema (`Inter` se presente sul sistema dell'utente, altrimenti `Segoe UI`/`system-ui`; nessun font scaricato), icone SVG proprie in `icons/sprite.svg` (riprendi i tracciati dei mockup), focus visibile, etichette collegate, contrasto AA (AAA in alto contrasto), tutto operabile da tastiera, desktop-first usabile da tablet ≥ 768 px. `ITexts` risolve chiavi `Sales.Invoice.Title` da `Resources/it-IT/*.json`; formati con `CultureInfo("it-IT")`; nessun testo hard-coded nei componenti (test di architettura).
|
||
|
||
---
|
||
|
||
## 11. Moduli funzionali
|
||
|
||
Per ogni modulo: entità (tabella → colonne principali), regole, maschere, stampe. Colonne di audit e `row_version` sottintese. `→` indica chiave esterna. Ogni modulo documenta se stesso in `docs/wiki/<Modulo>.md` (§17) e dichiara il proprio codice di licenza (§8.1).
|
||
|
||
### 11.1 Azienda e tabelle di base (`Company`, modulo CORE) — mockup 052, 074, 075, 076
|
||
- `company_profile` (riga singola, 075): ragione sociale, denominazione fiscale, P.IVA, codice fiscale, REA, capitale sociale, socio unico, stato liquidazione, indirizzo, contatti, PEC, **regime fiscale** `RF01…RF19`, codice destinatario proprio, logo (allegato), IBAN predefinito, valuta, paese (`IT` → `ItalyFiscalPack`), periodicità IVA, pro-rata %, IVA per cassa, dati del trasmittente/intermediario, note in calce.
|
||
- `fiscal_years` (esercizio: inizio, fine, stato *aperto/in chiusura/chiuso*, prima pagina libro giornale, ultima registrazione definitiva) e `fiscal_periods` (mese/trimestre: *aperto/liquidato/bloccato*; 052). Date ammesse solo in periodi aperti.
|
||
- `countries` (ISO 3166-1, UE, codice SDI `XXXXXXX`), `provinces`, `municipalities` (CAP, codice catastale: per codice fiscale e compilazione da CAP), `currencies` + `exchange_rates` (BCE), `units_of_measure` (codice SDI), `tax_codes` (076: aliquota, **natura SDI** `N1…N7` con sotto-codici, riferimento normativo, esigibilità `I/D/S`, tipo, indetraibilità %, conti IVA →, validità), `payment_methods` (`MP01…MP23`), `payment_terms` (+ righe: rata, giorni, fine mese, giorno fisso, %, IVA sulla prima rata, `TP01/02/03`), `bank_accounts` (IBAN, BIC, conto →, SIA/CUC), `salespeople` (provvigione, ENASARCO), `carriers`, `shipping_terms`, `transport_means`, `goods_appearances`, `delivery_terms` (Incoterms), `transport_reasons`, `document_numerators` (tipo, sezionale, anno, formato `{prefix}/{anno}/{number:D6}`, assegnazione atomica alla conferma, buchi non ammessi per fatture/NC/registrazioni definitive), `inventory_reasons`, `warehouses`, `item_categories` (3 livelli), `party_categories`, `price_lists`, `discount_policies`, `document_types` (catalogo statico: kind, numeratore, causale magazzino, **causale contabile**, registro IVA, TD SDI, modello stampa), `cost_centers`, `jobs` (commesse).
|
||
- Maschere: una per tabella (modello 012 + 076), import/export CSV.
|
||
|
||
### 11.2 Anagrafiche (`Parties`) e articoli (`Items`, CORE) — mockup 012–018
|
||
- `parties` (clienti/fornitori/prospect/lead come `kind`): `code` automatico (§11.12), ragione sociale o nome/cognome, P.IVA, codice fiscale (calcolabile), tipo soggetto (*azienda/privato/PA/UE/extra-UE/forfettario*), sede, contatti, lingua, paese, categoria, agente, note, `disabled`, `is_demo`, conti contabili cliente/fornitore → (sottoconti del partitario creati alla prima registrazione); `party_addresses`, `party_contacts`, `party_bank_accounts`, `party_sales_terms` (listino, sconti, pagamento, banca RiBa, agente, vettore, porto, deposito, fido, blocco, raggruppa DDT, giorno fatturazione, invio documenti e-mail/PEC), `party_purchase_terms` (pagamento, lead time, minimo, sconti), `party_fiscal` (codice destinatario, PEC, split payment, reverse charge, **dichiarazione d'intento** con plafond/utilizzato/residuo, ritenuta e aliquota, causale, cassa previdenza, ENASARCO, EORI, GLN, forfettario), `party_item_codes`.
|
||
- Regole (014, 015): validazione P.IVA, codice fiscale (check char), IBAN (mod 97), VIES per P.IVA UE (HTTP, esito salvato), PA → codice IPA 6 caratteri, estero `XXXXXXX`, privato `0000000`; disabilitazione invece di cancellazione se esistono documenti; conversione lead/prospect → cliente con assegnazione codice.
|
||
- `items` (017): `code` automatico, descrizioni, tipo (*merce/servizio/spesa/testo/cespite*), categoria, UM, IVA vendita/acquisto, EAN, NC8, produttore, marca, pesi, deposito, scorta minima, punto/lotto di riordino, prezzi, costi (standard/ultimo/medio), gestione a magazzino, conti ricavo/costo →, immagine; `item_uoms`, `item_barcodes`, `item_prices`, `item_suppliers`, `item_substitutes`. Listini (018): griglia listino × articolo, aggiornamento massivo %, arrotondamenti, validità, listini derivati, prezzi netti per cliente.
|
||
|
||
### 11.3 Motore documenti (`Application/Documents`, CORE)
|
||
- `DocumentDefinition` (codice, kind, direzione, numeratore, causale magazzino, effetti, sorgenti per evasione, TD SDI, causale contabile, registro IVA, template stampa). Tabelle per famiglia: `sale_quotations`, `sale_orders`, `sale_documents` (DDT, fatture, NC/ND, pro-forma, parcelle, autofatture), `purchase_orders`, `purchase_documents`, `inventory_documents`; ognuna con `_lines`, `_tax_summary`, `_installments`. Testata: tipo, sezionale, numero, data, anno, controparte →, destinazione →, riferimenti, valuta/cambio, listino, pagamento, metodo, banca, agente, deposito, causale, stato, flag (stampato, inviato, contabilizzato, scadenze generate, XML generato), totali (imponibile, imposta, totale, sconto piede, spese, bollo, ritenuta, cassa, netto), note, trasporto, `is_demo`, `gl_entry_id`, protocollo IVA. Righe: progressivo, tipo riga, articolo →, descrizione, UM, q.tà, prezzo, sconti, formula sconto, IVA →, imponibile, deposito, consegna, evasa/residua, riga origine, conto →, centro di costo, commessa, note, ordinamento.
|
||
- `document_links` (target riga → sorgente riga, quantità): evasione ordine → DDT → fattura differita; DDT fornitore → fattura acquisto; residui; riapertura; `DatiOrdineAcquisto`/`DatiDDT` nell'XML (027).
|
||
- Stati: `Draft → Confirmed → (PartiallyFulfilled | Fulfilled) → Closed`, `Cancelled`; fatture `Draft → Issued → SdiGenerated → SdiSent → (SdiDelivered | SdiRejected | SdiNotDelivered)`. Fattura emessa immutabile (NC o annullamento con motivo se XML non inviato).
|
||
- `DocumentTotalsCalculator`: imponibile riga = q.tà × prezzo × (1−s1)(1−s2)…, 2 decimali `AwayFromZero`; castelletto per codice IVA; imposta per aliquota; spese con IVA propria; sconto piede ripartito; **bollo** €2,00 se esenti/non imponibili/fuori campo > €77,47; **ritenuta** e **cassa previdenza** per parcelle; **split payment**; **reverse charge**; **IVA per cassa**. `InstallmentGenerator`: condizione di pagamento, fine mese, giorno fisso, %, IVA sulla prima rata, sconto cassa, arrotondamento sull'ultima. Prezzi: netto cliente-articolo → listino cliente → listino base → prezzo articolo, con `price_source`.
|
||
- Numerazione alla conferma; data non anteriore all'ultimo numerato del sezionale per fatture/NC; periodo fiscale aperto. **Contabilizzazione** (§11.7) alla conferma (immediata o batch). Stampa HTML/PDF (025) con diciture di legge; copie; e-mail/PEC con PDF (+XML). Duplicazione, trasformazione (026), evasione guidata, fatturazione differita (030).
|
||
|
||
### 11.4 Vendite (`Sales`, CORE) — mockup 020–030
|
||
Preventivi con revisioni e collegamento CRM · Ordini clienti (consegne, impegnato, blocco fido/scaduto con override, CIG/CUP) · DDT (scarico, trasporto, 3 copie, resi) · Fatture immediate TD01, accompagnatorie, differite TD24/TD25, pro-forma, acconto TD02/TD03, NC TD04 e ND TD05, parcelle TD06, semplificate TD07/TD08/TD09, cessione cespiti TD26, autoconsumo/omaggi TD27 · corrispettivi registrati manualmente · report: giornale vendite, fatturato per cliente/agente/categoria/articolo (071), DDT da fatturare, ordini aperti, provvigioni, margini.
|
||
|
||
### 11.5 Acquisti (`Purchases`, CORE) — mockup 031–035
|
||
Ordini fornitori (da proposte di riordino, 031) · DDT di carico con controllo quantità (032) · Fatture di acquisto con protocollo, conti e centri di costo per riga, ritenute (033) · note di credito fornitore · **import XML/P7M** (034: fornitore per P.IVA/CF, creazione al volo, mappatura righe, confronto con ordine, bozza con differenze, XML allegato, firma verificata) · **autofatture e integrazioni** (035): TD16 reverse charge interno, TD17 servizi estero, TD18 beni intra-UE, TD19 beni art. 17 c.2, TD20/TD29 regolarizzazione, TD21 splafonamento, TD22/TD23 depositi IVA, TD28 San Marino cartacee/irregolari da non residenti; registri RC vendite+acquisti (IVA neutra); XML entro il 15 del mese successivo con promemoria · fatture da forfettari.
|
||
|
||
### 11.6 Magazzino (`Inventory`, CORE) — mockup 036–039
|
||
`inventory_entries` + `_lines`, `item_balances` (articolo × deposito: giacenza, impegnato, ordinato, in transito, valore medio) aggiornati transazionalmente; disponibilità = giacenza − impegnato; movimenti manuali e trasferimenti (037), inventario fisico con liste, conteggi e rettifiche (038), costo medio ponderato (FIFO/LIFO predisposti), rimanenze finali per chiusura e libro inventari, scritture ausiliarie di magazzino, ricostruzione; giacenze/disponibilità con sottoscorta (036), proposta di riordino → ordini fornitore (039), scheda articolo, valorizzazione a data, ABC.
|
||
|
||
### 11.7 Contabilità generale (`Ledger`, ACCT) — mockup 040–052
|
||
- **Piano dei conti** (042) `gl_accounts`: codice gerarchico `MM.CC.SSS`, descrizione, natura, tipo, padre →, **voce CEE** (art. 2424/2425), voce riclassificata, partitario clienti/fornitori, rilevante IVA, chiusura automatica, movimentabile, attivo. Piano standard PMI **precaricato** (`Fiscal.Italy/ChartOfAccounts`) e **importabile**: non esiste uno standard italiano per lo scambio del piano dei conti, quindi si accettano `CSV` (`;`, colonne `codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag`) e `XLSX` con lo stesso tracciato, più `JSON` per export/import completo (`khaemhat-coa.json`: conti, voci di bilancio, causali e mappature); importazione guidata (077) con anteprima e verifica di coerenza gerarchica.
|
||
- **Causali contabili** (043) `gl_journal_templates`: righe modello con *ruolo* (cliente, fornitore, ricavo, costo, IVA vendite, IVA acquisti, banca, cassa, Erario ritenute, cassa previdenza, bollo, abbuoni, contropartita), dare/avere, registro IVA, genera partita; causali di base: FV, NCV, FA, NCA, AFRC, CORR, INC, PAG, INS, GIRO, AMM, RAT, RIM, chiusura/apertura, F24, ritenute versate, stipendi (import), interessi/commissioni.
|
||
- **Prima nota** (040, 041) `gl_entries` (numero per esercizio, data registrazione, competenza, causale, descrizione, documento origine, registro IVA → e protocollo, stato *provvisoria/definitiva*, periodo, fonte, storno di →) + `gl_entry_lines` (conto, dare/avere, controparte, centro di costo, commessa, partita →, valuta) + `gl_entry_vat`. Quadratura obbligatoria (bozza ammessa se non quadra, mai definitiva); registrazioni da documento modificabili solo stornando il documento; **definitive immutabili** con numerazione continua sul libro giornale; blocco per periodo liquidato e per esercizio chiuso; storno collegato; registrazioni ricorrenti; registrazioni in valuta con differenze cambio.
|
||
- **Partitari e mastrini** (044) con drill-down fino al documento; estratti conto.
|
||
- **Registri IVA** (045) `vat_registers` (vendite, acquisti, corrispettivi, vendite RC, acquisti RC, sezionali) con protocollo; stampe provvisorie e definitive (pagine numerate, totali per aliquota/natura). **Liquidazione IVA** (046) `vat_settlements`: debito/credito, esigibilità differita e per cassa, indetraibile, pro-rata, credito precedente, acconto di dicembre (storico/previsionale/analitico), interessi 1% trimestrali, minimo €25,82 con riporto, **dati F24** (6001–6012, 6031–6034, 6013/6035, 6099) e **LIPE** XML (tracciato AdE), controlli preliminari, conferma che blocca il periodo.
|
||
- **Bollo virtuale** (060), **ritenute e contributi** (047: operate con F24 1040/1038 e CU export; subite; INPS 4%/casse; ENASARCO), **cespiti** (048, ASSET: categorie con coefficienti DM 31/12/1988, primo anno 50%, limiti autovetture, < €516,46, dismissioni con plus/minusvalenza TD26, rivalutazioni, piano simulato, registro beni ammortizzabili, contabilizzazione annuale), **Intrastat** (049, INTRA: INTRA-1/2 bis-quater, periodicità da soglie, NC8, natura transazione, consegna, trasporto, file nel tracciato Agenzia Dogane), **dichiarazioni d'intento** ricevute ed emesse (061).
|
||
- **Chiusura esercizio** (050): controlli, ammortamenti, ratei/risconti, rimanenze, accantonamenti, chiusura CE e SP, apertura con riporto partite e saldi, stampe definitive (libro giornale, libro inventari, registri IVA, registro cespiti); blocco → sola lettura. **Bilancio** (051): verifica, CEE (ordinario/abbreviato/micro) con confronto e drill-down, riclassificati, indici, situazione infrannuale, nota integrativa in bozza, export XLSX/PDF; XBRL in fase 2.
|
||
- Report: libro giornale, mastrini, bilancini per C.d.C./commessa, registri IVA, liquidazioni, scadenziario IVA, elenco clienti/fornitori per fatturato, riepilogo per natura, quadri VE/VF (dati), estratti conto, **export per il commercialista** (pacchetto ZIP mensile: giornale, registri, partitari, bilancio in XLSX/CSV/PDF).
|
||
|
||
### 11.8 Scadenzario e tesoreria (`Finance`, FIN) — mockup 053–057
|
||
`open_items` (partite: controparte, documento, rata, scadenza, importo, pagato, residuo, metodo, banca, stato *aperta/parziale/chiusa/insoluta/in distinta/contestata*, registrazione →), `payments` con righe su partite, abbuoni, differenze cambio, spese, storno, registrazione contabile automatica (054). **Effetti e distinte** (055): RiBa (file CBI), SDD core/B2B (mandati, `pain.008`), bonifici SEPA (`pain.001`), MAV/RAV come scadenze; insoluti con riapertura e spese; anticipi s.b.f. **Riconciliazione bancaria** (057): import CSV/CBI/CAMT.053, abbinamento con confidenza, regole salvate, registrazione delle righe non abbinate. **Solleciti** (056): livelli 1–3, modelli e-mail/PEC/lettera, interessi di mora (D.Lgs. 231/2002), registro invii, blocco cliente; eseguibili da attività programmata. Report: scadenzario, aging (053), estratto conto, flusso di cassa 90 gg, insoluti, posizione bancaria.
|
||
|
||
### 11.9 Fatturazione elettronica (`EInvoicing` + `Fiscal.Italy`, EINV) — mockup 058–061
|
||
- `FatturaPaWriter`: XML `FPR12`/`FPA12`/`FSM10` secondo le specifiche tecniche correnti dell'Agenzia delle Entrate (alla stesura la v1.9 in vigore dal 1° aprile 2025, con TD29 e TD20 ridefinito; registra la versione supportata in `FatturaPaCodeLists.SpecVersion` e verifica sempre l'ultima pubblicata): `DatiTrasmissione`, `CedentePrestatore`, `CessionarioCommittente`, `DatiGenerali` (TD, DatiRitenuta, DatiBollo, DatiCassaPrevidenziale, ScontoMaggiorazione, Causale, Art73), `DatiOrdineAcquisto`/`DatiContratto`/`DatiConvenzione`/`DatiRicezione`/`DatiFattureCollegate` (CIG/CUP), `DatiDDT`, `DatiTrasporto`, `DettaglioLinee`, `DatiRiepilogo`, `DatiPagamento`, `Allegati`; nome file `IT<PIVA>_<progressivo base36>.xml`.
|
||
- `FatturaPaValidator` (code list, lunghezze, totali ±0,01, nature e riferimenti normativi, destinatario/PEC, PA con CIG/CUP, codice fiscale gruppi IVA, bollo); `FatturaPaReader` (passive, P7M/CAdES, allegati); `SdiNotificationReader` (RC, NS, MC, NE/EC01-EC02, DT, AT, metadati).
|
||
- **Canali di trasmissione** (`ISdiTransport`, mockup 059), tutti con la stessa interfaccia (invia, stato, notifiche, scarica passive): **PEC integrata** (nessun servizio esterno: invio dell'XML come allegato alla PEC dello SDI via SMTP della PEC aziendale, lettura delle notifiche e delle fatture passive dalla casella PEC con il client IMAP in casa, filtro per mittente/oggetto, archivio in cartelle); **SdICoop** (web service dell'Agenzia, accreditamento e certificato dell'azienda, SOAP costruito a mano con `HttpClient` e certificato client, notifiche in tempo reale); **Intermediario A** e **Intermediario B** (connettori REST ai due servizi di intermediazione scelti dal titolare del progetto, credenziali cifrate, mappatura stati/errori, conservazione a norma se inclusa nel servizio). Regole di instradamento (canale per cliente PA, per volumi, predefinito). Lo SDI non si può "inglobare": è il sistema dell'Agenzia; il canale PEC è il massimo dell'integrazione senza terzi.
|
||
- **Conservazione**: pacchetto di esportazione per periodo (XML + notifiche + indice) da affidare a un conservatore o al servizio dell'Agenzia; dichiarato nella wiki. `IEInvoiceFormat` consente EN 16931/UBL (Peppol) come implementazione futura.
|
||
- Cruscotto (058): contatori per stato, elenco prioritizzato, genera/valida/invia/scarica, correggi e rigenera, importa notifiche/passive, bollo virtuale, autofatture da inviare, canale usato per documento.
|
||
|
||
### 11.10 CRM (`Crm`, CRM) — mockup 062–068
|
||
`crm_leads` (fonte, interesse, punteggio da regola, responsabile, stato, conversione in cliente), `crm_pipelines` + `crm_stages`, `crm_opportunities` (fase, probabilità, valore, ponderato, chiusura, responsabile, fonte, concorrenti, motivo perdita, preventivo →, ordine →), `crm_activities` (chiamata/e-mail/riunione/attività/nota/visita, scadenza, esito, promemoria, collegamenti), `crm_campaigns` (tipo, segmento, modello, budget, costo, membri, statistiche), `crm_tickets` (priorità, stato, SLA, assegnatario, collegamento a intervento Servizi e a NC), `crm_email_templates`, `crm_segments`. Funzioni: dashboard con imbuto e previsione (062), lead (063), kanban trascinabile (064), scheda opportunità con cronologia (065), agenda condivisa con gli interventi (066), ticket (067), campagne (068), scheda controparte a 360°, e-mail inviate archiviate, import lead da CSV/API (form sito web).
|
||
|
||
### 11.11 Servizi (`Services`, SVC) e Canali e-commerce (`Channels`, CHAN) — mockup 069, 070
|
||
- Contratti di assistenza (cliente, sede, validità, rinnovo tacito, canone e periodicità, servizi inclusi, impianti e matricole), squadre e tecnici (costo orario), interventi (*programmato/a chiamata/garanzia*, stato, pianificazione, ore e materiali, rapportino, firma), generazione interventi periodici e rate/canoni, fatturazione dei rapportini tramite il motore documenti, calendario.
|
||
- Canali: `sales_channels` (tipo *generico* o connettore dedicato, credenziali cifrate, cliente cassa, sezionale, pagamento, deposito, mappature pagamenti/spedizioni), `channel_items`, `channel_orders` (payload JSON, stato), `channel_customers`; connettore **generico** (JSON/CSV + `POST /api/v1/channels/{code}/orders`, sincronizzazione giacenze/prezzi in uscita); connettori dedicati ai singoli marketplace/piattaforme come implementazioni successive di `IChannelConnector`.
|
||
|
||
### 11.12 Automazioni, procedure e preferenze (`Automation`, `UserSettings`, AUTO) — mockup 072–074
|
||
- **Codici automatici** (074, `CodeRule` per entità): maschere `C{seq:000000}`, `F{seq:000000}`, `{categoria}-{seq:0000}`, `L{anno}-{seq:0000}`, `CESP-{seq:0000}`, `OPP-{anno}-{seq:0000}`, `TK-{anno}-{seq:0000}`, `SVC-{seq:0000}`, `MAN-{anno}-{seq:0000}`; progressivo globale o per categoria/anno; codice manuale ammesso o no; anteprima del prossimo codice; numeratori in `code_sequences` con assegnazione atomica.
|
||
- **Compilazione automatica**: comune/provincia/regione da CAP, codice fiscale calcolato, VIES, cambi BCE, banca/BIC da IBAN (tabella ABI), descrizione articolo nelle righe, ultimo prezzo praticato, proposta ultimo documento simile, date consegna = data + lead time, destinazione/listino/pagamento/agente dal cliente, causale/deposito dal tipo documento, conti da articolo/categoria/causale.
|
||
- **Regole** (072) `automation_rules` quando → se → allora: eventi (`DocumentCreated/Confirmed/Issued/Cancelled`, `SdiNotificationImported`, `OpenItemOverdue`, `StockBelowReorder`, `LeadCreated`, `OpportunityStageChanged`, `TicketOpened`, `InterventionClosed`, `Schedule`), condizioni (filtri semplici e soglie %), azioni (e-mail/PEC con modello, notifica in app, crea attività, imposta campo/stato, blocca con permesso, aggiungi a proposta riordino, genera documento collegato, esegui procedura, webhook). Log esecuzioni, prova su documento, disattivazione dopo N errori.
|
||
- **Procedure** (073, `ProcedureCatalog`): fatturazione differita, contabilizzazione batch, generazione scadenze, solleciti, stampa/invio massivo, proposta riordino, aggiornamento listini, liquidazione IVA, ammortamenti, ratei/risconti, chiusura esercizio (passi), ricostruzioni, import inbox e canali SDI, cambi, export commercialista, pulizie; tutte idempotenti, con log, eseguibili a mano, da regola o da attività programmata.
|
||
- **Preferenze** a tre livelli: utente (tema, accento, densità, menu, pagina iniziale e dashboard, layout griglie, filtri salvati, scorciatoie, notifiche), azienda (numerazioni, codici, default documenti, arrotondamenti, controlli, modelli e-mail, testi di stampa, periodicità IVA), sistema (sicurezza, backup, retention, SMTP/PEC, cloud, licenze).
|
||
|
||
### 11.13 Report (`Reports`, CORE/REPORT) — mockup 071
|
||
`ReportDefinition` (parametri, query per dialetto, colonne, totali, raggruppamenti) resa con `KhGrid` + grafico, export CSV/XLSX/PDF, stampa, **pianificazione come attività programmata** (invio e-mail, salvataggio come allegato). Catalogo minimo: tutti i report citati nei moduli + ABC, statistiche per periodo, registro DDT, fatture per registro IVA, margini (REPORT), provvigioni, report CRM, report servizi, export per il commercialista.
|
||
|
||
---
|
||
|
||
## 12. Amministrazione (account di istanza) — mockup 078–089
|
||
|
||
1. **Istanza e database** (078, 079; super utente per le azioni distruttive): elenco dei database (sistema e aziende) con motore, dimensione, stato schema, ultimo backup, stato (*attiva/manutenzione/sola lettura/disattivata*); **nuova azienda** (CREATE DATABASE sul server configurato o file SQLite, migrazioni, tabelle di base, licenza MULTI richiesta oltre la prima); **collega database esistente** (connection string); **clona** (ambiente di prova da un backup, nome `khaemhat_<codice>_test`); **elimina** (solo super utente: backup automatico preventivo, conferma scrivendo il nome, cestino 30 giorni del file di backup); applica migrazioni; manutenzione per database (`VACUUM ANALYZE`, `REINDEX`, `integrity_check`); verifica integrità; ricostruzioni; statistiche tabelle; modalità manutenzione per azienda (utenti disconnessi, API 503); informazioni sul server PostgreSQL (versione, ruolo, connessioni, spazio, estensioni) con avviso se la versione è inferiore alla minima (16).
|
||
2. **Licenze e moduli** (080, §8).
|
||
3. **Utenti** (081): account di istanza (amministratori, solo super utente) e utenti di ogni azienda; livello, ambito (istanza/azienda), ruoli, flag, sessioni, scadenza, reset password, invito, 2FA, utenti tecnici per API.
|
||
4. **Ruoli e permessi** (082): matrice, cloni, override per utente, confronto, "chi ha questo permesso".
|
||
5. **Attività programmate** (083): tipi *backup*, *procedura* (dal catalogo, con parametri), *report via e-mail*, *notifica*, *import/export*, *verifica*, *script di manutenzione* (dal catalogo interno, mai shell libera); azienda, esegui come, preset di pianificazione o cron, fuso orario, timeout, retry, notifiche; storico con durata, esito, log; esegui ora, sospendi, duplica.
|
||
6. **Backup e ripristino** (079, §13).
|
||
7. **Log** (084, §9.5).
|
||
8. **Stato sistema** (085): stato, latenza DB, Redis, spazio disco, memoria, utenti collegati, controlli (migrazioni per database, licenza, SMTP, canali SDI, scheduler, backup, integrità, disco), versione/commit/immagine, **controllo aggiornamenti** su GHCR (nessun aggiornamento automatico; link alle note di rilascio), diagnostica scaricabile (zip con log, versioni, configurazione senza segreti).
|
||
9. **Impostazioni** (086, 087): SMTP con prova, PEC, sicurezza (password, 2FA per livello, sessioni, rate limit, upload, CSP), archiviazione e cloud (volume, S3 compatibile, WebDAV, retention copie remote), cache/Redis, notifiche, rete/URL, retention log; **rotazione di `KHAEMHAT_SECRET_KEY`** guidata (ri-cifra i segreti con la nuova chiave fornita via env `KHAEMHAT_SECRET_KEY_NEW`, poi si rimuove la vecchia).
|
||
10. **Chiavi API, MCP e webhook** (088).
|
||
11. **Dati di base e di esempio** (089): pacchetti dati con versione, *Aggiorna tabelle di base* (idempotente), *Carica dati di esempio* (solo azienda senza documenti reali), *Rimuovi dati di esempio* (super utente).
|
||
12. **Import/Export** (077): procedura guidata CSV/XLSX/JSON per anagrafiche, articoli, listini, giacenze iniziali, piano dei conti, saldi iniziali e partite di apertura; mappatura colonne, anteprima, validazione, report errori.
|
||
|
||
Ogni utente ha **Il mio profilo** (008): dati, password, 2FA, sessioni, tema/accento/densità/menu, pagina iniziale e dashboard, layout salvati, notifiche.
|
||
|
||
---
|
||
|
||
## 13. Backup e ripristino (integrati; per ogni database)
|
||
|
||
- **PostgreSQL**: l'immagine include `postgresql-client-17` (`pg_dump` deve essere ≥ versione del server: server 16 o 17; per 18 aggiornare l'immagine). `PgDumpRunner` esegue `pg_dump -Fc --no-owner --no-privileges` verso `/data/backups/<db>/bk-<db>-<timestamp>.dump` in streaming, con `sha256`, cifratura AES-256-GCM (chiave da `KHAEMHAT_SECRET_KEY`) e copie remote su **S3 compatibile** (`S3Client` SigV4 in casa, multipart) e **WebDAV** (NAS/cloud personali). Verifica con `pg_restore --list`. Allegati dell'azienda inclusi come tar.
|
||
- **SQLite**: `VACUUM INTO` (copia consistente) + stessa pipeline. **Backup logico** portabile (JSON Lines per tabella + manifest): indipendente dal motore, per migrare SQLite → PostgreSQL e per disaster recovery.
|
||
- **Politica** per database o per istanza (`sys_backup_policies`): pianificazione, retention giornalieri/settimanali/mensili (GFS), destinazioni, cifratura, verifica, notifica errori, avviso se l'ultimo backup riuscito è più vecchio di N ore; il database di sistema è sempre incluso.
|
||
- **Ripristino** (`PgRestoreRunner`): (1) manutenzione per l'azienda, (2) backup di sicurezza dello stato corrente, (3) ripristino in `khaemhat_restore_<ts>` con `pg_restore -Fc --no-owner`, (4) controllo versione schema e migrazioni mancanti, (5) verifica integrità, (6) scambio atomico (rinomina; richiede proprietà del database e `CREATEDB`; in alternativa ripristino in-place con `--clean --if-exists` dopo terminazione delle connessioni), (7) fine manutenzione, log e audit. Avviato da un amministratore, **confermato dal super utente** (notifica + TOTP). *Prova di ripristino* su database temporaneo senza scambio. Ripristino da backup logico su database vuoto. Ripristino del database di sistema solo da CLI (`scripts/restore-system.sh`) con l'istanza ferma.
|
||
- Documentazione in `docs/wiki/Backup-e-ripristino.md` con la procedura manuale equivalente (`docker exec … pg_dump`) e la strategia consigliata (backup app + snapshot volume Unraid/EBS).
|
||
|
||
---
|
||
|
||
## 14. Dati di base e dati di esempio (`Seeding`)
|
||
|
||
- `ISeeder { Module; SeedKind (Base|Demo); Order; RunAsync(SeedContext) }`; dati in C# o CSV incorporati (`EmbeddedResource`); versione del pacchetto dati (`IT 2026.2`) in `settings`.
|
||
- **Base**: paesi ISO; province e comuni (CAP, codice catastale); valute; UM; **codici IVA** con nature (22, 10, 5, 4, ESE10 N4, NI8 N3.1, NI41 N3.2, NI71 N3.3, NI8C N3.5, FC7 N2.1, fuori campo altre N2.2, ESC15 N1, RC17 N6.x, SPLIT, NS, indetraibili 50%/100%, forfettari); `MP01–MP23`; condizioni di pagamento; causali magazzino; depositi; trasporti; categorie; numeratori; **piano dei conti standard PMI** con voci CEE; **causali contabili**; registri IVA; **categorie cespiti** con coefficienti; **codici tributo F24**; code list SDI; regime RF01; tipi documento; pipeline e fasi CRM; modelli e-mail; ruoli; regole di automazione predefinite; attività programmate di sistema; tabella ABI/CAB.
|
||
- **Demo** (solo azienda vuota, righe `is_demo`): "Khaemhat Demo S.r.l." con dati **fittizi** (mai nomi di aziende, banche, marchi o prodotti reali): 3 depositi, 2 listini, 40 clienti (aziende, PA con split, privati, UE, extra-UE, forfettario, con dichiarazione d'intento, bloccato per fido), 15 fornitori (professionista con ritenuta, agente ENASARCO, estero per TD17/TD18), 120 articoli, 3 agenti, 5 vettori, 12 mesi di documenti coerenti (ordini → DDT → differite, immediate, accompagnatorie, NC, pro-forma, parcelle, ordini fornitore → carichi → fatture acquisto, autofatture, inventario, movimenti, trasferimenti), **contabilità completa** (registrazioni da documenti, incassi/pagamenti parziali, insoluto RiBa, giroconti, liquidazioni confermate fino al mese precedente, ritenute, 58 cespiti con ammortamenti, esercizio precedente chiuso con bilancio), XML SDI con stati diversi e notifiche, estratto conto da riconciliare, CRM (23 lead, 18 opportunità, attività, 3 campagne, 2 ticket), 2 contratti di servizio con interventi, 1 canale generico con ordini, allegati e file generati di esempio, utenti demo per ogni ruolo (password mostrata nella pagina admin), voci di log di esempio in tutte le sezioni.
|
||
- Il seeder demo usa i motori (documenti, contabile) e diventa un test end-to-end: `Khaemhat.Application.Tests` esegue base+demo su SQLite e verifica quadrature (giacenze = movimenti; partite = scadenze − incassi; totali documento = righe + castelletto; ogni registrazione quadra; saldi partitari = partite aperte; bilancio di verifica a zero).
|
||
|
||
---
|
||
|
||
## 15. REST API e MCP (modulo API) — mockup 088
|
||
|
||
- `/api/v1/{modulo}/{risorsa}` JSON `camelCase`, API key (`Authorization: Bearer kh_…`) o cookie; header `X-Company`; paginazione `?page&pageSize&sort&filter`; errori RFC 9457 con `trace_id`; ETag/`If-Match`; idempotenza (`Idempotency-Key`); rate limiting per chiave. Risorse: parties, items, price-lists, sale-orders, delivery-notes, invoices, purchase-orders, purchase-invoices, inventory/balances, inventory/entries, ledger/accounts, ledger/entries, open-items, payments, e-invoices, attachments (`GET` download, `POST` upload su un documento), crm/leads, crm/opportunities, crm/activities, channels/{code}/orders, reports/{code}, admin/status (sola lettura). OpenAPI 3.1 generato in-house su `/api/v1/openapi.json` + pagina `/api/docs`.
|
||
- **MCP** (Streamable HTTP, JSON-RPC 2.0) su `/mcp` con API key: `initialize`, `tools/list`, `tools/call`, `ping`; tool in lettura `search_parties`, `get_party`, `search_items`, `get_item_stock`, `get_document`, `list_documents`, `get_open_items`, `sales_summary`, `get_account_balance`, `trial_balance`, `vat_settlement_preview`, `crm_pipeline_summary`, `get_log_errors` (amministratori); in scrittura opzionali per chiave: `create_sale_order`, `create_party`, `create_crm_activity`. Documentazione in `docs/wiki/MCP.md`.
|
||
- Webhook in uscita (eventi delle automazioni) con firma HMAC e retry.
|
||
|
||
---
|
||
|
||
## 16. Docker, CI su GitHub, GHCR, Unraid, icona
|
||
|
||
### 16.1 Dockerfile
|
||
Stage `build`: `mcr.microsoft.com/dotnet/sdk:10.0` → restore con cache, `scripts/check-packages.sh`, test opzionali (`--build-arg RUN_TESTS=true`), `dotnet publish src/Khaemhat.Web -c Release -o /app /p:Version=$VERSION /p:SourceRevisionId=$GIT_SHA`. Stage `runtime`: `mcr.microsoft.com/dotnet/aspnet:10.0` + `postgresql-client-17 curl tzdata` (repository PGDG) + utente `app` non root con `PUID/PGID`; `VOLUME /data`; `EXPOSE 8080`; `HEALTHCHECK CMD curl -fs http://localhost:8080/health/live || exit 1`; `ENTRYPOINT ["/app/entrypoint.sh"]`. Etichette OCI (`org.opencontainers.image.*`) e **`net.unraid.docker.icon`**, **`net.unraid.docker.webui="http://[IP]:[PORT:8080]/"`**. Architetture: `linux/amd64` di default; `linux/arm64` con `publish-image.sh --arm64`.
|
||
|
||
### 16.2 Compose e template (`deploy/`, Appendice C)
|
||
`docker-compose.yml` (app + `postgres:17` + `redis:7` profilo), `docker-compose.sqlite.yml` (demo), **`docker-compose.unraid.yml`** (etichette `net.unraid.docker.managed/webui/icon`, volumi in `/mnt/user/appdata/khaemhat`, `PUID 99`/`PGID 100`), **`unraid/khaemhat.xml`** (template Community Applications con `<Icon>`, `<WebUI>`, porte, volumi, variabili mascherate). L'icona dei template deve essere raggiungibile senza autenticazione: `https://raw.githubusercontent.com/<owner>/khaemhat-assets/main/icon-256.png` (repository pubblico `khaemhat-assets`, anche se il repository principale è privato).
|
||
|
||
### 16.3 GitHub con minuti di CI contati
|
||
- Remote `origin` = GitHub (`GITHUB_REPO_URL` fornito dall'utente); `git init -b main`, Conventional Commits, tag `vX.Y.Z` a ogni milestone, `CHANGELOG.md` (Keep a Changelog); note di rilascio dal CHANGELOG.
|
||
- **Il rilascio normale non usa Actions**: `scripts/publish-image.sh` costruisce in locale (`docker buildx build`) e fa push su **GHCR** (`ghcr.io/<owner>/khaemhat:<versione>` e `:latest`) con un token `write:packages`; lo script tagga anche il repository e aggiorna il CHANGELOG. Da Unraid si tira l'immagine con `docker login ghcr.io` (token `read:packages`) se il package è privato.
|
||
- `.github/workflows/ci.yml`: **solo** `pull_request` verso `main` e `push` di tag; `paths-ignore: ["docs/**", "*.md", "assets/**", "deploy/**"]`; un solo job su `ubuntu-latest`; cache NuGet (`actions/cache` sulla cartella `~/.nuget/packages` con chiave da `Directory.Packages.props`); `dotnet build -warnaserror` + test su SQLite; PostgreSQL come `services:` solo quando il tag inizia con `v`; `timeout-minutes: 15`; `concurrency` con cancellazione delle esecuzioni superate. Niente matrix, niente esecuzione su ogni push di branch.
|
||
- `.github/workflows/release.yml`: solo `workflow_dispatch` (facoltativo, per chi non può costruire in locale): build + push su GHCR `linux/amd64`; arm64 opzionale via input.
|
||
- `.github/workflows/wiki.yml`: su `push` a `main` con `paths: ["docs/wiki/**"]`: clona `<repo>.wiki.git`, sincronizza, commit e push (durata sotto il minuto). In alternativa `scripts/publish-wiki.sh` da locale.
|
||
- `docs/DEPLOY.md` e wiki *Installazione*: host Docker generico (VPS, istanza cloud), un progetto compose per istanza (più aziende dentro), reverse proxy TLS a scelta dell'installatore, dimensionamento, backup (app + `pg_dump` host + snapshot), aggiornamento (`docker compose pull && up -d` su tag esplicito, mai `latest` in produzione), rollback (tag precedente + ripristino backup se le migrazioni sono cambiate), rotazione segreti.
|
||
|
||
### 16.4 Unraid
|
||
`docs/wiki/Installazione-Unraid.md`: rete docker personalizzata (`khaemhat-net`), container PostgreSQL dal template ufficiale o dal compose, template CA importato o compose con il plugin di gestione compose, cartelle `appdata`, `PUID/PGID` 99/100, reverse proxy e TLS, backup (plugin di backup appdata + backup applicativo), aggiornamento dall'icona del container (tag esplicito), icona e WebUI dalle etichette.
|
||
|
||
### 16.5 Versione nel prodotto
|
||
La versione SemVer (`major.minor.patch`, con `+sha`) compare: nella barra superiore (solo `major.minor` accanto al nome), nella barra di stato (completa), in *Stato sistema*, nel `manifest.webmanifest`, nelle etichette OCI e nell'**icona versionata** (§16.6) generata al build per la versione `major.minor`.
|
||
|
||
### 16.6 Icona
|
||
`assets/icon.svg` è l'icona ufficiale: quattro tessere dorate su fondo blu notte, ognuna con un glifo di una funzione del gestionale — **documento con €** (vendite/fatture), **collo** (magazzino), **istogramma con trend** (contabilità/analisi), **persone** (CRM/anagrafiche). Varianti fornite: `icon-v1.0.svg` con la fascia dorata "v 1.0" in basso (le tessere sono ridotte per far posto al numero), `icon-mono.svg` (solo tessere, per favicon 16–32 px), PNG 16–512, `favicon.ico`. Regole: la variante versionata mostra solo `major.minor`; `scripts/build.sh` rigenera `icon-v<major.minor>.svg/png` sostituendo il testo nel template SVG (nessuna libreria: è una sostituzione di stringa) e l'immagine Docker usa quella versionata come `net.unraid.docker.icon` quando pubblicata in `khaemhat-assets` (`icon-v1.0-256.png`), altrimenti quella semplice. Usala per favicon, manifest PWA, marca nella barra, pagina di accesso, e-mail. Sorgente SVG in Appendice B; colori `--kh-brand` (#C8962E/#E0B04A) e `--kh-topbar` (#17243A) sono quelli di `tokens.css`.
|
||
|
||
---
|
||
|
||
## 17. Documentazione (wiki) — obbligatoria e sempre aggiornata
|
||
|
||
- **Sorgente di verità: `docs/wiki/`** nel repository, pubblicata nel **wiki del repository GitHub** (`<repo>.wiki.git`) da `wiki.yml` o `publish-wiki.sh`. Convenzioni: `Home.md`, `_Sidebar.md`, `_Footer.md`, link `[Pagina](Nome-Pagina)`, immagini in `docs/wiki/img/` (gli screenshot reali sostituiscono progressivamente i mockup), stato in testa (`bozza/completa/da aggiornare`), ultima revisione e versione software.
|
||
- Struttura: Installazione (Unraid, Docker/cloud, Aggiornamento, Backup e ripristino), Primi passi, Guida utente per modulo (Interfaccia e scorciatoie, Dashboard, Anagrafiche, Articoli e listini, Vendite, Acquisti, Magazzino, Contabilità, IVA, Cespiti, Scadenzario, Fatturazione elettronica e canali SDI, CRM, Servizi, Canali, Report, Automazioni, Allegati e file), Amministrazione (Istanza e database, Licenze e moduli, Utenti e permessi, Attività programmate, Backup, Log, Impostazioni, API e MCP), Riferimenti (Fiscalità italiana: TD/nature/MP/RF/tributi/scadenze; API; MCP; Glossario; FAQ), Sviluppo (Architettura, Modello dati, Design UI, Contribuire, Changelog).
|
||
- **Aiuto in app** (011): F1 e "?" aprono la pagina wiki della maschera (`HelpLink` per pagina; URL base configurabile; copia della wiki servita su `/help` per installazioni offline).
|
||
- **Regole di aggiornamento** (parte della Definition of Done §20): ogni milestone porta le pagine dei moduli consegnati da *bozza* a *completa*; ogni modifica funzionale, di schema o di API aggiorna wiki + `docs/DATA-MODEL.md`/`docs/API.md` + `CHANGELOG.md` nello **stesso commit**; ogni cambiamento visivo aggiorna screenshot e `Design-UI.md`; decisioni negli ADR; `docs/STATUS.md` a fine sessione.
|
||
- Documentazione tecnica in `docs/`: `ARCHITECTURE.md`, `DATA-MODEL.md` (generato da `scripts/gen-datamodel.sh`), `MODULES.md`, `API.md`, `MCP.md`, `DEPLOY.md`, `DEVELOPMENT.md`, `SECURITY.md`, `STATUS.md`, `adr/`.
|
||
|
||
---
|
||
|
||
## 18. Test e verifica
|
||
|
||
- `scripts/test.sh` verde a ogni milestone: unit (`Core`), dialetti/migrazioni (`Data`, SQLite + PostgreSQL con `KHAEMHAT_TEST_PG`), infrastruttura (RESP, IMAP contro un server fittizio in-process, PDF, XLSX, backup/ripristino SQLite, S3 SigV4 su vettori noti, WebDAV contro server fittizio), `Fiscal.Italy` (FatturaPA writer vs golden file + round-trip, validator con scarti noti 00311/00423/00327, LIPE, F24, Intrastat), licenze (codici test accettati solo in modalità test; firma ECDSA), applicazione (flussi documentali, autofattura TD17, incasso con abbuono, insoluto, liquidazione che blocca il periodo, chiusura esercizio completa su demo, seed base+demo con quadrature, permessi per livello, multi-azienda con due database, allegati e generazione file, log per sezione, concorrenza ottimistica, automazioni), web (login/livelli, cookie, API key, health, MCP handshake, menu compresso e dashboard persistite).
|
||
- Test di architettura: dipendenze tra progetti, nessun `PackageReference` fuori allowlist, nessun testo UI hard-coded, nessun accesso al pacchetto fiscale fuori dalle interfacce, nessun `Process.Start` fuori da `Infrastructure/Backup`.
|
||
- Checklist manuale per milestone in `docs/DEVELOPMENT.md` con `docker compose -f deploy/docker-compose.sqlite.yml up`: login super utente e cambio password, creazione amministratore e seconda azienda, utente standard, tema scuro + accento, menu compresso, dashboard personalizzata, carica base/demo, fattura → PDF allegato → XML, prima nota, liquidazione, backup → prova di ripristino, attività programmata, log con filtro.
|
||
- Prestazioni con demo ×10: radar < 300 ms/pagina su PostgreSQL, salvataggio fattura 50 righe con contabilizzazione < 700 ms, liquidazione mensile < 5 s, bilancio di verifica su 2 M righe < 10 s, ricostruzione giacenze 100k movimenti < 60 s, backup 2 GB < 5 min, pagina log con 1 M righe < 1 s per filtro.
|
||
|
||
---
|
||
|
||
## 19. Regole di codice
|
||
|
||
`record` per DTO/value object, `sealed` di default, `decimal` per importi e quantità (mai `double`), `DateOnly`/`DateTime` UTC con conversione a `Europe/Rome` solo in presentazione; async con `CancellationToken`; `Result<T>` per gli esiti attesi ed eccezioni di dominio localizzabili; validazione in `Core`/`Application` (l'UI mostra, non decide); niente logica in `.razor` (code-behind + servizi); ogni servizio applicativo è transazionale per operazione; motore documenti e contabile garantiscono atomicità documento + magazzino + partite + registrazione + numerazione + allegati; ogni modulo logga nella propria sezione con `trace_id`; commenti solo per i *perché*; XML doc sui tipi pubblici di `Core`, `Data`, `Fiscal.Abstractions`; ogni file appartiene a un modulo; nessuna cartella "Utils".
|
||
|
||
---
|
||
|
||
## 20. Piano di esecuzione (milestone) e Definition of Done
|
||
|
||
| # | Milestone | Contenuto | Tag |
|
||
|---|---|---|---|
|
||
| 0 | Bootstrap | Soluzione, progetti, `Directory.*.props`, allowlist + `check-packages.sh`, copia di `assets/`, `deploy/`, `docs/mockups/`, `docs/wiki/`; Dockerfile e compose con pagina "in costruzione" e favicon; `/health`; `ci.yml`, `wiki.yml`, `release.yml`; `publish-image.sh`; README; ADR 0001–0008 (stack, no-external-libs, Blazor Server, micro-ORM, multi-DB, sistema+aziende, pacchetto fiscale, licenze a moduli) | `v0.0.1` |
|
||
| 1 | Strato dati | `Khaemhat.Data`, provider SQLite/PostgreSQL, migrazioni (sistema e azienda), query builder, registry database, segreti cifrati, test | `v0.1.0` |
|
||
| 2 | Sistema e sicurezza | DB di sistema, super utente dal container, amministratori, aziende (crea/collega), utenti per azienda, ruoli/permessi, login/2FA, sessioni, **licenze e moduli con codici test**, DataProtection su DB, cache memoria+Redis, scheduler base, **log avanzato per sezioni**, audit, notifiche | `v0.2.0` |
|
||
| 3 | Framework UI | Layout con menu comprimibile, TabHost, libreria `Kh*` dai mockup, toolbar a icone, intestazione documento e gruppi di campi, temi/accenti/densità, preferenze, **dashboard a widget personalizzabile e disattivabile**, localizzazione, radar, ricerca globale, scorciatoie, aiuto F1, stampa HTML/PDF di prova, **allegati e generazione file** sul primo documento | `v0.3.0` |
|
||
| 4 | Tabelle, anagrafiche, articoli | Company, pacchetto `Fiscal.Italy` (codici IVA, nature, code list, comuni), Parties, Items, listini, codici automatici, VIES, import/export (incl. piano dei conti CSV/XLSX/JSON), seed base | `v0.4.0` |
|
||
| 5 | Motore documenti e Vendite | Numeratori, totali, scadenze, flussi, stampe, allegati per documento; preventivi, ordini, DDT, fatture (tutti i TD), parcelle, NC/ND, pro-forma, differita | `v0.5.0` |
|
||
| 6 | Acquisti e Magazzino | Ordini/carichi/fatture fornitore con protocollo, import XML/P7M, autofatture TD16–TD29, movimenti, giacenze, inventario, riordino, ricostruzioni | `v0.6.0` |
|
||
| 7 | Contabilità generale | Piano dei conti (precaricato + import), causali, prima nota, contabilizzazione automatica, partitari, registri IVA, liquidazione + F24 + LIPE, bollo, ritenute, bilancio di verifica | `v0.7.0` |
|
||
| 8 | Scadenzario e tesoreria | Partite, incassi/pagamenti, abbuoni, insoluti, RiBa/SDD/SEPA, riconciliazione, solleciti, flusso di cassa | `v0.8.0` |
|
||
| 9 | Fatturazione elettronica | FatturaPA writer/validator/reader, notifiche, **canale PEC integrato (SMTP + IMAP in casa)**, SdICoop, connettori intermediari A e B, cruscotto, instradamento, conservazione export, inbox; seed demo completo | `v0.9.0` |
|
||
| 10 | Cespiti, Intrastat, chiusura, bilancio | Registro cespiti, Intrastat, dichiarazioni d'intento, ratei/risconti, chiusura/apertura, libri definitivi, bilancio CEE e riclassificati, export commercialista | `v0.10.0` |
|
||
| 11 | CRM | Lead, pipeline, attività e agenda, campagne, ticket, scheda 360°, dashboard CRM, import lead API | `v0.11.0` |
|
||
| 12 | Amministrazione, automazioni, API | Istanza e database (clona/elimina/manutenzione), attività programmate da UI, **backup/ripristino PostgreSQL + logico + S3 + WebDAV**, impostazioni e rotazione segreti, stato sistema e aggiornamenti GHCR, chiavi API, REST+OpenAPI, MCP, webhook, regole/procedure, import saldi/partite | `v0.12.0` |
|
||
| 13 | Consolidamento e rilascio | Hardening, prestazioni, accessibilità, wiki completa, `publish-image.sh` e prima immagine su GHCR, template Unraid verificato, icona versionata, PWA | `v1.0.0` |
|
||
| 14 | Fase 2 | Servizi (contratti/interventi), Canali e-commerce (generico + primi connettori), EN 16931/Peppol, XBRL, regime del margine, ventilazione corrispettivi, IVA per cassa completa, SFTP per backup | `v1.1.0`+ |
|
||
|
||
**Definition of Done per milestone:** compila senza warning; `check-packages.sh` e `test.sh` verdi su SQLite (e PostgreSQL se disponibile); maschere raggiungibili dal menu, protette da permessi e licenza, localizzate, coerenti con i mockup (toolbar a icone, intestazione documento, gruppi di campi); migrazioni da zero e idempotenti; seed base e demo estesi; log per sezione dei nuovi moduli; **wiki delle funzioni consegnate completa** e `docs/*.md` aggiornati; `CHANGELOG.md`; commit e tag; l'immagine si costruisce in locale e la demo SQLite parte da zero.
|
||
|
||
---
|
||
|
||
## 21. Elenco delle classi principali
|
||
|
||
### `Khaemhat.Core`
|
||
`Entity<TKey>`, `IEntity<TKey>`, `IAuditable`, `IDemoMarkable`, `Result`, `Result<T>`, `Error`, `DomainException`, `ConcurrencyException`, `ModuleNotLicensedException`, `Money`, `Quantity`, `Percentage`, `DiscountFormula`, `IClock`, `SystemClock`, `ICurrentUser`, `ICompanyContext`, `IEventBus`, `DomainEvent`, `Guard`.
|
||
Entità azienda/tabelle: `CompanyProfile`, `FiscalYear`, `FiscalPeriod`, `Country`, `Province`, `Municipality`, `Currency`, `ExchangeRate`, `UnitOfMeasure`, `TaxCode`, `PaymentMethod`, `PaymentTerm(+Line)`, `BankAccount`, `Salesperson`, `Carrier`, `ShippingTerm`, `TransportMean`, `GoodsAppearance`, `DeliveryTerm`, `TransportReason`, `DocumentNumerator`, `InventoryReason`, `Warehouse`, `ItemCategory`, `PartyCategory`, `PriceList`, `DiscountPolicy`, `DocumentType`, `CostCenter`, `Job`, `CodeSequence`, `CodeRule`.
|
||
Anagrafiche/articoli: `Party`, `PartyAddress`, `PartyContact`, `PartyBankAccount`, `PartySalesTerms`, `PartyPurchaseTerms`, `PartyFiscal`, `PartyItemCode`, `IntentDeclaration`; `Item`, `ItemUom`, `ItemBarcode`, `ItemPrice`, `ItemSupplier`, `ItemSubstitute`.
|
||
Documenti: `SaleQuotation(+Line,+Revision)`, `SaleOrder(+Line)`, `SaleDocument(+Line,+TaxSummary,+Installment)`, `PurchaseOrder(+Line)`, `PurchaseDocument(+Line,+TaxSummary,+Installment)`, `InventoryDocument(+Line)`, `DocumentLink`, `InventoryEntry(+Line)`, `ItemBalance`, `StockTake(+Line)`, `Attachment`.
|
||
Contabilità: `GlAccount`, `JournalTemplate(+Line)`, `GlEntry`, `GlEntryLine`, `GlEntryVat`, `VatRegister`, `VatSettlement(+Line)`, `StampDutyEntry`, `WithholdingTax`, `SocialSecurityCharge`, `FixedAsset`, `FixedAssetCategory`, `FixedAssetMovement`, `IntrastatDeclaration(+Line)`, `AccrualDeferral`, `ClosingRun(+Step)`, `FinancialStatementLine`, `RecurringEntryTemplate`.
|
||
Finanza: `OpenItem`, `Payment(+Line)`, `Remittance(+Line)`, `SddMandate`, `BankStatement(+Line)`, `BankMatchRule`, `DunningRun(+Line)`, `DunningLevel`.
|
||
E-invoicing: `EInvoice`, `SdiNotification`, `EInvoiceInboxFile`, `SdiChannel`, `SdiRoutingRule`, `ConservationPackage`.
|
||
CRM/Servizi/Canali: `Lead`, `Pipeline`, `PipelineStage`, `Opportunity`, `CrmActivity`, `Campaign(+Member)`, `Ticket`, `EmailTemplate`, `Segment`; `ServiceContract(+Line)`, `ServiceTeam`, `ServiceTechnician`, `ServiceIntervention(+Line)`; `SalesChannel`, `ChannelItem`, `ChannelOrder`, `ChannelCustomer`.
|
||
Azienda (utenti): `User` (`Kind`), `Role`, `Permission`, `RolePermission`, `UserRole`, `UserPermissionOverride`, `UserSession`, `UserSetting`, `ApiKey`, `Notification`, `AuditEntry`, `DashboardLayout`, `AutomationRule`, `AutomationRun`, `Webhook`.
|
||
Sistema: `Company` (registry), `SystemUser` (`Level`), `License`, `LicenseActivation`, `SystemSetting`, `DataProtectionKey`, `LogEntry` (con `Section`), `SecurityAuditEntry`, `ScheduledTask`, `JobRun`, `BackupSet`, `BackupPolicy`, `SystemNotification`, `SystemSession`, `LoginAttempt`.
|
||
Enum: `DbEngine`, `DatabaseScope`, `UserLevel` (SuperUser/Administrator/Standard), `UserKind`, `CompanyStatus`, `ModuleCode`, `LicenseMode`, `PartyKind`, `PartyType`, `ItemType`, `DocumentKind`, `DocumentStatus`, `EInvoiceStatus`, `SdiChannelKind` (Pec, SdiCoop, IntermediaryA, IntermediaryB), `LineType`, `TaxNature`, `TaxExigibility`, `VatRegisterType`, `EntryStatus`, `AccountNature`, `AccountKind`, `OpenItemStatus`, `RemittanceKind`, `AssetMovementKind`, `LeadStatus`, `ActivityKind`, `TicketStatus`, `AttachmentKind`, `LogSection`, `SeedKind`, `ThemeMode`, `AccentColor`, `Density`, `MenuState`, `AutomationTrigger`, `AutomationActionKind`, `BackupKind`, `BackupStatus`, `BackupTarget` (Local, S3, WebDav).
|
||
Regole: `DocumentTotalsCalculator`, `TaxSummaryBuilder`, `InstallmentGenerator`, `StampDutyRule`, `WithholdingCalculator`, `SocialSecurityCalculator`, `PriceResolver`, `DiscountResolver`, `StockEffectMatrix`, `UomConverter`, `NumberFormatter`, `DocumentNumberFormat`, `CodeMaskFormatter`, `JournalPostingRules`, `VatSettlementCalculator`, `ProRataCalculator`, `DepreciationCalculator`, `AccrualDeferralCalculator`, `ExchangeDifferenceCalculator`, `AgingCalculator`, `LeadScoring`, `DunningRules`, `BankMatcher`, `TodoAggregator` (widget *Da fare*), `DoneAggregator` (widget *Fatto oggi*), `DeadlineAggregator`.
|
||
Validatori: `ItalianVatNumberValidator`, `FiscalCodeValidator` (+ `FiscalCodeCalculator`), `IbanValidator`, `EanValidator`, `SdiRecipientCodeValidator`, `EmailValidator`, `JournalEntryValidator`, `ChartOfAccountsImportValidator`, `Validator<T>`, `ValidationResult`.
|
||
|
||
### `Khaemhat.Fiscal.Abstractions` / `Khaemhat.Fiscal.Italy`
|
||
`IFiscalPack`, `ITaxEngine`, `ITaxCodeCatalog`, `IEInvoiceFormat`, `IEInvoiceNotificationReader`, `ISdiTransport`, `IFiscalReports`, `IFiscalCalendar`, `IWithholdingRules`, `IFixedAssetRules`, `IFinancialStatementsSchema`, `IChartOfAccountsTemplate`, `IIntrastatExporter`, `ITaxPaymentFormExporter`; `ItalyFiscalPack`, `ItalianTaxEngine`, `ItalianTaxCodeCatalog`, `VatNatures`, `ReverseChargeRules`, `SplitPaymentRules`, `CashVatRules`, `VatSettlementRules`, `VatAdvanceCalculator`, `LipeWriter`, `FatturaPaWriter`, `FatturaPaReader`, `FatturaPaValidator`, `FatturaPaDocument`, `FatturaPaCodeLists`, `SdiFileNaming`, `SdiNotificationParser`, `P7mExtractor`, `CadesVerifier`, `PecSdiTransport` (SMTP + IMAP), `SdiCoopTransport` (SOAP + certificato client), `IntermediaryATransport`, `IntermediaryBTransport`, `SdiRouter`, `WithholdingRulesIt`, `EnasarcoRules`, `CuExporter`, `F24Model`, `F24Codes`, `F24Exporter`, `IntrastatModel`, `IntrastatExporterIt`, `CombinedNomenclature`, `StampDutyRulesIt`, `FixedAssetRulesIt`, `MinisterialCoefficients`, `CeeSchema2424`, `CeeSchema2425`, `FinancialRatios`, `ItalianChartOfAccountsTemplate`, `ChartOfAccountsCsvFormat`, `ChartOfAccountsJsonFormat`, `MunicipalitiesDataset`, `AbiCabDataset`.
|
||
|
||
### `Khaemhat.Data` (+ provider) e `Khaemhat.Infrastructure`
|
||
`IDbProvider`, `ISqlDialect`, `ISchemaBuilder`, `IUnitOfWork(+Factory)`, `IRepository<,>`, `Repository<,>`, `ICompanyRegistry`, `CompanyRegistry`, `DatabaseScope`, `EntityMap<T>`, `ColumnMap`, `ColumnType`, `MapRegistry`, `QueryBuilder<T>`, `Query<T>`, `PagedResult<T>`, `SqlFragment`, `ExpressionTranslator`, `DbExecutor`, `ReaderMapper<T>`, `CommandCache`, `TransientRetryPolicy`, `IMigration`, `MigrationAttribute`, `MigrationRunner`, `MigrationCatalog` (System/Company), `SchemaVersionStore`, `TableDefinition`/`ColumnDefinition`/`IndexDefinition`/`ForeignKeyDefinition`, `DdlGenerator`, `SqliteProvider`/`Dialect`/`SchemaBuilder`/`WriteLock`/`DecimalConverter`, `PostgresProvider`/`Dialect`/`SchemaBuilder`/`DatabaseCreator`/`AdvisoryLocks`/`Partitioning`/`ServerInfo`;
|
||
`ICacheProvider`, `MemoryCacheProvider`, `RedisCacheProvider`, `RespClient`, `RespReader`, `RespWriter`, `RedisConnectionPool`, `RedisSubscriber`; `PasswordHasher`, `PasswordPolicy`, `TotpGenerator`, `SecureTokenGenerator`, `ApiKeyHasher`, `DataProtectionDbXmlRepository`, `SecretProtector` (AES-256-GCM con `KHAEMHAT_SECRET_KEY`), `SecretRotation`; `LicenseKey`, `LicenseDocument`, `LicenseVerifier`, `ModuleActivationCode`, `TestLicenseCatalog`, `ILicenseActivationService`, `OfflineActivationService`, `LicenseMonitor`; `IMailSender`, `SmtpMailSender`, `MailQueue`, `MailTemplateRenderer`, `ImapClient` (minimo: LOGIN, SELECT, SEARCH, FETCH, STORE, LOGOUT, TLS), `MimeParser`; `PdfWriter`, `PdfDocument`, `PdfPage`, `PdfFont`, `PdfTextLayout`, `PdfImage`, `PdfA3Embedder`; `CsvWriter`, `CsvReader`, `XlsxWriter`, `XlsxReader`, `ZipStreamWriter`; `IJobScheduler`, `JobRunner`, `JobDefinition`, `JobContext`, `CronExpression`, `JobLock`; `IFileStore`, `VolumeFileStore`, `StoredFile`, `AttachmentStore`, `GeneratedFileFactory`; `PgDumpRunner`, `PgRestoreRunner`, `SqliteBackup`, `LogicalBackupWriter`, `LogicalBackupReader`, `BackupEncryptor`, `S3Client`, `SigV4Signer`, `WebDavClient`, `RetentionPolicy`, `BackupVerifier`; `ViesClient`, `EcbRatesClient`, `GhcrPackagesClient`, `OutboundWebhookClient`; `McpServer`, `JsonRpc*`, `McpTool`, `McpToolRegistry`, `McpSchemaGenerator`; `DbLogSink`, `DbLoggerProvider`, `JsonConsoleFormatter`, `LogSectionScope`, `SlowQueryLogger`, `LogAlertRules`; `NotificationDispatcher`.
|
||
|
||
### `Khaemhat.Application`
|
||
`IModule`, `ModuleRegistry`, `ModuleInfo`, `MenuItem`, `PermissionDefinition`, `HelpLink`, `LicenseGate`; `DocumentDefinition(s)`, `DocumentService<,>`, `Sale*`/`Purchase*`/`Inventory*Service`, `DocumentFlowService`, `DocumentFlowWizard`, `FulfillmentCalculator`, `DocumentPostingService`, `InventoryPoster`, `InstallmentPoster`, `LedgerPoster`, `DocumentNumberingService`, `DocumentStateMachine`, `DocumentCopyService`, `DeferredInvoicingService`, `DocumentPrintService`, `IDocumentPrinter`, `HtmlDocumentPrinter`, `PdfDocumentPrinter`, `DocumentMailService`, `SelfInvoiceService`, `AttachmentService`, `FileGenerationService`; `JournalService`, `PostingEngine`, `PeriodLockService`, `LedgerQueries`, `PartitarioService`, `VatRegisterService`, `VatSettlementService`, `StampDutyService`, `WithholdingService`, `FixedAssetService`, `DepreciationService`, `IntrastatService`, `IntentDeclarationService`, `AccrualDeferralService`, `ClosingProcedure` (+ `ClosingStep`), `TrialBalanceService`, `FinancialStatementsService`, `RecurringEntriesService`, `ExchangeDifferenceService`, `ChartOfAccountsImportService`; `OpenItemService`, `PaymentService`, `RemittanceService`, `SddMandateService`, `BankStatementImportService`, `BankReconciliationService`, `DunningService`, `CashFlowForecastService`, `AgingReportService`; `EInvoiceService`, `EInvoiceExportService`, `SdiChannelService`, `SdiInboxService`, `SdiNotificationImportService`, `PurchaseInvoiceImportService`, `ConservationExportService`; `LeadService`, `OpportunityService`, `PipelineService`, `ActivityService`, `CampaignService`, `TicketService`, `Party360Service`, `CrmDashboardService`, `SalesForecastService`; `ContractService`, `InterventionService`, `InterventionSchedulingService`, `ServiceBillingService`; `IChannelConnector`, `GenericChannelConnector`, `ChannelOrderImportService`, `ChannelSyncService`; `ReportDefinition`, `ReportRunner`, `ReportCatalog`, `ScheduledReportService`; `DashboardService`, `WidgetCatalog`; `SystemUserService`, `UserService`, `RoleService`, `PermissionService`, `SessionService`, `LicenseService`, `ModuleActivationService`, `CompanyService` (crea/collega/clona/elimina/migra), `MaintenanceModeService`, `DatabaseMaintenanceService`, `IntegrityCheckService`, `RebuildService`, `ScheduledTaskService`, `BackupService`, `RestoreService`, `SystemSettingsService`, `SecretRotationService`, `LogQueryService`, `LogAlertService`, `SystemStatusService`, `UpdateCheckService`, `ApiKeyService`, `WebhookService`, `ImportWizardService`, `CsvImportMapper`, `OpeningBalancesImportService`; `CodeRuleService`, `CodeSequenceService`, `AutoFillService`, `RuleEngine`, `TriggerCatalog`, `ConditionEvaluator`, `ActionExecutor`, `ProcedureCatalog`, `IProcedure`, `ProcedureRunner`; `UserSettingsService`, `CompanySettingsService`; `ISeeder`, `SeedRunner`, `SeedContext`, `BaseDataSeeder`/`DemoDataSeeder` per area, `DemoDataRemover`; `GlobalSearchService`; `AuditTrailService`.
|
||
|
||
### `Khaemhat.Web`
|
||
`Program`, `KhaemhatOptions`, `EnvironmentConfigurationReader`, `StartupOrchestrator`, `HealthEndpoints`, `MetricsEndpoint`, `MaintenanceMiddleware`, `TraceIdMiddleware`; `CookieSessionAuthenticationHandler`, `ApiKeyAuthenticationHandler`, `SessionStore`, `CurrentUserAccessor`, `CompanyContextAccessor`, `PermissionAuthorizationHandler`, `RequirePermissionAttribute`, `RequireLevelAttribute`, `RequireModuleAttribute`, `LoginRateLimiter`, `SecurityHeadersMiddleware`, `ProblemDetailsMiddleware`; `<Modulo>Endpoints`, `AttachmentEndpoints`, `OpenApiWriter`, `ApiDocsPage`, `McpEndpoint`, `WebhookEndpoints`; componenti: `App`, `Routes`, `MainLayout`, `TopBar`, `CompanySwitcher`, `GlobalSearch`, `NotificationBell`, `UserMenu`, `KhSideMenu`, `KhTabHost`, `KhStatusBar`, `Dashboard` + `DashboardCustomizer` + widget (`KpiWidget`, `TodoWidget`, `DoneTodayWidget`, `DeadlinesWidget`, `FulfillmentWidget`, `RevenueChartWidget`, `CrmActivitiesWidget`, `PersonalNotesWidget`, `ShortcutsWidget`, …), tutti i `Kh*` (§10.7), `DocumentPage<,>`, `MasterDataPage<T>`, pagine per modulo (`PartyPage`, `SupplierPage`, `ItemPage`, `PriceListPage`, `QuotationPage`, `SaleOrderPage`, `DeliveryNotePage`, `SaleDocumentPage`, `CreditNotePage`, `DeferredInvoicingWizard`, `PurchaseOrderPage`, `GoodsReceiptPage`, `PurchaseDocumentPage`, `PurchaseInvoiceImportPage`, `SelfInvoicePage`, `InventoryBalancesPage`, `InventoryEntryPage`, `StockTakePage`, `ReorderProposalPage`, `JournalEntryPage`, `ChartOfAccountsPage`, `JournalTemplatesPage`, `PartitarioPage`, `VatRegistersPage`, `VatSettlementPage`, `WithholdingPage`, `FixedAssetsPage`, `IntrastatPage`, `ClosingWizard`, `FinancialStatementsPage`, `FiscalYearsPage`, `OpenItemsPage`, `PaymentDialog`, `RemittancePage`, `DunningPage`, `BankReconciliationPage`, `EInvoiceDashboard`, `SdiChannelsPage`, `StampDutyPage`, `IntentDeclarationsPage`, `CrmDashboard`, `LeadsPage`, `PipelineBoard`, `OpportunityPage`, `AgendaPage`, `TicketsPage`, `CampaignsPage`, `ServiceContractPage`, `ChannelOrdersPage`, `ReportPage`, `AutomationRulesPage`, `ProceduresPage`, `CompanyPreferencesPage`, `CompanyProfilePage`, `TaxCodesPage`, `Admin*Page` (Instance, Database, Licenses, Users, Roles, ScheduledTasks, Backup, Log, Status, Settings, Cloud, ApiKeys, Seed, Import), `ProfilePage`, `LoginPage`, `TwoFactorPage`, `ChangePasswordPage`, `HelpPage`, `PrintPreviewPage`, `AttachmentsDrawer`); `ITexts`, `JsonTextProvider`; `KeyboardShortcutService`, `ToastService`, `DialogService`, `DrawerService`, `TabService`, `PrintService`, `ThemeService`, `MenuStateService`, `HelpService`.
|
||
|
||
---
|
||
|
||
## 22. Glossario (UI italiana → identificatori)
|
||
|
||
| UI | Codice |
|
||
|---|---|
|
||
| Super utente / Amministratore / Utente | `UserLevel.SuperUser / Administrator / Standard` |
|
||
| Istanza / Azienda / Database di sistema | `Instance` / `Company` / `SystemDb` |
|
||
| Modulo / Licenza / Codice di attivazione | `Module` (`ModuleCode`) / `License` / `ActivationCode` |
|
||
| Cliente / Fornitore / Prospect / Lead | `Party` (`PartyKind`) / `Lead` |
|
||
| Destinazione, Articolo, Listino, Deposito, Giacenza/Impegnato/Ordinato/Disponibile | `PartyAddress`, `Item`, `PriceList`, `Warehouse`, `OnHand/Committed/OnOrder/Available` |
|
||
| Causale di magazzino / Movimento / Inventario fisico / Proposta di riordino | `InventoryReason` / `InventoryEntry` / `StockTake` / `ReorderProposal` |
|
||
| Preventivo / Ordine / DDT / Fattura / NC / ND / Pro-forma / Parcella / Autofattura | `SaleQuotation` / `SaleOrder` / `DeliveryNote` / `Invoice` / `CreditNote` / `DebitNote` / `ProFormaInvoice` / `FeeNote` / `SelfInvoice` |
|
||
| Ordine fornitore / DDT di carico / Fattura di acquisto / Protocollo | `PurchaseOrder` / `GoodsReceipt` / `PurchaseInvoice` / `ProtocolNumber` |
|
||
| Piano dei conti / Mastro-Conto-Sottoconto / Causale contabile / Prima nota / Registrazione | `ChartOfAccounts` / `GlAccount` (`AccountKind`) / `JournalTemplate` / `Journal` / `GlEntry` |
|
||
| Dare / Avere / Quadratura / Provvisoria / Definitiva / Storno | `Debit` / `Credit` / `Balanced` / `Provisional` / `Final` / `Reversal` |
|
||
| Registro IVA / Liquidazione / Esigibilità / Natura / Pro-rata / Acconto | `VatRegister` / `VatSettlement` / `TaxExigibility` / `TaxNature` / `ProRata` / `VatAdvance` |
|
||
| Ritenuta / Cassa previdenza / Bollo / Split payment / Reverse charge | `WithholdingTax` / `SocialSecurityCharge` / `StampDuty` / `SplitPayment` / `ReverseCharge` |
|
||
| Cespite / Ammortamento / Fondo / Dismissione | `FixedAsset` / `Depreciation` / `AccumulatedDepreciation` / `Disposal` |
|
||
| Esercizio / Periodo / Chiusura / Apertura / Libro giornale / Libro inventari | `FiscalYear` / `FiscalPeriod` / `Closing` / `Opening` / `GeneralJournal` / `InventoryBook` |
|
||
| Partita / Scadenza / Incasso / Pagamento / Insoluto / Abbuono / Distinta / Sollecito | `OpenItem` / `DueDate` / `Receipt` / `Disbursement` / `Unpaid` / `Allowance` / `Remittance` / `Dunning` |
|
||
| Fattura elettronica / SDI / Canale / Codice destinatario / Notifica | `EInvoice` / `Sdi` / `SdiChannel` / `RecipientCode` / `SdiNotification` |
|
||
| Opportunità / Fase / Attività / Campagna / Ticket | `Opportunity` / `PipelineStage` / `CrmActivity` / `Campaign` / `Ticket` |
|
||
| Allegato / File generato / Anteprima | `Attachment` / `GeneratedFile` / `Preview` |
|
||
| Attività programmata / Regola / Procedura / Backup / Copia remota | `ScheduledTask` / `AutomationRule` / `Procedure` / `BackupSet` / `RemoteCopy` |
|
||
| Log / Sezione / Traccia | `LogEntry` / `LogSection` / `TraceId` |
|
||
| Radar / Hotlink / Scheda / Widget / Tema / Accento / Menu compresso | `Radar` / `Hotlink` / `Tab` / `Widget` / `ThemeMode` / `AccentColor` / `MenuState.Collapsed` |
|
||
|
||
---
|
||
|
||
## 23. Avvio della prima sessione
|
||
|
||
1. Verifica prerequisiti: `dotnet --version` (10.0.x), `docker --version`, `git --version`. Se manca l'SDK 10, fermati e chiedilo.
|
||
2. Crea la struttura di §4: `dotnet new sln`, `dotnet new classlib -f net10.0` per ogni libreria, `dotnet new blazor --interactivity Server --all-interactive --empty` per `Khaemhat.Web`, `dotnet new mstest` per i test; normalizza i `.csproj` (rimuovi pacchetti non ammessi, imposta `Directory.Packages.props`). Copia nel repository i file consegnati: `docs/mockups/png/*.png`, `docs/mockups/mockup.css`, `assets/*`, `deploy/*`; crea `docs/wiki/` con `Home.md`, `_Sidebar.md` e una pagina stub per ogni voce di §17.
|
||
3. Scrivi `README.md`, `docs/STATUS.md` e gli ADR iniziali; esegui la milestone 0 fino al tag `v0.0.1`; prosegui con la milestone 1 senza attendere conferme.
|
||
4. Ad ogni riavvio di sessione: leggi `CLAUDE.md`, `docs/STATUS.md`, `docs/mockups/README.md` (se lavori sull'UI) e l'ultimo `git log -20`, poi continua dal punto esatto indicato.
|
||
|
||
---
|
||
|
||
## Appendice A — Token di design (estratto di `docs/mockups/mockup.css`)
|
||
|
||
Il file completo `mockup.css` (consegnato a parte, da copiare in `docs/mockups/`) contiene anche tutte le classi dei componenti usate nei mockup. Qui i soli token, che `tokens.css` deve riprendere alla lettera.
|
||
|
||
```css
|
||
/* Khaemhat — mockup design tokens & components (reference for src/Khaemhat.Web/wwwroot/css/tokens.css) */
|
||
:root{
|
||
--kh-font: "Inter", "Segoe UI", system-ui, -apple-system, Roboto, sans-serif;
|
||
--kh-mono: "JetBrains Mono", "Cascadia Mono", "DejaVu Sans Mono", monospace;
|
||
--kh-fs: 13px; --kh-fs-sm: 11.5px; --kh-fs-lg: 15px; --kh-fs-xl: 20px;
|
||
--kh-radius: 6px; --kh-radius-lg: 10px;
|
||
--kh-topbar-h: 46px; --kh-tabs-h: 36px; --kh-status-h: 24px; --kh-sidebar-w: 228px;
|
||
--kh-gap: 12px; --kh-row-h: 30px;
|
||
--kh-shadow: 0 1px 2px rgba(16,24,40,.06), 0 1px 3px rgba(16,24,40,.08);
|
||
--kh-shadow-lg: 0 12px 32px rgba(16,24,40,.22);
|
||
/* brand */
|
||
--kh-brand: #C8962E; --kh-brand-deep: #8B6318; --kh-papyrus: #F1E6C8;
|
||
/* semantic */
|
||
--kh-ok: #1E8E5A; --kh-ok-soft: #DDF3E6; --kh-warn: #C27A1A; --kh-warn-soft: #FBEFD9;
|
||
--kh-err: #C2453A; --kh-err-soft: #FADEDC; --kh-info: #1F5FA8; --kh-info-soft: #E3ECF8;
|
||
}
|
||
/* ---- accents (per-user) ---- */
|
||
:root[data-accent="nilo"] { --kh-accent:#1F5FA8; --kh-accent-strong:#174A85; --kh-accent-soft:#E3ECF8; --kh-accent-text:#174A85; }
|
||
:root[data-accent="lapislazzuli"]{ --kh-accent:#3F51B5; --kh-accent-strong:#303F9F; --kh-accent-soft:#E6E9F7; --kh-accent-text:#303F9F; }
|
||
:root[data-accent="malachite"] { --kh-accent:#1E8E5A; --kh-accent-strong:#167347; --kh-accent-soft:#DDF3E6; --kh-accent-text:#167347; }
|
||
:root[data-accent="turchese"] { --kh-accent:#0F8A96; --kh-accent-strong:#0B6D77; --kh-accent-soft:#D9F0F2; --kh-accent-text:#0B6D77; }
|
||
:root[data-accent="ocra"] { --kh-accent:#C27A1A; --kh-accent-strong:#9A6013; --kh-accent-soft:#FBEFD9; --kh-accent-text:#8B5511; }
|
||
:root[data-accent="corniola"] { --kh-accent:#C2453A; --kh-accent-strong:#9E362D; --kh-accent-soft:#FADEDC; --kh-accent-text:#9E362D; }
|
||
:root[data-accent="ametista"] { --kh-accent:#7E57C2; --kh-accent-strong:#65449C; --kh-accent-soft:#ECE4F8; --kh-accent-text:#65449C; }
|
||
:root[data-accent="grafite"] { --kh-accent:#4B5563; --kh-accent-strong:#374151; --kh-accent-soft:#E5E7EB; --kh-accent-text:#374151; }
|
||
/* ---- light theme ---- */
|
||
:root, :root[data-theme="light"]{
|
||
--kh-bg:#F3F5F8; --kh-surface:#FFFFFF; --kh-surface-2:#F8FAFC; --kh-surface-3:#EEF2F6;
|
||
--kh-border:#DDE3EA; --kh-border-strong:#C5CDD7;
|
||
--kh-text:#1E2733; --kh-text-2:#5B6776; --kh-text-3:#8A95A3;
|
||
--kh-topbar:#17243A; --kh-topbar-text:#E8EDF5; --kh-topbar-muted:#9FB0C8;
|
||
--kh-sidebar:#FFFFFF; --kh-input:#FFFFFF; --kh-input-ro:#F3F5F8;
|
||
--kh-row-alt:#FAFBFD; --kh-row-hover:#F1F5FB; --kh-row-sel: var(--kh-accent-soft);
|
||
}
|
||
/* ---- dark theme ---- */
|
||
:root[data-theme="dark"]{
|
||
--kh-bg:#12161C; --kh-surface:#1B2028; --kh-surface-2:#20262F; --kh-surface-3:#262D37;
|
||
--kh-border:#2E3744; --kh-border-strong:#3C4756;
|
||
--kh-text:#E7ECF2; --kh-text-2:#A5B0BD; --kh-text-3:#73808F;
|
||
--kh-topbar:#0E131A; --kh-topbar-text:#E7ECF2; --kh-topbar-muted:#8391A3;
|
||
--kh-sidebar:#171C23; --kh-input:#12161C; --kh-input-ro:#1B2028;
|
||
--kh-row-alt:#1E242D; --kh-row-hover:#252D38; --kh-row-sel:#24354D;
|
||
--kh-ok-soft:#163B2A; --kh-warn-soft:#3E2E13; --kh-err-soft:#44201D; --kh-info-soft:#1C2F4A;
|
||
--kh-shadow: 0 1px 2px rgba(0,0,0,.4);
|
||
--kh-shadow-lg: 0 12px 32px rgba(0,0,0,.6);
|
||
}
|
||
:root[data-theme="dark"][data-accent="nilo"] { --kh-accent:#4C8EDB; --kh-accent-strong:#6AA3E6; --kh-accent-soft:#1C2F4A; --kh-accent-text:#8DB8EE; }
|
||
:root[data-theme="dark"][data-accent="lapislazzuli"]{ --kh-accent:#7986CB; --kh-accent-strong:#9FA8DA; --kh-accent-soft:#232A4D; --kh-accent-text:#AAB3E6; }
|
||
:root[data-theme="dark"][data-accent="malachite"] { --kh-accent:#3DBB7E; --kh-accent-strong:#62CC97; --kh-accent-soft:#163B2A; --kh-accent-text:#8ADBB1; }
|
||
:root[data-theme="dark"][data-accent="turchese"] { --kh-accent:#30B4C1; --kh-accent-strong:#5BC8D3; --kh-accent-soft:#143A3E; --kh-accent-text:#8EDBE3; }
|
||
:root[data-theme="dark"][data-accent="ocra"] { --kh-accent:#E09A3A; --kh-accent-strong:#EBB266; --kh-accent-soft:#3E2E13; --kh-accent-text:#F0C27A; }
|
||
:root[data-theme="dark"][data-accent="corniola"] { --kh-accent:#E0665A; --kh-accent-strong:#EA8A80; --kh-accent-soft:#44201D; --kh-accent-text:#F0A39B; }
|
||
:root[data-theme="dark"][data-accent="ametista"] { --kh-accent:#A98BE0; --kh-accent-strong:#BFA8EA; --kh-accent-soft:#2E2345; --kh-accent-text:#CBB8F0; }
|
||
:root[data-theme="dark"][data-accent="grafite"] { --kh-accent:#9CA3AF; --kh-accent-strong:#B9C0CC; --kh-accent-soft:#2A3038; --kh-accent-text:#C9D0DA; }
|
||
/* density */
|
||
:root[data-density="compact"]{ --kh-row-h:26px; --kh-fs:12.5px; --kh-gap:8px; }
|
||
```
|
||
|
||
## Appendice B — Icona (sorgenti SVG)
|
||
|
||
`assets/icon.svg` (semplice):
|
||
```svg
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512"><defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#243A5E"/><stop offset="1" stop-color="#0F1826"/></linearGradient><linearGradient id="gold" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F0C86A"/><stop offset="1" stop-color="#C8962E"/></linearGradient></defs><rect width="512" height="512" rx="112" fill="url(#bg)"/><rect x="16" y="16" width="480" height="480" rx="100" fill="none" stroke="#FFFFFF" stroke-opacity=".07" stroke-width="2"/><g transform="translate(0 0) scale(1.0)"><rect x="76" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="76" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><path d="M110 104h36l20 20v68a6 6 0 0 1-6 6h-50a6 6 0 0 1-6-6V110a6 6 0 0 1 6-6z" fill="#17243A"/><path d="M146 104v20h20" fill="#2A4472"/><path d="M122 142h28" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 158h34" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 174h20" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><text x="194" y="204" text-anchor="middle" font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="800" font-size="46" fill="#17243A">€</text><path d="M361 107l44 22-44 22-44-22z" fill="#2A4472"/><path d="M317 129l44 22v52l-44-22z" fill="#17243A"/><path d="M405 129l-44 22v52l44-22z" fill="#1D3155"/><path d="M339 118l44 22" stroke="#E0B04A" stroke-width="5" stroke-linecap="round" opacity=".9"/><rect x="116" y="358" width="22" height="48" rx="5" fill="#17243A"/><rect x="148" y="330" width="22" height="76" rx="5" fill="#17243A"/><rect x="180" y="302" width="22" height="104" rx="5" fill="#17243A"/><path d="M120 340L152 326L184 308" fill="none" stroke="#E0B04A" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/><circle cx="184" cy="308" r="7" fill="#E0B04A"/><circle cx="378" cy="344" r="13" fill="#2A4472"/><path d="M354 398a24 22 0 0 1 48 0z" fill="#2A4472"/><circle cx="346" cy="340" r="19" fill="#17243A"/><path d="M310 406a36 30 0 0 1 72 0z" fill="#17243A"/></g></svg>
|
||
```
|
||
|
||
`assets/icon-v1.0.svg` (versionata: stesso disegno ridotto all'80% con fascia "v 1.0"; `scripts/build.sh` sostituisce il testo `v 1.0` con `v <major.minor>`):
|
||
```svg
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512"><defs><linearGradient id="bg" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#243A5E"/><stop offset="1" stop-color="#0F1826"/></linearGradient><linearGradient id="gold" x1="0" y1="0" x2="0" y2="1"><stop offset="0" stop-color="#F0C86A"/><stop offset="1" stop-color="#C8962E"/></linearGradient></defs><rect width="512" height="512" rx="112" fill="url(#bg)"/><rect x="16" y="16" width="480" height="480" rx="100" fill="none" stroke="#FFFFFF" stroke-opacity=".07" stroke-width="2"/><g transform="translate(51 10) scale(0.8)"><rect x="76" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="76" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="76" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><rect x="286" y="286" width="150" height="150" rx="34" fill="url(#gold)"/><path d="M110 104h36l20 20v68a6 6 0 0 1-6 6h-50a6 6 0 0 1-6-6V110a6 6 0 0 1 6-6z" fill="#17243A"/><path d="M146 104v20h20" fill="#2A4472"/><path d="M122 142h28" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 158h34" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><path d="M122 174h20" stroke="#E0B04A" stroke-width="6" stroke-linecap="round"/><text x="194" y="204" text-anchor="middle" font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="800" font-size="46" fill="#17243A">€</text><path d="M361 107l44 22-44 22-44-22z" fill="#2A4472"/><path d="M317 129l44 22v52l-44-22z" fill="#17243A"/><path d="M405 129l-44 22v52l44-22z" fill="#1D3155"/><path d="M339 118l44 22" stroke="#E0B04A" stroke-width="5" stroke-linecap="round" opacity=".9"/><rect x="116" y="358" width="22" height="48" rx="5" fill="#17243A"/><rect x="148" y="330" width="22" height="76" rx="5" fill="#17243A"/><rect x="180" y="302" width="22" height="104" rx="5" fill="#17243A"/><path d="M120 340L152 326L184 308" fill="none" stroke="#E0B04A" stroke-width="6" stroke-linecap="round" stroke-linejoin="round"/><circle cx="184" cy="308" r="7" fill="#E0B04A"/><circle cx="378" cy="344" r="13" fill="#2A4472"/><path d="M354 398a24 22 0 0 1 48 0z" fill="#2A4472"/><circle cx="346" cy="340" r="19" fill="#17243A"/><path d="M310 406a36 30 0 0 1 72 0z" fill="#17243A"/></g><rect x="126" y="414" width="260" height="62" rx="31" fill="url(#gold)"/><text x="256" y="459" text-anchor="middle" font-family="Inter, Segoe UI, Arial, sans-serif" font-weight="800" font-size="40" fill="#17243A" letter-spacing="1">v 1.0</text></svg>
|
||
```
|
||
|
||
`assets/icon-mono.svg` (favicon 16–32 px):
|
||
```svg
|
||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><rect width="512" height="512" rx="112" fill="#17243A"/><rect x="76" y="76" width="150" height="150" rx="34" fill="#E0B04A"/><rect x="286" y="76" width="150" height="150" rx="34" fill="#E0B04A"/><rect x="76" y="286" width="150" height="150" rx="34" fill="#E0B04A"/><rect x="286" y="286" width="150" height="150" rx="34" fill="#E0B04A"/></svg>
|
||
```
|
||
|
||
## Appendice C — Deploy (`deploy/`)
|
||
|
||
`deploy/unraid/khaemhat.xml`:
|
||
```xml
|
||
<?xml version="1.0"?>
|
||
<!-- Template Unraid (formato Community Applications) per Khaemhat.
|
||
Importalo da Docker › Add Container › Template. Sostituisci <owner> con il tuo utente GitHub.
|
||
L'icona deve essere raggiungibile senza autenticazione: usa il repository pubblico khaemhat-assets. -->
|
||
<Container version="2">
|
||
<Name>khaemhat</Name>
|
||
<Repository>ghcr.io/<owner>/khaemhat:1.0.0</Repository>
|
||
<Registry>https://github.com/<owner>/khaemhat/pkgs/container/khaemhat</Registry>
|
||
<Network>khaemhat-net</Network>
|
||
<Privileged>false</Privileged>
|
||
<Support>https://github.com/<owner>/khaemhat/wiki</Support>
|
||
<Project>https://github.com/<owner>/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/<owner>/khaemhat-assets/main/unraid/khaemhat.xml</TemplateURL>
|
||
<Icon>https://raw.githubusercontent.com/<owner>/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_<codice>)" Type="Variable" Display="always" Required="true" Mask="false">DEMO</Config>
|
||
<Config Name="KHAEMHAT_COMPANY_NAME" Target="KHAEMHAT_COMPANY_NAME" Default="La mia azienda S.r.l." Mode="" Description="Ragione sociale della prima azienda" Type="Variable" Display="always" Required="true" Mask="false">La mia azienda S.r.l.</Config>
|
||
<Config Name="KHAEMHAT_PUBLIC_URL" Target="KHAEMHAT_PUBLIC_URL" Default="" Mode="" Description="URL pubblico usato nei link delle e-mail" Type="Variable" Display="always" Required="false" Mask="false"></Config>
|
||
<Config Name="KHAEMHAT_REDIS" Target="KHAEMHAT_REDIS" Default="" Mode="" Description="Opzionale: redis://:password@khaemhat-redis:6379/0" Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
|
||
<Config Name="KHAEMHAT_LICENSE_MODE" Target="KHAEMHAT_LICENSE_MODE" Default="production" Mode="" Description="production oppure test (abilita i codici di licenza fittizi)" Type="Variable" Display="advanced" Required="false" Mask="false">production</Config>
|
||
<Config Name="KHAEMHAT_LICENSE" Target="KHAEMHAT_LICENSE" Default="" Mode="" Description="Licenza firmata (.khl, testo). Vuoto = Trial" Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
|
||
<Config Name="KHAEMHAT_SEED_DEMO" Target="KHAEMHAT_SEED_DEMO" Default="false" Mode="" Description="true = dati dimostrativi al primo avvio (solo database vuoto)" Type="Variable" Display="advanced" Required="false" Mask="false">false</Config>
|
||
<Config Name="KHAEMHAT_UPDATE_FEED" Target="KHAEMHAT_UPDATE_FEED" Default="" Mode="" Description="Opzionale: URL API GHCR per il controllo aggiornamenti" Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
|
||
<Config Name="TZ" Target="TZ" Default="Europe/Rome" Mode="" Description="Fuso orario" Type="Variable" Display="advanced" Required="false" Mask="false">Europe/Rome</Config>
|
||
<Config Name="PUID" Target="PUID" Default="99" Mode="" Description="UID per i file in /data" Type="Variable" Display="advanced" Required="false" Mask="false">99</Config>
|
||
<Config Name="PGID" Target="PGID" Default="100" Mode="" Description="GID per i file in /data" Type="Variable" Display="advanced" Required="false" Mask="false">100</Config>
|
||
</Container>
|
||
|
||
```
|
||
|
||
`deploy/docker-compose.unraid.yml`:
|
||
```yaml
|
||
# Khaemhat su Unraid (plugin di gestione compose) o su qualunque host Docker.
|
||
# Le etichette net.unraid.docker.* mostrano icona e link WebUI nella pagina Docker di Unraid.
|
||
services:
|
||
khaemhat:
|
||
image: ghcr.io/<owner>/khaemhat:1.0.0
|
||
container_name: khaemhat
|
||
restart: unless-stopped
|
||
depends_on:
|
||
khaemhat-db:
|
||
condition: service_healthy
|
||
ports:
|
||
- "8080:8080"
|
||
environment:
|
||
KHAEMHAT_SYSTEM_DB: postgres://khaemhat:${POSTGRES_PASSWORD}@khaemhat-db:5432/khaemhat_system
|
||
KHAEMHAT_DB_SERVER: postgres://khaemhat:${POSTGRES_PASSWORD}@khaemhat-db:5432/
|
||
KHAEMHAT_SECRET_KEY: ${KHAEMHAT_SECRET_KEY}
|
||
KHAEMHAT_SUPERUSER: ${KHAEMHAT_SUPERUSER:-root}
|
||
KHAEMHAT_SUPERUSER_PASSWORD: ${KHAEMHAT_SUPERUSER_PASSWORD}
|
||
KHAEMHAT_SUPERUSER_EMAIL: ${KHAEMHAT_SUPERUSER_EMAIL:-}
|
||
KHAEMHAT_COMPANY_CODE: ${KHAEMHAT_COMPANY_CODE:-DEMO}
|
||
KHAEMHAT_COMPANY_NAME: ${KHAEMHAT_COMPANY_NAME:-La mia azienda S.r.l.}
|
||
KHAEMHAT_PUBLIC_URL: ${KHAEMHAT_PUBLIC_URL:-http://localhost:8080}
|
||
KHAEMHAT_REDIS: ${KHAEMHAT_REDIS:-}
|
||
KHAEMHAT_LICENSE_MODE: ${KHAEMHAT_LICENSE_MODE:-production}
|
||
KHAEMHAT_SEED_DEMO: ${KHAEMHAT_SEED_DEMO:-false}
|
||
TZ: Europe/Rome
|
||
PUID: "99"
|
||
PGID: "100"
|
||
volumes:
|
||
- /mnt/user/appdata/khaemhat/data:/data
|
||
labels:
|
||
net.unraid.docker.managed: composeman
|
||
net.unraid.docker.webui: "http://[IP]:[PORT:8080]/"
|
||
net.unraid.docker.icon: "https://raw.githubusercontent.com/<owner>/khaemhat-assets/main/icon-v1.0-256.png"
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-fs", "http://localhost:8080/health/live"]
|
||
interval: 30s
|
||
timeout: 5s
|
||
retries: 3
|
||
networks: [khaemhat-net]
|
||
|
||
khaemhat-db:
|
||
image: postgres:17
|
||
container_name: khaemhat-db
|
||
restart: unless-stopped
|
||
environment:
|
||
POSTGRES_DB: khaemhat_system
|
||
POSTGRES_USER: khaemhat
|
||
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
|
||
TZ: Europe/Rome
|
||
volumes:
|
||
- /mnt/user/appdata/khaemhat/postgres:/var/lib/postgresql/data
|
||
labels:
|
||
net.unraid.docker.managed: composeman
|
||
healthcheck:
|
||
test: ["CMD-SHELL", "pg_isready -U khaemhat -d khaemhat_system"]
|
||
interval: 10s
|
||
timeout: 5s
|
||
retries: 10
|
||
networks: [khaemhat-net]
|
||
|
||
khaemhat-redis:
|
||
image: redis:7
|
||
container_name: khaemhat-redis
|
||
restart: unless-stopped
|
||
profiles: ["redis"]
|
||
command: ["redis-server", "--requirepass", "${REDIS_PASSWORD:-cambiami}", "--save", "", "--appendonly", "no"]
|
||
labels:
|
||
net.unraid.docker.managed: composeman
|
||
networks: [khaemhat-net]
|
||
|
||
networks:
|
||
khaemhat-net:
|
||
name: khaemhat-net
|
||
|
||
```
|
||
|
||
`deploy/.env.example`:
|
||
```ini
|
||
# Copia in .env accanto a docker-compose.unraid.yml (mai committare .env)
|
||
POSTGRES_PASSWORD=cambiami-subito
|
||
KHAEMHAT_SECRET_KEY= # openssl rand -base64 48
|
||
KHAEMHAT_SUPERUSER=root
|
||
KHAEMHAT_SUPERUSER_PASSWORD=cambiami-al-primo-accesso
|
||
KHAEMHAT_SUPERUSER_EMAIL=alberto@example.com
|
||
KHAEMHAT_COMPANY_CODE=DEMO
|
||
KHAEMHAT_COMPANY_NAME=La mia azienda S.r.l.
|
||
KHAEMHAT_PUBLIC_URL=https://gestionale.example.com
|
||
KHAEMHAT_LICENSE_MODE=production
|
||
KHAEMHAT_SEED_DEMO=false
|
||
# KHAEMHAT_REDIS=redis://:cambiami@khaemhat-redis:6379/0
|
||
# REDIS_PASSWORD=cambiami
|
||
|
||
```
|
||
|
||
## Appendice D — Workflow GitHub a minuti contati e script di rilascio
|
||
|
||
`.github/workflows/ci.yml`:
|
||
```yaml
|
||
name: ci
|
||
on:
|
||
pull_request:
|
||
branches: [main]
|
||
paths-ignore: ["docs/**", "*.md", "assets/**", "deploy/**"]
|
||
push:
|
||
tags: ["v*"]
|
||
concurrency:
|
||
group: ci-${{ github.ref }}
|
||
cancel-in-progress: true
|
||
jobs:
|
||
build-test:
|
||
runs-on: ubuntu-latest
|
||
timeout-minutes: 15
|
||
services:
|
||
postgres:
|
||
image: ${{ startsWith(github.ref, 'refs/tags/v') && 'postgres:17' || '' }}
|
||
env: { POSTGRES_PASSWORD: test, POSTGRES_DB: khaemhat_test }
|
||
ports: ["5432:5432"]
|
||
options: >-
|
||
--health-cmd "pg_isready -U postgres" --health-interval 5s --health-timeout 5s --health-retries 10
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: actions/setup-dotnet@v4
|
||
with: { dotnet-version: "10.0.x" }
|
||
- uses: actions/cache@v4
|
||
with:
|
||
path: ~/.nuget/packages
|
||
key: nuget-${{ hashFiles('Directory.Packages.props', '**/*.csproj') }}
|
||
- run: scripts/check-packages.sh
|
||
- run: dotnet build -c Release -warnaserror
|
||
- run: dotnet test -c Release --no-build
|
||
env:
|
||
KHAEMHAT_TEST_PG: ${{ startsWith(github.ref, 'refs/tags/v') && 'postgres://postgres:test@localhost:5432/khaemhat_test' || '' }}
|
||
KHAEMHAT_LICENSE_MODE: test
|
||
```
|
||
|
||
`.github/workflows/release.yml` (solo manuale):
|
||
```yaml
|
||
name: release-image
|
||
on:
|
||
workflow_dispatch:
|
||
inputs:
|
||
version: { description: "Tag (es. v1.0.2)", required: true }
|
||
arm64: { description: "Costruisci anche linux/arm64", type: boolean, default: false }
|
||
jobs:
|
||
image:
|
||
runs-on: ubuntu-latest
|
||
timeout-minutes: 30
|
||
permissions: { contents: read, packages: write }
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
with: { ref: ${{ inputs.version }} }
|
||
- uses: docker/setup-buildx-action@v3
|
||
- uses: docker/login-action@v3
|
||
with: { registry: ghcr.io, username: ${{ github.actor }}, password: ${{ secrets.GITHUB_TOKEN }} }
|
||
- uses: docker/build-push-action@v6
|
||
with:
|
||
context: .
|
||
file: docker/Dockerfile
|
||
push: true
|
||
platforms: ${{ inputs.arm64 && 'linux/amd64,linux/arm64' || 'linux/amd64' }}
|
||
build-args: VERSION=${{ inputs.version }},GIT_SHA=${{ github.sha }}
|
||
tags: |
|
||
ghcr.io/${{ github.repository_owner }}/khaemhat:${{ inputs.version }}
|
||
ghcr.io/${{ github.repository_owner }}/khaemhat:latest
|
||
```
|
||
|
||
`.github/workflows/wiki.yml`:
|
||
```yaml
|
||
name: wiki
|
||
on:
|
||
push:
|
||
branches: [main]
|
||
paths: ["docs/wiki/**"]
|
||
jobs:
|
||
sync:
|
||
runs-on: ubuntu-latest
|
||
timeout-minutes: 5
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- run: |
|
||
git clone "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.wiki.git" wiki
|
||
rsync -a --delete --exclude .git docs/wiki/ wiki/
|
||
cd wiki && git add -A && git -c user.name=ci -c user.email=ci@users.noreply.github.com commit -m "wiki: sync from ${{ github.sha }}" || exit 0
|
||
git push
|
||
```
|
||
|
||
`scripts/publish-image.sh` (percorso normale, nessun minuto di CI):
|
||
```bash
|
||
#!/usr/bin/env bash
|
||
set -euo pipefail
|
||
VERSION="${1:?uso: publish-image.sh vX.Y.Z [--arm64]}"; PLATFORMS="linux/amd64"; [[ "${2:-}" == "--arm64" ]] && PLATFORMS="linux/amd64,linux/arm64"
|
||
OWNER="${GITHUB_OWNER:?}"; IMAGE="ghcr.io/$OWNER/khaemhat"; SHA="$(git rev-parse --short HEAD)"; MM="${VERSION#v}"; MM="${MM%.*}"
|
||
echo "$GITHUB_TOKEN" | docker login ghcr.io -u "$OWNER" --password-stdin
|
||
sed "s/v 1.0/v $MM/" assets/icon-v1.0.svg > "assets/icon-v$MM.svg" # icona versionata (sostituzione di stringa)
|
||
docker buildx build --platform "$PLATFORMS" -f docker/Dockerfile --build-arg VERSION="$VERSION" --build-arg GIT_SHA="$SHA" \
|
||
-t "$IMAGE:$VERSION" -t "$IMAGE:latest" --push .
|
||
git tag -a "$VERSION" -m "Khaemhat $VERSION" && git push origin "$VERSION"
|
||
echo "Pubblicata $IMAGE:$VERSION"
|
||
```
|