Files
Khaemhat/docs/DEVELOPMENT.md
T
Alby96andClaude Opus 5.5 738c43ba0a
CI / Build and test (SQLite) (pull_request) Successful in 45s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 3s
CI / Docker image (pull_request) Successful in 51s
feat: data layer with SQLite and PostgreSQL providers, migrations and encrypted company registry (M1)
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>
2026-11-11 13:11:34 +01:00

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 avvia Khaemhat.Web in debug su http://localhost:5080 con le stesse variabili di scripts/run-dev.sh (SQLite in .data/dev, licenze di test, log Debug) 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

  1. Leggere CLAUDE.md e STATUS.md (punto di ripresa).
  2. Aprire la milestone corrente su Gitea e le sue issue in Da fare / In corso nel progetto Khaemhat 1.0 — Sviluppo.
  3. git log -20 per vedere l'ultimo lavoro.
  4. Se si lavora sull'interfaccia: mockups/README.md e la wiki Design-UI.md.

3. Unità di lavoro: issue Gitea

  • Ogni lavoro parte da un'issue con milestone, etichette Area/…, Kind/…, Priority/… (ed eventualmente Modulo/…) 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 da main.
  • 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 main con Closes #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 di CLAUDE.md prevalgono su SPEC.
  • Blocco reale (credenziali, SDK, PNG o dati che solo il titolare può dare): etichetta Status/In attesa utente e 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)

  • record per DTO e value object, sealed di default, decimal per importi e quantità (mai double).
  • DateOnly / DateTime in UTC; conversione a Europe/Rome solo 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.sh verde a ogni milestone: SQLite sempre; PostgreSQL con KHAEMHAT_TEST_PG; Redis con KHAEMHAT_TEST_REDIS; test in modalità licenza test.
  • Test di architettura: dipendenze tra progetti, allowlist dei pacchetti, nessun testo UI hard-coded, nessun accesso al pacchetto fiscale fuori dalle interfacce, nessun Process.Start fuori da Infrastructure/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/ e Design-UI.md se 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.sh e test.sh verdi 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/*.md aggiornati; CHANGELOG.md
  • docs/STATUS.md aggiornato con il punto di ripresa
  • versione nei file di deploy/ (KHAEMHAT_VERSION dei compose e di .env.example, <Repository> del template Unraid); icona versionata con scripts/build.sh --icon se cambia major.minor dalla 1.0 in poi (ADR 0016)
  • commit, tag vX.Y.Z, immagine gitea.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