Files
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

9.8 KiB

KHAEMHAT — memoria di progetto per Claude Code

Questo file vale per ogni sessione di lavoro sul repository. È corto di proposito: la specifica completa e normativa è docs/SPEC.md (il prompt di progetto originale, intatto). Qui stanno le regole operative e gli emendamenti che adattano la specifica all'infrastruttura reale (Gitea al posto di GitHub, distribuzione solo Docker). Dove un emendamento e la specifica divergono, vale l'emendamento.


1. Cos'è Khaemhat

Gestionale ERP + CRM per PMI italiane, costruito da zero in C# 14 / .NET 10, interfaccia Blazor Server, PostgreSQL (o SQLite per demo e test), distribuito solo come immagine Docker nel registro pacchetti di Gitea. Più aziende sulla stessa istanza (un database di sistema + un database per azienda), moduli attivabili con licenza, fiscalità italiana isolata in un pacchetto paese.

Il nome viene da Khaemhat (detto anche Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto Amenhotep III (XVIII dinastia, circa 1388-1350 a.C.), sepolto nella tomba TT57 a Sheikh Abd el-Qurna, Tebe ovest. Era responsabile della raccolta, dell'immagazzinamento e della distribuzione del grano del regno: un contabile e un magazziniere dell'antichità. Vedi la pagina wiki Origine del nome.

2. Dove sono le cose

Cosa Dove
Specifica normativa (sezioni §0-§23, appendici A-D) docs/SPEC.md
Stato di avanzamento, punto di ripresa docs/STATUS.md
Decisioni architetturali docs/adr/NNNN-titolo.md
Processo di sviluppo, checklist, Definition of Done docs/DEVELOPMENT.md
Mockup (specifica visiva vincolante) docs/mockups/ — indice in docs/mockups/README.md
Token e componenti CSS di riferimento docs/mockups/mockup.css
Wiki (sorgente) docs/wiki/ → pubblicata nel wiki Gitea del repository
Icone assets/
File di deploy (Unraid, compose, .env) deploy/
Lavori da fare issue Gitea, raggruppate per milestone (M0…M14) e nel progetto Khaemhat 1.0

Gitea: https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat (in LAN http://192.168.30.23:3000, SSH ssh://git@192.168.30.23:2222/BalboSoft/Khaemhat.git). Organizzazione BalboSoft, repository pubblico.

3. Emendamenti alla specifica

E1 — Gitea al posto di GitHub (sostituisce §1.13, §4 .github/, §6 KHAEMHAT_UPDATE_FEED, §12.8, §16.2, §16.3, §16.6, §17, Appendici C e D; ADR 0009).

  • Repository, issue, milestone, progetti, wiki e pacchetti stanno su Gitea. Nessun uso di GitHub o GHCR.
  • I workflow sono Gitea Actions in .gitea/workflows/ ed eseguono su act_runner self-hosted (modalità Docker, etichetta ubuntu-latest, sullo stesso server di Gitea, un job alla volta). I job .NET usano il container mcr.microsoft.com/dotnet/sdk:10.0 e fanno il checkout con git (l'immagine SDK non ha Node.js, quindi niente actions/checkout), come nel repository Chronos. Al posto dei "minuti contati" vale il risparmio delle risorse del server: CI su pull request verso main, push su main che toccano codice (paths-ignore per docs/**, *.md, assets/**, deploy/**), tag v* e avvio manuale; niente matrici superflue.
  • Immagine: gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione> (e :latest solo come comodità, mai in produzione). Pubblicata dal workflow release.yml sui tag v* (segreto REGISTRY_TOKEN con permesso write:package) oppure in locale con scripts/publish-image.sh.
  • Icona per Unraid e template: URL raw del repository pubblico, ad esempio https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/assets/icon-v1.0-256.png. Il repository separato khaemhat-assets non serve.
  • Wiki: sorgente docs/wiki/, pubblicata nel wiki Gitea (Khaemhat.wiki.git) da wiki.yml (push su main che tocca docs/wiki/**) o da scripts/publish-wiki.sh.
  • Controllo aggiornamenti (§12.8, mockup 085): GiteaPackagesClient (al posto di GhcrPackagesClient) legge GET /api/v1/packages/BalboSoft?type=container&q=khaemhat; KHAEMHAT_UPDATE_FEED contiene quell'URL, KHAEMHAT_UPDATE_TOKEN un token di sola lettura se il pacchetto non è pubblico.
  • GITHUB_REPO_URL, GITHUB_OWNER, GITHUB_TOKEN diventano GITEA_URL, GITEA_OWNER, GITEA_TOKEN.

E2 — Solo Docker, nessun setup (ADR 0010). L'unico artefatto distribuito è l'immagine nel registro pacchetti di Gitea. Non si creano installer, setup, pacchetti .msi/.exe/.deb, release con binari o eseguibili desktop. Le release Gitea contengono solo le note (dal CHANGELOG.md).

E3 — Specifica in docs/SPEC.md (ADR 0011). La specifica originale dice di essere il CLAUDE.md: per non caricare 140 KB in ogni sessione è in docs/SPEC.md, invariata; questo file ne riassume le regole operative. I riferimenti alle immagini di SPEC (docs/mockups/png/…) restano validi.

E4 — Mockup disponibili (ADR 0011). Delle 88 schermate sono consegnate 22 in alta risoluzione in docs/mockups/png/ più la galleria completa 000-galleria-mockup.png; per tutte le 88 esiste una miniatura 401x241 ritagliata dalla galleria in docs/mockups/thumbs/. Per le schermate senza PNG ad alta risoluzione si lavora da miniatura + mockup.css + descrizione in SPEC §10-§12, scegliendo i mattoni della schermata più simile in alta risoluzione (§10.1 regola 4). Il titolare ha confermato il 2026-11-16 che altri PNG non esistono (ADR 0044): la miniatura è la specifica finale e i dettagli che non mostra si decidono seguendo la grafica del gestionale già costruita, senza chiederli.

E5 — Avvio dello sviluppo. La specifica (§0, §23) dice di lavorare in autonomia senza chiedere conferme. Vale, dopo il via esplicito dell'utente: la documentazione e la pianificazione su Gitea sono state preparate il 2026-11-10 e lo sviluppo parte solo quando l'utente lo dice. Da lì si procede milestone dopo milestone come in §20, fermandosi solo per blocchi reali (SDK mancante, credenziali, PNG o dati che solo l'utente può dare).

E6 — Commit e push. Un commit a fine sessione (regola globale dell'utente), messaggi Conventional Commits in inglese che dicono cosa cambia e perché. Il push su Gitea e le pull request seguono le indicazioni dell'utente; il tag vX.Y.Z si crea alla chiusura di ogni milestone (§20).

E7 — Versioni 0.x fino al via dell'utente (sostituisce la colonna versione di §20 per M13 e M14; deciso dall'utente il 2026-11-12). Finché il prodotto è in sviluppo le versioni restano 0.x: ogni milestone chiude con v0.<n>.0 (M13 v0.13.0, M14 v0.14.0 e seguenti). La 1.0.0 non si crea (tag, immagine, release, CHANGELOG) finché l'utente non lo dice esplicitamente. L'icona versionata icon-v1.0 resta il modello grafico.

4. Vincoli non negoziabili (sintesi di SPEC §1 — leggere l'originale)

  1. C# 14 su .NET 10; JavaScript solo come interop minimo in wwwroot/js, senza framework né bundler.
  2. Nessuna libreria esterna: solo framework condivisi Microsoft, Npgsql, Microsoft.Data.Sqlite, e nei soli test Microsoft.NET.Test.Sdk + MSTest. Allowlist in Directory.Packages.props, verificata da scripts/check-packages.sh. Niente CDN, font scaricati, script di terze parti.
  3. Codice indifferente al motore (SQLite / PostgreSQL ≥ 16); un DB di sistema + un DB per azienda; nessun company_id nelle tabelle operative.
  4. Configurazione iniziale solo da variabili d'ambiente KHAEMHAT_*; nessun file temporaneo con impostazioni o dati; scritture solo in KHAEMHAT_DATA_DIR.
  5. Redis opzionale con client RESP scritto in casa. Moduli dietro licenza (codici test in §8.3).
  6. Codice, commenti e commit in inglese; interfaccia in italiano tramite risorse.
  7. Tutto ciò che è italiano sta in Khaemhat.Fiscal.Italy dietro Khaemhat.Fiscal.Abstractions.
  8. Nullable, TreatWarningsAsErrors, analyzer di piattaforma, .editorconfig.
  9. Documentazione nella stessa unità di lavoro: wiki, docs/*.md, CHANGELOG.md, screenshot. Una funzione senza documentazione non è finita.

5. Come si lavora (dettagli in docs/DEVELOPMENT.md)

  • Ripresa di sessione: leggi questo file, docs/STATUS.md, le issue aperte della milestone corrente su Gitea, git log -20; se lavori sull'interfaccia anche docs/mockups/README.md e docs/wiki/Design-UI.md.
  • Unità di lavoro = issue Gitea. Ogni issue ha milestone, etichette Area/…, Kind/…, Priority/… e una checklist di passi. Ramo feat/<n>-breve-descrizione (o fix/…, docs/…), commit che citano #n, PR verso main con Closes #n. Spunta i passi della checklist man mano.
  • Decisioni: quando un punto è ambiguo decidi secondo SPEC, scrivi un ADR in docs/adr/ e prosegui.
  • Chiusura milestone: l'issue Chiusura milestone verifica la Definition of Done (SPEC §20), aggiorna wiki da bozza a completa, CHANGELOG.md, docs/STATUS.md, crea il tag e (da M0 in poi) l'immagine.
  • Blocchi: etichetta Status/In attesa utente + commento che dice esattamente cosa serve.

6. Etichette Gitea

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/… · Compat/Breaking · Modulo/… (codice licenza: CORE, ACCT, ASSET, FIN, EINV, INTRA, CRM, SVC, CHAN, AUTO, API, MULTI, REPORT).