Files
Alby96andClaude Opus 5.5 4123ccacb2
CI / Build and test (SQLite) (pull_request) Canceled after 0s
CI / PostgreSQL 16 integration (pull_request) Canceled after 0s
CI / PostgreSQL 17 integration (pull_request) Canceled after 0s
CI / Docker image (pull_request) Canceled after 0s
CI / YAML check (pull_request) Canceled after 0s
docs: user guide with real screenshots, developer README and M5 closing (#53 #54)
The wiki becomes a guide for the people who use Khaemhat: a new "Guida all'uso"
page walks from sign-in to an invoice sent by e-mail, and Vendite is rewritten
around the real screens of 0.5.0 (radars, document mask, Crea …, deferred
invoicing, print preview, mail). Primi passi, Dati di esempio, Allegati, Log
and Impostazioni describe what this version does, including the SMTP variables.

README.md turns into the installation guide for developers: prerequisites,
run-dev, tests with PostgreSQL, migrations, image and wiki publishing.

The engine now writes confirmations, changes of state and deletions to the
Documents log section, the last step of #53. ADR 0034 records the print and
mail decisions; CHANGELOG 0.5.0 and STATUS close the milestone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 17:38:14 +01:00

11 KiB

Khaemhat

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_HOST e KHAEMHAT_SMTP_FROM l'invio è spento. Per provarlo serve un server SMTP di prova sulla tua macchina, ad esempio KHAEMHAT_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 --base oppure scripts/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 e docs/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, Nullable attivo, warning come errori, .editorconfig; JavaScript solo come interop minimo in wwwroot/js.
  • Nessuna libreria esterna: framework Microsoft, Npgsql, Microsoft.Data.Sqlite e, 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 verso main con Closes #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.