Alby96andClaude Opus 5.5 246d6f9357
CI / Build and test (SQLite) (pull_request) Successful in 4m27s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 7s
CI / Docker image (pull_request) Successful in 1m30s
docs: e-invoicing guide, ADR 0039-0040 and 0.9.0 changelog (#81)
The wiki page "Fatturazione elettronica" becomes a complete guide for 0.9 with
nine screenshots of the real screens, and the pages that pointed to M9 now
describe what shipped (demo data and their removal, scheduled jobs, sales,
purchases, Italian tax rules, user guide). ADR 0039 records the e-invoice
design (file rows, progressive, offline checks with SDI codes and in-house
schema, notification dedup, safe polling, routing, SdICoop push with channel
key) and ADR 0040 the generic intermediary contracts and the schema-driven
removal of demo data. Screen polish: dashboard actions in the header, filters
on two rows, tables no longer squeezed, report titles and notification errors;
demo e-invoices get realistic send times and a rejection in the history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 13:24:31 +01:00

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.

S
Description
Gestionale ERP e CRM
Readme
27 MiB
0 Stars 1 Watchers 0 Forks
2026-11-13 20:43:53 +01:00
Languages
C# 78.2%
HTML 19.3%
CSS 1.8%
Shell 0.3%
JavaScript 0.3%