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>
No files matched your search
@@ -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
|
||||
|
||||
@@ -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).
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
- **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).
|
||||
|
||||

|
||||
|
||||
## 3. Preparare l'azienda
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
**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.
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
**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).
|
||||
|
||||

|
||||
|
||||
## 6. Vendere
|
||||
|
||||

|
||||
|
||||
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.
|
||||
|
||||

|
||||
|
||||
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.
|
||||
|
||||

|
||||
|
||||
Tutto il ciclo è spiegato in [Vendite](Vendite).
|
||||
|
||||
## 7. Stampare e inviare
|
||||
|
||||

|
||||
|
||||
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.
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
|
||||
**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
|
||||
|
||||

|
||||
|
||||
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).
|
||||
|
||||

|
||||
|
||||
## 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)
|
||||
@@ -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)
|
||||
|
||||

|
||||
|
||||
@@ -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) |
|
||||
|
||||
@@ -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*.
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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).*
|
||||
|
||||

|
||||
|
||||
*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).*
|
||||
|
||||

|
||||
|
||||
*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)).
|
||||

|
||||
|
||||
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
|
||||
|
||||
|
||||
@@ -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 |
|
||||
|---|---|---|---|
|
||||
|
||||
@@ -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)
|
||||
|
||||

|
||||
*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.
|
||||
|
||||

|
||||
*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):
|
||||
|
||||

|
||||
|
||||
## La maschera del documento
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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)
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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.
|
||||

|
||||
*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.
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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*.
|
||||
|
||||

|
||||
*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)
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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**.
|
||||

|
||||
|
||||
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
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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)
|
||||
|
||||

|
||||
*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)
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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
|
||||
|
||||

|
||||
*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)
|
||||
@@ -1,5 +1,8 @@
|
||||
**[Khaemhat](Home)**
|
||||
|
||||
**Guida**
|
||||
- [Guida all'uso](Guida-utente)
|
||||
|
||||
**Installazione**
|
||||
- [Primi passi](Primi-passi)
|
||||
- [Unraid](Installazione-Unraid)
|
||||
|
||||
|
After Width: | Height: | Size: 188 KiB |
|
After Width: | Height: | Size: 182 KiB |
|
After Width: | Height: | Size: 90 KiB |
|
After Width: | Height: | Size: 99 KiB |
|
After Width: | Height: | Size: 145 KiB |
|
After Width: | Height: | Size: 118 KiB |
|
After Width: | Height: | Size: 102 KiB |
|
After Width: | Height: | Size: 92 KiB |
|
After Width: | Height: | Size: 99 KiB |
|
After Width: | Height: | Size: 105 KiB |
|
After Width: | Height: | Size: 109 KiB |
|
After Width: | Height: | Size: 87 KiB |
|
After Width: | Height: | Size: 115 KiB |
|
After Width: | Height: | Size: 124 KiB |
|
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);
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||