The pages built so far now live inside the shell of the mockups instead of the M0 placeholder, every interface text comes from Resources/it-IT, and each user keeps their own look and start page. - Shell: top bar, collapsible side menu with fly-out sub-menus, status bar and tabs that keep each page alive (page type and route values per tab, so a tab never shows another page); at most 12 tabs, least-used clean tab evicted. - One shortcut table with Alt variants for the combinations browsers keep (Ctrl+W, Ctrl+Tab, Ctrl+N); command palette for pages and commands. - ITexts over embedded JSON; tests forbid literal texts in .razor components and check that every key used exists. - User settings in sys_user_settings / user_settings; theme written on the server; profile page with live preview, start page, sessions and shortcuts. - Home, coming-soon pages for later milestones, localized sign-in and error pages; ADR 0020; wiki, CHANGELOG, STATUS and data model updated. Refs #25 #26 #31 #33 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
13 KiB
Stato del progetto
Punto di ripresa per ogni sessione. Aggiornare a fine sessione.
Ultimo aggiornamento: 2026-11-11
Milestone corrente: M3 — Framework UI, nel ramo feat/25-interfaccia. Fatti: shell (#26), testi localizzati
(#33), preferenze e profilo per aspetto, pagina iniziale e sessioni (#31, in parte), base dei temi (#25, in parte).
Prossimo passo: il resto di M3: profilo con dati personali e password/2FA (#31), componenti Kh* (#27), toolbar e
intestazione documento (#29), griglie e radar (#28), dashboard a widget (#30), ricerca, aiuto e notifiche (#32),
allegati ed esportazioni (#34), chiusura (#36). #35 attende i PNG dall'utente.
Da recuperare: misure di riferimento su PostgreSQL in docs/DATA-MODEL.md §6.1; indicatore di robustezza della
password (mockup 003).
Fatto
- Specifica normativa in
docs/SPEC.md;CLAUDE.mdcon emendamenti E1-E6. - ADR 0001-0020.
- 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 (in corso,
feat/25-interfaccia): shell con barra superiore, menu comprimibile con sottomenu a comparsa, schede tenute in vita (massimo 12), barra di stato; scorciatoie con variantiAlt; ricerca di pagine e comandi; testi inResources/it-IT/*.jsoncon test anti-testo-letterale; preferenze utente insys_user_settingseuser_settings; Il mio profilo (aspetto con anteprima dal vivo, pagina iniziale, sessioni, scorciatoie); home e pagine "in arrivo"; ADR 0020. Test: 215 verdi in locale, 21 di PostgreSQL saltati. - 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)
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).
- 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.
- 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.
- Stato "Provvisorio" dell'esercizio nel mockup 052, non previsto da SPEC (aperto / in chiusura / chiuso).
- Codici conto incoerenti tra mockup (fornitori 05.02.001 in 040/043, 02.03.001 in 042).
- 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.