M10 gives the ledger its year end. Fixed assets get categories with the ministerial coefficients, a civil and a fiscal plan, depreciation posted per category and undoable, disposals with gain or loss and the register print (ADR 0041). Intrastat lists are generated from confirmed invoices with the due periodicity and the SCAMBI.CEE file; declarations of intent get their own register and the N3.5 ceiling is checked when an invoice is confirmed (ADR 0042). Accruals, deferrals and exchange differences feed a nine-step guided closing that can repeat or undo its last step until the final prints, reopens the next year and locks the closed one; the CEE statements (ordinary, abbreviated, micro), the reclassified statements, the ratios and the accountant export read the year's balances (ADR 0043). The demo seed now opens the year with assets, stock, bank and capital, so the integration test closes the demo year from the checks to the lock on SQLite and PostgreSQL. Docs: wiki pages with screenshots, ADR 0041-0043, MODULES, STATUS, DATA-MODEL and the 0.10.0 changelog. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Khaemhat
Gestionale ERP + CRM per piccole e medie imprese italiane, scritto da zero in C# 14 su .NET 10 con interfaccia Blazor Server, PostgreSQL (o SQLite per demo e test) e nessuna libreria esterna. Si distribuisce solo come immagine Docker nel registro pacchetti di Gitea.
Questo file è la guida di installazione per chi sviluppa: come preparare il computer, compilare, avviare, provare e pubblicare. Chi usa il gestionale parte dalla Guida all'uso nella wiki; chi lo installa su un server da Installazione Docker o Installazione Unraid.
Stato: sviluppo in corso, versioni 0.x. Ultima milestone chiusa: M5 — Motore documenti e Vendite (0.5.0). Punto di ripresa in
docs/STATUS.md, piano in Roadmap.
1. Prerequisiti
| Strumento | Versione | A cosa serve |
|---|---|---|
| .NET SDK | 10.0.100 o successiva della stessa feature band (vedi global.json) |
compilare, provare, avviare |
| Git | qualunque recente | il repository; su Windows anche Git Bash, che esegue gli script scripts/*.sh |
| Docker | facoltativo | costruire e provare l'immagine; PostgreSQL e Redis per i test sui motori reali |
| PostgreSQL | 16 o 17, facoltativo | i test di integrazione sul motore di produzione (KHAEMHAT_TEST_PG) |
Non servono Node.js, npm, bundler, IDE particolari né pacchetti NuGet oltre a quelli ammessi: un editor qualunque
va bene (Visual Studio, Rider, VS Code con C# Dev Kit). Lingua dei messaggi del compilatore: per avere gli errori in
inglese, DOTNET_CLI_UI_LANGUAGE=en.
2. Clonare
git clone https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat.git
In rete locale anche http://192.168.30.23:3000/BalboSoft/Khaemhat.git o, con una chiave SSH,
ssh://git@192.168.30.23:2222/BalboSoft/Khaemhat.git. Il ramo principale è main; si lavora su rami
feat/<n>-descrizione, fix/…, docs/… (vedi docs/DEVELOPMENT.md).
3. Com'è fatto il repository
| Cartella | Contenuto |
|---|---|
src/Khaemhat.Core |
entità, regole, macchine a stati dei documenti, nessuna dipendenza |
src/Khaemhat.Data, .Data.Sqlite, .Data.PostgreSql |
micro-ORM, migrazioni, provider dei due motori |
src/Khaemhat.Application |
servizi applicativi: sicurezza, tabelle, anagrafiche, motore documenti, stampe, seed |
src/Khaemhat.Infrastructure |
file (PDF, fogli di calcolo, archivi), posta SMTP, cache, licenze, sicurezza: scritti in casa |
src/Khaemhat.Fiscal.Abstractions, .Fiscal.Italy |
il pacchetto paese: tutto ciò che è italiano |
src/Khaemhat.Web |
host Blazor Server, componenti, pagine, risorse dei testi in Resources/it-IT/*.json |
tests/* |
MSTest, un progetto per strato |
tools/* |
strumenti di sviluppo: licenze (LicenseTool), comuni e CAP (PlacesTool), modello dati (DataModelTool) |
docker/, deploy/ |
Dockerfile ed entrypoint; compose, .env.example, template Unraid |
scripts/ |
build, test, avvio, seed, migrazioni, pubblicazione |
docs/ |
specifica, ADR, architettura, mockup e la wiki (docs/wiki/) |
4. Compilare
scripts/build.sh
Controlla l'allowlist dei pacchetti (scripts/check-packages.sh su Directory.Packages.props) e compila
Khaemhat.sln in Release con warning come errori e gli analyzer di piattaforma. L'equivalente a mano:
dotnet build Khaemhat.sln -c Release -warnaserror
5. Avviare in locale
scripts/run-dev.sh
Avvia Khaemhat su http://localhost:5080 con SQLite in .data/dev (ignorata da git) e queste impostazioni di
sviluppo, ognuna sovrascrivibile esportando la variabile prima di lanciare lo script:
| Variabile | Valore di sviluppo |
|---|---|
KHAEMHAT_DATA_DIR, KHAEMHAT_SYSTEM_DB |
.data/dev, sqlite://…/.data/dev/system.db |
KHAEMHAT_SECRET_KEY |
una chiave fissa solo per lo sviluppo |
KHAEMHAT_SUPERUSER, KHAEMHAT_SUPERUSER_PASSWORD |
root e la password iniziale scritta nello script |
KHAEMHAT_COMPANY_CODE, KHAEMHAT_COMPANY_NAME |
DEMO, Khaemhat Demo S.r.l. |
KHAEMHAT_LICENSE_MODE |
test: tutti i moduli attivi con i codici di prova |
KHAEMHAT_SEED_DEMO |
true: la prima azienda nasce con i dati di esempio (anagrafiche, articoli, un anno di vendite) |
Al primo accesso Khaemhat chiede di cambiare la password e di collegare un'app di autenticazione (il super utente
ha la verifica in due passaggi obbligatoria): conserva la chiave e i codici di recupero. Per ripartire da zero ferma
il server e cancella .data/dev.
Altre cose utili in sviluppo:
- Invio di e-mail: senza
KHAEMHAT_SMTP_HOSTeKHAEMHAT_SMTP_FROMl'invio è spento. Per provarlo serve un server SMTP di prova sulla tua macchina, ad esempioKHAEMHAT_SMTP_HOST=127.0.0.1 KHAEMHAT_SMTP_PORT=2525 KHAEMHAT_SMTP_SECURITY=NONE KHAEMHAT_SMTP_FROM=ufficio@example.com scripts/run-dev.sh; l'esito di ogni invio è nel log, sezione E-mail/PEC. - Dati di base e di esempio su un database esistente:
scripts/seed.sh --baseoppurescripts/seed.sh --demo(aggiungono solo ciò che manca; meglio con il server fermo). - Catalogo dei componenti: http://localhost:5080/sviluppo/componenti mostra i mattoni dell'interfaccia.
- Tutte le variabili
KHAEMHAT_*sono in Installazione Docker edocs/DEPLOY.md. Una configurazione non valida ferma l'avvio con l'elenco degli errori.
Prima di ricompilare ferma il server: su Windows l'eseguibile in esecuzione blocca le DLL e la build ritenta la copia (avviso MSB3026) fino a fallire.
6. Provare
scripts/test.sh
scripts/test.sh --filter "FullyQualifiedName~Documents"
Esegue l'allowlist e tutti i test in Release. SQLite è sempre provato; i test che avviano
l'applicazione intera usano un'istanza vera su una porta libera. I test sul PostgreSQL reale partono quando
KHAEMHAT_TEST_PG indica un ruolo con CREATEDB (ogni test crea e cancella il proprio database):
docker run -d --name khaemhat-pg-test -e POSTGRES_PASSWORD=prova -p 55432:5432 postgres:17
KHAEMHAT_TEST_PG="postgres://postgres:prova@localhost:55432/postgres" scripts/test.sh
Senza la variabile quei test risultano saltati. In CI (.gitea/workflows/ci.yml) i test girano su ogni pull request verso main; il job PostgreSQL
(16 e 17) sui tag e all'avvio manuale.
Regole che i test fanno rispettare: nessun pacchetto fuori allowlist, dipendenze tra progetti nel verso giusto,
nessun testo italiano scritto nei componenti (vanno nelle risorse Resources/it-IT/*.json), chiavi di testo
esistenti, sezione del modello dati aggiornata.
7. Database e migrazioni
scripts/new-migration.sh company create_sales_documents # nuova migrazione numerata
scripts/gen-datamodel.sh # rigenera la parte generata di docs/DATA-MODEL.md
scripts/gen-datamodel.sh --check # solo verifica (la fa anche un test)
Le migrazioni si applicano da sole all'avvio, al database di sistema e a quello di ogni azienda. Il codice non deve dipendere dal motore: ogni query passa dal micro-ORM e gira identica su SQLite e PostgreSQL.
8. Immagine Docker
docker build -f docker/Dockerfile -t khaemhat:dev .
docker compose -f deploy/docker-compose.sqlite.yml up # prova veloce con SQLite
L'immagine pubblicata è gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> (e :latest, mai in produzione). La
costruisce .gitea/workflows/release.yml quando si spinge un tag vX.Y.Z (segreto REGISTRY_TOKEN con
write:package), che crea anche la release Gitea con le note del CHANGELOG.md. Se il runner non è
disponibile:
GITEA_TOKEN=… scripts/publish-image.sh v0.5.0
Non si producono installer, eseguibili o pacchetti .msi/.exe/.deb: l'unico artefatto è l'immagine
(ADR 0010). Le versioni restano 0.x finché il prodotto è in
sviluppo.
9. Documentazione e wiki
La wiki è in docs/wiki/ e si aggiorna nella stessa unità di lavoro del codice: una funzione senza documentazione
non è finita. Il workflow wiki.yml la pubblica nel wiki Gitea a ogni push su main che la tocca; a mano:
scripts/publish-wiki.sh. Le schermate stanno in docs/wiki/img/ e si fanno sull'applicazione vera con i dati di
esempio. La stessa wiki è inclusa nell'immagine e si apre con F1 dentro il gestionale.
| Cosa | Dove |
|---|---|
| Specifica normativa | docs/SPEC.md |
| Regole operative ed emendamenti | CLAUDE.md |
| Processo, rami, Definition of Done | docs/DEVELOPMENT.md |
| Architettura, dati, moduli, API, MCP | docs/ARCHITECTURE.md, docs/DATA-MODEL.md, docs/MODULES.md, docs/API.md, docs/MCP.md |
| Installazione e sicurezza | docs/DEPLOY.md, docs/SECURITY.md |
| Decisioni architetturali | docs/adr/ |
| Mockup (specifica visiva) | docs/mockups/ |
| Novità | CHANGELOG.md |
| Wiki pubblicata | https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki |
10. Regole del codice in breve
- C# 14 su .NET 10,
Nullableattivo, warning come errori,.editorconfig; JavaScript solo come interop minimo inwwwroot/js. - Nessuna libreria esterna: framework Microsoft,
Npgsql,Microsoft.Data.Sqlitee, nei test, MSTest. - Codice, commenti e commit in inglese; interfaccia in italiano dalle risorse.
- Tutto ciò che è fiscale italiano sta in
Khaemhat.Fiscal.Italy. - Commit Conventional Commits che dicono cosa cambia e perché e citano l'issue (
#n); pull request versomainconCloses #n.
Il lavoro è organizzato in issue per milestone (M0-M14) e nei progetti.
Il nome viene da Khaemhat (Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto Amenhotep III: vedi Origine del nome.