docs: user guide with real screenshots, developer README and M5 closing (#53 #54)
CI / Build and test (SQLite) (pull_request) Canceled after 0s
CI / PostgreSQL 16 integration (pull_request) Canceled after 0s
CI / PostgreSQL 17 integration (pull_request) Canceled after 0s
CI / Docker image (pull_request) Canceled after 0s
CI / YAML check (pull_request) Canceled after 0s

The wiki becomes a guide for the people who use Khaemhat: a new "Guida all'uso"
page walks from sign-in to an invoice sent by e-mail, and Vendite is rewritten
around the real screens of 0.5.0 (radars, document mask, Crea …, deferred
invoicing, print preview, mail). Primi passi, Dati di esempio, Allegati, Log
and Impostazioni describe what this version does, including the SMTP variables.

README.md turns into the installation guide for developers: prerequisites,
run-dev, tests with PostgreSQL, migrations, image and wiki publishing.

The engine now writes confirmations, changes of state and deletions to the
Documents log section, the last step of #53. ADR 0034 records the print and
mail decisions; CHANGELOG 0.5.0 and STATUS close the milestone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alby96andClaude Opus 5.5 committed 2026-11-12 17:38:14 +01:00
1 parent 826042f828
commit 4123ccacb2
33 files changed
+775 -315

No files matched your search

+33
View File
@@ -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
+162 -39
View File
@@ -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:<versione>
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/<n>-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 <http://localhost:5080> 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**: <http://localhost:5080/sviluppo/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:<versione>` (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) | <https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki> (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 | <https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki> |
## 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).
+16 -14
View File
@@ -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,
@@ -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).
+6 -1
View File
@@ -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.
+2 -1
View File
@@ -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. |
+17 -2
View File
@@ -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.
+160
View File
@@ -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)
+5 -1
View File
@@ -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) |
+14
View File
@@ -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*.
+2 -2
View File
@@ -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 |
+16 -6
View File
@@ -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
+1 -1
View File
@@ -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 |
|---|---|---|---|
+264 -245
View File
@@ -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)
+3
View File
@@ -1,5 +1,8 @@
**[Khaemhat](Home)**
**Guida**
- [Guida all'uso](Guida-utente)
**Installazione**
- [Primi passi](Primi-passi)
- [Unraid](Installazione-Unraid)
Binary file not shown.

After

Width:  |  Height:  |  Size: 188 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 182 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 99 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 145 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 102 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 92 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 99 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 105 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 109 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 121 KiB

@@ -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
/// <see cref="DocumentService{THeader, TLine}"/> and <see cref="DocumentCopyService"/>.
/// </summary>
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<DocumentEngine> _logger;
/// <summary>Creates the engine.</summary>
/// <param name="factory">The units of work.</param>
@@ -111,8 +113,13 @@ public sealed class DocumentEngine
/// <param name="fiscal">The fiscal calendar (open periods).</param>
/// <param name="packs">The fiscal pack of each company (tax rounding, stamp duty).</param>
/// <param name="clock">The clock.</param>
public DocumentEngine(IUnitOfWorkFactory factory, PermissionService permissions, AuditTrail audit, FiscalYearService fiscal, CompanyFiscalContext packs, TimeProvider clock)
/// <param name="logger">The log (section Documenti): confirmations, changes of state, deletions.</param>
public DocumentEngine(
IUnitOfWorkFactory factory, PermissionService permissions, AuditTrail audit, FiscalYearService fiscal, CompanyFiscalContext packs, TimeProvider clock,
ILogger<DocumentEngine> 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);
}
/// <summary>The actions the state of a document admits for an actor.</summary>
@@ -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);
}
+4 -1
View File
@@ -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; }
@@ -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);
}
}