Files
Khaemhat/docs/STATUS.md
T
Alby96andClaude Opus 5.5 07555de700 feat: automatic codes and automatic filling (#43)
Parties, items and the CRM archives need codes given by the system without
duplicates, and the address and bank fields should fill themselves; this adds
both before the party and item screens that use them.

- CodeMask ({seq:0000}, {anno}, {categoria}) and code_sequences (migration
  015): one sequence per rule, year and category, taken under a lock in the
  transaction that saves the record, skipping codes written by hand
- CodeRuleService: rules in company settings with the masks of SPEC 11.12,
  validation, preview of the next code, manual code allowed or not
- AutoFillService: municipality from postal code and back, personal tax code,
  VIES, bank and BIC from the IBAN, delivery date on working days, options
  that can be switched off (the ECB job honours its option)
- IBankDirectory.ReadIban gives ABI and CAB even without the ABI list; the
  Italian pack now registers the directory
- Company preferences page (mockup 074) at /tabelle/preferenze, in the menu
- aria-checked now renders true/false on switch rows and profile radios
- ADR 0027, wiki, CHANGELOG, STATUS, DATA-MODEL

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 23:33:02 +01:00

14 KiB

Stato del progetto

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

Ultimo aggiornamento: 2026-11-11 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, senza gli elenchi ISTAT e ABI/CAB: serve il via dell'utente al download), codici automatici e compilazione automatica (#43). ADR 0025-0027. 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-0027.
  • 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.