Every later milestone stores its data through this layer, so it has to behave the same on both engines and be safe by construction: - Khaemhat.Data: explicit entity maps, typed queries over a safe expression subset, SqlFragment where every interpolated value becomes a parameter, unit of work with transactions, repositories with audit columns and optimistic concurrency on row_version, retries on transient errors. - SQLite provider (STRICT tables, WAL, exact decimals as integers scaled by 10^6, Unicode case-insensitive LIKE, serialised writes) and PostgreSQL 16+ provider (numeric(19,6), timestamptz, jsonb, advisory locks, database creation and server info). Databases are configured from postgres:// and sqlite:// URLs whose password never appears in messages. - C# migrations with system and company catalogues, schema_version with checksums, one transaction per migration under a lock, refusal of unknown applied versions; first system tables sys_companies and sys_settings. - CompanyRegistry stores each company's database URL encrypted with the instance key (AES-256-GCM, HKDF-derived key, purpose as associated data), so a copied row cannot be read for another company. - tools/Khaemhat.DataModelTool, scripts/gen-datamodel.sh and scripts/new-migration.sh: the current schema section of docs/DATA-MODEL.md is generated from the migrations and a test fails when it is stale. - C# 14 binds array.Contains to MemoryExtensions over spans; the query translator unwraps the span conversion. - Tests run every data scenario on SQLite and PostgreSQL (PostgreSQL in CI); ADR 0018 records where the contracts differ from SPEC 5.1. Docs, wiki, changelog and status updated. Closes #7, #8, #9, #10, #11, #12, #13, #14 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
Processo di sviluppo
Stato: completo per M0 · Revisione 2026-11-11 · Fonte: SPEC §17-§20, §23,
CLAUDE.md
Questo documento dice come si lavora su Khaemhat: unità di lavoro, rami, commit, verifica, chiusura delle
milestone. Le regole di prodotto stanno in SPEC.md e negli emendamenti di CLAUDE.md.
1. Prerequisiti
| Strumento | Versione | Note |
|---|---|---|
| .NET SDK | 10.0.x | fissato da global.json |
| Docker | Engine con Buildx | build dell'immagine e prove con compose |
| Git | qualsiasi recente | core.autocrlf=false consigliato; gli script *.sh hanno terminazioni LF |
| PostgreSQL | 16 o 17 | facoltativo in locale: KHAEMHAT_TEST_PG attiva i test sul motore reale |
| Redis | 7 | facoltativo: KHAEMHAT_TEST_REDIS attiva i test del client RESP |
Se manca l'SDK 10 ci si ferma e lo si chiede al titolare (SPEC §23). Su Windows gli script si eseguono da Git Bash.
1.1 Comandi
| Comando | Cosa fa |
|---|---|
scripts/build.sh |
check-packages.sh + dotnet build Khaemhat.sln -c Release -warnaserror |
scripts/build.sh --icon [X.Y] |
anche l'icona versionata assets/icon-vX.Y.svg e, se c'è un rasterizzatore, i PNG (ADR 0016) |
scripts/test.sh [argomenti di dotnet test] |
allowlist + tutti i test; PostgreSQL con KHAEMHAT_TEST_PG, Redis con KHAEMHAT_TEST_REDIS |
scripts/run-dev.sh |
avvio locale su http://localhost:5080, SQLite in .data/dev, licenze di test |
scripts/check-packages.sh |
fallisce se un file MSBuild usa un pacchetto fuori allowlist o fuori dal suo progetto |
docker build -f docker/Dockerfile -t khaemhat:dev . |
immagine locale (--build-arg RUN_TESTS=true per eseguire i test nel build) |
docker compose -f deploy/docker-compose.sqlite.yml up |
demo autonoma (con KHAEMHAT_VERSION per scegliere l'immagine) |
scripts/publish-image.sh vX.Y.Z [--arm64] |
pubblicazione dalla macchina di sviluppo se il runner non c'è (ADR 0015) |
scripts/publish-wiki.sh |
pubblica docs/wiki/ nel wiki Gitea senza passare dal runner |
scripts/new-migration.sh <system|company> <nome_snake_case> [cartella] [modulo] |
crea M<yyyymmdd>_<nnn>_<Nome>.cs con il primo numero libero del giorno (SPEC §5.3) |
scripts/gen-datamodel.sh [--check] |
rigenera la sezione generata di docs/DATA-MODEL.md dalle migrazioni; --check verifica soltanto |
KHAEMHAT_PERF=1 scripts/test.sh --filter TestCategory=Performance |
misure di riferimento dello strato dati con 100.000 righe (docs/DATA-MODEL.md §6.1) |
Gli stub seed.sh (M4) e restore-system.sh (M12, incluso nell'immagine, ADR 0017) spiegano l'uso previsto ed
escono con errore finché la loro milestone non li completa.
Test sui due motori
I test dello strato dati girano con [DataRow("Sqlite")] e [DataRow("PostgreSql")]. SQLite usa un database in
memoria condiviso, sempre disponibile. PostgreSQL usa KHAEMHAT_TEST_PG (URL
postgres://utente:password@host:5432/postgres di un ruolo con CREATEDB): ogni test crea un database
khaemhat_t_<casuale> e lo elimina alla fine; senza la variabile i test PostgreSQL risultano saltati. In CI il
job postgres li esegue su PostgreSQL 16 e 17 sui tag e all'avvio manuale del workflow.
1.2 Visual Studio Code
La cartella .vscode/ è nel repository:
launch.json: Khaemhat (web, SQLite) compila (attivitàbuild) e avviaKhaemhat.Webin debug suhttp://localhost:5080con le stesse variabili discripts/run-dev.sh(SQLite in.data/dev, licenze di test, logDebug) e apre il browser quando il server è pronto; Khaemhat (web, PostgreSQL) fa lo stesso contro un PostgreSQL locale (comando per avviarlo nel commento); Collega a un processo si aggancia a un'istanza già avviata;tasks.json:build(predefinita,Ctrl+Shift+B),test,watch (web)con ricaricamento a caldo,check-packages,docker build;extensions.json: C# Dev Kit, C#, EditorConfig, Docker.
Si apre la cartella del repository, si sceglie la configurazione nel pannello Esegui e debug e si preme F5. Le
chiavi e le password di launch.json valgono solo per lo sviluppo locale.
I test architetturali (Khaemhat.Core.Tests/Architecture) leggono i .csproj: un riferimento fra progetti non
previsto da SPEC §3 o un pacchetto fuori allowlist li fa fallire, oltre a far fallire check-packages.sh.
2. Ripresa di una sessione
- Leggere
CLAUDE.mdeSTATUS.md(punto di ripresa). - Aprire la milestone corrente su Gitea e le sue issue in Da fare / In corso nel progetto Khaemhat 1.0 — Sviluppo.
git log -20per vedere l'ultimo lavoro.- Se si lavora sull'interfaccia:
mockups/README.mde la wikiDesign-UI.md.
3. Unità di lavoro: issue Gitea
- Ogni lavoro parte da un'issue con milestone, etichette
Area/…,Kind/…,Priority/…(ed eventualmenteModulo/…) e una checklist di passi. Se un lavoro necessario non ha issue, la si crea prima di iniziare. - All'inizio si sposta l'issue nella colonna In corso del progetto; si spuntano i passi della checklist man mano che sono fatti.
- Ramo:
feat/<n>-breve-descrizione,fix/<n>-…,docs/<n>-…,chore/<n>-…a partire damain. - Commit: Conventional Commits in inglese (
feat(sales): add deferred invoicing wizard (#42)), messaggio che dice cosa cambia e perché. Un commit a fine sessione come minimo. - Pull request verso
mainconCloses #n, descrizione di cosa cambia, come è stato verificato, screenshot se cambia l'interfaccia. L'issue passa in In revisione; dopo il merge in Fatto. - Push su Gitea e PR seguono le indicazioni del titolare (emendamento E6).
4. Decisioni e blocchi
- Punto ambiguo: si decide secondo SPEC, si scrive un ADR in
adr/(NNNN-titolo.md, stato, contesto, decisione, conseguenze) e si prosegue. Gli emendamenti diCLAUDE.mdprevalgono su SPEC. - Blocco reale (credenziali, SDK, PNG o dati che solo il titolare può dare): etichetta
Status/In attesa utentee commento che dice esattamente cosa serve; si passa ad altro lavoro della milestone. - Punti aperti della specifica emersi durante la stesura della documentazione: elenco in
STATUS.md.
5. Regole di codice (sintesi di SPEC §19)
recordper DTO e value object,sealeddi default,decimalper importi e quantità (maidouble).DateOnly/DateTimein UTC; conversione aEurope/Romesolo in presentazione.- Async con
CancellationToken;Result<T>per gli esiti attesi; eccezioni di dominio localizzabili. - Validazione in
Core/Application: l'interfaccia mostra, non decide. Niente logica nei.razor(code-behind + servizi). - Ogni servizio applicativo è transazionale per operazione; motore documenti e contabile garantiscono l'atomicità di documento + magazzino + partite + registrazione + numerazione + allegati.
- Ogni modulo logga nella propria sezione con
trace_id. - Commenti solo per i perché; XML doc sui tipi pubblici di
Core,Data,Fiscal.Abstractions. - Ogni file appartiene a un modulo; nessuna cartella
Utils. - Codice, commenti e commit in inglese; testi dell'interfaccia in italiano nelle risorse
it-IT.
6. Test (SPEC §18)
scripts/test.shverde a ogni milestone: SQLite sempre; PostgreSQL conKHAEMHAT_TEST_PG; Redis conKHAEMHAT_TEST_REDIS; test in modalità licenzatest.- Test di architettura: dipendenze tra progetti, allowlist dei pacchetti, nessun testo UI hard-coded, nessun accesso
al pacchetto fiscale fuori dalle interfacce, nessun
Process.Startfuori daInfrastructure/Backup. - Prestazioni di riferimento con demo x10 (SPEC §18): radar < 300 ms/pagina su PostgreSQL, fattura di 50 righe con contabilizzazione < 700 ms, liquidazione mensile < 5 s, bilancio di verifica su 2 M righe < 10 s, ricostruzione giacenze di 100k movimenti < 60 s, backup di 2 GB < 5 min, pagina log con 1 M righe < 1 s per filtro.
7. Checklist manuale per milestone
Con docker compose -f deploy/docker-compose.sqlite.yml up (dalla milestone in cui la funzione esiste):
- accesso del super utente e cambio password obbligatorio
- creazione di un amministratore e di una seconda azienda
- utente standard con ruolo limitato
- tema scuro + colore di accento; menu compresso
- dashboard personalizzata e ripristinata dopo nuovo accesso
- caricamento dati di base e demo
- fattura → PDF allegato → XML FatturaPA
- prima nota; liquidazione IVA
- backup → prova di ripristino
- attività programmata eseguita
- log filtrato per sezione e per traccia
8. Documentazione nella stessa unità di lavoro
Una funzione senza documentazione non è finita. Nello stesso commit/PR si aggiornano:
- la pagina wiki in
docs/wiki/(stato bozza → completa alla consegna, data di revisione, versione); - i file tecnici toccati (
DATA-MODEL.md,API.md,MODULES.md, …); CHANGELOG.md(sezione Unreleased);- gli screenshot in
docs/wiki/img/eDesign-UI.mdse l'interfaccia cambia; - un ADR se si è presa una decisione.
La wiki si pubblica nel wiki Gitea da wiki.yml (push su main che tocca docs/wiki/**) o con
scripts/publish-wiki.sh. Non si modifica la wiki dall'editor web di Gitea: verrebbe sovrascritta.
9. CI e rilascio (ADR 0009)
| Workflow | Quando parte | Cosa fa |
|---|---|---|
.gitea/workflows/ci.yml |
PR verso main; push su main che toccano codice; tag v*; manuale |
allowlist, build -warnaserror, test SQLite; job PostgreSQL solo su tag e manuale |
.gitea/workflows/release.yml |
tag v*; manuale |
immagine, smoke test /health/live, push nel registro Gitea, release con note dal CHANGELOG.md |
.gitea/workflows/wiki.yml |
push su main che tocca docs/wiki/** |
sincronizza il wiki Gitea |
ci.yml costruisce e prova anche l'immagine (job Docker image: /health/live, utente PUID/PGID, pg_dump)
su PR, push e avvio manuale; sui tag lo fa release.yml. Un controllo YAML (Ruby) valida workflow e compose.
| Nome | Tipo | Uso |
|---|---|---|
REGISTRY_TOKEN |
segreto di organizzazione (già presente) | login al registro e controllo delle versioni già pubblicate; permesso pacchetti lettura e scrittura |
REGISTRY_USER |
variabile (facoltativa) | utente del login al registro; predefinito: chi ha spinto il tag (github.actor), che deve essere il proprietario del token |
REGISTRY, PUBLIC_URL |
variabili (facoltative) | host del registro e indirizzo pubblico di Gitea; predefiniti gitea.encke-hake.ts.net |
WIKI_TOKEN |
segreto (facoltativo) | solo se il token automatico del job non può scrivere nel wiki |
| token automatico | del job | checkout, archivio per il controllo YAML, release Gitea, wiki |
Il runner (act_runner in modalità Docker, etichetta ubuntu-latest) deve vedere il daemon Docker dell'host: i job
senza container: usano la CLI docker dell'immagine del runner, come in Chronos. Il runner è condiviso con altri
progetti: niente matrici superflue (solo PostgreSQL 16/17 sui tag), concurrency con cancellazione dei job superati,
timeout-minutes su ogni job. Ciò che un job annullato lascia sull'host (container, reti, immagini con l'etichetta
khaemhat-ci.job) lo rimuove il job successivo.
Rilascio (ADR 0015): CHANGELOG.md con la sezione ## [X.Y.Z] - data, commit su main, poi
git tag -a vX.Y.Z -m "Khaemhat X.Y.Z" && git push origin vX.Y.Z. Tag git vX.Y.Z, immagine X.Y.Z (più latest
se non è una pre-release). Se si è pubblicato con publish-image.sh, il push del tag crea solo la release.
10. Chiusura di una milestone
L'issue Chiusura milestone verifica la Definition of Done (SPEC §20):
- compila senza warning;
check-packages.shetest.shverdi su SQLite (e PostgreSQL se disponibile) - maschere raggiungibili dal menu, protette da permessi e licenza, localizzate, coerenti con i mockup
- migrazioni da zero e idempotenti; seed base e demo estesi
- log per sezione dei nuovi moduli
- wiki delle funzioni consegnate completa;
docs/*.mdaggiornati;CHANGELOG.md docs/STATUS.mdaggiornato con il punto di ripresa- versione nei file di
deploy/(KHAEMHAT_VERSIONdei compose e di.env.example,<Repository>del template Unraid); icona versionata conscripts/build.sh --iconse cambiamajor.minordalla 1.0 in poi (ADR 0016) - commit, tag
vX.Y.Z, immaginegitea.encke-hake.ts.net/balbosoft/khaemhat:X.Y.Z, release Gitea - l'immagine si costruisce in locale e la demo SQLite parte da zero
- le issue della milestone successiva passano in Da fare
11. Etichette Gitea
| Gruppo | Valori |
|---|---|
Area/… |
Fondamenta, Dati, Sicurezza e licenze, Interfaccia, Anagrafiche e articoli, Documenti e vendite, Acquisti e magazzino, Contabilità e IVA, Tesoreria, Fatturazione elettronica, CRM e servizi, Amministrazione, Automazioni e API, Docker e CI, Documentazione |
Kind/… |
Feature, Enhancement, Bug, Documentation, Testing, Security, Chiusura milestone |
Priority/… |
Critical, High, Medium, Low |
Status/… |
Blocked, In attesa utente, Need More Info, Abandoned |
Reviewed/… |
Confirmed, Duplicate, Invalid, Won't Fix |
Compat/Breaking |
modifica incompatibile (schema, API, configurazione) |
Modulo/… |
CORE, ACCT, ASSET, FIN, EINV, INTRA, CRM, SVC, CHAN, AUTO, API, MULTI, REPORT |