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>
21 KiB
Stato del progetto
Punto di ripresa per ogni sessione. Aggiornare a fine sessione.
Ultimo aggiornamento: 2026-11-16
Milestone corrente: M11 — CRM e servizi (issue #88-#91), da iniziare. M10 chiusa: PR in main, tag v0.10.0,
immagine e release.
Prossimo passo: M11 dall'issue #88. Decisioni del titolare del 2026-11-16 (ADR 0044): le schermate senza PNG si
disegnano dalla miniatura e dalla grafica del gestionale (#35 chiusa); niente elenco banche ABI/CAB precaricato (#45
chiusa); intermediari, SdICoop e PEC reale rimandati (#78 nel backlog).
Da recuperare: misure di riferimento su PostgreSQL in docs/DATA-MODEL.md §6.1; indicatore di robustezza della
password (mockup 003); schede Layout salvati e Notifiche del profilo; rinomina e filtro predefinito nei radar;
logo PNG nel PDF (oggi solo JPEG, ADR 0034); coda della posta persistente e modelli e-mail per azienda (M12).
Da M6: schermata dell'import fatture con file caricati (serve un caricamento via CDP); nei movimenti di un articolo il
numero del fornitore al posto di DDT fornitore senza numero; FIFO e LIFO a lotti (dopo la 1.0).
Da M7: schermata del bollo virtuale (la demo non ha fatture esenti sopra 77,47 euro); import di causali e voci di
bilancio dal file khaemhat-coa.json; libro inventari (M13); IVA per cassa (fase 2).
Da M8: tracciati CBI e SEPA da provare con un home banking reale; tabella semestrale dei tassi di mora da aggiornare a
gennaio e luglio (ADR 0038); blocco per fido su ordini e documenti; report di tesoreria in Report (M12).
Da M9: schema XSD ufficiale FatturaPA al posto di quello scritto in casa (serve il permesso di scaricarlo);
intermediari reali e accreditamento SdICoop (#78 nel backlog, ADR 0040 e 0044); conformità PDF/A-3 dichiarata della copia di cortesia;
pulsanti Carica e Rimuovi dati di esempio nell'interfaccia (M12).
Da M10: file SCAMBI.CEE da verificare con il software di controllo delle Dogane prima del primo invio (ADR 0042);
differenze di cambio calcolate sul residuo attuale della partita (ADR 0043); TFR stimato (retribuzioni / 13,5);
annullare il passo 2 della chiusura toglie tutti gli ammortamenti dell'anno (ADR 0041); il gruppo dichiarazione
d'intento nei dati fiscali del cliente è ora uno specchio del registro (si potrebbe renderlo di sola lettura con un
collegamento al registro); rivalutazioni senza regole guidate.
Fatto
- Specifica normativa in
docs/SPEC.md;CLAUDE.mdcon emendamenti E1-E7. - ADR 0001-0043.
- Mockup in
docs/mockups/(22 in alta risoluzione + galleria, 88 miniature,mockup.css, indice). - Icone in
assets/; deploy indeploy/(compose Unraid,.env.example, template Unraid). - Documentazione tecnica:
ARCHITECTURE.md,DATA-MODEL.md(provvisorio, sarà generato),MODULES.md,API.md,MCP.md,DEPLOY.md,SECURITY.md,DEVELOPMENT.md. - Wiki completa in bozza in
docs/wiki/, pubblicata nel wiki Gitea. - M0 (chiusa,
v0.0.1): soluzioneKhaemhat.slncon i 10 progetti di SPEC §3 e 6 progetti di test; regole di build (Directory.Build.props/targets, Central Package Management con l'allowlist,.editorconfig, warning come errori); test architetturali delle dipendenze e dei pacchetti;Khaemhat.Webcon pagina "in costruzione", icone,/health/live,/health/ready,/health(ADR 0012);docker/Dockerfile,entrypoint.shconPUID/PGID(ADR 0013),postgres/init.sql;deploy/docker-compose.ymledocker-compose.sqlite.yml; Gitea Actionsci.yml,release.yml,wiki.ymlcon controllo YAML; script di build, test, avvio, pubblicazione e stub; ADR 0012-0017. - M1 (chiusa,
v0.1.0, PR #116): micro-ORM inKhaemhat.Data(mappe, query tipizzate,SqlFragment, unit of work, repository con audit erow_version), provider SQLite e PostgreSQL,DatabaseUrl, migrazioni conschema_version, tabellesys_companiesesys_settings,CompanyRegistrycon URL cifrato,SecretProtector(AES-256-GCM, formatokhs1),tools/Khaemhat.DataModelToole gli scriptnew-migration.shegen-datamodel.sh; ADR 0018. Test: 106 test dello strato dati verdi su SQLite in locale e su PostgreSQL 16 e 17 in CI (in locale Docker non è disponibile). - M2 (chiusa,
v0.2.0, PR #118): avvio da variabili con elenco degli errori, migrazioni all'avvio, super utente e prima azienda; account di istanza e aziendali, password con storico e blocco, sessioni nel database, TOTP con codici di recupero, pagine di accesso (mockup 001-003); ruoli, permessi e attributi di autorizzazione; licenze firmate, codici di attivazione, modalità test,tools/Khaemhat.LicenseTool; DataProtection nel database cifrata; cache memoria/Redis (client RESP in casa); log su database per sezioni con traccia; attività programmate con cron, lock e job di sistema; storico dei record; aziende con stati e contesto (X-Company); header di sicurezza; ADR 0019. Test: 180 verdi in locale, più 21 di PostgreSQL saltati senza Docker (girano in CI). La chiave privata delle licenze è fuori dal repository (Khaemhat-private/khaemhat-license.khkey) e va conservata dal titolare. - M3 (chiusa,
v0.3.0, PR #119): shell con barra superiore, menu comprimibile con sottomenu a comparsa, schede tenute in vita, barra di stato, scorciatoie con variantiAlt; testi inResources/it-IT/*.jsoncon test anti-testo-letterale; preferenze utente e Il mio profilo (aspetto, pagina iniziale, dati personali, password e 2FA, sessioni, scorciatoie); libreriaKh*con campi all'italiana, toolbar a icone, intestazione documento e basiRecordPage/DocumentPage/MasterDataPage; liste conListQuery/ListFields,KhGridvirtualizzata,KhRadareKhLinesGrid; dashboard a widget con layout per utente e per ruolo ecompany_settings; ricerca globale a fornitori, aiuto in app dalla copia della wiki, pannello notifiche; allegati con anteprime, Genera file, ZIP, cestino e storico; anteprima di stampa A4; catalogo dei componenti e documento di prova per gli sviluppatori; primi screenshot reali indocs/wiki/img/; ADR 0020-0024. Test: 368 verdi in locale, 21 di PostgreSQL saltati; immagine costruita in locale e avviata da zero con SQLite. - M4 (chiusa,
v0.4.0, PR #121): pacchetto fiscaleIT 2026.3(codici IVA, nature, code list FatturaPA, motore IVA, calendario, ritenute, F24; ADR 0025); validatori eViesClient; 26 tabelle azienda con un'unica maschera, profilo azienda, esercizi e cambi BCE (ADR 0026); dati di base con province e comuni ISTAT e CAP GeoNames (ADR 0028) escripts/seed.sh --base|--demo; codici automatici e compilazione automatica (ADR 0027); clienti, fornitori e contatti con radar, scheda, controlli e VIES (ADR 0029); articoli e listini con prezzi a validità, listini derivati e aggiornamento massivo (ADR 0030); import/export guidato CSV/XLSX/JSON con tracciato del piano dei conti (ADR 0031); 21 anagrafiche e 120 articoli di esempio; screenshot reali nella wiki. Test: 631 verdi in locale, 21 di PostgreSQL saltati; immagine costruita in locale e avviata da zero con SQLite e dati di esempio. - M5 (chiusa,
v0.5.0, PR #124): motore documenti (#47, ADR 0032): generi e definizioni dei tipi documento, sei famiglie di tabelle con le righe edocument_links, stati con azioni ammesse, numerazione atomica alla conferma (provata in concorrenza su SQLite e su PostgreSQL 18 in locale), copia e trasformazione con evasione riga per riga; totali, castelletto IVA, bollo, ritenute, cassa e scadenze (#48, ADR 0033); radar e maschera dei documenti di vendita con Crea … (#49, #50); fatturazione differita guidata (#51); anteprima di stampa e PDF dallo stesso modello, invio per e-mail con SMTP e coda scritti in casa (#52, ADR 0034); log Documenti; profilo e un anno di vendite di esempio; wiki con la Guida all'uso e le schermate reali, README come guida per sviluppatori (#53). Test: 660 verdi in locale, 23 di PostgreSQL saltati (girano in CI). - M6 (chiusa,
v0.6.0, PR #125): movimenti di magazzino dai documenti nella stessa transazione, costo medio ponderato ricalcolato dalla storia, impegnato e ordinato, correzione del costo dalla fattura fornitore (#59, ADR 0035); ordini fornitori, ricevimenti, fatture e note di credito fornitore con protocollo, doppioni rifiutati, controllo dei prezzi, autofatture TD16-TD29 consigliate dal pacchetto italiano con scadenza (#55, #56, #58); lettura FatturaPA e.p7m(CMS scritto in casa) e import delle fatture passive in bozza (#57); giacenze, movimenti di un articolo, inventario fisico, proposta di riordino, valorizzazione con classi ABC, ricostruzione anche come job settimanale, widget Sottoscorta (#60); giacenze iniziali da file con movimentoAPE; acquisti e magazzino nei dati di esempio, wiki Acquisti e Magazzino con le schermate, guida all'uso (#61). Test: 709 verdi in locale, 23 di PostgreSQL saltati (girano in CI). - M7 (chiusa,
v0.7.0): piano dei conti a tre livelli con il modello PMI standard di 237 conti, causali con righe proposte (#62, ADR 0036); prima nota con bozze, registrazioni, definitive con numero del libro giornale e storni, ricorrenti con job giornaliero (#63); contabilizzazione automatica di fatture, note, parcelle e autofatture nella transazione del documento con righe IVA, partite e ritenute (#64, ADR 0037); registri IVA con stampa definitiva, liquidazione mensile o trimestrale con pro rata, interessi, minimo, acconto, F24 e LIPE (#65); ritenute operate e subite, dati CU, bollo virtuale con soglie, prospetto F24 con pagamento (#66); partitari, mastrini, bilancio di verifica, libro giornale (#67); contabilità nei dati di esempio con la liquidazione verificata a mano in un test, wiki Contabilità, IVA e Fiscalità italiana con le schermate (#68). Test: 754 verdi in locale, 23 di PostgreSQL saltati (girano in CI). - M8 (chiusa,
v0.8.0): scadenzario sulle partite della contabilità con aging, incassi e pagamenti multipli e parziali con abbuoni, spese, cambi e storno (#69, ADR 0038); distinte RiBa CBI, SDDpain.008e bonificipain.001con presentazione, anticipo s.b.f., accredito e insoluti, mandati SDD (#70); riconciliazione bancaria CSV/CBI/CAMT.053 senza doppioni con confidenza e regole (#71); solleciti a tre livelli con interessi di mora e job automatico, flusso di cassa, scadenze sulla Home (#72); tesoreria nei dati di esempio con FIN, wiki Scadenzario con le schermate (#73). Test: 823 verdi in locale, anche quelli di PostgreSQL (18) con un container locale. - M9 (chiusa,
v0.9.0): file FatturaPAFPR12/FPA12/FSM10con controllo offline dei codici SDI e schema scritto in casa (#74, ADR 0039); notifiche RC/NS/MC/NE/DT/AT/SE/MT senza doppioni che muovono file e documento, correzione degli scarti, copia di cortesia PDF con l'XML allegato (#75); canali PEC (IMAP e MIME in casa), SdICoop SOAP/MTOM e due intermediari generici con instradamento e riserva, jobeinvoice.polle push SdICoop su/sdicoop/{azienda}(#76, #77, ADR 0040); fatture ricevute da registrare e pacchetti di conservazione (#79); fatturazione nei dati di esempio e rimozione dei dati di esempio guidata dallo schema (#80); wiki Fatturazione elettronica con le schermate (#81). #78 (scelta degli intermediari, accreditamento SdICoop) resta aperta. Test: 874 verdi in locale, anche quelli di PostgreSQL (18) con un container locale. - M10 (chiusa,
v0.10.0): cespiti con categorie ministeriali, piano civilistico e fiscale, ammortamenti per categoria annullabili, dismissioni e registro (#82, ADR 0041); elenchi Intrastat dai documenti con periodicità dalle soglie e fileSCAMBI.CEE, registro delle dichiarazioni d'intento con controllo del plafond alla conferma (#83, ADR 0042); ratei e risconti per giorni e differenze di cambio (#84); chiusura guidata in nove passi ripetibili e annullabili con riapertura, stampe definitive e blocco (#85); bilancio CEE ordinario, abbreviato e micro con riclassificato, indici, stampa ed export per il commercialista (#86, ADR 0043); dati di esempio di fine anno e chiusura completa dell'anno demo come prova di accettazione (#87); wiki Cespiti, Intrastat, Dichiarazioni d'intento, Chiusura e bilancio con le schermate. Test: 907 verdi in locale, anche quelli di PostgreSQL con un container locale. - Su Gitea: etichette, milestone M0-M14, 114 issue con checklist, progetti Khaemhat 1.0 — Sviluppo (M0-M13) e Khaemhat 1.1+ — Fase 2 (M14). Numerazione: M0 #1-#6 e #114, M1 #7-#14, M2 #15-#24, M3 #25-#36, M4 #37-#46, M5 #47-#54, M6 #55-#61, M7 #62-#68, M8 #69-#73, M9 #74-#81, M10 #82-#87, M11 #88-#91, M12 #92-#100, M13 #101-#107, M14 #108-#113.
Ambiente verificato
Rilevato il 2026-11-11 sulla macchina di sviluppo (Windows 11, Git Bash per gli script):
| Strumento | Versione |
|---|---|
| .NET SDK | 10.0.403 (global.json: 10.0.100, rollForward: latestFeature) |
| Docker | 29.1.3 (Docker Desktop, daemon da avviare a mano) |
| Git | 2.54 |
| Runner Gitea Actions | act_runner in modalità Docker, etichetta ubuntu-latest (condiviso con Chronos) |
In attesa del titolare
- Prova del template su Unraid (issue #106).
- Un contatto privato per la segnalazione di vulnerabilità (vedi
SECURITY.md).
Punti aperti della specifica
Tracciati dall'issue #114.
Emersi durante la stesura della documentazione. Si decidono con un ADR quando si arriva alla milestone che li tocca (o prima, se il titolare preferisce indicarli); nel frattempo la wiki li segnala come "da definire in sviluppo".
Installazione, aggiornamento, backup (dalla stesura di DEPLOY e wiki installazione)
scripts/restore-system.shè l'unico modo di ripristinare il DB di sistema (§13), ma gli script non sono distribuiti (ADR 0010): oggi la wiki dice di scaricarlo dal repository. Valutare di includerlo nell'immagine (/app/scripts/). Deciso in M0: ADR 0017.- Backup cifrati con
KHAEMHAT_SECRET_KEY: manca uno strumento di decifratura fuori dall'app e non è definito cosa succede ai backup vecchi dopo la rotazione della chiave (oggi: conservare la chiave vecchia per tutta la retention). PUID/PGIDe utente non root (§16.1): proposta di avviare come root e scendere di privilegi consetprivnell'entrypoint; da decidere con ADR in M0. Deciso in M0: ADR 0013.- Varianti
_FILEdefinite solo perKHAEMHAT_SYSTEM_DBeKHAEMHAT_SUPERUSER_*: proposta di estenderle a tutte le variabili sensibili (inclusoKHAEMHAT_SECRET_KEY). Deciso in M0: ADR 0014. - Salute: la specifica ha
/health/livee/health;/health/readye le metriche sono da definire. Deciso in M0: ADR 0012. - Tag e doppia build:
publish-image.sh(Appendice D) crea il tag git, ma conrelease.ymlsui tagv*l'immagine verrebbe costruita due volte. Proposta: lo script non crea tag, oppurerelease.ymlsalta le versioni già nel registro. Deciso in M0: ADR 0015. - Formato tag: tag git
vX.Y.Z, tag immagineX.Y.Z(senzav). Deciso in M0: ADR 0015. - Icona versionata:
build.shdeve produrre PNG, serve un rasterizzatore; proposta: generarla sulla macchina di sviluppo e committarla prima del rilascio. Deciso in M0: ADR 0016. - Rotazione della password PostgreSQL: l'URL del database di ogni azienda è cifrato per intero in
sys_companies(ADR 0018); serve una procedura di aggiornamento (M12). - Il mockup 085 mostra ancora
ghcr.io: l'app mostrerà il registro Gitea (ADR 0009). - Non definiti: schermata di attivazione TOTP, nome dell'impostazione "migra aziende all'avvio", recupero password del super utente senza SMTP, chi modifica le impostazioni di backup cloud (scritto: super utente), flusso di ripristino da backup logico.
Contabilità, IVA, e-fattura, CRM (dalla stesura delle pagine funzionali)
- Scadenza IVA di settembre: mockup 046 la mette al 16/10/2026, mockup 047 nell'F24 del 16/11/2026 (corretto: 16/10 per i mensili). Deciso in M7: ADR 0037, il 16 del mese successivo.
- Bollo sulle cessioni intracomunitarie: il mockup 060 lo addebita su N3.2, ma cessioni intra-UE ed esportazioni ne sono esenti; la regola del bollo va legata al codice IVA con esclusioni.
- Funzioni di fase 2 nelle schermate di M7: ventilazione dei corrispettivi (046) e IVA per cassa completa sono in M14 per §20. Confermato in M7: non implementate.
- Moduli ambigui: bollo e dichiarazioni d'intento sotto ACCT e EINV (§8.1); export commercialista sotto ACCT e REPORT; Intrastat e LIPE nel menu e-fattura nei mockup; §10.2 senza voce Intrastat. Deciso in M10: dichiarazioni d'intento in CORE, Intrastat in INTRA nel menu e-fattura, export commercialista in ACCT con il permesso
reports.accountant.export(ADR 0042, 0043). - Stato "Provvisorio" dell'esercizio nel mockup 052, non previsto da SPEC (aperto / in chiusura / chiuso). Deciso in M10: restano i tre stati di SPEC; "in chiusura" dal passo 6, "chiuso" con il blocco (ADR 0043).
- Codici conto incoerenti tra mockup (fornitori 05.02.001 in 040/043, 02.03.001 in 042). Deciso in M7: ADR 0036, piano PMI standard (clienti 05.01.001, fornitori 14.01.001).
- Regola R-005 del mockup 072 "riapre in bozza" una fattura scartata: contrasta con l'immutabilità della fattura emessa.
- Codice campagne
CMP-…(068) non presente nelle maschere di §11.12. - Codice di scarto 00327 citato in §18 senza descrizione.
- SdICoop richiede un servizio esposto raggiungibile dallo SDI: requisito di rete per Docker/Unraid non trattato da SPEC.
- Codici permesso: SPEC ne definisce pochi; gli altri nella wiki seguono
modulo.entità.azionee sono indicativi.
Amministrazione, licenze, sicurezza (dalla stesura delle pagine di amministrazione e di SECURITY.md)
- Formato del codice di attivazione: §8.2 (
KH<v>-<MODULO>-<AAAAMM>-<payload>-<firma>), codici test §8.3 (KH-TEST-<MODULO>-0000-000N) e suggerimento del mockup 080 non coincidono. Documentato §8.2 come definitivo. - Licenza per azienda: il mockup 080 ha un campo Azienda, §8.2 descrive una licenza di istanza.
- Il mockup 081 dice che gli amministratori gestiscono "licenze operative"; §7.1 lo vieta. Seguito §7.1 (solo il super utente attiva).
- Operazioni sui database (nuova azienda, collega, clona, manutenzione, elimina): attribuite al solo super utente; §7.1 è ambiguo sugli amministratori.
- Impostazioni PEC: §12.9 le mette in Impostazioni, il mockup 086 non ha la scheda.
- Mockup 082 mostra 7 ruoli predefiniti invece degli 8 di §7.2 (manca Servizi).
- Nomi delle pagine di amministrazione diversi tra breadcrumb dei mockup e §12.
docs/SECURITY.mdcontiene proposte da confermare con ADR: HKDF per la derivazione delle chiavi, formati di cifrato e hash, id di sessione e token salvati come hash, parametri TOTP e anti-replay, HMAC-SHA256 con timestamp per i webhook, protezioni XXE/zip-bomb/formula injection, audit di sicurezza a catena di hash, JSON canonico per la firma delle licenze, ForwardedHeaders dietro proxy.- Segnalazione vulnerabilità: Gitea non ha issue riservate e il repository è pubblico; serve un contatto privato del titolare.
Riferimenti tecnici (ARCHITECTURE, MODULES, API, MCP, Fiscalità)
- Soglia minima di versamento IVA: SPEC §11.7 indica 25,82 €; il D.Lgs. 1/2024 l'ha portata a 100 € (da verificare e rendere parametro del pacchetto fiscale).
- Percorsi API: §15 dice
/api/v1/{modulo}/{risorsa}ma l'elenco mescola risorse con e senza prefisso di modulo; ADR prima della v1. - Modulo Automazioni: §4 non elenca
Modules/Automation/ma serve unIModulecon codice AUTO (ADR in M12). - Sezioni di log mancanti in §9.5 per anagrafiche/tabelle, tesoreria, servizi, report: proposte in
docs/MODULES.md. Idempotency-Keydelle API richiede una tabella non prevista da SPEC (da aggiungere in M12).- Errori RFC 9457: SPEC usa
trace_id, l'API è camelCase; propostotraceId. - Fatti fiscali aggiunti nella wiki Fiscalita-italiana da verificare in sviluppo: scadenze LIPE, scadenze trimestrali del bollo con soglia di 5.000 €, fattura differita entro il 15 del mese successivo.
Interfaccia, anagrafiche, documenti (dalla stesura delle pagine CORE)
- Codici automatici e preferenze: §11.12 li mette nel modulo AUTO, ma sono funzioni di base (mockup 074, M4); documentati come CORE.
- Lead: §11.2 lo tratta come tipo di anagrafica (
parties.kind), §11.10 e §22 come entità CRM separata (crm_leads). ADR da scrivere. - Import XML/P7M passivo e autofatture: §11.5 li mette in CORE, §8.1 in EINV. Documentato: import da file e documenti in CORE; scarico da SDI e invio XML in EINV.
- Maschera del codice articolo
{categoria}-{seq:0000}contro i codiciART-0012di mockup e seed. - Codice IVA esente art. 10:
ESE10nel seed (§14),ESC10nel mockup 076. UsatoESE10. - Tema ad alto contrasto: richiesto dai token ma senza valori in
mockup.css; da definire (AAA).autorisolto conprefers-color-scheme. - TD28 descritto in modo impreciso in §11.5; usata la definizione ufficiale delle specifiche FatturaPA.
- Nomi delle schede delle anagrafiche diversi tra §10.5 e mockup 014/016 (seguiti i mockup).
- Elementi solo nei mockup e assenti nel modello dati: lotto (037), ubicazione (038), soglie 80%/100% della dichiarazione d'intento (015), formula del fabbisogno (039), cartella
/data/inbox/sdi(034). - Comportamenti non definiti: tredicesima scheda aperta, ripristino del layout della dashboard e layout per ruolo, tasto
Fnei campi data, consultazione del cestino allegati, criterio dei duplicati all'import, categorie di notifica.