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>
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 suact_runnerself-hosted (modalità Docker, etichettaubuntu-latest, sullo stesso server di Gitea, un job alla volta). I job .NET usano il containermcr.microsoft.com/dotnet/sdk:10.0e fanno il checkout congit(l'immagine SDK non ha Node.js, quindi nienteactions/checkout), come nel repository Chronos. Al posto dei "minuti contati" vale il risparmio delle risorse del server: CI su pull request versomain, push sumainche toccano codice (paths-ignoreperdocs/**,*.md,assets/**,deploy/**), tagv*e avvio manuale; niente matrici superflue. - Immagine:
gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione>(e:latestsolo come comodità, mai in produzione). Pubblicata dal workflowrelease.ymlsui tagv*(segretoREGISTRY_TOKENcon permessowrite:package) oppure in locale conscripts/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 separatokhaemhat-assetsnon serve. - Wiki: sorgente
docs/wiki/, pubblicata nel wiki Gitea (Khaemhat.wiki.git) dawiki.yml(push sumainche toccadocs/wiki/**) o dascripts/publish-wiki.sh. - Controllo aggiornamenti (§12.8, mockup 085):
GiteaPackagesClient(al posto diGhcrPackagesClient) leggeGET /api/v1/packages/BalboSoft?type=container&q=khaemhat;KHAEMHAT_UPDATE_FEEDcontiene quell'URL,KHAEMHAT_UPDATE_TOKENun token di sola lettura se il pacchetto non è pubblico. GITHUB_REPO_URL,GITHUB_OWNER,GITHUB_TOKENdiventanoGITEA_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)
- C# 14 su .NET 10; JavaScript solo come interop minimo in
wwwroot/js, senza framework né bundler. - Nessuna libreria esterna: solo framework condivisi Microsoft,
Npgsql,Microsoft.Data.Sqlite, e nei soli testMicrosoft.NET.Test.Sdk+MSTest. Allowlist inDirectory.Packages.props, verificata dascripts/check-packages.sh. Niente CDN, font scaricati, script di terze parti. - Codice indifferente al motore (SQLite / PostgreSQL ≥ 16); un DB di sistema + un DB per azienda; nessun
company_idnelle tabelle operative. - Configurazione iniziale solo da variabili d'ambiente
KHAEMHAT_*; nessun file temporaneo con impostazioni o dati; scritture solo inKHAEMHAT_DATA_DIR. - Redis opzionale con client RESP scritto in casa. Moduli dietro licenza (codici test in §8.3).
- Codice, commenti e commit in inglese; interfaccia in italiano tramite risorse.
- Tutto ciò che è italiano sta in
Khaemhat.Fiscal.ItalydietroKhaemhat.Fiscal.Abstractions. Nullable,TreatWarningsAsErrors, analyzer di piattaforma,.editorconfig.- 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 anchedocs/mockups/README.mdedocs/wiki/Design-UI.md. - Unità di lavoro = issue Gitea. Ogni issue ha milestone, etichette
Area/…,Kind/…,Priority/…e una checklist di passi. Ramofeat/<n>-breve-descrizione(ofix/…,docs/…), commit che citano#n, PR versomainconCloses #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).