Files
Khaemhat/docs/STATUS.md
T
Alby96andClaude Opus 5.5 9e3ba92993 feat: general ledger, automatic posting, VAT settlement, withholdings and F24 (#62 #63 #64 #65 #66 #67 #68)
M7 adds the double-entry ledger so that the documents of M5 and M6 reach the
accounts without retyping, and the Italian VAT obligations can be prepared from
the same data.

- Chart of accounts on three levels with the Italian "PMI standard" model in the
  fiscal pack, journal templates with proposed lines, VAT registers; the chart
  import now writes the accounts and exports them (#62, ADR 0036).
- Journal entries: draft, posted, final with the libro giornale number,
  reversal; recurring entries with the nightly ledger.recurring job (#63).
- Documents post their entry inside the document transaction (PostingEngine,
  LedgerPoster) with VAT lines, open items and withholdings; a change rewrites
  the same entry, a cancellation removes or reverses it (#64, ADR 0037).
- VAT registers with final print, monthly or quarterly settlement with pro rata,
  interest, minimum and advance, confirmation with the LIQ entry, period lock
  and F24 line, LIPE file and F24 data (#65).
- Operated and suffered withholdings, CU data, stamp duty by quarter with the
  5,000 euro threshold, F24 summary with its payment entry (#66).
- Party ledgers, account ledgers, trial balance and libro giornale (#67).
- Demo accounting with the settlements of the past months confirmed and checked
  by hand in a test; wiki Contabilita, IVA, Fiscalita italiana completed with
  screenshots; CHANGELOG 0.7.0, STATUS, ADR 0036-0037 (#68).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 01:41:58 +01:00

18 KiB

Stato del progetto

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

Ultimo aggiornamento: 2026-11-13 Milestone corrente: M8 — Scadenzario e tesoreria (issue #69-#73), da iniziare. M7 chiusa: PR in main, tag v0.7.0, immagine e release. Prossimo passo: M8 dall'issue #69. #35 (PNG ad alta risoluzione) resta aperta e non blocca; #45 resta aperta solo per le banche ABI/CAB (manca una fonte con licenza compatibile). 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; scritture delle rimanenze e libro inventari (M10); chiusura delle partite con incassi e pagamenti e IVA per cassa (M8).

Fatto

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