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

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.md con emendamenti E1-E7.
  • ADR 0001-0043.
  • Mockup in docs/mockups/ (22 in alta risoluzione + galleria, 88 miniature, mockup.css, indice).
  • Icone in assets/; deploy in deploy/ (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): soluzione Khaemhat.sln con 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.Web con pagina "in costruzione", icone, /health/live, /health/ready, /health (ADR 0012); docker/Dockerfile, entrypoint.sh con PUID/PGID (ADR 0013), postgres/init.sql; deploy/docker-compose.yml e docker-compose.sqlite.yml; Gitea Actions ci.yml, release.yml, wiki.yml con controllo YAML; script di build, test, avvio, pubblicazione e stub; ADR 0012-0017.
  • M1 (chiusa, v0.1.0, PR #116): micro-ORM in Khaemhat.Data (mappe, query tipizzate, SqlFragment, unit of work, repository con audit e row_version), provider SQLite e PostgreSQL, DatabaseUrl, migrazioni con schema_version, tabelle sys_companies e sys_settings, CompanyRegistry con URL cifrato, SecretProtector (AES-256-GCM, formato khs1), tools/Khaemhat.DataModelTool e gli script new-migration.sh e gen-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 varianti Alt; testi in Resources/it-IT/*.json con test anti-testo-letterale; preferenze utente e Il mio profilo (aspetto, pagina iniziale, dati personali, password e 2FA, sessioni, scorciatoie); libreria Kh* con campi all'italiana, toolbar a icone, intestazione documento e basi RecordPage/DocumentPage/MasterDataPage; liste con ListQuery/ListFields, KhGrid virtualizzata, KhRadar e KhLinesGrid; dashboard a widget con layout per utente e per ruolo e company_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 in docs/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 fiscale IT 2026.3 (codici IVA, nature, code list FatturaPA, motore IVA, calendario, ritenute, F24; ADR 0025); validatori e ViesClient; 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) e scripts/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 e document_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 movimento APE; 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, SDD pain.008 e bonifici pain.001 con 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 FatturaPA FPR12/FPA12/FSM10 con 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, job einvoice.poll e 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 file SCAMBI.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)

  1. 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.
  2. 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).
  3. PUID/PGID e utente non root (§16.1): proposta di avviare come root e scendere di privilegi con setpriv nell'entrypoint; da decidere con ADR in M0. Deciso in M0: ADR 0013.
  4. Varianti _FILE definite solo per KHAEMHAT_SYSTEM_DB e KHAEMHAT_SUPERUSER_*: proposta di estenderle a tutte le variabili sensibili (incluso KHAEMHAT_SECRET_KEY). Deciso in M0: ADR 0014.
  5. Salute: la specifica ha /health/live e /health; /health/ready e le metriche sono da definire. Deciso in M0: ADR 0012.
  6. Tag e doppia build: publish-image.sh (Appendice D) crea il tag git, ma con release.yml sui tag v* l'immagine verrebbe costruita due volte. Proposta: lo script non crea tag, oppure release.yml salta le versioni già nel registro. Deciso in M0: ADR 0015.
  7. Formato tag: tag git vX.Y.Z, tag immagine X.Y.Z (senza v). Deciso in M0: ADR 0015.
  8. Icona versionata: build.sh deve produrre PNG, serve un rasterizzatore; proposta: generarla sulla macchina di sviluppo e committarla prima del rilascio. Deciso in M0: ADR 0016.
  9. 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).
  10. Il mockup 085 mostra ancora ghcr.io: l'app mostrerà il registro Gitea (ADR 0009).
  11. 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)

  1. 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.
  2. 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.
  3. 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.
  4. 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).
  5. 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).
  6. 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).
  7. Regola R-005 del mockup 072 "riapre in bozza" una fattura scartata: contrasta con l'immutabilità della fattura emessa.
  8. Codice campagne CMP-… (068) non presente nelle maschere di §11.12.
  9. Codice di scarto 00327 citato in §18 senza descrizione.
  10. SdICoop richiede un servizio esposto raggiungibile dallo SDI: requisito di rete per Docker/Unraid non trattato da SPEC.
  11. Codici permesso: SPEC ne definisce pochi; gli altri nella wiki seguono modulo.entità.azione e sono indicativi.

Amministrazione, licenze, sicurezza (dalla stesura delle pagine di amministrazione e di SECURITY.md)

  1. 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.
  2. Licenza per azienda: il mockup 080 ha un campo Azienda, §8.2 descrive una licenza di istanza.
  3. Il mockup 081 dice che gli amministratori gestiscono "licenze operative"; §7.1 lo vieta. Seguito §7.1 (solo il super utente attiva).
  4. Operazioni sui database (nuova azienda, collega, clona, manutenzione, elimina): attribuite al solo super utente; §7.1 è ambiguo sugli amministratori.
  5. Impostazioni PEC: §12.9 le mette in Impostazioni, il mockup 086 non ha la scheda.
  6. Mockup 082 mostra 7 ruoli predefiniti invece degli 8 di §7.2 (manca Servizi).
  7. Nomi delle pagine di amministrazione diversi tra breadcrumb dei mockup e §12.
  8. docs/SECURITY.md contiene 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.
  9. Segnalazione vulnerabilità: Gitea non ha issue riservate e il repository è pubblico; serve un contatto privato del titolare.

Riferimenti tecnici (ARCHITECTURE, MODULES, API, MCP, Fiscalità)

  1. 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).
  2. Percorsi API: §15 dice /api/v1/{modulo}/{risorsa} ma l'elenco mescola risorse con e senza prefisso di modulo; ADR prima della v1.
  3. Modulo Automazioni: §4 non elenca Modules/Automation/ ma serve un IModule con codice AUTO (ADR in M12).
  4. Sezioni di log mancanti in §9.5 per anagrafiche/tabelle, tesoreria, servizi, report: proposte in docs/MODULES.md.
  5. Idempotency-Key delle API richiede una tabella non prevista da SPEC (da aggiungere in M12).
  6. Errori RFC 9457: SPEC usa trace_id, l'API è camelCase; proposto traceId.
  7. 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)

  1. Codici automatici e preferenze: §11.12 li mette nel modulo AUTO, ma sono funzioni di base (mockup 074, M4); documentati come CORE.
  2. Lead: §11.2 lo tratta come tipo di anagrafica (parties.kind), §11.10 e §22 come entità CRM separata (crm_leads). ADR da scrivere.
  3. 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.
  4. Maschera del codice articolo {categoria}-{seq:0000} contro i codici ART-0012 di mockup e seed.
  5. Codice IVA esente art. 10: ESE10 nel seed (§14), ESC10 nel mockup 076. Usato ESE10.
  6. Tema ad alto contrasto: richiesto dai token ma senza valori in mockup.css; da definire (AAA). auto risolto con prefers-color-scheme.
  7. TD28 descritto in modo impreciso in §11.5; usata la definizione ufficiale delle specifiche FatturaPA.
  8. Nomi delle schede delle anagrafiche diversi tra §10.5 e mockup 014/016 (seguiti i mockup).
  9. 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).
  10. Comportamenti non definiti: tredicesima scheda aperta, ripristino del layout della dashboard e layout per ruolo, tasto F nei campi data, consultazione del cestino allegati, criterio dei duplicati all'import, categorie di notifica.