Files
Khaemhat/docs/STATUS.md
T
Alby96andClaude Opus 5.5 a9eda510f2 feat: postal codes from GeoNames for the ISTAT municipalities (#45)
The municipalities now come with their postal codes, so the lookup from
postal code works on a new company without loading anything. GeoNames
(CC BY 4.0) lists places rather than municipalities: a postal code goes
to a municipality only when the name and the province abbreviation match
exactly one of them (the name alone within Sardinia, whose abbreviations
changed), which covers 7,750 of 7,894 municipalities; the rest are mostly
renamed or merged ones that users complete by hand.

tools/Khaemhat.PlacesTool rebuilds both lists from the ISTAT sheet and
the GeoNames file, framework only, so the yearly update is repeatable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:16:07 +01:00

14 KiB

Stato del progetto

Punto di ripresa per ogni sessione. Aggiornare a fine sessione.

Ultimo aggiornamento: 2026-11-12 Milestone corrente: M4 — Tabelle, anagrafiche, articoli (issue #37-#46), ramo feat/37-tabelle-anagrafiche. Fatti: pacchetto fiscale (#37), validatori e VIES (#40), tabelle azienda, profilo, esercizi e cambi con le maschere (#38, #39), dati di base e scripts/seed.sh --base (#45) con province e comuni ISTAT e CAP GeoNames (ADR 0028; mancano le banche ABI/CAB, senza fonte con licenza compatibile), codici automatici e compilazione automatica (#43). ADR 0025-0028. Prossimo passo: anagrafiche (#41) e articoli e listini (#42) con i dati di esempio, import/export guidato (#44), chiusura M4 (#46). #35 (PNG ad alta risoluzione) resta aperta e non blocca. Da recuperare: misure di riferimento su PostgreSQL in docs/DATA-MODEL.md §6.1; indicatore di robustezza della password (mockup 003); schede Layout salvati (M4) e Notifiche (con le e-mail, M5) del profilo; rinomina e filtro predefinito nei radar.

Fatto

  • Specifica normativa in docs/SPEC.md; CLAUDE.md con emendamenti E1-E6.
  • ADR 0001-0028.
  • 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.
  • 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

  • PNG ad alta risoluzione delle 66 schermate disponibili solo come miniatura (issue #35, non bloccante).
  • Scelta degli intermediari SDI e accreditamento SdICoop (issue #78, non bloccante).
  • 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).
  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.
  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.
  5. Stato "Provvisorio" dell'esercizio nel mockup 052, non previsto da SPEC (aperto / in chiusura / chiuso).
  6. Codici conto incoerenti tra mockup (fornitori 05.02.001 in 040/043, 02.03.001 in 042).
  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.