Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2c56c0dff0 | ||
|
|
cd3e22e8c7 | ||
|
|
4123ccacb2 | ||
|
|
826042f828 | ||
|
|
f12848865d | ||
|
|
ddd2273f7e | ||
|
|
fa9304834a | ||
|
|
5ba28483a8 | ||
|
|
02219df9de | ||
|
|
11f69b6111 | ||
|
|
e53b14a3c5 | ||
|
|
b323d70f83 | ||
|
|
caa33a2cee | ||
|
|
3dbbaba86e | ||
|
|
c8241a414e | ||
|
|
3401271483 | ||
|
|
a9eda510f2 | ||
|
|
321aae7e81 | ||
|
|
07555de700 | ||
|
|
9bcf8c1082 | ||
|
|
34e196424f | ||
|
|
25f8a7ad30 | ||
|
|
49d2bb166b | ||
|
|
8079d3da69 | ||
|
|
f7c9cf6da8 | ||
|
|
4ecf15b609 | ||
|
|
b4a2802bed | ||
|
|
8198e0a754 | ||
|
|
f415dc37a8 | ||
|
|
acb7e598d1 | ||
|
|
75d60ee4c4 | ||
|
|
d0f9d0e651 | ||
|
|
d958e7372d | ||
|
|
b341ade9e9 | ||
|
|
cf6f849cc1 | ||
|
|
1c30054e3d | ||
|
|
4502526f4d | ||
|
|
032c602b49 | ||
|
|
4582837b70 | ||
|
|
edce4702da |
No files matched your search
@@ -10,6 +10,10 @@
|
||||
.data/
|
||||
out/
|
||||
docs/
|
||||
# ...except the copy of the wiki and the images it shows, shipped as the in-app help (ADR 0023).
|
||||
!docs/wiki/
|
||||
!docs/mockups/thumbs/
|
||||
!docs/mockups/png/
|
||||
deploy/
|
||||
*.md
|
||||
!README.md
|
||||
|
||||
@@ -135,19 +135,29 @@ jobs:
|
||||
docker build -f docker/Dockerfile --build-arg VERSION=0.0.0-ci --build-arg GIT_SHA="$(git rev-parse --short HEAD)" \
|
||||
--label khaemhat-ci.job="$(hostname)" -t "$NAME:image" .
|
||||
|
||||
- name: Smoke test (/health/live, non-root user, PUID/PGID)
|
||||
- name: Smoke test (start-up, login page, non-root user, PUID/PGID)
|
||||
run: |
|
||||
docker network create --label khaemhat-ci.job="$(hostname)" "$NAME"
|
||||
docker network connect "$NAME" "$(hostname)"
|
||||
# Since M2 the instance needs a key, a super user and a first company; the key is thrown away with the run.
|
||||
docker run -d --name "$NAME-app" --network "$NAME" --label khaemhat-ci.job="$(hostname)" \
|
||||
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test -e PUID=99 -e PGID=100 "$NAME:image"
|
||||
for i in $(seq 1 30); do
|
||||
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/live"; then echo; break; fi
|
||||
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test \
|
||||
-e KHAEMHAT_SECRET_KEY="$(head -c 32 /dev/urandom | base64)" \
|
||||
-e KHAEMHAT_SUPERUSER=root -e KHAEMHAT_SUPERUSER_PASSWORD=Ci-Smoke-Test-2026 -e KHAEMHAT_COMPANY_CODE=CI \
|
||||
-e PUID=99 -e PGID=100 "$NAME:image"
|
||||
for i in $(seq 1 60); do
|
||||
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/ready"; then echo; break; fi
|
||||
sleep 2
|
||||
done
|
||||
curl -fsS --max-time 5 "http://$NAME-app:8080/health"
|
||||
echo
|
||||
curl -fsS --max-time 5 "http://$NAME-app:8080/" | grep -q "in costruzione"
|
||||
test "$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "http://$NAME-app:8080/")" = "302"
|
||||
# Read the whole response first: grep -q closes the pipe at the first match, and with pipefail the
|
||||
# write error of curl (exit 23) would fail the step depending on timing.
|
||||
login="$(curl -fsS --max-time 5 "http://$NAME-app:8080/login")"
|
||||
grep -q "Accedi" <<<"$login"
|
||||
headers="$(curl -fsS -D - -o /dev/null --max-time 5 "http://$NAME-app:8080/login")"
|
||||
grep -qi "content-security-policy" <<<"$headers"
|
||||
test "$(docker exec "$NAME-app" sh -c 'stat -c %u:%g /proc/1')" = "99:100"
|
||||
test "$(docker exec "$NAME-app" stat -c %u:%g /data)" = "99:100"
|
||||
docker exec "$NAME-app" pg_dump --version
|
||||
|
||||
@@ -113,15 +113,18 @@ jobs:
|
||||
--label khaemhat-ci.job="$(hostname)" \
|
||||
-t "$IMAGE:$VERSION" .
|
||||
|
||||
- name: Smoke test (/health/live)
|
||||
- name: Smoke test (/health/ready)
|
||||
if: env.PUBLISHED != 'true'
|
||||
run: |
|
||||
docker network create --label khaemhat-ci.job="$(hostname)" "$NAME"
|
||||
docker network connect "$NAME" "$(hostname)"
|
||||
docker run -d --name "$NAME-app" --network "$NAME" --label khaemhat-ci.job="$(hostname)" \
|
||||
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test "$IMAGE:$VERSION"
|
||||
for i in $(seq 1 30); do
|
||||
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/live"; then echo; break; fi
|
||||
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test \
|
||||
-e KHAEMHAT_SECRET_KEY="$(head -c 32 /dev/urandom | base64)" \
|
||||
-e KHAEMHAT_SUPERUSER=root -e KHAEMHAT_SUPERUSER_PASSWORD=Ci-Smoke-Test-2026 -e KHAEMHAT_COMPANY_CODE=CI \
|
||||
"$IMAGE:$VERSION"
|
||||
for i in $(seq 1 60); do
|
||||
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/ready"; then echo; break; fi
|
||||
sleep 2
|
||||
done
|
||||
report="$(curl -fsS --max-time 5 "http://$NAME-app:8080/health")"
|
||||
|
||||
@@ -424,3 +424,4 @@ deploy/.env
|
||||
out/
|
||||
# License signing keys (tools/Khaemhat.LicenseTool): the private key never enters the repository (ADR 0008).
|
||||
*.khkey
|
||||
*.pem
|
||||
@@ -7,6 +7,270 @@ 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
|
||||
di credito e di debito, parcella, pro forma, autofattura, ordine fornitore, DDT fornitore, fattura e nota di credito
|
||||
fornitore, movimento di magazzino) che ne decide famiglia, ciclo di vita, effetti, righe ammesse, documenti evadibili
|
||||
e permessi. Tabelle `sale_quotations`, `sale_orders`, `sale_documents`, `purchase_orders`, `purchase_documents`,
|
||||
`inventory_documents` con le righe e `document_links`.
|
||||
- Stati e azioni ammesse per stato (`DocumentStateMachine`): ciclo *documento* (bozza, confermato, evaso in parte,
|
||||
evaso, chiuso, annullato), *fattura* (bozza, emessa, XML generato, inviata, consegnata, scartata, non consegnata,
|
||||
annullata) e *semplice*; fattura emessa immutabile, annullamento con motivo solo prima dell'invio allo SDI.
|
||||
- Numerazione alla conferma dentro la transazione e sotto il lock del numeratore (advisory lock su PostgreSQL, lock di
|
||||
scrittura su SQLite): nessun numero doppio, un rollback restituisce il numero, controllo della data fuori sequenza
|
||||
sui numeratori senza buchi, numeratore dell'anno nuovo creato da solo, elenco dei numeri mancanti.
|
||||
- Evasione riga per riga: copia e trasformazione dei documenti con le quantità residue, collegamenti registrati alla
|
||||
conferma e tolti all'annullamento, stato evaso/evaso in parte calcolato dalle righe, chiusura e riapertura del
|
||||
residuo. Servizio generico `DocumentService<THeader, TLine>` per famiglia e `DocumentCopyService`.
|
||||
- Totali dei documenti (#48, ADR 0033): importo di riga con sconti a cascata, spese e righe di sconto, sconto di
|
||||
piede sulle merci, prezzi IVA compresa scorporati per aliquota, castelletto IVA per codice con imposta sul totale del
|
||||
gruppo, esigibilità (immediata, differita, split payment), bollo sopra 77,47 euro di operazioni senza IVA (addebitato
|
||||
al cliente o no), cassa previdenza con la sua IVA, ritenuta d'acconto (anche sul 50% o 20% per gli agenti), ENASARCO,
|
||||
netto a pagare. Scadenze dalle condizioni di pagamento con fine mese, giorno fisso, mesi esclusi del cliente, IVA
|
||||
sulla prima rata e arrotondamento sull'ultima. Tabelle `document_tax_summaries` e `document_installments`,
|
||||
ricalcolate a ogni salvataggio.
|
||||
- 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
|
||||
di base (province, comuni e CAP compresi), clienti, fornitori e contatti, articoli e listini, i codici automatici,
|
||||
l'import/export guidato e i dati di esempio: le prime maschere gestionali vere.
|
||||
|
||||
### Added
|
||||
- Pacchetto fiscale (ADR 0025): `IFiscalPack` con codici IVA, motore delle imposte e calendario fiscale, più funzioni
|
||||
facoltative per paese; `FiscalPackCatalog` sceglie il pacchetto dal paese dell'azienda. Il pacchetto italiano
|
||||
(`IT 2026.2`) porta nature IVA N1-N7, codici IVA di base, code list FatturaPA (specifiche **1.9.1**: TD, MP, TP,
|
||||
RF, ritenute, casse previdenziali), castelletto IVA con arrotondamento sul totale per aliquota, regola del bollo,
|
||||
scadenze IVA mensili e trimestrali con slittamenti di agosto e dei festivi, ritenute, regole di base dei cespiti e
|
||||
codici tributo F24.
|
||||
- Controlli degli identificativi: IBAN (mod 97 e lunghezza per paese), codici a barre EAN/GTIN, e-mail; partita IVA
|
||||
italiana, codice fiscale con calcolo, lettura dei dati e omocodia, codice destinatario SDI per azienda, PA, privato
|
||||
ed estero; `ViesClient` per la verifica delle partite IVA comunitarie (esito *valida*, *non valida* o *servizio
|
||||
non disponibile*).
|
||||
- Tabelle azienda (ADR 0026): 26 tabelle codificate (codici IVA, modalità e condizioni di pagamento con le rate,
|
||||
banche, valute, tipi documento, numeratori, listini, sconti, agenti, depositi, causali di magazzino, unità di misura,
|
||||
vettori, porto, trasporto, causali di trasporto, aspetto dei beni, rese, nazioni, province, comuni, categorie,
|
||||
centri di costo, commesse) con un'unica maschera a `/tabelle/<tabella>`: elenco con filtro attive/disattivate,
|
||||
dettaglio con errori e avvisi, disattivazione al posto dell'eliminazione per le righe usate, export e import CSV
|
||||
tutto o niente, storico e cache condivisa fra istanze. Indice delle tabelle a `/tabelle` e voci nel menu.
|
||||
- Profilo azienda a schede (dati societari, fiscale e SDI, banche, stampa, esercizi, trasmittente e intermediario)
|
||||
con i controlli del pacchetto fiscale; esercizi e mesi con blocco e sblocco; cambi BCE giornalieri (attività di
|
||||
sistema) e cambi manuali.
|
||||
- Dati di base aggiunti alla creazione dell'azienda e a ogni avvio, solo per i codici mancanti: paesi, valute, unità
|
||||
di misura, codici IVA, pagamenti, tipi documento, numeratori, causali, trasporti, deposito, listino ed esercizio in
|
||||
corso. Versione salvata nelle impostazioni dell'azienda (`IT 2026.3`).
|
||||
- Province e comuni dall'elenco ISTAT dei codici dei comuni al 26/02/2026 (ADR 0028, CC BY 4.0): 110 province e
|
||||
7.894 comuni con codice catastale, provincia, regione e codice ISTAT, nei dati di base del pacchetto italiano
|
||||
(`IT 2026.3`), con i CAP di GeoNames (CC BY 4.0) per 7.750 comuni; i mancanti si completano nella tabella
|
||||
*Comuni*. `tools/Khaemhat.PlacesTool` rigenera i due elenchi dai file scaricati.
|
||||
- `scripts/seed.sh --base [--company CODICE]`, incluso nell'immagine in `/app/scripts/`.
|
||||
- Codici automatici (ADR 0027): maschere per clienti, fornitori, lead, articoli, cespiti, opportunità, ticket,
|
||||
contratti e interventi con `{seq:0000}`, `{anno}` e `{categoria}`, anteprima del prossimo codice, codice manuale
|
||||
ammesso o no, progressivi in `code_sequences` assegnati nella transazione del salvataggio (nessun doppione, nessun
|
||||
numero perso se il salvataggio fallisce, codici già presenti saltati).
|
||||
- Compilazione automatica: comune, provincia e regione dal CAP e CAP dal comune, codice fiscale, verifica VIES, ABI,
|
||||
CAB, banca e BIC dall'IBAN, data di consegna sul calendario lavorativo; ogni opzione si spegne nelle preferenze, e
|
||||
il job dei cambi BCE salta le aziende che l'hanno spento. Pagina *Preferenze azienda* (`/tabelle/preferenze`).
|
||||
- Anagrafiche (ADR 0029): clienti, fornitori, prospect e lead in un solo archivio, con tre radar
|
||||
(`/anagrafiche/clienti`, `/fornitori`, `/contatti`) con ricerca, filtri rapidi, disattivazione e riattivazione di
|
||||
più righe, e la scheda a otto schede: dati principali, indirizzi, contatti, condizioni di vendita e di acquisto,
|
||||
fiscale e SDI (fatturazione elettronica, regime IVA, ritenute e casse, dichiarazione d'intento), banche, note e
|
||||
allegati, storico. Controlli del pacchetto fiscale su partita IVA, codice fiscale, codice destinatario e paese, con
|
||||
avvisi che non bloccano (P.IVA doppia, privato senza codice fiscale); codice destinatario proposto per privati ed
|
||||
esteri; verifica VIES al salvataggio e su richiesta; calcolo del codice fiscale; CAP e comune compilati a vicenda.
|
||||
*Converti in cliente* per prospect e lead (nuovo codice, il vecchio resta come codice precedente) e per i fornitori
|
||||
(diventano anche clienti con lo stesso codice). Un'anagrafica usata da altri dati si disattiva invece di cancellarsi.
|
||||
- Dati di esempio delle anagrafiche con `KHAEMHAT_SEED_DEMO=true`: 3 agenti, 12 clienti di ogni tipo soggetto,
|
||||
5 fornitori, 2 prospect e 2 lead, con numeri inventati ma formalmente validi.
|
||||
- Articoli (ADR 0030): radar `/anagrafiche/articoli` con ricerca anche per codice a barre, filtri per tipo,
|
||||
categoria, magazzino e stato, disattivazione e riattivazione; scheda con dati principali, UM alternative, codici
|
||||
alternativi, listini e prezzi netti dei clienti, fornitori con il fornitore abituale, sostitutivi, note e allegati,
|
||||
storico. Codice dalla maschera per categoria, verifica EAN con duplicati bloccati o segnalati secondo le
|
||||
preferenze, NC8, solo le merci a magazzino; costi visibili solo con `items.cost.read` e conservati per chi non li
|
||||
vede; un articolo usato si disattiva invece di cancellarsi.
|
||||
- Listini (ADR 0030): prezzi con data di validità e storico, listino base, listini derivati con ricarico e
|
||||
arrotondamento, griglia `/anagrafiche/listini` articoli x listini con modifica in cella, prezzi netti di un
|
||||
cliente, margine e aggiornamento massivo con anteprima; ricerca del prezzo per i documenti (netto, listino del
|
||||
documento o del cliente, base, articolo) con la fonte e gli sconti del cliente a cascata.
|
||||
- Scheda *Articoli e codici* delle anagrafiche: i codici con cui un cliente o un fornitore chiama i tuoi articoli,
|
||||
trovati dalla ricerca nei suoi documenti.
|
||||
- 120 articoli di esempio con listini *Pubblico* e *Rivenditori*, prezzi dell'anno precedente, fornitori, UM e
|
||||
codici alternativi, sostitutivi e prezzi netti di un cliente; `scripts/seed.sh --demo [--scale N]` carica i dati
|
||||
di esempio da riga di comando e moltiplica il catalogo per le prove di prestazione.
|
||||
- Import/export guidato (ADR 0031) in *Amministrazione → Import / export dati*: CSV (separatore e codifica dedotti),
|
||||
XLSX (lettore interno, primo foglio) e JSON per clienti, fornitori, articoli e prezzi di listino e netti cliente;
|
||||
mappatura automatica delle colonne con alias, validazione riga per riga con le regole della scheda, esiti *nuovo*,
|
||||
*aggiorna*, *avviso*, *errore*, opzioni per codici esistenti o mancanti, VIES e comune da CAP, report errori CSV,
|
||||
esito nel log. Export con le stesse colonne dell'import e modelli vuoti. Giacenze iniziali e piano dei conti (tracciato
|
||||
`codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag` e `khaemhat-coa.json`) si verificano
|
||||
già, la scrittura arriva con M6 e M7.
|
||||
|
||||
### Changed
|
||||
- Tabella *Listini*: nuovi campi *Listino base* (uno solo) e *Derivato da*; la migrazione marca come base il listino
|
||||
`BASE` esistente.
|
||||
- Il componente dei passi verticali mette il dettaglio di ogni passo su una riga propria.
|
||||
|
||||
### Known issues
|
||||
- L'azienda demo creata da `KHAEMHAT_SEED_DEMO` ha il profilo vuoto (indirizzo, partita IVA): va compilato prima dei
|
||||
documenti (M5).
|
||||
- Mancano le banche ABI/CAB nei dati di base: non c'è ancora una fonte con licenza compatibile (#45).
|
||||
|
||||
## [0.3.0] - 2026-11-11
|
||||
|
||||
M3 — Framework UI. La shell dell'applicazione, la libreria di componenti `Kh*` con griglie, radar e pagine record, la
|
||||
dashboard a widget, le preferenze dell'utente, ricerca, aiuto e notifiche, allegati e anteprima di stampa, tutto
|
||||
provato su un documento di sviluppo in attesa delle maschere vere (da M4).
|
||||
|
||||
### Added
|
||||
- Libreria di componenti `Kh*` (ADR 0024): campi con numeri e date all'italiana (`T`, `F`, `I`, `+n`, cifre senza
|
||||
separatori) e calcolo `=10*3`, messaggi accanto al campo e riepilogo che porta al campo, pannelli, tessere, badge,
|
||||
chip, importi, schede con `Alt+1`…`Alt+9`, passi, finestre di dialogo, pannelli laterali e messaggi a comparsa.
|
||||
- `KhIconToolbar` su una riga con il menu `…`, `KhDocHead` a tre blocchi e le basi `RecordPage`, `DocumentPage`,
|
||||
`MasterDataPage` con comandi standard, conferme e scorciatoie `Ctrl+S`, `Ctrl+N`, `Ctrl+P`, `Ctrl+Canc`, `F9`.
|
||||
- Liste con un solo modello di richiesta (`ListQuery`, `ListFields`): la stessa descrizione dei campi diventa SQL o
|
||||
filtra righe in memoria. `KhGrid` virtualizzata (100.000 righe) con ordinamento, selezione, tastiera, modifica in
|
||||
riga, totali, menu di riga, colonne salvate ed esportazione CSV/XLSX; `KhRadar` con ricerca, filtri rapidi,
|
||||
costruttore di filtri e filtri salvati; finestra radar per la ricerca `F4`; `KhLinesGrid` per le righe dei
|
||||
documenti.
|
||||
- *Il mio profilo*: dati personali, cambio password che chiude le altre sessioni, attivazione e disattivazione della
|
||||
verifica in due passaggi con codici di recupero.
|
||||
- Catalogo dei componenti e documento di prova per gli sviluppatori (`/sviluppo/componenti`, `/sviluppo/documento`,
|
||||
solo in sviluppo).
|
||||
- Primi screenshot reali nella wiki (`docs/wiki/img/`): finestra, menu compresso, ricerca, notifiche, aiuto,
|
||||
dashboard, profilo, tema scuro, documento, allegati, storico, anteprima di stampa, telefono.
|
||||
- Shell (mockup 004, 007, 013): barra superiore con marchio e versione, cambio azienda per gli account di istanza,
|
||||
ricerca, recenti, notifiche, tema rapido, aiuto e menu utente; menu laterale per sezioni con voci filtrate da
|
||||
licenza e permessi, compresso a sole icone con sottomenu a comparsa (`Ctrl+B`, stato ricordato per utente,
|
||||
compresso sotto i 1100 px); barra di stato con azienda, esercizio, utente, latenza, cache e versione.
|
||||
- Schede tenute in vita: ogni pagina aperta resta com'era passando da una scheda all'altra, pallino delle modifiche,
|
||||
conferma alla chiusura, massimo 12 schede (si chiude la meno usata senza modifiche) (ADR 0020).
|
||||
- Scorciatoie da tastiera in un'unica tabella, con le varianti `Alt+W`, `Alt+PagGiù`/`Alt+PagSu`, `Alt+N` per le
|
||||
combinazioni che i browser tengono per sé; ricerca rapida `Ctrl+K` di pagine e comandi; `F1` apre la pagina wiki
|
||||
della maschera.
|
||||
- Testi dell'interfaccia in `Resources/it-IT/*.json` letti da `ITexts`, formati italiani per importi e date; test che
|
||||
vietano i testi letterali nei componenti e controllano che ogni chiave esista.
|
||||
- *Il mio profilo*: aspetto (tema automatico, chiaro, scuro, alto contrasto; otto accenti; densità; dimensione del
|
||||
testo; menu; numeri tabellari, animazioni ridotte, suggerimenti, evidenza della riga) con anteprima dal vivo,
|
||||
pagina iniziale, sessioni attive con chiusura, elenco delle scorciatoie.
|
||||
- Preferenze salvate per utente in `sys_user_settings` (account di istanza) e `user_settings` (utenti aziendali); il
|
||||
tema è già nella pagina inviata dal server.
|
||||
- Aiuto in app (mockup 011): `F1` e `?` aprono in una scheda la pagina wiki della maschera dalla copia della wiki
|
||||
contenuta nell'immagine (`/aiuto`, funziona senza Internet), con indice, *Apri nel wiki* e *Segnala un problema*;
|
||||
Markdown convertito in casa; nuova variabile facoltativa `KHAEMHAT_HELP_URL` per la wiki online (ADR 0023).
|
||||
- Pannello notifiche (mockup 010): filtri *Tutte* e *Non lette*, segna come letta, *Segna tutte come lette*,
|
||||
conteggio aggiornato ogni minuto; le notifiche per tutti si segnano lette per ciascun utente (tabelle
|
||||
`sys_notification_reads` e `notification_reads`).
|
||||
- Ricerca globale a fornitori (`GlobalSearchService`, `ISearchProvider`): oltre a pagine e comandi trova le pagine e
|
||||
le sezioni dell'aiuto; prefissi `#` documenti e `@` persone pronti per i moduli successivi.
|
||||
- Allegati nell'interfaccia (mockup 024): `KhAttachmentList` con caricamento, anteprima, download, blocco, cestino
|
||||
con ripristino, versioni precedenti, *Scarica tutto (ZIP)* e *Genera file* / *Rigenera*; anteprima di PDF e
|
||||
immagini nel browser, di XML e testo come testo, di CSV e XLSX come griglia (lettore XLSX scritto in casa).
|
||||
- Anteprima di stampa (mockup 025): `KhPrintPreview` con foglio A4 in HTML e CSS, *Stampa* del solo foglio, PDF da
|
||||
aprire o scaricare e *Salva come allegato*; prova sul documento di sviluppo con `Ctrl+P`.
|
||||
- Storico di un record: `AuditTrailService` legge il registro delle modifiche e `KhAuditList` mostra chi ha cambiato
|
||||
cosa, con i valori prima e dopo.
|
||||
- Indirizzi `/files/{id}`, `/files/zip` e `/files/generate` per scaricare gli allegati, tutti gli allegati di un
|
||||
record e un file generato al volo; solo PDF e immagini si aprono nel browser, con una politica di sicurezza propria
|
||||
che permette l'anteprima dentro Khaemhat.
|
||||
- Con la dashboard spenta, Home con licenza, moduli, azienda e aree disponibili; le aree delle prossime versioni
|
||||
aprono una pagina che dice con quale milestone arrivano.
|
||||
- Dashboard a widget (mockup 004-006, ADR 0022): Da fare oggi, Fatto oggi, Scadenze 30 giorni, Promemoria personali,
|
||||
Scorciatoie e Stato del sistema con dati veri; i widget dei moduli futuri si possono già accendere e dicono da quale
|
||||
versione arrivano i dati. Pannello *Personalizza* con pagina iniziale, interruttore della dashboard, widget da
|
||||
accendere, ordinare e dimensionare, trascinamento sulla griglia e pulsanti equivalenti da tastiera, *Ripristina* e
|
||||
layout predefinito per ruolo. Le liste raccolgono le righe da sorgenti che ogni modulo registra.
|
||||
- Impostazioni dell'azienda nella tabella `company_settings`, scritte con il permesso `company.settings.write`.
|
||||
- Token, temi e classi dei mockup in `css/tokens.css` e `css/components.css`, sprite di icone proprie, stampa sempre
|
||||
in chiaro.
|
||||
|
||||
### Changed
|
||||
- `Esc` chiude anche un pannello laterale aperto quando il focus non è in un campo.
|
||||
- Su telefono la barra superiore mostra solo le icone e la barra di stato solo connessione, cache e versione.
|
||||
|
||||
### Fixed
|
||||
- L'etichetta *Totale documento* dell'intestazione era tagliata: prendeva lo stile della timeline (`.tl`).
|
||||
- Le schede dei temi e dei colori nel profilo andavano in colonna: la classe `.kh-choices` del radar le
|
||||
ridefiniva; il gruppo di scelte del radar ora si chiama `.kh-radio-set`.
|
||||
- Pagine di accesso, errori e riconnessione con i testi localizzati e i colori del tema.
|
||||
|
||||
## [0.2.0] - 2026-11-11
|
||||
|
||||
M2 — Sistema e sicurezza. L'istanza si avvia da sola, crea super utente e prima azienda, e si entra con password e
|
||||
verifica in due passaggi.
|
||||
|
||||
### Added
|
||||
- Avvio guidato dalle variabili `KHAEMHAT_*` (anche `_FILE`): tutte le variabili sbagliate elencate insieme e uscita
|
||||
con codice 2; migrazioni del sistema e delle aziende all'avvio, super utente e prima azienda al primo avvio,
|
||||
pagina "Avvio in corso" e `/health/ready` a 503 finché non è pronto (ADR 0019).
|
||||
- Account di istanza (super utente, amministratori) e utenti aziendali, password PBKDF2-SHA256 con storico, blocco
|
||||
dopo 5 errori, limite di 10 accessi al minuto per indirizzo IP.
|
||||
- Pagine di accesso (mockup 001-003): scelta dell'azienda, cambio password obbligatorio, attivazione e verifica in
|
||||
due passaggi (TOTP, RFC 6238) con 10 codici di recupero; uscita con `POST /logout`.
|
||||
- Sessioni nel database con token salvato come hash, rigenerato a ogni passo, revocabili, riverificate dal circuito
|
||||
Blazor ogni minuto; audit di sicurezza in `sys_security_audit` con catena di hash.
|
||||
- Ruoli predefiniti, permessi `modulo.area.azione` con override per utente, attributi `[RequirePermission]`,
|
||||
`[RequireLevel]`, `[RequireModule]`.
|
||||
- Licenze: trial di 60 giorni, file `.khl` firmati ECDSA P-256, codici di attivazione dei moduli, modalità test con
|
||||
i codici fittizi, limite di aziende e di utenti contemporanei; strumento `tools/Khaemhat.LicenseTool`.
|
||||
- Chiavi DataProtection nel database di sistema, cifrate con la chiave di istanza.
|
||||
- Cache in memoria o su Redis (client RESP scritto in casa, `KHAEMHAT_REDIS`), con ritorno alla memoria se Redis non
|
||||
risponde.
|
||||
- Log su database (`sys_log`) per sezioni, con identificativo di traccia (`X-Trace-Id`), utente e azienda; query
|
||||
lente nella sezione *Prestazioni*; esito delle migrazioni nella sezione *Migrazioni*.
|
||||
- Attività programmate: cron a 5 campi con fuso orario, lock, timeout, tentativi, storico; job di sistema per pulizia
|
||||
sessioni, controllo licenza e retention del log.
|
||||
- Storico dei record (`audit_log` aziendale) con i soli campi cambiati.
|
||||
- Aziende: creazione e collegamento, stati attiva / manutenzione / sola lettura / disattivata, contesto azienda per
|
||||
pagine e API (`X-Company`), risposta 503 per le aziende in manutenzione.
|
||||
- Header di sicurezza su tutte le risposte (CSP senza script inline, `X-Frame-Options`, `nosniff`,
|
||||
`Referrer-Policy`, `Permissions-Policy`).
|
||||
- Tabelle di sistema e aziendali di M2, documentate in `docs/DATA-MODEL.md` (rigenerato).
|
||||
|
||||
### Changed
|
||||
- La home richiede l'accesso: senza sessione porta a `/login`.
|
||||
- I database SQLite in memoria restano disponibili per tutta la vita del processo.
|
||||
|
||||
## [0.1.0] - 2026-11-11
|
||||
|
||||
M1 — Strato dati. Nessuna funzione visibile nell'interfaccia: è il motore su cui si appoggiano tutte le milestone
|
||||
|
||||
@@ -88,6 +88,11 @@ fermandosi solo per blocchi reali (SDK mancante, credenziali, PNG o dati che sol
|
||||
inglese che dicono *cosa cambia e perché*. Il push su Gitea e le pull request seguono le indicazioni dell'utente;
|
||||
il tag `vX.Y.Z` si crea alla chiusura di ogni milestone (§20).
|
||||
|
||||
**E7 — Versioni 0.x fino al via dell'utente** (sostituisce la colonna versione di §20 per M13 e M14; deciso
|
||||
dall'utente il 2026-11-12). Finché il prodotto è in sviluppo le versioni restano **0.x**: ogni milestone chiude con
|
||||
`v0.<n>.0` (M13 `v0.13.0`, M14 `v0.14.0` e seguenti). La **1.0.0 non si crea** (tag, immagine, release, CHANGELOG)
|
||||
finché l'utente non lo dice esplicitamente. L'icona versionata `icon-v1.0` resta il modello grafico.
|
||||
|
||||
## 4. Vincoli non negoziabili (sintesi di SPEC §1 — leggere l'originale)
|
||||
|
||||
1. C# 14 su .NET 10; JavaScript solo come interop minimo in `wwwroot/js`, senza framework né bundler.
|
||||
|
||||
@@ -43,6 +43,8 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Khaemhat.LicenseTool", "too
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Khaemhat.DataModelTool", "tools\Khaemhat.DataModelTool\Khaemhat.DataModelTool.csproj", "{7CA26565-5E1A-46AA-A2F7-C38FBADF0E3F}"
|
||||
EndProject
|
||||
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Khaemhat.PlacesTool", "tools\Khaemhat.PlacesTool\Khaemhat.PlacesTool.csproj", "{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}"
|
||||
EndProject
|
||||
Global
|
||||
GlobalSection(SolutionConfigurationPlatforms) = preSolution
|
||||
Debug|Any CPU = Debug|Any CPU
|
||||
@@ -257,6 +259,18 @@ Global
|
||||
{7CA26565-5E1A-46AA-A2F7-C38FBADF0E3F}.Release|x64.Build.0 = Release|Any CPU
|
||||
{7CA26565-5E1A-46AA-A2F7-C38FBADF0E3F}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{7CA26565-5E1A-46AA-A2F7-C38FBADF0E3F}.Release|x86.Build.0 = Release|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Debug|Any CPU.Build.0 = Debug|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Debug|x64.ActiveCfg = Debug|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Debug|x64.Build.0 = Debug|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Debug|x86.ActiveCfg = Debug|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Debug|x86.Build.0 = Debug|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Release|Any CPU.ActiveCfg = Release|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Release|Any CPU.Build.0 = Release|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Release|x64.ActiveCfg = Release|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Release|x64.Build.0 = Release|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Release|x86.ActiveCfg = Release|Any CPU
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E}.Release|x86.Build.0 = Release|Any CPU
|
||||
EndGlobalSection
|
||||
GlobalSection(SolutionProperties) = preSolution
|
||||
HideSolutionNode = FALSE
|
||||
@@ -279,5 +293,6 @@ Global
|
||||
{FDCAC352-BB40-4B5E-948A-2CDAA48B9E6A} = {0AB3BF05-4346-4AA6-1389-037BE0695223}
|
||||
{4317FFD0-9473-43FD-8543-F80EF9BA812A} = {07C2787E-EAC7-C090-1BA3-A61EC2A24D84}
|
||||
{7CA26565-5E1A-46AA-A2F7-C38FBADF0E3F} = {07C2787E-EAC7-C090-1BA3-A61EC2A24D84}
|
||||
{04C6CC82-F19E-437A-BDFE-7A6F66E29D2E} = {07C2787E-EAC7-C090-1BA3-A61EC2A24D84}
|
||||
EndGlobalSection
|
||||
EndGlobal
|
||||
@@ -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).
|
||||
@@ -32,6 +32,7 @@
|
||||
<Config Name="KHAEMHAT_LICENSE_MODE" Target="KHAEMHAT_LICENSE_MODE" Default="production" Mode="" Description="production oppure test (abilita i codici di licenza fittizi)" Type="Variable" Display="advanced" Required="false" Mask="false">production</Config>
|
||||
<Config Name="KHAEMHAT_LICENSE" Target="KHAEMHAT_LICENSE" Default="" Mode="" Description="Licenza firmata (.khl, testo). Vuoto = Trial" Type="Variable" Display="advanced" Required="false" Mask="true"></Config>
|
||||
<Config Name="KHAEMHAT_SEED_DEMO" Target="KHAEMHAT_SEED_DEMO" Default="false" Mode="" Description="true = dati dimostrativi al primo avvio (solo database vuoto)" Type="Variable" Display="advanced" Required="false" Mask="false">false</Config>
|
||||
<Config Name="KHAEMHAT_HELP_URL" Target="KHAEMHAT_HELP_URL" Default="" Mode="" Description="Opzionale: wiki online aperta da Apri nel wiki (predefinita https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/)" Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
|
||||
<Config Name="KHAEMHAT_UPDATE_FEED" Target="KHAEMHAT_UPDATE_FEED" Default="" Mode="" Description="Opzionale: URL API pacchetti Gitea per il controllo aggiornamenti (https://gitea.encke-hake.ts.net/api/v1/packages/BalboSoft?type=container&q=khaemhat)" Type="Variable" Display="advanced" Required="false" Mask="false"></Config>
|
||||
<Config Name="TZ" Target="TZ" Default="Europe/Rome" Mode="" Description="Fuso orario" Type="Variable" Display="advanced" Required="false" Mask="false">Europe/Rome</Config>
|
||||
<Config Name="PUID" Target="PUID" Default="99" Mode="" Description="UID per i file in /data" Type="Variable" Display="advanced" Required="false" Mask="false">99</Config>
|
||||
|
||||
@@ -65,8 +65,8 @@ ENV ASPNETCORE_ENVIRONMENT=Production \
|
||||
WORKDIR /app
|
||||
COPY --from=build /app ./
|
||||
COPY docker/entrypoint.sh /app/entrypoint.sh
|
||||
COPY scripts/restore-system.sh /app/scripts/restore-system.sh
|
||||
RUN chmod 0755 /app/entrypoint.sh /app/scripts/restore-system.sh \
|
||||
COPY scripts/restore-system.sh scripts/seed.sh /app/scripts/
|
||||
RUN chmod 0755 /app/entrypoint.sh /app/scripts/restore-system.sh /app/scripts/seed.sh \
|
||||
&& install -d -o app -g app -m 0750 /data
|
||||
|
||||
LABEL org.opencontainers.image.title="Khaemhat" \
|
||||
|
||||
@@ -75,6 +75,7 @@ client degli aggiornamenti è `GiteaPackagesClient`.
|
||||
| `Khaemhat.Web` | host ASP.NET Core 10, Blazor Interactive Server, Minimal API, MCP, autenticazione | M0 → M13 |
|
||||
| `tools/Khaemhat.LicenseTool` | CLI per chiavi ed emissione licenze (chiave privata mai nel repository; non distribuito) | M2 |
|
||||
| `tools/Khaemhat.DataModelTool` | rigenera la sezione generata di `docs/DATA-MODEL.md` dalle migrazioni (non distribuito, ADR 0018) | M1 |
|
||||
| `tools/Khaemhat.PlacesTool` | rigenera province e comuni del pacchetto italiano dall'elenco ISTAT e dai CAP GeoNames (non distribuito, ADR 0028) | M4 |
|
||||
| `tests/*` | `Core`, `Data`, `Infrastructure`, `Fiscal.Italy`, `Application`, `Web` (MSTest) | ogni milestone |
|
||||
|
||||
## 3. Regole di dipendenza
|
||||
@@ -380,7 +381,7 @@ Khaemhat/
|
||||
│ └── Khaemhat.Web/ Program.cs Configuration/ Auth/ Api/ Mcp/ Help/ Components/
|
||||
│ (App, Routes, Layout/, Ui/, Pages/<Modulo>/, Shared/) Localization/ wwwroot/
|
||||
├── tests/ Core, Data, Infrastructure, Fiscal.Italy, Application, Web
|
||||
├── tools/Khaemhat.LicenseTool/
|
||||
├── tools/ Khaemhat.LicenseTool, Khaemhat.DataModelTool, Khaemhat.PlacesTool
|
||||
└── docs/
|
||||
├── SPEC.md ARCHITECTURE.md DATA-MODEL.md MODULES.md API.md MCP.md
|
||||
├── DEPLOY.md DEVELOPMENT.md SECURITY.md STATUS.md
|
||||
|
||||
@@ -219,7 +219,8 @@ Regole (SPEC §16.6, E1):
|
||||
VERSION` (`/p:Version`) insieme a `GIT_SHA` (`/p:SourceRevisionId`, mostrato come `+sha`).
|
||||
- Dove compare (SPEC §16.5): barra superiore (`major.minor`), barra di stato (completa), *Stato sistema*,
|
||||
`manifest.webmanifest`, etichette OCI, icona versionata.
|
||||
- Milestone: `v0.0.1` (M0) … `v0.12.0` (M12), `v1.0.0` (M13), `v1.1.0`+ (M14) — SPEC §20.
|
||||
- Milestone: `v0.0.1` (M0) … `v0.12.0` (M12), `v0.13.0` (M13), `v0.14.0`+ (M14). La `1.0.0` si crea solo quando
|
||||
l'utente lo decide (emendamento E7 in `CLAUDE.md`, che modifica SPEC §20).
|
||||
- Le migrazioni non si riscrivono mai dopo un rilascio: una correzione è una migrazione nuova.
|
||||
|
||||
## 8. Endpoint di salute
|
||||
|
||||
@@ -34,8 +34,10 @@ Se manca l'SDK 10 ci si ferma e lo si chiede al titolare (SPEC §23). Su Windows
|
||||
| `scripts/gen-datamodel.sh [--check]` | rigenera la sezione generata di `docs/DATA-MODEL.md` dalle migrazioni; `--check` verifica soltanto |
|
||||
| `KHAEMHAT_PERF=1 scripts/test.sh --filter TestCategory=Performance` | misure di riferimento dello strato dati con 100.000 righe (`docs/DATA-MODEL.md` §6.1) |
|
||||
|
||||
Gli stub `seed.sh` (M4) e `restore-system.sh` (M12, incluso nell'immagine, ADR 0017) spiegano l'uso previsto ed
|
||||
escono con errore finché la loro milestone non li completa.
|
||||
`scripts/seed.sh --base [--company CODICE]` aggiunge i dati di base mancanti (ADR 0026) con le variabili `KHAEMHAT_*`
|
||||
già impostate (ad esempio quelle di `run-dev.sh`); è incluso nell'immagine in `/app/scripts/`. `--demo` arriva con
|
||||
anagrafiche e articoli. Lo stub `restore-system.sh` (M12, incluso nell'immagine, ADR 0017) spiega l'uso previsto ed
|
||||
esce con errore finché la sua milestone non lo completa.
|
||||
|
||||
#### Test sui due motori
|
||||
|
||||
|
||||
@@ -136,8 +136,8 @@ programmata passa da un controllo esplicito.
|
||||
|
||||
| Aspetto | Regola |
|
||||
|---|---|
|
||||
| Autenticazione | cookie ASP.NET Core con `CookieSessionAuthenticationHandler`; nessun ASP.NET Identity/EF |
|
||||
| Attributi del cookie | `HttpOnly; Secure; SameSite=Lax` |
|
||||
| Autenticazione | schema `KhaemhatSession` scritto in casa (`SessionAuthenticationHandler`, ADR 0019); nessun ASP.NET Identity/EF |
|
||||
| Attributi del cookie | `khaemhat_session`, `HttpOnly; SameSite=Lax`; `Secure` quando la richiesta è HTTPS o `KHAEMHAT_PUBLIC_URL` è `https` |
|
||||
| Identificatore | 256 bit casuali da `SecureTokenGenerator` (`RandomNumberGenerator`) |
|
||||
| Stato | riga di sessione in `sys_sessions` (account di istanza) o `user_sessions` (utenti aziendali): dispositivo, IP, creazione, ultimo uso, revoca |
|
||||
| Scadenza | scorrevole, con timeout di inattività da impostazioni (mockup 086: 480 minuti) |
|
||||
@@ -148,9 +148,12 @@ programmata passa da un controllo esplicito.
|
||||
| Antiforgery | sui form statici (login, cambio password, recupero) |
|
||||
| Cookie ammessi | sessione e tema prima del login (SPEC §1.5); nessun cookie di profilazione |
|
||||
|
||||
Proposta: nella riga di sessione salvare l'**hash SHA-256** dell'identificatore, non il valore, così una lettura del
|
||||
database non consente di impersonare le sessioni attive. Rigenerare l'identificatore dopo il login e dopo il
|
||||
passaggio TOTP (prevenzione della session fixation).
|
||||
**Implementato in M2.** La riga di sessione contiene solo l'**hash SHA-256** dell'identificatore: una lettura del
|
||||
database non consente di impersonare le sessioni attive. L'identificatore viene **rigenerato a ogni passaggio di
|
||||
stato** (password verificata, TOTP verificato, password cambiata), contro la session fixation. Una sessione che non è
|
||||
ancora *attiva* (manca il TOTP o il cambio password) apre solo le pagine del suo passo. Il circuito Blazor ricontrolla
|
||||
la sessione ogni minuto e si chiude se è stata revocata; mettere un'azienda in manutenzione o disattivarla revoca le
|
||||
sessioni dei suoi utenti.
|
||||
|
||||
---
|
||||
|
||||
@@ -253,8 +256,8 @@ passaggio TOTP (prevenzione della session fixation).
|
||||
interfaccia `ISecretProtector` in `Khaemhat.Core`.
|
||||
- La chiave e i segreti in chiaro **non vanno mai** in log, messaggi d'errore, diagnostica, risposte API o file su
|
||||
disco (SPEC §1.5: nessun `appsettings.<Env>.json` con segreti, nessun file temporaneo).
|
||||
- Le varianti `_FILE` delle variabili (Docker secrets) sono previste per `KHAEMHAT_SYSTEM_DB` e le credenziali del
|
||||
super utente; proposta: estenderle a `KHAEMHAT_SECRET_KEY` e alle altre variabili sensibili.
|
||||
- Le varianti `_FILE` (Docker secrets) valgono per tutte le variabili sensibili, `KHAEMHAT_SECRET_KEY` compresa
|
||||
(ADR 0014); impostare sia la variabile sia la sua `_FILE` è un errore di avvio.
|
||||
|
||||
### 7.2 Rotazione (`SecretRotationService`, `SecretRotation`)
|
||||
|
||||
@@ -275,8 +278,9 @@ della vecchia chiave come chiave di sola decifratura identificata dalla versione
|
||||
- Le chiavi DataProtection di ASP.NET Core (cookie, antiforgery) sono nel **database di sistema**
|
||||
(`sys_data_protection_keys`) tramite `DataProtectionDbXmlRepository`: nessun file su disco, cookie validi dopo un
|
||||
riavvio o un nuovo container.
|
||||
- Proposta: cifrare l'XML delle chiavi a riposo con un `IXmlEncryptor` basato su `SecretProtector`, così la sola
|
||||
lettura del database di sistema non consente di falsificare cookie.
|
||||
- **Implementato in M2** (`DataProtectionKeyStore`, `SecretKeyXmlEncryptor`): l'XML delle chiavi è cifrato a riposo
|
||||
con `SecretProtector` (scopo `dataprotection:keys`), così la sola lettura del database di sistema non consente di
|
||||
falsificare cookie o token antiforgery. Il database di sistema è migrato prima che DataProtection legga le chiavi.
|
||||
|
||||
---
|
||||
|
||||
@@ -286,14 +290,18 @@ della vecchia chiave come chiave di sola decifratura identificata dalla versione
|
||||
|
||||
| Header | Valore |
|
||||
|---|---|
|
||||
| `Content-Security-Policy` | `default-src 'self'`; script solo `'self'` + **nonce** per gli script di Blazor; `connect-src 'self'` (WebSocket del circuito sullo stesso host); `frame-ancestors 'none'`; `object-src 'none'`; `base-uri 'self'` (dettaglio proposto) |
|
||||
| `Content-Security-Policy` | `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; object-src 'none'` |
|
||||
| `X-Frame-Options` | `DENY` |
|
||||
| `Referrer-Policy` | proposta: `strict-origin-when-cross-origin` (o `no-referrer`) |
|
||||
| `X-Content-Type-Options` | proposta: `nosniff` |
|
||||
| `Referrer-Policy` | `same-origin` |
|
||||
| `X-Content-Type-Options` | `nosniff` |
|
||||
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
|
||||
| `Cross-Origin-Opener-Policy` | `same-origin` |
|
||||
| `Strict-Transport-Security` | impostato dal **reverse proxy**, che termina TLS |
|
||||
|
||||
- Nessuna risorsa da CDN, nessun font scaricato, nessuno script di terze parti (SPEC §1.2): la CSP può restare
|
||||
rigorosa. JavaScript solo in `wwwroot/js`, senza `eval` né gestori inline.
|
||||
rigorosa. In M2 non serve nemmeno il nonce: nessuna pagina ha script inline (la `<ImportMap />` di Blazor, che
|
||||
ne scriverebbe uno, non è usata). `style-src 'unsafe-inline'` resta perché Blazor applica stili agli elementi
|
||||
durante la riconnessione. JavaScript solo in `wwwroot/js`, senza `eval` né gestori inline.
|
||||
- L'impostazione *CSP rigorosa (nonce)* (mockup 086) esiste per la diagnosi; disattivarla è un evento di audit.
|
||||
- Blazor esegue l'escaping dell'output: vietato `MarkupString` su contenuti provenienti da utenti o da file
|
||||
(eccezione: l'anteprima XML formattata, che va resa come testo).
|
||||
|
||||
@@ -2,16 +2,19 @@
|
||||
|
||||
> Punto di ripresa per ogni sessione. Aggiornare a fine sessione.
|
||||
|
||||
**Ultimo aggiornamento:** 2026-11-11
|
||||
**Milestone corrente:** M1 — Strato dati (in chiusura sul ramo `feat/7-strato-dati`)
|
||||
**Prossimo passo:** chiudere M1 (PR verso `main`, CI verde compreso il job `postgres` avviato a mano sul ramo, tag
|
||||
`v0.1.0`, immagine e release; misure PostgreSQL in `docs/DATA-MODEL.md` §6.1), poi M2 — Sistema e sicurezza,
|
||||
partendo dall'issue #15.
|
||||
**Ultimo aggiornamento:** 2026-11-12
|
||||
**Milestone corrente:** M6 — Acquisti e Magazzino (issue #55-#61), **non ancora iniziata**: si parte quando il
|
||||
titolare lo dice. M5 chiusa: PR #124 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-E6.
|
||||
- ADR 0001-0018.
|
||||
- Specifica normativa in `docs/SPEC.md`; `CLAUDE.md` con emendamenti E1-E7.
|
||||
- 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`,
|
||||
@@ -23,12 +26,46 @@ partendo dall'issue #15.
|
||||
`/health/live`, `/health/ready`, `/health` (ADR 0012); `docker/Dockerfile`, `entrypoint.sh` con `PUID`/`PGID`
|
||||
(ADR 0013), `postgres/init.sql`; `deploy/docker-compose.yml` e `docker-compose.sqlite.yml`; Gitea Actions `ci.yml`,
|
||||
`release.yml`, `wiki.yml` con controllo YAML; script di build, test, avvio, pubblicazione e stub; ADR 0012-0017.
|
||||
- **M1 (in chiusura, `v0.1.0`):** micro-ORM in `Khaemhat.Data` (mappe, query tipizzate, `SqlFragment`, unit of work,
|
||||
- **M1 (chiusa, `v0.1.0`, PR #116):** micro-ORM in `Khaemhat.Data` (mappe, query tipizzate, `SqlFragment`, unit of work,
|
||||
repository con audit e `row_version`), provider SQLite e PostgreSQL, `DatabaseUrl`, migrazioni con
|
||||
`schema_version`, tabelle `sys_companies` e `sys_settings`, `CompanyRegistry` con URL cifrato, `SecretProtector`
|
||||
(AES-256-GCM, formato `khs1`), `tools/Khaemhat.DataModelTool` e gli script `new-migration.sh` e
|
||||
`gen-datamodel.sh`; ADR 0018. Test: 85 su SQLite verdi in locale, 21 su PostgreSQL eseguiti solo in CI (in locale
|
||||
Docker non è disponibile).
|
||||
`gen-datamodel.sh`; ADR 0018. Test: 106 test dello strato dati verdi su SQLite in locale e su PostgreSQL 16 e 17 in CI
|
||||
(in locale Docker non è disponibile).
|
||||
- **M2 (chiusa, `v0.2.0`, PR #118):** avvio da variabili con elenco degli errori, migrazioni all'avvio, super utente e
|
||||
prima azienda; account di istanza e aziendali, password con storico e blocco, sessioni nel database, TOTP con codici
|
||||
di recupero, pagine di accesso (mockup 001-003); ruoli, permessi e attributi di autorizzazione; licenze firmate,
|
||||
codici di attivazione, modalità test, `tools/Khaemhat.LicenseTool`; DataProtection nel database cifrata; cache
|
||||
memoria/Redis (client RESP in casa); log su database per sezioni con traccia; attività programmate con cron, lock e
|
||||
job di sistema; storico dei record; aziende con stati e contesto (`X-Company`); header di sicurezza; ADR 0019.
|
||||
Test: 180 verdi in locale, più 21 di PostgreSQL saltati senza Docker (girano in CI). La chiave privata delle licenze è fuori dal
|
||||
repository (`Khaemhat-private/khaemhat-license.khkey`) e va conservata dal titolare.
|
||||
- **M3 (chiusa, `v0.3.0`, PR #119):** shell con barra superiore, menu comprimibile con sottomenu a comparsa,
|
||||
schede tenute in vita, barra di stato, scorciatoie con varianti `Alt`; testi in `Resources/it-IT/*.json` con test
|
||||
anti-testo-letterale; preferenze utente e *Il mio profilo* (aspetto, pagina iniziale, dati personali, password e
|
||||
2FA, sessioni, scorciatoie); libreria `Kh*` con campi all'italiana, toolbar a icone, intestazione documento e basi
|
||||
`RecordPage`/`DocumentPage`/`MasterDataPage`; liste con `ListQuery`/`ListFields`, `KhGrid` virtualizzata, `KhRadar`
|
||||
e `KhLinesGrid`; dashboard a widget con layout per utente e per ruolo e `company_settings`; ricerca globale a
|
||||
fornitori, aiuto in app dalla copia della wiki, pannello notifiche; allegati con anteprime, *Genera file*, ZIP,
|
||||
cestino e storico; anteprima di stampa A4; catalogo dei componenti e documento di prova per gli sviluppatori;
|
||||
primi screenshot reali in `docs/wiki/img/`; ADR 0020-0024. Test: 368 verdi in locale, 21 di PostgreSQL saltati;
|
||||
immagine costruita in locale e avviata da zero con SQLite.
|
||||
- **M4 (chiusa, `v0.4.0`, PR #121):** pacchetto fiscale `IT 2026.3` (codici IVA, nature, code list FatturaPA, motore IVA,
|
||||
calendario, ritenute, F24; ADR 0025); validatori e `ViesClient`; 26 tabelle azienda con un'unica maschera, profilo
|
||||
azienda, esercizi e cambi BCE (ADR 0026); dati di base con province e comuni ISTAT e CAP GeoNames (ADR 0028) e
|
||||
`scripts/seed.sh --base|--demo`; codici automatici e compilazione automatica (ADR 0027); clienti, fornitori e
|
||||
contatti con radar, scheda, controlli e VIES (ADR 0029); articoli e listini con prezzi a validità, listini derivati e
|
||||
aggiornamento massivo (ADR 0030); import/export guidato CSV/XLSX/JSON con tracciato del piano dei conti (ADR 0031);
|
||||
21 anagrafiche e 120 articoli di esempio; screenshot reali nella wiki. Test: 631 verdi in locale, 21 di PostgreSQL
|
||||
saltati; immagine costruita in locale e avviata da zero con SQLite e dati di esempio.
|
||||
- **M5 (chiusa, `v0.5.0`, PR #124):** motore documenti (#47, ADR 0032): generi e definizioni dei tipi documento, sei famiglie
|
||||
di tabelle con le righe e `document_links`, stati con azioni ammesse, numerazione atomica alla conferma (provata in
|
||||
concorrenza su SQLite e su PostgreSQL 18 in locale), copia e trasformazione con evasione riga per riga; totali,
|
||||
castelletto IVA, bollo, ritenute, cassa e scadenze (#48, ADR 0033); radar e maschera dei documenti di vendita con
|
||||
*Crea …* (#49, #50); fatturazione differita guidata (#51); anteprima di stampa e PDF dallo stesso modello, invio per
|
||||
e-mail con SMTP e coda scritti in casa (#52, ADR 0034); log *Documenti*; profilo e un anno di vendite di esempio;
|
||||
wiki con la *Guida all'uso* e le schermate reali, README come guida per sviluppatori (#53). Test: 660 verdi in
|
||||
locale, 23 di PostgreSQL saltati (girano in CI).
|
||||
- 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,54 @@
|
||||
# ADR 0019 - Sistema e sicurezza: scelte di M2
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §5.4, §6, §7, §8, §9.3, §9.5, §9.6; milestone M2, issue #15-#24
|
||||
|
||||
## Contesto
|
||||
|
||||
M2 costruisce avvio, account, accesso, licenze, cache, log, attività programmate e contesto azienda. La specifica
|
||||
indica il risultato ma lascia aperti alcuni dettagli, o li descrive con componenti che non si possono usare senza
|
||||
librerie esterne (SPEC §1.2). Questo ADR fissa le scelte fatte.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Autenticazione con uno schema proprio.** Lo schema `KhaemhatSession` (`SessionAuthenticationHandler`) legge il
|
||||
cookie `khaemhat_session` = `<database>.<token>`: `_` per gli account di istanza (`sys_sessions`), il codice
|
||||
azienda per gli utenti aziendali (`user_sessions`). Nel database c'è solo l'hash SHA-256 del token. Non si usa il
|
||||
cookie di autenticazione di ASP.NET Core: la sessione deve essere revocabile e contata per la licenza, e il suo
|
||||
stato vive nel database, non nel cookie.
|
||||
2. **Accesso in passi.** Una sessione nasce in uno stato (`PendingPasswordChange`, `PendingTotpSetup`,
|
||||
`PendingTotp`, `Active`) e solo `Active` autentica le pagine. Ogni passaggio di stato rigenera il token. Le pagine
|
||||
di accesso sono SSR statiche con `EditForm` (antiforgery incluso), escluse dal routing interattivo.
|
||||
3. **Attivazione TOTP senza QR.** La pagina mostra la chiave in base32 a gruppi di quattro e il collegamento
|
||||
`otpauth://`; un codice QR richiederebbe una libreria o un generatore scritto in casa che non vale il costo. Dopo
|
||||
la conferma si mostrano 10 codici di recupero monouso (salvati come hash).
|
||||
4. **Avvio in due tempi.** `BootstrapService.StartAsync` migra il database di sistema **prima** che parta il server
|
||||
(DataProtection legge le chiavi da lì); il resto (licenza, super utente, prima azienda, migrazioni delle aziende)
|
||||
gira in background mentre `/health/ready` risponde 503 e le pagine mostrano "Avvio in corso". Un errore di
|
||||
configurazione ferma il processo con codice 2 ed elenca tutte le variabili sbagliate; un errore di avvio con
|
||||
codice 1. Un'azienda che non si migra va in manutenzione senza fermare le altre.
|
||||
5. **Chiavi DataProtection** in `sys_data_protection_keys`, cifrate con `SecretProtector`.
|
||||
6. **Log su database** con un `ILoggerProvider` scritto in casa: coda limitata (20 000 eventi, si scartano i più
|
||||
vecchi), scrittura a blocchi di 200 ogni secondo, sezione ricavata dalla categoria o dallo scope `Section`,
|
||||
`TraceId`, utente e azienda dallo scope della richiesta. Gli eventi di `Microsoft.*` e `System.*` sotto
|
||||
`Warning` non vanno nel database. Retention per livello con un job notturno.
|
||||
7. **Redis** con un client RESP2 scritto in casa (una connessione, un comando alla volta, `AUTH`, `SELECT`, TLS
|
||||
con `rediss://`). Se Redis non risponde la cache passa alla memoria e lo scrive nel log una volta al minuto:
|
||||
la cache non fa mai fallire una richiesta.
|
||||
8. **Attività programmate**: cron a 5 campi con fuso orario (le ore che non esistono al cambio dell'ora legale si
|
||||
saltano), lock per attività in `sys_job_locks` con scadenza pari al timeout (un lock scaduto si riprende), una
|
||||
riga di `sys_job_runs` per tentativo, notifica agli account di istanza quando l'ultimo tentativo fallisce.
|
||||
9. **Contesto azienda**: gli utenti aziendali lavorano solo nella propria azienda; gli account di istanza la
|
||||
scelgono (sessione, o header `X-Company` per le API). Un'azienda in manutenzione è chiusa agli utenti aziendali,
|
||||
una disattivata a tutti: pagine con avviso 503, API con 503 e `Retry-After`; un `X-Company` di un'altra azienda
|
||||
dà 403.
|
||||
10. **Database SQLite in memoria** (test e demo): il provider tiene aperta una connessione per ogni database in
|
||||
memoria creato con `EnsureDatabaseExistsAsync`, che altrimenti sparirebbe con l'ultima connessione.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Nessuna dipendenza nuova; tutto è coperto da test (vettori RFC 6238, RESP, cron con ora legale, flusso di accesso
|
||||
sull'host reale, isolamento di due aziende).
|
||||
- Le schermate di amministrazione (utenti, ruoli, licenze, log, attività) arrivano in M12 sopra questi servizi.
|
||||
- La pagina di cambio password è più semplice del mockup 003 (niente indicatore di robustezza) fino a M3.
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0020 - Shell dell'interfaccia: schede, testi, preferenze, scorciatoie
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §1.9, §10.2, §10.5, §10.6, §10.8, §11.12; milestone M3, issue #25, #26, #31, #33
|
||||
|
||||
## Contesto
|
||||
|
||||
M3 costruisce la shell (barra superiore, menu comprimibile, schede, barra di stato), i testi localizzati e le
|
||||
preferenze utente. La specifica fissa il risultato visivo (mockup 004, 007, 008, 013) ma lascia aperti alcuni punti
|
||||
tecnici; altri si scontrano con il browser o con Blazor. Questo ADR fissa le scelte.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Schede tenute in vita.** Ogni indirizzo aperto diventa una scheda (`TabService`, massimo 12). La scheda conserva
|
||||
il **tipo di pagina e una copia dei parametri di rotta** (`RouteData` passato in cascata da `Routes.razor`), non il
|
||||
`Body` del layout: `Body` disegna sempre la pagina corrente, quindi tutte le schede avrebbero mostrato l'ultima.
|
||||
Il layout disegna un pannello per scheda e nasconde quelli inattivi (`hidden`), così passando da una scheda
|
||||
all'altra lo stato della pagina resta. La stessa pagina con un'altra query (`/profilo?scheda=sessioni`) riusa la
|
||||
scheda. Alla tredicesima si chiude la scheda meno usata **senza modifiche**; se tutte hanno modifiche l'apertura
|
||||
è rifiutata con un avviso. Il titolo del browser lo scrive il layout dalla scheda attiva; `KhPageTitle` imposta
|
||||
solo il titolo della scheda.
|
||||
2. **Scorciatoie riservate dal browser.** `Ctrl+W`, `Ctrl+Tab` e `Ctrl+N` restano dei browser, che non le passano alla
|
||||
pagina. Si tengono come da specifica e si aggiungono `Alt+W`, `Alt+PagGiù` / `Alt+PagSu` e `Alt+N`, che arrivano
|
||||
sempre. Le scorciatoie sono un'unica tabella (`KeyboardShortcuts.All`) usata dal gestore JavaScript, dalla
|
||||
ricerca e dalla scheda *Scorciatoie* del profilo; un test controlla che ogni combinazione sia unica.
|
||||
3. **Testi in JSON incorporati.** I testi stanno in `src/Khaemhat.Web/Resources/<cultura>/*.json`, risorse incorporate
|
||||
lette da `JsonTextProvider` (`ITexts`). Gli oggetti annidati danno chiavi puntate (`Shell.Menu.Parties`), la
|
||||
proprietà `_` dà il testo all'oggetto che ha anche figli, una chiave definita due volte è un errore all'avvio, una
|
||||
chiave mancante si vede come `[chiave]`. Niente `.resx`: il JSON si legge e si confronta meglio nelle revisioni e
|
||||
non richiede generatori. Due test lo fanno rispettare: nessun testo letterale nei componenti `.razor` (testo fra i
|
||||
tag e attributi `title`, `placeholder`, `alt`, `aria-label`, `label`) e ogni chiave usata nel codice esiste.
|
||||
4. **Preferenze per utente nel database del proprietario.** `UserSettingsService` salva coppie chiave/valore in
|
||||
`sys_user_settings` per gli account di istanza e in `user_settings` per gli utenti aziendali (valore massimo 64 KB,
|
||||
chiave massimo 200 caratteri). `UserPreferences` legge e scrive l'insieme tipizzato (tema, accento, densità,
|
||||
dimensione testo, numeri tabellari, animazioni, suggerimenti, evidenza riga, menu, pagina iniziale) e scarta i
|
||||
valori non validi; la pagina iniziale accetta solo percorsi locali.
|
||||
5. **Tema scritto dal server.** Le preferenze diventano attributi `data-*` sull'elemento `<html>` già nella risposta
|
||||
del server (`App.razor`), così la prima pagina ha i colori giusti; il cambio dal profilo o dalla barra superiore li
|
||||
aggiorna dal vivo con `khaemhat.applyRoot`. Prima dell'accesso vale `data-theme="auto"`, che segue il sistema. Il
|
||||
profilo mostra ogni scelta subito (anteprima) e la conserva solo con **Salva**; chiudendo la scheda senza salvare
|
||||
torna l'aspetto salvato.
|
||||
6. **Aree non ancora costruite.** Il menu mostra le aree concesse da licenza e permessi anche se arrivano con
|
||||
milestone successive; aprono una pagina che dice con quale milestone arrivano (`MenuItem.Milestone`). Quando una
|
||||
pagina vera esiste, la sua rotta prende il posto di quella generica e la milestone si toglie dal catalogo.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Le pagine aperte restano in memoria nel circuito finché la scheda è aperta: il limite di 12 schede tiene il
|
||||
consumo sotto controllo.
|
||||
- Una pagina che usa parametri da query li riceve anche quando è nascosta e cambia la query di un'altra scheda con
|
||||
lo stesso nome di parametro: i nomi dei parametri da query vanno scelti specifici della pagina.
|
||||
- Aggiungere un testo vuol dire aggiungere una chiave al JSON; i test falliscono se manca.
|
||||
@@ -0,0 +1,73 @@
|
||||
# ADR 0021 - File e allegati: archivio su volume, versioni, cestino, scrittori in casa
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §2 (riga *PDF e file*), §9.4; milestone M3, issue #34
|
||||
|
||||
## Contesto
|
||||
|
||||
La specifica chiede allegati per azienda con versioni, cestino di 30 giorni, archivio su volume con limite, quota e
|
||||
aggancio per l'antivirus, e scrittori PDF, CSV, XLSX e ZIP scritti in casa (nessuna libreria esterna, ADR 0002). Lascia
|
||||
aperti la regola di numerazione delle versioni, la forma dell'archivio, il perimetro della prima versione del PDF e le
|
||||
impostazioni predefinite del CSV. Questo ADR fissa le scelte.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Archivio.** `IFileStore` sta in `Khaemhat.Core.Files` (l'implementazione è in Infrastructure, che non vede
|
||||
Application); `VolumeFileStore` scrive in `<KHAEMHAT_DATA_DIR>/files/<AZIENDA>/<aaaa>/<guid>`. Ogni file è scritto
|
||||
prima come `<guid>.part` **nella stessa cartella**, contando i byte (limite) e calcolando lo SHA-256 durante la
|
||||
copia; poi passa quota e scanner e viene rinominato. Mai file temporanei fuori dal volume dei dati. La chiave
|
||||
salvata nel database è `aaaa/guid` (relativa alla cartella dell'azienda) e viene validata: non può uscire dalla
|
||||
cartella. I `.part` rimasti da caricamenti interrotti si cancellano dopo un giorno.
|
||||
2. **Limiti.** 25 MB per file e nessuna quota per impostazione predefinita; gli amministratori li cambiano con le
|
||||
impostazioni di istanza `files.max-upload-mb` e `files.company-quota-mb`. Il limite di dimensione vale per i file
|
||||
caricati; i file generati hanno solo la quota. La quota si calcola sommando i file della cartella dell'azienda.
|
||||
3. **Antivirus.** `IFileScanner` riceve il file completo prima che diventi visibile; quello registrato
|
||||
(`NoOpFileScanner`) accetta tutto.
|
||||
4. **Versioni.** Ogni allegato ha una *serie* (`version_key`): per i file generati il codice del generatore
|
||||
(`gen:<codice>`), per gli altri il nome in minuscolo (`name:<nome>`). La versione è il massimo della serie nel
|
||||
record più uno, contando anche gli allegati nel cestino; un indice unico su record + serie + versione impedisce due
|
||||
versioni uguali (in caso di conflitto si riprova). *Rigenera* è una nuova generazione: non sovrascrive mai.
|
||||
Caricare un file con lo stesso nome ne crea la versione successiva e lascia consultabile la precedente. L'elenco
|
||||
mostra di norma solo l'ultima versione di ogni serie; il nome di download porta il suffisso `_vN` dalla v2.
|
||||
5. **Cestino.** Cancellare un allegato o il documento lo sposta nel cestino (`deleted_at`); il job di sistema
|
||||
`system.attachments-trash` (ogni notte alle 3:45) elimina righe e file dopo 30 giorni. Un allegato **bloccato**
|
||||
(`locked`, ad esempio l'XML inviato allo SDI) non si cancella, e un documento con allegati bloccati non può mandarli
|
||||
nel cestino. Il blocco è definitivo.
|
||||
6. **Permessi.** `attachments.read` per vedere e scaricare, `attachments.write` per caricare, generare e bloccare,
|
||||
`attachments.delete` per cancellare e ripristinare. Il permesso sul documento lo verifica chi chiama, che lo
|
||||
conosce. Ogni modifica scrive lo storico (`audit_log`); l'utente che ha caricato o generato il file è salvato anche
|
||||
in `attachments.user_name`, perché le colonne di audit conoscono l'utente solo dentro una richiesta HTTP.
|
||||
7. **Tipi di file.** Il tipo MIME si ricava dall'estensione quando è nota; quello dichiarato dal browser si usa solo
|
||||
per estensioni sconosciute. I nomi file sono ripuliti (niente cartelle né caratteri vietati, massimo 255).
|
||||
8. **CSV.** Predefiniti per Excel in italiano: separatore `;`, BOM UTF-8, virgola decimale, date `gg/mm/aaaa`,
|
||||
righe CRLF, virgolette RFC 4180. Le celle di testo che iniziano con `=`, `+`, `-`, `@`, tabulazione o ritorno a capo
|
||||
ricevono un apostrofo davanti (iniezione di formule); i numeri non vengono toccati. Disponibile anche il profilo
|
||||
invariante (`,`, punto decimale, date ISO, senza BOM).
|
||||
9. **Scrittura in streaming.** CSV, XLSX, ZIP e PDF scrivono sull'uscita solo con chiamate asincrone, quindi possono
|
||||
scrivere direttamente nella risposta HTTP (dove le scritture sincrone sono vietate). `ZipArchive` scrive ancora in
|
||||
modo sincrono le chiusure delle voci e la directory centrale: quei pochi byte passano da un piccolo buffer in
|
||||
memoria (`AsyncOutputBuffer`) e vengono inviati con la chiamata asincrona successiva.
|
||||
10. **PDF, prima versione.** PDF 1.7 con i 12 font Type1 standard latini (Symbol e ZapfDingbats esclusi) in
|
||||
`WinAnsiEncoding` (lettere accentate, `€`, virgolette tipografiche), testo, linee, rettangoli, colori RGB,
|
||||
immagini JPEG incorporate così come sono (`DCTDecode`), più pagine, dizionario *Info*, flussi compressi
|
||||
`FlateDecode`, tabella xref. Coordinate in punti dall'angolo **in basso a sinistra**, testo posizionato sulla linea
|
||||
di base. Le larghezze per misurare e andare a capo sono quelle AFM di Helvetica, Helvetica-Bold e Times-Roman;
|
||||
corsivi e grassetti di Times usano quelle del tondo, Courier è a passo fisso. Una pagina viene scritta sull'uscita
|
||||
quando inizia la successiva. **PDF/A-3** (font incorporati, XMP, output intent, allegati XML per la copia di
|
||||
cortesia FatturaPA) è rimandato: annotato come TODO in `PdfWriter`.
|
||||
11. **Generatori.** Un'uscita di *Genera file* è un `IFileGenerator` (codice, chiave del testo, tipo, estensione,
|
||||
entità supportate, nome file, `GenerateAsync`); `FileGenerationService` scrive il risultato direttamente
|
||||
nell'archivio e lo registra come allegato generato con la versione successiva, oppure lo scrive su un flusso senza
|
||||
salvarlo (anteprima di stampa). Per il *documento di prova* dell'issue #34 ci sono tre generatori dell'entità
|
||||
fittizia `demo.document`: PDF, CSV e XLSX con righe e importi inventati.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Gli allegati nel cestino occupano spazio e quota per 30 giorni.
|
||||
- Il calcolo della quota legge la cartella dell'azienda a ogni caricamento quando una quota è impostata: va bene per
|
||||
le dimensioni attese; se diventasse lento si terrà un contatore.
|
||||
- Un file rimasto senza riga (crash fra scrittura del file e inserimento) è solo spazio perso; il contrario non può
|
||||
accadere, perché la riga si scrive dopo il file e il file si cancella se l'inserimento fallisce.
|
||||
- I moduli che producono file (stampe, FatturaPA, report) registrano i loro `IFileGenerator`; quelli che ricevono
|
||||
file dall'esterno (SDI, e-mail) usano `AttachmentService.AddAsync` con il tipo giusto e, se serve, `Locked`.
|
||||
@@ -0,0 +1,47 @@
|
||||
# ADR 0022 - Dashboard a widget: layout per utente e per ruolo, liste fornite dai moduli
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §10.3, §11.12; milestone M3, issue #30 e #31
|
||||
|
||||
## Contesto
|
||||
|
||||
La specifica descrive la dashboard (mockup 004-006) con widget attivabili, ordinabili e ridimensionabili, una pagina
|
||||
iniziale scelta dall'utente e un layout predefinito per ruolo, ma non dice dove si salvano i layout dei ruoli, quale
|
||||
layout vede chi non ha mai personalizzato, né come i moduli che arrivano dopo M3 (vendite, magazzino, CRM) riempiono
|
||||
i widget. Lascia anche aperto il comando per tornare alla disposizione iniziale.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Catalogo fisso.** I widget sono un catalogo nel codice (`WidgetCatalog`): id, titolo, icona, larghezza
|
||||
predefinita, modulo di licenza, permesso di lettura, solo amministratori, milestone che porta i dati. Un widget è
|
||||
*disponibile* se il modulo è attivo, l'utente ha il permesso e, per *Stato del sistema*, è un account di istanza.
|
||||
2. **Layout in JSON.** `{"v":1,"widgets":[{"id":"todo","w":4}]}`: l'ordine è quello dell'elenco, le larghezze sono 3,
|
||||
4, 6, 8 o 12 colonne (una larghezza diversa va alla più vicina, la più larga a parità). Leggendolo si scartano id
|
||||
sconosciuti e ripetuti; un layout illeggibile vale come assente. Al massimo 30 widget.
|
||||
3. **Dove si salva.** Il layout dell'utente è un'impostazione utente (`dashboard.layout`, ADR 0020: sistema per gli
|
||||
account di istanza, azienda per gli utenti aziendali). Il layout di un ruolo è un'impostazione **dell'azienda**
|
||||
(`dashboard.layout.role.<CODICE>`) nella nuova tabella `company_settings`, scritta da `CompanySettingsService`
|
||||
con il permesso `company.settings.write`. Promemoria (`dashboard.notes`) e scorciatoie (`dashboard.shortcuts`)
|
||||
sono impostazioni utente.
|
||||
4. **Quale layout si vede.** Quello dell'utente; altrimenti quello del primo ruolo dell'utente (per id) che ne ha uno;
|
||||
altrimenti il layout di Khaemhat. In ogni caso si tolgono i widget non disponibili. **Ripristina** cancella il
|
||||
layout dell'utente e riporta quello del ruolo o di Khaemhat.
|
||||
5. **Layout di Khaemhat.** Solo widget che hanno già dati: Da fare oggi, Fatto oggi, Scadenze, Scorciatoie,
|
||||
Promemoria, Stato del sistema. I widget dei moduli futuri (KPI, Da evadere, Fatturato, Sottoscorta, CRM, Ultimi
|
||||
documenti) si possono già accendere e mostrano da quale milestone arrivano i dati, senza numeri finti.
|
||||
6. **Liste dai moduli.** *Da fare oggi*, *Fatto oggi* e *Scadenze 30 giorni* raccolgono le righe da sorgenti
|
||||
registrate nel contenitore (`ITodoSource`, `IDoneSource`, `IDeadlineSource`): ogni modulo aggiunge le sue. Le
|
||||
sorgenti si chiamano una dopo l'altra; una che fallisce si scrive nel log e si salta, il widget mostra le altre.
|
||||
In M3 ci sono licenza, avvisi non letti e attività programmate.
|
||||
7. **Personalizza.** Pannello laterale non modale (la pagina resta visibile) con pagina iniziale, interruttore della
|
||||
dashboard, elenco dei widget con interruttore, larghezza e frecce, e il predefinito per ruolo per chi gestisce
|
||||
l'azienda. Sulla griglia i widget si trascinano (HTML drag and drop) e hanno anche pulsanti per spostare,
|
||||
allargare, restringere e nascondere, così tutto funziona da tastiera. Ogni modifica si salva subito.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- I moduli di M5, M6 e M11 riempiono i widget registrando sorgenti e sostituendo il componente del widget; il layout
|
||||
salvato dagli utenti resta valido.
|
||||
- `company_settings` è il posto per le altre impostazioni di azienda delle prossime milestone.
|
||||
- Un utente con più ruoli prende il predefinito del primo; se servirà una priorità esplicita fra ruoli si aggiungerà.
|
||||
@@ -0,0 +1,55 @@
|
||||
# ADR 0023 - Aiuto in app dalla copia della wiki, notifiche lette per utente, ricerca a fornitori
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §10.2, §17; milestone M3, issue #32 (mockup 009, 010, 011)
|
||||
|
||||
## Contesto
|
||||
|
||||
La specifica chiede che `F1` apra la pagina wiki della maschera dentro l'applicazione (mockup 011), con indice,
|
||||
*Apri nel wiki* e *Segnala un problema*, e che l'aiuto funzioni anche nelle installazioni senza Internet servendo
|
||||
una copia della wiki "all'indirizzo `/help`". Non dice come la copia arriva nell'immagine, come si converte il
|
||||
Markdown senza librerie esterne (SPEC §1.2), né come una notifica "per tutti" diventa letta per un utente e non per
|
||||
gli altri. Per la ricerca globale (mockup 009) dice cosa trovare, ma i dati (clienti, articoli, documenti) arrivano
|
||||
con le milestone successive.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **La wiki viaggia con il programma.** La compilazione copia `docs/wiki/*.md` in `help/wiki/` accanto al
|
||||
programma, e in `help/media/` le immagini che le pagine mostrano (miniature e PNG dei mockup, icone, `img/` della
|
||||
wiki), con lo stesso percorso che hanno nel repository. `.dockerignore` lascia entrare solo quelle cartelle di
|
||||
`docs/`. Nessun download all'avvio, nessuna scrittura: la copia è di sola lettura e corrisponde alla versione.
|
||||
2. **Markdown in casa.** `WikiMarkdown` converte il sottoinsieme che la wiki usa: titoli con ancora, paragrafi,
|
||||
elenchi annidati, tabelle, citazioni, blocchi di codice, linee, immagini, collegamenti, grassetto, corsivo,
|
||||
codice. Tutto il testo è codificato (niente HTML grezzo); diventano collegamenti solo indirizzi `http(s)`,
|
||||
ancore `#` e nomi di pagina. La citazione `> **Stato:** …` in testa a ogni pagina è lo stato della pagina e si
|
||||
mostra come tale, riga per riga; le altre citazioni sono riquadri informativi.
|
||||
3. **Indirizzi.** L'aiuto è la pagina Blazor `/aiuto/{Pagina}` (nelle schede come ogni altra maschera); le immagini
|
||||
sono servite da `/aiuto/media/{percorso}` solo se il percorso è fra quelli copiati e ha un'estensione d'immagine.
|
||||
L'indirizzo `/help` della specifica resta come rinvio a `/aiuto`. Le immagini che puntano ai file del repository
|
||||
(`…/raw/branch/main/<percorso>`) si servono dalla copia locale; le altre restano sul web.
|
||||
4. **Una pagina per ogni maschera.** `HelpLinks` associa a ogni prefisso di percorso una pagina wiki; un test
|
||||
controlla che ogni pagina dell'applicazione e ogni voce di menu porti a una pagina che esiste, e che tutti i
|
||||
collegamenti fra pagine della wiki trovino la loro pagina.
|
||||
5. **Wiki online configurabile.** `KHAEMHAT_HELP_URL` (facoltativa, indirizzo assoluto `http(s)`) è la wiki aperta da
|
||||
*Apri nel wiki*; predefinita la wiki del progetto. *Segnala un problema* apre `…/issues/new` del repository della
|
||||
wiki quando l'indirizzo finisce con `/wiki/` (Gitea e GitHub), altrimenti non compare.
|
||||
6. **Notifiche lette per utente.** Una notifica personale (con destinatario) usa la sua colonna `read_at`. Una
|
||||
notifica per tutti resta una riga sola; chi la legge aggiunge una riga in `sys_notification_reads` (notifiche di
|
||||
sistema) o `notification_reads` (notifiche dell'azienda), con vincolo unico su notifica e utente. Il pannello
|
||||
mostra le ultime 100 notifiche dell'utente, filtri *Tutte* e *Non lette*, *Segna tutte come lette*; la campanella
|
||||
aggiorna il conteggio ogni minuto.
|
||||
7. **Ricerca a fornitori.** Pagine del menu e comandi si cercano subito nel browser. I record arrivano da
|
||||
`ISearchProvider` registrati nel contenitore e interrogati in parallelo da `GlobalSearchService` dopo una pausa di
|
||||
200 ms e almeno 2 caratteri: ognuno dichiara gli ambiti (tutto, `#` documenti, `@` persone), dà al massimo 8
|
||||
risultati, e uno lento (oltre 3 secondi) o in errore si scrive nel log e si salta. In M3 c'è il fornitore delle
|
||||
pagine dell'aiuto (titoli e sezioni); `#` e `@` dicono con quali moduli arriveranno i risultati.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- L'aiuto funziona senza Internet ed è sempre quello della versione installata; l'immagine cresce delle sole pagine
|
||||
e immagini citate (qualche MB).
|
||||
- Il convertitore copre solo la sintassi usata dalla wiki: una pagina nuova con sintassi diversa si vede come testo,
|
||||
e il test di conversione di tutte le pagine la segnala.
|
||||
- I moduli successivi aggiungono i propri fornitori di ricerca e le proprie sorgenti di notifiche senza toccare la
|
||||
shell.
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0024 - Componenti `Kh*`, pagine record e liste con un solo modello di richiesta
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §10.5, §10.6, §10.7, §19; milestone M3, issue #27, #28, #29
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §10.7 elenca i componenti `Kh*` e §10.5 la struttura comune di documenti e anagrafiche (toolbar a icone,
|
||||
intestazione, schede, scorciatoie), ma non dice come si condividono il comportamento delle pagine che modificano un
|
||||
record, come una griglia legge 100.000 righe senza librerie esterne, né dove finiscono filtri e colonne salvati. Le
|
||||
maschere vere arrivano da M4 in poi: se ogni modulo scrivesse il proprio markup e le proprie query, toolbar,
|
||||
scorciatoie e filtri divergerebbero subito.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Una libreria, nomi dei mockup.** I componenti vivono in `Components/Ui` con prefisso `Kh` e riproducono le
|
||||
classi di `mockup.css` con gli stessi nomi semantici (`toolbar.icons`, `dochead`, `fgroup`, `grid`…). Le varianti
|
||||
che i mockup non hanno prendono un nome nuovo `kh-…`: una classe ha un solo significato (in 0.3.0 `.tl` e
|
||||
`.kh-choices` usati in due sensi hanno rotto il totale documento e le schede dei temi).
|
||||
2. **Campi all'italiana.** `KhTextBox`, `KhNumberBox`, `KhDateBox`, `KhSelect`, `KhCheck`, `KhSwitch`, `KhHotlink`
|
||||
dentro `KhForm`. Numeri con virgola e punto delle migliaia e calcolo `=…` (quattro operazioni e parentesi, parser
|
||||
in casa); date con `T`, `F`, `I`, `+n`, `-n` e cifre senza separatori (`ItalianDate`). Gli errori del servizio
|
||||
tornano per nome di campo, il riepilogo porta il focus sul campo.
|
||||
3. **Pagine record come classi base.** `RecordPage<T>` gestisce comandi standard, stato modificato sulla scheda della
|
||||
shell, conferme prima di scartare o eliminare e le scorciatoie di §10.5.7, attive solo quando la pagina è la
|
||||
scheda visibile. `DocumentPage<TDoc, TLine>` apre sulla scheda **Righe**; `MasterDataPage<T>` sui dati principali.
|
||||
I comandi sono `Func<Task>`: chi li ridefinisce chiama `StateHasChanged` se cambia lo stato della pagina.
|
||||
4. **`KhIconToolbar` su una riga.** I comandi meno usati scendono nel menu `…` invece di andare a capo.
|
||||
5. **Un modello di richiesta per tutte le liste.** `ListQuery` (testo cercato, filtri, ordinamento, pagina) e
|
||||
`ListPage<T>` (righe, totale, totali di colonna su tutte le righe selezionate). `ListFields<T>` descrive una volta i
|
||||
campi e li applica sia a una query del micro-ORM (SQL, `LIKE` senza distinzione di maiuscole) sia a righe in
|
||||
memoria (`InMemoryListSource`). I valori dei filtri sono testi invarianti, così un filtro si salva e si rilegge
|
||||
uguale.
|
||||
6. **`KhGrid` virtualizzata.** `Virtualize` di Blazor con righe alte 30 px e 20 righe di margine legge le pagine
|
||||
mentre si scorre (oppure a pagine con il pager); ordinamento, selezione, tastiera, modifica in riga, totali, menu
|
||||
di riga, esportazione CSV/XLSX con gli scrittori in casa (ADR 0021). Una ricerca nuova annulla quella in corso.
|
||||
7. **Salvati per utente.** Disposizione delle colonne di una griglia e filtri del radar (stella) sono impostazioni
|
||||
utente (ADR 0020) con chiave della lista; si eliminano dalla griglia e dal radar. La scheda *Layout salvati* del
|
||||
profilo arriva con le prime maschere che li usano (M4).
|
||||
8. **`KhRadar` intorno alla griglia**: ricerca, filtri rapidi, costruttore di filtri, filtri salvati; la stessa
|
||||
finestra serve la ricerca `F4` degli hotlink. `KhLinesGrid` è la griglia delle righe dei documenti, pensata per la
|
||||
tastiera (`Invio` cella successiva, `Ctrl+↓` nuova riga, `Ctrl+Canc` togli la riga).
|
||||
9. **Catalogo per gli sviluppatori.** `/sviluppo/componenti` e `/sviluppo/documento` (solo in ambiente di sviluppo)
|
||||
mostrano ogni componente con dati finti; gli screenshot della wiki si fanno da lì finché mancano le maschere vere.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Le maschere di M4 e seguenti sono composizione di componenti e di una `ListFields<T>`; un comportamento comune si
|
||||
corregge in un punto.
|
||||
- La griglia non usa librerie esterne e regge 100.000 righe in memoria; con PostgreSQL la paginazione è nella query.
|
||||
- I nomi di classe nuovi vanno controllati contro `mockup.css` e i fogli esistenti prima di introdurli.
|
||||
- Rinomina e scelta del filtro predefinito, e la scheda *Layout salvati* del profilo, restano da fare (M4).
|
||||
@@ -0,0 +1,51 @@
|
||||
# ADR 0025 - Pacchetto fiscale con parti obbligatorie e funzioni facoltative
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §1.10, §3, §21 (Fiscal e Validatori); ADR 0007; milestone M4, issue #37 e #40
|
||||
|
||||
## Contesto
|
||||
|
||||
ADR 0007 isola la fiscalità in `Khaemhat.Fiscal.Abstractions` (interfacce) e `Khaemhat.Fiscal.Italy`
|
||||
(implementazione). SPEC §21 elenca una dozzina di interfacce (`ITaxEngine`, `IEInvoiceFormat`, `IWithholdingRules`,
|
||||
`IIntrastatExporter`…), ma non dice come il pacchetto le espone né cosa succede a quelle che arrivano con milestone
|
||||
successive (FatturaPA in M9, bilancio CEE e Intrastat in M10). Inoltre non tutti i paesi hanno tutte le funzioni:
|
||||
un paese fuori dall'UE non ha Intrastat, non ovunque esistono le ritenute d'acconto.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Tre parti obbligatorie** come proprietà di `IFiscalPack`: `TaxCodes` (`ITaxCodeCatalog`: nature, codici IVA di
|
||||
base, regole del codice IVA), `TaxEngine` (`ITaxEngine`: arrotondamenti, castelletto, bollo) e `Calendar`
|
||||
(`IFiscalCalendar`: periodi, scadenze, festivi). Ogni paese ha imposte e scadenze.
|
||||
2. **Funzioni facoltative** chieste per tipo: `GetFeature<T>()` restituisce `null` se il paese (o la versione) non
|
||||
la offre; `Require<T>()` lancia `FiscalFeatureNotAvailableException` con paese e funzione. In 0.4.0 il pacchetto
|
||||
italiano offre `IEInvoiceFormat` (versione delle specifiche e code list FatturaPA), `IWithholdingRules`,
|
||||
`IFixedAssetRules` e `ITaxPaymentFormExporter` (codici tributo F24); `IFinancialStatementsSchema`,
|
||||
`IChartOfAccountsTemplate` e `IIntrastatExporter` sono definite ma arrivano con la milestone che le usa.
|
||||
3. **Le interfacce crescono con le milestone.** Ognuna contiene oggi solo ciò che serve e si può verificare
|
||||
(code list, regole, costanti); scrittori e lettori di file si aggiungono quando arriva la loro maschera.
|
||||
4. **Problemi come codici.** Le regole restituiscono `FiscalProblem` (campo, codice stabile come
|
||||
`fiscal.tax.nature-required`, errore o avviso); l'interfaccia traduce il codice con le risorse.
|
||||
5. **Risoluzione per paese.** `FiscalPackCatalog` raccoglie i pacchetti registrati e li trova per
|
||||
`company_profile.country` (senza distinzione di maiuscole). La composizione in `Hosting/KhaemhatServices.cs` è
|
||||
l'unico file fuori dal pacchetto che nomina `Khaemhat.Fiscal.Italy`: lo verifica `FiscalPackIsolationTests`, che
|
||||
controlla anche che le astrazioni non contengano nomi italiani.
|
||||
6. **Identificativi italiani nel pacchetto.** SPEC §21 mette `ItalianVatNumberValidator`, `FiscalCodeValidator`,
|
||||
`FiscalCodeCalculator` e `SdiRecipientCodeValidator` in `Khaemhat.Core`; il vincolo non negoziabile di SPEC §1.10
|
||||
("tutto ciò che è italiano sta in `Fiscal.Italy`") prevale: stanno nel pacchetto italiano dietro la funzione
|
||||
`ITaxIdentifierRules`, e la banca da IBAN dietro `IBankDirectory`. In `Core` restano i controlli internazionali:
|
||||
`IbanValidator` (mod 97 e lunghezza per paese), `EanValidator` (EAN-8, UPC-A, EAN-13, GTIN-14), `EmailValidator`.
|
||||
Il controllo VIES è `ViesClient` in `Infrastructure` (servizio REST della Commissione europea): un servizio che
|
||||
non risponde dà *non disponibile*, mai *non valida*.
|
||||
7. **Versione delle specifiche.** `FatturaPaCodeLists.SpecVersion` è **1.9.1** (pubblicata il 31 marzo 2026, in
|
||||
vigore dal 15 maggio 2026; non cambia le code list della 1.9, che aveva introdotto TD29 e ridefinito TD20). Va
|
||||
ricontrollata sul sito dell'Agenzia delle Entrate a ogni rilascio.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Un modulo che usa una funzione facoltativa decide cosa mostrare quando manca (per esempio nascondere Intrastat),
|
||||
invece di fallire alla prima chiamata.
|
||||
- Codici IVA di base, nature e code list del seed (#45) vengono dal pacchetto: c'è un'unica fonte.
|
||||
- La regola del bollo considera le nature N1, N2.x, N3.5, N3.6, N4 e N5; esportazioni, cessioni intracomunitarie,
|
||||
San Marino, operazioni assimilate, inversione contabile e N7 non contano. È da rivedere con i documenti di
|
||||
vendita (M5) se la normativa cambia.
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0026 - Tabelle azienda generiche e dati di base solo in aggiunta
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §4 (`scripts/seed.sh`), §11.1, §14; ADR 0025; milestone M4, issue #38, #39 e #45
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §11.1 elenca una ventina di tabelle azienda (codici IVA, pagamenti, depositi, vettori, numeratori, categorie…),
|
||||
ognuna con elenco, dettaglio, import ed export CSV. SPEC §14 chiede che le tabelle di base si carichino alla creazione
|
||||
dell'azienda e si aggiornino a ogni versione "senza toccare le righe modificate dall'azienda", ma non dice come
|
||||
riconoscere una riga modificata. Province, comuni con CAP e la tabella ABI/CAB delle banche sono elenchi pubblici
|
||||
grandi (8.000 comuni, decine di migliaia di sportelli) che non sono nel repository e hanno licenze da verificare.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Un servizio per tutte le tabelle codificate.** Ogni tabella è un'entità `CodedEntity` (codice, descrizione,
|
||||
disattivata) descritta in `TableCatalog`: le regole comuni (codice unico, una sola riga predefinita, eliminazione
|
||||
rifiutata se la riga è usata e proposta di disattivarla, storico, cache invalidata fra istanze, CSV tutto o niente)
|
||||
stanno in `TableService`. Le regole proprie di una tabella sono funzioni del catalogo; quelle italiane (natura
|
||||
IVA, codici SDI) arrivano dal pacchetto fiscale (ADR 0025).
|
||||
2. **Una maschera generica.** L'interfaccia descrive ogni tabella in `TableScreens` (campi, tipo, lookup, code list
|
||||
del pacchetto) e la mostra con un unico editor `KhTableEditor<T>` all'indirizzo `/tabelle/<slug>`. Profilo
|
||||
azienda, esercizi e cambi hanno pagine proprie perché non sono elenchi di codici.
|
||||
3. **Dati di base solo in aggiunta.** Il caricamento inserisce **solo i codici che mancano** e non modifica né
|
||||
cancella righe esistenti, anche se identiche al pacchetto: una riga presente è dell'azienda. Non serve quindi
|
||||
distinguere righe "modificate" da righe "originali". La versione caricata è salvata nelle impostazioni
|
||||
dell'azienda (`seed.base.version`, ad esempio `IT 2026.2`). Correggere una riga di base già presente è un'azione
|
||||
esplicita dell'utente, non dell'aggiornamento.
|
||||
4. **Origine delle righe.** Righe fiscali (codici IVA, modalità e condizioni di pagamento, tipi documento) dal
|
||||
pacchetto del paese tramite `IBaseTablesTemplate`; paesi ISO da un CSV incorporato; valute BCE, unità di misura,
|
||||
trasporti, causali, deposito principale, listino base, numeratori ed esercizio corrente dal seeder di base.
|
||||
5. **Comuni.** Il **codice** di un comune è il suo codice catastale (4 caratteri, quello del codice fiscale): non
|
||||
serve una colonna in più.
|
||||
6. **Elenchi pubblici caricati a parte.** Province, comuni con CAP e banche ABI/CAB non sono nel seed di 0.4.0:
|
||||
arriveranno come file di dati con origine e licenza indicate (ISTAT, CC BY 4.0, per province e comuni) dopo il
|
||||
via dell'utente al download. Fino ad allora le tabelle si riempiono a mano o con l'import CSV.
|
||||
*Aggiornato dall'ADR 0028:* province e comuni ISTAT, con i CAP di GeoNames, sono nei dati di base dalla
|
||||
versione `IT 2026.3`; le banche restano fuori.
|
||||
7. **Riga di comando.** `scripts/seed.sh --base [--company CODICE]` esegue la sequenza di avvio senza servire pagine
|
||||
(migrazioni, prima azienda) e aggiunge i dati di base a un'azienda o a tutte quelle attive. Nel container lo
|
||||
script è in `/app/scripts/` e passa da `entrypoint.sh` con il verbo `seed`; in sviluppo usa `dotnet run`.
|
||||
`--demo` e `--scale` arrivano con anagrafiche e articoli.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Un aggiornamento delle tabelle di base non può mai rovinare una configurazione aziendale; il rovescio è che una
|
||||
correzione a un codice già presente (ad esempio un riferimento normativo cambiato) va comunicata nel `CHANGELOG`
|
||||
e fatta dall'utente, o con una migrazione mirata quando è obbligatoria.
|
||||
- Aggiungere una tabella costa un'entità, una mappa, una voce in `TableCatalog` e una in `TableScreens`, più i testi:
|
||||
i test controllano che ogni schermata abbia le chiavi di testo e ogni codice di errore la sua traduzione.
|
||||
- Il pulsante *Aggiorna da tabelle base* delle maschere e la pagina di amministrazione (mockup 089) usano lo
|
||||
stesso `SeedRunner`.
|
||||
@@ -0,0 +1,49 @@
|
||||
# ADR 0027 - Codici automatici con sequenze per chiave e compilazione a opzioni
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-11
|
||||
- **Modifica:** SPEC §11.12 (codici automatici, compilazione automatica); ADR 0025, 0026; milestone M4, issue #43
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §11.12 chiede maschere di codice per archivio (`C{seq:000000}`, `{categoria}-{seq:0000}`, `L{anno}-{seq:0000}`…),
|
||||
progressivo globale o per categoria/anno, codice manuale ammesso o no, anteprima del prossimo codice e sequenze in
|
||||
`code_sequences` con assegnazione atomica. Non dice dove stanno le regole, come si chiamano le sequenze, cosa succede
|
||||
se il codice successivo è già stato scritto a mano o se la maschera cambia. Per la compilazione automatica elenca le
|
||||
opzioni senza dire chi le applica, e la banca dall'IBAN dipende da un elenco ABI che non è ancora nel repository
|
||||
(ADR 0026).
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Regole nelle impostazioni dell'azienda.** La maschera e il codice manuale di ogni archivio stanno in
|
||||
`company_settings` (`codes.<archivio>.mask`, `codes.<archivio>.manual`, `codes.items.unique-barcode`); un archivio
|
||||
senza impostazioni usa la maschera di SPEC. Gli archivi sono un elenco fisso in `CodeRuleService.Definitions`, con
|
||||
il modulo di licenza e la lunghezza massima del codice.
|
||||
2. **Una sequenza per chiave.** `code_sequences` ha una riga per chiave: il nome dell'archivio, più l'anno se la
|
||||
maschera contiene `{anno}`, più la categoria se contiene `{categoria}` (`customers`, `leads:2026`, `items:VALV`).
|
||||
La maschera non fa parte della chiave: **cambiare maschera continua lo stesso progressivo** e non riscrive i codici
|
||||
già assegnati.
|
||||
3. **Assegnazione nella transazione del salvataggio.** `CodeRuleService.AssignAsync` prende un lock applicativo sulla
|
||||
chiave (`AcquireLockAsync`, vuoto su SQLite dove le scritture sono già in fila), incrementa la sequenza e la scrive
|
||||
nella stessa unità di lavoro del record: se il salvataggio fallisce il numero torna libero, e due salvataggi
|
||||
contemporanei non ottengono mai lo stesso codice. Un codice già presente nella tabella (scritto a mano) viene
|
||||
saltato; dopo 1.000 salti il salvataggio è rifiutato.
|
||||
4. **Maschere controllate.** Letterali `A-Z 0-9 - _ / .` in maiuscolo, esattamente un `{seq}`, segnaposto
|
||||
`{anno}`/`{year}` e `{categoria}`/`{category}`, lunghezza minima entro quella della tabella. Gli errori sono codici
|
||||
(`codes.mask.*`) tradotti dall'interfaccia.
|
||||
5. **Compilazione a opzioni.** `AutoFillService` raccoglie le funzioni (comune da CAP e viceversa, codice fiscale dal
|
||||
pacchetto fiscale, VIES, banca da IBAN, data di consegna sul calendario del pacchetto) e le opzioni accese o spente
|
||||
(`autofill.<opzione>`); le maschere chiedono `IsOnAsync` prima di compilare. Il job dei cambi BCE salta le aziende
|
||||
che hanno spento l'opzione. Le opzioni sulle righe dei documenti e sui conti si applicano con i documenti (M5).
|
||||
6. **Banca da IBAN senza elenco ABI.** `IBankDirectory.ReadIban` restituisce sempre ABI e CAB di un IBAN italiano;
|
||||
nome e BIC arrivano dall'elenco quando c'è, altrimenti da un conto dell'azienda presso la stessa banca.
|
||||
7. **Modulo.** SPEC mette codici automatici e preferenze nel modulo AUTO, ma servono a ogni azienda (mockup 074, M4):
|
||||
stanno nel modulo CORE come le tabelle; le maschere degli archivi di CRM, Servizi e Cespiti si preparano anche
|
||||
senza il modulo.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Le anagrafiche (#41) e gli articoli (#42) chiamano `AssignAsync` quando il codice è vuoto e `CheckManual` quando è
|
||||
scritto; gli import li trattano allo stesso modo.
|
||||
- Una sequenza per categoria nasce al primo articolo della categoria; rinominare il codice di una categoria fa
|
||||
ripartire il suo progressivo, ma i codici già assegnati restano e quelli ripetuti vengono saltati.
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0028 - Province e comuni dall'elenco ISTAT e CAP da GeoNames nel pacchetto fiscale
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-12
|
||||
- **Modifica:** ADR 0026 punto 6; SPEC §11.1, §11.12, §14; milestone M4, issue #45
|
||||
|
||||
## Contesto
|
||||
|
||||
L'ADR 0026 rimandava province, comuni con CAP e banche ABI/CAB a file di dati con origine e licenza verificate,
|
||||
caricati dopo il via dell'utente. Il via è arrivato il 2026-11-12 per due fonti:
|
||||
|
||||
- l'**elenco dei codici dei comuni dell'ISTAT** (*Codici statistici delle unità amministrative territoriali*),
|
||||
pubblicato con licenza **CC BY 4.0** (note legali ISTAT). Il file CSV allo stesso indirizzo è fermo al gennaio 2024
|
||||
e ha ancora le 107 province precedenti al riordino della Sardegna; il file xlsx è aggiornato al **26/02/2026** e ha
|
||||
le **110 province** e i **7.894 comuni** in vigore;
|
||||
- il repository **comuni-json** per i CAP. La sua licenza non è MIT come si era ipotizzato: i comuni vengono
|
||||
dall'ISTAT (CC BY), ma per i CAP l'autore dichiara che le fonti non indicano una licenza e che al repository
|
||||
**non si applica nessuna licenza**. I dati sono fermi al 01/01/2020, prima delle fusioni di comuni successive.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Province e comuni nel pacchetto fiscale.** Sono dati italiani, quindi stanno in `Khaemhat.Fiscal.Italy`
|
||||
(`Data/province.csv`, `Data/comuni.csv`, risorse incorporate) dietro una nuova funzione facoltativa del pacchetto,
|
||||
`IPlaceDirectory` (province, comuni, origine). `BaseTablesSeeder` li aggiunge come il resto dei dati di base: solo
|
||||
i codici mancanti, mai modificando una riga già presente.
|
||||
2. **Formato ridotto.** Dal foglio ISTAT si tengono, per le province, sigla, denominazione e regione; per i comuni,
|
||||
codice catastale (il **codice** del comune, ADR 0026), denominazione in italiano, sigla della provincia, regione e
|
||||
codice ISTAT a 6 cifre. I file si rigenerano dal foglio ISTAT con lo stesso schema; ogni aggiornamento porta una
|
||||
nuova versione dei dati del pacchetto (da `IT 2026.2` a `IT 2026.3`).
|
||||
3. **Attribuzione.** L'origine (ISTAT, data dell'elenco, CC BY 4.0; GeoNames per i CAP) è scritta in
|
||||
`ItalianPlaces.ListSource`, nella wiki *Dati di base e di esempio* e in questo ADR.
|
||||
4. **Niente CAP da comuni-json.** Un file senza licenza non entra in un repository pubblico né nell'immagine
|
||||
distribuita, e i CAP del 2020 sarebbero comunque incompleti.
|
||||
5. **CAP da GeoNames.** Con un secondo via dell'utente (2026-11-12) i CAP vengono dall'elenco dei codici postali
|
||||
italiani di **GeoNames** (`IT.zip`, CC BY 4.0, attribuzione a www.geonames.org). GeoNames elenca località, non
|
||||
comuni: una riga si assegna a un comune quando nome (senza accenti, apostrofi e trattini, parte italiana dei nomi
|
||||
bilingui) e sigla della provincia coincidono con un solo comune; in Sardegna, dove le sigle sono cambiate, basta
|
||||
il nome entro la regione. Le frazioni con nome proprio restano fuori. Risultato: **7.750 comuni su 7.894** hanno i
|
||||
CAP (un CAP, una lista o intervalli come `10121-10156`); i 144 senza sono in gran parte comuni rinominati o nati da
|
||||
fusioni (ad esempio Sanremo, che GeoNames chiama *San Remo*) e si completano a mano o con l'**Importa CSV**.
|
||||
6. **Strumento di rigenerazione.** `tools/Khaemhat.PlacesTool` (non distribuito, solo framework) legge il foglio ISTAT
|
||||
e `IT.zip` e riscrive `Data/province.csv` e `Data/comuni.csv`; i file scaricati restano fuori dal repository.
|
||||
7. **Banche ABI/CAB** restano fuori finché non c'è una fonte aperta con licenza chiara (ADR 0026, ADR 0027 punto 6).
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Un'azienda nuova ha subito province, comuni e CAP: il calcolo del codice fiscale, la scelta del comune e la
|
||||
compilazione dal CAP funzionano senza caricare nulla. Le aziende esistenti li ricevono al primo avvio con la
|
||||
versione `IT 2026.3`, o con *Aggiorna tabelle di base*.
|
||||
- Il caricamento di base aggiunge circa 8.000 righe alla creazione dell'azienda: su SQLite resta sotto i due secondi;
|
||||
su PostgreSQL va misurato insieme alle altre misure di riferimento (`docs/DATA-MODEL.md` §6.1).
|
||||
- Un comune soppresso per fusione resta nella tabella di chi lo aveva già: va disattivato a mano. Le variazioni
|
||||
vanno annotate nel `CHANGELOG` quando si aggiorna l'elenco.
|
||||
@@ -0,0 +1,65 @@
|
||||
# ADR 0029 - Anagrafiche: un archivio per clienti, fornitori, prospect e lead
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-12
|
||||
- **Modifica:** SPEC §9 (modello dati delle anagrafiche), §11.2, §11.12, §14; milestone M4, issue #41
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §11.2 descrive clienti, fornitori, prospect e lead con radar (mockup 012-013), scheda a gruppi (014-016),
|
||||
condizioni commerciali, dati fiscali e SDI, banche, contatti e indirizzi. §9 elenca le tabelle `parties` e i
|
||||
dettagli, ma lascia aperti alcuni punti: come si rappresenta un soggetto che è sia cliente sia fornitore, che codice
|
||||
riceve un prospect, quando si verifica il VIES, come si cancella un'anagrafica usata, come sono fatti i dati di
|
||||
esempio prima che esistano gli articoli e i documenti.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Un archivio, quattro tipi.** `parties` ha un `kind` (*Customer*, *Supplier*, *Prospect*, *Lead*) e un
|
||||
`subject_type` (*Company*, *Person*, *PublicAdministration*, *EuCompany*, *NonEuCompany*, *FlatRate*) che decide i
|
||||
controlli e i valori proposti. Un soggetto che è sia cliente sia fornitore è un **cliente** con
|
||||
`is_also_supplier`: compare in entrambi i radar con lo stesso codice cliente. Un fornitore che diventa cliente
|
||||
(azione *Converti in cliente*) diventa quindi `Customer` con `is_also_supplier = true` e tiene il suo codice.
|
||||
2. **Tre radar.** `/anagrafiche/clienti` (tipo *Customer*), `/anagrafiche/fornitori` (*Supplier* più i clienti che
|
||||
sono anche fornitori), `/anagrafiche/contatti` (*Prospect* e *Lead*, con il filtro rapido del tipo).
|
||||
3. **Codici.** Clienti e fornitori usano le maschere `customers` e `suppliers`; prospect e lead la maschera `leads`
|
||||
(`L{anno}-{seq:0000}`, ADR 0027). Alla conversione in cliente un prospect o un lead riceve il codice cliente e il
|
||||
vecchio resta in `previous_code`, così i riferimenti esterni (e-mail, appunti) si ritrovano con la ricerca.
|
||||
4. **Dettagli in tabelle proprie.** Indirizzi, contatti e conti sono liste (`party_addresses`, `party_contacts`,
|
||||
`party_bank_accounts`, al più un predefinito per tipo); condizioni di vendita, di acquisto e dati fiscali sono
|
||||
tabelle 1:1 (`party_sales_terms`, `party_purchase_terms`, `party_fiscal`) create insieme all'anagrafica. Il
|
||||
salvataggio riscrive la scheda intera in una transazione; lo storico registra testata e dettagli. La cancellazione
|
||||
dei dettagli è a cascata.
|
||||
5. **Controlli dal pacchetto fiscale.** Partita IVA, codice fiscale, codice destinatario e PEC passano da
|
||||
`ITaxIdentifierRules` (ADR 0025). Errori bloccanti: ragione sociale, P.IVA per un'impresa, identificativo per una
|
||||
PA, codice fiscale non valido, codice duplicato, paese incoerente con il tipo soggetto, dichiarazione d'intento
|
||||
senza numero o plafond. **Avvisi**, che non bloccano: P.IVA già usata da un'altra anagrafica (filiali, sedi
|
||||
distinte), privato senza codice fiscale. Per un cliente privato o estero, o per un'impresa con sola PEC, il codice
|
||||
destinatario mancante si compila con il valore del formato (`0000000`, `XXXXXXX`).
|
||||
6. **VIES al salvataggio.** Per un'impresa UE la verifica parte dopo il commit, solo se la P.IVA o il paese sono
|
||||
cambiati o non è mai stata verificata, e solo se la compilazione automatica *Vies* è accesa. L'esito (*valida*,
|
||||
*non valida*, *non verificata*) e la data restano sull'anagrafica; un VIES irraggiungibile non impedisce di
|
||||
salvare. L'azione *Verifica VIES* della scheda ripete la verifica. Le date sono `DateTime` in UTC, come nel
|
||||
resto del modello.
|
||||
7. **Cancellare o disattivare.** *Elimina* prova a cancellare; se il database rifiuta per riferimenti (documenti dalle
|
||||
prossime milestone), l'anagrafica viene **disattivata** e l'utente lo legge in un messaggio. Il radar disattiva e
|
||||
riattiva più righe insieme; le disattivate sono escluse per filtro iniziale.
|
||||
8. **Dati di esempio senza documenti.** `DemoPartiesSeeder` (seeder *Demo*, solo se le anagrafiche sono vuote) crea
|
||||
3 agenti e 21 anagrafiche con `is_demo`: 12 clienti che coprono tutti i tipi soggetto (PA con split payment,
|
||||
cliente bloccato, disattivato, anche fornitore, con dichiarazione d'intento), 5 fornitori (ritenuta, ENASARCO, UE),
|
||||
2 prospect e 2 lead. Partite IVA, codici fiscali e IBAN sono **numeri inventati ma formalmente validi** (cifra di
|
||||
controllo, mod 97), scritti come costanti e controllati da un test; nessuno appartiene a un soggetto reale per
|
||||
scelta, ma la coincidenza non si può escludere e per questo non si verificano sul VIES. Il volume completo della
|
||||
SPEC (40 clienti, 15 fornitori, documenti) arriva in M9 con `seed --demo`.
|
||||
9. **Rinviati.** `party_item_codes` (codici articolo del cliente o del fornitore) arriva con gli articoli (#42);
|
||||
fatturato, scaduto, fido usato e *Scheda 360°* con vendite (M5) e scadenzario (M9); il flag utente *vede solo i
|
||||
propri clienti* con i filtri per riga sui permessi, non ancora previsti in una milestone. Gli agenti di esempio non hanno `is_demo` perché la tabella
|
||||
degli agenti (ADR 0026) non ha la colonna: si rimuovono a mano.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Una sola tabella e una sola query per i tre radar; le condizioni commerciali si leggono con un join 1:1.
|
||||
- Il passaggio fornitore → cliente non cambia codice né documenti; il passaggio prospect → cliente cambia codice e
|
||||
lascia traccia in `previous_code` e nello storico.
|
||||
- I controlli fiscali italiani restano nel pacchetto; un altro paese porterà le sue regole senza toccare il servizio.
|
||||
- I dati di esempio non hanno numeri reali e restano validi per i controlli, quindi le prove automatiche li usano come
|
||||
casi realistici (ogni anagrafica di esempio supera `ValidateAsync`).
|
||||
@@ -0,0 +1,67 @@
|
||||
# ADR 0030 - Articoli e listini: prezzi con validità, listini derivati, ricerca del prezzo
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-12
|
||||
- **Modifica:** SPEC §9 (modello dati degli articoli), §11.2, §11.3, §14; milestone M4, issue #42
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §11.2 descrive la scheda articolo (mockup 017) con UM alternative, codici alternativi, listini, fornitori,
|
||||
sostitutivi, giacenze e movimenti, e la griglia dei listini (mockup 018) con modifica in cella e aggiornamento
|
||||
massivo. §11.3 fissa l'ordine di ricerca del prezzo di una riga (netto cliente-articolo, listino del cliente o del
|
||||
documento, listino base, prezzo dell'articolo) e dice che i listini hanno validità, possono essere derivati e hanno
|
||||
regole di arrotondamento. Restavano aperti: dove stanno i prezzi netti dei clienti, come convivono prezzi vecchi e
|
||||
nuovi, quale listino è "il base", come si calcola un listino derivato, che cosa vede chi non può vedere i costi, che
|
||||
cosa si fa delle giacenze prima del magazzino (M6).
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Una tabella di prezzi.** `item_prices` tiene sia i prezzi di listino (`price_list_id`) sia i **prezzi netti**
|
||||
di un cliente (`party_id`): una riga ha esattamente uno dei due. Ogni riga ha un `valid_from`; il prezzo in vigore
|
||||
a una data è quello con l'**inizio più recente non successivo** alla data (una riga senza data vale sempre).
|
||||
Scrivere un prezzo con una data nuova aggiunge una riga, così i documenti già fatti e quelli datati prima
|
||||
ritrovano il prezzo di allora; scriverlo con la stessa data cambia la riga, e "nessun prezzo" la toglie. Un prezzo
|
||||
uguale a quello già in vigore non si riscrive.
|
||||
2. **Listino base.** `price_lists.is_base` marca il listino base (al più uno, regola della tabella); in mancanza
|
||||
vale quello con codice `BASE`, che i dati di base creano già marcato. La migrazione marca il `BASE` esistente.
|
||||
3. **Listini derivati.** Un listino con `base_price_list_id` senza un proprio prezzo per l'articolo prende il prezzo
|
||||
del listino di partenza alla stessa data, applica `markup_percent` (anche negativo) e arrotonda a `rounding_step`
|
||||
(al centesimo se zero). Il prezzo scritto nel listino derivato vince su quello calcolato. La derivazione si segue
|
||||
per al più cinque livelli. Il calcolo è in `PriceBook`, che lavora in memoria sui prezzi letti una volta.
|
||||
4. **Ricerca del prezzo** (`PriceListService.QuoteAsync`, usata dai documenti da M5): netto del cliente, poi il
|
||||
listino del documento o del cliente se valido alla data, poi il listino base, poi `items.price`. La risposta dice
|
||||
la **fonte** (`PriceSource`), che la riga del documento conserva. Gli sconti 1 e 2 del cliente si propongono come
|
||||
formula a cascata (`10+5`), **mai su un prezzo netto**.
|
||||
5. **Griglia dei listini.** Legge e scrive tutti i prezzi a **una data di validità** scelta in alto (oggi di
|
||||
default). Le celle modificate e quelle calcolate dall'aggiornamento massivo restano in sospeso, evidenziate, finché
|
||||
non si salva; l'anteprima dell'aggiornamento massivo (`PreviewAsync`) non scrive nulla. Le celle dei listini
|
||||
derivati senza prezzo proprio sono in corsivo.
|
||||
6. **Costi.** Costo standard, ultimo costo e costo medio si vedono solo con `items.cost.read`; per gli altri il
|
||||
servizio li restituisce vuoti e al salvataggio conserva quelli in archivio. Ultimo costo e costo medio non si
|
||||
scrivono dalla scheda: li aggiornano i carichi di magazzino (M6); fino ad allora li valorizzano solo i dati di
|
||||
esempio. Il margine è sul prezzo: (prezzo - costo) / prezzo.
|
||||
7. **Tipi e magazzino.** Solo le merci possono essere *gestite a magazzino*; servizi, spese, righe descrittive e
|
||||
cespiti non lo sono mai (il servizio lo corregge). Giacenze, impegni, movimenti e proposta di riordino arrivano
|
||||
con il magazzino (M6): la scheda li annuncia, i campi di riordino si compilano già.
|
||||
8. **Codici.** Il codice segue la maschera `items` (`{categoria}-{seq:0000}`, ADR 0027); se la maschera usa la
|
||||
categoria, la categoria è obbligatoria. Il codice a barre principale e quelli delle UM alternative hanno la
|
||||
verifica EAN; un codice a barre già usato da un altro articolo è un avviso, o un errore se le preferenze chiedono
|
||||
codici a barre univoci. La ricerca degli articoli trova esattamente anche i **codici alternativi** e, nei
|
||||
documenti di un'anagrafica, i **codici che quell'anagrafica usa** (`party_item_codes`).
|
||||
9. **Codici dell'anagrafica.** `party_item_codes` si gestisce nella scheda *Articoli e codici* dell'anagrafica e si
|
||||
salva con essa (un codice non si ripete per la stessa anagrafica); i controlli sono di `ItemService`.
|
||||
10. **Cancellazione.** Un articolo usato (sostitutivo di un altro, in documenti da M5) si disattiva invece di
|
||||
cancellarsi, come le anagrafiche (ADR 0029). Un cliente con prezzi netti non si cancella.
|
||||
11. **Dati di esempio.** `DemoItemsSeeder` crea 120 articoli fittizi di un grossista termoidraulico (SPEC §14) in dieci
|
||||
categorie, due listini derivati dal base (*Pubblico* +45% arrotondato a 0,10, *Rivenditori* -10%), un prezzo
|
||||
dell'anno precedente per lo storico, prezzi netti e codici di Rossi Impianti, fornitori abituali, UM alternative,
|
||||
codici alternativi e sostitutivi. I codici a barre hanno prefisso 200, riservato all'uso interno. Il comando
|
||||
`seed --demo [--scale N]` esegue prima i dati di base e poi quelli di esempio, ripetendo il catalogo N volte.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- I documenti (M5) chiamano `PriceListService.QuoteAsync` dentro la propria unità di lavoro e salvano prezzo e fonte;
|
||||
la stessa logica serve l'API (`items`, `price-lists`) e il tool MCP `search_items`.
|
||||
- Cambiare un prezzo non tocca i documenti esistenti; per correggere un prezzo sbagliato si riscrive con la stessa
|
||||
data, per un aumento si usa una data nuova.
|
||||
- Il magazzino (M6) aggiornerà `last_cost` e `average_cost` e aggiungerà le schede *Giacenze* e *Movimenti*.
|
||||
@@ -0,0 +1,69 @@
|
||||
# ADR 0031 - Import e export guidato: entità, tracciati, controlli come da scheda
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-12
|
||||
- **Modifica:** SPEC §11.7, §12.12, mockup 077; milestone M4, issue #44
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §12.12 chiede una procedura guidata di import/export (CSV, XLSX, JSON) per anagrafiche, articoli, listini,
|
||||
giacenze iniziali, piano dei conti, saldi e partite di apertura, con mappatura delle colonne, validazione riga per
|
||||
riga, report degli errori e un tracciato proprio del piano dei conti (`codice;descrizione;livello;padre;natura;tipo;
|
||||
voce_cee;riclassifica;flag` e `khaemhat-coa.json`). Restavano aperti: dove sta la procedura, quali entità esistono già
|
||||
in M4, come si controllano le righe, che cosa succede ai codici esistenti o mancanti, i valori ammessi di `natura`,
|
||||
`tipo` e `flag`, come si legge un XLSX senza librerie esterne, chi può esportare.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Dove.** Pagina `/amministrazione/import-export` (voce *Import / export dati* sotto *Amministrazione*, visibile
|
||||
agli account di istanza), consegnata in M4 prima del resto dell'area (M13). Una persona dell'azienda la apre se ha
|
||||
il permesso di scrittura o di export di almeno un'entità.
|
||||
2. **Entità.** `IImportTarget` descrive un'entità: chiave, modulo di licenza, permesso di import e di export, colonne
|
||||
(con alias per l'abbinamento automatico), verifica, scrittura ed export. In M4: `clienti`, `fornitori`,
|
||||
`articoli`, `listini` (prezzi di listino e netti cliente), `giacenze-iniziali`, `piano-dei-conti`. Le ultime due
|
||||
**si verificano soltanto** finché non esistono i movimenti di magazzino (M6) e la contabilità (M7): la procedura
|
||||
prepara il file in anticipo, la scrittura arriva con il modulo. Saldi e partite di apertura arrivano con M7 e M9.
|
||||
3. **Le righe passano dalla scheda.** Clienti, fornitori e articoli si leggono per codice (o si creano con i valori
|
||||
proposti dalla scheda), si riempiono con le celle **non vuote** della riga e si controllano e salvano con
|
||||
`PartyService` e `ItemService`: stesse regole, stessi codici di errore, stesso storico. Una cella vuota lascia il
|
||||
valore che c'è. I codici di altre tabelle (categoria, pagamento, listino, agente, UM, IVA, deposito) devono
|
||||
esistere. I prezzi si scrivono con `PriceListService` in una sola transazione (stessa voce e stessa data:
|
||||
sostituisce; data nuova: aggiunge, come la griglia dei listini, ADR 0030).
|
||||
4. **Opzioni.** *Se il codice esiste*: aggiorna (predefinito) o salta la riga (avviso). *Codice mancante*: genera con
|
||||
le regole dei codici automatici (ADR 0027) o errore. Un codice scritto per un record nuovo rispetta la regola
|
||||
(*codice manuale ammesso*). Un codice ripetuto nel file è un errore dalla seconda riga; un codice di un'anagrafica di
|
||||
altro tipo è un errore. *Verifica P.IVA su VIES* chiama VIES durante l'import (spento: nessuna chiamata, qualunque
|
||||
sia l'opzione automatica dell'azienda). *Completa comune da CAP* propone comune e provincia da un CAP con un solo
|
||||
comune, o il CAP da un comune con un solo CAP, come avviso.
|
||||
5. **Esiti.** Ogni riga ha *OK*, *avviso* (importabile) o *errore* (esclusa), con colonna, codice del testo e valore.
|
||||
Si importano solo le righe senza errori; le altre finiscono nel **report errori** (CSV con riga, codice, colonna,
|
||||
esito, messaggio). L'esito dell'import va nel log, sezione *Sistema*.
|
||||
6. **Valori.** Numeri all'italiana (`1.234,56`) o con il punto decimale (`1234.56`, come li scrivono XLSX e JSON);
|
||||
date `gg/mm/aaaa`, ISO, `aaaammgg` o numero seriale del foglio; sì/no come `sì`, `x`, `1`, `VERO`, `true` e i
|
||||
contrari; le parole di una scelta senza badare a maiuscole, accenti e punteggiatura.
|
||||
7. **Piano dei conti.** Codice di 1-3 parti separate da punto (mastro, conto, sottoconto); `livello` è il numero di
|
||||
parti; `padre` è il codice senza l'ultima parte e deve essere nel file; la `natura` (`attivo`, `passivo`, `costo`,
|
||||
`ricavo`, `ordine`) si eredita dal padre e non può essere diversa; `tipo` è `generico`, `clienti`, `fornitori`,
|
||||
`banca`, `cassa`, `iva`, `erario` (nuovo `AccountType` in `Khaemhat.Core.Accounting`); `flag` è un insieme di lettere:
|
||||
`M` movimentabile (solo conti senza sottoconti), `I` rilevante IVA, `P` con partitario, `C` chiusura automatica,
|
||||
`X` disattivato. `khaemhat-coa.json` è un oggetto `{format, version, accounts, statementLines, journalTemplates,
|
||||
mappings}`: `accounts` ha le stesse colonne, le altre sezioni si contano e si importano in M7. Il controllo è puro
|
||||
(`ChartOfAccountsImportValidator`) perché M7 scriva esattamente ciò che accetta.
|
||||
8. **File.** CSV in UTF-8 (con o senza BOM) o, se non è UTF-8 valido, Windows-1252; separatore `;`, `,` o tabulazione
|
||||
dedotto dall'intestazione; l'apostrofo che l'export mette davanti al testo che inizia con `=`, `+`, `-`, `@` si
|
||||
toglie. XLSX: primo foglio letto da `XlsxReader` (System.IO.Compression e XmlReader, DTD vietate, stringhe
|
||||
condivise, celle in linea, numeri formattati come data restituiti come data). JSON: elenco di oggetti. Al più
|
||||
50.000 righe e 25 MB.
|
||||
9. **Export e modelli.** L'export scrive le stesse colonne dell'import in CSV (`;`, UTF-8 con BOM, numeri e date
|
||||
all'italiana), XLSX o JSON, così il file si corregge e si reimporta; richiede il permesso di export dell'entità e
|
||||
il flag utente *Può esportare dati*. Il **modello** è il file con le sole intestazioni (in JSON un oggetto con i
|
||||
valori vuoti).
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- L'import non ha regole proprie: ogni regola nuova di una scheda vale subito anche per i file.
|
||||
- Un file di un altro gestionale con codici propri richiede che la regola dei codici ammetta il codice manuale.
|
||||
- M6 e M7 aggiungono la scrittura di giacenze e piano dei conti senza cambiare tracciati né controlli; M7 e M9
|
||||
aggiungono saldi e partite come nuove entità.
|
||||
- Le righe si scrivono una alla volta (anagrafiche e articoli): un errore a metà non annulla le righe già scritte,
|
||||
che il report indica come create o aggiornate.
|
||||
@@ -0,0 +1,65 @@
|
||||
# ADR 0032 - Motore documenti: comportamento per genere, tabelle per famiglia, numerazione alla conferma
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-12
|
||||
- **Modifica:** SPEC §11.3; milestone M5, issue #47
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §11.3 vuole un solo motore per tutti i documenti (vendita, acquisto, magazzino), guidato da definizioni
|
||||
dichiarative, con tabelle per famiglia (`sale_quotations`, `sale_orders`, `sale_documents`, `purchase_orders`,
|
||||
`purchase_documents`, `inventory_documents`, ognuna con le righe), `document_links` per l'evasione, gli stati
|
||||
`Draft → Confirmed → (PartiallyFulfilled | Fulfilled) → Closed`, `Cancelled` e per le fatture
|
||||
`Draft → Issued → SdiGenerated → SdiSent → (SdiDelivered | SdiRejected | SdiNotDelivered)`, la numerazione alla
|
||||
conferma con la data non anteriore all'ultimo numero del sezionale. Restavano aperti: dove sta il comportamento di un
|
||||
tipo documento (la tabella `document_types` è modificabile dall'utente e il suo `kind` dice solo la famiglia di
|
||||
numerazione), come si numera per anno quando il numeratore è per anno, quando nasce un legame di evasione, che cosa
|
||||
fa la copia, quali tabelle servono già adesso.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Genere e definizione.** Il comportamento sta in codice, per **genere** (`DocumentKind`: preventivo, ordine
|
||||
cliente, DDT, fattura immediata, accompagnatoria, differita, di acconto, nota di credito, nota di debito, parcella,
|
||||
pro forma, autofattura, ordine fornitore, DDT fornitore, fattura fornitore, nota di credito fornitore, movimento di
|
||||
magazzino). `DocumentBehaviors` dà per ogni genere: famiglia (tabella), direzione, ciclo di vita, effetti
|
||||
(magazzino, impegnato, ordinato, contabilità, scadenze, e-fattura), tipi di riga ammessi, generi da cui evade
|
||||
(sorgenti) e permessi. La tabella `document_types` riceve la colonna `document_kind`: ogni tipo dell'utente
|
||||
sceglie un genere e aggiunge numeratore, causale di magazzino, TD SDI, causale contabile, registro IVA, modello di
|
||||
stampa. `DocumentDefinition` è l'unione dei due (tipo + comportamento) e si legge con `DocumentDefinitionService`.
|
||||
I tipi seminati prendono il genere dalla migrazione e dal modello del pacchetto paese.
|
||||
2. **Tre cicli di vita.** `DocumentStateMachine` conosce tre cicli: *ordine* (preventivi, ordini, DDT, pro forma:
|
||||
bozza, confermato, evaso parzialmente, evaso, chiuso, annullato), *fattura* (fatture e autofatture di vendita:
|
||||
bozza, emessa, XML generato, inviata, consegnata, scartata, non consegnata, annullata) e *semplice* (fatture
|
||||
fornitore, movimenti: bozza, confermato, annullato). Per ogni stato dice le azioni ammesse; un'azione non ammessa
|
||||
è rifiutata con `document.action.not-allowed`. Si modifica solo una bozza, oltre a ordini e preventivi confermati
|
||||
non evasi; la fattura emessa è immutabile: si annulla con un motivo finché l'XML non è inviato (o se scartato),
|
||||
altrimenti si fa una nota di credito. Gli stati di evasione non sono azioni: li calcola `FulfillmentCalculator`.
|
||||
3. **Numerazione alla conferma.** `DocumentNumberingService` numera nella stessa transazione della conferma, sotto il
|
||||
lock `numerator:<codice>:<anno>` (advisory lock di transazione su PostgreSQL, lock di scrittura su SQLite): un
|
||||
rollback restituisce il numero, quindi non nascono buchi. Il numeratore del tipo vale per il suo codice; per
|
||||
l'anno della data si usa la riga (codice, anno) e, se manca, si crea copiando formato, prefisso e sezionale
|
||||
dell'ultima. Sui numeratori **senza buchi** (fatture, autofatture, protocollo acquisti) la data non può
|
||||
precedere l'ultima numerata (`document_numerators.last_date`) e la conferma chiede il periodo aperto quando il
|
||||
genere ha effetto contabile. `FindGapsAsync` elenca i numeri mancanti di un numeratore. Un documento numerato non
|
||||
si elimina: si annulla e il numero resta.
|
||||
4. **Tabelle.** Sei testate e sei tabelle di righe con le stesse colonne (classi base `DocumentHeader` e
|
||||
`DocumentLine`), più `document_links` (riga destinazione → riga sorgente, quantità). Le tabelle del castelletto IVA
|
||||
e delle rate arrivano con il calcolo dei totali (#48), i campi di trasporto sono già nella testata.
|
||||
5. **Evasione.** Una riga copiata da un documento evadibile tiene la riga d'origine (`source_family`,
|
||||
`source_line_id`). Il legame in `document_links` nasce alla **conferma** del documento destinazione e sparisce al
|
||||
suo annullamento; dopo ogni cambio `FulfillmentCalculator` ricalcola la quantità evasa delle righe sorgente e lo
|
||||
stato del documento sorgente (confermato, evaso parzialmente, evaso). Le righe con saldo forzato contano come
|
||||
evase; un documento chiuso o annullato non cambia stato.
|
||||
6. **Copia.** `DocumentCopyService` crea una bozza da un documento esistente verso lo stesso tipo (duplicazione) o un
|
||||
altro della stessa direzione (trasformazione). Se il genere destinazione evade il genere sorgente si copiano le
|
||||
quantità residue e le righe tengono l'origine, altrimenti si copiano le quantità intere senza legame.
|
||||
7. **Servizio generico.** `DocumentService<THeader, TLine>` (uno per famiglia) espone crea, leggi, salva, conferma,
|
||||
annulla, chiudi, riapri, elimina e copia; il lavoro su più famiglie (evasione, copia) passa da `DocumentEngine`, che
|
||||
tratta testate e righe tramite le classi base.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Un tipo documento nuovo dell'utente funziona senza codice se usa un genere esistente; un genere nuovo è codice.
|
||||
- Gli effetti sono dichiarati ma si applicano con i moduli: magazzino in M6, contabilità in M7, scadenze in M8,
|
||||
e-fattura in M8. Il calcolo dei totali e delle rate è #48, le maschere sono #49-#51.
|
||||
- La numerazione concorrente è provata su SQLite e PostgreSQL (test dei dati, eseguiti su PostgreSQL 16 e 17 ai tag).
|
||||
@@ -0,0 +1,55 @@
|
||||
# ADR 0033 - Totali, castelletto IVA e scadenze dei documenti
|
||||
|
||||
- **Stato:** accettata
|
||||
- **Data:** 2026-11-12
|
||||
- **Modifica:** SPEC §11.3; milestone M5, issue #48
|
||||
|
||||
## Contesto
|
||||
|
||||
SPEC §11.3 chiede un `DocumentTotalsCalculator` (imponibile di riga, sconti a cascata, castelletto per codice IVA,
|
||||
spese, sconto di piede, bollo, ritenuta, cassa previdenza, split payment, reverse charge, IVA per cassa) e un
|
||||
`InstallmentGenerator` (fine mese, giorno fisso, percentuali, IVA sulla prima rata, arrotondamento sull'ultima), con
|
||||
tabelle `_tax_summary` e `_installments` per ogni famiglia. Restavano aperti: dove si applica lo sconto di piede,
|
||||
come si gestiscono i prezzi IVA compresa, che cosa entra nella base della ritenuta e della cassa, dove si salvano
|
||||
castelletto e scadenze, quando si ricalcolano.
|
||||
|
||||
## Decisione
|
||||
|
||||
1. **Calcolo puro.** `DocumentTotalsCalculator` e `InstallmentGenerator` sono funzioni senza database, provate con
|
||||
casi numerici di riferimento. L'arrotondamento e il bollo vengono da `ITaxEngine` del pacchetto paese.
|
||||
2. **Riga.** Importo = quantità × prezzo × (1 − s1)(1 − s2)…, al centesimo con metà lontano da zero. Spese e sconti
|
||||
senza quantità valgono una volta; le righe di sconto sono negative; le righe descrittive non contano.
|
||||
3. **Sconto di piede** (formula come `10+5`): si applica a ogni riga di merce, non alle spese, e solo nel castelletto.
|
||||
La riga conserva il suo importo, il documento registra quanto lo sconto ha tolto (`footer_discount_amount`).
|
||||
4. **Castelletto** per codice IVA, con l'imposta calcolata sul totale del gruppo (come `DatiRiepilogo`). Con i
|
||||
**prezzi IVA compresa** si somma il lordo del gruppo e si scorpora una volta sola. L'esigibilità è quella del
|
||||
codice IVA, del documento (IVA per cassa) o *S* con lo **split payment**. Il reverse charge non ha bisogno di
|
||||
regole: i codici N6.x hanno aliquota zero.
|
||||
5. **Cassa previdenza, ritenuta, ENASARCO.** La base è la somma delle righe non escluse
|
||||
(`withholding_excluded`, ad esempio le spese anticipate in nome del cliente), dopo lo sconto di piede. La cassa
|
||||
entra nel castelletto con l'IVA indicata o con quella della prima riga imponibile; la ritenuta si calcola sulla
|
||||
quota della base (100% per i professionisti, 50% o 20% per gli agenti), con la cassa se è soggetta. Ritenuta,
|
||||
ENASARCO e IVA in split payment si tolgono dal **netto a pagare**, non dal totale.
|
||||
6. **Bollo** sulle fatture e note di vendita quando gli importi senza IVA che lo richiedono superano la soglia del
|
||||
pacchetto paese (77,47 euro): è sempre indicato; entra nel totale solo se addebitato al cliente.
|
||||
7. **Scadenze** dal netto a pagare e dalle rate della condizione di pagamento; con *IVA sulla prima rata* l'IVA
|
||||
effettivamente incassata va tutta sulla prima. Fine mese e giorno fisso: con fine mese il giorno fisso è del mese
|
||||
successivo, senza fine mese è il primo giorno fisso non anteriore. I **mesi esclusi** stanno nelle condizioni di
|
||||
vendita del cliente e spostano la scadenza a un giorno del mese successivo (10 se non indicato). Le scadenze
|
||||
esistono per fatture, note, fatture fornitore e, come previsione, per preventivi, ordini e pro forma.
|
||||
8. **Due tabelle condivise invece di dodici.** Castelletto e scadenze stanno in `document_tax_summaries` e
|
||||
`document_installments` con la colonna `family`, come `document_links`: le righe non hanno vincoli verso una
|
||||
sola tabella e il codice resta unico per tutte le famiglie. Diverge dalla lettera di §11.3 (una coppia di tabelle
|
||||
per famiglia), non dalla sostanza.
|
||||
9. **Quando.** Il motore ricalcola a ogni salvataggio (bozze e righe di documenti ancora aperti) e riscrive
|
||||
castelletto e scadenze nella stessa transazione. Un documento emesso non cambia più, quindi i suoi totali restano
|
||||
quelli dell'emissione. Lo scadenzario vero (partite, incassi) arriva con M8 e parte da queste righe.
|
||||
10. **Revisioni dei preventivi.** Modificare un preventivo confermato aumenta il numero di revisione: il numero
|
||||
del documento resta lo stesso.
|
||||
|
||||
## Conseguenze
|
||||
|
||||
- Le maschere mostrano castelletto, totali e scadenze ricalcolati durante la modifica con lo stesso codice del
|
||||
salvataggio (anteprima senza scrittura).
|
||||
- Il file FatturaPA (M9) troverà lo sconto di piede da ripartire sulle righe e il castelletto già pronto.
|
||||
- Lo sconto cassa resta fuori: si gestirà con gli incassi (M8).
|
||||
@@ -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,7 +1,7 @@
|
||||
# Allegati e file
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M3, completata in M5)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** `attachments.delete`, permessi di lettura del documento · **Specifica:** SPEC §9.4
|
||||
> **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
|
||||
foto, un foglio di calcolo) e file **generati** da Khaemhat (PDF di stampa, XML FatturaPA, esportazioni, pacchetti
|
||||
@@ -12,9 +12,17 @@ ZIP). Gli allegati sono archiviati sul volume dei dati dell'istanza, con version
|
||||
Da qualunque documento: icona **Allegati** nella toolbar (con il numero degli allegati) oppure scheda **Allegati (n)**.
|
||||
Si apre il pannello laterale **Allegati e file generati**.
|
||||
|
||||
> **In questa versione** i documenti veri arrivano con le vendite (M5): pannello, anteprime e anteprima di stampa si
|
||||
> provano sul **documento di prova** degli sviluppatori (dal catalogo dei componenti `/sviluppo/componenti`,
|
||||
> solo in ambiente di sviluppo), che ha
|
||||
> tre file generabili (PDF, righe in CSV, righe in Excel). Mancano ancora **Invia** per e-mail e **Da scanner / foto**.
|
||||
|
||||

|
||||
*Mockup 024 — pannello laterale sopra la fattura: elenco degli allegati con azioni, Carica file, Da scanner / foto, Scarica tutto (ZIP) e sezione Genera file (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la scheda Allegati del documento di prova: tre file generati con le loro versioni, Carica file, Scarica tutto (ZIP) e Genera file.*
|
||||
|
||||
## Regole di base
|
||||
|
||||
- Un allegato appartiene **a un solo documento** (o a una sola anagrafica). Non esistono allegati "sciolti": se lo
|
||||
@@ -42,10 +50,12 @@ caricato o generato e quando, dimensione, versione, eventuale modello usato.
|
||||
|---|---|
|
||||
| occhio | **Anteprima** in app |
|
||||
| freccia in giù | **Scarica** |
|
||||
| busta | **Invia** per e-mail |
|
||||
| frecce circolari | **Rigenera**: crea una nuova versione del file generato |
|
||||
| cestino | **Elimina** (solo file non bloccati e con permesso) |
|
||||
| lucchetto | il file è bloccato |
|
||||
| busta | **Invia** per e-mail (con le vendite) |
|
||||
| frecce circolari | **Rigenera** (nella sezione *Genera file*): crea una nuova versione del file generato |
|
||||
| lucchetto | **Blocca**: da quel momento il file non si può più eliminare; accanto al nome indica un file bloccato |
|
||||
| cestino | **Sposta nel cestino** (solo file non bloccati e con permesso), dopo una conferma |
|
||||
|
||||
La casella **Versioni precedenti** mostra anche le versioni superate dei file generati (`v1` quando c'è già `v2`).
|
||||
|
||||
In fondo all'elenco:
|
||||
|
||||
@@ -69,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.
|
||||
@@ -79,19 +94,41 @@ Il pannello apre in app l'anteprima di:
|
||||
|
||||
| Formato | Come si vede |
|
||||
|---|---|
|
||||
| PDF | visualizzatore integrato |
|
||||
| Immagini | a dimensione piena con zoom |
|
||||
| XML | testo formattato e indentato |
|
||||
| CSV, XLSX | griglia |
|
||||
| PDF | visualizzatore PDF del browser, dentro la finestra di anteprima |
|
||||
| Immagini (JPEG, PNG, GIF, WebP) | adattate alla finestra |
|
||||
| XML, testo | testo così com'è |
|
||||
| CSV, XLSX | griglia (il primo foglio per gli XLSX) |
|
||||
|
||||
Gli altri formati si scaricano. Per i documenti c'è anche l'**anteprima di stampa** (`Ctrl+P`, mockup 025), descritta
|
||||
in [Vendite](Vendite).
|
||||

|
||||
*Khaemhat 0.3.0 — l'anteprima di un file Excel generato: il primo foglio come griglia.*
|
||||
|
||||
Dei file lunghi l'anteprima mostra l'inizio (200 righe, 200.000 caratteri) e lo dice. Gli altri formati si scaricano;
|
||||
PDF e immagini si aprono anche in una nuova finestra del browser.
|
||||
|
||||
### Anteprima di stampa
|
||||
|
||||

|
||||
*Mockup 025 — anteprima di stampa di una fattura in formato A4 (anteprima ridotta).*
|
||||
|
||||
`Ctrl+P` o l'icona **Stampa** del documento aprono in una scheda l'**anteprima di stampa**: il documento come foglio
|
||||
A4, con ingrandimento al 75, 100 o 125%. In alto:
|
||||
|
||||
- **Stampa** — la stampa del browser, che stampa solo il foglio (non menu e barre);
|
||||
- **Apri PDF** e **Scarica PDF** — il PDF prodotto da Khaemhat, senza salvarlo fra gli allegati;
|
||||
- **Salva come allegato** — salva il PDF fra gli allegati del documento come nuova versione.
|
||||
|
||||
Modello di stampa, copie e lingua arrivano con i documenti di vendita ([Vendite](Vendite)).
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — l'anteprima di stampa del documento di prova, con Stampa, Apri PDF, Scarica PDF, Salva come allegato e l'ingrandimento.*
|
||||
|
||||
## Cestino
|
||||
|
||||
Quando un documento viene cancellato, i suoi allegati non spariscono subito: restano nel **cestino dell'azienda per
|
||||
30 giorni** e possono essere recuperati in quel periodo; poi vengono eliminati definitivamente. La maschera di
|
||||
consultazione del cestino sarà definita in sviluppo.
|
||||
Quando un allegato viene spostato nel cestino, o quando viene cancellato il suo documento, il file non sparisce
|
||||
subito: resta nel **cestino dell'azienda per 30 giorni** e poi viene eliminato definitivamente da un'attività
|
||||
programmata. In fondo al pannello degli allegati, la sezione **Nel cestino** elenca i file del documento
|
||||
che sono nel cestino, con la data in cui saranno eliminati e il pulsante **Ripristina** (serve
|
||||
`attachments.delete`).
|
||||
|
||||
## Limiti e archiviazione
|
||||
|
||||
@@ -119,8 +156,10 @@ consultazione del cestino sarà definita in sviluppo.
|
||||
|
||||
## Permessi e licenza
|
||||
|
||||
Gli allegati sono nel modulo **CORE**. Chi può leggere un documento ne vede gli allegati; caricare richiede il
|
||||
permesso di modifica del documento; cancellare richiede `attachments.delete`. Gli allegati sono raggiungibili anche
|
||||
Gli allegati sono nel modulo **CORE**. Vedere e scaricare richiede `attachments.read`; caricare, generare e bloccare
|
||||
richiede `attachments.write`; spostare nel cestino e ripristinare richiede `attachments.delete`. Un utente aziendale
|
||||
vede solo gli allegati della propria azienda. I file si scaricano solo dopo l'accesso: un indirizzo copiato non
|
||||
funziona per chi non è collegato. Gli allegati sono raggiungibili anche
|
||||
dalle API (download e caricamento su un documento, modulo API; vedi [API e MCP](API-e-MCP)).
|
||||
|
||||
## Domande frequenti
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Anagrafiche
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** famiglia `parties.*` (`read`, `write`, `delete`, `export`; codici esatti definiti in sviluppo) · **Specifica:** SPEC §11.2, §11.12, §22
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.4.0 (milestone M4)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** `parties.party.read` (consultare), `parties.party.write` (inserire, modificare, disattivare, convertire), `parties.party.delete` (eliminare) · **Specifica:** SPEC §11.2, §11.12, §22 · **Decisioni:** ADR 0029
|
||||
|
||||
Le **anagrafiche** sono l'archivio unico delle controparti dell'azienda: **clienti**, **fornitori**, **prospect** e
|
||||
**lead**. Un soggetto è registrato una volta sola; il suo *tipo* (cliente, fornitore…) dice come viene usato. Dalla
|
||||
@@ -10,8 +10,9 @@ codici che il cliente o il fornitore usa per i tuoi articoli.
|
||||
|
||||
## Dove si trova
|
||||
|
||||
Menu **Anagrafiche** → **Clienti**, **Fornitori**, **Contatti** (prospect e lead), **Categorie**. Nello stesso menu ci
|
||||
sono anche *Articoli* e *Listini* (vedi [Articoli e listini](Articoli-e-listini)).
|
||||
Menu **Anagrafiche** → **Clienti** (`/anagrafiche/clienti`), **Fornitori** (`/anagrafiche/fornitori`), **Contatti**
|
||||
(`/anagrafiche/contatti`, prospect e lead). Le categorie sono una tabella azienda (vedi [Tabelle azienda](Tabelle-azienda)).
|
||||
Nello stesso menu arriveranno *Articoli* e *Listini* (vedi [Articoli e listini](Articoli-e-listini)).
|
||||
|
||||
## Tipi di anagrafica
|
||||
|
||||
@@ -19,13 +20,15 @@ sono anche *Articoli* e *Listini* (vedi [Articoli e listini](Articoli-e-listini)
|
||||
|---|---|---|
|
||||
| **Cliente** | intestatario di preventivi, ordini, DDT e fatture di vendita | `C{seq:000000}` → `C000124` |
|
||||
| **Fornitore** | intestatario di ordini fornitore, DDT di carico, fatture di acquisto | `F{seq:000000}` → `F000032` |
|
||||
| **Prospect** | potenziale cliente già qualificato, senza documenti fiscali | assegnato alla conversione in cliente |
|
||||
| **Prospect** | potenziale cliente già qualificato, senza documenti fiscali | come i lead; alla conversione riceve il codice cliente |
|
||||
| **Lead** | contatto commerciale da qualificare (gestito con il CRM) | `L{anno}-{seq:0000}` → `L2026-0001` |
|
||||
|
||||
Lo stesso soggetto può essere sia cliente sia fornitore.
|
||||
Lo stesso soggetto può essere sia cliente sia fornitore: è un **cliente** con la casella *È anche fornitore* e compare
|
||||
in entrambi gli elenchi con lo stesso codice.
|
||||
|
||||
Il **tipo soggetto** (*azienda*, *privato*, *pubblica amministrazione*, *UE*, *extra-UE*, *forfettario*) determina
|
||||
i controlli e i valori proposti: codice destinatario SDI, split payment, bollo, partita IVA estera.
|
||||
Il **tipo soggetto** (*impresa italiana*, *privato*, *pubblica amministrazione*, *impresa UE*, *impresa extra-UE*,
|
||||
*forfettario*) determina i controlli e i valori proposti: codice destinatario SDI, split payment, partita IVA estera,
|
||||
paese della sede.
|
||||
|
||||
## Radar dei clienti
|
||||
|
||||
@@ -35,55 +38,68 @@ i controlli e i valori proposti: codice destinatario SDI, split payment, bollo,
|
||||

|
||||
*Mockup 012 — lo stesso radar con il menu espanso (anteprima ridotta).*
|
||||
|
||||
Il radar elenca le anagrafiche con le colonne **Codice**, **Ragione sociale**, **P.IVA / C.F.**, **Città**,
|
||||
**Pagamento**, **Listino**, **Agente**, **Fatturato** dell'anno, **Scaduto** (in rosso se presente) e **Stato**. Lo
|
||||
stato è un badge: *Attivo*, *Disabilitato*, *PA · split*, *UE*, *Extra-UE*, *Privato*, *Fido superato*.
|
||||

|
||||
*Khaemhat 0.4.0 — il radar dei clienti di esempio con i filtri Soggetto, Agente e Stato e lo stato di ogni anagrafica (impresa UE, PA con split payment, privato, bloccato, anche fornitore). Fatturato e scaduto arrivano con vendite e scadenzario.*
|
||||
|
||||
- Filtri: ricerca libera, **Tipo**, **Agente**, **Stato**, più filtri aggiunti come chip (ad esempio *Scaduto > 0*,
|
||||
*Provincia: CN, TO, AT*).
|
||||
- Il piede mostra i totali della selezione (ad esempio *1.284 clienti · 12 selezionati · fatturato visibile*).
|
||||
- Tasti: `F9` radar, `Invio` apri, `Spazio` seleziona. Con più righe selezionate si possono usare le azioni
|
||||
multiple (stampa, e-mail, esporta, **Disabilita**).
|
||||
Il radar elenca le anagrafiche con le colonne **Codice**, **Ragione sociale**, **P.IVA / C.F.**, **Città** (con la
|
||||
provincia), **Pagamento**, **Listino** (solo clienti), **Agente** e **Stato**; nei *Contatti* al posto di pagamento e
|
||||
listino c'è il **Tipo** (prospect o lead). Lo stato è un badge: *Attivo*, *Disattivato*, *Bloccato*, *PA · split*,
|
||||
*Privato*, *Impresa UE*, *Impresa extra-UE*, *Anche fornitore* / *Anche cliente*. Le colonne **Fatturato** e
|
||||
**Scaduto** del mockup arrivano con le vendite (M5) e lo scadenzario (M9).
|
||||
|
||||
- Ricerca libera su codice, nome, partita IVA, codice fiscale e città.
|
||||
- Filtri rapidi: **Tipo** (solo contatti), **Soggetto**, **Agente**, **Stato**; all'apertura sono mostrate solo le
|
||||
anagrafiche attive.
|
||||
- Tasti: `F9` radar, `Invio` o doppio clic apre la scheda, `Spazio` seleziona. Con più righe selezionate si usano
|
||||
**Disattiva** e **Riattiva**; l'esportazione CSV/XLSX è quella di tutti i radar.
|
||||
|
||||
## La scheda anagrafica
|
||||
|
||||

|
||||
*Mockup 014 — scheda cliente: azioni Scheda 360°, Nuovo documento, VIES, Attività CRM; intestazione con identità, condizioni e fatturato; scheda Dati principali a gruppi (anteprima ridotta).*
|
||||
|
||||
**Toolbar**: comandi standard a icone (vedi [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie)) e le azioni
|
||||
contestuali **Scheda 360°** (visione completa: documenti, partite, attività CRM), **Nuovo documento**, **VIES**
|
||||
(verifica della partita IVA comunitaria), **Attività CRM**.
|
||||

|
||||
*Khaemhat 0.4.0 — la scheda di un cliente di esempio: intestazione con condizioni e agente, schede con i contatori e gruppi Identità, Sede legale, Recapiti, Classificazione e consensi.*
|
||||
|
||||
**Intestazione** in tre blocchi: a sinistra tipo (*Cliente*), codice e nome, stato (*Attivo*), uso del fido, data
|
||||
di inizio rapporto, agente; al centro ragione sociale con P.IVA, indirizzo, contatti e i chip delle condizioni
|
||||
(pagamento, listino e sconto, codice SDI, dichiarazione d'intento, scaduto); a destra il **fatturato** dell'anno con
|
||||
anno precedente, aperto e fido.
|
||||
**Toolbar**: comandi standard a icone (vedi [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie)) e le azioni
|
||||
contestuali **Verifica VIES** (partita IVA comunitaria) e, per prospect, lead e fornitori, **Converti in cliente**;
|
||||
nel menu `…` **Disattiva** o **Riattiva**. *Scheda 360°*, *Nuovo documento* e *Attività CRM* arrivano con vendite e
|
||||
CRM.
|
||||
|
||||
**Intestazione**: tipo, codice e nome, stato, data di inizio rapporto e agente; i chip delle condizioni (pagamento,
|
||||
listino, agente, esito VIES, split payment). Il blocco del **fatturato** arriva con le vendite (M5).
|
||||
|
||||
**Schede**:
|
||||
|
||||
| Scheda | Contenuto |
|
||||
|---|---|
|
||||
| **Dati principali** | gruppi *Identità*, *Sede legale*, *Classificazione e note* |
|
||||
| **Indirizzi** | destinazioni diverse (cantieri, sedi di consegna, indirizzo di fatturazione) |
|
||||
| **Contatti** | persone di riferimento con ruolo, telefono, e-mail |
|
||||
| **Condizioni commerciali** | condizioni di vendita (clienti) o di acquisto (fornitori) |
|
||||
| **Fiscale e SDI** | fatturazione elettronica, regime IVA, ritenute, dichiarazione d'intento, identificativi |
|
||||
| **Banche** | conti correnti della controparte (IBAN) |
|
||||
| **Articoli e codici** | codici con cui la controparte identifica i tuoi articoli |
|
||||
| **Dati principali** | gruppi *Identità*, *Dati di nascita* (privati), *Sede legale*, *Recapiti*, *Classificazione e consensi* |
|
||||
| **Indirizzi** | destinazioni diverse (destinazione merce, fatturazione, cantiere o sede operativa), una predefinita per tipo |
|
||||
| **Contatti** | persone di riferimento con ruolo, telefono, cellulare, e-mail; un contatto principale |
|
||||
| **Condizioni** | condizioni di vendita (clienti), di acquisto (fornitori, e clienti che sono anche fornitori), conti contabili |
|
||||
| **Fiscale e SDI** | fatturazione elettronica, regime IVA, ritenute e casse, dichiarazione d'intento, identificativi |
|
||||
| **Banche** | conti correnti della controparte (IBAN), uno predefinito |
|
||||
| **Articoli e codici** | i codici con cui il cliente o il fornitore identifica i tuoi articoli: codice, articolo (ricerca F4), descrizione; nei documenti di quell'anagrafica la ricerca degli articoli trova anche questi codici (vedi [Articoli e listini](Articoli-e-listini)) |
|
||||
| **Note e allegati** | note libere e file allegati all'anagrafica |
|
||||
| **CRM** | lead, opportunità e attività collegate (con modulo CRM) |
|
||||
| **Storico** | modifiche registrate: chi, quando, cosa |
|
||||
|
||||
Una scheda con errori mostra il numero degli errori nell'etichetta; le liste mostrano quante righe contengono. La
|
||||
scheda *CRM* arriva con il modulo CRM. Nella scheda *Articoli e codici* lo stesso codice non si ripete per la stessa
|
||||
anagrafica.
|
||||
|
||||
### Dati principali
|
||||
|
||||
| Gruppo | Campi |
|
||||
|---|---|
|
||||
| **Identità** | Codice (automatico), Tipo, Tipo soggetto, **Ragione sociale** *, Denominazione fiscale, **Partita IVA** *, Codice fiscale, REA, Categoria |
|
||||
| **Sede legale** | Indirizzo, N., CAP, Comune, Provincia, Paese, Telefono, E-mail, PEC, Sito |
|
||||
| **Classificazione e note** | Agente, Lingua, Valuta, Attivo, Privacy accettata, Marketing, Note |
|
||||
| **Identità** | Codice (automatico), Codice precedente, Tipo, Tipo soggetto, **Ragione sociale** *, Denominazione per i documenti, **Partita IVA** *, Codice fiscale, REA, Categoria |
|
||||
| **Dati di nascita** | Data, Sesso, Comune di nascita (codice catastale) |
|
||||
| **Sede legale** | Indirizzo, Civico, CAP, Comune, Provincia, Paese |
|
||||
| **Recapiti** | Telefono, Cellulare, E-mail, PEC, Sito web |
|
||||
| **Classificazione e consensi** | Agente, Lingua, Valuta, In anagrafica dal, Informativa privacy accettata, Consenso al marketing |
|
||||
|
||||
Per i privati si inseriscono nome e cognome al posto della ragione sociale. Digitando il **CAP** Khaemhat propone
|
||||
comune, provincia e regione; il **codice fiscale** di una persona fisica può essere calcolato dai dati anagrafici.
|
||||
Per i privati si inseriscono cognome e nome al posto della ragione sociale. Digitando il **CAP** Khaemhat propone
|
||||
comune e provincia (se il CAP è di più comuni li elenca e si sceglie); digitando il comune propone il CAP. Il
|
||||
**codice fiscale** di un privato si calcola con il pulsante accanto al campo da cognome, nome e dati di nascita.
|
||||
|
||||
### Fiscale e SDI
|
||||
|
||||
@@ -93,7 +109,8 @@ comune, provincia e regione; il **codice fiscale** di una persona fisica può es
|
||||
| Gruppo | Campi |
|
||||
|---|---|
|
||||
| **Fatturazione elettronica** | **Codice destinatario** *, PEC destinatario, tipo destinatario, formato (FPR12 privati / FPA12 PA), riferimento amministrazione, *Allega PDF di cortesia*, *Invia copia via e-mail all'emissione* |
|
||||
| **Regime IVA e ritenute** | *Split payment* (art. 17-ter), *Reverse charge* predefinito, codice IVA predefinito, esigibilità, *Soggetto a ritenuta*, cassa previdenza, bollo (a carico del cliente o dell'azienda), regime |
|
||||
| **Regime IVA** | *Scissione dei pagamenti* (art. 17-ter), *Inversione contabile*, codice IVA abituale, esigibilità (I, D, S), bollo a carico del cliente |
|
||||
| **Ritenute e casse** | *Ritenuta d'acconto* con aliquota e causale, cassa previdenziale con aliquota, *ENASARCO* |
|
||||
| **Dichiarazione d'intento** (esportatore abituale) | Attiva, Numero, Data, Protocollo AdE, Codice IVA (non imponibile art. 8 c.1 lett. c, natura N3.5), **Plafond**, **Utilizzato**, **Residuo**, Validità |
|
||||
| **Identificativi** | GLN, EORI, nostro codice presso il cliente |
|
||||
|
||||
@@ -101,21 +118,22 @@ comune, provincia e regione; il **codice fiscale** di una persona fisica può es
|
||||
|
||||
| Controparte | Valore |
|
||||
|---|---|
|
||||
| Azienda italiana (B2B) | 7 caratteri, comunicati dal cliente (in alternativa la PEC) |
|
||||
| Azienda italiana (B2B) | 7 caratteri, comunicati dal cliente; con la sola PEC si usa `0000000` (proposto) |
|
||||
| Pubblica amministrazione | **codice IPA** dell'ufficio, 6 caratteri |
|
||||
| Estero (UE ed extra-UE) | `XXXXXXX` |
|
||||
| Privato | `0000000` |
|
||||
| Estero (UE ed extra-UE) | `XXXXXXX` (proposto se vuoto) |
|
||||
| Privato | `0000000` (proposto se vuoto) |
|
||||
|
||||
**Dichiarazione d'intento**: quando il cliente è esportatore abituale, le fatture usano il codice IVA non
|
||||
imponibile collegato e riportano numero e protocollo della dichiarazione; l'utilizzato si aggiorna con le fatture e
|
||||
il residuo avvisa quando il plafond sta per esaurirsi (il mockup mostra un avviso all'80% e un blocco al 100%; le
|
||||
soglie definitive saranno fissate in sviluppo). Il registro completo delle dichiarazioni ricevute ed emesse è nel
|
||||
soglie si fissano con la fatturazione, M5). Una dichiarazione attiva richiede numero e plafond. Il registro completo delle dichiarazioni ricevute ed emesse è nel
|
||||
modulo Fatturazione elettronica (vedi [Fatturazione elettronica](Fatturazione-elettronica)).
|
||||
|
||||
### Condizioni di vendita (clienti)
|
||||
|
||||
Listino, sconti, pagamento, banca d'appoggio per le RiBa, agente, vettore, porto, deposito, **fido** e **blocco**,
|
||||
raggruppamento dei DDT in fattura differita, giorno di fatturazione, invio dei documenti per e-mail o PEC. Queste
|
||||
Listino, due sconti, pagamento, nostra banca d'appoggio per le RiBa, vettore, porto, deposito, **fido** e **ordini
|
||||
bloccati**, raggruppamento dei DDT in fattura differita, giorno di fatturazione, invio dei documenti per e-mail o PEC
|
||||
con l'indirizzo dedicato. Queste
|
||||
condizioni vengono proposte automaticamente nei documenti del cliente (vedi [Vendite](Vendite)).
|
||||
|
||||
Il **fido** è l'esposizione massima ammessa: quando viene superato, o se il cliente ha scaduto, gli ordini
|
||||
@@ -128,13 +146,12 @@ segnalano il blocco, superabile solo da chi ha il permesso di forzarlo.
|
||||
|
||||
| Gruppo | Campi |
|
||||
|---|---|
|
||||
| **Condizioni di acquisto** | Pagamento, Valuta, **Lead time** (giorni), **Minimo d'ordine**, Sconto %, Porto, Registro IVA acquisti, Conto di costo predefinito |
|
||||
| **Ritenute e contributi** | *Professionista (ritenuta d'acconto)*, aliquota ritenuta, causale, cassa previdenza, *Agente ENASARCO*, *Regime forfettario* (niente IVA, bollo), *Reverse charge* (es. subappalto edile) |
|
||||
| **Banca e contatti** | IBAN, BIC, referente, e-mail per gli ordini |
|
||||
| **Condizioni di acquisto** | Pagamento, **Tempo di consegna** (giorni), **Ordine minimo**, Sconto %, Porto, Registro IVA, Conto di costo, E-mail per gli ordini |
|
||||
| **Ritenute e casse** (scheda *Fiscale e SDI*) | *Ritenuta d'acconto* con aliquota e causale, cassa previdenziale, *ENASARCO*; il tipo soggetto *Forfettario* per chi non applica l'IVA |
|
||||
| **Banche** e **Contatti** | IBAN, BIC, banca, ABI e CAB; referenti |
|
||||
|
||||
L'intestazione del fornitore mostra il totale **acquisti** dell'anno, l'aperto, lo scaduto e gli ordini aperti; tra
|
||||
le schede *Articoli forniti* elenca gli articoli che il fornitore ti vende. Il lead time viene usato per calcolare
|
||||
le date di consegna previste negli ordini fornitore.
|
||||
Il tempo di consegna servirà a calcolare le date previste negli ordini fornitore. Il totale **acquisti**, l'aperto,
|
||||
lo scaduto e gli *Articoli forniti* del mockup arrivano con acquisti e articoli.
|
||||
|
||||
## Come si usa
|
||||
|
||||
@@ -142,41 +159,54 @@ le date di consegna previste negli ordini fornitore.
|
||||
|
||||
1. **Anagrafiche → Clienti**, premi **Nuovo cliente** (o `Ctrl+N`).
|
||||
2. Scegli il **tipo soggetto**. Il codice viene assegnato automaticamente al salvataggio (vedi più sotto).
|
||||
3. Inserisci ragione sociale e partita IVA: al salvataggio Khaemhat controlla la partita IVA e, se è comunitaria,
|
||||
3. Inserisci ragione sociale e partita IVA: al salvataggio Khaemhat controlla la partita IVA e, per un'impresa UE,
|
||||
la verifica sul servizio **VIES** (l'esito resta salvato con la data).
|
||||
4. Compila la sede legale partendo dal CAP.
|
||||
5. In **Fiscale e SDI** inserisci il codice destinatario o la PEC.
|
||||
6. In **Condizioni commerciali** imposta pagamento, listino, agente e fido.
|
||||
7. **Salva** (`Ctrl+S`).
|
||||
6. In **Condizioni** imposta pagamento, listino e fido; l'agente è nei dati principali.
|
||||
7. **Salva** (`Ctrl+S`). Gli errori portano alla scheda del primo campo da correggere; gli **avvisi** (ad esempio
|
||||
una partita IVA già usata da un'altra anagrafica, che va bene per filiali e sedi distinte) non bloccano e compaiono
|
||||
in un messaggio dopo il salvataggio.
|
||||
|
||||
Un lead si crea da **Contatti → Nuovo lead**, un prospect da **Contatti → Nuovo prospect**.
|
||||
|
||||
### Convertire un lead o un prospect in cliente
|
||||
|
||||
Dalla scheda del lead o del prospect usa l'azione di conversione: il soggetto diventa **cliente**, riceve il codice
|
||||
cliente secondo la maschera automatica e mantiene la propria storia (attività, opportunità). Con il modulo CRM la
|
||||
conversione si avvia anche dalla maschera dei lead (vedi [CRM](CRM)).
|
||||
Dalla scheda del lead o del prospect usa **Converti in cliente**: il soggetto diventa **cliente**, riceve il codice
|
||||
cliente secondo la maschera automatica e conserva il vecchio come **codice precedente** (si trova ancora con la
|
||||
ricerca), insieme a storico e allegati. Con il modulo CRM la conversione si avvierà anche dalla maschera dei lead
|
||||
(vedi [CRM](CRM)).
|
||||
|
||||
Su un **fornitore** la stessa azione lo rende anche cliente: il codice non cambia e l'anagrafica compare in entrambi
|
||||
gli elenchi.
|
||||
|
||||
### Disabilitare invece di cancellare
|
||||
|
||||
Un'anagrafica che compare in almeno un documento **non si cancella**: si **disabilita** (azione **Disabilita** nel
|
||||
radar o nella scheda). Un'anagrafica disabilitata non viene più proposta nei nuovi documenti né nelle ricerche
|
||||
predefinite, ma resta consultabile con i suoi documenti. Si può cancellare solo un'anagrafica mai usata.
|
||||
Un'anagrafica che compare in almeno un documento **non si cancella**: si **disattiva** (azione **Disattiva** nel
|
||||
radar o nel menu della scheda). Un'anagrafica disattivata non viene più proposta nei nuovi documenti né nelle
|
||||
ricerche predefinite, ma resta consultabile con i suoi documenti. Se si prova a eliminare un'anagrafica usata,
|
||||
Khaemhat la disattiva e lo dice. Si cancella davvero solo un'anagrafica mai usata.
|
||||
|
||||
## Validazioni
|
||||
|
||||
| Dato | Controllo |
|
||||
|---|---|
|
||||
| **Partita IVA italiana** | 11 cifre con cifra di controllo |
|
||||
| **Ragione sociale** | obbligatoria (per i privati cognome e nome) |
|
||||
| **Partita IVA italiana** | 11 cifre con cifra di controllo; obbligatoria per un'impresa; un doppione è un avviso |
|
||||
| **Partita IVA UE** | verifica sul servizio VIES della Commissione europea; esito e data salvati |
|
||||
| **Codice fiscale** | 16 caratteri con carattere di controllo (11 cifre per le società); calcolabile dai dati anagrafici |
|
||||
| **Codice fiscale** | 16 caratteri con carattere di controllo (11 cifre per le società); per un privato senza codice fiscale un avviso |
|
||||
| **Pubblica amministrazione** | serve il codice fiscale o la partita IVA |
|
||||
| **Paese** | nella tabella dei paesi; un'impresa UE ha sede in un altro paese dell'Unione, impresa italiana, privato, PA e forfettario nel paese dell'azienda |
|
||||
| **IBAN** | struttura e controllo modulo 97 |
|
||||
| **Codice destinatario** | 7 caratteri; 6 per la PA (codice IPA); `XXXXXXX` estero; `0000000` privato |
|
||||
| **E-mail / PEC** | formato dell'indirizzo |
|
||||
| **Codice** | unico fra tutte le anagrafiche |
|
||||
|
||||
## Codici automatici
|
||||
|
||||
Il codice di clienti, fornitori e lead è assegnato automaticamente secondo le maschere impostate in
|
||||
Il codice di clienti, fornitori, prospect e lead è assegnato automaticamente secondo le maschere impostate in
|
||||
*Tabelle azienda → Preferenze e codici automatici* (vedi [Tabelle azienda](Tabelle-azienda)): `C{seq:000000}` per i
|
||||
clienti, `F{seq:000000}` per i fornitori, `L{anno}-{seq:0000}` per i lead. La maschera mostra l'anteprima del
|
||||
clienti, `F{seq:000000}` per i fornitori, `L{anno}-{seq:0000}` per prospect e lead. La maschera mostra l'anteprima del
|
||||
prossimo codice; un'impostazione decide se è ammesso scrivere un **codice manuale**. Il progressivo è assegnato in
|
||||
modo atomico: due utenti che salvano insieme non ottengono mai lo stesso codice.
|
||||
|
||||
@@ -184,25 +214,31 @@ modo atomico: due utenti che salvano insieme non ottengono mai lo stesso codice.
|
||||
|
||||
| Quando | Khaemhat propone |
|
||||
|---|---|
|
||||
| inserisci il CAP | comune, provincia e regione |
|
||||
| inserisci i dati anagrafici di una persona | il codice fiscale |
|
||||
| inserisci il CAP | comune e provincia (scelta fra più comuni) |
|
||||
| inserisci il comune | CAP e provincia |
|
||||
| premi *Calcola* accanto al codice fiscale di un privato | il codice fiscale |
|
||||
| salvi una P.IVA UE | la verifica VIES |
|
||||
| inserisci un IBAN | banca e BIC (tabella ABI) |
|
||||
| crei un documento per il cliente | destinazione, listino, pagamento, agente |
|
||||
| inserisci un IBAN | ABI, CAB e banca (dalla tabella delle banche, quando caricata) |
|
||||
| lasci vuoto il codice destinatario di un privato o di un estero | `0000000` o `XXXXXXX` |
|
||||
| crei un documento per il cliente | destinazione, listino, pagamento, agente (con le vendite, M5) |
|
||||
|
||||
Le singole compilazioni si attivano o disattivano in *Tabelle azienda → Preferenze e codici automatici*.
|
||||
|
||||
## Permessi e licenza
|
||||
|
||||
Le anagrafiche fanno parte del modulo **CORE**. Il flag utente *vede solo i propri clienti* limita un agente ai
|
||||
clienti a lui assegnati. Le schede *CRM* e *Scheda 360°* mostrano i dati CRM solo con il modulo **CRM** attivo; il
|
||||
Le anagrafiche fanno parte del modulo **CORE**: `parties.party.read` per consultare, `parties.party.write` per
|
||||
inserire, modificare, disattivare e convertire, `parties.party.delete` per eliminare. Il flag utente *vede solo i
|
||||
propri clienti*, che limiterà un agente ai clienti assegnati, non è ancora attivo. Le schede *CRM* e *Scheda 360°* mostrano i dati CRM solo con il modulo **CRM** attivo; il
|
||||
registro delle dichiarazioni d'intento richiede **EINV**. Ogni modifica è registrata nello **Storico**.
|
||||
|
||||
## Domande frequenti
|
||||
|
||||
- **Non riesco a cancellare un cliente.** Ha documenti collegati: disabilitalo.
|
||||
- **La verifica VIES non risponde.** Il servizio europeo può essere temporaneamente non disponibile: salva
|
||||
comunque e ripeti la verifica con l'azione **VIES** più tardi.
|
||||
comunque e ripeti la verifica con l'azione **Verifica VIES** più tardi.
|
||||
- **Ho convertito un prospect e il vecchio codice è sparito.** È nel campo *Codice precedente* e la ricerca lo trova.
|
||||
- **Un fornitore compare anche fra i clienti.** È un cliente con *È anche fornitore*: un solo soggetto, un solo
|
||||
codice.
|
||||
- **Un cliente privato non ha codice destinatario.** È corretto: si usa `0000000` e la fattura resta disponibile
|
||||
nell'area riservata del cliente sul sito dell'Agenzia delle Entrate; consegnagli comunque una copia di cortesia.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Architettura
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M0-M13)
|
||||
> **Specifica:** SPEC §1-§5, §9, §13, §21 · ADR 0009-0011
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.1.0 (accesso ai dati); il resto arriva con le milestone M2-M13
|
||||
> **Specifica:** SPEC §1-§5, §9, §13, §21 · ADR 0004, 0009-0018
|
||||
|
||||
Come è fatto Khaemhat "dentro", spiegato senza entrare nel codice. Chi sviluppa trova il documento tecnico completo
|
||||
(regole di dipendenza, contratti, elenco delle classi) in
|
||||
@@ -63,6 +63,13 @@ I dati di un'azienda non si mescolano mai con quelli di un'altra: stanno fisicam
|
||||
lavora solo nella sua azienda; gli amministratori scelgono l'azienda dalla barra superiore. Gestione in
|
||||
[Istanza-e-database](Istanza-e-database).
|
||||
|
||||
Il database di sistema tiene l'elenco delle aziende e, per ciascuna, **dove si trova il suo database**: questa
|
||||
informazione contiene la password del database ed è salvata **cifrata** con la chiave dell'istanza
|
||||
(`KHAEMHAT_SECRET_KEY`), in modo che non si possa leggere nemmeno copiandola da un'azienda all'altra. Quando il
|
||||
programma lavora per un'azienda apre il database giusto da solo; la struttura di ogni database viene aggiornata dalle
|
||||
**migrazioni** ([Modello-dati](Modello-dati)). Tutto il programma funziona allo stesso modo su PostgreSQL (16 o
|
||||
successivo) e su SQLite: i test girano su entrambi a ogni versione.
|
||||
|
||||

|
||||
*Mockup 078 — elenco dei database dell'istanza (sistema e aziende) con motore, dimensione, stato dello schema, ultimo backup e stato; sotto, le informazioni sul server PostgreSQL (anteprima ridotta).*
|
||||
|
||||
|
||||
@@ -1,153 +1,212 @@
|
||||
# Articoli e listini
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** famiglia `items.*` (es. `items.cost.read` per vedere i costi) · **Specifica:** SPEC §11.2, §11.3 (prezzi), §11.6
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.4.0 (milestone M4; giacenze e costi dai movimenti con il magazzino, M6)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** `items.item.read` (consultare), `items.item.write` (inserire, modificare, disattivare, prezzi), `items.item.delete` (eliminare), `items.cost.read` (vedere costi e margini) · **Specifica:** SPEC §11.2, §11.3 (prezzi), §14 · **Decisioni:** ADR 0030
|
||||
|
||||
L'**articolo** descrive ciò che l'azienda vende o compra: merci, servizi, spese, righe di solo testo e cespiti.
|
||||
Nella scheda articolo stanno codici, unità di misura, IVA, conti contabili, prezzi e costi, i parametri di
|
||||
**riordino** e le **giacenze** per deposito in tempo reale. I **listini** raccolgono i prezzi di vendita per gruppi di
|
||||
clienti e si aggiornano anche in modo massivo.
|
||||
L'**articolo** descrive ciò che l'azienda vende o compra: merci, servizi, spese, righe descrittive e cespiti. Nella
|
||||
scheda articolo stanno codici, unità di misura, IVA, conti, prezzi e costi e i parametri di **riordino**. I
|
||||
**listini** raccolgono i prezzi di vendita per gruppi di clienti, con una data di validità, e si aggiornano anche in
|
||||
modo massivo.
|
||||
|
||||
## Dove si trova
|
||||
|
||||
Menu **Anagrafiche → Articoli** e **Anagrafiche → Listini**; le categorie articolo sono in **Anagrafiche →
|
||||
Categorie**.
|
||||
Menu **Anagrafiche → Articoli** e **Anagrafiche → Listini**. Le **categorie articolo**, le **intestazioni dei
|
||||
listini** e le **unità di misura** sono tabelle dell'azienda (vedi [Tabelle azienda](Tabelle-azienda)).
|
||||
|
||||
## L'elenco degli articoli
|
||||
|
||||
L'elenco è una griglia con ricerca per codice, descrizione, codice a barre (anche alternativo) e marca, e le colonne
|
||||
codice, descrizione, tipo, categoria, UM, **prezzo base**, **costo medio** (solo con il permesso di vedere i costi),
|
||||
magazzino e stato. I filtri rapidi scelgono tipo, categoria, articoli a magazzino e **attivi / disattivati**. Dalla
|
||||
toolbar si disattivano e riattivano gli articoli selezionati e si apre la griglia dei listini.
|
||||
|
||||

|
||||
*Khaemhat 0.4.0 — il radar dei 120 articoli di esempio con categoria, UM, marca, tipo, costo medio e prezzo base.*
|
||||
|
||||
## La scheda articolo
|
||||
|
||||

|
||||
*Mockup 017 — scheda articolo: azioni Movimenti, Etichette, Proposta riordino; intestazione con disponibilità e costo medio; gruppi Identità, Codici UM e fisco, Prezzi e costi, Riordino; giacenze per deposito (anteprima ridotta).*
|
||||
*Mockup 017 — scheda articolo: intestazione con prezzo e costo medio; gruppi Identità, Codici UM e fisco, Prezzi e costi, Riordino; giacenze per deposito (anteprima ridotta).*
|
||||
|
||||
**Toolbar**: comandi standard e le azioni contestuali **Movimenti** (movimenti di magazzino dell'articolo),
|
||||
**Etichette** (stampa etichette), **Proposta riordino**.
|
||||

|
||||
*Khaemhat 0.4.0 — la scheda di un articolo di esempio con prezzo base, costo medio e margine nell'intestazione e le schede UM, codici alternativi, listini, fornitori e sostitutivi.*
|
||||
|
||||
**Intestazione**: a sinistra codice, avvisi (ad esempio *Sotto punto di riordino*), EAN e categoria; al centro
|
||||
descrizione, UM, marca, peso, nomenclatura NC8, aliquota IVA e chip con prezzi di listino, disponibilità
|
||||
(*Disp. · Imp. · Ord.*), fornitore abituale, scorta minima e punto di riordino; a destra il **costo medio** con
|
||||
ultimo costo, costo standard e margine.
|
||||
**Intestazione**: codice, descrizione, tipo e categoria; a destra il **prezzo base in vigore oggi** con costo medio,
|
||||
ultimo costo, costo standard e **margine** (i costi solo con il permesso `items.cost.read`).
|
||||
|
||||
**Schede**: *Dati principali*, *UM alternative*, *Codici alternativi*, *Listini*, *Fornitori*, *Sostitutivi*,
|
||||
*Movimenti*, *Immagini e allegati*.
|
||||
**Schede**:
|
||||
|
||||
| Scheda | Contenuto |
|
||||
|---|---|
|
||||
| **Dati principali** | i gruppi *Identità*, *Unità, codici e IVA*, *Prezzi e costi*, *Magazzino e riordino*, *Contabilità* |
|
||||
| **UM alternative** | unità diverse da quella base con il **fattore** (una scatola da 10 pezzi ha fattore 10) e l'EAN della confezione |
|
||||
| **Codici alternativi** | codici a barre dei produttori e codici dei vecchi gestionali: la ricerca li trova esattamente |
|
||||
| **Listini** | i prezzi in vigore oggi in ogni listino, i prezzi di listino scritti con la loro data e i **prezzi netti dei clienti** |
|
||||
| **Fornitori** | chi fornisce l'articolo, con codice e prezzo del fornitore, giorni di consegna, minimo d'ordine e il **fornitore abituale** |
|
||||
| **Sostitutivi** | articoli equivalenti da proporre quando quello richiesto manca |
|
||||
| **Note e allegati** | note libere e file (immagini, schede tecniche) |
|
||||
| **Storico** | modifiche registrate: chi, quando, cosa |
|
||||
|
||||
Una scheda con errori mostra il numero degli errori nell'etichetta, come nelle [Anagrafiche](Anagrafiche).
|
||||
|
||||
### Campi principali
|
||||
|
||||
| Gruppo | Campi |
|
||||
|---|---|
|
||||
| **Identità** | Codice (automatico), Tipo, Categoria, **Descrizione** *, Descrizione estesa, Marca, Produttore |
|
||||
| **Codici, UM e fisco** | UM base, EAN (con verifica della cifra di controllo), NC8 (Intrastat), IVA vendita, IVA acquisto, Peso netto, Conto ricavo, Conto costo |
|
||||
| **Prezzi e costi** | prezzi dei listini principali (es. base, pubblico IVA inclusa, rivenditori), Costo standard, Ultimo costo, Medio ponderato (gli ultimi due calcolati) |
|
||||
| **Riordino** | Gestito a magazzino, Deposito, **Scorta minima**, **Punto di riordino**, **Lotto di riordino**, Fornitore abituale |
|
||||
| **Giacenze per deposito (tempo reale)** | per ogni deposito: Giacenza, Impegnato, Ordinato, Disponibile, Valore, con riga di totale |
|
||||
| **Unità, codici e IVA** | UM base, codice a barre (EAN, con verifica della cifra di controllo), nomenclatura **NC8** (otto cifre, per Intrastat), IVA vendita, IVA acquisto, Peso netto e lordo |
|
||||
| **Prezzi e costi** | Prezzo dell'articolo (vale solo se nessun listino ha un prezzo), Costo standard, Ultimo costo, Costo medio |
|
||||
| **Magazzino e riordino** | Gestito a magazzino, Deposito, **Scorta minima**, **Punto di riordino**, **Lotto di riordino** |
|
||||
| **Contabilità** | Conto ricavo, Conto costo |
|
||||
|
||||
### Tipi di articolo
|
||||
|
||||
| Tipo | Uso | Magazzino |
|
||||
|---|---|---|
|
||||
| **Merce** | beni venduti o acquistati | sì, se *Gestito a magazzino* |
|
||||
| **Servizio** | prestazioni (es. installazione, assistenza a ore) | no |
|
||||
| **Servizio** | prestazioni (installazione, assistenza a ore) | no |
|
||||
| **Spesa** | spese accessorie in fattura (trasporto, incasso) | no |
|
||||
| **Testo** | righe descrittive ricorrenti | no |
|
||||
| **Cespite** | beni strumentali (collegati al registro cespiti con il modulo Cespiti) | da definire in sviluppo |
|
||||
| **Descrittivo** | righe di solo testo ricorrenti | no |
|
||||
| **Cespite** | beni strumentali (registro cespiti con il modulo Cespiti) | no |
|
||||
|
||||
### Unità di misura e codici
|
||||
Solo le merci possono essere gestite a magazzino: per gli altri tipi l'opzione è spenta e Khaemhat la corregge al
|
||||
salvataggio.
|
||||
|
||||
- **UM base** (ad esempio `PZ`, `MT`, `H`, `NR`) dalla tabella delle unità di misura, con il codice usato nell'XML
|
||||
SDI; le **UM alternative** hanno un fattore di conversione (ad esempio confezione da 10 pezzi).
|
||||
- **Codici alternativi**: altri codici a barre (EAN) e codici interni; nella ricerca F4 un articolo si trova anche
|
||||
per EAN e per il **codice che il cliente usa** per quell'articolo (impostato nella scheda *Articoli e codici* del
|
||||
cliente, vedi [Anagrafiche](Anagrafiche)).
|
||||
- **Fornitori**: chi fornisce l'articolo, con codice e prezzo del fornitore; uno è il **fornitore abituale** usato
|
||||
dalla proposta di riordino.
|
||||
- **Sostitutivi**: articoli equivalenti proposti quando quello richiesto non è disponibile.
|
||||
### Costi
|
||||
|
||||
### Prezzi e costi
|
||||
- **Costo standard**: valore scritto a mano.
|
||||
- **Ultimo costo** e **costo medio**: li aggiornano i carichi di magazzino (DDT di carico, fatture di acquisto) che
|
||||
arrivano con il magazzino (M6); fino ad allora sono valorizzati solo nei dati di esempio. Il costo medio è il
|
||||
criterio di valorizzazione del magazzino (vedi [Magazzino](Magazzino)).
|
||||
- Il **margine** è calcolato sul prezzo: (prezzo - costo) / prezzo.
|
||||
- Chi non ha il permesso `items.cost.read` non vede i costi (né nella scheda né nell'elenco né nei listini) e,
|
||||
quando salva, i costi in archivio restano quelli di prima.
|
||||
|
||||
- I **prezzi di vendita** stanno nei listini (vedi sotto); la scheda mostra quelli dei listini principali.
|
||||
- **Costo standard**: valore impostato a mano.
|
||||
- **Ultimo costo** e **costo medio ponderato**: aggiornati dai carichi di magazzino (DDT di carico, fatture di
|
||||
acquisto). Il costo medio è il criterio di valorizzazione del magazzino (vedi [Magazzino](Magazzino)).
|
||||
- Il **margine** è mostrato solo a chi ha il permesso di vedere costi e margini.
|
||||
### Giacenze e riordino
|
||||
|
||||
### Riordino e giacenze
|
||||
Con **Gestito a magazzino** l'articolo parteciperà a movimenti, giacenze per deposito (*Giacenza, Impegnato,
|
||||
Ordinato, Disponibile, Valore*) e **proposta di riordino**: questi arrivano con il magazzino (M6). Scorta minima,
|
||||
punto e lotto di riordino si possono già compilare.
|
||||
|
||||
Con **Gestito a magazzino** attivo l'articolo partecipa ai movimenti, alle giacenze e alla **proposta di riordino**:
|
||||
quando la disponibilità scende sotto il **punto di riordino** l'articolo viene proposto per un ordine al fornitore
|
||||
abituale, in multipli del **lotto**. La griglia *Giacenze per deposito* mostra:
|
||||
### Controlli al salvataggio
|
||||
|
||||
| Colonna | Significato |
|
||||
|---|---|
|
||||
| **Giacenza** | quantità fisicamente presente |
|
||||
| **Impegnato** | quantità riservata da ordini clienti confermati |
|
||||
| **Ordinato** | quantità in arrivo da ordini fornitore |
|
||||
| **Disponibile** | giacenza - impegnato |
|
||||
| **Valore** | giacenza x costo medio |
|
||||
- Descrizione obbligatoria; categoria obbligatoria se la maschera del codice la usa.
|
||||
- Codice a barre con cifra di controllo corretta (EAN-8, EAN-13, UPC). Un codice a barre già usato da un altro
|
||||
articolo blocca il salvataggio se nelle preferenze è attivo *Blocca duplicati per EAN* (impostazione di
|
||||
partenza), altrimenti è solo un avviso.
|
||||
- NC8 di otto cifre; quantità, pesi, prezzi e costi non negativi; fattori delle UM maggiori di zero.
|
||||
- Nelle schede di dettaglio: la stessa UM, lo stesso codice alternativo, lo stesso fornitore o sostitutivo non si
|
||||
ripetono; un articolo non è sostitutivo di sé stesso; un prezzo netto vale per un cliente.
|
||||
|
||||
### Disattivare ed eliminare
|
||||
|
||||
**Disattiva** toglie l'articolo dalle ricerche dei documenti nuovi senza perdere nulla. **Elimina** cancella
|
||||
l'articolo solo se nessun altro dato lo usa (ad esempio se è sostitutivo di un altro articolo, e da M5 se compare
|
||||
nei documenti); altrimenti Khaemhat lo **disattiva** al posto dell'eliminazione e lo dice.
|
||||
|
||||
## Codici articolo
|
||||
|
||||
Il codice segue la maschera `{categoria}-{seq:0000}` con progressivo **per categoria** (categoria `VALV` →
|
||||
`VALV-0013`). Maschera, codice manuale e blocco dei duplicati per EAN si impostano in *Tabelle azienda →
|
||||
Preferenze e codici automatici* (vedi [Tabelle azienda](Tabelle-azienda)). Il codice si assegna al primo
|
||||
salvataggio.
|
||||
|
||||
I **codici che un cliente o un fornitore usa** per i tuoi articoli si scrivono nella scheda *Articoli e codici*
|
||||
dell'anagrafica (vedi [Anagrafiche](Anagrafiche)): nei documenti di quel cliente la ricerca F4 trova l'articolo
|
||||
anche con il suo codice.
|
||||
|
||||
## Listini
|
||||
|
||||

|
||||
*Mockup 018 — griglia listino x articolo: costo medio, LIST01 Base, LIST02 Pubblico, LIST03 Rivenditori, prezzi netti di un cliente e margine; cella modificata evidenziata e scheda con pallino di modifica.*
|
||||
*Mockup 018 — griglia listino x articolo: costo medio, listini base, pubblico e rivenditori, prezzi netti di un cliente e margine; cella modificata evidenziata.*
|
||||
|
||||
La maschera **Listini** è una **griglia articoli x listini**: per ogni articolo (codice, descrizione, UM, costo
|
||||
medio) una colonna per ciascun listino, più eventuali colonne di **prezzi netti per cliente** e il **margine**.
|
||||

|
||||
*Khaemhat 0.4.0 — la griglia articoli x listini sui 120 articoli di esempio: listino base, Pubblico e Rivenditori derivati (in corsivo i prezzi calcolati), costo medio e margine.*
|
||||
|
||||
- Filtri: ricerca, **Categoria**, **Listino**, **Validità** (la data a cui leggere i prezzi, ad esempio *Oggi*),
|
||||
chip *Mostra margine*.
|
||||
- I prezzi si modificano direttamente nelle celle; le modifiche restano evidenziate e la scheda mostra il pallino
|
||||
arancione finché non salvi. Il piede riporta il numero di articoli, le modifiche non salvate e la data di validità
|
||||
dei nuovi prezzi.
|
||||
- Azioni: **Aggiornamento massivo**, **Nuovo listino**; icone per salvare, annullare, stampare, esportare,
|
||||
applicare una variazione percentuale, ripristinare, duplicare.
|
||||
Un **listino** ha codice, descrizione, valuta, *IVA inclusa*, validità e, se è derivato, il listino da cui
|
||||
**deriva**, il **ricarico %** (anche negativo, come uno sconto) e il **passo di arrotondamento**. Le intestazioni si
|
||||
gestiscono nella tabella *Listini* dell'azienda; uno solo è il **listino base** (in partenza `BASE`).
|
||||
|
||||
Ogni listino ha una **validità** (i prezzi nuovi valgono da una data, i vecchi restano per i documenti precedenti),
|
||||
può essere **derivato** da un altro listino (ad esempio pubblico = base + 40%) e ha le proprie regole di
|
||||
**arrotondamento**.
|
||||
### La griglia dei listini
|
||||
|
||||
**Anagrafiche → Listini** è una griglia **articoli x listini**: per ogni articolo codice, descrizione, UM, costo
|
||||
medio (con il permesso) e una colonna per ciascun listino attivo.
|
||||
|
||||
- In alto: ricerca, **Listino** (tutti o uno solo), **Validità** (la data a cui leggere e scrivere i prezzi, oggi
|
||||
in partenza), **Prezzi netti di** un cliente (aggiunge la colonna dei suoi prezzi netti) e **Mostra margine**.
|
||||
- I prezzi si scrivono nelle celle (vuoto toglie il prezzo a quella data). Le celle cambiate restano **evidenziate
|
||||
da salvare**; il piede riporta articoli, modifiche non salvate e data di validità dei nuovi prezzi. **Salva**
|
||||
scrive tutto insieme, **Annulla modifiche** torna ai prezzi salvati.
|
||||
- Le celle in *corsivo* sono **calcolate** da un listino derivato che non ha un prezzo proprio per l'articolo: il
|
||||
suggerimento dice da quale listino. Scrivere un prezzo nella cella lo rende proprio di quel listino.
|
||||
- Con modifiche non salvate non si cambiano validità o cliente: prima salva o annulla.
|
||||
- **Nuovo listino** apre la tabella dei listini.
|
||||
|
||||
### Validità dei prezzi
|
||||
|
||||
Ogni prezzo vale **dalla sua data** fino al prezzo successivo dello stesso listino (o dello stesso cliente).
|
||||
Scrivere un prezzo con una data nuova **aggiunge** un prezzo e lascia quello vecchio ai documenti datati prima;
|
||||
scriverlo con la stessa data lo corregge. I documenti già fatti conservano sempre il prezzo di allora.
|
||||
|
||||
### Listini derivati
|
||||
|
||||
Un listino derivato senza un proprio prezzo per un articolo prende il prezzo del listino di partenza alla stessa
|
||||
data, applica il ricarico e arrotonda al passo (al centesimo se il passo è zero). Esempio dei dati di esempio:
|
||||
*Pubblico* = base + 45% arrotondato a 0,10; *Rivenditori* = base - 10%. Un prezzo scritto nel listino derivato vince
|
||||
su quello calcolato.
|
||||
|
||||
### Aggiornamento massivo
|
||||
|
||||
1. Premi **Aggiornamento massivo**.
|
||||
2. Scegli **che cosa** aggiornare: un listino, una categoria o le righe selezionate.
|
||||
3. Scegli la **variazione**: percentuale (anche negativa) oppure a partire da un altro listino.
|
||||
4. Scegli l'**arrotondamento**: a 0,10, 0,50 o 1,00, per eccesso o per difetto.
|
||||
5. Indica la **data di validità** dei nuovi prezzi.
|
||||
6. Controlla le righe aggiornate (restano evidenziate) e **Salva**.
|
||||
2. Scegli il **listino da aggiornare** e da dove **calcolare**: i prezzi attuali dello stesso listino o un altro
|
||||
listino.
|
||||
3. Scrivi la **variazione %** (anche negativa).
|
||||
4. Scegli l'**arrotondamento** (0,01, 0,10, 0,50, 1,00) e il **verso** (al più vicino, per eccesso, per difetto).
|
||||
5. Indica la data da cui valgono i nuovi prezzi (**Valido dal**).
|
||||
6. Scegli gli **articoli**: tutti, quelli di una categoria o solo i selezionati.
|
||||
7. Premi **Calcola i prezzi**: le celle calcolate restano evidenziate; controllale e **Salva**.
|
||||
|
||||
L'aggiornamento listini è disponibile anche come procedura pianificabile (vedi [Automazioni](Automazioni)).
|
||||
Il calcolo non scrive nulla finché non salvi; gli articoli il cui prezzo non cambia sono esclusi.
|
||||
|
||||
## Come viene scelto il prezzo in un documento
|
||||
|
||||
Quando inserisci un articolo in una riga di vendita, Khaemhat cerca il prezzo in quest'ordine e si ferma al primo
|
||||
che trova:
|
||||
Quando inserisci un articolo in una riga di vendita (da M5), Khaemhat cerca il prezzo valido alla data del documento
|
||||
in quest'ordine e si ferma al primo che trova:
|
||||
|
||||
| Ordine | Fonte | Esempio |
|
||||
|---|---|---|
|
||||
| 1 | **prezzo netto cliente-articolo** | prezzo concordato con Rossi Impianti per quella valvola |
|
||||
| 2 | **listino del cliente** | il cliente usa LIST03 Rivenditori |
|
||||
| 3 | **listino base** | LIST01 Base |
|
||||
| 4 | **prezzo dell'articolo** | prezzo indicato nella scheda |
|
||||
| 2 | **listino del documento o del cliente** | il cliente usa il listino *Rivenditori* |
|
||||
| 3 | **listino base** | *Base* |
|
||||
| 4 | **prezzo dell'articolo** | prezzo scritto nella scheda |
|
||||
|
||||
La riga ricorda **da dove viene il prezzo** (la fonte), così è sempre possibile capire perché è stato proposto
|
||||
quel valore. Sul prezzo si applicano poi gli sconti del cliente e della riga (anche a cascata, come `5+2`). Se è
|
||||
attiva la compilazione automatica *Ultimo prezzo praticato al cliente*, Khaemhat lo mostra come riferimento.
|
||||
|
||||
## Codici automatici
|
||||
|
||||
Il codice articolo segue la maschera `{categoria}-{seq:0000}` con progressivo **per categoria** (ad esempio
|
||||
categoria `VALV` → `VALV-0013`); la maschera, l'eventuale codice manuale e il blocco dei **duplicati per EAN** si
|
||||
impostano in *Tabelle azienda → Preferenze e codici automatici* (vedi [Tabelle azienda](Tabelle-azienda)).
|
||||
La riga ricorda **da dove viene il prezzo** (la fonte). Sul prezzo di listino si propongono gli sconti del cliente a
|
||||
cascata (come `10+5`); su un **prezzo netto** non si applicano sconti.
|
||||
|
||||
## Permessi e licenza
|
||||
|
||||
Articoli e listini sono nel modulo **CORE**. I costi e i margini sono visibili solo agli utenti con il permesso
|
||||
`items.cost.read` (flag *vede costi e margini*). Il collegamento ai cespiti richiede il modulo **ASSET**; i conti
|
||||
contabili sono usati con il modulo **ACCT**.
|
||||
Articoli e listini sono nel modulo **CORE**. Per scrivere i prezzi nella griglia serve `items.item.write`; i costi
|
||||
e i margini richiedono `items.cost.read` (il ruolo *Magazzino* gestisce gli articoli ma non vede i costi). Il
|
||||
collegamento ai cespiti richiede il modulo **ASSET**; i conti contabili sono usati con il modulo **ACCT**.
|
||||
|
||||
## Dati di esempio
|
||||
|
||||
I dati di esempio (vedi [Dati di base e di esempio](Dati-di-base-e-esempio)) creano 120 articoli fittizi di un
|
||||
grossista termoidraulico in dieci categorie (valvolame, raccorderia, tubi, caldaie, sanitari, consumabili, pompe,
|
||||
utensili, servizi, spese), i listini *Pubblico* e *Rivenditori* derivati dal base, prezzi dell'anno precedente per
|
||||
lo storico, fornitori abituali, UM alternative, codici alternativi, sostitutivi e i prezzi netti e i codici di
|
||||
Rossi Impianti. I codici a barre di esempio iniziano con `200`, prefisso riservato all'uso interno.
|
||||
|
||||
## Domande frequenti
|
||||
|
||||
- **Ho cambiato un prezzo di listino ma la fattura di ieri non cambia.** È corretto: i documenti conservano il
|
||||
prezzo con cui sono stati fatti; la validità del listino vale per i documenti nuovi.
|
||||
- **Perché il prezzo proposto non è quello del listino?** Probabilmente esiste un prezzo netto per quel cliente:
|
||||
la fonte del prezzo è indicata nella riga.
|
||||
- **Un articolo di servizio non compare nelle giacenze.** I servizi e le spese non sono gestiti a magazzino.
|
||||
prezzo con cui sono stati fatti; i prezzi nuovi valgono dalla loro data.
|
||||
- **Ho scritto un prezzo con la data sbagliata.** Imposta quella data in *Validità*, svuota la cella e salva: il
|
||||
prezzo a quella data viene tolto.
|
||||
- **Perché il prezzo proposto non è quello del listino?** Probabilmente esiste un prezzo netto per quel cliente: la
|
||||
fonte del prezzo è indicata nella riga.
|
||||
- **Non vedo il costo medio.** Serve il permesso di vedere costi e margini (`items.cost.read`).
|
||||
- **Un servizio non si può mettere a magazzino.** È voluto: solo le merci vanno a magazzino.
|
||||
|
||||
## Pagine correlate
|
||||
|
||||
|
||||
@@ -1,8 +1,13 @@
|
||||
# Attività programmate
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2 e M12)
|
||||
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2 e M12)
|
||||
> **Modulo di licenza:** CORE (procedure oltre quelle di sistema: AUTO; report pianificati: REPORT) · **Livello richiesto:** amministratore · **Specifica:** SPEC §9, §11.12, §11.13, §12.5
|
||||
|
||||
> **Nella versione 0.2.0** c'è il motore: espressioni cron a 5 campi con fuso orario, lock per attività (una sola
|
||||
> esecuzione anche con più istanze), timeout, tentativi, storico delle esecuzioni e notifica agli amministratori
|
||||
> quando un'attività fallisce. Girano i tre job di sistema (pulizia sessioni, controllo licenza, retention del log).
|
||||
> La schermata e le attività create dagli utenti arrivano in M12.
|
||||
|
||||
## A cosa serve
|
||||
|
||||
Le **attività programmate** fanno lavorare Khaemhat da solo a orari stabiliti: backup notturni, fatturazione
|
||||
@@ -132,6 +137,14 @@ il dettaglio dell'ultima. Le esecuzioni sono registrate nel database di sistema.
|
||||
|
||||
## Job di sistema
|
||||
|
||||
Nella versione 0.2.0 i job di sistema sono questi (orari nel fuso `Europe/Rome`):
|
||||
|
||||
| Codice | Cosa fa | Quando |
|
||||
|---|---|---|
|
||||
| `system.sessions-cleanup` | elimina le sessioni scadute o revocate da più di 30 giorni, nel database di sistema e in ogni azienda non disattivata | al minuto 15 di ogni ora |
|
||||
| `system.license-check` | ricalcola la licenza; avvisa gli amministratori a 30, 14, 7, 3 e 1 giorno dalla scadenza e quando è scaduta | ogni ora |
|
||||
| `system.log-retention` | elimina gli eventi di log più vecchi della retention del loro livello | ogni notte alle 03:30 |
|
||||
|
||||
Oltre alle attività degli amministratori, Khaemhat esegue sempre alcuni **job di sistema**: pulizia (log e sessioni
|
||||
secondo la retention), controllo della licenza, aggiornamento dei cambi BCE, lettura dell'inbox e dei canali SDI,
|
||||
coda delle e-mail, verifica delle giacenze, backup. Le attività di sistema predefinite sono create con le tabelle di
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Changelog
|
||||
|
||||
> **Stato:** completa per 0.1.0 · **Ultima revisione:** 2026-11-11
|
||||
> **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,12 +11,16 @@ 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. |
|
||||
| 0.1.0 | 2026-11-11 | M1 — Strato dati: accesso ai database SQLite e PostgreSQL, migrazioni dello schema, registro delle aziende, cifratura dei dati riservati. Nessuna funzione visibile nell'interfaccia. |
|
||||
| 0.0.1 | 2026-11-11 | M0 — Bootstrap: struttura del codice, immagine Docker con pagina "in costruzione" ed endpoint di salute, compose, CI e rilascio su Gitea Actions. Nessuna funzione gestionale ancora. |
|
||||
| *preparazione* | 2026-11-10 | Documentazione, specifica, mockup, wiki e pianificazione su Gitea. Nessun software. |
|
||||
|
||||
Ogni immagine Docker pubblicata ha lo stesso numero di versione del tag git (senza la `v` iniziale), ad esempio
|
||||
`gitea.encke-hake.ts.net/balbosoft/khaemhat:0.1.0`. Prima di aggiornare leggi [Aggiornamento](Aggiornamento).
|
||||
`gitea.encke-hake.ts.net/balbosoft/khaemhat:0.3.0`. Prima di aggiornare leggi [Aggiornamento](Aggiornamento).
|
||||
|
||||
## Pagine correlate
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Dashboard
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M3)
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 (milestone M3)
|
||||
> **Modulo di licenza:** CORE (alcuni widget richiedono il modulo dell'area, ad esempio CRM) · **Specifica:** SPEC §10.3, §11.12
|
||||
|
||||
La **dashboard** è la pagina *Home*: una griglia di **widget** che riassume che cosa c'è da fare oggi, che cosa è
|
||||
@@ -17,17 +17,33 @@ diversamente in *Pagina iniziale*.
|
||||

|
||||
*Mockup 004 — dashboard con saluto e data, KPI, Da fare oggi, Fatto oggi, Scadenze prossimi 30 giorni, Da evadere, Fatturato 12 mesi (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la dashboard predefinita di un super utente. Indicatori, Da evadere e Fatturato 12 mesi si accendono quando arrivano i dati (vendite, M5).*
|
||||
|
||||

|
||||
*Mockup 005 — la stessa dashboard in tema scuro (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la stessa dashboard in tema scuro.*
|
||||
|
||||

|
||||
*Mockup 006 — modalità Personalizza: widget con bordo tratteggiato e pannello laterale con pagina iniziale ed elenco dei widget attivabili (anteprima ridotta).*
|
||||
|
||||
In testa alla pagina: il saluto (*Buongiorno Alberto*) con la data, a destra **Personalizza** e **Nuovo documento**.
|
||||

|
||||
*Khaemhat 0.3.0 — Personalizza: widget con bordo tratteggiato e comandi di spostamento e larghezza, pannello con pagina iniziale ed elenco dei widget.*
|
||||
|
||||
In testa alla pagina: il saluto (*Buongiorno Alberto*, *Buon pomeriggio*, *Buonasera*) con la data, a destra
|
||||
**Personalizza**. Il pulsante **Nuovo documento** arriva con le vendite (M5).
|
||||
|
||||
## Widget disponibili
|
||||
|
||||
La griglia ha 12 colonne; ogni widget può occupare 3, 4, 6, 8 o 12 colonne.
|
||||
La griglia ha 12 colonne; ogni widget può occupare 3, 4, 6, 8 o 12 colonne (sotto i 1000 px di larghezza ogni
|
||||
widget prende tutta la riga).
|
||||
|
||||
Nella versione 0.3.0 hanno già dati **Da fare oggi**, **Fatto oggi**, **Scadenze 30 giorni**, **Promemoria
|
||||
personali**, **Scorciatoie** e **Stato del sistema**. Gli altri si possono già accendere, mettere in ordine e
|
||||
dimensionare: finché il loro modulo non c'è dicono con quale versione arrivano i dati (*Vendite* M5, *Acquisti e
|
||||
magazzino* M6, *CRM* M11), senza numeri finti.
|
||||
|
||||
| Widget | Cosa mostra | Note |
|
||||
|---|---|---|
|
||||
@@ -43,38 +59,63 @@ La griglia ha 12 colonne; ogni widget può occupare 3, 4, 6, 8 o 12 colonne.
|
||||
| **Sottoscorta** | articoli sotto la scorta minima | |
|
||||
| **Pipeline CRM** | valore delle opportunità per fase | richiede il modulo CRM |
|
||||
| **Ultimi documenti** | ultimi documenti aperti o creati | |
|
||||
| **Stato sistema** | stato dell'istanza (database, backup, scheduler) | solo amministratori |
|
||||
| **Stato del sistema** | versione, database, cache, licenza, aziende aperte, attività programmate di oggi, ognuno con un pallino verde, giallo o rosso | solo account di istanza |
|
||||
|
||||
Ogni widget ha in alto a destra un menu **⋯** con le azioni proprie (ad esempio aggiornare o aprire l'elenco
|
||||
completo). I dati rispettano i permessi: un utente che non vede costi e margini non li trova nemmeno nei widget.
|
||||
Ogni widget ha in alto a destra le sue azioni: il numero di righe nelle liste, la matita delle **Scorciatoie** (scegli
|
||||
fino a 12 pagine fra quelle che puoi aprire), il cestino dei **Promemoria** che toglie quelli spuntati. Un clic su una
|
||||
riga di *Da fare oggi*, *Fatto oggi* o *Scadenze* apre la pagina giusta. I dati rispettano i permessi: un utente che
|
||||
non vede costi e margini non li trova nemmeno nei widget.
|
||||
|
||||
Nella versione 0.3.0 le righe vengono da:
|
||||
|
||||
| Widget | Righe |
|
||||
|---|---|
|
||||
| Da fare oggi | licenza scaduta, in tolleranza o in scadenza entro 7 giorni (account di istanza); avvisi non letti di livello *attenzione* o *errore*; attività programmate la cui ultima esecuzione di oggi non è riuscita (account di istanza) |
|
||||
| Fatto oggi | attività programmate riuscite oggi, una riga per attività con il numero di esecuzioni e l'ora dell'ultima |
|
||||
| Scadenze 30 giorni | fine della prova o scadenza della licenza (account di istanza) |
|
||||
|
||||
I moduli delle prossime versioni aggiungono le loro righe (scarti SDI, liquidazioni, incassi, ordini da evadere…).
|
||||
Se una fonte non risponde, il widget mostra le altre e l'errore finisce nel [log](Log).
|
||||
|
||||
I **promemoria** si scrivono nel campo in fondo al widget e si aggiungono con Invio (al massimo 20, di 300 caratteri
|
||||
ciascuno); la casella li segna come fatti, la **×** li toglie.
|
||||
|
||||
## Come si personalizza
|
||||
|
||||
1. Premi **Personalizza** in alto a destra. I widget si contornano con un bordo tratteggiato e si apre il pannello
|
||||
laterale **Personalizza dashboard**.
|
||||
2. Nel pannello, sezione **Widget (trascina per ordinare)**, attiva o disattiva ciascun widget con l'interruttore e
|
||||
trascinalo per cambiarne l'ordine.
|
||||
3. Sulla griglia trascina i widget per spostarli e ridimensionali (3, 4, 6, 8 o 12 colonne).
|
||||
4. Imposta, se vuoi, il periodo dei KPI.
|
||||
5. Chiudi il pannello: la disposizione è salvata.
|
||||
laterale **Personalizza dashboard**; la pagina resta utilizzabile e, sugli schermi larghi almeno 1280 px, si
|
||||
stringe per lasciare spazio al pannello.
|
||||
2. Nel pannello, sezione **Widget**, accendi o spegni ciascun widget con l'interruttore; per quelli accesi scegli la
|
||||
larghezza (*Un quarto*, *Un terzo*, *Metà*, *Due terzi*, *Tutta la riga*) e spostali con le frecce. Un widget
|
||||
acceso si aggiunge in fondo.
|
||||
3. Sulla griglia trascina un widget sopra un altro per prenderne il posto. Ogni widget ha anche i pulsanti
|
||||
**‹ ›** (sposta prima o dopo), **− +** (più stretto o più largo) e **×** (nascondi): tutto si fa anche da tastiera.
|
||||
4. **Ripristina** cancella la tua disposizione: torna quella predefinita del tuo ruolo o, se non c'è, quella di
|
||||
Khaemhat. **Fine** (o Esc) chiude il pannello.
|
||||
|
||||
Disposizione e scelte sono salvate nelle tue preferenze (sul database dell'azienda): le ritrovi su ogni dispositivo.
|
||||
Ogni modifica si salva subito nelle tue preferenze: la ritrovi su ogni dispositivo. Il pannello dice da dove viene la
|
||||
disposizione che stai usando (tua, del ruolo o di Khaemhat).
|
||||
|
||||
## Pagina iniziale e dashboard disattivabile
|
||||
|
||||
La dashboard si può **spegnere**. Nel pannello *Personalizza* (sezione **Pagina iniziale**) o in
|
||||
[Il mio profilo → Pagina iniziale](Preferenze-utente) scegli:
|
||||
|
||||
- **All'accesso apri**: *Dashboard*, oppure l'*ultima scheda aperta*, un *radar* (ad esempio *Clienti*), la *prima
|
||||
nota*, l'*agenda CRM*…
|
||||
- **Pagina da aprire**: *La pagina iniziale* (la dashboard), l'*ultima scheda aperta* o una delle pagine che puoi
|
||||
aprire (ad esempio *Clienti*).
|
||||
- **Mostra la dashboard**: se disattivato, la voce *Home* non mostra più i widget e all'accesso si apre la pagina
|
||||
scelta.
|
||||
|
||||
## Layout per ruolo
|
||||
|
||||
Gli amministratori possono definire un **layout predefinito per ruolo** (ad esempio un layout per *Vendite*, uno per
|
||||
*Contabilità*): un nuovo utente parte dal layout del proprio ruolo e può poi modificarlo per sé. La maschera di
|
||||
gestione dei layout per ruolo sarà definita in sviluppo (vedi [Utenti e permessi](Utenti-e-permessi)).
|
||||
Chi ha il permesso **Modificare le impostazioni dell'azienda** (`company.settings.write`, ad esempio il ruolo
|
||||
*Amministrazione*) trova in fondo al pannello la sezione **Predefinito per ruolo**: sceglie un ruolo e preme **Usa
|
||||
questo layout per il ruolo** per dargli la disposizione che ha sulla pagina in quel momento; **Togli il predefinito**
|
||||
lo riporta a quello di Khaemhat. I ruoli che hanno un predefinito sono segnati nell'elenco.
|
||||
|
||||
Chi non ha mai personalizzato la dashboard parte dal predefinito del suo ruolo (se ha più ruoli, il primo assegnato
|
||||
che ne ha uno); appena cambia qualcosa la disposizione diventa sua. I predefiniti dei ruoli sono impostazioni
|
||||
dell'azienda: ogni azienda ha i suoi. La sezione compare solo quando lavori in un'azienda.
|
||||
|
||||
## Permessi e licenza
|
||||
|
||||
@@ -85,9 +126,10 @@ se l'utente ha i permessi di lettura su quei dati; *Stato sistema* è riservato
|
||||
|
||||
- **Un widget non compare nell'elenco.** Il modulo relativo (ad esempio CRM) non è licenziato o non hai il permesso
|
||||
di vederne i dati.
|
||||
- **Voglio tornare alla disposizione iniziale.** Un comando per ripristinare il layout del ruolo non è ancora
|
||||
definito nella specifica; sarà deciso in sviluppo e documentato qui. Nel frattempo riattiva o riordina i widget
|
||||
da *Personalizza*.
|
||||
- **Voglio tornare alla disposizione iniziale.** *Personalizza* → **Ripristina**: torna il predefinito del tuo ruolo
|
||||
o quello di Khaemhat.
|
||||
- **Ho spento la dashboard e voglio riaccenderla.** La *Home* mostra in alto **Mostra la dashboard**; in alternativa
|
||||
[Il mio profilo → Pagina iniziale](Preferenze-utente).
|
||||
- **"Da fare oggi" mostra cose che non riguardano il mio lavoro.** L'elenco segue i tuoi permessi; se vedi voci non
|
||||
pertinenti, chiedi all'amministratore di verificare il tuo ruolo.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Dati di base e di esempio
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4; dati di esempio 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
|
||||
@@ -21,26 +21,26 @@ alto a destra, es. *Database: khaemhat_demo*).
|
||||
|
||||
*Mockup 089 — riepilogo di tabelle di base, dati di esempio, documenti reali e utenti demo con i pulsanti **Aggiorna
|
||||
tabelle di base**, **Carica dati di esempio**, **Rimuovi dati di esempio**, **Anteprima differenze**; a destra le
|
||||
ultime migrazioni; sotto, i **pacchetti di dati di base** della versione `IT 2026.2` con contenuto, righe e stato
|
||||
ultime migrazioni; sotto, i **pacchetti di dati di base** della versione `IT 2026.3` con contenuto, righe e stato
|
||||
(anteprima ridotta)*
|
||||
|
||||
Il riepilogo mostra:
|
||||
|
||||
| Voce | Esempio |
|
||||
|---|---|
|
||||
| **Tabelle di base** | versione del pacchetto (`IT 2026.2`), righe, data dell'ultimo aggiornamento |
|
||||
| **Tabelle di base** | versione del pacchetto (`IT 2026.3`), righe, data dell'ultimo aggiornamento |
|
||||
| **Dati di esempio** | *presenti* con i conteggi (clienti, fornitori, articoli, documenti, registrazioni, cespiti, lead) oppure *assenti* |
|
||||
| **Documenti reali** | numero di documenti non dimostrativi (0 in un'azienda demo) |
|
||||
| **Utenti demo** | utenti dimostrativi e relativa password |
|
||||
|
||||
## Le tabelle di base
|
||||
|
||||
Sono raccolte in **pacchetti** con una **versione** (oggi `IT 2026.2`, salvata nelle impostazioni dell'azienda).
|
||||
Sono raccolte in **pacchetti** con una **versione** (oggi `IT 2026.3`, salvata nelle impostazioni dell'azienda).
|
||||
Il pacchetto italiano fa parte del pacchetto fiscale Italia (vedi [Fiscalità italiana](Fiscalita-italiana)).
|
||||
|
||||
| Pacchetto | Contenuto |
|
||||
|---|---|
|
||||
| **Paesi e comuni** | paesi ISO, province, comuni con CAP e codice catastale |
|
||||
| **Paesi e comuni** | paesi ISO, province, comuni con codice catastale, codice ISTAT e CAP |
|
||||
| **Valute e unità di misura** | valute, unità di misura |
|
||||
| **Codici IVA e nature** | aliquote 22, 10, 5, 4; esenti (ESE10 N4); non imponibili (NI8 N3.1, NI41 N3.2, NI71 N3.3, NI8C N3.5); fuori campo (FC7 N2.1, altre N2.2); escluse (ESC15 N1); reverse charge (RC17 N6.x); split payment; non soggette; indetraibili 50% e 100%; forfettari |
|
||||
| **Modalità e condizioni di pagamento** | modalità `MP01`-`MP23`, condizioni di pagamento |
|
||||
@@ -56,6 +56,32 @@ Il pacchetto italiano fa parte del pacchetto fiscale Italia (vedi [Fiscalità it
|
||||
| **CRM** | pipeline e fasi, modelli e-mail |
|
||||
| **Sistema** | ruoli predefiniti, regole di automazione predefinite, attività programmate di sistema |
|
||||
|
||||
### Cosa c'è oggi
|
||||
|
||||
Dalla versione 0.4.0 il caricamento di base contiene: paesi ISO con appartenenza all'UE, le 30 valute dei cambi BCE,
|
||||
unità di misura, codici IVA e nature, modalità `MP01`-`MP23` e condizioni di pagamento con le rate, tipi documento
|
||||
con codice TD, numeratori, causali di magazzino, deposito principale, porti, trasporto a cura, causali di trasporto,
|
||||
aspetto dei beni, rese, categorie, listino base e l'esercizio dell'anno in corso con i suoi mesi. Le righe fiscali
|
||||
vengono dal pacchetto del paese dell'azienda.
|
||||
|
||||
**Province e comuni** (dalla versione `IT 2026.3`) vengono dall'elenco ISTAT dei codici dei comuni aggiornato al
|
||||
26/02/2026: 110 province con sigla e regione, 7.894 comuni con codice catastale, provincia, regione e codice ISTAT.
|
||||
Il **codice** di un comune è il suo codice catastale (es. `H501` per Roma), lo stesso del codice fiscale.
|
||||
I **CAP** vengono dall'elenco dei codici postali di GeoNames e ci sono per 7.750 comuni: un CAP, una lista o un
|
||||
intervallo come `10121-10156` per le città con più CAP.
|
||||
|
||||
> Fonti: ISTAT, *Codici statistici delle unità amministrative territoriali*, e GeoNames
|
||||
> ([www.geonames.org](https://www.geonames.org)), entrambi con licenza
|
||||
> [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.it).
|
||||
|
||||
Ai comuni rinominati o nati da fusioni recenti (ad esempio Sanremo) il CAP può mancare: si completa a mano nella
|
||||
tabella *Comuni* o con l'**Importa CSV** (colonne `Code` e `PostalCodes`, più CAP separati da virgola). La
|
||||
compilazione dal CAP propone solo i comuni che hanno il CAP scritto. Le **banche ABI/CAB** non sono ancora incluse: banca e BIC dall'IBAN vengono da un conto
|
||||
dell'azienda presso la stessa banca. Un comune soppresso per fusione resta nella tabella finché non lo disattivi.
|
||||
|
||||
Le altre voci dell'elenco (piano dei conti, causali contabili, registri IVA, cespiti, codici tributo, CRM) arrivano con i
|
||||
moduli che le usano.
|
||||
|
||||
### Aggiorna tabelle di base
|
||||
|
||||
Ogni nuova versione di Khaemhat può portare un pacchetto aggiornato (nuovi codici IVA, nuovi tipi documento SDI,
|
||||
@@ -64,8 +90,12 @@ nuovi codici tributo…).
|
||||
1. Premi **Anteprima differenze** per vedere cosa cambierebbe.
|
||||
2. Premi **Aggiorna tabelle di base**.
|
||||
|
||||
L'aggiornamento è **idempotente** (rieseguirlo non duplica nulla) e **aggiunge solo i codici mancanti senza
|
||||
toccare le righe che l'azienda ha modificato**.
|
||||
L'aggiornamento è **idempotente** (rieseguirlo non duplica nulla) e **aggiunge solo i codici mancanti**: una riga
|
||||
già presente non viene mai modificata né cancellata, anche se l'azienda non l'ha mai toccata. Se una nuova versione
|
||||
corregge un codice esistente (ad esempio un riferimento normativo), il [CHANGELOG](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/CHANGELOG.md)
|
||||
lo segnala e la correzione si fa nella tabella. La versione caricata è salvata nelle impostazioni dell'azienda.
|
||||
|
||||
Lo stesso aggiornamento si avvia dal menu `…` di ogni tabella con **Aggiorna da tabelle base**.
|
||||
|
||||
Le tabelle di base si caricano anche automaticamente alla creazione di un'azienda, se la variabile
|
||||
`KHAEMHAT_SEED_BASE` non è `false` (predefinito `true`).
|
||||
@@ -94,6 +124,31 @@ reale. Contiene:
|
||||
| Log | voci di log di esempio in tutte le sezioni |
|
||||
|
||||
Tutte le righe dimostrative sono marcate come tali (`is_demo`), così si possono rimuovere senza toccare il resto.
|
||||
|
||||
**Oggi (M4)** i dati di esempio contengono 3 agenti e **21 anagrafiche**: 12 clienti che coprono tutti i tipi
|
||||
soggetto (fra cui un comune con split payment, un cliente bloccato, uno disattivato, uno che è anche fornitore e
|
||||
uno con dichiarazione d'intento), 5 fornitori (professionista con ritenuta, agente ENASARCO, fornitore UE),
|
||||
2 prospect e 2 lead. Partite IVA, codici fiscali e IBAN sono numeri inventati ma formalmente validi, perché passino
|
||||
i controlli; non si verificano sul VIES (ADR 0029). Gli agenti di esempio non sono marcati e si rimuovono a mano.
|
||||
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.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -125,14 +180,29 @@ esempio.
|
||||
|
||||
## Da riga di comando
|
||||
|
||||
Lo script `scripts/seed.sh` esegue le stesse operazioni fuori dall'interfaccia (utile in sviluppo):
|
||||
Lo script `scripts/seed.sh` aggiunge le tabelle di base e i dati di esempio fuori dall'interfaccia. Esegue la sequenza di avvio
|
||||
(migrazioni, prima azienda) senza servire pagine, poi lavora su un'azienda o su tutte quelle attive e stampa le righe
|
||||
aggiunte per tabella. Usa le stesse variabili `KHAEMHAT_*` del servizio.
|
||||
|
||||
Nel container (lo script è in `/app/scripts/`):
|
||||
|
||||
```
|
||||
scripts/seed.sh --base
|
||||
scripts/seed.sh --demo [--scale N] [--company CODICE]
|
||||
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --base
|
||||
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --base --company DEMO
|
||||
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --demo --company DEMO
|
||||
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --demo --scale 10 --company PROVA
|
||||
```
|
||||
|
||||
`--scale N` moltiplica i volumi dei dati di esempio (usato per le prove di prestazione).
|
||||
In sviluppo, dalla cartella del repository: `scripts/seed.sh --base|--demo [--scale N] [--company CODICE]`.
|
||||
|
||||
| Opzione | Effetto |
|
||||
|---|---|
|
||||
| `--base` | aggiunge i codici di base mancanti |
|
||||
| `--demo` | prima i dati di base, poi i dati di esempio; ogni gruppo (anagrafiche, articoli) si carica solo nell'azienda che non ne ha ancora |
|
||||
| `--scale N` | solo con `--demo`: ripete il catalogo articoli N volte (da 1 a 100), per le prove di prestazione |
|
||||
| `--company CODICE` | lavora solo su quell'azienda invece che su tutte quelle attive |
|
||||
|
||||
I dati di esempio si caricano anche al primo avvio con `KHAEMHAT_SEED_DEMO=true`.
|
||||
|
||||
## Migrazioni
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Design UI
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M3)
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 (milestone M3)
|
||||
> **Pagina per chi sviluppa** · **Specifica:** SPEC §10 (in particolare §10.1, §10.6, §10.7, §10.8), Appendice A
|
||||
|
||||
Questa pagina è il riferimento visivo per chi sviluppa l'interfaccia di Khaemhat: come si usano i mockup, i token di
|
||||
@@ -31,7 +31,18 @@ Regole vincolanti (SPEC §10.1):
|
||||
|
||||
Solo 23 schermate sono disponibili in alta risoluzione; per le altre si lavora dalla miniatura, da `mockup.css` e
|
||||
dalla descrizione in SPEC §10-§12 (emendamento E4 in `CLAUDE.md`). Gli screenshot reali in `docs/wiki/img/`
|
||||
sostituiscono progressivamente i mockup nelle pagine della wiki.
|
||||
affiancano i mockup nelle pagine della wiki: dalla versione 0.3.0 ci sono la shell, la dashboard, il profilo, l'aiuto,
|
||||
le notifiche, il documento di prova con allegati e storico e l'anteprima di stampa.
|
||||
|
||||
Gli screenshot si rifanno su un'istanza nuova (database SQLite vuoto, azienda DEMO, tema chiaro, finestra
|
||||
1440x900, telefono 390x844), così non mostrano dati o notifiche di prova; i nomi dei file sono quelli usati dalle
|
||||
pagine, ad esempio `interfaccia-home.png` o `allegati-pannello.png`.
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — i mattoni di 020 e 021 dal vero: toolbar a icone, intestazione documento, schede interne, griglia delle righe.*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la dashboard con tema scuro e accento Nilo.*
|
||||
|
||||
## Token di design
|
||||
|
||||
@@ -91,8 +102,8 @@ Altre preferenze di presentazione: dimensione del testo, carattere numerico tabe
|
||||
`AccentColor`, `Density`, `MenuState`). `ThemeService` e `MenuStateService` applicano gli attributi senza ricaricare
|
||||
la pagina.
|
||||
|
||||
`mockup.css` **non contiene ancora i valori del tema alto contrasto**: vanno definiti in `tokens.css` rispettando il
|
||||
contrasto AAA, con gli stessi nomi di token, e documentati in questa pagina.
|
||||
`mockup.css` non contiene i valori del tema **alto contrasto**: sono definiti in `tokens.css` con gli stessi nomi di
|
||||
token (testo nero su bianco, bordi neri, un solo accento blu scuro per tutti gli accenti), per il contrasto AAA.
|
||||
|
||||
## Classi dei mockup e componenti `Kh*`
|
||||
|
||||
@@ -154,6 +165,20 @@ radar, `Ctrl+Invio` apre, creazione al volo; `KhGrid` con colonne tipizzate, ord
|
||||
server, virtualizzazione, selezione multipla, editing inline, riga dei totali, layout colonne salvato, export,
|
||||
evidenziazioni, menu di riga.
|
||||
|
||||
## File CSS
|
||||
|
||||
| File | Contenuto |
|
||||
|---|---|
|
||||
| `css/tokens.css` | token `--kh-*` di `mockup.css`, temi (automatico, chiaro, scuro, alto contrasto), accenti, densità, dimensioni del testo; generato da `mockup.css` |
|
||||
| `css/components.css` | classi dei mockup (shell, toolbar, pannelli, campi, griglie, badge, dialoghi…), riprese da `mockup.css` |
|
||||
| `css/interactive.css` | ciò che i mockup statici non hanno: reset dei pulsanti, focus, suggerimenti, menu a comparsa, schede, notifiche a scomparsa, interruttori `data-*` |
|
||||
| `css/print.css` | stampa sempre in chiaro, shell nascosta |
|
||||
| `app.css` | pagine costruite finora (accesso, home, profilo, messaggi) |
|
||||
|
||||
Gli attributi sull'elemento `<html>` comandano l'aspetto: `data-theme` (`auto`, `light`, `dark`, `high-contrast`),
|
||||
`data-accent`, `data-density`, `data-text-size` (`100`, `110`, `120`), `data-tabular`, `data-motion`,
|
||||
`data-tooltips`, `data-row-hover`. Il server li scrive dalle preferenze dell'utente; il profilo li cambia dal vivo.
|
||||
|
||||
## Shell
|
||||
|
||||
- Griglia: barra superiore 46 px, area centrale, barra di stato 24 px; menu 228 px (60 px compresso).
|
||||
@@ -162,7 +187,9 @@ evidenziazioni, menu di riga.
|
||||
- **Menu**: sezioni in maiuscoletto (`.sec`), voce attiva su `--kh-accent-soft`; compresso: solo icone 20 px, barretta
|
||||
d'accento a sinistra della voce attiva, sottomenu in `.flyout` (min 190 px, ombra grande). Pulsante **Comprimi
|
||||
menu** tratteggiato in fondo. Sotto 1100 px parte compresso; stato salvato per utente.
|
||||
- **Schede** (`.wtab`): altezza 30 px, massimo 260 px di larghezza, pallino `--kh-warn` se modificata.
|
||||
- **Schede** (`.wtab`): altezza 30 px, massimo 260 px di larghezza, pallino `--kh-warn` se modificata. Ogni pagina
|
||||
imposta il titolo della sua scheda con `<KhPageTitle Text="..." Icon="..." />` e segnala le modifiche con il
|
||||
`KhTab` in cascata (`Tab?.SetModified(true)`).
|
||||
- **Barra di stato**: testo 11.5 px, pallino `--kh-ok` per la connessione.
|
||||
|
||||
Dettagli d'uso in [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie).
|
||||
@@ -211,17 +238,26 @@ dal testo. Nessuna libreria di icone esterna. L'icona dell'applicazione è descr
|
||||
**nessun font scaricato**, nessuna CDN.
|
||||
- **Focus sempre visibile**, etichette collegate ai campi (`<label for>`), contrasto **AA** (AAA nel tema alto
|
||||
contrasto), tutto operabile da tastiera.
|
||||
- Desktop-first, usabile da tablet a partire da **768 px**.
|
||||
- **Testi**: nessun testo hard-coded nei componenti (verificato da un test di architettura); `ITexts` risolve chiavi
|
||||
come `Sales.Invoice.Title` da `Resources/it-IT/*.json`.
|
||||
- Desktop-first, usabile da tablet a partire da **768 px** e su telefono con la barra superiore a sole icone (vedi [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie)).
|
||||
- **Nomi di classe unici**: una classe dei mockup ha un solo significato. Se un componente ha bisogno di una variante, usa un nome nuovo (`kh-…`) invece di riusarne uno esistente: in 0.3.0 `.tl` (timeline) e `.kh-choices` usati in due sensi diversi spostavano l'etichetta del totale documento e le schede dei temi.
|
||||
- **Testi**: nessun testo hard-coded nei componenti; `ITexts` (iniettato in ogni componente come `T`) risolve chiavi
|
||||
come `Shell.Menu.Parties` da `src/Khaemhat.Web/Resources/it-IT/*.json` (risorse incorporate). Gli oggetti annidati
|
||||
danno le chiavi puntate, la proprietà `_` dà il testo all'oggetto che ha figli, una chiave doppia blocca l'avvio e
|
||||
una mancante appare come `[chiave]`. Uso: `@T["Pages.Profile.Title"]`, `@T.Format("Pages.Home.Coming", "M4")`,
|
||||
`T.Money(1234.5m)`, `T.Date(...)`. Due test lo garantiscono: nessun testo letterale fra i tag e negli attributi
|
||||
`title`, `placeholder`, `alt`, `aria-label`, `label` dei `.razor`, e ogni chiave usata esiste (ADR 0020).
|
||||
- **Formati**: `CultureInfo("it-IT")` per numeri, importi e date; date memorizzate in UTC e mostrate nel fuso
|
||||
`Europe/Rome`.
|
||||
|
||||
## Stampa
|
||||
|
||||
Le stampe e i PDF sono **sempre in tema chiaro** (`print.css`), indipendentemente dal tema dell'utente. L'anteprima
|
||||
usa `.paper` (pagina bianca larga 794 px, cioè un A4 a 96 dpi, margini 40/44 px, tabelle con intestazione in
|
||||
maiuscoletto e bordo inferiore marcato).
|
||||
Le stampe e i PDF sono **sempre in tema chiaro** (`print.css`), indipendentemente dal tema dell'utente. L'anteprima di
|
||||
stampa (`KhPrintPreview`, mockup 025) mostra il documento come foglio `.kh-sheet` largo 210 mm e alto almeno 297 mm,
|
||||
con ingrandimento 75/100/125%; `@media print` nasconde tutto tranne il foglio e imposta `@page` A4 senza margini.
|
||||
La classe `.paper` di `mockup.css` resta per le anteprime piccole dentro le pagine.
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — l'anteprima di stampa del documento di prova.*
|
||||
|
||||
## Regola di aggiornamento
|
||||
|
||||
|
||||
@@ -1,13 +1,13 @@
|
||||
# Fiscalità italiana
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4-M10)
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.4.0 (codici e regole di base; il resto con M5-M10)
|
||||
> **Modulo di licenza:** CORE, ACCT, EINV, INTRA · **Specifica:** SPEC §11.1, §11.3-§11.9, §14
|
||||
|
||||
Questa pagina raccoglie in un solo posto i **codici e le regole fiscali italiane** che Khaemhat usa: tipi documento
|
||||
SDI, nature IVA, modalità e condizioni di pagamento, regimi fiscali, codici tributo F24 e scadenze. Serve come
|
||||
riferimento rapido mentre si compilano anagrafiche, codici IVA e documenti.
|
||||
|
||||
Tutte queste tabelle sono **caricate dai dati di base** (pacchetto dati, per esempio `IT 2026.2`) e si aggiornano da
|
||||
Tutte queste tabelle sono **caricate dai dati di base** (pacchetto dati, per esempio `IT 2026.3`) e si aggiornano da
|
||||
**Amministrazione → Dati di base e di esempio** con **Aggiorna tabelle di base**. Le descrizioni ufficiali complete
|
||||
sono quelle delle *specifiche tecniche della fattura elettronica* dell'Agenzia delle Entrate, caricate nel seed: in
|
||||
caso di dubbio fa fede il testo mostrato dal programma, non questa pagina.
|
||||
@@ -58,6 +58,9 @@ caso di dubbio fa fede il testo mostrato dal programma, non questa pagina.
|
||||
| TD28 | Acquisti da San Marino con IVA (fattura cartacea) | acquisti |
|
||||
| TD29 | Comunicazione per omessa o irregolare fatturazione | regolarizzazione (introdotto con le specifiche v1.9) |
|
||||
|
||||
Versione delle specifiche tecniche seguita: **1.9.1** (pubblicata dall'Agenzia il 31 marzo 2026, in vigore dal
|
||||
15 maggio 2026; non cambia le code list della 1.9, che ha introdotto TD29 e ridefinito TD20).
|
||||
|
||||
Formati di trasmissione: **FPR12** (verso privati), **FPA12** (verso pubbliche amministrazioni), **FSM10** (fattura
|
||||
semplificata). Nome del file: `IT<partita IVA>_<progressivo>.xml`.
|
||||
|
||||
@@ -70,7 +73,7 @@ codice IVA sulla riga del documento la natura viene compilata da sola.
|
||||
|---|---|---|
|
||||
| N1 | Escluse ex art. 15 DPR 633/72 | `ESC15` |
|
||||
| N2.1 | Non soggette ad IVA ai sensi degli artt. da 7 a 7-septies DPR 633/72 | `FC7` |
|
||||
| N2.2 | Non soggette - altri casi | fuori campo altre (anche fatture da forfettari) |
|
||||
| N2.2 | Non soggette - altri casi | `NS`, `FORF` (operazioni in regime forfettario) |
|
||||
| N3.1 | Non imponibili - esportazioni | `NI8` |
|
||||
| N3.2 | Non imponibili - cessioni intracomunitarie | `NI41` |
|
||||
| N3.3 | Non imponibili - cessioni verso San Marino | `NI71` |
|
||||
@@ -79,11 +82,25 @@ codice IVA sulla riga del documento la natura viene compilata da sola.
|
||||
| N3.6 | Non imponibili - altre operazioni che non concorrono alla formazione del plafond | — |
|
||||
| N4 | Esenti | `ESE10` |
|
||||
| N5 | Regime del margine / IVA non esposta in fattura | — (regime del margine previsto in fase 2) |
|
||||
| N6.1 … N6.9 | Inversione contabile (reverse charge): rottami (N6.1), oro e argento (N6.2), subappalto edile (N6.3), cessione di fabbricati (N6.4), telefoni cellulari (N6.5), prodotti elettronici (N6.6), prestazioni comparto edile e connessi (N6.7), settore energetico (N6.8), altri casi (N6.9) | `RC17` (varianti per sotto-codice) |
|
||||
| N6.1 … N6.9 | Inversione contabile (reverse charge): rottami (N6.1), oro e argento (N6.2), subappalto edile (N6.3), cessione di fabbricati (N6.4), telefoni cellulari (N6.5), prodotti elettronici (N6.6), prestazioni comparto edile e connessi (N6.7), settore energetico (N6.8), altri casi (N6.9) | `RC74` (N6.1), `RC17O` (N6.2), `RC17A` (N6.3), `RC17F` (N6.4), `RC17B` (N6.5), `RC17C` (N6.6), `RC17E` (N6.7), `RC17N` (N6.8), `RC17` (N6.9) |
|
||||
| N7 | IVA assolta in altro stato UE | — |
|
||||
|
||||
Altri codici IVA di base: aliquote **22**, **10**, **5**, **4**; **SPLIT** (scissione dei pagamenti), **NS**,
|
||||
**indetraibili 50% e 100%**, codici per **forfettari**.
|
||||
Altri codici IVA di base: aliquote **22**, **10**, **5**, **4**; **22SP** e **10SP** (scissione dei pagamenti,
|
||||
esigibilità S); **22I50** e **22I100** (IVA 22% indetraibile al 50% e al 100%).
|
||||
|
||||
I codici N2, N3 e N6 senza sotto-codice non sono più accettati dallo SDI: Khaemhat li riconosce nei documenti vecchi
|
||||
ma non li lascia scegliere su un codice IVA nuovo.
|
||||
|
||||
**Controlli sul codice IVA.** Salvando un codice IVA Khaemhat verifica che:
|
||||
|
||||
- un'aliquota maggiore di zero non abbia natura e un'aliquota zero ce l'abbia;
|
||||
- la natura esista e sia ancora valida;
|
||||
- la scissione dei pagamenti abbia un'aliquota;
|
||||
- l'inversione contabile (N6.x) abbia esigibilità immediata;
|
||||
- la percentuale di indetraibilità sia fra 0 e 100.
|
||||
|
||||
Sono solo **avvisi** (il codice si salva) un'aliquota diversa da 4, 5, 10 e 22 (per esempio le percentuali di
|
||||
compensazione agricole) e la mancanza del riferimento normativo, che va stampato in fattura quando c'è la natura.
|
||||
|
||||
**Esigibilità** (campo del codice IVA): **I** immediata, **D** differita, **S** scissione dei pagamenti (split
|
||||
payment).
|
||||
@@ -181,12 +198,13 @@ Khaemhat propone il codice tributo e prepara i **dati F24** da passare a interme
|
||||
| Adempimento | Regola | Note in Khaemhat |
|
||||
|---|---|---|
|
||||
| Liquidazione IVA mensile | versamento entro il **16 del mese successivo** | la conferma della liquidazione **blocca il periodo** |
|
||||
| Liquidazione IVA trimestrale | versamento entro il 16 del secondo mese successivo al trimestre (per il secondo trimestre vale la proroga estiva di agosto), con **interessi dell'1%**; il quarto trimestre si versa con il saldo annuale | interessi calcolati in automatico |
|
||||
| Liquidazione IVA trimestrale | versamento entro il 16 del secondo mese successivo al trimestre (per il secondo trimestre vale la proroga estiva di agosto), con **interessi dell'1%**; il quarto trimestre si versa con il saldo annuale entro il 16 marzo | interessi calcolati in automatico |
|
||||
| Scadenze in agosto e nei festivi | i versamenti fra il 1° e il 20 agosto slittano al **20 agosto**; una scadenza di sabato, domenica o festivo slitta al primo giorno lavorativo | festivi nazionali, Pasquetta e, dal 2026, il 4 ottobre |
|
||||
| Versamento minimo | importo fino a **€ 25,82** non versato e riportato al periodo successivo | valore della specifica; da verificare in sviluppo rispetto alla norma vigente |
|
||||
| Acconto IVA | entro il **27 dicembre**; metodo **storico**, **previsionale** o **analitico** | scelta del metodo nella liquidazione di dicembre |
|
||||
| LIPE | 1° trimestre entro 31 maggio, 2° entro 16 settembre, 3° entro 30 novembre, 4° entro fine febbraio (o nella dichiarazione annuale) | XML LIPE generato dalla liquidazione |
|
||||
| Ritenute d'acconto operate | versamento entro il **16 del mese successivo** al pagamento della parcella (1040/1038) | la ritenuta nasce al pagamento della fattura |
|
||||
| Imposta di bollo | **€ 2,00** se le operazioni esenti, non imponibili o fuori campo superano **€ 77,47** | applicato in automatico; addebito al cliente o a carico azienda |
|
||||
| Imposta di bollo | **€ 2,00** se le operazioni esenti, non imponibili o fuori campo superano **€ 77,47** | contano le nature N1, N2.1, N2.2, N3.5, N3.6, N4, N5; non contano esportazioni (N3.1), cessioni intracomunitarie (N3.2), San Marino (N3.3), operazioni assimilate (N3.4), inversione contabile (N6.x) e N7 |
|
||||
| Bollo virtuale | versamento trimestrale: 1° trimestre entro 31 maggio, 2° entro 30 settembre, 3° entro 30 novembre, 4° entro fine febbraio; con importi bassi i primi trimestri possono slittare (soglia di € 5.000) | elenco da confrontare con quello proposto dall'Agenzia |
|
||||
| Autofatture e integrazioni (TD16-TD19) | XML da trasmettere **entro il 15 del mese successivo** | promemoria nella dashboard |
|
||||
| Fattura differita (TD24) | emissione entro il 15 del mese successivo a quello delle consegne documentate da DDT | procedura **Fatturazione differita** |
|
||||
|
||||
@@ -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-10 · **Versione software:** 0.0.1 (M0, pagina "in costruzione"; sviluppo in corso)
|
||||
> **Stato:** completa per 0.5.0 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0 (M5; sviluppo in corso)
|
||||
|
||||

|
||||
|
||||
@@ -12,14 +12,18 @@ Docker** e gestisce più aziende sulla stessa installazione.
|
||||
Il nome viene da uno scriba dell'antico Egitto che sovrintendeva ai granai del regno: vedi
|
||||
[Origine del nome](Origine-del-nome).
|
||||
|
||||
> Il software è **in fase di progettazione**: questa wiki descrive ciò che verrà costruito, milestone dopo
|
||||
> milestone. Ogni pagina indica nel riquadro iniziale lo stato (*bozza* finché la funzione non è consegnata) e la
|
||||
> Il software è **in sviluppo** (versioni 0.x): questa wiki descrive ciò che è già consegnato e ciò che verrà
|
||||
> costruito, milestone dopo milestone. Ogni pagina indica nel riquadro iniziale lo stato (*bozza* finché la funzione non è consegnata) e la
|
||||
> milestone in cui arriva. Vedi la [Roadmap](Roadmap).
|
||||
|
||||
## 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) |
|
||||
|
||||
@@ -1,103 +1,169 @@
|
||||
# Import/Export
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4; saldi e partite di apertura in M12)
|
||||
> **Modulo di licenza:** CORE (piano dei conti, saldi e partite: ACCT/FIN) · **Livello richiesto:** amministratore · **Specifica:** SPEC §11.7, §12.12
|
||||
> **Stato:** completa per M4 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.4.0 (scrittura di giacenze iniziali in M6, piano dei conti in M7; saldi e partite di apertura in M7 e M9)
|
||||
> **Modulo di licenza:** CORE (piano dei conti: ACCT) · **Livello richiesto:** amministratore, oppure permesso di scrittura o di export dell'entità · **Specifica:** SPEC §11.7, §12.12 · **Decisione:** ADR 0031
|
||||
|
||||
## A cosa serve
|
||||
|
||||
La procedura guidata di **Import/Export** porta in Khaemhat i dati che arrivano da un altro gestionale o da un
|
||||
foglio di calcolo e li esporta in formati aperti. È lo strumento per l'**avviamento** di un'azienda: anagrafiche,
|
||||
articoli, listini, giacenze iniziali, piano dei conti, saldi iniziali e partite aperte.
|
||||
articoli, prezzi, giacenze iniziali e piano dei conti.
|
||||
|
||||
## Dove si trova
|
||||
|
||||
**Amministrazione → Import/Export** (titolo: *Import / export dati*). Ogni importazione si apre in una scheda
|
||||
propria (es. *Import clienti*).
|
||||
**Amministrazione → Import / export dati** (indirizzo `/amministrazione/import-export`). Il tasto **F1** apre questa
|
||||
pagina.
|
||||
|
||||
## Schermata
|
||||
|
||||

|
||||
|
||||
*Mockup 077 — a sinistra i quattro passi della procedura guidata (Origine, Mappatura colonne, Validazione,
|
||||
Importazione) e le opzioni; a destra l'**Anteprima e validazione** con l'esito riga per riga; in alto **Scarica report
|
||||
errori** e **Importa N righe** (anteprima ridotta)*
|
||||
Importazione), le opzioni e il riquadro **Esporta e modelli**; a destra la mappatura o l'**Anteprima e validazione**
|
||||
con l'esito riga per riga; in alto **Scarica report errori** e **Importa N righe***
|
||||
|
||||

|
||||
*Khaemhat 0.4.0 — il passo Mappatura colonne con un CSV di clienti: le dieci colonne si abbinano da sole, anche *P.IVA*, *Città* e *Prov*.*
|
||||
|
||||

|
||||
*Khaemhat 0.4.0 — l'anteprima dello stesso file: un comune dedotto dal CAP (avviso), un cliente nuovo e tre righe escluse (partita IVA mancante ed e-mail non valida, codice ripetuto, pagamento inesistente).*
|
||||
|
||||
## Formati
|
||||
|
||||
| Formato | Uso |
|
||||
| Formato | Lettura | Scrittura (export e modelli) |
|
||||
|---|---|---|
|
||||
| **CSV** (`.csv`, `.txt`) | separatore `;`, `,` o tabulazione (dedotto dalla riga di intestazione); UTF-8 con o senza BOM, altrimenti Windows-1252 | `;`, UTF-8 con BOM, numeri con la virgola, date `gg/mm/aaaa`, sì/no come `VERO`/`FALSO` |
|
||||
| **XLSX** | il primo foglio, intestazioni nella prima riga | un foglio con le intestazioni bloccate |
|
||||
| **JSON** | un elenco di oggetti con le colonne come chiavi; per il piano dei conti anche `khaemhat-coa.json` | lo stesso elenco (numeri e sì/no come valori JSON) |
|
||||
|
||||
La prima riga contiene sempre le **intestazioni**. Le righe vuote si saltano. Al massimo **50.000 righe** e **25 MB**
|
||||
per file.
|
||||
|
||||
**Valori accettati in tutte le colonne:**
|
||||
|
||||
- **numeri** all'italiana (`1.234,56`, `€ 12,5`, `22 %`) o con il punto decimale (`1234.56`, come li scrivono Excel e
|
||||
JSON);
|
||||
- **date** `gg/mm/aaaa` (anche `g/m/aa`, `gg-mm-aaaa`, `gg.mm.aaaa`), `aaaa-mm-gg`, `aaaammgg` o il numero di serie
|
||||
di una cella data di Excel;
|
||||
- **sì/no** come `sì`, `si`, `x`, `1`, `VERO`, `true` oppure `no`, `0`, `FALSO`, `false`;
|
||||
- le **parole di una scelta** (es. `tipo_soggetto`) senza badare a maiuscole, accenti, spazi e punteggiatura
|
||||
(`Extra UE` = `extra-ue`, `P.A.` = `pa`).
|
||||
|
||||
## Entità e colonne
|
||||
|
||||
Le intestazioni si abbinano da sole quando sono uguali ai nomi qui sotto o a un nome simile (es. `P.IVA`,
|
||||
`Partita IVA`, `piva` → `partita_iva`; `Città` → `comune`). Le colonne con **\*** servono per un record nuovo.
|
||||
|
||||
### Clienti e fornitori
|
||||
|
||||
`codice`, `ragione_sociale`, `nome`, `cognome`, `tipo_soggetto`, `partita_iva`, `codice_fiscale`, `rea`, `indirizzo`,
|
||||
`civico`, `cap`, `comune`, `provincia`, `nazione`, `telefono`, `email`, `pec`, `sito`, `codice_destinatario`,
|
||||
`categoria`; per i **clienti** anche `agente`, `pagamento`, `listino`, `sconto1`, `sconto2`, `fido`, `iban`, `note`;
|
||||
per i **fornitori** `pagamento`, `iban`, `note`.
|
||||
|
||||
| Colonna | Valori |
|
||||
|---|---|
|
||||
| **CSV** | testo con separatore `;` e codifica UTF-8 (formato più comune per gli scambi) |
|
||||
| **XLSX** | foglio Excel con le stesse colonne del CSV |
|
||||
| **JSON** | scambio completo fra installazioni Khaemhat (es. piano dei conti con voci di bilancio e causali) |
|
||||
| `tipo_soggetto` | `impresa`, `privato`, `pa`, `ue`, `extra-ue`, `forfettario` (vuoto: impresa; con solo cognome e nome: privato) |
|
||||
| `nazione` | codice ISO a due lettere (`IT`, `DE`...) |
|
||||
| `categoria`, `agente`, `pagamento`, `listino` | il **codice** della tabella (vedi [Tabelle azienda](Tabelle-azienda)) |
|
||||
| `iban` | aggiunge il conto se non c'è già (il primo diventa predefinito) |
|
||||
|
||||
## Entità importabili
|
||||
Ragione sociale (o cognome e nome per un privato), partita IVA e gli altri controlli sono quelli della scheda (vedi
|
||||
[Anagrafiche](Anagrafiche)).
|
||||
|
||||
| Entità | Note |
|
||||
### Articoli
|
||||
|
||||
`codice`, `descrizione`\*, `descrizione_estesa`, `tipo`, `categoria`, `um`, `iva_vendite`, `iva_acquisti`, `ean`,
|
||||
`nc8`, `marca`, `produttore`, `peso_netto`, `peso_lordo`, `a_magazzino`, `magazzino`, `scorta_minima`,
|
||||
`punto_riordino`, `lotto_riordino`, `prezzo`, `costo_standard`, `conto_ricavo`, `conto_costo`, `note`.
|
||||
|
||||
| Colonna | Valori |
|
||||
|---|---|
|
||||
| **Anagrafiche** (clienti, fornitori) | verifica partita IVA (VIES per i soggetti UE), comune da CAP |
|
||||
| **Articoli** | |
|
||||
| **Listini** | |
|
||||
| **Giacenze iniziali** | quantità di apertura per deposito |
|
||||
| **Piano dei conti** | tracciato descritto sotto; verifica della coerenza gerarchica |
|
||||
| **Saldi iniziali** | saldi di apertura dei conti |
|
||||
| **Partite di apertura** | crediti e debiti aperti verso clienti e fornitori, con scadenze |
|
||||
| `tipo` | `merce`, `servizio`, `spesa`, `descrittivo`, `cespite` (vuoto: merce) |
|
||||
| `categoria`, `um`, `iva_vendite`, `iva_acquisti`, `magazzino` | il **codice** della tabella (`PZ`, `22`, il codice del deposito) |
|
||||
| `a_magazzino` | sì/no; un articolo che non è merce non è mai a magazzino |
|
||||
| `prezzo` | il prezzo dell'articolo; i prezzi di listino si importano con l'entità *Prezzi* |
|
||||
|
||||
Le colonne disponibili per ogni entità corrispondono ai campi della relativa scheda (vedi [Anagrafiche](Anagrafiche),
|
||||
[Articoli e listini](Articoli-e-listini), [Magazzino](Magazzino), [Contabilità](Contabilita),
|
||||
[Scadenzario](Scadenzario)); i tracciati completi saranno pubblicati con i rispettivi moduli.
|
||||
Il codice generato usa la regola degli articoli, di solito `{categoria}-{seq:0000}`: in quel caso la categoria è
|
||||
obbligatoria. Unità alternative, codici alternativi, fornitori e sostitutivi restano quelli della scheda (vedi
|
||||
[Articoli e listini](Articoli-e-listini)).
|
||||
|
||||
### Prezzi di listino e netti cliente
|
||||
|
||||
`articolo`\*, `listino`, `cliente`, `prezzo`\*, `valido_dal`. Ogni riga ha **il listino oppure il cliente** (prezzo
|
||||
netto), non entrambi. Stesso articolo, listino o cliente e data: il prezzo si sostituisce; una data nuova aggiunge
|
||||
un prezzo che vale da quel giorno, come nella griglia dei listini. Le righe senza errori si scrivono tutte insieme.
|
||||
|
||||
### Giacenze iniziali (solo verifica fino a M6)
|
||||
|
||||
`articolo`\*, `deposito` (vuoto: il deposito dell'articolo), `quantita`\* (maggiore di zero), `costo_unitario`.
|
||||
L'articolo deve essere merce gestita a magazzino. Il controllo serve a preparare il file: la scrittura del movimento
|
||||
di apertura arriva con il [Magazzino](Magazzino).
|
||||
|
||||
### Piano dei conti (solo verifica fino a M7)
|
||||
|
||||
Vedi il tracciato più sotto.
|
||||
|
||||
## Come si importa
|
||||
|
||||
### 1. Origine
|
||||
|
||||
1. Scegli l'**Entità** (es. *Clienti*).
|
||||
2. Carica il file. Khaemhat riconosce numero di righe, codifica e separatore (es. *clienti.csv · 1.284 righe ·
|
||||
UTF-8 · separatore ;*).
|
||||
3. Imposta le opzioni:
|
||||
1. Scegli l'**Entità**.
|
||||
2. Imposta le opzioni:
|
||||
|
||||
| Opzione | Valori |
|
||||
|---|---|
|
||||
| **Se il codice esiste** | *Aggiorna* il record esistente oppure lo salta (valori esatti definiti in sviluppo) |
|
||||
| **Codici mancanti** | *Genera automatici* secondo le regole dei codici automatici (vedi [Tabelle azienda](Tabelle-azienda)) |
|
||||
| **Verifica P.IVA (VIES per UE)** | controlla le partite IVA |
|
||||
| **Compila comune da CAP** | completa comune e provincia dal CAP |
|
||||
| Opzione | Valori | Entità |
|
||||
|---|---|---|
|
||||
| **Se il codice esiste** | *Aggiorna* (le celle piene cambiano il record, le vuote lasciano ciò che c'è) oppure *Salta la riga* (avviso) | clienti, fornitori, articoli, prezzi |
|
||||
| **Codice mancante** | *Genera automatico* con le regole dei codici automatici (vedi [Tabelle azienda](Tabelle-azienda)) oppure *Errore sulla riga* | clienti, fornitori, articoli |
|
||||
| **Verifica P.IVA su VIES (UE)** | controlla su VIES le partite IVA dei soggetti UE durante l'import (più lento) | clienti, fornitori |
|
||||
| **Completa comune da CAP** | completa comune e provincia da un CAP con un solo comune, o il CAP da un comune con un solo CAP (avviso) | clienti, fornitori |
|
||||
|
||||
3. Scegli il **file**. Il passo mostra nome, righe e dimensione (es. *clienti_2026.csv · 1.284 righe · 37 KB*).
|
||||
|
||||
Un codice scritto nel file per un record nuovo deve essere ammesso dalla regola dei codici (**codice manuale**): per
|
||||
mantenere i codici del gestionale precedente lascia attiva quell'opzione nella regola. Un codice già presente in una
|
||||
riga precedente del file è un errore; il codice di un'anagrafica di altro tipo (un fornitore fra i clienti) anche.
|
||||
|
||||
### 2. Mappatura colonne
|
||||
|
||||
Khaemhat abbina le colonne del file ai campi dell'entità (es. *12 di 14 colonne abbinate*). Controlla gli
|
||||
abbinamenti proposti, correggi quelli sbagliati e indica le colonne da ignorare.
|
||||
Khaemhat abbina le colonne del file ai campi dell'entità (es. *14 di 16 colonne abbinate*) e mostra per ognuna il
|
||||
valore della prima riga. Correggi gli abbinamenti con l'elenco **Campo**; scegli *Ignora* per le colonne da
|
||||
tralasciare. Un campo va su una sola colonna. Un avviso elenca i campi obbligatori non abbinati. Premi **Verifica le
|
||||
righe**.
|
||||
|
||||
### 3. Validazione
|
||||
|
||||
Ogni riga viene controllata come se fosse inserita a mano. L'**Anteprima e validazione** mostra le prime righe con
|
||||
l'**Esito**:
|
||||
Ogni riga viene controllata come se fosse inserita a mano nella scheda. L'**Anteprima e validazione** mostra fino a
|
||||
500 righe con l'**Esito** e il motivo accanto; le celle con un problema sono evidenziate.
|
||||
|
||||
| Esito | Significato | Esempio |
|
||||
|---|---|---|
|
||||
| **OK** | riga importabile | |
|
||||
| **Avviso** | riga importabile con una correzione proposta | *CAP mancante: proposto 12100* |
|
||||
| **Errore** | riga non importabile | *P.IVA non valida* |
|
||||
| **Nuovo** / **Aggiorna** | riga importabile | |
|
||||
| **Avviso** | riga importabile con una correzione proposta o una nota | *Comune: dedotto dal CAP (Forlì)* |
|
||||
| **Errore** | riga esclusa | *Partita IVA non valida*, *Il codice XX non esiste* |
|
||||
|
||||
Il filtro **Tutte / Solo problemi** mostra solo le righe con avvisi o errori. **Scarica report errori** scarica
|
||||
l'elenco delle righe problematiche con il motivo: correggile nel file di origine e reimportale.
|
||||
Il filtro **Tutte / Solo problemi** mostra solo le righe con avvisi o errori. **Scarica report errori** scarica un CSV
|
||||
con riga, codice, colonna, esito e messaggio: correggi il file di origine e reimportalo. **Mappatura** torna al passo
|
||||
precedente.
|
||||
|
||||
### 4. Importazione
|
||||
|
||||
Il riepilogo indica quante righe verranno **create** e quante **aggiornate**. Premi **Importa N righe**: le righe con
|
||||
errori vengono escluse, le altre importate. L'esito finisce nel [Log](Log) e ogni record creato ha il suo storico.
|
||||
**Importa N righe** chiede conferma e scrive le righe senza errori, una alla volta come un salvataggio della scheda
|
||||
(i prezzi tutti insieme). Il riepilogo indica creati, aggiornati, saltati e righe con errori; ogni record ha il suo
|
||||
storico e l'esito finisce nel [Log](Log) (sezione *Sistema*). **Nuova importazione** ricomincia.
|
||||
|
||||
**Consiglio:** prova l'importazione su un'azienda clonata (vedi [Istanza e database](Istanza-e-database)) prima di
|
||||
farla sull'azienda reale, soprattutto per saldi e partite di apertura.
|
||||
farla sull'azienda reale.
|
||||
|
||||
## Tracciato del piano dei conti
|
||||
|
||||
In Italia non esiste uno standard per lo scambio del piano dei conti, perciò Khaemhat definisce il proprio
|
||||
tracciato. Il piano standard per PMI è già **precaricato** con le tabelle di base; l'importazione serve a chi vuole
|
||||
usare il piano del proprio commercialista o del gestionale precedente.
|
||||
tracciato. Il piano standard per PMI sarà **precaricato** con la contabilità (M7); l'importazione serve a chi vuole
|
||||
usare il piano del proprio commercialista o del gestionale precedente. Fino a M7 il file si **verifica** soltanto.
|
||||
|
||||
### CSV e XLSX
|
||||
|
||||
Separatore `;`, una riga per conto, con le colonne:
|
||||
Una riga per conto, con le colonne:
|
||||
|
||||
```
|
||||
codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
|
||||
@@ -105,54 +171,78 @@ codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
|
||||
|
||||
| Colonna | Contenuto |
|
||||
|---|---|
|
||||
| `codice` | codice gerarchico nella forma `MM.CC.SSS` (mastro, conto, sottoconto) |
|
||||
| `descrizione` | descrizione del conto |
|
||||
| `livello` | livello nella gerarchia (mastro, conto, sottoconto) |
|
||||
| `padre` | codice del conto padre (vuoto per i mastri) |
|
||||
| `natura` | natura del conto (es. patrimoniale/economico; valori ammessi definiti in sviluppo) |
|
||||
| `tipo` | tipo del conto (valori ammessi definiti in sviluppo) |
|
||||
| `codice`\* | da 1 a 3 parti separate da punto: mastro, conto, sottoconto (`01`, `01.10`, `01.10.001`) |
|
||||
| `descrizione`\* | descrizione del conto |
|
||||
| `livello` | 1, 2 o 3: il numero di parti del codice (se indicato deve corrispondere) |
|
||||
| `padre` | il codice senza l'ultima parte (se indicato deve corrispondere); deve essere nel file |
|
||||
| `natura` | `attivo`, `passivo`, `costo`, `ricavo`, `ordine`; obbligatoria sui mastri, ereditata dai sottoconti e uguale a quella del padre |
|
||||
| `tipo` | `generico` (vuoto), `clienti`, `fornitori`, `banca`, `cassa`, `iva`, `erario` |
|
||||
| `voce_cee` | voce dello schema di bilancio CEE (artt. 2424/2425 c.c.) |
|
||||
| `riclassifica` | voce del bilancio riclassificato |
|
||||
| `flag` | indicatori del conto (partitario clienti/fornitori, rilevante IVA, chiusura automatica, movimentabile, attivo; codifica definita in sviluppo) |
|
||||
| `flag` | lettere: `M` movimentabile, `I` rilevante IVA, `P` con partitario clienti/fornitori, `C` chiusura automatica, `X` disattivato |
|
||||
|
||||
Esempio di righe (valori indicativi):
|
||||
Esempio:
|
||||
|
||||
```
|
||||
codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag
|
||||
01;Immobilizzazioni;1;;…;…;;;
|
||||
01.01;Immobilizzazioni immateriali;2;01;…;…;…;…;
|
||||
01.01.001;Software;3;01.01;…;…;…;…;…
|
||||
01;Attivo;1;;attivo;;;;
|
||||
01.10;Crediti verso clienti;2;01;;;;;
|
||||
01.10.001;Clienti Italia;3;01.10;;clienti;CII1;;MP
|
||||
01.20;Disponibilità liquide;2;01;;;;;
|
||||
01.20.001;Banca;3;01.20;;banca;CIV1;;M
|
||||
```
|
||||
|
||||
Il file **XLSX** usa le stesse colonne, nella prima riga del primo foglio.
|
||||
|
||||
### JSON (`khaemhat-coa.json`)
|
||||
|
||||
Per l'export e l'import **completo** fra installazioni Khaemhat: contiene **conti**, **voci di bilancio**, **causali
|
||||
contabili** e **mappature**. È il formato da usare per copiare il piano dei conti da un'azienda all'altra.
|
||||
Per lo scambio **completo** fra installazioni Khaemhat:
|
||||
|
||||
### Controlli in importazione
|
||||
```json
|
||||
{
|
||||
"format": "khaemhat-coa",
|
||||
"version": 1,
|
||||
"accounts": [ { "codice": "01", "descrizione": "Attivo", "natura": "attivo" } ],
|
||||
"statementLines": [],
|
||||
"journalTemplates": [],
|
||||
"mappings": []
|
||||
}
|
||||
```
|
||||
|
||||
- **Coerenza gerarchica**: ogni conto deve avere un padre esistente e un livello coerente con il codice.
|
||||
- Gli altri controlli (ad esempio codici duplicati o voci CEE inesistenti) seguono le regole del piano dei conti e
|
||||
saranno precisati in sviluppo.
|
||||
`accounts` ha le stesse colonne del CSV. Voci di bilancio (`statementLines`), causali (`journalTemplates`) e
|
||||
mappature (`mappings`) si contano già nella mappatura e si importano con la contabilità (M7).
|
||||
|
||||
## Export
|
||||
### Controlli
|
||||
|
||||
I dati si esportano negli stessi formati:
|
||||
- codice di 1-3 parti, livello e padre coerenti con il codice, padre presente nel file;
|
||||
- natura indicata sui mastri e uguale a quella del padre;
|
||||
- **solo i conti senza sottoconti** sono movimentabili (`M` su un conto con sottoconti è un errore; un sottoconto
|
||||
senza `M` è un avviso);
|
||||
- lettere di `flag` sconosciute e codici ripetuti sono errori.
|
||||
|
||||
- dalla procedura guidata, per le entità sopra elencate (l'obiettivo è che un file esportato si possa reimportare
|
||||
con lo stesso tracciato; dettagli definiti in sviluppo);
|
||||
- dalle griglie e dai report (CSV/XLSX/PDF), dal pulsante **Genera file/esporta**;
|
||||
- il piano dei conti completo in `khaemhat-coa.json`.
|
||||
## Export e modelli
|
||||
|
||||
Gli export richiedono il flag utente **Può esportare dati** (vedi [Utenti e permessi](Utenti-e-permessi)).
|
||||
Il riquadro **Esporta e modelli** usa l'entità scelta in alto:
|
||||
|
||||
- **Formato**: CSV, XLSX o JSON;
|
||||
- **Scarica modello**: il file con le sole intestazioni (in JSON un oggetto con i valori vuoti; per il piano dei conti
|
||||
l'oggetto `khaemhat-coa`);
|
||||
- **Esporta**: tutti i record con le **stesse colonne dell'import**, così il file si corregge e si reimporta
|
||||
(nome `clienti-2026-11-12.csv`). I codici delle tabelle sono esportati come codici.
|
||||
|
||||
L'export richiede il flag utente **Può esportare dati** e il permesso di export dell'entità (per le anagrafiche
|
||||
*Esportare anagrafiche*) (vedi [Utenti e permessi](Utenti-e-permessi)). Giacenze e piano dei conti hanno per ora solo
|
||||
il modello. Le griglie esportano anche dal proprio menu (CSV/XLSX).
|
||||
|
||||
## Domande frequenti
|
||||
|
||||
- **Il file ha la virgola come separatore.** Usa il separatore `;` (standard per i CSV in italiano, dove la virgola è
|
||||
il separatore decimale) oppure salva in XLSX.
|
||||
- **Le lettere accentate appaiono sbagliate.** Salva il CSV in UTF-8.
|
||||
- **Il file ha la virgola come separatore.** Va bene: il separatore si deduce dalla riga di intestazione.
|
||||
- **Le lettere accentate appaiono sbagliate.** Khaemhat legge UTF-8 e, in alternativa, Windows-1252 (il CSV di Excel
|
||||
per l'Italia); con altre codifiche salva in UTF-8 o in XLSX.
|
||||
- **Il codice del vecchio gestionale viene rifiutato.** La regola dei codici di quell'archivio non ammette il codice
|
||||
manuale: abilitalo in *Preferenze azienda → Codici automatici* (`/tabelle/preferenze`), oppure scegli *Genera automatico* e togli la colonna.
|
||||
- **Ho importato con errori: devo rifare tutto?** No: correggi solo le righe del report e reimportale; con *Aggiorna*
|
||||
le righe già importate si aggiornano senza doppioni.
|
||||
- **Posso importare documenti (fatture, DDT) da un altro gestionale?** Non con questa procedura: le fatture
|
||||
elettroniche di acquisto si importano dall'XML SDI (vedi [Acquisti](Acquisti) e
|
||||
[Fatturazione elettronica](Fatturazione-elettronica)).
|
||||
@@ -160,4 +250,4 @@ Gli export richiedono il flag utente **Può esportare dati** (vedi [Utenti e per
|
||||
## Pagine correlate
|
||||
|
||||
[Dati di base e di esempio](Dati-di-base-e-esempio) · [Contabilità](Contabilita) · [Anagrafiche](Anagrafiche) ·
|
||||
[Articoli e listini](Articoli-e-listini) · [Scadenzario](Scadenzario) · [Tabelle azienda](Tabelle-azienda) · [Primi passi](Primi-passi)
|
||||
[Articoli e listini](Articoli-e-listini) · [Magazzino](Magazzino) · [Tabelle azienda](Tabelle-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*.
|
||||
|
||||
|
||||
@@ -189,6 +189,7 @@ obbligatoria, termina con un messaggio che indica quale.
|
||||
| `KHAEMHAT_SEED_DEMO` | no | `false` | dati di esempio, solo su database vuoto |
|
||||
| `KHAEMHAT_UPDATE_FEED` | no | `https://gitea.encke-hake.ts.net/api/v1/packages/BalboSoft?type=container&q=khaemhat` | API dei pacchetti Gitea per il controllo aggiornamenti |
|
||||
| `KHAEMHAT_UPDATE_TOKEN` | no | token Gitea in sola lettura | solo se il pacchetto non è pubblico |
|
||||
| `KHAEMHAT_HELP_URL` | no | `https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/` | wiki online aperta da **Apri nel wiki** nell'aiuto; l'aiuto (F1) usa la copia della wiki contenuta nell'immagine e funziona anche senza Internet |
|
||||
| `TZ` | no | `Europe/Rome` | fuso orario |
|
||||
| `PUID` / `PGID` | no | `1654` / `1654` (Unraid: `99` / `100`) | utente e gruppo proprietari dei file in `/data`; l'applicazione non gira mai come root |
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Interfaccia e scorciatoie
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M3)
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 (milestone M3)
|
||||
> **Modulo di licenza:** CORE · **Specifica:** SPEC §10.2, §10.4, §10.5, §10.7, §17 (aiuto in app)
|
||||
|
||||
Questa pagina descrive come è fatta la finestra di Khaemhat e come ci si muove: barra superiore, menu laterale,
|
||||
@@ -15,6 +15,9 @@ scorciatoia nel suggerimento che compare al passaggio del mouse.
|
||||

|
||||
*Mockup 013 — la finestra con il menu laterale compresso: barra superiore, sottomenu Anagrafiche a comparsa, schede aperte, radar dei clienti e barra di stato.*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la finestra con il menu espanso: barra superiore, menu, scheda Home con la dashboard predefinita e barra di stato.*
|
||||
|
||||
| Zona | Dove | Contenuto |
|
||||
|---|---|---|
|
||||
| Barra superiore | in alto, scura | marchio e versione, azienda, ricerca globale, nuovo, recenti, notifiche, tema, aiuto, utente |
|
||||
@@ -66,9 +69,15 @@ Si passa da uno stato all'altro con il pulsante **Comprimi menu** in fondo al me
|
||||
**ricordato per utente** (anche fra dispositivi diversi); sotto i 1100 px di larghezza della finestra il menu parte
|
||||
compresso. Lo stato iniziale si sceglie anche in [Preferenze utente](Preferenze-utente).
|
||||
|
||||
Le aree che arrivano con le prossime versioni sono già nel menu, se la licenza e i permessi le concedono: aprendole
|
||||
compare una pagina che dice con quale milestone arrivano e quali voci conterranno.
|
||||
|
||||

|
||||
*Mockup 007 — dashboard con il menu compresso a sole icone e accento Turchese (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — lo stesso menu compresso a sole icone; la freccia in basso lo riapre.*
|
||||
|
||||
## Area a schede
|
||||
|
||||
Ogni maschera aperta (un radar, un documento, una scheda anagrafica, una procedura) diventa una **scheda** in alto.
|
||||
@@ -76,9 +85,23 @@ Le schede restano "vive": passando da una all'altra non si perde nulla di quanto
|
||||
|
||||
- Un **pallino arancione** accanto al titolo indica modifiche non salvate.
|
||||
- Chiudendo una scheda con modifiche non salvate Khaemhat chiede conferma.
|
||||
- Si possono tenere aperte al massimo **12 schede**; il comportamento all'apertura della tredicesima sarà definito in
|
||||
sviluppo.
|
||||
- `Ctrl+W` chiude la scheda attiva, `Ctrl+Tab` passa alla successiva; il pulsante `+` apre una nuova scheda.
|
||||
- Si possono tenere aperte al massimo **12 schede**. Aprendone una tredicesima si chiude da sola quella usata meno di
|
||||
recente fra quelle **senza modifiche**; se tutte hanno modifiche da salvare, Khaemhat lo dice e non apre la nuova.
|
||||
- Aprire una pagina già aperta porta alla sua scheda invece di crearne un'altra.
|
||||
- `Ctrl+W` (o `Alt+W`) chiude la scheda attiva, `Ctrl+Tab` (o `Alt+PagGiù`) passa alla successiva,
|
||||
`Ctrl+Maiusc+Tab` (o `Alt+PagSu`) alla precedente; il pulsante `+` apre la ricerca per aprire una nuova pagina.
|
||||
Molti browser tengono per sé `Ctrl+W` e `Ctrl+Tab`: le varianti con `Alt` funzionano sempre.
|
||||
- Il titolo della finestra del browser segue la scheda attiva.
|
||||
|
||||
## Su tablet e telefono
|
||||
|
||||
La finestra è pensata per lo schermo di un computer, ma resta usabile su tablet (dai 768 px) e su telefono. Sotto i
|
||||
1.100 px la barra superiore nasconde il nome dell'utente, sotto i 900 px il testo della ricerca; sul telefono il
|
||||
menu laterale resta a sole icone, la barra superiore mostra solo le icone (il nome dell'azienda resta letto dagli
|
||||
screen reader) e la barra di stato mostra solo connessione, cache e versione.
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la Home su un telefono largo 390 px.*
|
||||
|
||||
## Barra di stato
|
||||
|
||||
@@ -91,6 +114,13 @@ e la **versione** del software con il commit (es. `v1.0.0 (a3f9c1e)`).
|
||||

|
||||
*Mockup 009 — ricerca "rossi": risultati raggruppati per clienti, articoli, documenti, contabilità e azioni (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la ricerca "cli": pagine del menu e pagine dell'aiuto. Clienti, articoli e documenti si aggiungono con i rispettivi moduli.*
|
||||
|
||||
> **In questa versione** la ricerca trova le **pagine** del menu, i **comandi** (tema, menu, profilo, sessioni,
|
||||
> scorciatoie) e le **pagine dell'aiuto** (titoli e sezioni, che si aprono al punto giusto). Clienti, articoli e
|
||||
> documenti si aggiungono con le milestone che li introducono: per ora `#` e `@` dicono con quali moduli arrivano.
|
||||
|
||||
Premi `Ctrl+K` (o fai clic sulla casella di ricerca) e digita. I risultati arrivano mentre scrivi, raggruppati per
|
||||
tipo: **clienti e fornitori**, **articoli**, **documenti**, **registrazioni e conti** contabili, **azioni** (ad
|
||||
esempio *Nuova fattura per Rossi Impianti*, *Registra incasso*, *Scheda cliente a 360°*).
|
||||
@@ -103,40 +133,58 @@ esempio *Nuova fattura per Rossi Impianti*, *Registra incasso*, *Scheda cliente
|
||||
| `@` | persone (contatti, utenti) | `@ verdi` |
|
||||
|
||||
Con le frecce `↑` `↓` ti sposti tra i risultati, con `Invio` apri quello evidenziato; il piede della finestra ricorda
|
||||
anche l'apertura in una nuova scheda (`Ctrl+Invio`) e i prefissi. `Esc` chiude.
|
||||
i prefissi. `Esc` chiude. Pagine e comandi compaiono subito; gli altri risultati arrivano un attimo dopo che hai
|
||||
smesso di scrivere, da almeno due caratteri.
|
||||
|
||||
## Notifiche
|
||||
|
||||

|
||||
*Mockup 010 — pannello laterale delle notifiche con filtri e azioni (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — il pannello delle notifiche con i filtri Tutte e Non lette e il pulsante Segna tutte come lette.*
|
||||
|
||||
La campanella apre un pannello laterale con le notifiche in app. Le notifiche nascono da automazioni, attività
|
||||
programmate, SDI (scarti, notifiche), scadenze, magazzino (sottoscorta) e sicurezza (ad esempio un accesso da un
|
||||
dispositivo sconosciuto). Ogni voce ha icona, titolo, dettaglio e, se serve, un'etichetta d'urgenza (*Nuova*, *Da
|
||||
gestire*, *Verifica*); un clic apre il documento o la maschera collegata.
|
||||
|
||||
In alto i filtri **Tutte**, **Non lette**, **Errori**; in basso **Segna tutte come lette** e **Impostazioni notifiche**
|
||||
(che porta alla scheda *Notifiche* di [Il mio profilo](Preferenze-utente), dove si attiva anche il riepilogo via
|
||||
e-mail).
|
||||
In alto i filtri **Tutte** e **Non lette**, con il numero di voci; in basso **Segna tutte come lette**. Ogni voce ha
|
||||
il segno di spunta per segnarla come letta; il clic sul titolo la segna e apre la maschera collegata. Il numero
|
||||
sulla campanella si aggiorna da solo ogni minuto.
|
||||
|
||||
Chi legge una notifica rivolta a tutti la segna come letta **solo per sé**: per i colleghi resta da leggere. Gli
|
||||
account di istanza vedono le notifiche di sistema (backup, attività programmate, licenza), gli utenti aziendali
|
||||
quelle della propria azienda. Il pannello mostra le ultime 100 notifiche.
|
||||
|
||||
> **In questa versione** mancano il filtro *Errori* e *Impostazioni notifiche* (riepilogo via e-mail), che arrivano
|
||||
> con le automazioni.
|
||||
|
||||
## Aiuto in app (F1)
|
||||
|
||||

|
||||
*Mockup 011 — l'aiuto della maschera Fatture: indice delle pagine a sinistra, pagina wiki con stato e revisione a destra.*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — l'aiuto di questa pagina: indice a sinistra, pagina della wiki a destra, Apri nel wiki e Segnala un problema in alto.*
|
||||
|
||||
`F1` o il pulsante `?` aprono, in una nuova scheda, **la pagina wiki della maschera** su cui stai lavorando (ogni
|
||||
maschera ha il proprio collegamento). La pagina mostra in testa lo stato (*bozza*, *completa*), la revisione e la data
|
||||
di aggiornamento; a sinistra c'è l'indice delle pagine. In alto a destra: **Apri nel wiki** (apre la wiki completa
|
||||
nel browser) e **Segnala un problema**.
|
||||
nel browser) e **Segnala un problema** (apre una nuova segnalazione nel repository della wiki).
|
||||
|
||||
L'indirizzo della wiki è configurabile; per le installazioni senza accesso a Internet Khaemhat serve una copia della
|
||||
wiki all'indirizzo `/help` della propria istanza.
|
||||
L'aiuto è una **copia della wiki contenuta nell'immagine Docker**, all'indirizzo `/aiuto` dell'istanza (`/help` porta
|
||||
lì): funziona anche senza Internet e corrisponde sempre alla versione installata, immagini comprese. La variabile
|
||||
`KHAEMHAT_HELP_URL` cambia solo la wiki aperta da *Apri nel wiki* (vedi [Installazione Docker](Installazione-Docker)).
|
||||
|
||||
## Toolbar a icone
|
||||
|
||||

|
||||
*Mockup 020 — fattura di vendita: toolbar a icone con il suggerimento "Salva Ctrl+S", azioni contestuali, intestazione documento e righe (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — il documento di prova degli sviluppatori: toolbar a icone, intestazione a tre blocchi, schede interne e righe modificabili.*
|
||||
|
||||
Ogni maschera ha una toolbar su **una sola riga**, con i comandi standard **solo icona** (senza etichetta). Passando
|
||||
con il mouse compare il suggerimento con nome e scorciatoia (disattivabile in [Preferenze utente](Preferenze-utente)).
|
||||
|
||||
@@ -183,6 +231,11 @@ anagrafiche hanno la stessa struttura:
|
||||
(oppure revisioni o partite, secondo il documento) e **totali**.
|
||||
6. Gli errori di validazione compaiono accanto al campo e in un riepilogo. Un documento emesso è **in sola lettura**:
|
||||
campi e azioni non più ammesse sono disattivati.
|
||||
7. La scheda **Storico** elenca chi ha creato e modificato il record e quando, con i valori di prima (barrati) e
|
||||
quelli nuovi; serve il permesso di lettura del record.
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la scheda Storico del documento di prova (modifiche di esempio).*
|
||||
|
||||
## Radar
|
||||
|
||||
@@ -239,13 +292,18 @@ azioni di riga. Gli sconti accettano la forma a cascata (`5+2`).
|
||||
|
||||
| Digiti | Ottieni |
|
||||
|---|---|
|
||||
| `T` | la data di oggi |
|
||||
| `F` | la fine del mese (il riferimento esatto, data del campo o mese corrente, sarà fissato in sviluppo) |
|
||||
| `+` / `-` | un giorno avanti / indietro |
|
||||
| `T` oppure `O` | la data di oggi |
|
||||
| `F` | la fine del mese della data già nel campo (del mese corrente se il campo è vuoto) |
|
||||
| `I` | l'inizio dello stesso mese |
|
||||
| `+` / `-` | un giorno avanti / indietro rispetto alla data nel campo (o a oggi) |
|
||||
| `+30` / `-7` | trenta giorni avanti, sette indietro |
|
||||
| `15` | il 15 del mese corrente |
|
||||
| `1503` oppure `15/3` | il 15 marzo dell'anno corrente |
|
||||
| `150326` oppure `15.3.26` | il 15 marzo 2026 |
|
||||
|
||||
**Numeri e importi** (formato italiano: virgola per i decimali, punto per le migliaia): si può scrivere un
|
||||
**calcolo** che inizia con `=`, ad esempio `=10*3` diventa `30`. Altre abbreviazioni eventuali saranno definite in
|
||||
sviluppo e documentate qui.
|
||||
**calcolo** che inizia con `=`, ad esempio `=10*3` diventa `30`: valgono le quattro operazioni, le parentesi e il
|
||||
segno meno davanti a un numero, sempre con la virgola per i decimali (`=(12,5+3)*2` diventa `31`).
|
||||
|
||||
## Tabella completa delle scorciatoie
|
||||
|
||||
@@ -254,9 +312,10 @@ sviluppo e documentate qui.
|
||||
| `Ctrl+K` | ricerca globale | ovunque |
|
||||
| `F1` | aiuto della maschera corrente | ovunque |
|
||||
| `Ctrl+B` | comprime / espande il menu laterale | ovunque |
|
||||
| `Ctrl+W` | chiude la scheda attiva | ovunque |
|
||||
| `Ctrl+Tab` | passa alla scheda successiva | ovunque |
|
||||
| `Ctrl+N` | nuovo record / documento | maschere e radar |
|
||||
| `Ctrl+W` o `Alt+W` | chiude la scheda attiva | ovunque |
|
||||
| `Ctrl+Tab` o `Alt+PagGiù` | passa alla scheda successiva | ovunque |
|
||||
| `Ctrl+Maiusc+Tab` o `Alt+PagSu` | passa alla scheda precedente | ovunque |
|
||||
| `Ctrl+N` o `Alt+N` | nuovo record / documento | maschere e radar |
|
||||
| `Ctrl+S` | salva | maschere |
|
||||
| `Esc` | annulla le modifiche / chiude la finestra aperta | maschere, finestre |
|
||||
| `Ctrl+Canc` | elimina il record (se ammesso) | maschere |
|
||||
@@ -271,11 +330,11 @@ sviluppo e documentate qui.
|
||||
| `Tab` | cella o filtro successivo | griglia righe, finestra F4 |
|
||||
| `Spazio` | seleziona la riga | radar |
|
||||
| `Ctrl+D` | quadra la registrazione | prima nota (vedi [Contabilità](Contabilita)) |
|
||||
| `T`, `F`, `+`, `-` | oggi, fine mese, giorno dopo/prima | campi data |
|
||||
| `T` (`O`), `F`, `I`, `+`, `-`, `+n` | oggi, fine mese, inizio mese, giorno dopo/prima, n giorni | campi data |
|
||||
| `=` | calcolo inline (`=10*3`) | campi numerici |
|
||||
|
||||
Le scorciatoie personali si potranno adattare nelle preferenze utente (§11.12 della specifica); l'interfaccia di
|
||||
personalizzazione sarà definita in sviluppo.
|
||||
L'elenco è anche in **Il mio profilo → Scorciatoie** ([Preferenze utente](Preferenze-utente)). Le varianti con `Alt`
|
||||
esistono perché i browser non passano alla pagina `Ctrl+W`, `Ctrl+Tab` e `Ctrl+N` (ADR 0020).
|
||||
|
||||
## Permessi e licenza
|
||||
|
||||
@@ -289,6 +348,7 @@ un permesso negato.
|
||||
amministratore.
|
||||
- **Ho chiuso una scheda per sbaglio.** Se c'erano modifiche non salvate Khaemhat ti ha chiesto conferma; il
|
||||
documento salvato si ritrova con **Recenti** o con `Ctrl+K`.
|
||||
- **`Ctrl+W` chiude il browser invece della scheda.** È il browser che tiene per sé la combinazione: usa `Alt+W`.
|
||||
- **Il menu si è compresso da solo.** Sotto i 1100 px di larghezza il menu parte compresso; allarga la finestra o
|
||||
premi `Ctrl+B`.
|
||||
|
||||
|
||||
@@ -1,8 +1,13 @@
|
||||
# Istanza e database
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2 e M12)
|
||||
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2 e M12)
|
||||
> **Modulo di licenza:** CORE (aziende oltre la prima: MULTI) · **Livello richiesto:** amministratore; azioni distruttive solo super utente · **Specifica:** SPEC §5.3, §5.4, §7.1, §12.1, §13
|
||||
|
||||
> **Nella versione 0.2.0** ci sono la creazione della prima azienda al primo avvio, la creazione e il collegamento
|
||||
> di altre aziende (dal codice, con il modulo MULTI), gli stati *attiva / manutenzione / sola lettura / disattivata*
|
||||
> con le sessioni chiuse quando un'azienda va in manutenzione e il contesto azienda per pagine e API (header
|
||||
> `X-Company`). Le schermate descritte qui arrivano in M12.
|
||||
|
||||
## A cosa serve
|
||||
|
||||
Un'installazione di Khaemhat (una **istanza**, cioè un container) può servire più aziende. Ogni azienda ha il
|
||||
|
||||
@@ -1,8 +1,13 @@
|
||||
# Licenze e moduli
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2)
|
||||
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2)
|
||||
> **Modulo di licenza:** CORE · **Livello richiesto:** super utente (attivazione); amministratore (consultazione) · **Specifica:** SPEC §1.8, §6, §8, §12.2
|
||||
|
||||
> **Nella versione 0.2.0** ci sono verifica e applicazione della licenza: trial di 60 giorni, file `.khl` firmati
|
||||
> (ECDSA P-256) da `KHAEMHAT_LICENSE` o caricati, codici di attivazione dei moduli, modalità test con i codici
|
||||
> fittizi, controllo orario della scadenza con notifiche, limite di aziende e di utenti contemporanei. La schermata
|
||||
> **Licenze e moduli** arriva in M12.
|
||||
|
||||
## A cosa serve
|
||||
|
||||
Khaemhat è diviso in **moduli** attivabili con licenza. La pagina **Licenze e moduli** mostra la licenza
|
||||
|
||||
@@ -1,8 +1,13 @@
|
||||
# Log
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2)
|
||||
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2)
|
||||
> **Modulo di licenza:** CORE · **Livello richiesto:** amministratore · **Specifica:** SPEC §7.3, §9.5, §12.7
|
||||
|
||||
> **Nella versione 0.2.0** il log è scritto nel database di sistema (`sys_log`) con sezione, livello, utente,
|
||||
> azienda e identificativo di traccia (header `X-Trace-Id`), oltre che su console in JSON; la retention per livello
|
||||
> gira ogni notte. La schermata **Log** con filtri e regole di avviso arriva in M12: fino ad allora si legge il log
|
||||
> del container.
|
||||
|
||||
## A cosa serve
|
||||
|
||||
Il **log applicativo** registra ciò che succede in Khaemhat: accessi, documenti emessi, invii SDI, backup,
|
||||
@@ -54,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 |
|
||||
@@ -63,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 @@
|
||||
# Preferenze utente (Il mio profilo)
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M3)
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.3.0 (milestone M3)
|
||||
> **Modulo di licenza:** CORE · **Specifica:** SPEC §7.3, §10.6, §11.12 (preferenze), §12 (Il mio profilo)
|
||||
|
||||
**Il mio profilo** raccoglie tutto ciò che riguarda te come utente: aspetto dell'interfaccia (tema, colore di
|
||||
@@ -9,25 +9,32 @@ salvati e notifiche. Ogni utente può modificare il proprio profilo senza permes
|
||||
|
||||
## Dove si trova
|
||||
|
||||
Menu utente in alto a destra (iniziali e nome) → **Il mio profilo**. Il percorso mostrato nella maschera è
|
||||
*Utente → Preferenze*.
|
||||
Menu utente in alto a destra (iniziali e nome) → **Il mio profilo**, **Aspetto e colori** o **Sessioni attive**;
|
||||
oppure `Ctrl+K` e il comando corrispondente. L'indirizzo è `/profilo`, con `?scheda=aspetto`, `pagina-iniziale`,
|
||||
`sessioni` o `scorciatoie` per aprire direttamente una scheda.
|
||||
|
||||

|
||||
*Mockup 008 — scheda Aspetto con tema Scuro (notturno) e accento Ocra selezionati; a destra l'anteprima dal vivo.*
|
||||
|
||||

|
||||
*Khaemhat 0.3.0 — la scheda Aspetto con tema Automatico e accento Nilo, i valori di partenza. Ogni scelta si applica subito alla finestra.*
|
||||
|
||||
## Schede della maschera
|
||||
|
||||
| Scheda | Contenuto |
|
||||
|---|---|
|
||||
| **Aspetto** | tema, colore di accento, densità, dimensione testo, menu laterale, suggerimenti, animazioni |
|
||||
| **Dati personali** | nome, e-mail e altri dati del tuo utente |
|
||||
| **Password e 2FA** | cambio password, attivazione della verifica in due passaggi |
|
||||
| **Sessioni** | dispositivi collegati con il tuo utente (il numero accanto al titolo indica quante sono) |
|
||||
| **Pagina iniziale** | cosa aprire all'accesso, dashboard sì/no |
|
||||
| **Layout salvati** | filtri e disposizioni di colonne memorizzati nei radar e nelle griglie |
|
||||
| **Notifiche** | quali notifiche ricevere e il riepilogo via e-mail |
|
||||
| Scheda | Contenuto | Disponibile |
|
||||
|---|---|---|
|
||||
| **Aspetto** | tema, colore di accento, densità, dimensione testo, menu laterale, suggerimenti, animazioni | 0.3.0 |
|
||||
| **Pagina iniziale** | cosa aprire all'accesso, dashboard sì/no | 0.3.0 |
|
||||
| **Sessioni** | dispositivi collegati con il tuo utente, chiusura | 0.3.0 |
|
||||
| **Scorciatoie** | l'elenco delle scorciatoie da tastiera | 0.3.0 |
|
||||
| **Dati personali** | nome, e-mail e altri dati del tuo utente | 0.3.0 |
|
||||
| **Password e 2FA** | cambio password, attivazione della verifica in due passaggi | 0.3.0 |
|
||||
| **Layout salvati** | filtri e disposizioni di colonne memorizzati nei radar e nelle griglie | non ancora |
|
||||
| **Notifiche** | quali notifiche ricevere e il riepilogo via e-mail | non ancora |
|
||||
|
||||
In alto a destra: **Ripristina** (torna ai valori predefiniti) e **Salva**.
|
||||
In alto a destra: **Valori predefiniti**, **Annulla le modifiche** e **Salva**. Ogni scelta si vede **subito** sulla
|
||||
pagina; solo **Salva** la conserva. Finché non salvi, la scheda mostra il pallino delle modifiche; chiudendola senza
|
||||
salvare torna l'aspetto di prima.
|
||||
|
||||
## Aspetto
|
||||
|
||||
@@ -35,12 +42,13 @@ In alto a destra: **Ripristina** (torna ai valori predefiniti) e **Salva**.
|
||||
|
||||
| Tema | Descrizione |
|
||||
|---|---|
|
||||
| **Chiaro** | sfondo chiaro, barra superiore scura (predefinito) |
|
||||
| **Automatico** | segue l'impostazione chiaro/scuro del sistema operativo (predefinito) |
|
||||
| **Chiaro** | sfondo chiaro, barra superiore scura |
|
||||
| **Scuro (notturno)** | sfondi scuri e colori attenuati, per lavorare con poca luce |
|
||||
| **Automatico** | segue l'impostazione chiaro/scuro del sistema operativo |
|
||||
| **Alto contrasto** | contrasto massimo per chi ha esigenze visive (livello AAA) |
|
||||
|
||||
Prima dell'accesso (pagina di login) vale il tema del sistema operativo. Le **stampe e i PDF sono sempre in tema
|
||||
Prima dell'accesso (pagina di login) vale il tema del sistema operativo. Dopo l'accesso il tema scelto è già nella
|
||||
pagina che arriva dal server, senza lampeggi. Le **stampe e i PDF sono sempre in tema
|
||||
chiaro**, qualunque sia il tema scelto.
|
||||
|
||||
Il cambio tema rapido (sole/luna) nella barra superiore passa tra chiaro e scuro senza aprire il profilo.
|
||||
@@ -68,9 +76,9 @@ I valori esatti dei colori sono nella pagina [Design UI](Design-UI).
|
||||
| Impostazione | Valori |
|
||||
|---|---|
|
||||
| **Densità** | *Comoda* (righe da 30 px, predefinita) o *Compatta* (righe da 26 px, testo e spaziature più piccoli): con la compatta in una griglia stanno più righe |
|
||||
| **Dimensione testo** | *Normale* (13 px) e altre misure che saranno definite in sviluppo |
|
||||
| **Menu laterale** | *Espanso (ricorda l'ultimo stato)* o compresso all'avvio |
|
||||
| **Carattere numerico tabellare** | cifre di larghezza fissa negli importi, così le colonne restano allineate |
|
||||
| **Dimensione testo** | *100%* (13 px, predefinita), *110%*, *120%* |
|
||||
| **Menu laterale** | *Automatico* (compresso sotto i 1100 px, poi ricorda l'ultimo stato), *Espanso*, *Compresso* |
|
||||
| **Numeri tabellari** | cifre di larghezza fissa negli importi, così le colonne restano allineate (attivo) |
|
||||
|
||||
Interruttori:
|
||||
|
||||
@@ -78,8 +86,8 @@ Interruttori:
|
||||
- **Evidenzia riga sotto il cursore nelle griglie**.
|
||||
- **Animazioni ridotte** — riduce transizioni e movimenti.
|
||||
|
||||
Il riquadro **Anteprima** a destra mostra subito l'effetto delle scelte su una toolbar, alcuni campi, una griglia e
|
||||
i badge di stato (*Bozza*, *Confermato*, *Emessa*, *Attenzione*, *Scartata*).
|
||||
Al posto del riquadro **Anteprima** del mockup, l'anteprima è la pagina stessa: ogni scelta si applica subito a
|
||||
tutta l'interfaccia.
|
||||
|
||||
## Dati personali
|
||||
|
||||
@@ -99,34 +107,39 @@ non si cambiano da qui: li assegna un amministratore ([Utenti e permessi](Utenti
|
||||
|
||||
## Sessioni
|
||||
|
||||
Elenco delle sessioni aperte con il tuo utente: dispositivo, indirizzo IP, data di inizio e ultima attività. Puoi
|
||||
**chiudere** (revocare) una sessione che non riconosci. Un accesso da un **nuovo dispositivo** genera una notifica
|
||||
Elenco delle sessioni aperte con il tuo utente: dispositivo (browser e sistema), indirizzo IP, azienda, data di
|
||||
accesso e ultima attività; la sessione da cui stai lavorando è segnata come *Questa sessione*. Puoi **chiudere**
|
||||
(revocare) una sessione che non riconosci, o **chiuderle tutte tranne questa**: il dispositivo dovrà accedere di
|
||||
nuovo alla richiesta successiva. Un accesso da un **nuovo dispositivo** genera una notifica
|
||||
di sicurezza. Le sessioni scadono dopo un periodo di inattività (scadenza scorrevole) e contano nel numero di utenti
|
||||
contemporanei previsto dalla licenza.
|
||||
|
||||
## Pagina iniziale
|
||||
|
||||
- **All'accesso apri**: *Dashboard*, *ultima scheda aperta*, un *radar* (ad esempio Clienti), la *prima nota*,
|
||||
l'*agenda*…
|
||||
- **All'accesso apri**: *la pagina iniziale*, *le schede aperte l'ultima volta* (si riapre quella attiva), oppure
|
||||
*una pagina a scelta* fra quelle del menu che puoi aprire.
|
||||
- **Mostra la dashboard**: sì/no. Vedi [Dashboard](Dashboard).
|
||||
|
||||
## Layout salvati
|
||||
|
||||
Qui trovi i **filtri salvati** (stella nei radar) e le **disposizioni delle colonne** delle griglie che hai
|
||||
memorizzato, con la possibilità di eliminarli (le altre operazioni, come rinomina o scelta del predefinito, saranno
|
||||
definite in sviluppo). Il numero accanto al titolo della scheda indica quanti sono.
|
||||
La scheda raccoglierà i **filtri salvati** (stella nei radar) e le **disposizioni delle colonne** delle griglie che
|
||||
hai memorizzato, con la possibilità di eliminarli. **In questa versione** filtri e colonne si salvano e si eliminano
|
||||
direttamente dal radar e dalla griglia; la scheda nel profilo arriva con le prime maschere che li usano davvero
|
||||
(anagrafiche, M4).
|
||||
|
||||
## Notifiche
|
||||
|
||||
Scegli quali notifiche ricevere in app (documenti, SDI, scadenze, magazzino, sicurezza, attività programmate…) e se
|
||||
ricevere anche un **riepilogo via e-mail** (digest). L'elenco preciso delle categorie e quali di esse siano
|
||||
obbligatorie saranno definiti in sviluppo. Vedi anche
|
||||
La scheda permetterà di scegliere quali notifiche ricevere in app (documenti, SDI, scadenze, magazzino, sicurezza,
|
||||
attività programmate…) e se ricevere anche un **riepilogo via e-mail** (digest). **In questa versione** arrivano
|
||||
tutte le notifiche previste per il tuo ruolo e non c'è il riepilogo via e-mail: categorie e scelte arrivano con
|
||||
l'invio delle e-mail (M5). Vedi anche
|
||||
[Interfaccia e scorciatoie](Interfaccia-e-scorciatoie) (pannello notifiche).
|
||||
|
||||
## Dove sono salvate le preferenze
|
||||
|
||||
Le preferenze sono salvate **nel database dell'azienda** e valgono su ogni dispositivo da cui accedi. Le preferenze
|
||||
esistono su tre livelli:
|
||||
Le preferenze sono salvate **nel database**, non nel browser, e valgono su ogni dispositivo da cui accedi: per gli
|
||||
utenti aziendali nel database dell'azienda (tabella `user_settings`), per gli account di istanza (super utente,
|
||||
amministratori) nel database di sistema (`sys_user_settings`). Le preferenze esistono su tre livelli:
|
||||
|
||||
| Livello | Esempi | Chi le cambia |
|
||||
|---|---|---|
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Primi passi
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2-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,15 +57,24 @@ 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).*
|
||||
|
||||
1. Nel campo **Azienda** scegli la prima azienda (quella creata dal container, ad esempio *Khaemhat Demo S.r.l.*).
|
||||

|
||||
|
||||
*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.
|
||||
2. In **Nome utente** scrivi il nome del super utente (`KHAEMHAT_SUPERUSER`, predefinito `root`).
|
||||
3. In **Password** scrivi la password iniziale (`KHAEMHAT_SUPERUSER_PASSWORD`).
|
||||
4. Spunta **Ricordami su questo dispositivo** solo su un computer personale.
|
||||
5. Premi **Accedi**.
|
||||
|
||||
Il riquadro giallo in fondo al modulo ricorda che l'istanza è in **modalità Trial** finché non attivi una licenza
|
||||
(passo 6). Il collegamento **Password dimenticata?** invia un link monouso all'indirizzo e-mail registrato; funziona
|
||||
solo dopo aver configurato la posta (SMTP) in **Amministrazione → Impostazioni**.
|
||||
(passo 6). Il collegamento **Password dimenticata?** invia un link monouso all'indirizzo e-mail registrato; arriva con
|
||||
la posta (SMTP) in una milestone successiva: nella versione 0.2.0 non è ancora presente.
|
||||
|
||||
Dopo 5 tentativi sbagliati l'account resta bloccato per 15 minuti; da uno stesso indirizzo IP sono accettati al
|
||||
massimo 10 invii al minuto del modulo di accesso.
|
||||
|
||||
## Passo 3 — Cambio password obbligatorio
|
||||
|
||||
@@ -74,11 +83,15 @@ solo dopo aver configurato la posta (SMTP) in **Amministrazione → Impostazioni
|
||||
*Mockup 003 — cambio password al primo accesso, con indicatore di robustezza e avviso che la password del container
|
||||
viene disattivata (anteprima ridotta).*
|
||||
|
||||
1. In **Password attuale (provvisoria)** riscrivi la password iniziale.
|
||||
1. In **Password attuale o provvisoria** riscrivi la password iniziale.
|
||||
2. In **Nuova password** scrivi la nuova password. La regola predefinita chiede almeno **10 caratteri** e **3 classi**
|
||||
(lettere, numeri, simboli) e non ammette nessuna delle ultime 5 password usate.
|
||||
3. Ripetila in **Conferma nuova password** e controlla la barra **Robustezza**.
|
||||
4. Premi **Imposta password e continua**.
|
||||
(minuscole, maiuscole, numeri, simboli), non deve contenere il nome utente e non ammette nessuna delle ultime 5
|
||||
password usate.
|
||||
3. Ripetila in **Ripeti la nuova password**.
|
||||
4. Premi **Salva e continua**.
|
||||
|
||||
Nella versione 0.2.0 la pagina è più essenziale del mockup 003: l'indicatore di robustezza arriva con l'interfaccia
|
||||
completa (M3).
|
||||
|
||||
Da questo momento la password scritta nelle variabili del container non vale più. Puoi toglierla dal file `.env` o
|
||||
dal template: non viene più letta.
|
||||
@@ -87,23 +100,32 @@ dal template: non viene più letta.
|
||||
|
||||
Per il super utente e per gli amministratori la verifica in due passaggi è **obbligatoria** (SPEC §7.3). Al primo
|
||||
accesso Khaemhat chiede di collegare un'app di autenticazione (qualunque app compatibile con lo standard TOTP,
|
||||
RFC 6238). La schermata di attivazione non è tra i mockup: il formato esatto (chiave testuale e/o codice QR) sarà
|
||||
definito in sviluppo.
|
||||
RFC 6238). La schermata **Configura la verifica in due passaggi** non è tra i mockup (ADR 0019): mostra la chiave
|
||||
in gruppi di quattro caratteri e il collegamento **Apri nell'app di autenticazione** (`otpauth://`), utile sul
|
||||
telefono. Non c'è un codice QR, perché generarlo richiederebbe una libreria esterna (SPEC §1.2).
|
||||
|
||||
1. Apri l'app di autenticazione sul telefono e aggiungi un nuovo account con la chiave mostrata da Khaemhat.
|
||||
2. Scrivi in Khaemhat il codice a 6 cifre generato dall'app per confermare il collegamento.
|
||||
3. Conserva in un luogo sicuro le eventuali informazioni di recupero proposte.
|
||||
1. Apri l'app di autenticazione (Google Authenticator, Microsoft Authenticator, Aegis, 2FAS…) e aggiungi un nuovo
|
||||
account scrivendo la chiave mostrata da Khaemhat, oppure tocca **Apri nell'app di autenticazione** dal telefono.
|
||||
2. In **Primo codice dell'app** scrivi le 6 cifre generate dall'app e premi **Attiva**.
|
||||
3. Khaemhat mostra **10 codici di recupero**: copiali in un luogo sicuro. Ognuno vale una volta sola al posto del
|
||||
codice dell'app e non verrà mostrato di nuovo. Poi premi **Ho salvato i codici, continua**.
|
||||
|
||||

|
||||
|
||||
*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.
|
||||
|
||||
Al posto delle 6 cifre puoi scrivere uno dei codici di recupero.
|
||||
|
||||
> **Attenzione.** Se perdi il telefono con l'app e sei il super utente, nessun altro può reimpostare il tuo accesso
|
||||
> dall'interfaccia. Tieni una copia sicura della chiave TOTP o delle informazioni di recupero.
|
||||
> dall'interfaccia. Tieni al sicuro i codici di recupero.
|
||||
|
||||
## Passo 5 — Creare un amministratore
|
||||
|
||||
@@ -261,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
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Roadmap
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Specifica:** SPEC §20
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-12 · **Specifica:** SPEC §20
|
||||
|
||||
Khaemhat si costruisce in **15 milestone**. Ogni milestone si chiude con un tag di versione, un'immagine Docker nel
|
||||
registro pacchetti di Gitea e la wiki delle funzioni consegnate portata da *bozza* a *completa*.
|
||||
@@ -10,6 +10,11 @@ Il lavoro di dettaglio è nelle issue di Gitea, raggruppate per
|
||||
[progetti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/projects) *Khaemhat 1.0 — Sviluppo* e
|
||||
*Khaemhat 1.1+ — Fase 2*.
|
||||
|
||||
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), M5 (0.5.0). **Prossima:** M6.
|
||||
|
||||
| # | Milestone | Contenuto principale | Versione |
|
||||
|---|---|---|---|
|
||||
| M0 | Bootstrap | Soluzione e progetti, regole di build e allowlist, Dockerfile e compose con pagina "in costruzione", `/health`, Gitea Actions (`ci.yml`, `release.yml`, `wiki.yml`), script, ADR | 0.0.1 |
|
||||
@@ -25,8 +30,8 @@ Il lavoro di dettaglio è nelle issue di Gitea, raggruppate per
|
||||
| M10 | Cespiti, Intrastat, chiusura, bilancio | Registro cespiti, Intrastat, dichiarazioni d'intento, ratei e risconti, chiusura e apertura, bilancio CEE | 0.10.0 |
|
||||
| M11 | CRM | Lead, pipeline, opportunità, attività e agenda, campagne, ticket, scheda 360° | 0.11.0 |
|
||||
| M12 | Amministrazione, automazioni, API | Gestione database, backup e ripristino (anche S3 e WebDAV), attività programmate, impostazioni, stato sistema e aggiornamenti, API REST, MCP, webhook, regole e procedure | 0.12.0 |
|
||||
| M13 | Consolidamento e rilascio | Sicurezza, prestazioni, accessibilità, wiki completa, PWA, prova su Unraid | **1.0.0** |
|
||||
| M14 | Fase 2 | Servizi (contratti e interventi), canali e-commerce, EN 16931/Peppol, XBRL, regime del margine, ventilazione, IVA per cassa completa, SFTP | 1.1.0+ |
|
||||
| M13 | Consolidamento e rilascio | Sicurezza, prestazioni, accessibilità, wiki completa, PWA, prova su Unraid | 0.13.0 |
|
||||
| M14 | Fase 2 | Servizi (contratti e interventi), canali e-commerce, EN 16931/Peppol, XBRL, regime del margine, ventilazione, IVA per cassa completa, SFTP | 0.14.0+ |
|
||||
|
||||
## Stato attuale
|
||||
|
||||
|
||||
@@ -63,7 +63,7 @@ Il riquadro **Versione** riporta:
|
||||
| **Motore DB** | PostgreSQL 17 · minima 16 |
|
||||
| **Cache** | Redis (opzionale) o memoria |
|
||||
| **Fuso orario** | `Europe/Rome` |
|
||||
| **Pacchetto fiscale** | Italia · dati `IT 2026.2` |
|
||||
| **Pacchetto fiscale** | Italia · dati `IT 2026.3` |
|
||||
| **Istanza** | nome host e numero di aziende |
|
||||
|
||||
La stessa versione compare nella barra superiore (solo `major.minor`), nella barra di stato (completa) e
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Tabelle azienda
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** famiglia `company.*` (codici esatti definiti in sviluppo) · **Specifica:** SPEC §11.1, §11.12 (codici automatici, compilazione, preferenze), §14
|
||||
> **Stato:** completa · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.4.0 (milestone M4)
|
||||
> **Modulo di licenza:** CORE · **Permessi principali:** `company.settings.read` (consultare), `company.settings.write` (modificare) · **Specifica:** SPEC §11.1, §11.12 (codici automatici, compilazione, preferenze), §14
|
||||
|
||||
Le **tabelle azienda** sono i dati di configurazione su cui si appoggia tutto il resto: il **profilo dell'azienda**,
|
||||
gli **esercizi e i periodi**, i **codici IVA**, i pagamenti, le banche, i depositi, i numeratori dei documenti, i
|
||||
@@ -10,20 +10,50 @@ dati di base italiani (vedi [Dati di base e di esempio](Dati-di-base-e-esempio))
|
||||
|
||||
## Dove si trova
|
||||
|
||||
Menu **Tabelle azienda** → *Profilo azienda*, *Codici IVA*, *Pagamenti*, *Numeratori*, *Depositi*, *Valute*,
|
||||
*Trasporti*, *Preferenze e codici automatici*; le altre tabelle sono raggiungibili dallo stesso menu e dalla ricerca
|
||||
globale (`Ctrl+K`). Esercizi e periodi sono in *Tabelle azienda → Esercizi*.
|
||||
Menu **Tabelle azienda**: la voce principale apre l'indice di tutte le tabelle (`/tabelle`), raggruppate in
|
||||
*Azienda*, *Fisco, pagamenti e banche*, *Vendite e documenti*, *Magazzino e trasporto*, *Geografia* e *Classificazioni*. Sotto la voce
|
||||
ci sono le scorciatoie per *Profilo azienda*, *Esercizi*, *Preferenze e codici automatici*, *Codici IVA*, *Pagamenti*, *Numeratori*, *Depositi*,
|
||||
*Valute* e *Cambi*. Ogni tabella ha un indirizzo proprio, ad esempio `/tabelle/codici-iva`, ed è raggiungibile anche
|
||||
dalla ricerca globale (`Ctrl+K`). *Preferenze e codici automatici* è a `/tabelle/preferenze`.
|
||||
|
||||
Ogni tabella ha la propria maschera, costruita come il radar dei clienti e la maschera dei codici IVA: elenco con
|
||||
ricerca e filtri, dettaglio sotto o in scheda, **import ed export CSV**.
|
||||

|
||||
*Khaemhat 0.4.0 — l'indice delle tabelle azienda per gruppi, con il sottomenu delle voci più usate.*
|
||||
|
||||
## Come si usa una tabella
|
||||
|
||||
Tutte le tabelle codificate hanno la stessa maschera:
|
||||
|
||||
- **Elenco** con ricerca, filtro rapido *Attive / Disattivate / Tutte* (all'apertura si vedono solo le attive) e
|
||||
colonne principali; un clic sceglie la riga, doppio clic o `Invio` la apre.
|
||||
- **Dettaglio** sotto l'elenco: *Codice*, *Descrizione*, *Disattivata* e i campi propri della tabella. Gli errori
|
||||
compaiono accanto al campo e nel riepilogo; gli **avvisi** (ad esempio un codice IVA senza riferimento normativo)
|
||||
non bloccano il salvataggio.
|
||||
- **Barra comandi**: *Nuovo*, *Salva* (`Ctrl+S`), *Annulla modifiche*, *Elimina*. Una riga usata altrove non si può
|
||||
eliminare: Khaemhat propone di **disattivarla**, così resta nei documenti già fatti ma non si propone più.
|
||||
- Menu `…`: **Esporta CSV**, **Importa CSV** e **Aggiorna da tabelle base**.
|
||||
- Uscendo con modifiche non salvate viene chiesta conferma.
|
||||
|
||||
**Importa CSV** (file fino a 20 MB, separatore `;`, `,` o tabulazione, prima riga con i nomi delle colonne come nell'export): le
|
||||
righe con un codice già presente vengono aggiornate, le altre aggiunte. È **tutto o niente**: se una riga ha un
|
||||
errore non viene importato nulla e la finestra elenca riga, campo e motivo.
|
||||
|
||||
**Aggiorna da tabelle base** aggiunge i codici di base mancanti senza modificare le righe che ci sono già (vedi
|
||||
[Dati di base e di esempio](Dati-di-base-e-esempio)).
|
||||
|
||||
Le **condizioni di pagamento** hanno anche le **rate**: giorni, fine mese, giorno fisso e percentuale; la somma delle
|
||||
percentuali deve fare 100 e le rate si salvano tutte insieme.
|
||||
|
||||
## Profilo azienda
|
||||
|
||||

|
||||
*Mockup 075 — profilo azienda: schede Dati societari, Fiscale e SDI, Banche, Logo e stampe, Esercizi e periodicità, Trasmittente/intermediario (anteprima ridotta).*
|
||||
|
||||
Indirizzo: `/tabelle/profilo-azienda`. Al salvataggio partita IVA, codice fiscale, codice destinatario e regime
|
||||
fiscale sono controllati dal pacchetto fiscale del paese; se un errore è in un'altra scheda, Khaemhat si sposta
|
||||
sulla scheda del primo errore. Il logo per le stampe arriva con i modelli di stampa dei documenti.
|
||||
|
||||
Il profilo è una scheda unica (una sola per azienda). In alto a destra un badge indica la versione del **pacchetto
|
||||
fiscale** in uso (es. *IT 2026.2*).
|
||||
fiscale** in uso (es. *IT 2026.3*).
|
||||
|
||||
| Scheda / gruppo | Campi |
|
||||
|---|---|
|
||||
@@ -49,6 +79,10 @@ sblocca.
|
||||
**Periodi** (mesi o trimestri secondo la periodicità IVA): stato *aperto*, *liquidato* o *bloccato*, esito della
|
||||
liquidazione IVA (*provvisoria*, *confermata*), registrazioni, interruttore **Blocco**.
|
||||
|
||||
Indirizzo: `/tabelle/esercizi`. **Nuovo esercizio** crea l'anno successivo all'ultimo con i suoi dodici mesi. Il
|
||||
pulsante **Blocca** di un mese impedisce nuove registrazioni con date in quel mese; **Sblocca** chiede conferma. Un
|
||||
mese *liquidato* si sblocca solo annullando la liquidazione IVA (M7).
|
||||
|
||||
Regola fondamentale: **si possono registrare documenti e movimenti contabili solo con data in un periodo aperto**. Un
|
||||
periodo bloccato rifiuta ogni registrazione con data al suo interno; la conferma della liquidazione IVA blocca il
|
||||
periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura (vedi [Contabilità](Contabilita)).
|
||||
@@ -58,8 +92,8 @@ periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura
|
||||
| Tabella | Contenuto |
|
||||
|---|---|
|
||||
| **Paesi** | codici ISO 3166-1, appartenenza all'UE, codice SDI per l'estero (`XXXXXXX`) |
|
||||
| **Province** e **Comuni** | CAP e codice catastale: servono per la compilazione da CAP e per il calcolo del codice fiscale |
|
||||
| **Valute** e **Cambi** | valute con i cambi giornalieri della BCE |
|
||||
| **Province** e **Comuni** | Sigla, regione, codice catastale (il codice del comune), codice ISTAT e CAP: servono per la compilazione da CAP e per il calcolo del codice fiscale. Province, comuni e CAP arrivano con i dati di base (elenco ISTAT, CAP da GeoNames); i pochi CAP mancanti si completano a mano o con l'Importa CSV, vedi [Dati di base e di esempio](Dati-di-base-e-esempio) |
|
||||
| **Valute** e **Cambi** | valute con i cambi giornalieri della BCE; in *Cambi* (`/tabelle/cambi`) si vedono i cambi per data e origine e si inserisce un cambio manuale |
|
||||
| **Unità di misura** | codici interni e codice usato nell'XML SDI |
|
||||
| **Codici IVA** | aliquota, natura SDI, riferimento normativo, esigibilità, tipo, indetraibilità, conti IVA, validità (vedi sotto) |
|
||||
| **Metodi di pagamento** | codici SDI `MP01`…`MP23` (es. MP01 contanti, MP02 assegno, MP05 bonifico, MP08 carta di pagamento, MP12 RiBa, MP19 SEPA Direct Debit) |
|
||||
@@ -77,9 +111,9 @@ periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura
|
||||
| **Depositi** | magazzini, anche mobili (es. furgone) |
|
||||
| **Categorie articolo** | su tre livelli |
|
||||
| **Categorie controparte** | classificazione di clienti e fornitori |
|
||||
| **Listini** | intestazioni dei listini (i prezzi sono in [Articoli e listini](Articoli-e-listini)) |
|
||||
| **Politiche di sconto** | regole di sconto riutilizzabili (struttura definita in sviluppo) |
|
||||
| **Tipi documento** | catalogo dei documenti con numeratore, causale di magazzino, causale contabile, registro IVA, codice TD, modello di stampa |
|
||||
| **Listini** | intestazioni dei listini: valuta, IVA inclusa, validità, **Listino base** (uno solo, in partenza `BASE`), **Derivato da** con ricarico % e arrotondamento (i prezzi sono in [Articoli e listini](Articoli-e-listini)) |
|
||||
| **Politiche di sconto** | sconti in cascata con un codice, come formula (`10+5`), da richiamare nelle condizioni |
|
||||
| **Tipi documento** | catalogo dei documenti con **genere** (obbligatorio), numeratore, causale di magazzino, causale contabile, registro IVA, codice TD, modello di stampa |
|
||||
| **Centri di costo** | per l'analisi dei costi e dei ricavi |
|
||||
| **Commesse** | progetti o cantieri a cui imputare costi e ricavi |
|
||||
|
||||
@@ -88,6 +122,9 @@ periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura
|
||||

|
||||
*Mockup 076 — elenco dei codici IVA con aliquota, tipo, natura SDI, esigibilità, indetraibilità e conti, con il dettaglio del codice RC17 (anteprima ridotta).*
|
||||
|
||||

|
||||
*Khaemhat 0.4.0 — l'elenco dei codici IVA di base con il dettaglio del codice 22SP (scissione dei pagamenti).*
|
||||
|
||||
Ogni codice IVA ha: **codice**, **descrizione**, **aliquota**, **tipo** (IVA, esente, non imponibile, fuori campo,
|
||||
escluso, reverse charge), **natura SDI** per le operazioni senza imposta, **riferimento normativo** (stampato in
|
||||
fattura e riportato nell'XML), **esigibilità** (`I` immediata, `D` differita, `S` scissione dei pagamenti),
|
||||
@@ -112,19 +149,33 @@ sotto-codice scelto in riga), `SPLIT` (split payment), indetraibili 50% e 100%,
|
||||
|
||||
## Numeratori
|
||||
|
||||
Ogni **tipo documento** usa un numeratore per **sezionale** e **anno**, con un **formato** che di predefinito è
|
||||
`{prefix}/{anno}/{number:D6}`, ad esempio `FT/2026/000419`. Il numero è assegnato in modo atomico **alla conferma**;
|
||||
per fatture, note di credito e registrazioni contabili definitive **non sono ammessi buchi** nella numerazione. Il
|
||||
protocollo IVA degli acquisti ha il proprio formato (es. `ACQ/{anno}/…`) e i progressivi si azzerano a ogni
|
||||
esercizio (impostazione *Reset progressivi*).
|
||||
Ogni **tipo documento** usa un numeratore per **sezionale** e **anno**, con un **formato** composto dai segnaposto
|
||||
`{prefix}`, `{year}`, `{section}` e `{number}` (con `{number:D6}` il numero ha sei cifre con gli zeri davanti). Il
|
||||
formato deve contenere `{number}`. Esempi dei numeratori di base: fatture `{number}/{year}` (`419/2026`), ordini
|
||||
clienti `OC-{year}-{number:D4}` (`OC-2026-0042`), autofatture `{number}/AF/{year}` nel sezionale `AF`.
|
||||
|
||||
Il numero è assegnato in modo atomico **alla conferma** del documento (da M5); per fatture, note di credito,
|
||||
protocollo acquisti e registrazioni contabili **non sono ammessi buchi** nella numerazione (opzione *Ammessi buchi di numerazione*
|
||||
spenta) e la data di un documento non può precedere la **data dell'ultimo numero** del numeratore. I numeratori sono
|
||||
per anno: il caricamento di base crea quelli dell'anno in corso e il primo documento di un anno nuovo crea da solo il
|
||||
numeratore di quell'anno, con le stesse regole e dal numero 1.
|
||||
|
||||
Il **genere** di un tipo documento dice come si comportano i suoi documenti: famiglia, ciclo di vita, effetti, righe
|
||||
ammesse e documenti che può evadere (vedi [Vendite](Vendite#il-motore-dei-documenti-in-sintesi)). I tipi di base hanno
|
||||
già il genere; un tipo nuovo dell'azienda (ad esempio una seconda fattura immediata con un altro sezionale) sceglie uno
|
||||
dei generi esistenti e funziona senza altre impostazioni.
|
||||
|
||||
## Preferenze e codici automatici
|
||||
|
||||

|
||||
*Mockup 074 — Preferenze azienda: maschere dei codici automatici per anagrafiche, articoli e cespiti, CRM e servizi, documenti e contabilità; elenco delle compilazioni automatiche (anteprima ridotta).*
|
||||
|
||||
La maschera **Preferenze azienda** ha le schede *Codici automatici*, *Compilazione automatica*, *Arrotondamenti e
|
||||
controlli*, *Default documenti*, *Modelli e-mail*, *Testi di stampa*.
|
||||

|
||||
*Khaemhat 0.4.0 — le maschere dei codici automatici con l'anteprima del prossimo codice; le maschere dei moduli non attivi restano pronte.*
|
||||
|
||||
La maschera **Preferenze azienda** (`/tabelle/preferenze`) ha le schede *Codici automatici* e *Compilazione
|
||||
automatica*; le schede *Arrotondamenti e controlli*, *Default documenti*, *Modelli e-mail* e *Testi di stampa*
|
||||
arrivano con i documenti e le e-mail. **Salva** registra le due schede insieme.
|
||||
|
||||
### Codici automatici
|
||||
|
||||
@@ -142,40 +193,58 @@ Per ogni archivio si imposta una **maschera**; sotto il campo compare l'anteprim
|
||||
| Contratti di servizio | `SVC-{seq:0000}` | `SVC-0001` |
|
||||
| Interventi | `MAN-{anno}-{seq:0000}` | `MAN-2026-0001` |
|
||||
|
||||
Segnaposto: `{seq:0000}` progressivo con il numero di cifre indicato, `{anno}` anno corrente, `{categoria}` codice
|
||||
della categoria. Il progressivo può essere **globale** o **per categoria / per anno**. Opzioni: *Consenti codice
|
||||
manuale* (l'utente può scrivere un codice diverso), *Blocca duplicati per EAN* (articoli). I progressivi sono
|
||||
assegnati in modo atomico: due salvataggi contemporanei non ottengono mai lo stesso codice.
|
||||
Segnaposto: `{seq:0000}` progressivo con tante cifre quanti sono gli zeri (`{seq}` senza zeri davanti), `{anno}`
|
||||
anno della registrazione, `{categoria}` codice della categoria (solo articoli). Il resto della maschera si scrive
|
||||
così com'è: lettere, cifre e `- _ / .`. Il progressivo è **globale**, riparte **ogni anno** se la maschera
|
||||
contiene `{anno}` e va **per categoria** se contiene `{categoria}`. Una maschera sbagliata (senza progressivo, con
|
||||
segnaposto sconosciuti o con codici più lunghi della tabella) viene segnalata sotto il campo e non si salva.
|
||||
|
||||
Opzioni: *Consenti codice manuale* per ogni riquadro (l'utente può scrivere un codice diverso; spento, il campo
|
||||
codice resta vuoto e il codice arriva al salvataggio), *Blocca duplicati per EAN* (articoli). Le maschere dei moduli
|
||||
non attivi (CRM, Servizi, Cespiti) si possono preparare: valgono quando il modulo viene attivato.
|
||||
|
||||
I progressivi sono assegnati **al salvataggio** dentro la stessa transazione: due salvataggi contemporanei non
|
||||
ottengono mai lo stesso codice, e un salvataggio non riuscito non consuma il numero. Se il codice successivo esiste
|
||||
già (perché scritto a mano), Khaemhat passa al numero dopo. **Cambiare la maschera non riscrive i codici già
|
||||
assegnati** e non azzera il progressivo: da `C{seq:000000}` a `CL{seq:0000}` dopo `C000123` il codice successivo è
|
||||
`CL0124`.
|
||||
|
||||
Il riquadro *Documenti e contabilità* rimanda ai [numeratori](#numeratori): fatture, protocollo e registrazioni non
|
||||
usano maschere ma numeratori per anno e sezionale.
|
||||
|
||||
### Compilazione automatica
|
||||
|
||||
| Opzione | Effetto |
|
||||
|---|---|
|
||||
| Comune, provincia e regione dal CAP | compila l'indirizzo partendo dal CAP |
|
||||
| Codice fiscale dai dati anagrafici | calcola il codice fiscale delle persone fisiche |
|
||||
| Verifica P.IVA UE (VIES) al salvataggio | interroga il servizio VIES e salva l'esito |
|
||||
| Banca e BIC dall'IBAN | ricava la banca dalla tabella ABI |
|
||||
| Cambi BCE giornalieri | scarica i cambi ogni giorno |
|
||||
| Descrizione articolo nelle righe | copia la descrizione dell'articolo nella riga del documento |
|
||||
| Ultimo prezzo praticato al cliente | lo mostra come riferimento |
|
||||
| Proponi ultimo documento simile | parte dal documento precedente dello stesso cliente |
|
||||
| Date consegna = data + lead time | calcola la consegna prevista |
|
||||
| Conti contabili da articolo, categoria, causale | propone conti di ricavo e costo |
|
||||
Ogni opzione si accende o spegne con un interruttore; spenta, i campi restano da scrivere a mano.
|
||||
|
||||
Oltre a queste, i documenti ricevono sempre destinazione, listino, pagamento e agente dal cliente e causale e
|
||||
deposito dal tipo documento.
|
||||
| Opzione | Effetto | Predefinita |
|
||||
|---|---|---|
|
||||
| Comune, provincia e regione dal CAP | scrivendo il CAP propone il comune (o i comuni) con provincia e regione; scrivendo il comune propone CAP e provincia | accesa |
|
||||
| Codice fiscale dai dati anagrafici | calcola il codice fiscale delle persone fisiche da cognome, nome, data, sesso e comune di nascita | accesa |
|
||||
| Verifica P.IVA UE (VIES) al salvataggio | interroga il servizio VIES e salva l'esito (*valida*, *non valida*, *servizio non disponibile*) | accesa |
|
||||
| Banca e BIC dall'IBAN | legge ABI e CAB dall'IBAN; banca e BIC vengono dall'elenco ABI o, finché l'elenco non è caricato, da un conto dell'azienda presso la stessa banca | accesa |
|
||||
| Cambi BCE giornalieri | l'attività di sistema scarica i cambi nei giorni lavorativi; spenta, l'azienda usa solo cambi manuali | accesa |
|
||||
| Descrizione articolo nelle righe | copia la descrizione dell'articolo nella riga del documento | accesa |
|
||||
| Ultimo prezzo praticato al cliente | lo mostra come riferimento | accesa |
|
||||
| Proponi ultimo documento simile | parte dal documento precedente dello stesso tipo e cliente | spenta |
|
||||
| Data di consegna = data + lead time | aggiunge il tempo di approvvigionamento e sposta la data al primo giorno lavorativo | accesa |
|
||||
| Conti contabili da articolo, categoria e causale | propone conti di ricavo e costo | accesa |
|
||||
|
||||
Le opzioni sulle righe e sui conti agiscono con i documenti e la contabilità (da M5). Oltre a queste, i documenti
|
||||
ricevono sempre destinazione, listino, pagamento e agente dal cliente e causale e deposito dal tipo documento.
|
||||
|
||||
### Altre preferenze aziendali
|
||||
|
||||
| Scheda | Contenuto |
|
||||
|---|---|
|
||||
| **Arrotondamenti e controlli** | arrotondamenti di prezzi e totali, controlli bloccanti o di avviso (fido, scaduto, date) |
|
||||
| **Default documenti** | sezionali, depositi, causali e condizioni proposti per tipo documento |
|
||||
| **Modelli e-mail** | testi per l'invio di documenti, solleciti, notifiche |
|
||||
| **Testi di stampa** | diciture e note in calce ai documenti |
|
||||
In 0.4.0 le preferenze azienda hanno le schede *Codici automatici* e *Compilazione automatica*. Arriveranno con i
|
||||
moduli che le usano:
|
||||
|
||||
La periodicità IVA e le numerazioni fanno parte delle preferenze aziendali e si impostano nel profilo e nei
|
||||
numeratori. Il dettaglio di ogni opzione sarà completato in sviluppo.
|
||||
| Scheda | Contenuto | Con |
|
||||
|---|---|---|
|
||||
| **Arrotondamenti e controlli** | arrotondamenti di prezzi e totali, controlli bloccanti o di avviso (fido, scaduto, date) | documenti (M5) |
|
||||
| **Default documenti** | sezionali, depositi, causali e condizioni proposti per tipo documento | documenti (M5) |
|
||||
| **Modelli e-mail** | testi per l'invio di documenti, solleciti, notifiche | e-mail (M5) |
|
||||
| **Testi di stampa** | diciture e note in calce ai documenti | stampe (M5) |
|
||||
|
||||
La periodicità IVA e le numerazioni si impostano nel profilo azienda e nei numeratori.
|
||||
|
||||
## Permessi e licenza
|
||||
|
||||
@@ -188,8 +257,9 @@ con i rispettivi moduli attivi. La conferma della liquidazione e la chiusura del
|
||||
modificare i codici predefiniti usati in documenti già emessi.
|
||||
- **Non riesco a inserire un documento con data di agosto.** Il periodo è bloccato o liquidato: chiedi a chi gestisce
|
||||
la contabilità.
|
||||
- **Posso cambiare la maschera dei codici clienti a metà anno?** I codici già assegnati non vengono riscritti: la
|
||||
nuova maschera vale per i codici successivi (il comportamento in caso di conflitti sarà definito in sviluppo).
|
||||
- **Posso cambiare la maschera dei codici clienti a metà anno?** Sì: i codici già assegnati non vengono riscritti,
|
||||
la nuova maschera vale per i codici successivi e continua lo stesso progressivo; un codice che esiste già viene
|
||||
saltato.
|
||||
|
||||
## Pagine correlate
|
||||
|
||||
|
||||
@@ -1,8 +1,14 @@
|
||||
# Utenti e permessi
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2)
|
||||
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2)
|
||||
> **Modulo di licenza:** CORE · **Livello richiesto:** amministratore (amministratori: solo super utente) · **Permessi principali:** `company.users.manage` · **Specifica:** SPEC §7, §12.3, §12.4
|
||||
|
||||
> **Nella versione 0.2.0** ci sono il motore e l'accesso: i tre livelli, gli account di istanza e gli utenti di
|
||||
> azienda, password con storico e blocco, verifica in due passaggi con codici di recupero, sessioni revocabili, ruoli
|
||||
> predefiniti e permessi `modulo.area.azione` con override, controlli sulle pagine (`[RequirePermission]`,
|
||||
> `[RequireLevel]`, `[RequireModule]`). Le schermate **Utenti** e **Ruoli e permessi** descritte qui arrivano in M12:
|
||||
> fino ad allora gli utenti si gestiscono solo con il super utente creato dal container.
|
||||
|
||||
## A cosa serve
|
||||
|
||||
Queste due pagine stabiliscono **chi entra** in Khaemhat e **cosa può fare**:
|
||||
|
||||
@@ -1,288 +1,350 @@
|
||||
# Vendite
|
||||
|
||||
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **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 è descritto da una definizione che stabilisce: numeratore e sezionale, causale di magazzino
|
||||
(se il documento carica o scarica merce), **effetti** (impegno, scarico, partite, registrazione contabile), 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:
|
||||
|
||||
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**.
|
||||
|
||||
## 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*).
|
||||
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*).
|
||||
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.
|
||||
- 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; 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
|
||||
|
||||
- Formato `{prefisso}/{anno}/{numero a 6 cifre}`, ad esempio `FT/2026/000418`, per **sezionale** (FT, NC, DDT…) e
|
||||
anno, configurato nei numeratori (vedi [Tabelle azienda](Tabelle-azienda)).
|
||||
- Il numero è assegnato **alla conferma**, in modo atomico: le bozze non consumano numeri.
|
||||
- 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 sezionale.
|
||||
- La data deve cadere in un **periodo fiscale aperto** (vedi esercizi e periodi in [Tabelle azienda](Tabelle-azienda)).
|
||||
- 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 **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; la **trasformazione** cambia tipo mantenendo i
|
||||
collegamenti (preventivo → ordine).
|
||||
- **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: 122 KiB |
|
After Width: | Height: | Size: 119 KiB |
|
After Width: | Height: | Size: 84 KiB |
|
After Width: | Height: | Size: 119 KiB |
|
After Width: | Height: | Size: 115 KiB |
|
After Width: | Height: | Size: 150 KiB |
|
After Width: | Height: | Size: 134 KiB |
|
After Width: | Height: | Size: 159 KiB |
|
After Width: | Height: | Size: 93 KiB |
|
After Width: | Height: | Size: 89 KiB |
|
After Width: | Height: | Size: 127 KiB |
|
After Width: | Height: | Size: 115 KiB |
|
After Width: | Height: | Size: 215 KiB |
|
After Width: | Height: | Size: 89 KiB |
|
After Width: | Height: | Size: 74 KiB |
|
After Width: | Height: | Size: 54 KiB |
|
After Width: | Height: | Size: 98 KiB |
|
After Width: | Height: | Size: 101 KiB |
|
After Width: | Height: | Size: 140 KiB |
|
After Width: | Height: | Size: 99 KiB |
|
After Width: | Height: | Size: 93 KiB |
|
After Width: | Height: | Size: 119 KiB |
|
After Width: | Height: | Size: 117 KiB |
|
After Width: | Height: | Size: 111 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 |
@@ -3,7 +3,8 @@
|
||||
# Any KHAEMHAT_* variable already set in the shell wins over the defaults below.
|
||||
set -euo pipefail
|
||||
|
||||
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
# Under Git Bash on Windows, pwd -W gives B:/... instead of /b/..., which .NET would read as a folder b on the drive.
|
||||
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && (pwd -W 2>/dev/null || pwd))"
|
||||
cd "$root"
|
||||
|
||||
data_dir="$root/.data/dev"
|
||||
@@ -11,7 +12,10 @@ mkdir -p "$data_dir"
|
||||
|
||||
export ASPNETCORE_ENVIRONMENT="${ASPNETCORE_ENVIRONMENT:-Development}"
|
||||
export KHAEMHAT_DATA_DIR="${KHAEMHAT_DATA_DIR:-$data_dir}"
|
||||
export KHAEMHAT_SYSTEM_DB="${KHAEMHAT_SYSTEM_DB:-sqlite://$data_dir/system.db}"
|
||||
# sqlite:///home/... on Linux and macOS, sqlite:///B:/... on Windows.
|
||||
db_path="$data_dir"
|
||||
[[ "$db_path" == /* ]] || db_path="/$db_path"
|
||||
export KHAEMHAT_SYSTEM_DB="${KHAEMHAT_SYSTEM_DB:-sqlite://$db_path/system.db}"
|
||||
# Development-only key: never use it outside this script.
|
||||
export KHAEMHAT_SECRET_KEY="${KHAEMHAT_SECRET_KEY:-a2hhZW1oYXQtZGV2ZWxvcG1lbnQtb25seS1ub3QtYS1zZWNyZXQ=}"
|
||||
export KHAEMHAT_SUPERUSER="${KHAEMHAT_SUPERUSER:-root}"
|
||||
|
||||
@@ -1,9 +1,17 @@
|
||||
#!/usr/bin/env bash
|
||||
# Loads base tables and demo data into a company database (SPEC §15).
|
||||
# scripts/seed.sh --base | --demo [--scale N] [--company CODE]
|
||||
# Stub: completed in milestone M4 (SPEC §20). Until then it explains what it will do and exits with an error.
|
||||
# Adds the missing base tables to the company databases (SPEC §14, ADR 0026), and with --demo the demo data to the
|
||||
# tables still empty (--scale N repeats the demo catalogues N times). Rows already there are never changed.
|
||||
# scripts/seed.sh --base [--company CODE]
|
||||
# scripts/seed.sh --demo [--scale N] [--company CODE]
|
||||
# In the container (shipped as /app/scripts/seed.sh, same KHAEMHAT_* variables as the service):
|
||||
# docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --base
|
||||
# On a development machine it runs the project with the variables already set in the shell (see scripts/run-dev.sh).
|
||||
set -euo pipefail
|
||||
|
||||
echo "seed.sh: non ancora disponibile, arriva con la milestone M4." >&2
|
||||
echo "Uso previsto: scripts/seed.sh --base | --demo [--scale N] [--company CODE]" >&2
|
||||
exit 1
|
||||
if [[ -f /app/Khaemhat.Web.dll ]]; then
|
||||
# The entrypoint prepares the user and waits for the database, then runs "dotnet Khaemhat.Web.dll seed ...".
|
||||
exec /app/entrypoint.sh seed "$@"
|
||||
fi
|
||||
|
||||
root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
exec dotnet run --project "$root/src/Khaemhat.Web" -- seed "$@"
|
||||