Alby96andClaude Opus 5.5 4b759ee96e
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: purchases and warehouse guide with screenshots, ADR 0035 and the 0.6.0 changelog (#61)
The Acquisti and Magazzino wiki pages now describe what M6 delivers, with real
screenshots of the demo company: stock, item movements, valuation, stock take, reorder
proposal, receipts, price differences, e-invoice import and pending self-invoices. The
user guide gains the buying and warehouse steps; the pages that said "arriva con M6"
(sales, items, dashboard, import, scheduled jobs, demo data) are brought up to date.
ADR 0035 records how documents post to the warehouse, the recomputed weighted average,
the invoice cost correction, the rebuild, the stock take, the base tables of existing
companies and where the Italian self-invoice and import rules live.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:24:43 +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%