diff --git a/CHANGELOG.md b/CHANGELOG.md index 162eeef..75133c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ un'immagine `gitea.encke-hake.ts.net/balbosoft/khaemhat:X.Y.Z`. ## [Unreleased] +## [0.5.0] - 2026-11-12 + +M5 — Motore documenti e Vendite. Un solo motore per tutti i documenti, con numerazione, totali, scadenze e +collegamenti riga per riga, e le maschere del ciclo attivo: dal preventivo alla fattura stampata e inviata per +e-mail, con un anno di vendite nei dati di esempio e una guida all'uso nella wiki. + ### Added - Motore documenti (#47, ADR 0032): un solo motore per vendite, acquisti e magazzino. Ogni tipo documento ha un **genere** (17: preventivo, ordine cliente, DDT, fatture immediate, accompagnatorie, differite e di acconto, note @@ -33,11 +39,38 @@ un'immagine `gitea.encke-hake.ts.net/balbosoft/khaemhat:X.Y.Z`. - Copia di più documenti della stessa controparte in uno solo (`MergeAsync`), con una riga di riferimento per ognuno: la base della fatturazione differita. Le note di credito e di debito ricordano la fattura che correggono. +- Maschere delle vendite (#49, #50): radar di preventivi, ordini, DDT, fatture e note con ricerca, filtri per tipo, + stato e anno; un'unica maschera documento con intestazione, righe (articolo con F4, sconti a cascata, righe + descrittive, di spesa e di sconto), Testata, Trasporto per DDT e fatture accompagnatorie, Totali, Scadenze, Note, + Allegati, Collegamenti e Storico; azioni Conferma, Emetti, Duplica, Chiudi, Riapri, Annulla con motivo, *Segna come + rifiutato* per i preventivi e **Crea …** con la scelta delle righe e delle quantità residue. +- Fatturazione differita guidata (#51): DDT confermati e non fatturati del periodo, per tutti i clienti o uno, una + fattura differita TD24 per cliente o per DDT, in bozza o già emessa, con i riferimenti ai DDT nelle righe. +- Stampa dei documenti (#52, ADR 0034): anteprima di stampa A4 e PDF disegnati dallo stesso modello (dati + dell'azienda e logo, controparte, campi, righe, riepilogo IVA, scadenze, totali, trasporto con le firme, diciture e + filigrane), generatore *Stampa del documento in PDF* con versioni negli allegati, documento segnato come stampato. +- Invio per e-mail (#52, ADR 0034): destinatari, oggetto e testo proposti dal modello con i campi `{{Numero}}`, + `{{Cliente}}`…, PDF allegato e salvato come nuova versione, coda in background con tre tentativi, client SMTP + scritto in casa (STARTTLS, TLS, AUTH PLAIN e LOGIN) configurato da `KHAEMHAT_SMTP_*`, esito nel log *E-mail/PEC*. +- Log, sezione *Documenti* (#53): conferme ed emissioni con il numero, chiusure, riaperture, annullamenti ed + eliminazioni delle bozze. +- Dati di esempio (#53): profilo dell'azienda demo e un anno di vendite costruite con il motore (6 preventivi, 4 + ordini, 5 DDT, 8 fatture e pro forma, 1 nota di credito) in tutti gli stati, idempotenti. +- Wiki: pagina [Guida all'uso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Guida-utente) con il percorso + completo e le schermate; [Vendite](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Vendite) riscritta con + le schermate reali; schermate dell'accesso in *Primi passi*. + ### Changed +- `README.md` è ora la guida di installazione per chi sviluppa (prerequisiti, avvio, test, migrazioni, immagine). +- L'emissione di una fattura o di una nota richiede il codice IVA su ogni riga (non descrittiva). - *Tipi documento*: nuovo campo obbligatorio **Genere** (i tipi di base lo ricevono dalla migrazione); *Numeratori*: nuovo campo **Data dell'ultimo numero**. - *Clienti*, condizioni di vendita: **mesi esclusi** (due mesi senza scadenze e il giorno del mese dopo in cui slittano). +### Fixed +- `scripts/run-dev.sh` sotto Git Bash su Windows scriveva i dati in una cartella `b` sul disco invece che in + `.data/dev`. + ## [0.4.0] - 2026-11-12 M4 — Tabelle, anagrafiche, articoli. Il pacchetto fiscale italiano, il profilo e le tabelle dell'azienda con i dati diff --git a/README.md b/README.md index fd439e3..f055dbf 100644 --- a/README.md +++ b/README.md @@ -5,72 +5,195 @@ # Khaemhat **Gestionale ERP + CRM per piccole e medie imprese italiane**, scritto da zero in C# 14 su .NET 10 con interfaccia -Blazor Server, PostgreSQL (o SQLite per demo e test) e **nessuna libreria esterna**. Si installa **solo con Docker**: -l'unico artefatto distribuito è l'immagine nel registro pacchetti di Gitea. +Blazor Server, PostgreSQL (o SQLite per demo e test) e **nessuna libreria esterna**. Si distribuisce **solo come +immagine Docker** nel registro pacchetti di Gitea. -> **Stato:** sviluppo avviato. M0 (struttura, immagine Docker, CI) consegna la versione 0.0.1 con una pagina -> "in costruzione"; le funzioni arrivano milestone dopo milestone. Vedi [`docs/STATUS.md`](docs/STATUS.md) e la +Questo file è la **guida di installazione per chi sviluppa**: come preparare il computer, compilare, avviare, +provare e pubblicare. Chi **usa** il gestionale parte dalla +[Guida all'uso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Guida-utente) nella wiki; chi lo **installa** +su un server da [Installazione Docker](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Docker) +o [Installazione Unraid](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Unraid). + +> **Stato:** sviluppo in corso, versioni 0.x. Ultima milestone chiusa: **M5 — Motore documenti e Vendite** (0.5.0). +> Punto di ripresa in [`docs/STATUS.md`](docs/STATUS.md), piano in > [Roadmap](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Roadmap). -Il nome viene da Khaemhat (Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto -Amenhotep III: un contabile e un magazziniere dell'antichità. Vedi -[Origine del nome](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Origine-del-nome). +## 1. Prerequisiti -## Cosa farà +| Strumento | Versione | A cosa serve | +|---|---|---| +| **.NET SDK** | 10.0.100 o successiva della stessa *feature band* (vedi [`global.json`](global.json)) | compilare, provare, avviare | +| **Git** | qualunque recente | il repository; su Windows anche **Git Bash**, che esegue gli script `scripts/*.sh` | +| **Docker** | facoltativo | costruire e provare l'immagine; PostgreSQL e Redis per i test sui motori reali | +| **PostgreSQL** | 16 o 17, facoltativo | i test di integrazione sul motore di produzione (`KHAEMHAT_TEST_PG`) | -- Anagrafiche, articoli, listini, tabelle; vendite e acquisti con motore documenti unico; magazzino. -- Contabilità generale, IVA, F24, LIPE, ritenute, bollo, cespiti, Intrastat, chiusura e bilancio CEE. -- Scadenzario, incassi e pagamenti, RiBa/SDD/SEPA, riconciliazione bancaria, solleciti. -- Fatturazione elettronica FatturaPA con canali SDI (PEC integrata, SdICoop, intermediari). -- CRM (lead, pipeline, attività, campagne, ticket), automazioni, API REST e server MCP. -- Più aziende sulla stessa istanza (un database di sistema + un database per azienda), moduli attivabili con - licenza, temi chiaro/scuro, dashboard a widget. +Non servono Node.js, npm, bundler, IDE particolari né pacchetti NuGet oltre a quelli ammessi: un editor qualunque +va bene (Visual Studio, Rider, VS Code con C# Dev Kit). Lingua dei messaggi del compilatore: per avere gli errori in +inglese, `DOTNET_CLI_UI_LANGUAGE=en`. -## Installazione +## 2. Clonare ```bash -docker pull gitea.encke-hake.ts.net/balbosoft/khaemhat: +git clone https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat.git ``` -- Qualunque host Docker: [`deploy/docker-compose.yml`](deploy/docker-compose.yml) (con PostgreSQL) e - [`deploy/.env.example`](deploy/.env.example); per una prova veloce - [`deploy/docker-compose.sqlite.yml`](deploy/docker-compose.sqlite.yml). -- Unraid: template [`deploy/unraid/khaemhat.xml`](deploy/unraid/khaemhat.xml) o - [`deploy/docker-compose.unraid.yml`](deploy/docker-compose.unraid.yml) con [`deploy/.env.example`](deploy/.env.example). -- Guide: [Installazione Unraid](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Unraid) · - [Installazione Docker](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Docker) · - [Primi passi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Primi-passi). +In rete locale anche `http://192.168.30.23:3000/BalboSoft/Khaemhat.git` o, con una chiave SSH, +`ssh://git@192.168.30.23:2222/BalboSoft/Khaemhat.git`. Il ramo principale è `main`; si lavora su rami +`feat/-descrizione`, `fix/…`, `docs/…` (vedi [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)). -## Sviluppo +## 3. Com'è fatto il repository -Serve l'SDK .NET 10 (`global.json`); Docker solo per costruire e provare l'immagine. +| Cartella | Contenuto | +|---|---| +| `src/Khaemhat.Core` | entità, regole, macchine a stati dei documenti, nessuna dipendenza | +| `src/Khaemhat.Data`, `.Data.Sqlite`, `.Data.PostgreSql` | micro-ORM, migrazioni, provider dei due motori | +| `src/Khaemhat.Application` | servizi applicativi: sicurezza, tabelle, anagrafiche, motore documenti, stampe, seed | +| `src/Khaemhat.Infrastructure` | file (PDF, fogli di calcolo, archivi), posta SMTP, cache, licenze, sicurezza: scritti in casa | +| `src/Khaemhat.Fiscal.Abstractions`, `.Fiscal.Italy` | il pacchetto paese: tutto ciò che è italiano | +| `src/Khaemhat.Web` | host Blazor Server, componenti, pagine, risorse dei testi in `Resources/it-IT/*.json` | +| `tests/*` | MSTest, un progetto per strato | +| `tools/*` | strumenti di sviluppo: licenze (`LicenseTool`), comuni e CAP (`PlacesTool`), modello dati (`DataModelTool`) | +| `docker/`, `deploy/` | Dockerfile ed entrypoint; compose, `.env.example`, template Unraid | +| `scripts/` | build, test, avvio, seed, migrazioni, pubblicazione | +| `docs/` | specifica, ADR, architettura, mockup e la wiki (`docs/wiki/`) | + +## 4. Compilare + +```bash +scripts/build.sh +``` + +Controlla l'allowlist dei pacchetti (`scripts/check-packages.sh` su `Directory.Packages.props`) e compila +`Khaemhat.sln` in Release con **warning come errori** e gli analyzer di piattaforma. L'equivalente a mano: + +```bash +dotnet build Khaemhat.sln -c Release -warnaserror +``` + +## 5. Avviare in locale + +```bash +scripts/run-dev.sh +``` + +Avvia Khaemhat su con SQLite in `.data/dev` (ignorata da git) e queste impostazioni di +sviluppo, ognuna sovrascrivibile esportando la variabile prima di lanciare lo script: + +| Variabile | Valore di sviluppo | +|---|---| +| `KHAEMHAT_DATA_DIR`, `KHAEMHAT_SYSTEM_DB` | `.data/dev`, `sqlite://…/.data/dev/system.db` | +| `KHAEMHAT_SECRET_KEY` | una chiave fissa **solo per lo sviluppo** | +| `KHAEMHAT_SUPERUSER`, `KHAEMHAT_SUPERUSER_PASSWORD` | `root` e la password iniziale scritta nello script | +| `KHAEMHAT_COMPANY_CODE`, `KHAEMHAT_COMPANY_NAME` | `DEMO`, *Khaemhat Demo S.r.l.* | +| `KHAEMHAT_LICENSE_MODE` | `test`: tutti i moduli attivi con i codici di prova | +| `KHAEMHAT_SEED_DEMO` | `true`: la prima azienda nasce con i dati di esempio (anagrafiche, articoli, un anno di vendite) | + +Al primo accesso Khaemhat chiede di cambiare la password e di collegare un'app di autenticazione (il super utente +ha la verifica in due passaggi obbligatoria): conserva la chiave e i codici di recupero. Per ripartire da zero ferma +il server e cancella `.data/dev`. + +Altre cose utili in sviluppo: + +- **Invio di e-mail**: senza `KHAEMHAT_SMTP_HOST` e `KHAEMHAT_SMTP_FROM` l'invio è spento. Per provarlo serve un + server SMTP di prova sulla tua macchina, ad esempio + `KHAEMHAT_SMTP_HOST=127.0.0.1 KHAEMHAT_SMTP_PORT=2525 KHAEMHAT_SMTP_SECURITY=NONE KHAEMHAT_SMTP_FROM=ufficio@example.com scripts/run-dev.sh`; + l'esito di ogni invio è nel log, sezione *E-mail/PEC*. +- **Dati di base e di esempio** su un database esistente: `scripts/seed.sh --base` oppure `scripts/seed.sh --demo` + (aggiungono solo ciò che manca; meglio con il server fermo). +- **Catalogo dei componenti**: mostra i mattoni dell'interfaccia. +- **Tutte le variabili** `KHAEMHAT_*` sono in + [Installazione Docker](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Docker) e + [`docs/DEPLOY.md`](docs/DEPLOY.md). Una configurazione non valida ferma l'avvio con l'elenco degli errori. + +Prima di ricompilare ferma il server: su Windows l'eseguibile in esecuzione blocca le DLL e la build ritenta la copia +(avviso MSB3026) fino a fallire. + +## 6. Provare + +```bash +scripts/test.sh +scripts/test.sh --filter "FullyQualifiedName~Documents" +``` + +Esegue l'allowlist e tutti i test in Release. SQLite è sempre provato; i test che avviano +l'applicazione intera usano un'istanza vera su una porta libera. I test sul **PostgreSQL** reale partono quando +`KHAEMHAT_TEST_PG` indica un ruolo con `CREATEDB` (ogni test crea e cancella il proprio database): + +```bash +docker run -d --name khaemhat-pg-test -e POSTGRES_PASSWORD=prova -p 55432:5432 postgres:17 +KHAEMHAT_TEST_PG="postgres://postgres:prova@localhost:55432/postgres" scripts/test.sh +``` + +Senza la variabile quei test risultano *saltati*. In CI (`.gitea/workflows/ci.yml`) i test girano su ogni pull request verso `main`; il job PostgreSQL +(16 e 17) sui tag e all'avvio manuale. + +Regole che i test fanno rispettare: nessun pacchetto fuori allowlist, dipendenze tra progetti nel verso giusto, +nessun testo italiano scritto nei componenti (vanno nelle risorse `Resources/it-IT/*.json`), chiavi di testo +esistenti, sezione del modello dati aggiornata. + +## 7. Database e migrazioni + +```bash +scripts/new-migration.sh company create_sales_documents # nuova migrazione numerata +scripts/gen-datamodel.sh # rigenera la parte generata di docs/DATA-MODEL.md +scripts/gen-datamodel.sh --check # solo verifica (la fa anche un test) +``` + +Le migrazioni si applicano da sole all'avvio, al database di sistema e a quello di ogni azienda. Il codice non deve +dipendere dal motore: ogni query passa dal micro-ORM e gira identica su SQLite e PostgreSQL. + +## 8. Immagine Docker ```bash -scripts/build.sh # allowlist dei pacchetti + build con warning come errori -scripts/test.sh # tutti i test (PostgreSQL con KHAEMHAT_TEST_PG, Redis con KHAEMHAT_TEST_REDIS) -scripts/run-dev.sh # avvio locale su http://localhost:5080 con SQLite in .data/dev docker build -f docker/Dockerfile -t khaemhat:dev . +docker compose -f deploy/docker-compose.sqlite.yml up # prova veloce con SQLite ``` -Processo, rami e Definition of Done in [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md). +L'immagine pubblicata è `gitea.encke-hake.ts.net/balbosoft/khaemhat:` (e `:latest`, mai in produzione). La +costruisce `.gitea/workflows/release.yml` quando si spinge un tag `vX.Y.Z` (segreto `REGISTRY_TOKEN` con +`write:package`), che crea anche la release Gitea con le note del [`CHANGELOG.md`](CHANGELOG.md). Se il runner non è +disponibile: -## Documentazione +```bash +GITEA_TOKEN=… scripts/publish-image.sh v0.5.0 +``` + +Non si producono installer, eseguibili o pacchetti `.msi/.exe/.deb`: l'unico artefatto è l'immagine +([ADR 0010](docs/adr/0010-solo-docker-nessun-installer.md)). Le versioni restano **0.x** finché il prodotto è in +sviluppo. + +## 9. Documentazione e wiki + +La wiki è in `docs/wiki/` e si aggiorna nella stessa unità di lavoro del codice: una funzione senza documentazione +non è finita. Il workflow `wiki.yml` la pubblica nel wiki Gitea a ogni push su `main` che la tocca; a mano: +`scripts/publish-wiki.sh`. Le schermate stanno in `docs/wiki/img/` e si fanno sull'applicazione vera con i dati di +esempio. La stessa wiki è inclusa nell'immagine e si apre con `F1` dentro il gestionale. | Cosa | Dove | |---|---| -| Wiki (guida utente e amministratore) | (sorgente in [`docs/wiki/`](docs/wiki/)) | | Specifica normativa | [`docs/SPEC.md`](docs/SPEC.md) | | Regole operative ed emendamenti | [`CLAUDE.md`](CLAUDE.md) | -| Processo di sviluppo | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | +| Processo, rami, Definition of Done | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | | Architettura, dati, moduli, API, MCP | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md), [`docs/MODULES.md`](docs/MODULES.md), [`docs/API.md`](docs/API.md), [`docs/MCP.md`](docs/MCP.md) | | Installazione e sicurezza | [`docs/DEPLOY.md`](docs/DEPLOY.md), [`docs/SECURITY.md`](docs/SECURITY.md) | | Decisioni architetturali | [`docs/adr/`](docs/adr/) | -| Mockup | [`docs/mockups/`](docs/mockups/README.md) | +| Mockup (specifica visiva) | [`docs/mockups/`](docs/mockups/README.md) | | Novità | [`CHANGELOG.md`](CHANGELOG.md) | +| Wiki pubblicata | | -## Pianificazione +## 10. Regole del codice in breve -Il lavoro è organizzato in [issue](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/issues) raggruppate per +- C# 14 su .NET 10, `Nullable` attivo, warning come errori, `.editorconfig`; JavaScript solo come interop minimo in + `wwwroot/js`. +- **Nessuna libreria esterna**: framework Microsoft, `Npgsql`, `Microsoft.Data.Sqlite` e, nei test, MSTest. +- Codice, commenti e commit in **inglese**; interfaccia in **italiano** dalle risorse. +- Tutto ciò che è fiscale italiano sta in `Khaemhat.Fiscal.Italy`. +- Commit *Conventional Commits* che dicono cosa cambia e perché e citano l'issue (`#n`); pull request verso `main` + con `Closes #n`. + +Il lavoro è organizzato in [issue](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/issues) per [milestone](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/milestones) (M0-M14) e nei -[progetti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/projects) *Khaemhat 1.0 — Sviluppo* e -*Khaemhat 1.1+ — Fase 2*. +[progetti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/projects). + +Il nome viene da Khaemhat (Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto +Amenhotep III: vedi [Origine del nome](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Origine-del-nome). diff --git a/docs/STATUS.md b/docs/STATUS.md index 01e8517..29a37c6 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -3,20 +3,18 @@ > Punto di ripresa per ogni sessione. Aggiornare a fine sessione. **Ultimo aggiornamento:** 2026-11-12 -**Milestone corrente:** M5 — Motore documenti e Vendite (issue #47-#54, nel progetto in *Da fare*). M4 chiusa: -PR #121 in `main`, tag `v0.4.0`, immagine e release. -**Prossimo passo:** M5: il motore documenti (#47) è sul ramo `feat/47-motore-documenti` in attesa di revisione; -poi il calcolo dei totali (#48) e le maschere (#49-#51). #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: profilo dell'azienda demo (indirizzo, partita IVA) prima dei documenti di M5; misure di riferimento su PostgreSQL in `docs/DATA-MODEL.md` §6.1; indicatore di robustezza della -password (mockup 003); schede *Layout salvati* e *Notifiche* (con le e-mail, M5) del profilo; rinomina e -filtro predefinito nei radar. +**Milestone corrente:** M6 — Acquisti e Magazzino (issue #55-#61), **non ancora iniziata**: si parte quando il +titolare lo dice. M5 chiusa: PR di milestone in `main`, tag `v0.5.0`, immagine e release. +**Prossimo passo:** M6 dall'issue #55. #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). ## Fatto - Specifica normativa in `docs/SPEC.md`; `CLAUDE.md` con emendamenti E1-E7. -- ADR 0001-0032. +- ADR 0001-0034. - 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`, @@ -60,10 +58,14 @@ filtro predefinito nei radar. 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 (in corso):** 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. Test: 664 - verdi in locale, PostgreSQL compreso. +- **M5 (chiusa, `v0.5.0`):** 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). - 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, diff --git a/docs/adr/0034-stampa-e-invio-dei-documenti.md b/docs/adr/0034-stampa-e-invio-dei-documenti.md new file mode 100644 index 0000000..09e6c59 --- /dev/null +++ b/docs/adr/0034-stampa-e-invio-dei-documenti.md @@ -0,0 +1,47 @@ +# ADR 0034 - Stampa e invio dei documenti + +- **Stato:** accettata +- **Data:** 2026-11-12 +- **Modifica:** SPEC §9.4, §12.6; milestone M5, issue #52 + +## Contesto + +SPEC §9.4 chiede l'anteprima di stampa (mockup 025) e il PDF di ogni documento come allegato versionato; §12.6 l'invio +per e-mail con modelli, allegati ed esito nel log. Il vincolo di §1 esclude librerie esterne per PDF, posta e modelli. +Restavano aperti: come tenere uguali anteprima e PDF, dove stanno le diciture, quali immagini accetta il PDF, come si +invia la posta senza una libreria, che cosa succede se il server di posta non risponde. + +## Decisione + +1. **Un solo modello di stampa.** `DocumentPrintService` costruisce un `DocumentPrintModel` (intestazione dell'azienda + dal profilo, controparte, campi, righe, riepilogo IVA, scadenze, totali, trasporto, firme, diciture, filigrana) già + formattato con la cultura italiana. L'anteprima HTML (`SalesPrintPage`) e il PDF (`DocumentPdfGenerator`, sopra il + `PdfWriter` di M3) disegnano lo stesso modello: un campo nuovo compare in tutti e due. +2. **Diciture nelle risorse.** Etichette, diciture di legge (split payment, pro forma non valida ai fini fiscali, + fattura differita) e filigrane (*Bozza*, *Annullato*, *Dato dimostrativo*) stanno in `Resources/it-IT/Print.json`. + I modelli di stampa configurabili per tipo documento di §9.4 restano per M12; fino ad allora il tipo documento + sceglie solo quali blocchi compaiono (il trasporto e le firme per DDT e fatture accompagnatorie). +3. **Logo.** Nell'anteprima compare qualunque immagine del profilo; nel PDF solo un **JPEG**, perché il `PdfWriter` + incorpora i JPEG senza decodificarli (DCTDecode) e un decodificatore PNG scritto in casa non vale il costo ora. + Con un PNG il PDF esce senza logo. +4. **Il PDF è un allegato.** Il generatore `documents.pdf` è un `IFileGenerator`: *Salva come allegato* e l'invio per + e-mail creano una nuova versione, così resta la copia esatta di ciò che è uscito. Il documento registra i flag + *stampato* e *inviato* (con la sola permission di lettura, perché non cambiano il contenuto) e lo storico. +5. **SMTP scritto in casa.** `SmtpMailSender` parla SMTP su `TcpClient`/`SslStream`: EHLO, STARTTLS o TLS implicito, + AUTH PLAIN o LOGIN, un messaggio per connessione, timeout di 60 secondi. `MimeMessageWriter` scrive + `multipart/mixed` con testo e allegati in base64 e intestazioni non ASCII come *encoded word*. Configurazione da + `KHAEMHAT_SMTP_*` finché non c'è la pagina *Impostazioni* (M12). +6. **Coda in memoria.** `MailQueue` è un servizio in background con un canale limitato a 500 messaggi: tre tentativi + a 30 e 60 secondi, ogni passo nel log, sezione *E-mail/PEC*. Chi invia non aspetta il server. Un messaggio in coda + quando il processo si ferma si perde e il log lo dice; una coda persistente arriva se servirà con le automazioni + (M12). +7. **Modelli con campi.** Oggetto e testo vengono da `Print.Mail.*` con i campi `{{Documento}}`, `{{Numero}}`, + `{{Data}}`, `{{Cliente}}`, `{{Azienda}}`, `{{Totale}}` (`MailTemplateRenderer`; un campo sconosciuto resta + com'è, così l'errore si vede). L'utente li modifica prima di inviare; i modelli per azienda arrivano con M12. + +## Conseguenze + +- Anteprima e PDF non divergono e si provano insieme (il modello ha i suoi test). +- Nessuna dipendenza nuova; il client SMTP è provato contro un server finto in-process. +- Limiti noti: niente PNG nel PDF, niente coda persistente, niente modelli per azienda, niente PEC dedicata (arriva + con il canale SDI via PEC in M9). diff --git a/docs/wiki/Allegati-e-file.md b/docs/wiki/Allegati-e-file.md index 664b007..d99b9af 100644 --- a/docs/wiki/Allegati-e-file.md +++ b/docs/wiki/Allegati-e-file.md @@ -1,6 +1,6 @@ # Allegati e file -> **Stato:** completa per M3 (invio e-mail e scanner con M5) · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 (milestone M3) +> **Stato:** completa per M5 (acquisizione da scanner con M13) · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 > **Modulo di licenza:** CORE · **Permessi principali:** `attachments.read`, `attachments.write`, `attachments.delete` · **Specifica:** SPEC §9.4 Ogni documento e ogni anagrafica può avere **allegati**: file caricati dall'utente (l'ordine del cliente in PDF, una @@ -79,6 +79,11 @@ La sezione **Genera file** del pannello elenca le uscite disponibili per il docu **Rigenera** non sovrascrive mai: crea la versione successiva (`v2`, `v3`…) e lascia consultabili le precedenti. +**In 0.5.0** i documenti di vendita (preventivi, ordini, DDT, fatture, note, pro forma) hanno il generatore **Stampa +del documento in PDF**: lo stesso disegno dell'anteprima di stampa (vedi [Vendite](Vendite#stampa-e-pdf)). Lo usano +anche **Salva come allegato** dell'anteprima e **Invia per e-mail**, che allega al messaggio la versione appena +creata: così tra gli allegati resta sempre la copia esatta di ciò che è stato stampato o inviato. + Anche i **report** producono file (XLSX, CSV, PDF) scaricabili e, se pianificati, inviati per e-mail come allegati. Le **stampe massive** (ad esempio tutte le fatture del mese) producono un unico **ZIP** scaricato direttamente, senza file temporanei. diff --git a/docs/wiki/Changelog.md b/docs/wiki/Changelog.md index 25d6fbc..7fa9a19 100644 --- a/docs/wiki/Changelog.md +++ b/docs/wiki/Changelog.md @@ -1,6 +1,6 @@ # Changelog -> **Stato:** completa per 0.4.0 · **Ultima revisione:** 2026-11-12 +> **Stato:** completa per 0.5.0 · **Ultima revisione:** 2026-11-12 Le novità di ogni versione sono nel file [`CHANGELOG.md`](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/CHANGELOG.md) del repository @@ -11,6 +11,7 @@ Le novità di ogni versione sono nel file | Versione | Data | Contenuto | |---|---|---| +| 0.5.0 | 2026-11-12 | M5 — Motore documenti e Vendite: preventivi, ordini, DDT, fatture, note di credito, pro forma e parcelle con numerazione senza buchi, castelletto IVA, bollo, ritenute e scadenze; documenti collegati riga per riga e *Crea …* per passare dall'uno all'altro; fatturazione differita guidata; anteprima di stampa e PDF salvato tra gli allegati; invio per e-mail con SMTP interno; un anno di vendite nei dati di esempio; [Guida all'uso](Guida-utente) con le schermate. | | 0.4.0 | 2026-11-12 | M4 — Tabelle, anagrafiche, articoli: pacchetto fiscale italiano, profilo azienda, esercizi e cambi, 26 tabelle azienda con province, comuni e CAP, clienti, fornitori e contatti con controlli e VIES, articoli e listini con prezzi a validità, codici automatici, import/export guidato (anche del piano dei conti, per ora solo verifica) e dati di esempio. | | 0.3.0 | 2026-11-11 | M3 — Framework UI: la finestra di Khaemhat con menu, schede e barra di stato, la dashboard a widget, *Il mio profilo* con temi e colori, ricerca globale, aiuto in app, notifiche, componenti per maschere e liste, allegati e anteprima di stampa (provati su un documento di prova, le maschere gestionali arrivano da 0.4.0). | | 0.2.0 | 2026-11-11 | M2 — Sistema e sicurezza: avvio da variabili d'ambiente, super utente e prima azienda, accesso con password e verifica in due passaggi, utenti, ruoli e permessi, licenze e moduli con codici di prova, log per sezioni, attività programmate. | diff --git a/docs/wiki/Dati-di-base-e-esempio.md b/docs/wiki/Dati-di-base-e-esempio.md index fef72f5..85b07bf 100644 --- a/docs/wiki/Dati-di-base-e-esempio.md +++ b/docs/wiki/Dati-di-base-e-esempio.md @@ -1,6 +1,6 @@ # Dati di base e di esempio -> **Stato:** completa per M4 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.4.0 (dati di esempio di documenti e contabilità con i moduli, completi in M9) +> **Stato:** completa per M5 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 (dati di esempio di acquisti, magazzino e contabilità con i moduli, completi in M9) > **Modulo di licenza:** CORE · **Livello richiesto:** amministratore (rimozione dati di esempio: super utente) · **Specifica:** SPEC §6, §12.11, §14 ## A cosa serve @@ -133,7 +133,22 @@ i controlli; non si verificano sul VIES (ADR 0029). Gli agenti di esempio non so Ci sono poi **120 articoli** in dieci categorie con i listini *Pubblico* e *Rivenditori* derivati dal base, prezzi dell'anno precedente, fornitori abituali, UM e codici alternativi, sostitutivi e i prezzi netti e i codici di un cliente (ADR 0030, vedi [Articoli e listini](Articoli-e-listini)). I codici a barre di esempio iniziano con `200`, -prefisso riservato all'uso interno. Il resto della tabella arriva con le milestone dei rispettivi moduli. +prefisso riservato all'uso interno. + +**Da M5** l'azienda di esempio ha anche il **profilo** compilato (indirizzo, partita IVA, REA, nota a piè di +pagina delle stampe) e **un anno di vendite** costruite con il motore dei documenti, con date dal 1° gennaio a oggi: + +| Documenti | Stati | +|---|---| +| 6 preventivi | 2 trasformati in ordine, 1 rifiutato, 1 con la validità scaduta, 1 in attesa di risposta, 1 in bozza | +| 4 ordini clienti | 3 evasi (uno in due consegne), 1 ancora da consegnare | +| 5 DDT | 2 già fatturati in differita, 3 da fatturare (prova la [fatturazione differita](Vendite#fatturazione-differita)) | +| 8 fatture | 5 immediate (una in bozza), 2 differite, 1 pro forma | +| 1 nota di credito | reso di un articolo difettoso, collegata alla fattura | + +Le fatture e la nota condividono il numeratore (`1/2026` … `7/2026`), senza buchi e in ordine di data. Tutti i +documenti sono marcati come dimostrativi e la stampa lo scrive in evidenza. Il caricamento non si ripete se +l'azienda ha già documenti di vendita. Il resto della tabella arriva con le milestone dei rispettivi moduli. I dati sono costruiti con gli stessi motori del programma (documenti, contabilità): ogni quadratura torna, e lo stesso caricamento è usato come prova automatica di correttezza. diff --git a/docs/wiki/Guida-utente.md b/docs/wiki/Guida-utente.md new file mode 100644 index 0000000..979fd8c --- /dev/null +++ b/docs/wiki/Guida-utente.md @@ -0,0 +1,160 @@ +# Guida all'uso + +> **Stato:** completa per la versione 0.5 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 (M5) + +Questa pagina accompagna chi usa Khaemhat ogni giorno: dall'accesso alla fattura inviata al cliente, un passo per +volta, con le schermate della versione attuale. Ogni passo rimanda alla pagina che lo spiega per intero. Chi deve +**installare** Khaemhat parte invece da [Installazione con Docker](Installazione-Docker) o +[Installazione su Unraid](Installazione-Unraid) e da [Primi passi](Primi-passi). + +## Che cosa c'è in questa versione + +| Area | In 0.5.0 | Arriva con | +|---|---|---| +| Accesso e sicurezza | password, verifica in due passaggi, codici di recupero, blocco dopo i tentativi sbagliati | — | +| Interfaccia | menu, schede, ricerca globale, notifiche, aiuto F1, dashboard a widget, temi e colori | — | +| Tabelle azienda | profilo azienda, esercizi, cambi, codici IVA, pagamenti, banche, depositi, tipi documento, numeratori e le altre tabelle di base | — | +| Anagrafiche | clienti, fornitori, contatti, controlli di partita IVA e codice fiscale, VIES | CRM (lead, opportunità): M11 | +| Articoli | articoli, categorie, listini con prezzi a validità, prezzi netti per cliente | giacenze: M6 | +| Vendite | preventivi, ordini, DDT, fatture, note, pro forma, fatturazione differita, stampa PDF, invio per e-mail | magazzino M6, contabilità M7, partite M8, XML SDI M9 | +| Acquisti e magazzino | — | M6 | +| Contabilità, IVA, scadenzario | — | M7, M8 | +| Fatturazione elettronica | — | M9 | +| Import ed export | clienti, fornitori, articoli e prezzi da CSV, Excel e JSON; esportazione dai radar | giacenze iniziali M6, piano dei conti M7 | +| Amministrazione da interfaccia | utenti e licenze da variabili e riga di comando | pagine di amministrazione: M12 | + +Le voci di menu delle aree non ancora pronte aprono una pagina che dice che cosa conterranno. + +## 1. Entrare + +![Pagina di accesso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/accesso-login.png) + +Scegli l'**azienda**, scrivi **nome utente** e **password** e premi **Accedi**. Se il tuo account ha la verifica in +due passaggi, Khaemhat chiede il codice a 6 cifre dell'app di autenticazione (o un codice di recupero). Al primo +accesso può chiederti di cambiare la password. Vedi [Primi passi](Primi-passi) e +[Utenti e permessi](Utenti-e-permessi). + +## 2. Orientarsi + +![La Home](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-home.png) + +- **Barra superiore**: logo e versione, l'**azienda** su cui lavori (si cambia da qui), la **ricerca globale** + (`Ctrl+K`), cronologia, **notifiche**, tema chiaro o scuro, **aiuto** (`F1`) e il menu del tuo profilo. +- **Menu a sinistra**: le aree del gestionale; si comprime per avere più spazio. +- **Schede**: ogni maschera si apre in una scheda; puoi tenerne aperte più insieme e passare dall'una all'altra. +- **Barra di stato** in basso: azienda, esercizio, utente, stato della connessione e versione. + +La **Home** è una dashboard a widget che ognuno personalizza. Le scorciatoie da tastiera sono elencate in +[Interfaccia e scorciatoie](Interfaccia-e-scorciatoie#tabella-completa-delle-scorciatoie); la dashboard in +[Dashboard](Dashboard). + +![Ricerca globale](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-ricerca.png) + +## 3. Preparare l'azienda + +![Codici IVA](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/tabelle-codici-iva.png) + +Prima dei documenti controlla in **Tabelle azienda**: + +1. **Profilo azienda**: ragione sociale, partita IVA, indirizzo, REA, contatti, logo e la nota a piè di pagina delle + stampe. Questi dati compaiono su ogni documento stampato. +2. **Esercizi e periodi**: l'esercizio dell'anno deve essere aperto, altrimenti i documenti non si confermano. +3. **Pagamenti**, **banche**, **codici IVA**, **depositi**: le tabelle di base sono già caricate; aggiungi le tue. +4. **Tipi documento** e **numeratori**: il formato dei numeri (`7/2026`, `OC-2026-0004`) e i sezionali. +5. **Codici automatici**: come si numerano clienti, fornitori e articoli. + +Dettagli in [Tabelle azienda](Tabelle-azienda) e [Dati di base e di esempio](Dati-di-base-e-esempio). + +## 4. Clienti e fornitori + +![Radar dei clienti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/anagrafiche-radar.png) + +**Anagrafiche → Clienti** apre il **radar**, l'elenco con ricerca, filtri, colonne a scelta e viste salvate. +`Ctrl+N` crea un cliente; un doppio clic apre la scheda. + +![Scheda cliente](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/anagrafiche-scheda.png) + +Nella scheda compili i dati anagrafici e fiscali (partita IVA e codice fiscale sono controllati; la partita IVA UE si +verifica sul VIES), gli indirizzi di consegna, i contatti e le **condizioni commerciali**: pagamento, listino, +agente, banca. I documenti di vendita le propongono da soli. Vedi [Anagrafiche](Anagrafiche). + +## 5. Articoli e prezzi + +![Scheda articolo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/articoli-scheda.png) + +**Anagrafiche → Articoli**: codice, descrizione, categoria, unità di misura, codice IVA, prezzo, codici a barre, +fornitori abituali. **Listini** gestisce i prezzi per listino con date di validità; nella scheda del cliente puoi +fissare prezzi netti. Vedi [Articoli e listini](Articoli-e-listini). + +![Griglia dei listini](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/listini-griglia.png) + +## 6. Vendere + +![Radar delle fatture](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatture-radar.png) + +Il menu **Vendite** raccoglie preventivi, ordini, DDT, fatture e note di credito. Il percorso tipico: + +1. **Preventivo** → **Crea Ordine cliente** quando il cliente accetta. +2. **Ordine** → **Crea DDT** a ogni consegna (anche parziale) oppure **Crea Fattura immediata**. +3. **Fatturazione differita** a fine mese: tutti i DDT del periodo diventano fatture, una per cliente. +4. **Nota di credito** dalla fattura per un reso o una correzione. + +![Fattura emessa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento.png) + +Nella maschera del documento scegli il cliente, inserisci le righe (`F4` cerca l'articolo) e controlla castelletto +IVA, scadenze e totali; **Conferma** (o **Emetti** per le fatture) assegna il numero. I documenti restano collegati +riga per riga, così Khaemhat sa che cosa resta da consegnare o da fatturare. + +![Fatturazione differita](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatturazione-differita.png) + +Tutto il ciclo è spiegato in [Vendite](Vendite). + +## 7. Stampare e inviare + +![Anteprima di stampa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-stampa.png) + +La **stampante** della toolbar (`Ctrl+P`) apre l'anteprima: **Stampa** con la stampante del computer, **Apri PDF** o +**Scarica PDF**, **Salva come allegato** per conservarne una copia. + +![Invio per e-mail](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-email.png) + +Dal menu **⋯** del documento, **Invia per e-mail** propone destinatario, oggetto e testo; il PDF parte in allegato e +l'esito finisce nel log. Vedi [Vendite](Vendite#invio-per-e-mail). + +## 8. Allegati + +![Pannello allegati](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/allegati-pannello.png) + +Ogni anagrafica e ogni documento ha la scheda **Allegati**: carichi file dal computer, li vedi in anteprima, scarichi tutto in un archivio ZIP. I PDF che Khaemhat genera sono **versionati**: ogni stampa salvata o +e-mail inviata aggiunge una versione e le precedenti restano. Vedi [Allegati e file](Allegati-e-file). + +## 9. Importare ed esportare + +![Mappatura delle colonne](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/import-export-mappatura.png) + +**Amministrazione → Import/Export** porta in Khaemhat clienti, fornitori, articoli e prezzi di listino da un file +CSV, Excel o JSON: scegli il file, abbini le colonne, guarda l'anteprima con gli errori riga per riga e conferma. Ogni radar +esporta le righe visibili. Vedi [Import/Export](Import-Export). + +## 10. Personalizzare + +![Il mio profilo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/preferenze-profilo.png) + +Dal menu del tuo nome, **Il mio profilo**: tema chiaro, scuro o automatico, colore d'accento, densità e carattere, +dati personali, password e verifica in due passaggi, sessioni aperte e pagina iniziale. Le preferenze dell'azienda (ad esempio i decimali dei +prezzi) sono in **Tabelle azienda → Preferenze**. Vedi [Preferenze utente](Preferenze-utente). + +![Tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-tema-scuro.png) + +## Se qualcosa non va + +- **`F1`** apre l'aiuto della pagina in cui sei: la pagina di questa wiki, anche senza connessione a Gitea. +- La pagina di errore riporta un **codice di traccia**: comunicalo all'amministratore, che lo ritrova nel + [Log](Log). +- Le domande più comuni sono in [FAQ](FAQ); i termini del gestionale nel [Glossario](Glossario). + +## Pagine correlate + +[Primi passi](Primi-passi) · [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie) · [Anagrafiche](Anagrafiche) · +[Articoli e listini](Articoli-e-listini) · [Tabelle azienda](Tabelle-azienda) · [Vendite](Vendite) · +[Allegati e file](Allegati-e-file) · [Import/Export](Import-Export) · [Preferenze utente](Preferenze-utente) diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md index 9970cb0..5ad5149 100644 --- a/docs/wiki/Home.md +++ b/docs/wiki/Home.md @@ -1,6 +1,6 @@ # Khaemhat -> **Stato:** bozza · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.4.0 (M4; sviluppo in corso) +> **Stato:** completa per 0.5.0 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 (M5; sviluppo in corso) ![Khaemhat](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/assets/icon-v1.0-128.png) @@ -18,8 +18,12 @@ Il nome viene da uno scriba dell'antico Egitto che sovrintendeva ai granai del r ## Per iniziare +> **Usi Khaemhat?** Parti dalla **[Guida all'uso](Guida-utente)**: dall'accesso alla fattura inviata al cliente, con +> le schermate della versione attuale e che cosa c'è e che cosa arriva. + | Se vuoi… | Leggi | |---|---| +| Imparare a usare il gestionale | [Guida all'uso](Guida-utente) | | Installare Khaemhat su Unraid | [Installazione-Unraid](Installazione-Unraid) | | Installarlo con Docker Compose | [Installazione-Docker](Installazione-Docker) | | Fare il primo accesso e configurare l'azienda | [Primi-passi](Primi-passi) | diff --git a/docs/wiki/Impostazioni.md b/docs/wiki/Impostazioni.md index 65ebcbc..9d81430 100644 --- a/docs/wiki/Impostazioni.md +++ b/docs/wiki/Impostazioni.md @@ -55,6 +55,20 @@ Khaemhat invia e-mail (inviti, recupero password, documenti, report, avvisi) tra I valori iniziali possono arrivare dalle variabili `KHAEMHAT_SMTP_HOST`, `_PORT`, `_USER`, `_PASSWORD`, `_FROM`, `_SECURITY`; quelli salvati qui li sovrascrivono. +> **In 0.5.0** la pagina *Impostazioni* non c'è ancora (arriva con M12): il server SMTP si configura **solo con le +> variabili d'ambiente** e serve all'invio dei documenti per e-mail (vedi [Vendite](Vendite#invio-per-e-mail)). +> +> | Variabile | Valore | +> |---|---| +> | `KHAEMHAT_SMTP_HOST` | nome del server; senza, l'invio è spento | +> | `KHAEMHAT_SMTP_FROM` | indirizzo del mittente (solo l'indirizzo, ad esempio `ufficio@azienda.it`); obbligatorio insieme all'host | +> | `KHAEMHAT_SMTP_SECURITY` | `STARTTLS` (predefinito), `SSL` (o `TLS`, connessione cifrata dall'inizio) oppure `NONE` (solo su reti fidate) | +> | `KHAEMHAT_SMTP_PORT` | predefinita 587, oppure 465 con `SSL` | +> | `KHAEMHAT_SMTP_USER`, `KHAEMHAT_SMTP_PASSWORD` | credenziali, se il server le chiede (AUTH PLAIN o LOGIN); la password anche come `KHAEMHAT_SMTP_PASSWORD_FILE` | +> +> Il client SMTP è scritto in Khaemhat, senza librerie esterne: un messaggio per connessione, tre tentativi, l'esito +> nel [Log](Log), sezione *E-mail / PEC*. + **Prova:** premi **Invia e-mail di prova** dopo aver salvato: arriva un messaggio all'indirizzo indicato. L'esito compare anche in [Stato sistema](Stato-sistema) (controllo *SMTP*) e nel [Log](Log), sezione *E-mail / PEC*. diff --git a/docs/wiki/Log.md b/docs/wiki/Log.md index fb105ff..b0e9d7c 100644 --- a/docs/wiki/Log.md +++ b/docs/wiki/Log.md @@ -59,7 +59,7 @@ Ogni modulo scrive nella **propria sezione**. Il pannello a sinistra le elenca c | **Autenticazione** | accessi, errori di password, blocchi, 2FA, nuovi dispositivi | | **Database** | connessioni, manutenzione | | **Migrazioni** | migrazioni applicate e loro esito | -| **Documenti** | creazione, emissione, annullamento di documenti | +| **Documenti** | conferma ed emissione con il numero assegnato, chiusura, riapertura, annullamento, eliminazione delle bozze (da 0.5.0) | | **Contabilità** | registrazioni, liquidazioni, chiusure | | **Magazzino** | movimenti, ricostruzioni | | **SDI / e-invoicing** | generazione XML, invii, notifiche, scarti | @@ -68,7 +68,7 @@ Ogni modulo scrive nella **propria sezione**. Il pannello a sinistra le elenca c | **Attività programmate** | inizio, fine, durata, esito di ogni esecuzione | | **Backup** | backup, copie remote, verifiche, ripristini | | **API / MCP** | chiamate API e strumenti MCP | -| **E-mail / PEC** | invii e letture di posta | +| **E-mail / PEC** | invii e letture di posta: da 0.5.0 ogni messaggio messo in coda, inviato, ritentato o fallito, con la risposta del server SMTP | | **Integrazioni** | VIES, cambi BCE, intermediari SDI | | **UI / circuiti** | errori dell'interfaccia con lo stack completo | | **Prestazioni** | query oltre 500 ms, richieste lente, garbage collection | diff --git a/docs/wiki/Primi-passi.md b/docs/wiki/Primi-passi.md index 4b8bb9c..79d3883 100644 --- a/docs/wiki/Primi-passi.md +++ b/docs/wiki/Primi-passi.md @@ -1,6 +1,6 @@ # Primi passi -> **Stato:** parziale (passi 1-4 completi) · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (passi 1-4), passi successivi M3-M5 +> **Stato:** parziale (passi 1-4, 7, 10 e 12 completi; amministrazione da interfaccia con M12) · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 > **Modulo di licenza:** CORE · **Livello richiesto:** super utente, poi amministratore · **Specifica:** SPEC §5.4, §7, §8, §12, §14 Questa pagina accompagna chi ha appena installato Khaemhat dal primo avvio del container fino alla prima fattura @@ -57,6 +57,10 @@ disattivata al primo cambio password. *Mockup 001 — pagina di accesso: a sinistra marca e funzioni principali, a destra il modulo con azienda, nome utente, password e l'avviso della modalità Trial (anteprima ridotta).* +![Khaemhat 0.5.0 · pagina di accesso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/accesso-login.png) + +*La pagina di accesso di Khaemhat 0.5.0.* + 1. Nel campo **Azienda** lascia la prima azienda, già proposta (quella creata dal container, ad esempio *Khaemhat Demo S.r.l.*). Il super utente e gli amministratori possono anche scegliere **Nessuna (account di istanza)** per lavorare solo sulle pagine di amministrazione dell'istanza. @@ -111,6 +115,10 @@ telefono. Non c'è un codice QR, perché generarlo richiederebbe una libreria es *Mockup 002 — verifica in due passaggi: sei caselle per il codice, pulsante Verifica e nota sul codice che cambia ogni 30 secondi (anteprima ridotta).* +![Khaemhat 0.5.0 · verifica in due passaggi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/accesso-verifica.png) + +*La verifica in due passaggi di Khaemhat 0.5.0: il codice dell'app oppure un codice di recupero.* + Agli accessi successivi, dopo la password, compare la schermata **Verifica in due passaggi**: scrivi le 6 cifre mostrate dall'app e premi **Verifica**. Il codice cambia ogni 30 secondi. @@ -275,12 +283,14 @@ Con l'azienda configurata puoi emettere la prima fattura: 4. Scegli il cliente: pagamento, listino e agente vengono proposti dalla sua scheda. 5. Nella scheda **Righe** aggiungi l'articolo (`F4` apre la ricerca), la quantità e controlla prezzo e IVA. 6. Premi **Salva** (`Ctrl+S`): la fattura è in *bozza*. -7. Premi **Conferma ed emetti**: la fattura riceve il numero, diventa immutabile e, con il modulo ACCT attivo, - viene contabilizzata. -8. Dalla toolbar genera il PDF o l'XML FatturaPA: ogni file generato diventa un allegato della fattura. +7. Premi **Emetti**: la fattura riceve il numero e diventa immutabile. +8. Premi la **stampante** (`Ctrl+P`): l'anteprima di stampa offre il PDF e **Salva come allegato**; dal menu **⋯** + **Invia per e-mail** manda il PDF al cliente (serve il server SMTP, vedi [Impostazioni](Impostazioni#e-mail-smtp)). -La guida completa è in [Vendite](Vendite); l'invio allo SDI richiede il modulo EINV (vedi -[Fatturazione elettronica](Fatturazione-elettronica)). +![Khaemhat 0.5.0 · una fattura emessa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento.png) + +La guida completa è in [Vendite](Vendite). La contabilizzazione arriva con M7 e l'XML FatturaPA per lo SDI con M9 +(modulo EINV, vedi [Fatturazione elettronica](Fatturazione-elettronica)). ## Domande frequenti diff --git a/docs/wiki/Roadmap.md b/docs/wiki/Roadmap.md index dc05874..dc2906b 100644 --- a/docs/wiki/Roadmap.md +++ b/docs/wiki/Roadmap.md @@ -13,7 +13,7 @@ Il lavoro di dettaglio è nelle issue di Gitea, raggruppate per Finché il prodotto è in sviluppo le versioni restano **0.x**, anche dopo M13: la **1.0.0** sarà pubblicata solo quando verrà deciso esplicitamente. -**Completate:** M0 (0.0.1), M1 (0.1.0), M2 (0.2.0), M3 (0.3.0), M4 (0.4.0). **In corso:** M5. +**Completate:** M0 (0.0.1), M1 (0.1.0), M2 (0.2.0), M3 (0.3.0), M4 (0.4.0), M5 (0.5.0). **Prossima:** M6. | # | Milestone | Contenuto principale | Versione | |---|---|---|---| diff --git a/docs/wiki/Vendite.md b/docs/wiki/Vendite.md index dcbe9c8..2c65130 100644 --- a/docs/wiki/Vendite.md +++ b/docs/wiki/Vendite.md @@ -1,331 +1,350 @@ # Vendite -> **Stato:** bozza (motore documenti pronto, maschere in arrivo) · **Ultima revisione:** 2026-11-12 · **Versione software:** non ancora rilasciata (milestone M5) -> **Modulo di licenza:** CORE (XML SDI con EINV, contabilizzazione con ACCT, partite con FIN) · **Permessi principali:** `sales.invoice.issue`, `sales.deliverynote.reopen`, famiglia `sales.*` · **Specifica:** SPEC §11.3, §11.4 +> **Stato:** completa per la versione 0.5 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 (M5) +> **Modulo di licenza:** CORE (XML SDI con EINV, contabilizzazione con ACCT, partite con FIN) · **Permessi principali:** `sales.quote.*`, `sales.order.*`, `sales.delivery.*`, `sales.invoice.*` (emissione `sales.invoice.issue`) · **Specifica:** SPEC §9.4, §11.3, §11.4, §12.6 -Il modulo **Vendite** gestisce l'intero ciclo attivo: **preventivi**, **ordini clienti**, **DDT**, **fatture** -(immediate, accompagnatorie, differite, acconti, semplificate), **note di credito e di debito**, **pro-forma**, -**parcelle**, la **fatturazione differita** guidata e i corrispettivi registrati a mano. Tutti i documenti usano lo -stesso motore e la stessa maschera. +Il modulo **Vendite** gestisce il ciclo attivo: **preventivi**, **ordini clienti**, **DDT**, **fatture** (immediate, +accompagnatorie, differite, di acconto, parcelle), **note di credito e di debito**, **pro forma** e la +**fatturazione differita** dei DDT. Tutti i documenti usano lo stesso motore e la stessa maschera, si stampano in PDF +e si inviano per e-mail. + +> **In questa versione** i documenti hanno numeri, totali, castelletto IVA, bollo, ritenute, scadenze, collegamenti +> riga per riga, stampa ed e-mail. Arrivano più avanti: lo **scarico di magazzino** e l'impegno (M6, con il +> magazzino), la **registrazione contabile** (M7), le **partite** e il controllo del fido (M8), il **file XML** per lo +> SDI (M9) e il collegamento alle opportunità del **CRM** (M11). I pulsanti di queste funzioni compaiono quando la +> funzione c'è. ## Dove si trova Menu **Vendite** → *Preventivi*, *Ordini clienti*, *DDT*, *Fatture*, *Note di credito*, *Fatturazione differita*. +Le pro forma, le fatture di acconto e le parcelle stanno nell'elenco *Fatture*; le note di debito in *Note di credito*. -## Il motore dei documenti in sintesi +## Un giro completo in cinque minuti -Ogni tipo di documento (tabella *Tipi documento*, vedi [Tabelle azienda](Tabelle-azienda)) ha un **genere** e -insieme formano la sua definizione: numeratore e sezionale, causale di magazzino (se il documento carica o scarica -merce), **effetti** (impegno, scarico, partite, registrazione contabile, fattura elettronica), righe ammesse, da quali -documenti può essere **evaso** (ad esempio un DDT da un ordine), tipo documento SDI (TD), causale contabile, registro -IVA e modello di stampa. +Con l'azienda di esempio (vedi [Dati di base e di esempio](Dati-di-base-e-esempio)) trovi già un anno di vendite in +tutti gli stati. Per provare il ciclo da zero: -| Genere | Famiglia | Ciclo di vita | Evade | -|---|---|---|---| -| Preventivo | preventivi | documento | | -| Ordine cliente | ordini clienti | documento | preventivo | -| DDT di vendita | documenti di vendita | documento | ordine cliente | -| Fattura immediata, accompagnatoria, parcella | documenti di vendita | fattura | ordine cliente, pro forma | -| Fattura differita | documenti di vendita | fattura | DDT di vendita | -| Fattura di acconto | documenti di vendita | fattura | ordine cliente | -| Nota di credito, nota di debito | documenti di vendita | fattura | fatture | -| Pro forma | documenti di vendita | documento | ordine cliente | -| Autofattura o integrazione | documenti di vendita | fattura | fattura fornitore | -| Ordine fornitore | ordini fornitori | documento | | -| DDT fornitore | documenti di acquisto | documento | ordine fornitore | -| Fattura fornitore | documenti di acquisto | semplice | ordine fornitore, DDT fornitore | -| Nota di credito fornitore | documenti di acquisto | semplice | fattura fornitore | -| Movimento di magazzino | movimenti di magazzino | semplice | | +1. **Vendite → Preventivi → Nuovo preventivo** (`Ctrl+N`): scegli il cliente, aggiungi due righe, **Conferma**. +2. Sul preventivo premi **Crea Ordine cliente**: le righe passano all'ordine, collegate al preventivo. +3. Sull'ordine confermato premi **Crea DDT**: puoi consegnare solo una parte delle quantità. +4. **Vendite → Fatturazione differita**: indica il mese, **Cerca i DDT**, **Genera fatture**. +5. Apri la fattura, premi la **stampante** (`Ctrl+P`) per l'anteprima e il PDF, poi **⋯ → Invia per e-mail**. -I DDT non accettano righe di spesa o di sconto; i movimenti di magazzino solo articoli e righe descrittive. +## Gli elenchi (radar) + +![Khaemhat 0.5.0 · radar delle fatture di vendita](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatture-radar.png) +*Le fatture dell'azienda di esempio: numero, data, tipo, cliente, riferimento, imponibile, totale e stato. Le bozze +non hanno ancora un numero.* + +Ogni voce del menu apre un **radar** (vedi [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie#radar)): cerca per +numero, riferimento o cliente, filtra per **tipo**, **stato** e **anno**, ordina, scegli le colonne e salva la vista. +Un doppio clic (o `Invio`) apre il documento in una nuova scheda. + +![Khaemhat 0.5.0 · radar dei preventivi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-preventivi-radar.png) +*I preventivi: quelli evasi sono diventati ordini, uno è stato rifiutato, uno è in bozza.* + +**Nuovo** chiede il tipo quando l'elenco ne raccoglie più d'uno (ad esempio fattura immediata, accompagnatoria, +differita, di acconto, parcella o pro forma): + +![Khaemhat 0.5.0 · scelta del tipo di fattura](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-nuovo-tipo.png) + +## La maschera del documento + +![Khaemhat 0.5.0 · fattura immediata, scheda Righe](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento.png) +*Una fattura emessa: toolbar, intestazione con tipo, numero, stato, cliente e totale; righe; castelletto IVA, +scadenze e totali.* + +- **Toolbar**: nuovo, salva (`Ctrl+S`), annulla le modifiche, elimina (solo bozze), **stampa** (`Ctrl+P`), + **allegati**, le azioni del documento (*Conferma*, *Emetti*, *Crea …*) e il menu **⋯** con *Duplica*, *Chiudi*, + *Riapri*, *Annulla documento*, *Invia per e-mail*. A destra il **radar** e i pulsanti per il documento precedente e + successivo. +- **Intestazione**: tipo e numero (in bozza *Numero alla conferma*), data, stato, badge *Dato dimostrativo* per i dati + di esempio; cliente con codice, località e partita IVA, condizioni proposte (pagamento, listino, agente); il totale + del documento con imponibile e IVA. +- **Schede**: *Righe* (si apre lì), *Testata*, *Trasporto* (DDT e fatture accompagnatorie), *Totali*, *Scadenze*, + *Note*, *Allegati*, *Collegamenti*, *Storico*. Il numero accanto al nome della scheda conta righe, rate o + collegamenti. + +### Righe + +Ogni riga ha articolo (`F4` per cercarlo), descrizione, unità di misura, quantità, prezzo, sconti a cascata (`10+3`), +codice IVA e importo. Scegliendo l'articolo Khaemhat propone descrizione, unità, codice IVA e prezzo secondo l'ordine +*prezzo netto del cliente → listino del cliente → listino base → prezzo dell'articolo* (vedi +[Articoli e listini](Articoli-e-listini)). Oltre alle righe di merce ci sono le righe **descrittive** (solo testo), +le righe di **spesa** (trasporto, incasso) e le righe di **sconto**; i DDT non accettano spese né sconti. + +Sotto le righe: **castelletto IVA** (imponibile e imposta per codice IVA), **scadenze** (le rate della condizione di +pagamento) e **totali**. + +### Testata + +![Khaemhat 0.5.0 · fattura, scheda Testata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento-testata.png) +*La Testata con i gruppi Documento, Cliente, Condizioni e Dati fiscali.* + +| Gruppo | Campi | +|---|---| +| **Documento** | tipo, numero (alla conferma), **data** *, validità (preventivi), data di consegna (ordini), revisione, riferimento e data del cliente, documento rettificato (note) | +| **Cliente** | **cliente** *, agente, valuta, listino | +| **Condizioni** | pagamento, modalità, banca, sconto di piede, prezzi IVA inclusa | +| **Dati fiscali** | esigibilità IVA, split payment, bollo a carico del cliente, CIG e CUP per la PA | +| **Ritenuta, cassa previdenza, ENASARCO** | per parcelle e provvigioni: aliquote, base, tipo e causale della ritenuta, cassa | +| **Note** | note stampate sul documento | + +Scegliendo il cliente Khaemhat propone destinazione, listino, pagamento, agente e banca dalle sue **condizioni +commerciali** (vedi [Anagrafiche](Anagrafiche)). Per emettere una fattura ogni riga (tranne le descrittive) deve +avere il codice IVA. + +### Trasporto (DDT e fatture accompagnatorie) + +![Khaemhat 0.5.0 · DDT, scheda Trasporto](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-ddt-trasporto.png) +*Causale del trasporto, trasporto a cura del mittente, del destinatario o del vettore, porto, aspetto dei beni, +colli, pesi, inizio del trasporto.* + +I dati di trasporto finiscono nella stampa insieme agli spazi per le **firme** del conducente, del vettore e del +destinatario. + +### Collegamenti + +![Khaemhat 0.5.0 · ordine cliente, scheda Collegamenti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-collegamenti.png) +*Un ordine evaso: da quale preventivo nasce e quali DDT lo hanno evaso, con le quantità.* I documenti sono **collegati riga per riga**: quando un DDT evade un ordine, ogni riga del DDT ricorda la riga -d'ordine di origine e la quantità evasa. Così Khaemhat calcola i **residui**, permette di riaprirli e scrive nel file -XML della fattura i riferimenti all'ordine (*DatiOrdineAcquisto*) e ai DDT (*DatiDDT*). Il collegamento vale dalla -**conferma** del documento che evade: una bozza non toglie nulla al residuo, un documento annullato lo restituisce. +d'ordine e la quantità evasa. Così Khaemhat calcola i **residui** e lo stato (*Evaso in parte*, *Evaso*). Il +collegamento vale dalla **conferma** del documento che evade: una bozza non toglie nulla al residuo, un documento +annullato lo restituisce. Una nota di credito mostra qui la fattura che rettifica. + +## Dal preventivo alla fattura: Crea … ``` -Preventivo ──trasforma──► Ordine cliente ──evadi──► DDT ──fattura differita──► Fattura TD24 - └────────────── evadi ──────────────► Fattura immediata TD01 +Preventivo ──Crea Ordine──► Ordine cliente ──Crea DDT──► DDT ──Fatturazione differita──► Fattura differita (TD24) + └──────────── Crea Fattura immediata ─────────────► Fattura immediata (TD01) +Fattura ──Crea Nota di credito──► Nota di credito (TD04) ``` -Alla **conferma**, in un'unica operazione indivisibile, il documento riceve il numero, muove il magazzino, genera -le scadenze e le partite, crea la registrazione contabile e gli allegati: o riesce tutto o non cambia nulla. +![Khaemhat 0.5.0 · Crea ordine dal preventivo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-trasforma.png) +*Crea Ordine cliente da un preventivo: si scelgono le righe; per un documento che evade, la quantità proposta è +quella ancora da evadere.* -## La maschera di un documento di vendita +I pulsanti **Crea …** della toolbar elencano i documenti che si possono generare da quello aperto. Se il nuovo tipo +**evade** il vecchio (preventivo → ordine, ordine → DDT o fattura, DDT → fattura differita) le righe prendono solo le +**quantità residue**, che puoi ridurre, e restano collegate; altrimenti (ad esempio fattura → nota di credito) le +righe si **copiano**. Il nuovo documento nasce in **bozza** e si apre in una nuova scheda. **Duplica** crea invece un +documento dello stesso tipo con la data di oggi. -![020 · Fattura di vendita · righe](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/020-fattura-vendita-righe.png) -*Mockup 020 — fattura in bozza: toolbar con Conferma ed emetti, XML SDI, Contabilizza, Evadi da…; intestazione; righe con riga descrittiva; castelletto IVA, scadenze e totali (anteprima ridotta).* +## Preventivi -![021 · Fattura di vendita · testata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/021-fattura-vendita-testata.png) -*Mockup 021 — scheda Testata con i gruppi Documento, Controparte, Condizioni, Magazzino e trasporto (anteprima ridotta).* +Il preventivo ha una **validità** (giorni o data) che compare nella stampa. Quando il cliente accetta, **Crea Ordine +cliente**; se rifiuta, **⋯ → Segna come rifiutato** (il preventivo passa a *Chiuso*). Un preventivo trasformato in +ordine risulta *Evaso*. -![022 · Fattura di vendita · tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/022-fattura-vendita-tema-scuro.png) -*Mockup 022 — la stessa fattura in tema scuro con accento Malachite (anteprima ridotta).* +## Ordini clienti -La struttura è quella descritta in [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie): toolbar, intestazione a -tre blocchi, schede **Righe** (si apre lì), *Testata*, *Totali*, *Trasporto*, *Scadenze*, *Dati SDI/PA*, *Note*, -*Allegati*, *Collegamenti*, *Storico*. +L'ordine raccoglie gli impegni presi con il cliente. Da un ordine confermato si creano **DDT** o **fatture +immediate**, anche più di uno, finché resta un residuo; la scheda *Collegamenti* mostra chi ha evaso cosa. **⋯ → +Chiudi** chiude il residuo che non verrà consegnato, **Riapri** lo riporta aperto. Per la PA la Testata raccoglie CIG +e CUP, riportati nella stampa. -| Gruppo della Testata | Campi | +## DDT (documenti di trasporto) + +Il DDT accompagna la merce: si compila la scheda *Trasporto* e si stampa con gli spazi per le firme. Un DDT confermato +non ancora fatturato compare nella **fatturazione differita**; un DDT fatturato risulta *Evaso*. Finché non è +fatturato le righe si possono ancora correggere; **Annulla documento** lo annulla con un motivo. Lo scarico del +magazzino arriva con M6. + +## Fatture + +1. **Vendite → Fatture → Nuova fattura**, scegli il tipo, oppure parti da un ordine con **Crea Fattura immediata**. +2. Scegli il cliente: condizioni, listino, agente e destinazione vengono proposti. +3. Inserisci le righe e controlla castelletto IVA, scadenze e totali. +4. **Emetti** (permesso `sales.invoice.issue`): assegna il numero e blocca il documento. + +Una fattura **emessa non si modifica**. Per correggerla si emette una **nota di credito**; finché il file XML non è +stato inviato allo SDI si può **annullare** indicando il motivo (il numero resta usato). + +## Note di credito (TD04) e di debito (TD05) + +![Khaemhat 0.5.0 · nota di credito](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-nota-credito.png) +*Una nota di credito che storna un articolo difettoso: l'intestazione indica la fattura rettificata.* + +Si crea dalla fattura con **Crea Nota di credito** (le righe si copiano e si tolgono quelle che non vanno stornate) o +da **Vendite → Note di credito → Nuova nota**. Usa lo stesso numeratore delle fatture. + +## Pro forma e parcelle + +La **pro forma** è un documento **non fiscale** (ad esempio per chiedere un anticipo): stessa maschera della fattura, +numerazione propria (`PF-2026-0001`), nessun file XML e nessun effetto contabile; si trasforma in fattura quando +serve. La **parcella** (TD06) calcola la **cassa previdenza** e la **ritenuta d'acconto** e mostra il **netto a +pagare**; gli acconti su parcella usano TD03. + +## Fatturazione differita + +![Khaemhat 0.5.0 · fatturazione differita](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatturazione-differita.png) +*Ottobre: tre DDT da fatturare, uno per cliente; a destra la fattura in cui finirà ciascuno.* + +1. **Periodo e cliente**: *DDT dal* e *DDT al*, un cliente (vuoto per tutti), la **data delle fatture** e il + **raggruppamento** (*una fattura per cliente* o *una fattura per DDT*). Spunta *Emetti subito le fatture* per + numerarle subito; altrimenti restano in bozza da controllare. Premi **Cerca i DDT**. +2. **Scelta dei DDT**: l'elenco mostra i DDT confermati e non ancora fatturati con la fattura che verrà generata; + togli la spunta a quelli da fatturare più avanti. +3. **Genera fatture**: crea una fattura differita (TD24) per gruppo, con i riferimenti ai DDT nelle righe; i DDT + diventano *Evasi*. Il riepilogo indica quante fatture sono state create; un clic le apre. + +Con *una fattura per cliente* i DDT dello stesso cliente finiscono in una sola fattura, che prende pagamento, +banca e condizioni dal primo DDT; se un cliente ha DDT con condizioni diverse scegli *una fattura per DDT*. La fattura differita va emessa entro il giorno 15 del mese successivo a quello delle consegne. + +## Stampa e PDF + +![Khaemhat 0.5.0 · anteprima di stampa di una fattura](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-stampa.png) +*L'anteprima di stampa: intestazione dell'azienda, cliente, righe, riepilogo IVA, scadenze e totali.* + +La **stampante** della toolbar (`Ctrl+P`) salva il documento se serve e apre l'**anteprima di stampa**: + +| Pulsante | Che cosa fa | |---|---| -| **Documento** | Tipo documento, Sezionale/Numero, **Data** *, Registro IVA, Competenza IVA, Valuta, Cambio, Vostro riferimento | -| **Controparte** | **Cliente** *, Destinazione, Fatturare a, Agente, Listino | -| **Condizioni** | Pagamento, Inizio rate (es. fine mese), Banca azienda, Sconto piede %, Spese incasso, Bollo (automatico) | -| **Magazzino e trasporto** | Causale magazzino, Deposito, Vettore, Porto, Colli | +| **Stampa** | la stampa del browser (scegli la stampante o *Salva come PDF*) | +| **Apri PDF** / **Scarica PDF** | il PDF disegnato da Khaemhat, identico all'anteprima | +| **Salva come allegato** | conserva il PDF tra gli **allegati** del documento come nuova versione e segna il documento come *stampato* | +| 75% · 100% · 125% | lo zoom dell'anteprima | -Scegliendo il cliente, Khaemhat propone destinazione, listino, pagamento, agente e banca dalle sue condizioni -commerciali; dal tipo documento propone causale e deposito. +La stampa riporta i dati dell'azienda dal **profilo azienda** (ragione sociale, indirizzo, partita IVA, REA, capitale +sociale, contatti e la nota a piè di pagina; vedi [Tabelle azienda](Tabelle-azienda)), il logo (nel PDF se è un +JPEG), il cliente, i campi utili (pagamento, banca, riferimento, validità, agente, CIG e CUP), le righe, il +**riepilogo IVA**, le **scadenze**, i totali con bollo e ritenuta e le diciture previste (split payment, pro forma non +valida ai fini fiscali, fattura differita con i DDT). Le bozze, i documenti annullati e i dati dimostrativi portano +una scritta in evidenza. Il DDT ha in più il riquadro del trasporto e le firme: -Le **righe** hanno: articolo, descrizione, UM, quantità, prezzo, sconti (anche `5+2`), codice IVA, importo, deposito, -data di consegna. Le righe descrittive (solo testo) servono per riferimenti e note. Sotto la griglia: **castelletto -IVA** (imponibile e imposta per codice IVA, esigibilità), **scadenze** (rate con data, metodo e importo) e -**totali**. +![Khaemhat 0.5.0 · anteprima di stampa di un DDT](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-stampa-ddt.png) + +Ogni PDF salvato diventa un **allegato versionato** (vedi [Allegati e file](Allegati-e-file)): nella scheda +*Allegati* si vedono tutte le versioni, con chi le ha create e quando. Il generatore si chiama *Stampa del documento +in PDF*. + +## Invio per e-mail + +![Khaemhat 0.5.0 · invio di una fattura per e-mail](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-email.png) +*Destinatario dall'anagrafica del cliente, oggetto e testo dal modello; il PDF parte in allegato.* + +**⋯ → Invia per e-mail** (su un documento salvato) propone: + +- **Destinatari**: l'e-mail del cliente; più indirizzi separati da virgola o punto e virgola. +- **Oggetto** e **Messaggio** dal modello, con i campi `{{Documento}}`, `{{Numero}}`, `{{Data}}`, `{{Cliente}}`, + `{{Azienda}}` e `{{Totale}}` già compilati. Puoi cambiare tutto prima di inviare. + +**Invia** salva il PDF tra gli allegati come nuova versione, lo allega al messaggio, mette il messaggio **in coda** e +segna il documento come *inviato*. Il messaggio parte in background: tre tentativi a distanza crescente; l'esito (o +l'errore del server) è nel [Log](Log), sezione **E-mail/PEC**. La coda vive in memoria: un messaggio ancora in attesa +quando Khaemhat si ferma non parte, e il log lo dice. + +L'invio richiede un **server SMTP** configurato dall'amministratore con le variabili `KHAEMHAT_SMTP_*` (vedi +[Impostazioni](Impostazioni#e-mail-smtp)); senza, la finestra lo segnala e il pulsante *Invia* è spento. ## Tipi di documento e codici TD | Documento | Codice TD (SDI) | Note | |---|---|---| | Fattura immediata | **TD01** | emessa contestualmente alla cessione o prestazione | -| Fattura accompagnatoria | **TD01** | fattura con i dati di trasporto, fa anche da documento di trasporto e scarica il magazzino | +| Fattura accompagnatoria | **TD01** | fattura con i dati di trasporto, fa anche da documento di trasporto | | Fattura di acconto/anticipo su fattura | **TD02** | | | Fattura di acconto/anticipo su parcella | **TD03** | | | Nota di credito | **TD04** | riferita alla fattura da stornare | | Nota di debito | **TD05** | | | Parcella | **TD06** | con ritenuta d'acconto e cassa previdenza | | Fattura semplificata | **TD07** | per importi fino a 400 euro | -| Nota di credito semplificata | **TD08** | | -| Nota di debito semplificata | **TD09** | | +| Nota di credito / di debito semplificata | **TD08** / **TD09** | | | Fattura differita (beni con DDT, servizi documentati) | **TD24** | art. 21, comma 4, lett. a) DPR 633/72 | | Fattura differita (triangolazioni interne) | **TD25** | art. 21, comma 4, terzo periodo, lett. b) | -| Cessione di beni ammortizzabili e passaggi interni | **TD26** | anche dalle dismissioni dei cespiti | +| Cessione di beni ammortizzabili e passaggi interni | **TD26** | | | Autoconsumo o cessioni gratuite senza rivalsa (omaggi) | **TD27** | | -| Pro-forma | — | non è un documento fiscale: niente numerazione fiscale né XML | +| Pro forma | — | non è un documento fiscale: niente numerazione fiscale né XML | Le autofatture e le integrazioni (TD16-TD29) sono negli [Acquisti](Acquisti). L'elenco completo dei codici è in -[Fiscalità italiana](Fiscalita-italiana). - -## Preventivi - -![026 · Preventivo / offerta con revisioni](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/026-preventivo-offerta.png) -*Mockup 026 — preventivo inviato, revisione 2 di 2, collegato a un'opportunità CRM; azioni Trasforma in ordine, Nuova revisione, Accettato, Rifiutato (anteprima ridotta).* - -Il preventivo (offerta) ha una **validità** (es. 30 giorni, con data di scadenza) e uno stato (*Bozza*, *Inviato*, -*Accettato*, *Rifiutato*). Le schede sono *Righe*, *Testata*, *Totali*, *Condizioni e note*, *Revisioni*, *Allegati*, -*CRM*; sotto le righe il pannello **Revisioni** elenca le versioni con data, totale ed esito (*Superata*, *Inviata*). - -1. Crea il preventivo, inserisci le righe e invialo per e-mail. -2. Se il cliente chiede modifiche usa **Nuova revisione**: la versione precedente resta consultabile come - *superata*. -3. Segna l'esito con **Accettato** o **Rifiutato**. -4. **Trasforma in ordine** crea l'ordine cliente con le stesse righe e collega i due documenti. - -Con il modulo CRM il preventivo è collegato all'**opportunità** e ne aggiorna valore e fase (vedi [CRM](CRM)). -L'intestazione mostra anche il **margine** a chi può vedere i costi. - -## Ordini clienti - -![027 · Ordine cliente · evasione e residui](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/027-ordine-cliente.png) -*Mockup 027 — ordine di una PA con split payment, evaso al 38%: righe con ordinato, evaso, residuo, disponibile e stato; documenti collegati (anteprima ridotta).* - -Azioni contestuali: **Genera DDT**, **Genera fattura**, **Impegna**, **Ordina a fornitore**, **Chiudi residuo**. - -- **Evasione**: la griglia *Righe e stato di evasione* mostra per ogni riga quantità ordinata, evasa, residua e - disponibile, con uno stato (*Evaso*, *Parziale*, *Impegnato*, *Da ordinare*, *Aperto*) e una barra di avanzamento. - Il pannello **Documenti collegati** elenca DDT e fatture già generati e gli ordini fornitore nati dall'ordine. -- **Impegnato**: un ordine confermato **impegna** la merce, che resta in giacenza ma non è più disponibile per altri. -- **Residui**: le quantità non evase restano aperte finché non vengono consegnate o chiuse con **Chiudi residuo**. -- **Ordina a fornitore**: per le righe non disponibili crea un ordine fornitore. -- **Fido e scaduto**: se il cliente supera il fido o ha pagamenti scaduti, la conferma è bloccata; chi ha il - permesso di forzatura può procedere indicando il motivo. -- **Dati PA**: per la pubblica amministrazione la scheda *Dati PA (CIG/CUP)* raccoglie CIG, CUP e riferimenti alla - determina, riportati poi nell'XML della fattura. - -## DDT (documenti di trasporto) - -![028 · DDT · dati di trasporto, colli, firme](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/028-ddt-trasporto.png) -*Mockup 028 — DDT confermato e scaricato, da fatturare: scheda Trasporto con causale, vettore, porto, colli e pesi, firme (anteprima ridotta).* - -Il DDT accompagna la merce e **scarica il magazzino** alla conferma. Azioni: **Stampa 3 copie**, **Fattura questo -DDT**, **Etichette colli**, **Riapri**. - -| Gruppo (scheda Trasporto) | Campi | -|---|---| -| **Trasporto** | Causale del trasporto (vendita, reso, conto visione…), Trasporto a mezzo (mittente, destinatario, vettore), Vettore, Porto, resa (Incoterms), Inizio trasporto (data e ora), Targa, Annotazioni | -| **Colli e pesi** | Aspetto esteriore dei beni, Numero colli, Peso lordo, Peso netto, Volume, Pallet, Tracking | -| **Firme** | Conducente, Vettore, Destinatario (firme sulla stampa) | - -Il DDT si stampa in **tre copie**. Un DDT confermato ha le righe non modificabili; **Riapri** (permesso -`sales.deliverynote.reopen`) storna lo scarico e lo rigenera alla nuova conferma. I **resi** da cliente si -registrano con un DDT con causale di reso, che ricarica il magazzino. - -## Fatture - -1. **Vendite → Fatture**, **Nuovo** (`Ctrl+N`) oppure parti da un ordine o da un DDT con **Evadi da…**. -2. Scegli il cliente (F4 per cercare): condizioni, listino, agente e destinazione vengono proposti. -3. Inserisci le righe: il prezzo segue l'ordine *netto cliente → listino cliente → listino base → prezzo articolo* - (vedi [Articoli e listini](Articoli-e-listini)). -4. Controlla castelletto IVA, scadenze e totali. -5. **Conferma ed emetti**: assegna il numero, blocca il documento, scarica il magazzino (accompagnatoria), genera - scadenze e registrazione contabile. -6. **XML SDI** genera il file FatturaPA, che si invia dal canale configurato (vedi - [Fatturazione elettronica](Fatturazione-elettronica)). - -Una fattura **emessa non si modifica**. Per correggerla si emette una **nota di credito**; se l'XML non è ancora -stato inviato allo SDI si può **annullare** indicando il motivo. - -## Note di credito (TD04) - -![029 · Nota di credito TD04](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/029-nota-di-credito.png) -*Mockup 029 — nota di credito che storna una riga della fattura per reso merce difettosa, con rientro a magazzino e compensazione della partita (anteprima ridotta).* - -La nota di credito indica la **fattura stornata**, il **motivo** e la causale (ad esempio *reso da cliente*); se -c'è un reso la merce **rientra a magazzino**. Il pannello **Partite** mostra l'effetto sulla partita della fattura -(ad esempio *chiude parzialmente la rata 1/1*). L'XML è di tipo TD04 e riporta il riferimento alla fattura -d'origine. La nota di debito (TD05) funziona allo stesso modo per gli addebiti integrativi. - -## Pro-forma - -Documento **non fiscale** (ad esempio per chiedere un anticipo): stessa maschera della fattura, senza numerazione -fiscale, senza XML e senza registrazione contabile. Si trasforma in fattura quando serve. - -## Parcelle (TD06) - -Per le aziende o gli studi che emettono parcelle: la parcella calcola la **cassa previdenza** (contributo -integrativo, con IVA propria) e la **ritenuta d'acconto** che il cliente tratterrà, e mostra il **netto a pagare**. -Gli acconti su parcella usano TD03. - -## Fatturazione differita guidata - -![030 · Fatturazione differita · procedura guidata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/030-fatturazione-differita.png) -*Mockup 030 — procedura in quattro passi: parametri, selezione dei DDT non fatturati nel periodo, anteprima delle fatture, generazione (anteprima ridotta).* - -1. **Parametri**: DDT dal… al…, **data fattura**, **sezionale**, tipo (*Fattura differita TD24*), **raggruppa** - (*per cliente, rispettando la preferenza* di raggruppamento del cliente), *Genera XML SDI*, *Invia e-mail al - cliente*. -2. **Selezione DDT**: elenco dei DDT non fatturati nel periodo con la fattura che verrà generata; togli la spunta - ai DDT da escludere. -3. **Anteprima fatture**: numero di fatture e totale. -4. **Generazione**: numera le fatture, le contabilizza e, se richiesto, genera l'XML. I riferimenti ai DDT sono - riportati in riga e nell'XML (*DatiDDT*). - -La fattura differita va emessa entro il giorno 15 del mese successivo a quello delle consegne. La stessa procedura -è eseguibile da attività programmata (vedi [Automazioni](Automazioni)). +[Fiscalità italiana](Fiscalita-italiana). I tipi, i numeratori e i sezionali si configurano in *Tipi documento* (vedi +[Tabelle azienda](Tabelle-azienda)). ## Stati -| Documenti (preventivi, ordini, DDT) | Significato | +| Preventivi, ordini, DDT, pro forma | Significato | |---|---| -| **Bozza** | modificabile, senza numero definitivo, nessun effetto | -| **Confermato** | numerato, effetti applicati (impegno, scarico) | -| **Evaso parzialmente** / **Evaso** | una parte o tutto è passato al documento successivo | -| **Chiuso** | concluso (anche con residuo chiuso a mano) | -| **Annullato** | annullato con motivo | +| **Bozza** | modificabile, senza numero, nessun effetto | +| **Confermato** | numerato; le righe si possono ancora cambiare finché non sono evase | +| **Evaso in parte** / **Evaso** | una parte o tutto è passato al documento successivo | +| **Chiuso** | concluso, anche con residuo chiuso a mano (o preventivo rifiutato) | +| **Annullato** | annullato con motivo; il numero resta usato | | Fatture e note | Significato | |---|---| | **Bozza** | modificabile | -| **Emessa** | numerata, contabilizzata, immutabile | -| **XML generato** | file FatturaPA pronto | -| **Inviata allo SDI** | in attesa di esito | -| **Consegnata** | recapitata al cliente | -| **Scartata** | rifiutata dallo SDI: va corretta e rigenerata | -| **Non consegnata** | impossibile recapitarla: è disponibile nell'area riservata del cliente | +| **Emessa** | numerata e immutabile | +| **XML generato**, **Inviata allo SdI**, **Consegnata**, **Scartata**, **Non consegnata** | gli stati della fatturazione elettronica (M9) | -Altri badge indicano lo stato contabile (*Non contabilizzata*), del magazzino (*Scaricato*) o della fatturazione -(*Da fatturare*). - -Le fatture fornitore e i movimenti di magazzino hanno solo *Bozza*, *Confermato* e *Annullato*. - -Che cosa si può fare in ogni stato: +Che cosa si può fare: - Si **modifica** una bozza; di ordini, preventivi, DDT e pro forma confermati si possono ancora cambiare le righe finché non sono evasi del tutto, ma una quantità non scende sotto quella già evasa e una riga evasa non si toglie. - Numero, data di un documento numerato e tipo non cambiano più. - Si **elimina** solo una bozza, che non ha mai avuto un numero. - Si **annulla** un documento confermato non ancora evaso: il numero resta e le quantità che aveva evaso tornano ai - documenti d'origine. Una fattura si annulla **con un motivo** finché il file non è stato inviato allo SDI (o dopo - uno scarto); dopo, si fa una nota di credito. Non si annulla un documento che altri hanno già evaso. -- Si **chiude** il residuo di un documento evaso in parte (o anche del tutto); **Riapri** lo riporta allo stato che - dicono le sue righe. -- Si **duplica** o **trasforma** un documento in qualunque stato. + documenti d'origine. Una fattura si annulla **con un motivo** finché il file non è stato inviato allo SDI; dopo, si + fa una nota di credito. +- Si **chiude** il residuo di un documento evaso in parte; **Riapri** lo riporta allo stato che dicono le sue righe. +- Si **duplica** o si **crea** un altro documento da uno in qualunque stato. ## Numerazione -- Il formato è quello del numeratore del tipo documento, per **sezionale** e anno (vedi - [Tabelle azienda](Tabelle-azienda#numeratori)): ad esempio `{number}/{year}` per fatture e note (`418/2026`), - `OC-{year}-{number:D4}` per gli ordini (`OC-2026-0042`). +- Il formato è quello del numeratore del tipo documento, per **sezionale** e anno: ad esempio `{number}/{year}` per + fatture, note e DDT (`7/2026`), `OC-{year}-{number:D4}` per gli ordini (`OC-2026-0004`), `PRE-{year}-{number:D4}` + per i preventivi. - Il numero è assegnato **alla conferma**, in modo atomico: le bozze non consumano numeri, due conferme contemporanee non ricevono mai lo stesso numero e una conferma non riuscita restituisce il numero. Fatture, note di credito e note di debito condividono il numeratore delle fatture. -- Per fatture e note di credito **non sono ammessi buchi** e la data non può essere anteriore a quella dell'ultimo - documento numerato nello stesso numeratore. -- La data dei documenti con effetto contabile deve cadere in un **periodo fiscale aperto** (vedi esercizi e periodi in - [Tabelle azienda](Tabelle-azienda)). -- Con il primo documento di un anno nuovo la numerazione riparte da 1. +- Per fatture e note **non sono ammessi buchi** e la data non può essere anteriore a quella dell'ultimo documento + numerato nello stesso numeratore. +- La data deve cadere in un **esercizio aperto** (vedi [Tabelle azienda](Tabelle-azienda)); con il primo documento + di un anno nuovo la numerazione riparte da 1. ## Calcolo dei totali | Elemento | Regola | |---|---| -| **Imponibile di riga** | quantità x prezzo x (1 - sconto 1) x (1 - sconto 2)…, arrotondato a 2 decimali (arrotondamento commerciale) | +| **Imponibile di riga** | quantità × prezzo × (1 − sconto 1) × (1 − sconto 2)…, arrotondato a 2 decimali (arrotondamento commerciale) | | **Castelletto IVA** | imponibili raggruppati per codice IVA; imposta calcolata per aliquota sul totale del gruppo | | **Spese** | trasporto, incasso ecc. con il proprio codice IVA | -| **Sconto piede** | ripartito sulle righe | -| **Bollo** | 2,00 euro automatici se le operazioni esenti, non imponibili o fuori campo IVA superano 77,47 euro; la scheda del cliente indica se è a carico del cliente | +| **Sconto di piede** | ripartito sulle righe | +| **Bollo** | 2,00 euro automatici se le operazioni esenti, non imponibili o fuori campo IVA superano 77,47 euro; la scheda del cliente indica se è a suo carico | | **Ritenuta d'acconto** | sulle parcelle, calcolata sull'imponibile previsto; il netto a pagare la esclude | | **Cassa previdenza** | contributo sulle parcelle, con IVA propria | -| **Split payment** | per PA e soggetti obbligati: l'IVA è esposta ma versata dal cliente all'Erario; il totale *da versare* è il solo imponibile (esigibilità **S**) | +| **Split payment** | per PA e soggetti obbligati: l'IVA è esposta ma versata dal cliente all'Erario (esigibilità **S**) | | **Reverse charge** | fattura senza IVA con natura N6.x: l'imposta la integra il cliente | -| **IVA per cassa** | esigibilità differita al pagamento per chi ha aderito al regime (gestione completa prevista in fase 2) | **Scadenze**: generate dalla condizione di pagamento (rate, giorni, fine mese, giorno fisso, percentuali, IVA sulla -prima rata, sconto cassa); l'eventuale differenza di arrotondamento va sull'ultima rata. - -## Stampa, PDF ed e-mail - -![025 · Anteprima di stampa / PDF](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/025-anteprima-stampa-pdf.png) -*Mockup 025 — anteprima di stampa della fattura: modello, copie, lingua, zoom (anteprima ridotta).* - -`Ctrl+P` apre l'**anteprima di stampa** in una nuova scheda: si scelgono **modello**, numero di **copie** e -**lingua**, si ingrandisce (50%, 100%, adatta) e si stampa, si scarica il PDF o lo si invia. La stampa contiene le -diciture di legge previste ed è sempre in tema chiaro. Ogni PDF generato diventa un **allegato versionato** del -documento (vedi [Allegati e file](Allegati-e-file)). - -L'invio per **e-mail o PEC** allega il PDF (e, se richiesto, l'XML o la copia di cortesia ZIP) usando i modelli -e-mail dell'azienda; il canale preferito è nelle condizioni del cliente. - -## Collegamenti, duplicazione e corrispettivi - -- **Collegamenti**: la scheda omonima mostra i documenti di origine e quelli generati (ordine → DDT → fattura) con - le quantità; l'icona *Collegamenti* della toolbar apre lo stesso elenco. -- **Duplica** crea un nuovo documento in bozza con le stesse righe e la data di oggi; la **trasformazione** crea un - documento di un altro tipo della stessa direzione (vendita o acquisto). Se il nuovo tipo evade il vecchio - (preventivo → ordine, ordine → DDT, DDT → fattura differita) le righe prendono solo le **quantità residue** e - restano collegate; le righe che il nuovo tipo non accetta (ad esempio le spese in un DDT) non si copiano. -- **Corrispettivi**: le vendite al dettaglio si registrano a mano come corrispettivi giornalieri. - -## Report - -Giornale vendite, fatturato per cliente, agente, categoria e articolo (vedi [Report](Report)), DDT da fatturare, -ordini aperti, provvigioni agenti, margini (con il modulo REPORT). +prima rata); l'eventuale differenza di arrotondamento va sull'ultima rata. ## Permessi e licenza -Le vendite sono nel modulo **CORE**. Emettere una fattura richiede `sales.invoice.issue`; riaprire un DDT -`sales.deliverynote.reopen`; forzare un blocco di fido un permesso di tipo `override`. La generazione e l'invio -dell'XML richiedono **EINV**, la registrazione contabile **ACCT**, partite e incassi **FIN**. +Le vendite sono nel modulo **CORE**. Ogni famiglia ha due permessi, lettura (`.read`) e scrittura (`.write`): +`sales.quote`, `sales.order`, `sales.delivery`, `sales.invoice` (fatture, note e pro forma). La scrittura vale per +creare, modificare, confermare, chiudere, riaprire e annullare; per le fatture e le note **emettere** e annullare +richiede in più `sales.invoice.issue` ed eliminare una bozza `sales.invoice.delete`. Stampare richiede la sola +lettura. Vedi [Utenti e permessi](Utenti-e-permessi). ## Domande frequenti - **Non riesco a confermare la fattura: "data anteriore all'ultima numerata".** Nello stesso sezionale esiste una fattura con data successiva: correggi la data o usa un altro sezionale. -- **Il bollo non viene calcolato.** Il bollo è automatico solo se la parte esente, non imponibile o fuori campo - supera 77,47 euro; controlla i codici IVA delle righe. -- **Devo correggere una fattura già inviata.** Emetti una nota di credito (TD04) e una nuova fattura. +- **"Indica il codice IVA" su una riga.** Fatture e note si emettono solo con il codice IVA su ogni riga di merce, + spesa o sconto: sceglilo nella riga o nella scheda dell'articolo. +- **Il bollo non viene calcolato.** È automatico solo se la parte esente, non imponibile o fuori campo supera 77,47 + euro; controlla i codici IVA delle righe. +- **Un DDT non compare nella fatturazione differita.** Deve essere *Confermato*, non già fatturato e con data nel + periodo; se hai indicato un cliente, deve essere suo. +- **"Invia per e-mail" è spento.** Il documento ha modifiche non salvate: salvalo. Se la finestra dice che manca il + server SMTP, chiedi all'amministratore di configurarlo. +- **Ho inviato l'e-mail ma il cliente non l'ha ricevuta.** Guarda il [Log](Log), sezione *E-mail/PEC*: c'è la + risposta del server per ogni tentativo. +- **Devo correggere una fattura già inviata allo SDI.** Emetti una nota di credito (TD04) e una nuova fattura. ## Pagine correlate -[Anagrafiche](Anagrafiche) · [Articoli e listini](Articoli-e-listini) · [Magazzino](Magazzino) · -[Allegati e file](Allegati-e-file) · [Fatturazione elettronica](Fatturazione-elettronica) · -[Contabilità](Contabilita) · [Scadenzario](Scadenzario) · [CRM](CRM) · [Fiscalità italiana](Fiscalita-italiana) +[Anagrafiche](Anagrafiche) · [Articoli e listini](Articoli-e-listini) · [Tabelle azienda](Tabelle-azienda) · +[Allegati e file](Allegati-e-file) · [Log](Log) · [Magazzino](Magazzino) · +[Fatturazione elettronica](Fatturazione-elettronica) · [Contabilità](Contabilita) · [Scadenzario](Scadenzario) · +[Fiscalità italiana](Fiscalita-italiana) diff --git a/docs/wiki/_Sidebar.md b/docs/wiki/_Sidebar.md index 0a39344..acf2037 100644 --- a/docs/wiki/_Sidebar.md +++ b/docs/wiki/_Sidebar.md @@ -1,5 +1,8 @@ **[Khaemhat](Home)** +**Guida** +- [Guida all'uso](Guida-utente) + **Installazione** - [Primi passi](Primi-passi) - [Unraid](Installazione-Unraid) diff --git a/docs/wiki/img/accesso-login.png b/docs/wiki/img/accesso-login.png new file mode 100644 index 0000000..b79dc14 Binary files /dev/null and b/docs/wiki/img/accesso-login.png differ diff --git a/docs/wiki/img/accesso-verifica.png b/docs/wiki/img/accesso-verifica.png new file mode 100644 index 0000000..d05798c Binary files /dev/null and b/docs/wiki/img/accesso-verifica.png differ diff --git a/docs/wiki/img/vendite-collegamenti.png b/docs/wiki/img/vendite-collegamenti.png new file mode 100644 index 0000000..67b8c10 Binary files /dev/null and b/docs/wiki/img/vendite-collegamenti.png differ diff --git a/docs/wiki/img/vendite-ddt-trasporto.png b/docs/wiki/img/vendite-ddt-trasporto.png new file mode 100644 index 0000000..af3b367 Binary files /dev/null and b/docs/wiki/img/vendite-ddt-trasporto.png differ diff --git a/docs/wiki/img/vendite-documento-testata.png b/docs/wiki/img/vendite-documento-testata.png new file mode 100644 index 0000000..def5807 Binary files /dev/null and b/docs/wiki/img/vendite-documento-testata.png differ diff --git a/docs/wiki/img/vendite-documento.png b/docs/wiki/img/vendite-documento.png new file mode 100644 index 0000000..47864cd Binary files /dev/null and b/docs/wiki/img/vendite-documento.png differ diff --git a/docs/wiki/img/vendite-email.png b/docs/wiki/img/vendite-email.png new file mode 100644 index 0000000..f2dfc1b Binary files /dev/null and b/docs/wiki/img/vendite-email.png differ diff --git a/docs/wiki/img/vendite-fatturazione-differita.png b/docs/wiki/img/vendite-fatturazione-differita.png new file mode 100644 index 0000000..2dc7f57 Binary files /dev/null and b/docs/wiki/img/vendite-fatturazione-differita.png differ diff --git a/docs/wiki/img/vendite-fatture-radar.png b/docs/wiki/img/vendite-fatture-radar.png new file mode 100644 index 0000000..2ec9f72 Binary files /dev/null and b/docs/wiki/img/vendite-fatture-radar.png differ diff --git a/docs/wiki/img/vendite-nota-credito.png b/docs/wiki/img/vendite-nota-credito.png new file mode 100644 index 0000000..b7e35b2 Binary files /dev/null and b/docs/wiki/img/vendite-nota-credito.png differ diff --git a/docs/wiki/img/vendite-nuovo-tipo.png b/docs/wiki/img/vendite-nuovo-tipo.png new file mode 100644 index 0000000..586cbed Binary files /dev/null and b/docs/wiki/img/vendite-nuovo-tipo.png differ diff --git a/docs/wiki/img/vendite-preventivi-radar.png b/docs/wiki/img/vendite-preventivi-radar.png new file mode 100644 index 0000000..ae3c7d8 Binary files /dev/null and b/docs/wiki/img/vendite-preventivi-radar.png differ diff --git a/docs/wiki/img/vendite-stampa-ddt.png b/docs/wiki/img/vendite-stampa-ddt.png new file mode 100644 index 0000000..2ecaf15 Binary files /dev/null and b/docs/wiki/img/vendite-stampa-ddt.png differ diff --git a/docs/wiki/img/vendite-stampa.png b/docs/wiki/img/vendite-stampa.png new file mode 100644 index 0000000..bb6516e Binary files /dev/null and b/docs/wiki/img/vendite-stampa.png differ diff --git a/docs/wiki/img/vendite-trasforma.png b/docs/wiki/img/vendite-trasforma.png new file mode 100644 index 0000000..778b071 Binary files /dev/null and b/docs/wiki/img/vendite-trasforma.png differ diff --git a/src/Khaemhat.Application/Documents/DocumentEngine.cs b/src/Khaemhat.Application/Documents/DocumentEngine.cs index 73c1ab0..a13a8c6 100644 --- a/src/Khaemhat.Application/Documents/DocumentEngine.cs +++ b/src/Khaemhat.Application/Documents/DocumentEngine.cs @@ -4,6 +4,7 @@ using Khaemhat.Application.Tables; using Khaemhat.Core.Documents; using Khaemhat.Data; using Khaemhat.Data.Querying; +using Microsoft.Extensions.Logging; namespace Khaemhat.Application.Documents; @@ -95,7 +96,7 @@ public static class DocumentErrors /// reopen and delete for every family, with the numbering and the fulfilment links. The typed entry points are /// and . /// -public sealed class DocumentEngine +public sealed partial class DocumentEngine { private readonly IUnitOfWorkFactory _factory; private readonly PermissionService _permissions; @@ -103,6 +104,7 @@ public sealed class DocumentEngine private readonly FiscalYearService _fiscal; private readonly CompanyFiscalContext _packs; private readonly TimeProvider _clock; + private readonly ILogger _logger; /// Creates the engine. /// The units of work. @@ -111,8 +113,13 @@ public sealed class DocumentEngine /// The fiscal calendar (open periods). /// The fiscal pack of each company (tax rounding, stamp duty). /// The clock. - public DocumentEngine(IUnitOfWorkFactory factory, PermissionService permissions, AuditTrail audit, FiscalYearService fiscal, CompanyFiscalContext packs, TimeProvider clock) + /// The log (section Documenti): confirmations, changes of state, deletions. + public DocumentEngine( + IUnitOfWorkFactory factory, PermissionService permissions, AuditTrail audit, FiscalYearService fiscal, CompanyFiscalContext packs, TimeProvider clock, + ILogger logger) { + ArgumentNullException.ThrowIfNull(logger); + _logger = logger; ArgumentNullException.ThrowIfNull(packs); _packs = packs; ArgumentNullException.ThrowIfNull(factory); @@ -329,6 +336,7 @@ public sealed class DocumentEngine await store.RecordAsync(_audit, uow, AuditAction.Update, id, before, header, actor.UserName, cancellationToken).ConfigureAwait(false); await LinkAsync(uow, definition, record, actor.UserName, cancellationToken).ConfigureAwait(false); await uow.CommitAsync(cancellationToken).ConfigureAwait(false); + LogConfirmed(_logger, header.Kind, header.DocumentNumber ?? id.ToString(System.Globalization.CultureInfo.InvariantCulture), header.Status, company, actor.UserName); } return await GetAsync(actor, company, family, id, cancellationToken).ConfigureAwait(false) ?? throw new KeyNotFoundException(DocumentErrors.NotFound); @@ -455,6 +463,7 @@ public sealed class DocumentEngine await store.DeleteAsync(uow, id, cancellationToken).ConfigureAwait(false); await store.RecordAsync(_audit, uow, AuditAction.Delete, id, record.Header, null, actor.UserName, cancellationToken).ConfigureAwait(false); await uow.CommitAsync(cancellationToken).ConfigureAwait(false); + LogDeleted(_logger, record.Header.Kind, id, company, actor.UserName); } /// The actions the state of a document admits for an actor. @@ -671,6 +680,7 @@ public sealed class DocumentEngine } await uow.CommitAsync(cancellationToken).ConfigureAwait(false); + LogChanged(_logger, record.Header.Kind, record.Header.DocumentNumber ?? id.ToString(System.Globalization.CultureInfo.InvariantCulture), action, next, company, actor.UserName); } return await GetAsync(actor, company, family, id, cancellationToken).ConfigureAwait(false) ?? throw new KeyNotFoundException(DocumentErrors.NotFound); @@ -837,4 +847,13 @@ public sealed class DocumentEngine } private DateOnly Today() => DateOnly.FromDateTime(_clock.GetLocalNow().DateTime); + + [LoggerMessage(EventId = 4101, Level = LogLevel.Information, Message = "{Kind} {Number} confirmed ({Status}) in {Company} by {User}")] + private static partial void LogConfirmed(ILogger logger, DocumentKind kind, string number, DocumentStatus status, string company, string user); + + [LoggerMessage(EventId = 4102, Level = LogLevel.Information, Message = "{Kind} {Number}: {Action}, now {Status}, in {Company} by {User}")] + private static partial void LogChanged(ILogger logger, DocumentKind kind, string number, DocumentAction action, DocumentStatus status, string company, string user); + + [LoggerMessage(EventId = 4103, Level = LogLevel.Information, Message = "Draft {Kind} {Id} deleted in {Company} by {User}")] + private static partial void LogDeleted(ILogger logger, DocumentKind kind, long id, string company, string user); } diff --git a/src/Khaemhat.Web/wwwroot/app.css b/src/Khaemhat.Web/wwwroot/app.css index fd3c6d3..469eb44 100644 --- a/src/Khaemhat.Web/wwwroot/app.css +++ b/src/Khaemhat.Web/wwwroot/app.css @@ -358,11 +358,14 @@ h1[tabindex="-1"]:focus { outline: none; box-shadow: none; } @media (max-width: 1100px) { .kh-import { grid-template-columns: 1fr; } } /* Sales documents (SPEC §11.3, mockups 020-030): the panels under the lines, errors of the lines, the choice of a type. */ -.kh-doc-panels { display: grid; grid-template-columns: minmax(0, 2fr) minmax(0, 1.2fr) minmax(0, 1fr); gap: var(--kh-gap); padding: 14px 16px; align-items: start; } +.kh-doc-panels { display: grid; grid-template-columns: minmax(0, 1.8fr) minmax(0, 1.2fr) minmax(270px, 1fr); gap: var(--kh-gap); padding: 14px 16px; align-items: start; } .kh-doc-panels.wide { grid-template-columns: minmax(0, 2fr) minmax(0, 1fr); } .kh-doc-panels.single { grid-template-columns: minmax(0, 720px); } .kh-doc-panels .grid.compact td, .kh-doc-panels .grid.compact th { padding: 5px 10px; } .kh-doc-panels .totals span { white-space: nowrap; } +.kh-doc-panels .totals { gap: 4px 12px; } +.kh-doc-panels .totals span:nth-child(even) { min-width: 0; } +.kh-doc-panels .totals .big, .kh-doc-panels .totals .big + span { font-size: 15.5px; } .kh-doc-panels .kh-total-row td { font-weight: 600; border-top: 1px solid var(--kh-border); } .kh-doc-callout { margin: 12px 16px 0; align-items: center; } .kh-doc-callout span { flex: 1; } diff --git a/tests/Khaemhat.Core.Tests/Common/CronExpressionTests.cs b/tests/Khaemhat.Core.Tests/Common/CronExpressionTests.cs index 7ba25a2..065acb1 100644 --- a/tests/Khaemhat.Core.Tests/Common/CronExpressionTests.cs +++ b/tests/Khaemhat.Core.Tests/Common/CronExpressionTests.cs @@ -72,6 +72,8 @@ public sealed class CronExpressionTests Assert.AreEqual("Sistema", LogSections.Label(LogSection.System)); Assert.AreEqual(LogSection.Authentication, LogSections.FromCategory("Khaemhat.Application.Security.SignInService")); Assert.AreEqual(LogSection.ScheduledJobs, LogSections.FromCategory("Khaemhat.Application.Jobs.JobScheduler")); + Assert.AreEqual(LogSection.Documents, LogSections.FromCategory("Khaemhat.Application.Documents.DocumentEngine")); + Assert.AreEqual(LogSection.Email, LogSections.FromCategory("Khaemhat.Infrastructure.Mail.MailQueue")); Assert.AreEqual("Performance", LogSections.Scope(LogSection.Performance).Single().Value); } }