Alby96andClaude Opus 5.5 83ef60fce2
CI / Build and test (SQLite) (pull_request) Successful in 5m27s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 6s
CI / Docker image (pull_request) Successful in 1m59s
docs: record owner decisions on mockups, bank list and SDI channels (#35 #45 #78)
The owner confirmed that no further high-resolution mockups exist, gave up
the preloaded ABI/CAB bank list and set aside real SDI intermediaries,
SdICoop accreditation and a test PEC mailbox. ADR 0044 records this so the
next milestones stop waiting on that material: thumbnail-only screens are
designed from the thumbnail and the existing UI, bank name and BIC come
from a company account or are typed once, and #78 moves to the backlog.
CLAUDE.md E4, the mockup index, related ADRs, status, changelog and the
user guide are updated accordingly.

Closes #35
Closes #45

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 17:19:01 +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%