Compare commits

..
Author SHA1 Message Date
Alby96andClaude Opus 5.5 83ef60fce2 docs: record owner decisions on mockups, bank list and SDI channels (#35 #45 #78)
CI / Build and test (SQLite) (pull_request) Successful in 5m27s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 6s
CI / Docker image (pull_request) Successful in 1m59s
The owner confirmed that no further high-resolution mockups exist, gave up
the preloaded ABI/CAB bank list and set aside real SDI intermediaries,
SdICoop accreditation and a test PEC mailbox. ADR 0044 records this so the
next milestones stop waiting on that material: thumbnail-only screens are
designed from the thumbnail and the existing UI, bank name and BIC come
from a company account or are typed once, and #78 moves to the backlog.
CLAUDE.md E4, the mockup index, related ADRs, status, changelog and the
user guide are updated accordingly.

Closes #35
Closes #45

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 17:19:01 +01:00
Alby96 a8f00cbae0 Merge M10 · Cespiti, Intrastat, chiusura, bilancio (v0.10.0) (#129)
Wiki / Publish the wiki (push) Successful in 9s
Release / Image and release (push) Successful in 3m32s
CI / PostgreSQL 16 integration (push) Successful in 2m17s
CI / Build and test (SQLite) (push) Successful in 4m38s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 6s
CI / PostgreSQL 17 integration (push) Successful in 1m58s
2026-11-13 20:26:03 +01:00
Alby96andClaude Opus 5.5 51007d68ca feat: fixed assets, Intrastat, intent declarations, year-end closing and statements (#82 #83 #84 #85 #86 #87)
CI / Build and test (SQLite) (pull_request) Successful in 4m35s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Successful in 1m24s
M10 gives the ledger its year end. Fixed assets get categories with the
ministerial coefficients, a civil and a fiscal plan, depreciation posted
per category and undoable, disposals with gain or loss and the register
print (ADR 0041). Intrastat lists are generated from confirmed invoices
with the due periodicity and the SCAMBI.CEE file; declarations of intent
get their own register and the N3.5 ceiling is checked when an invoice is
confirmed (ADR 0042). Accruals, deferrals and exchange differences feed a
nine-step guided closing that can repeat or undo its last step until the
final prints, reopens the next year and locks the closed one; the CEE
statements (ordinary, abbreviated, micro), the reclassified statements,
the ratios and the accountant export read the year's balances (ADR 0043).

The demo seed now opens the year with assets, stock, bank and capital, so
the integration test closes the demo year from the checks to the lock on
SQLite and PostgreSQL. Docs: wiki pages with screenshots, ADR 0041-0043,
MODULES, STATUS, DATA-MODEL and the 0.10.0 changelog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 19:31:26 +01:00
Alby96andClaude Opus 5.5 836a316b05 Merge M9 · Fatturazione elettronica (v0.9.0) (#128)
Wiki / Publish the wiki (push) Successful in 10s
Release / Image and release (push) Successful in 3m25s
CI / PostgreSQL 16 integration (push) Successful in 1m45s
CI / Build and test (SQLite) (push) Successful in 4m14s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 4s
CI / PostgreSQL 17 integration (push) Successful in 1m46s
E-invoicing: FatturaPA files checked offline with the SDI codes, four channels with routing and fallback, notifications, inbox, conservation packages, demo e-invoices and schema-driven demo removal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 13:31:14 +01:00
Alby96andClaude Opus 5.5 246d6f9357 docs: e-invoicing guide, ADR 0039-0040 and 0.9.0 changelog (#81)
CI / Build and test (SQLite) (pull_request) Successful in 4m27s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 7s
CI / Docker image (pull_request) Successful in 1m30s
The wiki page "Fatturazione elettronica" becomes a complete guide for 0.9 with
nine screenshots of the real screens, and the pages that pointed to M9 now
describe what shipped (demo data and their removal, scheduled jobs, sales,
purchases, Italian tax rules, user guide). ADR 0039 records the e-invoice
design (file rows, progressive, offline checks with SDI codes and in-house
schema, notification dedup, safe polling, routing, SdICoop push with channel
key) and ADR 0040 the generic intermediary contracts and the schema-driven
removal of demo data. Screen polish: dashboard actions in the header, filters
on two rows, tables no longer squeezed, report titles and notification errors;
demo e-invoices get realistic send times and a rejection in the history.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 13:24:31 +01:00
Alby96andClaude Opus 5.5 b78260beb0 feat: e-invoice screens and SdICoop push endpoint (#74 #75 #76 #77 #79)
The SDI dashboard (mockup 058) with its six counters, the documents to
generate, generate+send, manual receipts import, history, courtesy copy
and mark-as-sent; the channels page (mockup 059) with settings, test,
pause and routing rules; the received invoices, the notifications and
the conservation packages. The SdICoop web service receives pushes at
/sdicoop/{company}, authenticated by the key of the channel, through a
new IEInvoicePushReader feature so the web layer stays country-neutral.
The menu gives each e-invoice page its own permission and keeps the
intent declarations under M10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 12:54:09 +01:00
Alby96andClaude Opus 5.5 9d7cb9e71f feat: demo e-invoices, demo data removal and e-invoice integration tests (#79 #80)
The demo company now has its electronic invoices: a paused PEC channel and an
intermediary, routing rules, the files of the demo invoices with the notifications
the SDI would send (delivered, one rejected, one not delivered, some waiting) read
by the fiscal pack as real ones, and three supplier invoices in the inbox with their
metadata. Every demo seeder now marks as demo also the rows the services write for
it (entries, open items, payments, mandates, statements), so the new
DemoDataRemover, driven by the schema of the migrations, removes the demo data and
only them; it stops and names the tables when rows entered by users still refer to
demo rows. `scripts/seed.sh --remove-demo` exposes it and the seed prints its time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 12:33:07 +01:00
Alby96andClaude Opus 5.5 fb12411404 feat: e-invoice services, SDI channels, inbox, polling and conservation (#74 #75 #76 #77 #79)
Adds the company tables of the electronic invoice and the services that drive them:
the builder turns an issued document into the FatturaPA model, the service generates,
checks and sends the file through the channel chosen by the routing rules (with a
fallback) and applies the SDI notifications to the e-invoice and its document. The
channel settings keep their secrets protected and out of the audit trail; a job reads
the PEC mailbox and the intermediaries every 15 minutes, storing supplier invoices in
the inbox and acknowledging a message only once all its files are kept. The inbox
registers received invoices through the purchase import, and the conservation export
packs a period with a SHA-256 index. A rejected invoice can now be corrected and
generated again; the courtesy PDF embeds the XML.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 12:20:59 +01:00
Alby96andClaude Opus 5.5 709bb13532 feat: FatturaPA writer, validator, SDI receipts and transport channels (#74 #75 #76 #77)
The Italian pack can now produce and check the e-invoice and talk to the SDI:
- FatturaPaWriter writes FPR12/FPA12 v1.2 with SDI file naming; FatturaPaValidator
  checks it against an embedded schema and the AdE semantic rules (official codes).
- SdiReceiptReader reads RC, NS, MC, NE, DT, AT, MT and SE notifications.
- The incoming-invoice model becomes the shared EInvoice* model, read and written.
- In-house ImapClient and MimeParser (no external libraries) back the PEC channel;
  SdICoop (SOAP/MTOM with client certificate) and two generic REST intermediaries
  sit behind the same IEInvoiceTransport contract, with fake-server tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 11:51:31 +01:00
Alby96 0debd82983 Merge M8 · Scadenzario e tesoreria (v0.8.0) (#127)
Wiki / Publish the wiki (push) Successful in 7s
Release / Image and release (push) Successful in 2m43s
CI / PostgreSQL 16 integration (push) Successful in 1m39s
CI / Build and test (SQLite) (push) Successful in 3m47s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 4s
CI / PostgreSQL 17 integration (push) Successful in 1m29s
Closes #69 #70 #71 #72 #73
2026-11-13 10:09:45 +01:00
Alby96andClaude Opus 5.5 f38b5894ce docs: close M8 with treasury wiki, screenshots and screen fixes (#69 #70 #71 #72 #73)
CI / Build and test (SQLite) (pull_request) Successful in 3m51s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Successful in 1m22s
Rewrite the Scadenzario wiki page from the real screens and services, add
ADR 0038, the 0.8.0 changelog, STATUS, MODULES and the regenerated data
model, and update the pages that still pointed to M8.

The browser check found a few screen defects, fixed here: reminder
channels are flags, so they show as "e-mail + PEC" and are edited with
check boxes; icon buttons in grids stay on one row; the summary strip no
longer collapses on long pages; the customers/suppliers switch uses the
right style; the cash flow bars scale between the lowest and highest
balance. The late payment rate of the second half of 2026 is 2.40 (MEF,
GU 163 of 16 July 2026), now covered by tests, and the mapping test
knows the ten treasury tables.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 09:59:57 +01:00
Alby96andClaude Opus 5.5 aef0a0d233 feat: schedule and treasury screens (#69 #70 #71 #72)
The pages of the Scadenzario area follow mockups 053-057: open items with aging,
the collection and payment dialog, collections and payments of a period,
remittances (new, file, presentation, credit, unpaid), SDD mandates, reminders
with levels and history, bank reconciliation with rules, and the cash flow
forecast. The dashboard shows the items due among the deadlines and the overdue
receivables among the things to do. Texts are in Treasury.json; the menu lists
the new pages and no longer marks the area as coming.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 09:36:33 +01:00
Alby96andClaude Opus 5.5 4014373797 feat: demo treasury and integration tests for the schedule (#69 #70 #71 #72)
The demo company gets a bank account with the capital paid in, collections and
supplier payments (one customer pays only half), a RiBa remittance presented,
credited and with one effect back unpaid, a draft remittance for the next weeks,
a direct debit mandate, a CSV statement to reconcile with a rule for the bank
fees, and a first reminder already sent. The seeder runs only when FIN is
licensed and only once.

The tests run the demo on a real instance: collections registered and cancelled,
the CBI file written, the statement reconciled, reminders and cash flow, with the
trial balance checked after every flow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 09:17:29 +01:00
Alby96andClaude Opus 5.5 5bbc2120a1 feat: remittances, SDD mandates, bank reconciliation, dunning and cash flow services (#70 #71 #72)
Remittances draft the items due, write the RiBa CBI or SEPA pain.001/pain.008
file, present them (bills account and advance, or supplier payments), credit
them and record unpaid effects with their fees. The reconciliation imports
CSV, CBI and CAMT.053 statements without duplicates and proposes matches with
open items, payments, F24, remittances and saved rules. Reminders follow three
levels with late interest, e-mail/PEC/letter and customer block, also from a
scheduled task; the cash flow forecasts 90 days by week.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 09:06:04 +01:00
Alby96andClaude Opus 5.5 562bf98092 feat: schedule and payments services; posting keeps settled open items (#69)
The schedule lists the open items with aging, disputes and statement of
account; a collection or payment settles items with allowances, exchange
differences and fees, writes its INC/PAG entry and makes the withholding of a
fully paid invoice due. Reposting a document now updates its items by
installment and refuses to drop what was already collected.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 08:53:21 +01:00
Alby96andClaude Opus 5.5 5fbbe4d3a4 feat: SEPA, RiBa and bank statement file formats for treasury (#70 #71)
Remittances need files the banks accept and statements need readers for
reconciliation, without external libraries:

- SepaXmlWriter writes pain.001.001.09 credit transfers and pain.008.001.08
  direct debits (one PmtInf per sequence and collection date), reducing texts
  to the SEPA Latin set and refusing what a bank would reject.
- Camt053Reader reads any camt.053.001.xx by local names; CsvStatementReader
  reads home banking exports (UTF-8 or Windows-1252, Italian or English
  numbers) and guesses the layout from the header row.
- The Italian pack gains RibaCbiWriter (CBI Ricevute bancarie, 120-character
  records IB/14/20/30/40/50/51/70/EF) and CbiStatementReader (RH/61-64/EF).
- Tests validate the SEPA files against hand-written subsets of the ISO 20022
  schemas, to be replaced by the official XSDs when available.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 08:51:09 +01:00
Alby96andClaude Opus 5.5 b12dc79317 feat: treasury data model, rules and migration (#69 #70 #71 #72)
Open items gain their schedule state; payments, remittances, mandates, bank
statements, match rules and dunning get their tables. Pure rules for aging,
allocation, payment posting, late interest, bank matching, dunning levels and
cash flow periods. The Italian pack adds the treasury accounts, templates and
the late payment rates of D.Lgs. 231/2002.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 08:42:48 +01:00
Alby96andClaude Opus 5.5 88a0c8ce9c feat: bank file contracts for remittances and statements (#70 #71)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 08:32:59 +01:00
Alby96andClaude Opus 5.5 cfca29d71c Merge M7 · Contabilità generale e IVA (v0.7.0) (#126)
Wiki / Publish the wiki (push) Successful in 14s
CI / PostgreSQL 16 integration (push) Successful in 1m44s
CI / Build and test (SQLite) (push) Successful in 4m3s
CI / Docker image (push) Skipped
CI / PostgreSQL 17 integration (push) Successful in 1m27s
CI / YAML check (push) Successful in 6s
Release / Image and release (push) Successful in 2m24s
General ledger, automatic posting of documents, VAT registers and settlement, withholdings, stamp duty and F24 (#62-#68). Gitea Actions created no run for this PR: build, the full suite (754) and the PostgreSQL 18 data tests (110) passed locally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 03:49:32 +01:00
Alby96andClaude Opus 5.5 9e3ba92993 feat: general ledger, automatic posting, VAT settlement, withholdings and F24 (#62 #63 #64 #65 #66 #67 #68)
M7 adds the double-entry ledger so that the documents of M5 and M6 reach the
accounts without retyping, and the Italian VAT obligations can be prepared from
the same data.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 01:41:58 +01:00
Alby96 838362bfe1 Merge M6 · Acquisti e Magazzino (v0.6.0) (#125)
CI / YAML check (push) Failing after 58s
CI / Build and test (SQLite) (push) Successful in 4m11s
CI / PostgreSQL 16 integration (push) Skipped
CI / PostgreSQL 17 integration (push) Skipped
CI / Docker image (push) Failing after 1m19s
Purchase cycle, supplier e-invoice import, self-invoices and a warehouse posted from the documents, with the user guide in the wiki.

Closes #55 #56 #57 #58 #59 #60 #61
2026-11-12 22:37:36 +01:00
Alby96andClaude Opus 5.5 7f8cb57a08 docs: record M6 as closed (v0.6.0) and M7 as the current milestone (#61)
CI / Build and test (SQLite) (pull_request) Failing after 45s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / Docker image (pull_request) Skipped
CI / YAML check (pull_request) Successful in 1m1s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:35:34 +01:00
Alby96andClaude Opus 5.5 4b759ee96e docs: purchases and warehouse guide with screenshots, ADR 0035 and the 0.6.0 changelog (#61)
CI / Build and test (SQLite) (pull_request) Canceled after 0s
CI / PostgreSQL 16 integration (pull_request) Canceled after 0s
CI / PostgreSQL 17 integration (pull_request) Canceled after 0s
CI / Docker image (pull_request) Canceled after 0s
CI / YAML check (pull_request) Canceled after 0s
The Acquisti and Magazzino wiki pages now describe what M6 delivers, with real
screenshots of the demo company: stock, item movements, valuation, stock take, reorder
proposal, receipts, price differences, e-invoice import and pending self-invoices. The
user guide gains the buying and warehouse steps; the pages that said "arriva con M6"
(sales, items, dashboard, import, scheduled jobs, demo data) are brought up to date.
ADR 0035 records how documents post to the warehouse, the recomputed weighted average,
the invoice cost correction, the rebuild, the stock take, the base tables of existing
companies and where the Italian self-invoice and import rules live.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:24:43 +01:00
Alby96andClaude Opus 5.5 cd4cb85562 fix: tidy the warehouse screens and the supplier document labels (#55 #60)
Seen while checking M6 in the browser: the stock take toolbar crowded the panel title,
the reorder and stock take tables ran past their panel, and the movements dialog cut
the balance column. Confirmed supplier receipts have no number of their own and showed
"Bozza"; they now read "Senza numero". The self-invoice advice no longer doubles the
full stop, and a single price difference reads in the singular.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:24:43 +01:00
Alby96andClaude Opus 5.5 ced689b297 feat: warehouse and purchase screens, e-invoice import, demo purchases (#55 #56 #57 #58 #60)
Stock, stock take and reorder screens under /magazzino, with valuation, rebuild and the
movements of an item; the understock dashboard widget. Supplier e-invoices (XML, p7m, ZIP)
become draft purchase invoices with supplier, items and tax codes matched, the file attached
and duplicates refused; the TD code mapping stays in the Italian fiscal pack. Purchase
invoices show price differences against the order and the self-invoice still to issue,
with a pending list on the self-invoice screen. The opening stock import now writes an
opening movement. The demo company gets purchases, an opening stock, a pending
self-invoice and a stock take being counted.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 22:01:32 +01:00
Alby96andClaude Opus 5.5 eb301fa570 feat: stock take, reorder proposal and warehouse rebuild (#60)
A physical stock take freezes the book quantity and cost of a warehouse at a
date, takes counts typed or read from a scanner file, and posts the gains and
losses as INVP/INVN movements at that date. The reorder proposal lists the
items whose available and ordered quantity no longer covers the reorder point
and turns the accepted lines into draft supplier orders, one per supplier.
The warehouse can be rebuilt from its documents on demand and every Sunday
night, as a safety net after imports or corrections.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 21:35:34 +01:00
Alby96andClaude Opus 5.5 f8b72f4d17 feat: purchase and warehouse documents on the document screens (#55 #56 #58)
The document radars and records now serve /acquisti and /magazzino too:
supplier orders, receipts, supplier invoices and credit notes, self-invoices
and warehouse movements, with the supplier in place of the customer, the
supplier's number and date, the protocol and VAT date of registered invoices,
and reason and warehouses of a movement. Supplier invoices take their
protocol from the purchase numbering, refuse a second document with the same
supplier number in the same year and show price differences against their
order or receipt. The Italian pack advises the self-invoice a received
invoice needs (TD16-TD19, TD28) with its deadline, and the purchase service
drafts it with the ordinary rate. A credit note of an invoice now moves its
goods back instead of being skipped as already moved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 21:25:25 +01:00
Alby96andClaude Opus 5.5 eeabb12f96 feat: post documents to the warehouse at weighted average cost (#59)
Confirmed delivery notes, invoices that move goods, supplier receipts and
warehouse movements now write stock movements in the same transaction;
cancelling removes them. Each change re-runs the history of the items
touched, so balances per warehouse, committed and ordered quantities and
the average and last cost stay consistent even when an old document is
cancelled. Supplier invoices give their cost to the receipts they invoice.
Immediate invoices, supplier invoices and credit notes get their warehouse
reasons; the self-invoice types TD20-TD29 join the base tables.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 21:13:27 +01:00
Alby96 20b2421eea Merge branch 'refs/heads/worktree-agent-a350efc9cb07bc00b' into feat/55-acquisti-magazzino 2026-11-12 21:09:11 +01:00
Alby96andClaude Opus 5.5 9a40adecfe feat: read FatturaPA invoices and signed p7m files (#57)
The import of supplier e-invoices needs a reading layer that turns a
received file into plain records, whatever form the file arrives in.

- Fiscal.Abstractions: IIncomingInvoiceReader, an optional pack feature,
  with the IncomingInvoiceFile records and the incoming.* error codes the
  import service and screens build on.
- Infrastructure: CmsSignedData, a minimal CMS SignedData (CAdES .p7m)
  reader on System.Formats.Asn1, since System.Security.Cryptography.Pkcs
  is a separate package. It accepts DER, BER with indefinite lengths and
  chunked content, base64 text and nested envelopes; it checks the
  message digest and the RSA (PKCS#1, PSS) or ECDSA signature with the
  embedded certificate and reports signer, tax code, validity and signing
  time. No trust chain or revocation check: no trusted list offline.
- Fiscal.Italy: FatturaPaReader for FPR12/FPA12 v1.2.x and FSM10, matched
  by local name, DTD prohibited and no resolver, BOM/windows-1252/missing
  declaration tolerated, batches as one invoice per body, attachments
  decoded; registered in ItalyFiscalPack.
- Tests build every sample and signed envelope in code (AsnWriter and
  self-signed certificates), nothing downloaded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 21:08:29 +01:00
Alby96 2c56c0dff0 Merge M5 · Motore documenti e vendite (v0.5.0) (#124)
Wiki / Publish the wiki (push) Successful in 7s
Release / Image and release (push) Successful in 3m12s
CI / PostgreSQL 16 integration (push) Successful in 2m6s
CI / Build and test (SQLite) (push) Successful in 2m55s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 9s
CI / PostgreSQL 17 integration (push) Successful in 1m47s
Document engine, sales cycle, printing and mail of documents, user guide in the wiki.

Closes #47 #48 #49 #50 #51 #52 #53 #54
2026-11-12 18:48:55 +01:00
Alby96andClaude Opus 5.5 cd3e22e8c7 docs: record the M5 pull request in STATUS (#54)
CI / Build and test (SQLite) (pull_request) Successful in 4m7s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 14s
CI / Docker image (pull_request) Successful in 1m49s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 17:39:37 +01:00
Alby96andClaude Opus 5.5 4123ccacb2 docs: user guide with real screenshots, developer README and M5 closing (#53 #54)
CI / Build and test (SQLite) (pull_request) Canceled after 0s
CI / PostgreSQL 16 integration (pull_request) Canceled after 0s
CI / PostgreSQL 17 integration (pull_request) Canceled after 0s
CI / Docker image (pull_request) Canceled after 0s
CI / YAML check (pull_request) Canceled after 0s
The wiki becomes a guide for the people who use Khaemhat: a new "Guida all'uso"
page walks from sign-in to an invoice sent by e-mail, and Vendite is rewritten
around the real screens of 0.5.0 (radars, document mask, Crea …, deferred
invoicing, print preview, mail). Primi passi, Dati di esempio, Allegati, Log
and Impostazioni describe what this version does, including the SMTP variables.

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

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 17:38:14 +01:00
Alby96andClaude Opus 5.5 826042f828 feat: sales screens, deferred invoicing, printing and mail of documents (#49 #50 #51 #52)
Quotations, orders, delivery notes, invoices and credit notes get their radars and
one document screen (lines, header, transport, links, attachments) with the
transformations of the engine, so a quotation reaches the invoice without
retyping. The deferred invoicing groups the open delivery notes of a period by
customer, payment and destination into one invoice each.

Every document prints from one model: an HTML preview on screen and a PDF drawn
by the in-house writer, kept among the attachments as a new version. "Invia per
e-mail" proposes recipient, subject and text from the templates, attaches the
PDF and hands it to a background queue that talks SMTP itself (no external
library); the outcome goes to the log, section E-mail/PEC.

The demo company now has a year of sales in every state, made through the
engine, and run-dev.sh no longer writes to a stray B:\b folder under Git Bash.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 17:20:25 +01:00
Alby96andClaude Opus 5.5 f12848865d feat: document totals, VAT summary, stamp duty, withholding and installments (#48)
The engine now computes the totals of every document it saves: line amounts with
cascaded discounts, footer discount on goods, VAT summary per tax code with the tax
on the group total, prices with VAT split back once per group, split payment and
cash-basis exigibility, stamp duty above the threshold of the fiscal pack, social
security contribution, withholding (also on part of the amount) and ENASARCO taken
off the amount to pay. Installments come from the payment terms with end of month,
fixed day, the customer's excluded months and VAT on the first installment.

The figures live in two shared tables keyed by family (ADR 0033) and are rewritten
in the same transaction as the document. DocumentEditor serves the screens: radars,
values proposed by party and item, totals preview without saving, linked documents
and open documents to fulfil. The copy service can merge several documents of one
party, the base of deferred invoicing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 15:55:58 +01:00
Alby96andClaude Opus 5.5 ddd2273f7e feat: document engine with kinds, states, atomic numbering and fulfilment (#47)
One engine for sales, purchases and warehouse documents (ADR 0032). Each document
type now carries a kind that decides its family of tables, life cycle, effects,
accepted lines, the kinds it fulfils and its permissions, so company-defined types
work without code.

- Six families of header and line tables plus document_links; document_types gets
  document_kind (seeded types filled by the migration and the Italian template),
  document_numerators gets last_date.
- DocumentStateMachine with the order, invoice and simple life cycles and the
  actions each state admits; issued invoices are immutable and are cancelled with
  a reason only before the file reaches the exchange system.
- DocumentNumberingService numbers at confirmation inside the transaction under
  the numerator lock (advisory lock on PostgreSQL, write lock on SQLite): no
  duplicates, a rollback gives the number back, out-of-sequence dates refused on
  gap-free numerators, the new year's numerator created on first use, gap report.
- DocumentEngine, the generic DocumentService<THeader, TLine> and
  DocumentCopyService: save, confirm or issue, cancel, close, reopen, delete,
  duplicate and transform; links are recorded at confirmation and removed at
  cancellation, and FulfillmentCalculator recomputes quantities and states.
- Tests: rules in Core, concurrent numbering on SQLite and PostgreSQL (data tests,
  run on PostgreSQL 18 locally), order to delivery notes to deferred invoice on a
  real instance. Wiki (Vendite, Tabelle azienda), CHANGELOG, STATUS, DATA-MODEL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 15:30:24 +01:00
Alby96 fa9304834a Merge ci: smoke test dell'immagine senza falsi errori di pipe (#123)
CI / Build and test (SQLite) (push) Successful in 3m10s
CI / PostgreSQL 16 integration (push) Skipped
CI / PostgreSQL 17 integration (push) Skipped
CI / YAML check (push) Successful in 9s
CI / Docker image (push) Successful in 1m57s
2026-11-12 14:01:10 +01:00
Alby96andClaude Opus 5.5 5ba28483a8 ci: read the login page before grepping it in the image smoke test
CI / Build and test (SQLite) (pull_request) Successful in 2m44s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 6s
CI / Docker image (pull_request) Successful in 1m28s
The Docker image job failed on main after the M4 merge although the
container was ready: grep -q stops at the first match and closes the pipe,
curl then fails with a write error (exit 23) and pipefail fails the step.
It depends on timing, which is why the same commit passed on the pull
request. The response and the headers are now read into variables first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 13:44:29 +01:00
Alby96 02219df9de Merge docs: chiusura M4 (#122) 2026-11-12 13:43:38 +01:00
Alby96andClaude Opus 5.5 11f69b6111 docs: record M4 as closed (v0.4.0) and M5 as the current milestone
CI / Build and test (SQLite) (pull_request) Successful in 2m50s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 6s
CI / Docker image (pull_request) Successful in 1m56s
STATUS is the resume point of every session; after the M4 merge, tag,
image and release it must point at M5 instead of the pending merge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 13:13:05 +01:00
Alby96 e53b14a3c5 Merge M4 · Tabelle, anagrafiche, articoli (#121)
Wiki / Publish the wiki (push) Successful in 8s
Release / Image and release (push) Successful in 2m58s
CI / PostgreSQL 16 integration (push) Successful in 2m27s
CI / Build and test (SQLite) (push) Successful in 2m44s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 5s
CI / PostgreSQL 17 integration (push) Successful in 2m42s
2026-11-12 13:03:35 +01:00
Alby96andClaude Opus 5.5 b323d70f83 docs: close M4 with real screenshots, complete wiki pages and the 0.4.0 changelog (#46)
CI / Build and test (SQLite) (pull_request) Successful in 3m11s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 23s
CI / Docker image (pull_request) Successful in 1m53s
The milestone's Definition of Done asks for complete wiki pages with real
screenshots, a changelog for everything delivered, an image that builds
locally and a SQLite demo that starts from zero. Ten screenshots taken on a
fresh demo instance now sit next to the mockups; Anagrafiche, Articoli e
listini and Tabelle azienda are complete, Import-Export and Dati di base are
complete for M4, and the preference tabs still to come say which milestone
brings them. The changelog gains its 0.4.0 section, and STATUS, Roadmap,
Changelog and Home point at 0.4.0 and M5.

The screenshots showed that the import preview pushed the outcome column off
the right edge, so its reasons could not be read: the outcome now follows
the line number and the table scrolls sideways. The warnings for values
filled from the postal code no longer repeat the column name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 12:26:06 +01:00
Alby96andClaude Opus 5.5 caa33a2cee feat: guided import and export for parties, items, prices, opening stock and chart of accounts (#44)
Companies starting on Khaemhat need to bring their master data from another
system or a spreadsheet, and the chart of accounts has no Italian exchange
standard, so SPEC 12.12 asks for a guided wizard and an own layout.

- Administration > Import / export: CSV (separator and encoding guessed),
  XLSX (in-house reader, first sheet) and JSON, automatic column mapping with
  aliases, row-by-row check, error report, import confirmation and log entry.
- Rows go through PartyService, ItemService and PriceListService, so the
  import has exactly the rules, error codes and history of the forms; options
  cover existing and missing codes, VIES and city from postal code.
- Export writes the same columns as the import, plus empty templates.
- Opening stock and the chart of accounts (khaemhat-coa layout, natura, tipo,
  flag) are check-only until M6 and M7 add the ledgers to write into.
- PartyService.SaveAsync takes an explicit VIES switch for the import.
- ADR 0031, wiki Import-Export, CHANGELOG and STATUS updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:52:59 +01:00
Alby96andClaude Opus 5.5 3dbbaba86e feat: items and price lists with dated prices, derived lists and demo catalogue (#42)
Items get their own archive and record (mockup 017): codes from the
per-category mask, EAN and NC8 checks, alternative units and bar codes,
suppliers with the usual one, substitutes, notes and history. Only goods
can be stocked; stock itself comes with the warehouse in M6. Costs are
hidden from users without items.cost.read and kept as they were when
those users save. A used item is disabled instead of deleted.

Prices live in one item_prices table, either for a price list or as a
customer's net price, each valid from a date, so documents keep the price
of their day. Derived lists compute a price from their base list with
markup and rounding when they have none of their own. The price grid
(mockup 018) edits every list at one validity date, keeps changes pending
and highlighted until saved, and computes mass updates as a preview.
PriceListService.QuoteAsync gives documents (M5) the price search order
net, list, base, item price with its source.

Parties get the "Articoli e codici" tab: the codes a customer or supplier
uses for our items, found by the item search in that party's documents.

Demo data adds 120 items of a plumbing wholesaler, the PUBB and RIV lists,
last year's prices, suppliers, units, codes and a customer's net prices;
seed --demo [--scale N] loads them from the command line and repeats the
catalogue for performance tests.

ADR 0030 records the decisions; wiki, data model, CHANGELOG and STATUS
are updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 11:06:57 +01:00
Alby96andClaude Opus 5.5 c8241a414e docs: keep 0.x versions until the user calls 1.0.0 (amendment E7)
The user wants the leading zero to keep signalling that Khaemhat is in
development, so M13 closes as v0.13.0 and M14 as v0.14.0+ instead of
v1.0.0 and v1.1.0+ from SPEC §20. The Gitea milestones were renamed to
match.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 10:09:29 +01:00
Alby96andClaude Opus 5.5 3401271483 feat: parties with radar, record, checks, VIES and demo data (#41)
Customers, suppliers, prospects and leads live in one parties archive
with a kind and a subject type (ADR 0029). A customer that also supplies
carries is_also_supplier, so it shows in both radars with one code.

- Three radars (/anagrafiche/clienti, /fornitori, /contatti) with search,
  quick filters and bulk disable/enable; the record has eight tabs
  (main data, addresses, contacts, terms, fiscal and SDI, banks, notes and
  attachments, history) on the MasterDataPage base.
- PartyService saves the whole record in one transaction, checks it with
  the fiscal pack (VAT number, tax code, recipient code, country), treats
  a duplicate VAT number or a consumer without tax code as warnings, fills
  the default recipient code, runs VIES after commit for EU companies, and
  converts prospects/leads (new customer code, old one kept as
  previous_code) and suppliers (become customers that also supply).
- Delete falls back to disable when the party is referenced.
- DemoPartiesSeeder adds 3 salespeople and 21 parties with fictitious but
  formally valid identifiers; SeedAsync now runs demo seeders when asked.
- Test host accepts service overrides so VIES can be stubbed.

Docs: ADR 0029, wiki Anagrafiche and demo data pages, regenerated data
model, CHANGELOG and STATUS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 10:06:33 +01:00
Alby96andClaude Opus 5.5 a9eda510f2 feat: postal codes from GeoNames for the ISTAT municipalities (#45)
The municipalities now come with their postal codes, so the lookup from
postal code works on a new company without loading anything. GeoNames
(CC BY 4.0) lists places rather than municipalities: a postal code goes
to a municipality only when the name and the province abbreviation match
exactly one of them (the name alone within Sardinia, whose abbreviations
changed), which covers 7,750 of 7,894 municipalities; the rest are mostly
renamed or merged ones that users complete by hand.

tools/Khaemhat.PlacesTool rebuilds both lists from the ISTAT sheet and
the GeoNames file, framework only, so the yearly update is repeatable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:16:07 +01:00
Alby96andClaude Opus 5.5 321aae7e81 feat: provinces and municipalities from the ISTAT list in the base data (#45)
New companies now get the 110 provinces and 7,894 municipalities in force
(ISTAT list of 26/02/2026, CC BY 4.0), so the tax code calculation and the
municipality lookups work without loading anything. The list lives in the
Italian pack behind a new IPlaceDirectory feature and is added by the base
seeder like the rest of the base data: missing codes only, never touching
existing rows. The pack data version moves to IT 2026.3 so existing
companies receive the lists at the next start.

Postal codes are left out: the only candidate source (comuni-json) has no
licence for them and stops at 2020 (ADR 0028).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-12 09:07:12 +01:00
Alby96andClaude Opus 5.5 07555de700 feat: automatic codes and automatic filling (#43)
Parties, items and the CRM archives need codes given by the system without
duplicates, and the address and bank fields should fill themselves; this adds
both before the party and item screens that use them.

- CodeMask ({seq:0000}, {anno}, {categoria}) and code_sequences (migration
  015): one sequence per rule, year and category, taken under a lock in the
  transaction that saves the record, skipping codes written by hand
- CodeRuleService: rules in company settings with the masks of SPEC 11.12,
  validation, preview of the next code, manual code allowed or not
- AutoFillService: municipality from postal code and back, personal tax code,
  VIES, bank and BIC from the IBAN, delivery date on working days, options
  that can be switched off (the ECB job honours its option)
- IBankDirectory.ReadIban gives ABI and CAB even without the ABI list; the
  Italian pack now registers the directory
- Company preferences page (mockup 074) at /tabelle/preferenze, in the menu
- aria-checked now renders true/false on switch rows and profile radios
- ADR 0027, wiki, CHANGELOG, STATUS, DATA-MODEL

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 23:33:02 +01:00
Alby96andClaude Opus 5.5 9bcf8c1082 feat: company table screens, profile and fiscal years, seed command (#38, #39, #45)
Gives the company tables of the previous commit their screens, so a company
can be configured from the browser, and makes the base data runnable outside
the web server.

- one generic editor for the 26 coded tables (/tabelle/<slug>), described in
  TableScreens: grid with active/disabled filter, detail with errors and
  warnings, disable instead of delete, CSV export and all-or-nothing import,
  "update from base tables"; index page and menu entries
- company profile in tabs with the fiscal pack checks, fiscal years with
  month lock/unlock, exchange rates with manual rates
- PaymentTermService: installments saved together, percentages must sum to 100
- a new profile proposes the registered company name instead of its code
- seed verb in Khaemhat.Web and scripts/seed.sh --base [--company CODE],
  shipped in the image under /app/scripts
- ADR 0026 (base data only adds missing codes; ISTAT and ABI/CAB lists come
  as separate datasets), wiki, CHANGELOG, STATUS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 23:15:09 +01:00
Alby96andClaude Opus 5.5 34e196424f feat: company tables, profile, fiscal years and base data (#38, #39, #45)
Adds the company tables of SPEC 11.1 behind one generic service so that every
table gets the same rules, history, cache and CSV import/export, plus the
company profile, fiscal years with monthly lock and the base-data seeder.

- 26 coded tables, exchange rates, company profile, fiscal years and periods:
  entities, maps and migrations 010-014
- TableService + TableCatalog: unique codes, per-table rules (VAT codes are
  checked by the fiscal pack), delete or disable when in use, single default,
  CSV export/import all-or-nothing, cache with cross-instance invalidation
- CompanyProfileService (Italian identifiers through the pack),
  FiscalYearService with the date check used by every dated record
- EcbRatesClient and the ECB rates system task; CsvReader
- ISeeder/SeedRunner with the data version in company settings; base tables
  from the pack (IBaseTablesTemplate) and an embedded ISO country list

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 22:33:37 +01:00
Alby96andClaude Opus 5.5 25f8a7ad30 feat: identifier validators and the VIES client (#40)
Parties need their identifiers checked before they reach documents. IBAN, EAN
and e-mail checks are international and live in Core. The Italian VAT number,
fiscal code (with calculator, decoder and omocodia) and SDI recipient code are
Italian, so they sit in the Italian pack behind ITaxIdentifierRules, as the
non-negotiable rule of SPEC 1.10 wins over the class list of SPEC 21 (ADR 0025).
IBankDirectory reads ABI and CAB from an Italian IBAN; its bank list arrives
with the base data.

ViesClient calls the VIES REST service and never reports a number as invalid
when the service could not answer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:53:37 +01:00
Alby96andClaude Opus 5.5 49d2bb166b feat: fiscal pack abstractions and the Italian pack (#37)
The rest of the product needs tax codes, natures, code lists and VAT rules
without knowing the country. IFiscalPack exposes the parts every country has
(tax code catalog, tax engine, calendar) and optional features by type, so a
module can tell a missing feature from a broken one. FiscalPackCatalog finds
the pack by country; only the composition root names the Italian pack, as an
architecture test now checks.

The Italian pack carries the FatturaPA 1.9.1 code lists, VAT natures and base
tax codes with their rules, summary rounding on the total per rate, the stamp
duty rule, VAT deadlines with the August and holiday shifts, withholding kinds,
basic depreciation rules and F24 codes. ADR 0025 records the design.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:48:09 +01:00
Alby96 8079d3da69 Merge docs: chiusura M3 (#120) 2026-11-11 21:33:58 +01:00
Alby96andClaude Opus 5.5 f7c9cf6da8 docs: record M3 as closed (v0.3.0) and M4 as the current milestone
CI / Build and test (SQLite) (pull_request) Successful in 1m29s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Successful in 1m44s
STATUS is the resume point of every session; after the M3 merge and tag
it must point at M4 instead of the pending merge.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 21:02:42 +01:00
Alby96 4ecf15b609 Merge M3 · Framework UI (#119)
Wiki / Publish the wiki (push) Successful in 7s
Release / Image and release (push) Successful in 3m27s
CI / PostgreSQL 16 integration (push) Successful in 1m17s
CI / Build and test (SQLite) (push) Successful in 1m31s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 5s
CI / PostgreSQL 17 integration (push) Successful in 1m17s
2026-11-11 21:00:44 +01:00
Alby96andClaude Opus 5.5 b4a2802bed docs: close M3 with real screenshots, ADR 0024 and the 0.3.0 changelog (#36)
CI / Build and test (SQLite) (pull_request) Successful in 1m36s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 5s
CI / Docker image (pull_request) Successful in 1m13s
The milestone's Definition of Done asks for real screenshots, complete
wiki pages and a changelog for everything delivered. Fifteen screenshots
taken on a fresh instance now sit next to the mockups in the wiki;
Interfaccia, Dashboard, Preferenze, Design UI and Allegati are marked
complete, with the date-field shortcuts and the profile tabs that are not
built yet described as they really are. ADR 0024 records the Kh component
library, record pages and the shared list query, which shipped without
one, and the changelog gains its entries and a 0.3.0 section.

The visual check against the mockups found three layout bugs, fixed here:
the document total label took the timeline's .tl style and was cut, the
radar's .kh-choices class stacked the profile's theme cards in a column
(renamed .kh-radio-set), and on phones the top bar wrapped; it now keeps
icons only and the status bar shows only the live values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 20:26:36 +01:00
Alby96andClaude Opus 5.5 8198e0a754 feat: attachments panel, file previews, print preview and history (#34)
Documents need to show, upload and generate their files from the interface,
and users need to see who changed a record. This adds the attachment list
(upload, preview, download, lock, trash and restore, older versions, ZIP,
generate/regenerate), in-app previews for PDF, images, XML, text, CSV and
XLSX, an A4 print preview with "save as attachment", and an audit history
list read through a permission-checked AuditTrailService.

Files are served by /files endpoints that require a signed-in user and the
company permissions; only PDF and images open inline, with their own CSP
that allows framing by this site only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 19:59:37 +01:00
Alby96andClaude Opus 5.5 f415dc37a8 feat: in-app help, notifications panel and global search (#32)
F1 and "?" now open the wiki page of the screen inside the application
(/aiuto, mockup 011) from a copy of the wiki shipped next to the program,
so help works offline and always matches the installed version. Markdown
is converted in-house and fully encoded; images of the repository are
served from the copy. KHAEMHAT_HELP_URL sets the online wiki behind
"Apri nel wiki"; "Segnala un problema" opens a new issue of that repo.
A test checks that every page and menu entry has an existing wiki page.

The bell opens a notifications panel (mockup 010) with all/unread
filters and mark read. Broadcast notifications are now read per user
through sys_notification_reads / notification_reads instead of one
shared read_at.

The global search asks ISearchProvider implementations through
GlobalSearchService after a short pause; the first provider finds help
pages and sections, # and @ say which modules will fill them.

Escape also closes a side panel when the focus fell out of it.
Decisions in ADR 0023.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 19:39:17 +01:00
Alby96andClaude Opus 5.5 acb7e598d1 feat: widget dashboard and company settings (#30, #31)
The home page becomes the widget dashboard of mockups 004-006. Each user
switches widgets on and off, orders them (drag and drop or buttons that
also work from the keyboard), sizes them on the 12-column grid and picks
the start page; every change is saved at once. Whoever may change the
company settings sets a default layout per role, used by people who
never customized; Reset goes back to it.

Todo, Done and Deadlines collect lines from sources each module
registers, so later milestones fill them without touching the widgets;
a failing source is logged and skipped. M3 provides licence, unread
warnings and scheduled task runs. Notes, Shortcuts and System status
work now; widgets of modules still to come say which milestone brings
their data instead of showing fake numbers.

Role defaults live in the new company_settings table, written through
CompanySettingsService with company.settings.write (ADR 0022).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 19:15:06 +01:00
Alby96andClaude Opus 5.5 75d60ee4c4 feat: grids, radar and document lines (#28)
Lists need one component for the whole app (SPEC §10.6-§10.7): a list
query model that turns search, filters, sort and paging into SQL or runs
over rows in memory, a KhGrid that pages 100,000 rows while scrolling
(or in pages) with sort, selection, keyboard, inline edit, totals, row
menu, saved column layout and CSV/XLSX export, the KhRadar around it
with search, quick filters, a filter builder and saved filters, a radar
window for F4 lookups, and KhLinesGrid for document lines typed from the
keyboard.

Checked in the browser on the component catalog and the sample document.
Fixed on the way: the grid height lost to the flex basis, a new search
kept the old scroll position, Save of a filter needed a second click,
page shortcuts (Ctrl+Canc) reached the record behind a modal window,
Escape did nothing once focus left a dialog, totals did not follow an
inline edit, and amounts exported as 0 instead of 0,00.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:47:38 +01:00
Alby96 d0f9d0e651 Merge attachments and file writers (#34) into the M3 branch
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	src/Khaemhat.Web/Hosting/KhaemhatServices.cs
2026-11-11 18:12:34 +01:00
Alby96andClaude Opus 5.5 d958e7372d feat: Kh component library, record pages and profile security (M3, part 2)
Adds the building blocks every later screen uses, so modules are built from
one set of components instead of ad hoc markup:

- Form components (KhForm, KhTextBox, KhNumberBox, KhDateBox, KhSelect,
  KhCheck, KhSwitch, KhHotlink) with Italian number and date input, inline
  calculation (=10*3), field messages plus a summary that focuses the field,
  and service errors added by field name.
- Display and window components (panels, tiles, badges, chips, money, tabs
  with Alt+1..9, steps, dialog, side drawer and DrawerService).
- KhIconToolbar that keeps one line and moves less used commands into the
  "..." menu, KhDocHead, and the RecordPage/DocumentPage/MasterDataPage bases
  with standard commands, shortcuts and save/cancel/delete flow (#27, #29).
- Development-only component catalog and sample document page.
- Profile: personal data, password change that ends other sessions, TOTP
  enable/disable and recovery codes through ProfileService (#31).

Refs #27 #29 #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:11:16 +01:00
Alby96andClaude Opus 5.5 b341ade9e9 feat: attachments, file store and in-house PDF/CSV/XLSX/ZIP writers (#34)
Documents need attachments and generated files (SPEC 9.4) before the UI of
M3 can show them, and the spec forbids external libraries for PDF and
spreadsheets.

- VolumeFileStore keeps files under <data>/files/<COMPANY>/<yyyy>/<guid>,
  writing a .part file in the same folder with size limit and SHA-256, then
  quota and scanner checks (IFileScanner hook, no-op by default).
- attachments table (migration 007) with kind, version series, lock, trash
  and the uploading user; AttachmentService uploads, adds generated files as
  the next version, lists, opens, zips, locks, trashes, restores and purges
  after 30 days (new system job system.attachments-trash).
- FileGenerationService runs IFileGenerator implementations into the store;
  three generators for the fictitious test document (PDF, CSV, XLSX).
- CsvWriter (Italian Excel defaults, formula-injection guard), XlsxWriter,
  ZipStreamWriter and PdfWriter (standard Type1 fonts, WinAnsi, AFM widths,
  JPEG, Flate, xref) only write asynchronously, so they can stream to an
  HTTP response.
- ADR 0021 records versioning, storage layout, PDF scope and CSV defaults.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 18:06:48 +01:00
Alby96andClaude Opus 5.5 cf6f849cc1 feat: application shell, localized texts and user preferences (M3, part 1)
The pages built so far now live inside the shell of the mockups instead of the
M0 placeholder, every interface text comes from Resources/it-IT, and each user
keeps their own look and start page.

- Shell: top bar, collapsible side menu with fly-out sub-menus, status bar and
  tabs that keep each page alive (page type and route values per tab, so a tab
  never shows another page); at most 12 tabs, least-used clean tab evicted.
- One shortcut table with Alt variants for the combinations browsers keep
  (Ctrl+W, Ctrl+Tab, Ctrl+N); command palette for pages and commands.
- ITexts over embedded JSON; tests forbid literal texts in .razor components
  and check that every key used exists.
- User settings in sys_user_settings / user_settings; theme written on the
  server; profile page with live preview, start page, sessions and shortcuts.
- Home, coming-soon pages for later milestones, localized sign-in and error
  pages; ADR 0020; wiki, CHANGELOG, STATUS and data model updated.

Refs #25 #26 #31 #33

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 16:44:59 +01:00
732 changed files with 139421 additions and 2015 deletions

No files matched your search

+4
View File
@@ -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
+6 -2
View File
@@ -152,8 +152,12 @@ jobs:
curl -fsS --max-time 5 "http://$NAME-app:8080/health"
echo
test "$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "http://$NAME-app:8080/")" = "302"
curl -fsS --max-time 5 "http://$NAME-app:8080/login" | grep -q "Accedi"
curl -fsS -D - -o /dev/null --max-time 5 "http://$NAME-app:8080/login" | grep -qi "content-security-policy"
# 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
+499
View File
@@ -7,6 +7,505 @@ un'immagine `gitea.encke-hake.ts.net/balbosoft/khaemhat:X.Y.Z`.
## [Unreleased]
### Changed
- Decisioni del titolare (ADR 0044): le schermate con sola miniatura si disegnano dalla miniatura e dalla grafica del
gestionale, senza attendere altri PNG (#35); nessun elenco ABI/CAB precaricato, nome della banca e BIC dal conto
dell'azienda o a mano (#45); intermediari reali, accreditamento SdICoop e PEC di prova rimandati (#78). La guida
*Fatturazione elettronica* spiega quale canale usare.
## [0.10.0] - 2026-11-13
M10 - Cespiti, Intrastat, chiusura, bilancio. I beni ammortizzabili hanno il loro registro con il piano civilistico e
fiscale; gli elenchi Intrastat nascono dalle fatture con il file per le Dogane; le dichiarazioni d'intento hanno un
registro e il plafond è controllato quando si conferma la fattura; a fine anno ratei, risconti e una chiusura guidata
in nove passi portano al bilancio CEE con riclassificato, indici ed export per il commercialista.
### Added
- Cespiti (#82, ADR 0041, mockup 048): categorie con i coefficienti del DM 31/12/1988 (*Categorie standard*), conti e
aliquote civilistica e fiscale; registro con piano di ammortamento per anno, movimenti, beni già in uso con i fondi
iniziali; ammortamenti dell'anno registrati per categoria e annullabili finché non definitivi; dismissioni totali e
parziali con plusvalenza o minusvalenza; stampa del registro dei beni ammortizzabili.
- Intrastat (#83, ADR 0042, mockup 049): elenchi di cessioni e acquisti generati da fatture e note confermate (beni
raggruppati, servizi per fattura, rettifiche), righe manuali che sopravvivono alla rigenerazione, controlli di
nomenclatura, massa, partita IVA e codice CPA, periodicità dovuta dalle soglie dei quattro trimestri precedenti,
file `SCAMBI.CEE` e invio registrato con il protocollo.
- Dichiarazioni d'intento (#83, ADR 0042, mockup 061): registro cronologico delle dichiarazioni ricevute ed emesse
con protocollo telematico, plafond, utilizzato ricalcolato dalle vendite in N3.5, avviso dal 90 %, revoca e stampa;
la conferma di una fattura in N3.5 è rifiutata senza dichiarazione valida o oltre il plafond.
- Ratei e risconti (#84): inserimento con calcolo per giorni, proposta dei risconti dalle fatture di acquisto sui
costi tipicamente a cavallo dell'anno, differenze di cambio al 31/12 sulle partite in valuta.
- Chiusura guidata (#85, ADR 0043, mockup 050): controlli, ammortamenti, ratei e risconti, rimanenze al costo medio
ponderato, accantonamenti (svalutazione crediti 0,5 %, TFR), chiusura dei conti economici e patrimoniali, apertura
dell'esercizio successivo con lo storno dei ratei, stampe definitive (libro giornale, registri IVA, registro
cespiti, bilancio); ogni passo si ripete o si annulla fino alle stampe; blocco dell'esercizio.
- Bilancio (#86, ADR 0043, mockup 051): schede *CEE*, *Riclassificato* e *Indici* nella pagina *Bilancio*; schema
ordinario, abbreviato e micro con l'anno precedente e la variazione, dettaglio dei conti di ogni voce, avviso dei
conti senza voce, stato patrimoniale finanziario e conto economico a valore aggiunto, undici indici, stampa PDF ed
export ZIP per il commercialista (cinque CSV).
- Dati di esempio di fine anno (#87): apertura dei conti al 1° gennaio con cespiti, rimanenze, banca e capitale,
quattro cespiti, un risconto, la dichiarazione d'intento in uso e una cessione intracomunitaria; prova di
integrazione che chiude l'anno demo dal passo 1 al blocco su SQLite e PostgreSQL.
- Permessi `assets.asset.read`, `assets.asset.write`, `assets.depreciation.post`, `intrastat.list.read`,
`intrastat.list.write`, `intrastat.list.export`, `sales.intent.read`, `sales.intent.write`, `ledger.year.close`,
`reports.accountant.export`.
- Tabelle `fixed_asset_categories`, `fixed_assets`, `fixed_asset_movements`, `accruals`, `closing_runs`,
`closing_steps`, `closing_prints`, `intrastat_lists`, `intrastat_list_lines`, `intent_declarations` (migrazione
`create_year_end`).
- ADR 0041, 0042 e 0043; pagine wiki *Cespiti*, *Intrastat*, *Dichiarazioni d'intento* e *Chiusura e bilancio* con
le schermate.
### Changed
- Menu *Contabilità* con *Ratei e risconti* e *Chiusura esercizio*; menu *Cespiti* con *Categorie*; *Intrastat* e
*Dichiarazioni d'intento* attivi nel menu *Fatturazione elettronica*.
- La dichiarazione d'intento nei dati fiscali del cliente è lo specchio di quella corrente del registro; quelle
scritte prima della 0.10 entrano nel registro alla prima lettura.
- Il pacchetto fiscale espone le regole di cespiti, chiusura, Intrastat, dichiarazioni d'intento e lo schema del
bilancio CEE.
### Known issues
- Il file `SCAMBI.CEE` non è ancora stato verificato con il software di controllo delle Dogane: controllarlo prima
del primo invio.
- Le differenze di cambio usano il residuo attuale della partita; il TFR della chiusura è una stima.
## [0.9.0] - 2026-11-13
M9 - Fatturazione elettronica. Le fatture emesse diventano file FatturaPA controllati prima dell'invio con i codici
dello SDI e partono dal canale scelto dalle regole di instradamento (PEC, SdICoop o due intermediari); le notifiche
aggiornano da sole file e documenti, gli scarti si correggono e si rigenerano, le fatture dei fornitori arrivano in
una casella da registrare e i file di un periodo si esportano per la conservazione.
### Added
- File FatturaPA (#74, ADR 0039): `FatturaPaWriter` scrive `FPR12`, `FPA12` e `FSM10` v1.2 con nome
`IT<identificativo>_<progressivo>.xml` e progressivo in base 36 mai riusato; il modello del documento viene da
`EInvoiceBuilder` (cedente, cessionario, ritenute, cassa, bollo, sconti, riferimenti, DDT, riepilogo IVA,
pagamenti, allegati).
- Controllo prima dell'invio (#74): `FatturaPaValidator` ripete offline i controlli dello SDI con lo stesso codice
(00305-00473) e le tolleranze delle specifiche 1.9.1, più la struttura contro uno schema incorporato;
*Controlla senza generare* sul cruscotto.
- Notifiche SDI (#75): `SdiReceiptReader` legge RC, NS, MC, NE, DT, AT, SE e MT; ogni notifica è conservata una sola
volta, abbinata al file e applicata al file e al documento nella stessa transazione; import manuale di XML, P7M e
ZIP del portale; pagina *Notifiche SDI* con filtri e download.
- Canali (#76, #77): PEC con SMTP e un client IMAP e un lettore MIME scritti in casa (primo invio a
`sdi01@pec.fatturapa.it`, poi l'indirizzo appreso dallo SDI, cartella di archivio), SdICoop SOAP/MTOM con
certificato client, Intermediario A (chiave API) e Intermediario B (utente e password) dietro lo stesso contratto
`IEInvoiceTransport` (ADR 0040); prova di connessione, pausa, segreti cifrati.
- Instradamento (#77): regole *Sempre*, *Cliente PA*, *Cliente specifico*, *Tipo documento* e *Volume giornaliero*
con canale di riserva (`SdiRouter`); pagina *Canali di trasmissione* (mockup 059).
- Lettura dei canali (#76): attività `einvoice.poll` ogni 15 minuti e *Leggi i canali ora*; un messaggio si conferma
solo quando tutti i suoi file sono salvati. Ricezione push di SdICoop su `POST /sdicoop/{azienda}` con la chiave
di ricezione nell'intestazione `X-Khaemhat-SdiCoop-Key` e il certificato reciproco sul reverse proxy.
- Cruscotto SDI (#74, #75, mockup 058): sei contatori, viste *Emesse*, *Autofatture* e *Da fare*, filtri e
ricerca, documenti da generare, *Genera + invia*, *Invia*, *Correggi*, *Segna come inviata*, download dell'XML,
storico del file con le versioni sostituite, esito della trasmissione; avvisi sulla Home per scarti e file da
inviare (`EInvoiceFeedSource`).
- Copia di cortesia (#74): il PDF del documento con il file FatturaPA allegato (`/AF`).
- Fatture ricevute (#79): casella delle fatture dei fornitori dai canali o caricate (XML, P7M, metadati, ZIP) senza
doppioni, registrazione singola o in blocco con l'import del ciclo passivo, scarto e ripristino, download.
- Conservazione (#79): pacchetto ZIP di un periodo (fino a due anni) con `emesse/`, `ricevute/`, `notifiche/`,
`indice.csv` con SHA-256 e `LEGGIMI.txt`, e l'elenco dei pacchetti preparati.
- Fatturazione elettronica nei dati di esempio con il modulo EINV (#80): canale PEC in pausa, Intermediario A
disattivato, tre regole, i file delle fatture demo con consegne, uno scarto corretto, una mancata consegna e file
in attesa, tre fatture di fornitori da registrare.
- Rimozione dei dati di esempio (#80, ADR 0040): `DemoDataRemover` guidato dallo schema delle migrazioni elimina le
righe `is_demo` e quelle che appartengono loro in una transazione e si ferma se dati dell'utente vi fanno
riferimento; `scripts/seed.sh --remove-demo [--company CODICE]`; il seed stampa il tempo impiegato.
- Permessi `einvoice.document.read`, `einvoice.document.send`, `einvoice.inbox.read`, `einvoice.inbox.import`,
`einvoice.channel.manage`; testi in `Resources/it-IT/EInvoicing.json`.
- Tabelle `e_invoices`, `e_invoice_notifications`, `e_invoice_inbox`, `e_invoice_channels`, `e_invoice_routing`,
`e_invoice_conservation` (migrazione `M20261113_004`).
- ADR 0039 e 0040; pagina wiki *Fatturazione elettronica* completa con le schermate (#81).
### Changed
- Il menu *Fatturazione elettronica* ha le voci *Cruscotto SDI*, *Fatture ricevute*, *Notifiche SDI*,
*Conservazione* e *Canali di trasmissione*, ognuna con il suo permesso; *Dichiarazioni d'intento* resta in M10.
- Una fattura scartata dallo SDI torna modificabile e si rigenera con un nuovo file.
- I seeder dimostrativi marcano come demo anche le righe scritte dai servizi per loro (registrazioni, partite,
pagamenti, mandati, estratti conto).
- Il modello delle fatture ricevute è condiviso con quello delle emesse (`EInvoice*` nelle astrazioni fiscali).
## [0.8.0] - 2026-11-13
M8 - Scadenzario e tesoreria. Le partite aperte di clienti e fornitori si chiudono con incassi e pagamenti che si
contabilizzano da soli; distinte RiBa, SDD e bonifici SEPA con il file per l'home banking, presentazione, accredito
e insoluti; riconciliazione dell'estratto conto con abbinamento automatico; solleciti con interessi di mora e flusso
di cassa.
### Added
- Scadenzario (#69, ADR 0038): partite aperte di clienti e fornitori dalla contabilità con stati, aging in cinque
fasce, filtri, modifica di scadenza, metodo, banca e contestazione, estratto conto della controparte con gli
interessi di mora, export CSV.
- Incassi e pagamenti (#69): su più partite della stessa controparte, totali o parziali, con abbuoni, spese bancarie,
differenze cambio e note di credito; registrazione `INC` o `PAG` nella stessa transazione; annullamento con storno;
la ritenuta d'acconto di una parcella diventa dovuta quando la fattura è saldata. Elenchi *Incassi* e *Pagamenti*.
- Distinte (#70): RiBa nel tracciato CBI (`RibaCbiWriter`), SDD core e B2B in `pain.008.001.08` e bonifici SEPA in
`pain.001.001.09` (`SepaXmlWriter`); candidati con controllo di IBAN, ABI/CAB e mandato; bozza, file, presentazione
su *Effetti all'incasso* o con anticipo *salvo buon fine*, accredito, insoluto con riapertura della partita e
spese come nuova partita del cliente.
- Mandati SDD (#70) con riferimento univoco, schema core o B2B, firma, revoca, sequenza FRST/RCUR.
- Riconciliazione bancaria (#71): import di estratti CSV (colonne riconosciute dall'intestazione), CBI e CAMT.053
senza doppioni (impronta dei movimenti); proposte con confidenza da partite, incassi e pagamenti registrati, F24,
accrediti e insoluti di distinte e regole salvate (`BankMatcher`); conferma singola o di tutte le proposte dal
90%; abbinamento manuale, registrazione su conto con regola, *Ignora*, *Annulla abbinamento*; saldo banca, saldo
contabile e differenza.
- Solleciti (#72): tre livelli modificabili con giorni, modello, canali (e-mail, PEC, lettera PDF), interessi di
mora, avviso all'agente e blocco del cliente; proposta di invio che esclude PA, partite contestate e in distinta;
anteprima PDF, invio con la coda di posta, lettere in un PDF unico, registro degli invii; attività programmata
`finance.dunning` nei giorni feriali alle 7:00 per i livelli automatici.
- Interessi di mora del D.Lgs. 231/2002 nel pacchetto italiano (`LatePaymentRulesIt`): tasso BCE del semestre più
8 punti, 10,15% nel primo semestre 2026 e 10,40% nel secondo.
- Flusso di cassa (#72) a 30-365 giorni per settimana o mese da partite, effetti presentati, ordini non fatturati,
registrazioni ricorrenti e F24, con le fonti selezionabili e il punto più basso.
- Scadenze di incassi e pagamenti e crediti scaduti sulla Home (`TreasuryFeedSource`).
- Menu *Scadenzario* con otto voci; testi in `Resources/it-IT/Treasury.json`; permessi `finance.schedule.*`,
`finance.payment.*`, `finance.bank.reconcile`.
- Tesoreria nei dati di esempio con il modulo FIN (#73): banca, versamento dei soci, incassi e pagamenti, distinta
accreditata con un insoluto, distinta s.b.f. in bozza, mandato, estratto CSV da riconciliare con una regola, primo
sollecito.
- Tabelle `payments`, `payment_lines`, `remittances`, `remittance_lines`, `sdd_mandates`, `bank_statements`,
`bank_statement_lines`, `bank_match_rules`, `dunning_levels`, `dunning_letters`; nuove colonne di
`gl_open_items` e `bank_accounts.creditor_id` (migrazione `M20261113_003`).
- Conti *Perdite su cambi*, *Utili su cambi* e *Interessi di mora attivi* nel piano dei conti PMI standard (240 conti).
- ADR 0038; pagina wiki *Scadenzario* completa con le schermate.
### Changed
- La rettifica della registrazione di un documento mantiene le partite già incassate o pagate.
- Il menu *Fatturazione elettronica* mostra M9 come milestone.
### Fixed
- Le strisce di riepilogo non si schiacciano più nelle pagine più alte della finestra.
## [0.7.0] - 2026-11-13
M7 - Contabilità generale e IVA. Ogni fattura, nota e autofattura si contabilizza da sola nella stessa transazione,
con le righe IVA nel suo registro, le partite aperte e la ritenuta; la prima nota in partita doppia con registrazioni
provvisorie, definitive e storni; registri IVA, liquidazione periodica con F24 e LIPE, ritenute, bollo virtuale,
partitari, mastrini e bilancio di verifica.
### Added
- Piano dei conti a tre livelli (#62, ADR 0036): mastro, conto e sottoconto (`MM.CC.SSS`), natura, tipo, voce CEE,
partitario, rilevanza IVA; modello italiano *PMI standard* di 237 conti nel pacchetto fiscale
(`ItalianLedgerTemplate`), albero con ricerca, scheda e mastrino con saldo progressivo e stampa.
- Causali contabili con righe proposte, registro IVA, apertura delle partite e causale di storno (#62): `FV`, `NCV`,
`FA`, `NCA`, `AFRC`, `CORR`, `INC`, `PAG`, `RIT`, `RITS`, `LIQ`, `F24`, `GIRO`, `SPB`, `STO` e altre.
- Prima nota (#63): registrazioni in partita doppia con cliente o fornitore sui conti con partitario, centro di
costo e righe IVA; bozza, registrata (numero per anno) e definitiva (numero del libro giornale) con *Rendi
definitive*; storno; *Chiudi lo sbilancio*; filtri e paginazione.
- Registrazioni ricorrenti (#63): copia di una registrazione modello mensile, trimestrale, semestrale o annuale fino
a una data, job di sistema `ledger.recurring` ogni giorno alle 5:00 e *Genera ora*.
- Contabilizzazione automatica dei documenti (#64, ADR 0037): fatture, note di debito, parcelle, note di credito,
fatture e note fornitore, autofatture e integrazioni scrivono la registrazione alla conferma (`PostingEngine`,
`LedgerPoster`), la riscrivono con lo stesso numero alla modifica e la tolgono o la stornano all'annullamento;
scissione dei pagamenti, IVA indetraibile sul costo, rivalsa cassa e bollo; *Contabilizza documenti* per i
documenti confermati prima.
- Registri IVA vendite, acquisti, autofatture e corrispettivi (#65) con riepilogo per aliquota, stampa di prova e
definitiva con numerazione delle pagine.
- Liquidazione IVA mensile o trimestrale (#65): IVA a debito e a credito, pro rata, credito e debito riportati,
interessi trimestrali, minimo di versamento, acconto di dicembre (storico, previsionale, effettivo); conferma con la
registrazione `LIQ`, il blocco dei periodi e il versamento F24; riapertura; file della comunicazione LIPE
(`IVP18`) e dati F24. Regole e codici tributo nel pacchetto italiano (`VatSettlementRulesIt`).
- Ritenute d'acconto operate e subite (#66): da versare quando la fattura del professionista è pagata, registrazioni
`RIT` e `RITS`, codice 1040 al 16 del mese dopo; dati della certificazione unica in CSV.
- Bollo virtuale per trimestre (#66) con soglia dei 5.000 euro, codici 2521-2524 e scadenze.
- Prospetto F24 per scadenza (#66) con export dei dati e registrazione del pagamento `F24` sulla banca
dell'azienda.
- Partitari clienti e fornitori con estratto conto e partite aperte, bilancio di verifica per mastri, conti e
sottoconti con centro di costo e risultato del periodo, libro giornale di prova e definitivo in PDF (#67).
- Menu *Contabilità*; testi in `Resources/it-IT/Ledger.json`; permessi `ledger.account.*`, `ledger.entry.*`,
`vat.register.read`, `vat.settlement.*`.
- Contabilità nei dati di esempio (#68): documenti contabilizzati, fattura del professionista pagata, noleggio
mensile della stampante come ricorrente, liquidazioni dei mesi passati confermate e F24 scaduti pagati.
- Tabelle `gl_accounts`, `gl_journal_templates`, `gl_journal_template_lines`, `gl_entries`, `gl_entry_lines`,
`gl_entry_vat`, `gl_open_items`, `gl_recurring_entries`, `vat_registers`, `vat_register_prints`,
`vat_settlements`, `vat_settlement_lines`, `tax_payments`, `withholdings` (migrazione `M20261113_002`).
- ADR 0036 e 0037; pagine wiki *Contabilità*, *IVA* e *Fiscalità italiana* complete con le schermate.
### Changed
- *Bollo virtuale* passa dal menu *Fatturazione elettronica* al menu *Contabilità*.
- Il seed di base e *Aggiorna da tabelle base* aggiungono piano dei conti, causali e registri IVA alle aziende
esistenti.
## [0.6.0] - 2026-11-12
M6 — Acquisti e Magazzino. Il ciclo passivo dall'ordine al fornitore alla fattura protocollata, le fatture
elettroniche ricevute importate in bozza, le autofatture con la loro scadenza e un magazzino che si aggiorna da solo
con i documenti: giacenze per deposito, costo medio, inventario, riordino e valorizzazione.
### Added
- Movimenti di magazzino dai documenti (#59, ADR 0035): alla conferma DDT, fatture immediate e accompagnatorie, note,
DDT e fatture fornitore, note di credito fornitore e movimenti `MM` scrivono i loro movimenti nella stessa
transazione (`inventory_entries`, `inventory_entry_lines`); l'annullamento li toglie. La causale del tipo documento
decide carico, scarico o trasferimento; la fattura di un DDT non muove di nuovo la merce, la nota di credito la
muove all'inverso. Tabella `item_balances` con giacenza per deposito, impegnato (ordini clienti) e ordinato
(ordini fornitore).
- Costo medio ponderato per articolo ricalcolato dalla storia dei movimenti a ogni modifica, anche per documenti con
data passata; ultimo costo e date di ultimo carico e scarico; il prezzo della fattura fornitore corregge il costo
dei carichi che fattura.
- Documenti del ciclo passivo nelle maschere dei documenti (#55, #56, #58): ordini fornitori, ricevimenti merce (DDT
fornitore con il numero e la data del fornitore), fatture e note di credito fornitore con **protocollo** IVA alla
conferma e rifiuto del doppio numero del fornitore nello stesso anno, autofatture e movimenti di magazzino con
causale e depositi. Menu *Acquisti* e *Magazzino*.
- Controllo dei prezzi: sulla fattura fornitore un avviso elenca le righe con un prezzo diverso dall'ordine o dal
ricevimento e la differenza totale.
- Autofatture e integrazioni: il pacchetto italiano (`SelfInvoiceRulesIt`) riconosce dalla fattura del fornitore
l'integrazione dovuta (TD16, TD17, TD18, TD19, TD28) e la scadenza; la fattura lo mostra con **Crea autofattura**,
che prepara la bozza con l'aliquota ordinaria; *Acquisti → Autofatture* elenca le integrazioni da emettere. Tipi
`AF20`-`AF29` nelle tabelle di base.
- Lettura delle fatture elettroniche ricevute (#57): `FatturaPaReader` (FPR12, FPA12, FSM10, lotti, allegati) e
lettore CMS/CAdES dei file `.p7m` con verifica dell'impronta e della firma, scritti in casa.
- Import delle fatture passive (#57): *Acquisti → Importa fatture* legge XML, P7M e ZIP, trova o crea il fornitore,
segnala doppioni, tipi non d'acquisto, totali diversi e firme non verificate, e registra in bozza fatture (TD01,
TD02, TD03, TD05, TD06, TD24-TD27) e note di credito (TD04, TD08) con articoli abbinati per codice del fornitore,
EAN e codice, codice IVA per aliquota e natura, sconti di riga e file allegato. Le regole TD stanno nel pacchetto
fiscale (`IncomingInvoiceRulesIt`).
- Giacenze e disponibilità (#60): indicatori, filtri per deposito, categoria e stato (*Disponibile*, *Da riordinare*,
*Sottoscorta*, *Esaurito*), movimenti di un articolo con saldo progressivo.
- Inventario fisico (#60): apertura per deposito, data e categoria con la giacenza contabile congelata, conteggi
scritti o importati dal file del lettore, rettifiche `INVP` e `INVN` alla data del conteggio; tabelle `stock_takes`
e `stock_take_lines`.
- Proposta di riordino (#60): articoli sotto il punto di riordino o la scorta minima, quantità dal lotto o dalla
soglia con il minimo d'ordine del fornitore, fornitore preferito con prezzo e arrivo previsto, ordini fornitore in
bozza uno per fornitore.
- Valorizzazione a data con costo medio, ultimo costo o costo standard e classi ABC; ricostruzione del magazzino da
interfaccia con avanzamento e come job di sistema `inventory.rebuild` ogni domenica alle 2:15.
- Widget *Sottoscorta* della dashboard con i dati veri.
- Dati di esempio di acquisti e magazzino (#61): esistenze iniziali, ordini ricevuti per intero e in parte, fatture
con una differenza di prezzo e una integrazione AF18 da emettere, un inventario in conteggio.
- ADR 0035; pagine wiki *Acquisti* e *Magazzino* complete con le schermate, guida all'uso aggiornata.
### Changed
- Import *Giacenze iniziali*: non è più solo verifica, scrive e conferma un movimento `APE` per deposito.
- I documenti confermati senza numero interno (DDT fornitore) si presentano come *Senza numero* invece di *Bozza*.
- *Tipi documento*: fattura immediata, fattura e nota di credito fornitore ricevono la causale di magazzino (`SCA`,
`CAR`, `RESF`); la migrazione la assegna anche nelle aziende esistenti dove manca. I tipi `AF20`-`AF29` mancanti si
aggiungono con *Aggiorna da tabelle base* o `scripts/seed.sh --base`.
## [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
+8 -2
View File
@@ -76,8 +76,9 @@ validi.
`docs/mockups/png/` più la galleria completa `000-galleria-mockup.png`; per **tutte le 88** esiste una miniatura
401x241 ritagliata dalla galleria in `docs/mockups/thumbs/`. Per le schermate senza PNG ad alta risoluzione si
lavora da miniatura + `mockup.css` + descrizione in SPEC §10-§12, scegliendo i mattoni della schermata più simile
in alta risoluzione (§10.1 regola 4). I PNG mancanti vanno chiesti all'utente quando servono, senza bloccare il
lavoro (issue con etichetta `Status/In attesa utente`).
in alta risoluzione (§10.1 regola 4). Il titolare ha confermato il 2026-11-16 che altri PNG non esistono
(ADR [0044](docs/adr/0044-schermate-senza-png-banche-e-canali-sdi.md)): la miniatura è la specifica finale e i dettagli
che non mostra si decidono seguendo la grafica del gestionale già costruita, senza chiederli.
**E5 — Avvio dello sviluppo.** La specifica (§0, §23) dice di lavorare in autonomia senza chiedere conferme. Vale,
**dopo** il via esplicito dell'utente: la documentazione e la pianificazione su Gitea sono state preparate il
@@ -88,6 +89,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.
+15
View File
@@ -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
+162 -39
View File
@@ -5,72 +5,195 @@
# Khaemhat
**Gestionale ERP + CRM per piccole e medie imprese italiane**, scritto da zero in C# 14 su .NET 10 con interfaccia
Blazor Server, PostgreSQL (o SQLite per demo e test) e **nessuna libreria esterna**. Si installa **solo con Docker**:
l'unico artefatto distribuito è l'immagine nel registro pacchetti di Gitea.
Blazor Server, PostgreSQL (o SQLite per demo e test) e **nessuna libreria esterna**. Si distribuisce **solo come
immagine Docker** nel registro pacchetti di Gitea.
> **Stato:** sviluppo avviato. M0 (struttura, immagine Docker, CI) consegna la versione 0.0.1 con una pagina
> "in costruzione"; le funzioni arrivano milestone dopo milestone. Vedi [`docs/STATUS.md`](docs/STATUS.md) e la
Questo file è la **guida di installazione per chi sviluppa**: come preparare il computer, compilare, avviare,
provare e pubblicare. Chi **usa** il gestionale parte dalla
[Guida all'uso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Guida-utente) nella wiki; chi lo **installa**
su un server da [Installazione Docker](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Docker)
o [Installazione Unraid](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Unraid).
> **Stato:** sviluppo in corso, versioni 0.x. Ultima milestone chiusa: **M5 — Motore documenti e Vendite** (0.5.0).
> Punto di ripresa in [`docs/STATUS.md`](docs/STATUS.md), piano in
> [Roadmap](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Roadmap).
Il nome viene da Khaemhat (Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto
Amenhotep III: un contabile e un magazziniere dell'antichità. Vedi
[Origine del nome](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Origine-del-nome).
## 1. Prerequisiti
## Cosa farà
| Strumento | Versione | A cosa serve |
|---|---|---|
| **.NET SDK** | 10.0.100 o successiva della stessa *feature band* (vedi [`global.json`](global.json)) | compilare, provare, avviare |
| **Git** | qualunque recente | il repository; su Windows anche **Git Bash**, che esegue gli script `scripts/*.sh` |
| **Docker** | facoltativo | costruire e provare l'immagine; PostgreSQL e Redis per i test sui motori reali |
| **PostgreSQL** | 16 o 17, facoltativo | i test di integrazione sul motore di produzione (`KHAEMHAT_TEST_PG`) |
- Anagrafiche, articoli, listini, tabelle; vendite e acquisti con motore documenti unico; magazzino.
- Contabilità generale, IVA, F24, LIPE, ritenute, bollo, cespiti, Intrastat, chiusura e bilancio CEE.
- Scadenzario, incassi e pagamenti, RiBa/SDD/SEPA, riconciliazione bancaria, solleciti.
- Fatturazione elettronica FatturaPA con canali SDI (PEC integrata, SdICoop, intermediari).
- CRM (lead, pipeline, attività, campagne, ticket), automazioni, API REST e server MCP.
- Più aziende sulla stessa istanza (un database di sistema + un database per azienda), moduli attivabili con
licenza, temi chiaro/scuro, dashboard a widget.
Non servono Node.js, npm, bundler, IDE particolari né pacchetti NuGet oltre a quelli ammessi: un editor qualunque
va bene (Visual Studio, Rider, VS Code con C# Dev Kit). Lingua dei messaggi del compilatore: per avere gli errori in
inglese, `DOTNET_CLI_UI_LANGUAGE=en`.
## Installazione
## 2. Clonare
```bash
docker pull gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione>
git clone https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat.git
```
- Qualunque host Docker: [`deploy/docker-compose.yml`](deploy/docker-compose.yml) (con PostgreSQL) e
[`deploy/.env.example`](deploy/.env.example); per una prova veloce
[`deploy/docker-compose.sqlite.yml`](deploy/docker-compose.sqlite.yml).
- Unraid: template [`deploy/unraid/khaemhat.xml`](deploy/unraid/khaemhat.xml) o
[`deploy/docker-compose.unraid.yml`](deploy/docker-compose.unraid.yml) con [`deploy/.env.example`](deploy/.env.example).
- Guide: [Installazione Unraid](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Unraid) ·
[Installazione Docker](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Docker) ·
[Primi passi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Primi-passi).
In rete locale anche `http://192.168.30.23:3000/BalboSoft/Khaemhat.git` o, con una chiave SSH,
`ssh://git@192.168.30.23:2222/BalboSoft/Khaemhat.git`. Il ramo principale è `main`; si lavora su rami
`feat/<n>-descrizione`, `fix/…`, `docs/…` (vedi [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md)).
## Sviluppo
## 3. Com'è fatto il repository
Serve l'SDK .NET 10 (`global.json`); Docker solo per costruire e provare l'immagine.
| Cartella | Contenuto |
|---|---|
| `src/Khaemhat.Core` | entità, regole, macchine a stati dei documenti, nessuna dipendenza |
| `src/Khaemhat.Data`, `.Data.Sqlite`, `.Data.PostgreSql` | micro-ORM, migrazioni, provider dei due motori |
| `src/Khaemhat.Application` | servizi applicativi: sicurezza, tabelle, anagrafiche, motore documenti, stampe, seed |
| `src/Khaemhat.Infrastructure` | file (PDF, fogli di calcolo, archivi), posta SMTP, cache, licenze, sicurezza: scritti in casa |
| `src/Khaemhat.Fiscal.Abstractions`, `.Fiscal.Italy` | il pacchetto paese: tutto ciò che è italiano |
| `src/Khaemhat.Web` | host Blazor Server, componenti, pagine, risorse dei testi in `Resources/it-IT/*.json` |
| `tests/*` | MSTest, un progetto per strato |
| `tools/*` | strumenti di sviluppo: licenze (`LicenseTool`), comuni e CAP (`PlacesTool`), modello dati (`DataModelTool`) |
| `docker/`, `deploy/` | Dockerfile ed entrypoint; compose, `.env.example`, template Unraid |
| `scripts/` | build, test, avvio, seed, migrazioni, pubblicazione |
| `docs/` | specifica, ADR, architettura, mockup e la wiki (`docs/wiki/`) |
## 4. Compilare
```bash
scripts/build.sh
```
Controlla l'allowlist dei pacchetti (`scripts/check-packages.sh` su `Directory.Packages.props`) e compila
`Khaemhat.sln` in Release con **warning come errori** e gli analyzer di piattaforma. L'equivalente a mano:
```bash
dotnet build Khaemhat.sln -c Release -warnaserror
```
## 5. Avviare in locale
```bash
scripts/run-dev.sh
```
Avvia Khaemhat su <http://localhost:5080> con SQLite in `.data/dev` (ignorata da git) e queste impostazioni di
sviluppo, ognuna sovrascrivibile esportando la variabile prima di lanciare lo script:
| Variabile | Valore di sviluppo |
|---|---|
| `KHAEMHAT_DATA_DIR`, `KHAEMHAT_SYSTEM_DB` | `.data/dev`, `sqlite://…/.data/dev/system.db` |
| `KHAEMHAT_SECRET_KEY` | una chiave fissa **solo per lo sviluppo** |
| `KHAEMHAT_SUPERUSER`, `KHAEMHAT_SUPERUSER_PASSWORD` | `root` e la password iniziale scritta nello script |
| `KHAEMHAT_COMPANY_CODE`, `KHAEMHAT_COMPANY_NAME` | `DEMO`, *Khaemhat Demo S.r.l.* |
| `KHAEMHAT_LICENSE_MODE` | `test`: tutti i moduli attivi con i codici di prova |
| `KHAEMHAT_SEED_DEMO` | `true`: la prima azienda nasce con i dati di esempio (anagrafiche, articoli, un anno di vendite) |
Al primo accesso Khaemhat chiede di cambiare la password e di collegare un'app di autenticazione (il super utente
ha la verifica in due passaggi obbligatoria): conserva la chiave e i codici di recupero. Per ripartire da zero ferma
il server e cancella `.data/dev`.
Altre cose utili in sviluppo:
- **Invio di e-mail**: senza `KHAEMHAT_SMTP_HOST` e `KHAEMHAT_SMTP_FROM` l'invio è spento. Per provarlo serve un
server SMTP di prova sulla tua macchina, ad esempio
`KHAEMHAT_SMTP_HOST=127.0.0.1 KHAEMHAT_SMTP_PORT=2525 KHAEMHAT_SMTP_SECURITY=NONE KHAEMHAT_SMTP_FROM=ufficio@example.com scripts/run-dev.sh`;
l'esito di ogni invio è nel log, sezione *E-mail/PEC*.
- **Dati di base e di esempio** su un database esistente: `scripts/seed.sh --base` oppure `scripts/seed.sh --demo`
(aggiungono solo ciò che manca; meglio con il server fermo).
- **Catalogo dei componenti**: <http://localhost:5080/sviluppo/componenti> mostra i mattoni dell'interfaccia.
- **Tutte le variabili** `KHAEMHAT_*` sono in
[Installazione Docker](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Installazione-Docker) e
[`docs/DEPLOY.md`](docs/DEPLOY.md). Una configurazione non valida ferma l'avvio con l'elenco degli errori.
Prima di ricompilare ferma il server: su Windows l'eseguibile in esecuzione blocca le DLL e la build ritenta la copia
(avviso MSB3026) fino a fallire.
## 6. Provare
```bash
scripts/test.sh
scripts/test.sh --filter "FullyQualifiedName~Documents"
```
Esegue l'allowlist e tutti i test in Release. SQLite è sempre provato; i test che avviano
l'applicazione intera usano un'istanza vera su una porta libera. I test sul **PostgreSQL** reale partono quando
`KHAEMHAT_TEST_PG` indica un ruolo con `CREATEDB` (ogni test crea e cancella il proprio database):
```bash
docker run -d --name khaemhat-pg-test -e POSTGRES_PASSWORD=prova -p 55432:5432 postgres:17
KHAEMHAT_TEST_PG="postgres://postgres:prova@localhost:55432/postgres" scripts/test.sh
```
Senza la variabile quei test risultano *saltati*. In CI (`.gitea/workflows/ci.yml`) i test girano su ogni pull request verso `main`; il job PostgreSQL
(16 e 17) sui tag e all'avvio manuale.
Regole che i test fanno rispettare: nessun pacchetto fuori allowlist, dipendenze tra progetti nel verso giusto,
nessun testo italiano scritto nei componenti (vanno nelle risorse `Resources/it-IT/*.json`), chiavi di testo
esistenti, sezione del modello dati aggiornata.
## 7. Database e migrazioni
```bash
scripts/new-migration.sh company create_sales_documents # nuova migrazione numerata
scripts/gen-datamodel.sh # rigenera la parte generata di docs/DATA-MODEL.md
scripts/gen-datamodel.sh --check # solo verifica (la fa anche un test)
```
Le migrazioni si applicano da sole all'avvio, al database di sistema e a quello di ogni azienda. Il codice non deve
dipendere dal motore: ogni query passa dal micro-ORM e gira identica su SQLite e PostgreSQL.
## 8. Immagine Docker
```bash
scripts/build.sh # allowlist dei pacchetti + build con warning come errori
scripts/test.sh # tutti i test (PostgreSQL con KHAEMHAT_TEST_PG, Redis con KHAEMHAT_TEST_REDIS)
scripts/run-dev.sh # avvio locale su http://localhost:5080 con SQLite in .data/dev
docker build -f docker/Dockerfile -t khaemhat:dev .
docker compose -f deploy/docker-compose.sqlite.yml up # prova veloce con SQLite
```
Processo, rami e Definition of Done in [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
L'immagine pubblicata è `gitea.encke-hake.ts.net/balbosoft/khaemhat:<versione>` (e `:latest`, mai in produzione). La
costruisce `.gitea/workflows/release.yml` quando si spinge un tag `vX.Y.Z` (segreto `REGISTRY_TOKEN` con
`write:package`), che crea anche la release Gitea con le note del [`CHANGELOG.md`](CHANGELOG.md). Se il runner non è
disponibile:
## Documentazione
```bash
GITEA_TOKEN=… scripts/publish-image.sh v0.5.0
```
Non si producono installer, eseguibili o pacchetti `.msi/.exe/.deb`: l'unico artefatto è l'immagine
([ADR 0010](docs/adr/0010-solo-docker-nessun-installer.md)). Le versioni restano **0.x** finché il prodotto è in
sviluppo.
## 9. Documentazione e wiki
La wiki è in `docs/wiki/` e si aggiorna nella stessa unità di lavoro del codice: una funzione senza documentazione
non è finita. Il workflow `wiki.yml` la pubblica nel wiki Gitea a ogni push su `main` che la tocca; a mano:
`scripts/publish-wiki.sh`. Le schermate stanno in `docs/wiki/img/` e si fanno sull'applicazione vera con i dati di
esempio. La stessa wiki è inclusa nell'immagine e si apre con `F1` dentro il gestionale.
| Cosa | Dove |
|---|---|
| Wiki (guida utente e amministratore) | <https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki> (sorgente in [`docs/wiki/`](docs/wiki/)) |
| Specifica normativa | [`docs/SPEC.md`](docs/SPEC.md) |
| Regole operative ed emendamenti | [`CLAUDE.md`](CLAUDE.md) |
| Processo di sviluppo | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) |
| Processo, rami, Definition of Done | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) |
| Architettura, dati, moduli, API, MCP | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md), [`docs/DATA-MODEL.md`](docs/DATA-MODEL.md), [`docs/MODULES.md`](docs/MODULES.md), [`docs/API.md`](docs/API.md), [`docs/MCP.md`](docs/MCP.md) |
| Installazione e sicurezza | [`docs/DEPLOY.md`](docs/DEPLOY.md), [`docs/SECURITY.md`](docs/SECURITY.md) |
| Decisioni architetturali | [`docs/adr/`](docs/adr/) |
| Mockup | [`docs/mockups/`](docs/mockups/README.md) |
| Mockup (specifica visiva) | [`docs/mockups/`](docs/mockups/README.md) |
| Novità | [`CHANGELOG.md`](CHANGELOG.md) |
| Wiki pubblicata | <https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki> |
## Pianificazione
## 10. Regole del codice in breve
Il lavoro è organizzato in [issue](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/issues) raggruppate per
- C# 14 su .NET 10, `Nullable` attivo, warning come errori, `.editorconfig`; JavaScript solo come interop minimo in
`wwwroot/js`.
- **Nessuna libreria esterna**: framework Microsoft, `Npgsql`, `Microsoft.Data.Sqlite` e, nei test, MSTest.
- Codice, commenti e commit in **inglese**; interfaccia in **italiano** dalle risorse.
- Tutto ciò che è fiscale italiano sta in `Khaemhat.Fiscal.Italy`.
- Commit *Conventional Commits* che dicono cosa cambia e perché e citano l'issue (`#n`); pull request verso `main`
con `Closes #n`.
Il lavoro è organizzato in [issue](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/issues) per
[milestone](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/milestones) (M0-M14) e nei
[progetti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/projects) *Khaemhat 1.0 — Sviluppo* e
*Khaemhat 1.1+ — Fase 2*.
[progetti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/projects).
Il nome viene da Khaemhat (Mahu), scriba reale e sovrintendente al doppio granaio dell'Alto e del Basso Egitto sotto
Amenhotep III: vedi [Origine del nome](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/wiki/Origine-del-nome).
+1
View File
@@ -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&amp;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>
+2 -2
View File
@@ -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" \
+2 -1
View File
@@ -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
+3260 -15
View File
File diff suppressed because it is too large. Load diff
+2 -1
View File
@@ -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
+4 -2
View File
@@ -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
+28 -26
View File
@@ -57,10 +57,11 @@ conservati; ogni accesso residuo risponde `module_not_licensed`.
| Purchases | CORE | Documenti | [Acquisti](wiki/Acquisti.md) | M6 |
| Inventory | CORE | Magazzino | [Magazzino](wiki/Magazzino.md) | M6 |
| Ledger | ACCT | Contabilità | [Contabilita](wiki/Contabilita.md) | M7, M10 |
| Vat | ACCT, INTRA | Contabilità | [IVA](wiki/IVA.md), [Intrastat](wiki/Intrastat.md) | M7, M10 |
| Vat | ACCT, INTRA | Contabilità | [IVA](wiki/IVA.md), [Intrastat](wiki/Intrastat.md) | M7, M10 (Intrastat) |
| YearEnd | ACCT (chiusura, bilancio), INTRA (Intrastat), CORE (dichiarazioni d'intento) | Contabilità | [Chiusura-e-bilancio](wiki/Chiusura-e-bilancio.md), [Dichiarazioni-d-intento](wiki/Dichiarazioni-d-intento.md) | M10 |
| Assets | ASSET | Contabilità | [Cespiti](wiki/Cespiti.md) | M10 |
| Finance | FIN | Contabilità (proposta) | [Scadenzario](wiki/Scadenzario.md) | M8 |
| EInvoicing | EINV | SDI/e-invoicing; E-mail/PEC | [Fatturazione-elettronica](wiki/Fatturazione-elettronica.md) | M9 (dichiarazioni d'intento: M10) |
| EInvoicing | EINV | SDI/e-invoicing; E-mail/PEC | [Fatturazione-elettronica](wiki/Fatturazione-elettronica.md) | M9 |
| Crm | CRM | CRM | [CRM](wiki/CRM.md) | M11 |
| Services | SVC | CRM (proposta) | [Servizi](wiki/Servizi.md) | M14 (fase 2) |
| Channels | CHAN | Integrazioni | [Canali-e-commerce](wiki/Canali-e-commerce.md) | M14 (fase 2) |
@@ -161,12 +162,12 @@ conservati; ogni accesso residuo risponde `module_not_licensed`.
|---|---|
| Licenza | `ACCT` |
| Responsabilità | piano dei conti (precaricato e importabile CSV/XLSX/JSON), causali, prima nota con quadratura, contabilizzazione automatica, partitari e mastrini, registrazioni ricorrenti e in valuta, ritenute e casse, ratei/risconti, chiusura e apertura, libri definitivi, bilancio di verifica, CEE e riclassificati, export per il commercialista |
| Entità | `GlAccount`, `JournalTemplate(+Line)`, `GlEntry`, `GlEntryLine`, `GlEntryVat`, `WithholdingTax`, `SocialSecurityCharge`, `AccrualDeferral`, `ClosingRun(+Step)`, `FinancialStatementLine`, `RecurringEntryTemplate` |
| Servizi | `JournalService`, `PostingEngine`, `LedgerPoster`, `PeriodLockService`, `LedgerQueries`, `PartitarioService`, `WithholdingService`, `AccrualDeferralService`, `ClosingProcedure`, `TrialBalanceService`, `FinancialStatementsService`, `RecurringEntriesService`, `ExchangeDifferenceService`, `ChartOfAccountsImportService` |
| Entità | `GlAccount`, `JournalTemplate(+Line)`, `GlEntry`, `GlEntryLine`, `GlEntryVat`, `WithholdingTax`, `SocialSecurityCharge`, `RecurringEntryTemplate`; dalla M10 (cartella `YearEnd`) `AccrualDeferral`, `ClosingRun`, `ClosingStep`, `ClosingPrint` |
| Servizi | `JournalService`, `PostingEngine`, `LedgerPoster`, `PeriodLockService`, `LedgerQueries`, `PartitarioService`, `WithholdingService`, `TrialBalanceService`, `RecurringEntriesService`, `ChartOfAccountsImportService`; dalla M10 `AccrualService` (ratei, risconti, differenze di cambio), `ClosingService` (nove passi, stampe, blocco), `FinancialStatementsService` (CEE, riclassificati, indici, export); nel pacchetto paese `ClosingRulesIt`, `CeeSchemaIt` |
| Maschere e mockup | prima nota (040, 041), piano dei conti e mastrino (042), causali (043), partitario/estratto conto (044), ritenute e F24 (047), chiusura esercizio (050), bilancio CEE (051), esercizi e periodi (052) |
| Permessi | **`ledger.entry.finalize`**; proposte: `ledger.entry.read`, `ledger.entry.write`, `ledger.entry.reopen`, `ledger.account.write`, `ledger.closing.run` |
| Permessi | **`ledger.entry.finalize`**, `ledger.entry.read`, `ledger.entry.write`, `ledger.account.write`; dalla M10 `ledger.year.close` (ratei e risconti, chiusura, blocco) e `reports.accountant.export` |
| Log | Contabilità |
| Wiki | [Contabilita](wiki/Contabilita.md) |
| Wiki | [Contabilita](wiki/Contabilita.md), [Chiusura-e-bilancio](wiki/Chiusura-e-bilancio.md) |
| Milestone | M7 `v0.7.0` (piano dei conti, causali, prima nota, partitari, ritenute, bilancio di verifica); M10 `v0.10.0` (ratei/risconti, chiusura/apertura, libri definitivi, bilancio CEE, export commercialista) |
### 3.8 Vat — IVA, adempimenti e Intrastat
@@ -175,28 +176,29 @@ conservati; ogni accesso residuo risponde `module_not_licensed`.
|---|---|
| Licenza | `ACCT`; parte Intrastat `INTRA` |
| Responsabilità | registri IVA con protocollo e stampe definitive, liquidazione periodica (differita, per cassa, pro-rata, acconto, interessi, minimo), dati F24 e LIPE XML, bollo virtuale (dati per F24), dichiarazioni d'intento, elenchi Intrastat |
| Entità | `VatRegister`, `VatSettlement(+Line)`, `StampDutyEntry`, `IntentDeclaration`, `IntrastatDeclaration(+Line)` |
| Entità | `VatRegister`, `VatSettlement(+Line)`, `StampDutyEntry`; dalla M10 `IntentDeclaration`, `IntrastatList(+Line)` |
| Servizi | `VatRegisterService`, `VatSettlementService`, `StampDutyService`, `IntentDeclarationService`, `IntrastatService`; nel pacchetto paese `VatSettlementRules`, `VatAdvanceCalculator`, `LipeWriter`, `F24Exporter`, `IntrastatExporterIt` |
| Maschere e mockup | registri IVA (045, `VatRegistersPage`), liquidazione IVA/F24/LIPE (046, `VatSettlementPage`), Intrastat (049, `IntrastatPage`) |
| Permessi | **`vat.settlement.confirm`**; proposte: `vat.register.print`, `vat.register.finalize`, `vat.settlement.read`, `vat.intrastat.export` |
| Permessi | **`vat.settlement.confirm`**; proposte: `vat.register.print`, `vat.register.finalize`, `vat.settlement.read`; dalla M10 `intrastat.list.read`, `intrastat.list.write`, `intrastat.list.export`, `sales.intent.read`, `sales.intent.write` |
| Log | Contabilità |
| Wiki | [IVA](wiki/IVA.md), [Intrastat](wiki/Intrastat.md), [Fiscalita-italiana](wiki/Fiscalita-italiana.md) |
| Milestone | M7 `v0.7.0` (registri, liquidazione, F24, LIPE, bollo); M10 `v0.10.0` (Intrastat, dichiarazioni d'intento) |
Nota: SPEC elenca bollo virtuale e dichiarazioni d'intento sia in `ACCT` sia in `EINV` (§8.1), e le loro maschere
(060, 061) sotto *Fatturazione elettronica*. Proposta: i servizi stanno in `Vat`, le maschere sono raggiungibili dal
menu *Fatturazione elettronica* se `EINV` è attivo e da *Contabilità* se è attivo solo `ACCT`. Da fissare con ADR.
(060, 061) sotto *Fatturazione elettronica*. Deciso in M10 (ADR 0042): le dichiarazioni d'intento sono nel modulo base
`CORE` perché riguardano la normale fatturazione, Intrastat in `INTRA`; entrambe le pagine stanno nel menu
*Fatturazione elettronica* come nei mockup, i servizi in `Khaemhat.Application/YearEnd`.
### 3.9 Assets — Cespiti
| Voce | Contenuto |
|---|---|
| Licenza | `ASSET` |
| Responsabilità | categorie con coefficienti ministeriali, registro beni ammortizzabili, piano di ammortamento (primo anno 50%, limiti autovetture, beni < €516,46), dismissioni con plus/minusvalenza (TD26), rivalutazioni, piano simulato, contabilizzazione annuale |
| Responsabilità | categorie con coefficienti ministeriali, registro beni ammortizzabili, piano di ammortamento civilistico e fiscale (primo anno 50%, limiti autovetture, beni < €516,46), dismissioni totali e parziali con plus/minusvalenza, registrazione annuale per categoria annullabile, stampa del registro |
| Entità | `FixedAsset`, `FixedAssetCategory`, `FixedAssetMovement` |
| Servizi | `FixedAssetService`, `DepreciationService`; `DepreciationCalculator` (Core), `FixedAssetRulesIt`, `MinisterialCoefficients` |
| Maschere e mockup | registro cespiti e piano di ammortamento (048, `FixedAssetsPage`) |
| Permessi | proposte: `assets.asset.read`, `assets.asset.write`, `assets.depreciation.post` |
| Servizi | `FixedAssetService`; `DepreciationCalculator` (Core); nel pacchetto paese le regole dei cespiti e `MinisterialCoefficients` (ADR 0041) |
| Maschere e mockup | registro cespiti e piano di ammortamento (048, `AssetsPage`), ammortamenti (`DepreciationPage`), categorie (`CategoriesPage`) |
| Permessi | `assets.asset.read`, `assets.asset.write`, `assets.depreciation.post` |
| Log | Contabilità |
| Wiki | [Cespiti](wiki/Cespiti.md) |
| Milestone | M10 `v0.10.0` |
@@ -206,28 +208,28 @@ menu *Fatturazione elettronica* se `EINV` è attivo e da *Contabilità* se è at
| Voce | Contenuto |
|---|---|
| Licenza | `FIN` |
| Responsabilità | partite aperte e aging, incassi e pagamenti con abbuoni e differenze cambio, insoluti, distinte RiBa (CBI), SDD (`pain.008`), bonifici SEPA (`pain.001`), riconciliazione bancaria (CSV/CBI/CAMT.053), solleciti a livelli con interessi di mora, flusso di cassa 90 giorni |
| Entità | `OpenItem`, `Payment(+Line)`, `Remittance(+Line)`, `SddMandate`, `BankStatement(+Line)`, `BankMatchRule`, `DunningRun(+Line)`, `DunningLevel` |
| Servizi | `OpenItemService`, `PaymentService`, `RemittanceService`, `SddMandateService`, `BankStatementImportService`, `BankReconciliationService`, `DunningService`, `CashFlowForecastService`, `AgingReportService`, `InstallmentPoster` |
| Maschere e mockup | partite e aging (053, `OpenItemsPage`), registra incasso (054, `PaymentDialog`), distinte (055, `RemittancePage`), solleciti (056, `DunningPage`), riconciliazione (057, `BankReconciliationPage`) |
| Permessi | proposte: `finance.open_item.read`, `finance.payment.write`, `finance.remittance.write`, `finance.dunning.run`, `finance.reconciliation.write` |
| Responsabilità | partite aperte (le `gl_open_items` della contabilità) e aging, incassi e pagamenti con abbuoni, spese e differenze cambio, insoluti, distinte RiBa (CBI), SDD (`pain.008.001.08`), bonifici SEPA (`pain.001.001.09`), mandati, riconciliazione bancaria (CSV/CBI/CAMT.053), solleciti a livelli con interessi di mora, flusso di cassa 30-365 giorni, scadenze sulla Home |
| Entità | `OpenItem` (Ledger), `Payment(+Line)`, `Remittance(+Line)`, `SddMandate`, `BankStatement(+Line)`, `BankMatchRule`, `DunningLevel`, `DunningLetter` |
| Servizi | `ScheduleService`, `PaymentService`, `RemittanceService`, `MandateService`, `BankReconciliationService`, `DunningService` (+ job `finance.dunning`), `CashFlowService`, `TreasuryFeedSource`, `DemoTreasurySeeder`; nel core `AgingCalculator`, `PaymentAllocator`, `BankMatcher`, `SepaXmlWriter`, `CsvStatementReader`, `Camt053Reader`; nel pacchetto italiano `RibaCbiWriter`, `CbiStatementReader`, `LatePaymentRulesIt` (ADR 0038) |
| Maschere e mockup | partite e aging (053, `SchedulePage`), registra incasso (054, `PaymentDialog`), incassi e pagamenti (`PaymentsPage`), distinte (055, `RemittancesPage`), mandati (`MandatesPage`), solleciti (056, `DunningPage`), riconciliazione (057, `ReconciliationPage`), flusso di cassa (`CashFlowPage`) |
| Permessi | `finance.schedule.read`, `finance.schedule.write`, `finance.payment.read`, `finance.payment.write`, `finance.bank.reconcile` |
| Log | Contabilità (proposta: SPEC §9.5 non ha una sezione "Tesoreria"); invio solleciti in E-mail/PEC |
| Wiki | [Scadenzario](wiki/Scadenzario.md) |
| Milestone | M8 `v0.8.0` |
| Milestone | M8 `v0.8.0` (consegnata) |
### 3.11 EInvoicing — Fatturazione elettronica
| Voce | Contenuto |
|---|---|
| Licenza | `EINV` |
| Responsabilità | generazione e validazione XML FatturaPA (`FPR12`/`FPA12`/`FSM10`), lettura passive e P7M, notifiche SDI, quattro canali (PEC integrata, SdICoop, Intermediario A, Intermediario B) con instradamento, cruscotto, inbox, export per la conservazione, autofatture da inviare |
| Entità | `EInvoice`, `SdiNotification`, `EInvoiceInboxFile`, `SdiChannel`, `SdiRoutingRule`, `ConservationPackage` |
| Servizi | `EInvoiceService`, `EInvoiceExportService`, `SdiChannelService`, `SdiInboxService`, `SdiNotificationImportService`, `PurchaseInvoiceImportService`, `ConservationExportService`; nel pacchetto paese `FatturaPaWriter`, `FatturaPaValidator`, `FatturaPaReader`, `SdiRouter`, i quattro `ISdiTransport` |
| Maschere e mockup | cruscotto SDI (058, `EInvoiceDashboard`), canali SDI (059, `SdiChannelsPage`), bollo virtuale (060, `StampDutyPage`), dichiarazioni d'intento e plafond (061, `IntentDeclarationsPage`) |
| Permessi | proposte: `einvoicing.invoice.generate`, `einvoicing.invoice.send`, `einvoicing.channel.write`, `einvoicing.inbox.import` |
| Responsabilità | file FatturaPA (`FPR12`/`FPA12`/`FSM10`) con controlli offline e codici dello SDI, quattro canali (PEC, SdICoop, Intermediario A, Intermediario B) con instradamento e canale di riserva, lettura dei canali programmata e push SdICoop, notifiche, correzione degli scarti, copia di cortesia PDF con l'XML allegato, fatture ricevute da registrare, pacchetti per la conservazione, autofatture da inviare, rimozione dei dati di esempio |
| Entità | `EInvoice` (`e_invoices`), `EInvoiceNotification` (`e_invoice_notifications`), `EInvoiceInboxFile` (`e_invoice_inbox`), `EInvoiceChannelSetting` (`e_invoice_channels`), `SdiRoutingRule` (`e_invoice_routing`), `ConservationExport` (`e_invoice_conservation`) |
| Servizi | `EInvoiceService`, `EInvoiceChannelService`, `EInvoicePollingService` (+ job `einvoice.poll`), `SdiPushService` (endpoint `POST /sdicoop/{azienda}`), `SdiInboxService`, `ConservationExportService`, `EInvoiceFeedSource`, `DemoEInvoiceSeeder`, `DemoDataRemover`; nel core `SdiRouter`, `EInvoiceStates`; nel pacchetto italiano `FatturaPaWriter`, `FatturaPaValidator`, `FatturaPaReader`, `SdiReceiptReader`, `PecSdiTransport`, `SdiCoopTransport`, `IntermediaryATransport`, `IntermediaryBTransport`, `SdiCoopPushReader` (ADR 0039, 0040) |
| Maschere e mockup | cruscotto SDI (058, `EInvoiceDashboardPage`), canali e instradamento (059, `EInvoiceChannelsPage`), fatture ricevute (`EInvoiceInboxPage`), notifiche (`EInvoiceNotificationsPage`), conservazione (`ConservationPage`); dichiarazioni d'intento e plafond (061) in M10; bollo virtuale (060) in *IVA* dalla 0.7 |
| Permessi | `einvoice.document.read`, `einvoice.document.send`, `einvoice.inbox.read`, `einvoice.inbox.import`, `einvoice.channel.manage` |
| Log | SDI/e-invoicing; invio e lettura PEC in E-mail/PEC; intermediari in Integrazioni |
| Wiki | [Fatturazione-elettronica](wiki/Fatturazione-elettronica.md) |
| Milestone | M9 `v0.9.0` (con seed demo completo); dichiarazioni d'intento in M10 |
| Milestone | M9 `v0.9.0` (consegnata); dichiarazioni d'intento in M10 |
### 3.12 Crm — CRM
+97 -16
View File
@@ -2,17 +2,34 @@
> Punto di ripresa per ogni sessione. Aggiornare a fine sessione.
**Ultimo aggiornamento:** 2026-11-11
**Milestone corrente:** M2 — Sistema e sicurezza, completata nel ramo `feat/15-sistema-e-sicurezza` (PR verso `main`);
il tag `v0.2.0` si crea dopo il merge.
**Prossimo passo:** M3 — Interfaccia (issue #25-#36): layout, navigazione e componenti sopra le pagine di accesso di M2.
Da recuperare: misure di riferimento su PostgreSQL in `docs/DATA-MODEL.md` §6.1; pagina di cambio password con
indicatore di robustezza (mockup 003) in M3.
**Ultimo aggiornamento:** 2026-11-16
**Milestone corrente:** M11 — CRM e servizi (issue #88-#91), da iniziare. M10 chiusa: PR in `main`, tag `v0.10.0`,
immagine e release.
**Prossimo passo:** M11 dall'issue #88. Decisioni del titolare del 2026-11-16 (ADR 0044): le schermate senza PNG si
disegnano dalla miniatura e dalla grafica del gestionale (#35 chiusa); niente elenco banche ABI/CAB precaricato (#45
chiusa); intermediari, SdICoop e PEC reale rimandati (#78 nel backlog).
Da recuperare: misure di riferimento su PostgreSQL in `docs/DATA-MODEL.md` §6.1; indicatore di robustezza della
password (mockup 003); schede *Layout salvati* e *Notifiche* del profilo; rinomina e filtro predefinito nei radar;
logo PNG nel PDF (oggi solo JPEG, ADR 0034); coda della posta persistente e modelli e-mail per azienda (M12).
Da M6: schermata dell'import fatture con file caricati (serve un caricamento via CDP); nei movimenti di un articolo il
numero del fornitore al posto di *DDT fornitore* senza numero; FIFO e LIFO a lotti (dopo la 1.0).
Da M7: schermata del bollo virtuale (la demo non ha fatture esenti sopra 77,47 euro); import di causali e voci di
bilancio dal file `khaemhat-coa.json`; libro inventari (M13); IVA per cassa (fase 2).
Da M8: tracciati CBI e SEPA da provare con un home banking reale; tabella semestrale dei tassi di mora da aggiornare a
gennaio e luglio (ADR 0038); blocco per fido su ordini e documenti; report di tesoreria in *Report* (M12).
Da M9: schema XSD ufficiale FatturaPA al posto di quello scritto in casa (serve il permesso di scaricarlo);
intermediari reali e accreditamento SdICoop (#78 nel backlog, ADR 0040 e 0044); conformità PDF/A-3 dichiarata della copia di cortesia;
pulsanti *Carica* e *Rimuovi dati di esempio* nell'interfaccia (M12).
Da M10: file `SCAMBI.CEE` da verificare con il software di controllo delle Dogane prima del primo invio (ADR 0042);
differenze di cambio calcolate sul residuo attuale della partita (ADR 0043); TFR stimato (retribuzioni / 13,5);
annullare il passo 2 della chiusura toglie tutti gli ammortamenti dell'anno (ADR 0041); il gruppo dichiarazione
d'intento nei dati fiscali del cliente è ora uno specchio del registro (si potrebbe renderlo di sola lettura con un
collegamento al registro); rivalutazioni senza regole guidate.
## Fatto
- Specifica normativa in `docs/SPEC.md`; `CLAUDE.md` con emendamenti E1-E6.
- ADR 0001-0019.
- Specifica normativa in `docs/SPEC.md`; `CLAUDE.md` con emendamenti E1-E7.
- ADR 0001-0043.
- 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`,
@@ -30,7 +47,7 @@ indicatore di robustezza (mockup 003) in M3.
(AES-256-GCM, formato `khs1`), `tools/Khaemhat.DataModelTool` e gli script `new-migration.sh` e
`gen-datamodel.sh`; ADR 0018. Test: 106 test dello strato dati verdi su SQLite in locale e su PostgreSQL 16 e 17 in CI
(in locale Docker non è disponibile).
- **M2 (`v0.2.0`, PR da aprire):** avvio da variabili con elenco degli errori, migrazioni all'avvio, super utente e
- **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
@@ -38,6 +55,72 @@ indicatore di robustezza (mockup 003) in M3.
job di sistema; storico dei record; aziende con stati e contesto (`X-Company`); header di sicurezza; ADR 0019.
Test: 180 verdi in locale, più 21 di PostgreSQL saltati senza Docker (girano in CI). La chiave privata delle licenze è fuori dal
repository (`Khaemhat-private/khaemhat-license.khkey`) e va conservata dal titolare.
- **M3 (chiusa, `v0.3.0`, PR #119):** shell con barra superiore, menu comprimibile con sottomenu a comparsa,
schede tenute in vita, barra di stato, scorciatoie con varianti `Alt`; testi in `Resources/it-IT/*.json` con test
anti-testo-letterale; preferenze utente e *Il mio profilo* (aspetto, pagina iniziale, dati personali, password e
2FA, sessioni, scorciatoie); libreria `Kh*` con campi all'italiana, toolbar a icone, intestazione documento e basi
`RecordPage`/`DocumentPage`/`MasterDataPage`; liste con `ListQuery`/`ListFields`, `KhGrid` virtualizzata, `KhRadar`
e `KhLinesGrid`; dashboard a widget con layout per utente e per ruolo e `company_settings`; ricerca globale a
fornitori, aiuto in app dalla copia della wiki, pannello notifiche; allegati con anteprime, *Genera file*, ZIP,
cestino e storico; anteprima di stampa A4; catalogo dei componenti e documento di prova per gli sviluppatori;
primi screenshot reali in `docs/wiki/img/`; ADR 0020-0024. Test: 368 verdi in locale, 21 di PostgreSQL saltati;
immagine costruita in locale e avviata da zero con SQLite.
- **M4 (chiusa, `v0.4.0`, PR #121):** pacchetto fiscale `IT 2026.3` (codici IVA, nature, code list FatturaPA, motore IVA,
calendario, ritenute, F24; ADR 0025); validatori e `ViesClient`; 26 tabelle azienda con un'unica maschera, profilo
azienda, esercizi e cambi BCE (ADR 0026); dati di base con province e comuni ISTAT e CAP GeoNames (ADR 0028) e
`scripts/seed.sh --base|--demo`; codici automatici e compilazione automatica (ADR 0027); clienti, fornitori e
contatti con radar, scheda, controlli e VIES (ADR 0029); articoli e listini con prezzi a validità, listini derivati e
aggiornamento massivo (ADR 0030); import/export guidato CSV/XLSX/JSON con tracciato del piano dei conti (ADR 0031);
21 anagrafiche e 120 articoli di esempio; screenshot reali nella wiki. Test: 631 verdi in locale, 21 di PostgreSQL
saltati; immagine costruita in locale e avviata da zero con SQLite e dati di esempio.
- **M5 (chiusa, `v0.5.0`, PR #124):** motore documenti (#47, ADR 0032): generi e definizioni dei tipi documento, sei famiglie
di tabelle con le righe e `document_links`, stati con azioni ammesse, numerazione atomica alla conferma (provata in
concorrenza su SQLite e su PostgreSQL 18 in locale), copia e trasformazione con evasione riga per riga; totali,
castelletto IVA, bollo, ritenute, cassa e scadenze (#48, ADR 0033); radar e maschera dei documenti di vendita con
*Crea …* (#49, #50); fatturazione differita guidata (#51); anteprima di stampa e PDF dallo stesso modello, invio per
e-mail con SMTP e coda scritti in casa (#52, ADR 0034); log *Documenti*; profilo e un anno di vendite di esempio;
wiki con la *Guida all'uso* e le schermate reali, README come guida per sviluppatori (#53). Test: 660 verdi in
locale, 23 di PostgreSQL saltati (girano in CI).
- **M6 (chiusa, `v0.6.0`, PR #125):** movimenti di magazzino dai documenti nella
stessa transazione, costo medio ponderato ricalcolato dalla storia, impegnato e ordinato, correzione del costo dalla
fattura fornitore (#59, ADR 0035); ordini fornitori, ricevimenti, fatture e note di credito fornitore con protocollo,
doppioni rifiutati, controllo dei prezzi, autofatture TD16-TD29 consigliate dal pacchetto italiano con scadenza
(#55, #56, #58); lettura FatturaPA e `.p7m` (CMS scritto in casa) e import delle fatture passive in bozza (#57);
giacenze, movimenti di un articolo, inventario fisico, proposta di riordino, valorizzazione con classi ABC,
ricostruzione anche come job settimanale, widget *Sottoscorta* (#60); giacenze iniziali da file con movimento `APE`;
acquisti e magazzino nei dati di esempio, wiki *Acquisti* e *Magazzino* con le schermate, guida all'uso (#61).
Test: 709 verdi in locale, 23 di PostgreSQL saltati (girano in CI).
- **M7 (chiusa, `v0.7.0`):** piano dei conti a tre livelli con il modello *PMI standard* di 237 conti, causali con righe
proposte (#62, ADR 0036); prima nota con bozze, registrazioni, definitive con numero del libro giornale e storni,
ricorrenti con job giornaliero (#63); contabilizzazione automatica di fatture, note, parcelle e autofatture nella
transazione del documento con righe IVA, partite e ritenute (#64, ADR 0037); registri IVA con stampa definitiva,
liquidazione mensile o trimestrale con pro rata, interessi, minimo, acconto, F24 e LIPE (#65); ritenute operate e
subite, dati CU, bollo virtuale con soglie, prospetto F24 con pagamento (#66); partitari, mastrini, bilancio di
verifica, libro giornale (#67); contabilità nei dati di esempio con la liquidazione verificata a mano in un test,
wiki *Contabilità*, *IVA* e *Fiscalità italiana* con le schermate (#68). Test: 754 verdi in locale, 23 di PostgreSQL saltati (girano in CI).
- **M8 (chiusa, `v0.8.0`):** scadenzario sulle partite della contabilità con aging, incassi e pagamenti multipli e
parziali con abbuoni, spese, cambi e storno (#69, ADR 0038); distinte RiBa CBI, SDD `pain.008` e bonifici
`pain.001` con presentazione, anticipo s.b.f., accredito e insoluti, mandati SDD (#70); riconciliazione bancaria
CSV/CBI/CAMT.053 senza doppioni con confidenza e regole (#71); solleciti a tre livelli con interessi di mora e job
automatico, flusso di cassa, scadenze sulla Home (#72); tesoreria nei dati di esempio con FIN, wiki *Scadenzario*
con le schermate (#73). Test: 823 verdi in locale, anche quelli di PostgreSQL (18) con un container locale.
- **M9 (chiusa, `v0.9.0`):** file FatturaPA `FPR12`/`FPA12`/`FSM10` con controllo offline dei codici SDI e schema
scritto in casa (#74, ADR 0039); notifiche RC/NS/MC/NE/DT/AT/SE/MT senza doppioni che muovono file e documento,
correzione degli scarti, copia di cortesia PDF con l'XML allegato (#75); canali PEC (IMAP e MIME in casa),
SdICoop SOAP/MTOM e due intermediari generici con instradamento e riserva, job `einvoice.poll` e push SdICoop su
`/sdicoop/{azienda}` (#76, #77, ADR 0040); fatture ricevute da registrare e pacchetti di conservazione (#79);
fatturazione nei dati di esempio e rimozione dei dati di esempio guidata dallo schema (#80); wiki *Fatturazione
elettronica* con le schermate (#81). #78 (scelta degli intermediari, accreditamento SdICoop) resta aperta.
Test: 874 verdi in locale, anche quelli di PostgreSQL (18) con un container locale.
- **M10 (chiusa, `v0.10.0`):** cespiti con categorie ministeriali, piano civilistico e fiscale, ammortamenti per
categoria annullabili, dismissioni e registro (#82, ADR 0041); elenchi Intrastat dai documenti con periodicità dalle
soglie e file `SCAMBI.CEE`, registro delle dichiarazioni d'intento con controllo del plafond alla conferma (#83,
ADR 0042); ratei e risconti per giorni e differenze di cambio (#84); chiusura guidata in nove passi ripetibili e
annullabili con riapertura, stampe definitive e blocco (#85); bilancio CEE ordinario, abbreviato e micro con
riclassificato, indici, stampa ed export per il commercialista (#86, ADR 0043); dati di esempio di fine anno e
chiusura completa dell'anno demo come prova di accettazione (#87); wiki *Cespiti*, *Intrastat*, *Dichiarazioni
d'intento*, *Chiusura e bilancio* con le schermate. Test: 907 verdi in locale, anche quelli di PostgreSQL con un
container locale.
- 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,
@@ -56,8 +139,6 @@ Rilevato il 2026-11-11 sulla macchina di sviluppo (Windows 11, Git Bash per gli
## In attesa del titolare
- PNG ad alta risoluzione delle 66 schermate disponibili solo come miniatura (issue #35, non bloccante).
- Scelta degli intermediari SDI e accreditamento SdICoop (issue #78, non bloccante).
- Prova del template su Unraid (issue #106).
- Un contatto privato per la segnalazione di vulnerabilità (vedi `SECURITY.md`).
@@ -84,12 +165,12 @@ Emersi durante la stesura della documentazione. Si decidono con un ADR quando si
### Contabilità, IVA, e-fattura, CRM (dalla stesura delle pagine funzionali)
12. Scadenza IVA di settembre: mockup 046 la mette al 16/10/2026, mockup 047 nell'F24 del 16/11/2026 (corretto: 16/10 per i mensili).
12. Scadenza IVA di settembre: mockup 046 la mette al 16/10/2026, mockup 047 nell'F24 del 16/11/2026 (corretto: 16/10 per i mensili). **Deciso in M7: ADR 0037, il 16 del mese successivo.**
13. Bollo sulle cessioni intracomunitarie: il mockup 060 lo addebita su N3.2, ma cessioni intra-UE ed esportazioni ne sono esenti; la regola del bollo va legata al codice IVA con esclusioni.
14. Funzioni di fase 2 nelle schermate di M7: ventilazione dei corrispettivi (046) e IVA per cassa completa sono in M14 per §20.
15. Moduli ambigui: bollo e dichiarazioni d'intento sotto ACCT e EINV (§8.1); export commercialista sotto ACCT e REPORT; Intrastat e LIPE nel menu e-fattura nei mockup; §10.2 senza voce Intrastat.
16. Stato "Provvisorio" dell'esercizio nel mockup 052, non previsto da SPEC (aperto / in chiusura / chiuso).
17. Codici conto incoerenti tra mockup (fornitori 05.02.001 in 040/043, 02.03.001 in 042).
14. Funzioni di fase 2 nelle schermate di M7: ventilazione dei corrispettivi (046) e IVA per cassa completa sono in M14 per §20. **Confermato in M7: non implementate.**
15. Moduli ambigui: bollo e dichiarazioni d'intento sotto ACCT e EINV (§8.1); export commercialista sotto ACCT e REPORT; Intrastat e LIPE nel menu e-fattura nei mockup; §10.2 senza voce Intrastat. **Deciso in M10: dichiarazioni d'intento in CORE, Intrastat in INTRA nel menu e-fattura, export commercialista in ACCT con il permesso `reports.accountant.export` (ADR 0042, 0043).**
16. Stato "Provvisorio" dell'esercizio nel mockup 052, non previsto da SPEC (aperto / in chiusura / chiuso). **Deciso in M10: restano i tre stati di SPEC; "in chiusura" dal passo 6, "chiuso" con il blocco (ADR 0043).**
17. Codici conto incoerenti tra mockup (fornitori 05.02.001 in 040/043, 02.03.001 in 042). **Deciso in M7: ADR 0036, piano PMI standard (clienti 05.01.001, fornitori 14.01.001).**
18. Regola R-005 del mockup 072 "riapre in bozza" una fattura scartata: contrasta con l'immutabilità della fattura emessa.
19. Codice campagne `CMP-…` (068) non presente nelle maschere di §11.12.
20. Codice di scarto 00327 citato in §18 senza descrizione.
@@ -28,6 +28,7 @@
- Per le schermate con sola miniatura valgono SPEC §10.1 regola 4 (comporre con i mattoni della più simile) e le
descrizioni testuali; se un dettaglio non è ricostruibile si chiede il PNG all'utente con un'issue
`Status/In attesa utente`, senza fermare il resto.
`Status/In attesa utente`, senza fermare il resto. *Aggiornato dall'ADR 0044:* altri PNG non esistono, i dettagli
mancanti si decidono seguendo la grafica del gestionale.
- Quando arrivano gli screenshot reali dell'applicazione sostituiscono progressivamente i mockup nella wiki
(`docs/wiki/img/`), come da SPEC §17.
+53
View File
@@ -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.
+73
View File
@@ -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`.
+47
View File
@@ -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à.
+55
View File
@@ -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,55 @@
# 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.
*Aggiornato dall'ADR 0044:* il titolare rinuncia all'elenco precaricato delle banche; nome e BIC si scrivono a mano
o vengono da un conto dell'azienda presso la stessa banca.
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,54 @@
# 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).
Il titolare ha rinunciato ai dati precaricati (ADR 0044).
## 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.
+65
View File
@@ -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`).
+67
View File
@@ -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*.
+69
View File
@@ -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.
+65
View File
@@ -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).
@@ -0,0 +1,80 @@
# ADR 0035 - Magazzino e ciclo passivo
- **Stato:** accettata
- **Data:** 2026-11-12
- **Modifica:** SPEC §11.5, §11.6, §12.12; milestone M6, issue #55-#61
## Contesto
SPEC §11.6 chiede giacenze per deposito con impegnato, ordinato e disponibile aggiornati nella stessa transazione del
documento, costo medio ponderato (FIFO e LIFO predisposti), inventario fisico, proposta di riordino, valorizzazione a
data e una ricostruzione; §11.5 il ciclo passivo con protocollo IVA, import delle fatture elettroniche ricevute,
controllo dei prezzi rispetto all'ordine e autofatture TD16-TD29. Il motore documenti di M5 (ADR 0032) sa già quali
generi hanno effetto *Inventory*; restavano aperti: come si registra un movimento, come si calcola il costo quando i
documenti arrivano fuori ordine di data, come non contare due volte la merce di una fattura nata da un DDT, come
portare le novità nelle aziende create prima, dove stanno le regole italiane di autofatture e import.
## Decisione
1. **La causale decide, il genere filtra.** Ogni tipo documento ha una causale di magazzino (`inventory_reasons`:
carico, scarico, nessun effetto; flag *trasferimento* e *muove il valore*). `StockEffectMatrix` (in `Khaemhat.Core`)
dice quali generi la applicano (DDT, fatture immediate e accompagnatorie, note, DDT e fatture fornitore, note di
credito fornitore, movimenti `MM`) e quali hanno costi d'acquisto che muovono la media (DDT fornitore, fattura
fornitore, movimento con prezzo). Ordini clienti e fornitori non muovono la giacenza: il loro **residuo** è
l'impegnato e l'ordinato. Le causali di base sono 12 (`CAR`, `SCA`, `RESC`, `RESF`, `TRA`, `INVP`, `INVN`, `CVU`,
`CVR`, `OMA`, `AUTO`, `APE`).
2. **Movimenti come righe derivate.** `InventoryPoster` gira dentro la transazione del motore documenti: alla conferma
scrive un `inventory_entries` per documento con una riga per articolo e deposito (`inventory_entry_lines`, quantità
nell'unità base, con segno); all'annullamento o alla modifica di un documento in vigore lo riscrive da capo. Le righe
che vengono da un documento che ha già mosso la merce nello stesso verso (la fattura di un DDT) sono saltate;
la nota di credito di una fattura la muove all'inverso.
3. **Storia ricalcolata, non saldi incrementali.** Dopo ogni modifica la storia degli articoli toccati viene
ripercorsa per data e ordine di registrazione (`StockCostCalculator`): giacenza per deposito, costo medio ponderato
dell'articolo su tutti i depositi, ultimo costo, date di ultimo carico e scarico, e i risultati vanno in
`item_balances` e nella scheda articolo. Così un documento con una data passata dà lo stesso risultato di uno
inserito in ordine. Ogni carico con valore sposta la media; gli altri movimenti escono alla media del momento; con
giacenza a zero o negativa il carico successivo fissa la media. La giacenza negativa non blocca la conferma (non
si fermano le consegne), si vede nelle giacenze e nella dashboard.
4. **La fattura corregge il costo del carico.** Il prezzo di una fattura fornitore confermata sostituisce, per la quota
fatturata, il costo dei carichi dei DDT fornitore che fattura; la differenza di prezzo rispetto a ordine e ricevimento
è anche mostrata come avviso sulla fattura (`PurchaseService.PriceDifferencesAsync`), senza bloccare.
5. **Ricostruzione.** `InventoryService.RebuildAsync` cancella i movimenti e riposta tutti i documenti in vigore,
dal più vecchio e, a parità di data, i DDT prima delle fatture, poi ricalcola ogni articolo; gira a mano (con
avanzamento) e ogni domenica come job di sistema `inventory.rebuild`.
6. **Inventario come documento a sé.** `stock_takes` e `stock_take_lines` fotografano la giacenza contabile alla
data del conteggio; la registrazione crea due movimenti `MM` (`INVP` e `INVN`) alla stessa data. Gli articoli non
contati non vengono toccati; non c'è blocco dei movimenti durante il conteggio, perché le rettifiche sono datate
e la storia ricalcolata tiene conto dei movimenti successivi.
7. **Valorizzazione.** Costo medio ponderato, ultimo costo e costo standard a qualsiasi data, con classi ABC (80% e
95% del valore). FIFO e LIFO restano **predisposti**: il criterio è un parametro del calcolo
(`StockValuationMethod`) e i movimenti conservano data, quantità e costo di ogni carico, ma i due metodi non sono
ancora offerti perché richiedono i lotti di carico, rimandati a dopo la 1.0.
8. **Tabelle di base nelle aziende esistenti.** La migrazione `M20261113_001_CreateInventory` crea le tabelle e
assegna la causale ai tipi di base che non l'hanno (`FI` → `SCA`, `FF` → `CAR`, `NCF` → `RESF`), senza toccare una
causale scelta dall'utente. I tipi nuovi (`AF20`-`AF29`) e le causali mancanti si aggiungono con *Aggiorna da
tabelle base* o `scripts/seed.sh --base`, che aggiungono i codici mancanti senza modificare quelli esistenti
(ADR 0026). Il tracciato
*Giacenze iniziali* scrive un movimento `APE` per deposito.
9. **Regole italiane nel pacchetto fiscale.** `ISelfInvoiceRules` (`SelfInvoiceRulesIt`) decide dall'anagrafica del
fornitore (paese, UE), dal genere delle righe (beni o servizi) e dalle nature IVA quale autofattura serve (TD16,
TD17, TD18, TD19, TD28) e la scadenza (15 del mese successivo; 90 giorni per TD20 e TD29).
`IIncomingInvoiceRules` (`IncomingInvoiceRulesIt`) traduce il tipo FatturaPA nel tipo documento d'acquisto (TD01,
TD02, TD03, TD05, TD06, TD24-TD27 in `FF`; TD04 e TD08 in `NCF`; gli altri sono rifiutati). L'applicazione non
conosce i codici TD.
10. **Import delle fatture ricevute.** `PurchaseInvoiceImportService` legge XML, P7M e ZIP con il lettore di #57, trova
il fornitore per partita IVA o codice fiscale (o lo crea), rifiuta i doppioni (stesso fornitore, numero, anno),
abbina le righe per codice del fornitore, EAN e codice articolo, il codice IVA per aliquota e natura, porta gli
sconti percentuali nello sconto di riga e gli altri nel prezzo netto, e salva una bozza con il file allegato.
Totale diverso, firma non verificata e sconti sul totale sono avvisi, non errori.
## Conseguenze
- Le quantità e i costi sono sempre ricostruibili dai documenti: i movimenti sono un dato derivato e la ricostruzione
è anche la verifica di coerenza.
- Ricalcolare la storia di un articolo costa più di un aggiornamento incrementale; con le dimensioni di una PMI
(migliaia di movimenti per articolo all'anno) resta nell'ordine dei millisecondi, e i documenti toccano pochi
articoli alla volta. Se servirà, un punto di partenza annuale (chiusura del magazzino) accorcia la storia.
- I documenti fornitore senza numero interno (`DDTF`) si riconoscono dal numero del fornitore; l'interfaccia li mostra
come *Senza numero*.
- Rimandati: lotti, matricole e ubicazioni; FIFO e LIFO; libro inventari e scritture delle rimanenze (M7); XML delle
autofatture e scarico dal canale SDI (M9); report di magazzino stampabili (M13).
+65
View File
@@ -0,0 +1,65 @@
# ADR 0036 - Contabilità generale
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.7, §12.11; milestone M7, issue #62, #63, #67, #68
## Contesto
SPEC §11.7 chiede un piano dei conti a tre livelli con un modello italiano, causali con righe proposte, prima nota
in partita doppia con registrazioni provvisorie e definitive, registrazioni ricorrenti, partitari di clienti e
fornitori, mastrini, bilancio di verifica e libro giornale. Restavano aperti: come si numerano le registrazioni,
quando una registrazione non si può più toccare, come si correggono gli errori, dove sta il modello del piano dei
conti, come si portano piano e causali nelle aziende create prima di M7.
## Decisione
1. **Piano dei conti a tre livelli.** `gl_accounts` con codice `MM.CC.SSS` (mastro, conto, sottoconto), padre,
natura (attività, passività, costo, ricavo, ordine), tipo (generico, clienti, fornitori, banca, cassa, IVA,
tributi), voce del bilancio CEE, flag *partitario*, *rilevante IVA* e *chiusura automatica*. Si registra solo sui
sottoconti; i conti con partitario chiedono il cliente o il fornitore sulla riga. Un conto con movimenti o con
sottoconti non si elimina (si disattiva). Le regole sui codici stanno in `AccountCodes` (`Khaemhat.Core`).
2. **Il modello sta nel pacchetto fiscale.** `ILedgerTemplate` (`ItalianLedgerTemplate`) dà il piano *PMI standard*
(237 conti, da `Data/piano-dei-conti.csv`), le causali, i registri IVA, il conto di ogni ruolo contabile
(`PostingRole`: clienti, fornitori, IVA vendite e acquisti, erario, ritenute, bollo, arrotondamenti...) e quale
causale usa ogni tipo documento. L'applicazione non conosce codici di conto italiani.
3. **Causali con righe proposte.** `gl_journal_templates` e `gl_journal_template_lines`: area, registro IVA,
*apre partite*, *causale di storno*, righe con ruolo o conto, segno e descrizione. La causale di storno non ha
righe: copia quelle della registrazione stornata a segni invertiti. Una causale usata non si elimina.
4. **Tre stati e due numeri.** Una registrazione (`gl_entries`, `gl_entry_lines`, `gl_entry_vat`) nasce *Bozza*
(può non quadrare, non entra nei saldi se non lo si chiede), diventa *Registrata* quando quadra (numero di
registrazione per anno, assegnato alla registrazione) e *Definitiva* con **Rendi definitive** fino a una data: le
registrazioni ricevono il numero del libro giornale in ordine di data e non si modificano né si eliminano più. Il
comando è rifiutato se prima di quella data restano bozze, e dopo non si registra più con una data anteriore
all'ultima definitiva. Gli errori su una definitiva si correggono solo con lo
**storno** (registrazione `STO` a segni invertiti, una sola per registrazione). `JournalEntryValidator`
(`Khaemhat.Core`) controlla quadratura, sottoconti, partitari, righe IVA.
5. **Partite aperte.** Le registrazioni con una causale che *apre partite* scrivono `gl_open_items` (una per rata,
con scadenza, importo, pagato); il partitario mostra saldo, estratto conto e partite, con le scadute evidenziate.
Incassi e pagamenti che chiudono le partite arrivano con la tesoreria (M8).
6. **Ricorrenti come copia di un modello.** `gl_recurring_entries` punta a una registrazione modello e ne crea una
copia a ogni data (mensile, trimestrale, semestrale, annuale, con la fine del mese mantenuta) fino alla data di
fine; il job di sistema `ledger.recurring` gira ogni giorno alle 05:00 e il pulsante *Genera ora* lo anticipa. Le
copie sono *Registrate* con origine *Ricorrente*.
7. **Saldi calcolati dalle righe.** Mastrini, partitari e bilancio di verifica (`LedgerQueryService`) sommano le
righe del periodo, con saldo di apertura dalle righe precedenti, senza tabelle di saldi: le registrazioni toccano
poche righe e i totali restano coerenti per costruzione. Il bilancio di verifica raggruppa per mastro, conto e
sottoconto, filtra per centro di costo e mostra il risultato del periodo (ricavi meno costi).
8. **Stampe.** Libro giornale di prova o definitivo, mastrini, estratti conto e bilancio di verifica sono PDF di
`LedgerReport` sul motore di stampa di M5 (ADR 0034).
9. **Aziende esistenti.** La migrazione `M20261113_002_CreateLedger` crea le tabelle; i documenti hanno già la
colonna *contabilizzato* da M5. Piano dei conti, causali e registri arrivano da `LedgerSeeder` (seed di base, *Aggiorna da tabelle
base* o `scripts/seed.sh --base`), che aggiunge i codici mancanti senza toccare quelli esistenti (ADR 0026). La
demo (`DemoLedgerSeeder`) contabilizza i documenti demo, paga la fattura del professionista, crea il noleggio
mensile della stampante come ricorrente, conferma le liquidazioni dei mesi passati e paga gli F24 scaduti.
10. **Permessi.** `ledger.account.read/write`, `ledger.entry.read/write/finalize`; tutto dietro il modulo `ACCT`.
## Conseguenze
- Un errore su una registrazione definitiva lascia sempre traccia (registrazione originale e storno), come chiede il
libro giornale.
- Sommare le righe a ogni richiesta costa più di un saldo memorizzato; con le dimensioni di una PMI (decine di
migliaia di righe l'anno) resta sotto il secondo, e gli indici su conto e data coprono le query. La chiusura
dell'esercizio (M10) porta i saldi di apertura e accorcia la storia.
- Rimandati: chiusura e riapertura dell'esercizio, bilancio CEE riclassificato, cespiti (M10); incassi, pagamenti e
riconciliazione bancaria (M8); budget per centro di costo.
+72
View File
@@ -0,0 +1,72 @@
# ADR 0037 - Contabilizzazione dei documenti, IVA e F24
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.7, §11.8, §12.11; milestone M7, issue #64, #65, #66
## Contesto
SPEC §11.7 e §11.8 chiedono che fatture, note e autofatture si contabilizzino da sole, con registri IVA,
liquidazione periodica, acconto, comunicazione LIPE, ritenute d'acconto, certificazione unica, bollo virtuale e
prospetto F24. Restavano aperti: quando si scrive la registrazione di un documento, come si corregge, come si
calcola la liquidazione, cosa succede se la si riapre, dove stanno codici tributo e scadenze italiane.
## Decisione
1. **Contabilizzazione nella transazione del documento.** `LedgerPoster` gira nel motore documenti, come
`InventoryPoster` (ADR 0035), e solo con il modulo `ACCT` attivo. Fatture (immediate, accompagnatorie,
differite, di acconto), note di debito e parcelle sono *vendite*; la nota di credito è una vendita a segni
invertiti; fattura e nota fornitore sono *acquisti*; autofatture e integrazioni vanno in entrambi i registri. La
modifica di un documento in vigore riscrive la sua registrazione **con lo stesso numero**; l'annullamento la
elimina o, se è definitiva, la storna. Una registrazione che viene da un documento non si modifica a mano: si
corregge il documento. I documenti confermati prima della licenza si contabilizzano in blocco
(`LedgerService.PostPendingAsync`, pulsante *Contabilizza documenti*).
2. **Regole di registrazione in `PostingEngine`** (`Khaemhat.Core`, senza accesso ai dati): vendita = cliente Dare
per il totale, ricavi Avere per conto dell'articolo o della riga, rivalsa cassa e bollo addebitato Avere, IVA
vendite Avere; scissione dei pagamenti = l'IVA torna dal cliente al conto dell'erario; acquisto = fornitore Avere,
costi Dare con l'IVA indetraibile sommata al costo, IVA acquisti Dare; autofattura = IVA acquisti Dare e IVA
vendite Avere. Sconti di testata e arrotondamenti vanno sulla riga più grande, così la registrazione quadra sempre
al centesimo. Un conto mancante blocca la conferma con un errore che dice quale ruolo configurare.
3. **Righe IVA e partite dal documento.** Il castelletto del documento diventa `gl_entry_vat` nel registro della
causale (`VEN1`, `VEN-RC`, `ACQ1`, `ACQ-RC`, `CORR`) con protocollo, data IVA, esigibilità e quota indetraibile;
le rate diventano partite aperte; la ritenuta del documento diventa una riga di `withholdings`.
4. **Registri e stampa definitiva.** I registri IVA si leggono per periodo con il riepilogo per aliquota; la stampa
definitiva (`vat_register_prints`) parte dal giorno dopo l'ultima stampa definitiva e continua la numerazione delle
pagine dell'anno. Il blocco del periodo viene dalla liquidazione (punto 5), non dalla stampa.
5. **Liquidazione in `VatSettlementCalculator`** (`Khaemhat.Core`): IVA a debito delle vendite e dei corrispettivi
esigibili (l'esigibilità differita resta fuori), IVA a credito degli acquisti al netto dell'indetraibile e del pro
rata, credito o debito del periodo precedente, acconto di dicembre, interessi dell'1% sul trimestrale (anche sul
quarto, versato a marzo con il codice 6099), minimo di versamento sotto il quale il debito passa al periodo dopo. Periodicità dal profilo
azienda. La liquidazione si **calcola** quante volte si vuole e si **conferma** in ordine: la conferma scrive la
registrazione `LIQ` (IVA vendite Dare, IVA acquisti Avere, interessi Dare, erario c/liquidazione Avere), segna i
periodi fiscali come liquidati (da lì documenti e registrazioni con IVA in quelle date sono rifiutati, ADR 0026
sui periodi) e crea il versamento F24 se c'è da pagare. La si può **riaprire** finché il suo F24
non è pagato e nessuna liquidazione successiva è confermata.
6. **Regole italiane nel pacchetto fiscale.** `IVatSettlementRules` (`VatSettlementRulesIt`) dà minimo (25,82),
interessi trimestrali, acconto (88%, minimo 103,29, metodi storico, previsionale ed effettivo), codici tributo
(6001-6012, 6031-6033, 6099 con rateazione 0101, 6013 e 6035 per l'acconto, 1040 per le ritenute, 2521-2524 per il
bollo), scadenze (16 del mese, agosto al 20, acconto al 27 dicembre, giorno lavorativo successivo) e soglie del
bollo virtuale (5.000 euro sul primo e secondo trimestre). `IPeriodicVatReturnWriter` (`LipeWriter`) scrive il
file LIPE (fornitura `IVP18`); `ITaxPaymentFormExporter` esporta i dati F24 in CSV.
7. **Tributi come versamenti.** `tax_payments` raccoglie ogni riga da versare (IVA, acconto, ritenute, bollo) con
codice, periodo e scadenza; il prospetto F24 le raggruppa per scadenza. *Registra pagamento* scrive la
registrazione `F24` (erario Dare per origine, banca Avere) e segna le righe come pagate; si annulla eliminando o
stornando quella registrazione.
8. **Ritenute.** Quelle *operate* nascono dalle fatture dei professionisti: in attesa finché la fattura non è
pagata, poi da versare (registrazione `RIT`, riga F24 al 16 del mese dopo); quelle *subite* nascono dalle
parcelle emesse (registrazione `RITS`, credito per ritenute). I dati della certificazione unica si esportano in
CSV per anno e percipiente.
9. **Nessun invio telematico.** Khaemhat prepara LIPE, dati F24 e dati CU; l'invio resta all'utente o
all'intermediario con i servizi dell'Agenzia delle Entrate.
10. **Permessi.** `vat.register.read`, `vat.settlement.read/confirm`, oltre a quelli di ADR 0036.
## Conseguenze
- Documenti e contabilità non divergono: la registrazione è un dato derivato, scritto nella stessa transazione, e
una contabilizzazione in blocco la ricostruisce.
- Correggere un documento di un periodo già liquidato è rifiutato dal blocco dei periodi: si corregge con una nota
di variazione, come prevede la norma, oppure si riapre la liquidazione.
- La verifica a mano della demo è un test (`DemoLedgerTests`): la prima liquidazione con IVA è ricalcolata dai
registri e confrontata con quella confermata.
- Rimandati: dichiarazione IVA annuale, Intrastat, F24 telematico, plafond e dichiarazioni d'intento, IVA per cassa
con chiusura automatica delle partite (con gli incassi di M8).
+70
View File
@@ -0,0 +1,70 @@
# ADR 0038 - Scadenzario, distinte, riconciliazione bancaria e solleciti
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.8, §10.3; milestone M8, issue #69, #70, #71, #72
## Contesto
SPEC §11.8 chiede lo scadenzario di clienti e fornitori con incassi e pagamenti (abbuoni, differenze cambio,
insoluti), le distinte RiBa, SDD e bonifici SEPA, i mandati, la riconciliazione bancaria con import CSV/CBI/CAMT.053
e abbinamento automatico, i solleciti con interessi di mora e il flusso di cassa. Restavano aperti: dove vivono le
partite, come si contabilizzano distinte e insoluti, quali versioni dei tracciati produrre senza librerie esterne
(SPEC §1), come evitare i doppioni dell'estratto conto, come stimare la confidenza degli abbinamenti, dove stanno i
tassi di mora e cosa fa la demo senza licenza FIN.
## Decisione
1. **Le partite sono quelle della contabilità.** Lo scadenzario non ha una tabella sua: legge e aggiorna
`gl_open_items`, scritte dalla contabilizzazione dei documenti (ADR 0037). Incassi e pagamenti (`payments`,
`payment_lines`) chiudono le partite e scrivono **subito** la registrazione INC o PAG nella stessa transazione,
con abbuoni, spese e differenze cambio sui conti dei ruoli di registrazione del pacchetto fiscale
(`AllowanceIncome`, `AllowanceExpense`, `BankCharges`, `ExchangeGain`, `ExchangeLoss`). La rettifica di una
registrazione mantiene le partite già saldate. L'annullamento di un incasso storna la registrazione e riapre le
partite; la ritenuta d'acconto di una parcella diventa dovuta quando la fattura è saldata del tutto.
2. **Distinte in quattro passi.** Bozza (le partite passano *In distinta*) → file generato → presentazione → accredito.
RiBa e SDD alla presentazione spostano il credito da *Clienti* a *Effetti all'incasso* (`BillsForCollection`); con
il *salvo buon fine* la banca accredita subito su *Banche c/anticipi* (`BankAdvances`). L'accredito chiude il conto
effetti o l'anticipo. I bonifici SEPA pagano i fornitori già alla presentazione. L'**insoluto** riapre la partita
come *Insoluta*, riprende l'importo dalla banca e trasforma le spese in una **nuova partita** del cliente, così il
recupero passa dallo scadenzario come ogni altra rata.
3. **Tracciati scritti in casa.** RiBa nel tracciato CBI a record di 120 caratteri (IB, 14, 20, 30, 40, 50, 51, 70,
EF), scritto dal pacchetto italiano (`RibaCbiWriter`); SDD in `pain.008.001.08` e bonifici in `pain.001.001.09`
con `XmlWriter` (`SepaXmlWriter`, nel core perché SEPA non è solo italiano). Le specifiche CBI e gli schemi
ISO 20022 non si possono scaricare durante lo sviluppo: i tracciati seguono la documentazione pubblica nota e i
test controllano lunghezze, posizioni, totali e struttura. Il file va caricato a mano nell'home banking; il
collegamento diretto (CBI online, PSD2) è fuori da M8.
4. **Estratti conto senza doppioni.** Ogni movimento importato ha un'**impronta** SHA-256 di conto, data contabile,
importo, descrizione e riferimento normalizzati e del numero di movimenti uguali che lo precedono nello stesso
file; l'impronta è unica per conto, quindi rimportare un file o file sovrapposti salta i movimenti già presenti.
Il CSV si riconosce dalla riga di intestazione (separatore, nomi italiani o inglesi, colonne di entrate e uscite
o importo con segno); il CBI dai record RH/61-64/EF; CAMT.053 dallo spazio dei nomi.
5. **Confidenza a punti.** `BankMatcher` (core) assegna 50 punti all'importo esatto (40 se entro la tolleranza del
candidato, per esempio un insoluto con spese), +30 per un numero di documento, CRO o riferimento trovato nella
descrizione, +30 per le parole chiave del candidato, +25 per l'IBAN della controparte, +20 per il nome, e +10/+5/0/-10
per la distanza fra le date (≤3, ≤15, ≤60, oltre). Una **regola** salvata che riconosce il testo vale 98. La
proposta si conferma a mano o in blocco sopra la soglia di **90**: sotto, la scelta resta all'utente.
6. **Interessi di mora nel pacchetto.** `ILatePaymentRules` (astrazioni) e `LatePaymentRulesIt` portano il tasso
del D.Lgs. 231/2002: tasso BCE di riferimento del semestre più 8 punti, da una **tabella semestrale** nel codice
(2,15% nel primo semestre 2026, 2,40% nel secondo) che va aggiornata a ogni comunicato del MEF; dopo l'ultima riga
vale l'ultimo tasso. Gli interessi si mostrano nei solleciti e nell'estratto conto, non si contabilizzano.
7. **Solleciti.** Tre livelli predefiniti (7, 20 e 45 giorni) modificabili; canali come flag (e-mail, PEC, lettera
PDF); esclusi PA, partite contestate e in distinta. L'invio usa la coda di posta dell'invio documenti (ADR 0034); le lettere si
scaricano in un PDF unico. L'attività `finance.dunning` (giorni feriali alle 7:00) invia solo i livelli
*Automatico* e solo per e-mail e PEC.
8. **Permessi.** Cinque codici: `finance.schedule.read`/`write`, `finance.payment.read`/`write`,
`finance.bank.reconcile`, tutti nel modulo `FIN`; le registrazioni chiedono anche `ACCT`.
9. **Demo solo con FIN.** `DemoTreasurySeeder` usa gli stessi servizi del programma, che controllano la licenza:
senza il modulo FIN attivo la demo salta la tesoreria invece di scrivere dati che l'azienda non potrebbe vedere.
10. **Flusso di cassa calcolato al momento.** Nessuna tabella: saldo contabile di banche e cassa, partite aperte,
effetti presentati senza anticipo, residuo degli ordini (30 giorni dopo la consegna), registrazioni ricorrenti
che muovono la banca e F24 non pagati; lo scaduto cade nel primo periodo.
## Conseguenze
- Contabilità e scadenzario non possono divergere: c'è una sola fonte delle partite.
- La tabella dei tassi di mora è una manutenzione semestrale del pacchetto italiano (gennaio e luglio).
- I tracciati vanno provati con l'home banking reale alla prima installazione; le differenze si correggono nel
pacchetto senza toccare i servizi.
- Il piano dei conti PMI standard guadagna *Perdite su cambi*, *Utili su cambi* e *Interessi di mora attivi*
(240 conti).
+81
View File
@@ -0,0 +1,81 @@
# ADR 0039 - Fatturazione elettronica: file, stati, canali e ricezione
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.9, §10.3 (mockup 058 e 059); milestone M9, issue #74, #75, #76, #77, #79
## Contesto
SPEC §11.9 chiede il file FatturaPA delle fatture emesse con controllo prima dell'invio, la trasmissione allo SDI
attraverso quattro canali (PEC integrata, SdICoop, due intermediari) con regole di instradamento, le notifiche che
aggiornano lo stato dei documenti, le fatture ricevute, la correzione degli scarti, la copia di cortesia e il
pacchetto per la conservazione. Restavano aperti: dove sta il file e come convive con il documento, come si
numerano i file, come si controlla il file senza librerie esterne né lo schema ufficiale (SPEC §1, nessun download
durante lo sviluppo), come si evitano doppioni di notifiche e fatture ricevute, come si leggono i canali senza perdere
messaggi, come riceve SdICoop e come si proteggono le credenziali.
## Decisione
1. **Il file sta nel database.** Ogni file è una riga di `e_invoices` con il contenuto XML, nome, progressivo,
canale, identificativo SDI e stato. Lo stato del documento di vendita segue quello del file nella stessa
transazione, attraverso il motore dei documenti (`AdvanceExchangeAsync`, azioni `GenerateXml`, `Send`,
`MarkDelivered`, `MarkRejected`, `MarkNotDelivered`). Un file scartato **non si cancella**: resta come
*sostituito* e il documento torna modificabile; la nuova generazione prende un nuovo progressivo. Un file
generato e non ancora inviato si riscrive con lo stesso nome.
2. **Nome e progressivo.** `IT<identificativo>_<progressivo>.xml`, progressivo di cinque caratteri in base 36 da un
contatore dell'azienda, mai riusato (60.466.175 file per trasmittente).
3. **Tutto ciò che è italiano nel pacchetto.** Le astrazioni (`IEInvoiceWriter`, `IEInvoiceValidator`,
`IEInvoiceReceiptReader`, `IEInvoiceChannels`, `IEInvoicePushReader`) sono in `Khaemhat.Fiscal.Abstractions`;
scrittura, controlli, lettura delle ricevute e i quattro trasporti sono in `Khaemhat.Fiscal.Italy`. Il web non
dipende dal pacchetto italiano.
4. **Controlli con i codici dello SDI e schema scritto in casa.** `FatturaPaValidator` ripete offline i controlli
documentati dall'Agenzia con lo **stesso codice di errore** (00400, 00423, 00471…), con le tolleranze delle
specifiche (un centesimo su `PrezzoTotale` e `Imposta`, un euro su `ImponibileImporto`); ciò che richiede i
registri dell'Agenzia (partita IVA esistente, codice destinatario accreditato, indice IPA) si controlla solo nella
forma. La struttura si controlla contro uno schema XSD **scritto per Khaemhat** sulle regole del formato 1.2
(risorsa incorporata `FatturaPA_v1.2_khaemhat.xsd`), perché il file ufficiale non si può scaricare durante lo
sviluppo; le specifiche seguite sono la 1.9.1 (`FatturaPaCodeLists.SpecVersion`). Sostituire lo schema con
quello ufficiale non cambia il codice.
5. **Una notifica entra una volta.** Il nome del file della notifica è unico in `e_invoice_notifications`; un
doppione è riconosciuto e segnalato, non applicato due volte. La notifica si abbina al file per nome del file
fattura o per identificativo SDI; quella non abbinata resta registrata ed evidenziata. MT e SE si conservano
senza cambiare stato. Le fatture ricevute entrano in `e_invoice_inbox` una volta sola (impronta SHA-256 del
contenuto).
6. **Lettura dei canali senza perdite.** L'attività `einvoice.poll` (ogni 15 minuti) legge i canali attivi e non in
pausa; ogni messaggio è **confermato** (archiviato in PEC, `ack` o cancellazione presso l'intermediario) solo dopo
che tutti i suoi file sono stati salvati, così un arresto a metà rilegge il messaggio e la deduplicazione scarta
ciò che c'è già. Per la PEC si leggono solo i messaggi con mittente `fatturapa.it` e gli allegati `.xml`/`.p7m`
del messaggio originale; la cartella di archivio è l'impostazione consigliata.
7. **Instradamento a regole.** `SdiRouter` (core) sceglie la prima regola attiva che si applica, nell'ordine:
*Sempre*, *Cliente PA*, *Cliente specifico*, *Tipo documento*, *Volume giornaliero*. Ogni regola ha un canale di
riserva usato se il primo è in pausa, disattivato o fallisce l'invio. Senza regole vale il primo canale attivo.
8. **SdICoop in push.** Lo SDI consegna notifiche e fatture con chiamate SOAP verso l'azienda. Khaemhat espone
`POST /sdicoop/{azienda}` (anonimo per l'autenticazione dell'applicazione, senza antiforgery, al massimo 16 MB);
`SdiPushService` accetta la chiamata solo se il canale SDICOOP è attivo e l'intestazione
`X-Khaemhat-SdiCoop-Key` corrisponde alla chiave di ricezione (confronto a tempo costante delle impronte SHA-256).
Il certificato reciproco richiesto dall'Agenzia si verifica sul **reverse proxy**, che aggiunge l'intestazione:
Kestrel resta senza configurazione TLS speciale. Il pacchetto legge la busta (`IEInvoicePushReader`) e prepara la
risposta SOAP. Risposte: 404 azienda sconosciuta o senza modulo, 401 canale non attivo o chiave errata, 400 corpo
illeggibile, 200 dopo il salvataggio.
9. **Credenziali cifrate.** Password, chiavi API, chiave di ricezione e certificato PKCS#12 sono cifrati con
`ISecretProtector` (scopo `einvoice.channel`) e non tornano mai nell'interfaccia: un campo vuoto mantiene il valore.
Gli indirizzi dei servizi devono essere `https` (`http` solo verso `localhost`).
10. **Copia di cortesia in PDF.** La stampa del documento con il file FatturaPA come file associato (`/AF`,
struttura PDF/A-3). Non si dichiara la conformità PDF/A, che richiederebbe profili colore e font incorporati
certificati.
11. **Conservazione come esportazione.** Khaemhat non è un conservatore: `ConservationExportService` prepara uno ZIP
(`emesse/`, `ricevute/`, `notifiche/`, `indice.csv` con SHA-256, `LEGGIMI.txt`) per al massimo 731 giorni e
registra in `e_invoice_conservation` periodo, numero di file, dimensione e impronta.
12. **Permessi.** `einvoice.document.read`, `einvoice.document.send`, `einvoice.inbox.read`, `einvoice.inbox.import`,
`einvoice.channel.manage`, tutti nel modulo `EINV`.
## Conseguenze
- La fattura e i suoi file viaggiano insieme in backup e ripristino; il database cresce di qualche kB per fattura.
- Gli scarti più comuni si vedono prima dell'invio, con il messaggio che lo SDI darebbe.
- Lo schema scritto in casa può essere meno severo di quello ufficiale su dettagli di struttura: quando l'utente
autorizza il download, il file ufficiale va messo al posto della risorsa e i test di scrittura rieseguiti.
- SdICoop e gli intermediari sono pronti ma vanno attivati solo dopo l'accreditamento e la scelta del fornitore
(issue #78, ADR 0040); la PEC funziona da subito.
- Le dichiarazioni d'intento (M10) e il formato EN 16931 / UBL arriveranno come altre implementazioni delle stesse
astrazioni.
@@ -0,0 +1,45 @@
# ADR 0040 - Contratti degli intermediari SDI e rimozione dei dati di esempio
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.9, §14; milestone M9, issue #77, #78, #80
## Contesto
SPEC §11.9 prevede due intermediari accreditati come canali verso lo SDI, ma il titolare del progetto non ha ancora
scelto i fornitori (issue #78): non ci sono API reali da seguire. SPEC §14 chiede inoltre che i dati di esempio si
possano **rimuovere** senza toccare i dati dell'utente; finora ogni milestone aggiungeva tabelle demo e una rimozione
scritta a mano avrebbe dovuto essere aggiornata ogni volta.
## Decisione
1. **Due contratti generici.** `IntermediaryTransportBase` contiene il ciclo comune (invio, lettura dei file in
attesa, conferma, prova); le due classi derivate definiscono solo le richieste:
- **Intermediario A** (chiave API, `Authorization: Bearer`): `POST {endpoint}/invoices` con il file e
l'intestazione `X-File-Name`, risposta `{ "id", "sdiId" }`; `GET files` per notifiche e fatture in attesa;
`POST files/{id}/ack` per confermarle; `GET status` per la prova.
- **Intermediario B** (utente e password, `Authorization: Basic`): `POST api/v1/send`, `GET api/v1/inbox`,
`DELETE api/v1/inbox/{id}` come conferma, `GET api/v1/ping`.
Quando l'utente sceglie i fornitori, ogni contratto diventa l'API reale cambiando solo le richieste della classe
derivata; servizi, instradamento, interfaccia e test di integrazione restano uguali.
2. **Prima l'accreditamento.** SdICoop e intermediari sono scritti e provati con server finti nei test, ma si
attivano in produzione solo dopo accreditamento o contratto (#78). La PEC è il canale che funziona subito.
*Aggiornato dall'ADR 0044:* la scelta dei fornitori e l'accreditamento sono rimandati; #78 resta nel backlog.
3. **Rimozione guidata dallo schema.** `DemoDataRemover` legge dalle migrazioni le tabelle con la colonna `is_demo`
e le chiavi esterne: elimina le righe marcate e quelle delle tabelle senza marca che appartengono loro (righe di
documento, giacenze), in ordine di dipendenza e in **una transazione**. Se una riga dell'utente si riferisce a una
riga demo (una fattura vera a un cliente demo) non elimina nulla e restituisce le tabelle che lo impediscono.
Le entità che possono essere demo implementano `IDemoMarkable`; un nuovo modulo è coperto senza modifiche.
4. **Comando.** `scripts/seed.sh --remove-demo [--company CODICE]` (non combinabile con `--base`, `--demo`,
`--scale`) stampa le righe rimosse per tabella o le tabelle bloccanti.
5. **Demo della fatturazione solo con EINV e senza rete.** `DemoEInvoiceSeeder` usa i servizi del programma, che
controllano la licenza; il canale PEC dell'esempio è **in pausa** con credenziali finte e le notifiche sono
applicate come se fossero arrivate, così nessun dato dimostrativo raggiunge lo SDI.
## Conseguenze
- Il lavoro per un intermediario reale è limitato a una classe e ai suoi test.
- Un database creato prima della marca `is_demo` su tutte le tabelle può bloccare la rimozione: è voluto, l'utente
vede quali tabelle controllare.
- La rimozione resta un'operazione da super utente e da riga di comando; il pulsante nell'interfaccia arriva con le
pagine di amministrazione (M12).
+45
View File
@@ -0,0 +1,45 @@
# ADR 0041 - Cespiti: piani paralleli, registrazione per categoria e dismissioni
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.7, §21; milestone M10, issue #82; mockup 048
## Contesto
SPEC §11.7 chiede il registro dei beni ammortizzabili con piano civilistico e fiscale, il calcolo e la registrazione
delle quote di fine anno, le dismissioni con plusvalenza o minusvalenza e la stampa del registro. Le regole italiane
(coefficienti del DM 31/12/1988, primo anno al 50 % ai fini fiscali, limiti delle autovetture, beni fino a 516,46 €)
devono restare nel pacchetto fiscale. La chiusura dell'esercizio (ADR 0043) deve poter registrare gli ammortamenti
come suo passo 2 e annullarli.
## Decisione
1. **Categorie con aliquote proprie.** Il pacchetto italiano espone `IFixedAssetRules` con le categorie standard
(`MinisterialCoefficients`): materiali con i coefficienti comuni del DM 31/12/1988, immateriali con i limiti
dell'art. 103 TUIR. La categoria dell'azienda conserva aliquota civilistica e fiscale, metà aliquota civilistica
nel primo anno, limite di costo e deducibilità, conti di cespite, fondo e ammortamento: la tabella dipende dal
settore e ogni azienda la adatta.
2. **Due piani con la stessa regola.** `DepreciationCalculator` applica le quote costanti al costo, dimezzate nel
primo anno quando richiesto, senza superare il residuo; i beni con aliquota 100 % si ammortizzano nel primo anno.
Il piano fiscale dimezza sempre il primo anno dei beni materiali. Il bene conserva fondo civilistico e fiscale;
l'aliquota del bene vuota segue la categoria.
3. **Una registrazione per anno, una riga per categoria.** Gli ammortamenti si registrano al 31/12 con origine
`FixedAsset` (quota in Dare, fondo in Avere, per categoria) e un movimento `Depreciation` per bene. L'annullamento
toglie movimenti, fondi e registrazione finché la registrazione non è definitiva. Solo la quota civilistica va in
contabilità: la differenza con la fiscale è una variazione in dichiarazione.
4. **Beni già in uso.** Un bene acquistato prima dell'avvio porta i fondi iniziali e l'ultimo esercizio già
ammortizzato con un movimento `Opening`; i fondi entrano in contabilità con la scrittura di apertura dei conti.
5. **Dismissioni senza quota dell'anno.** La dismissione (totale o parziale) toglie il costo dismesso e la quota
proporzionale del fondo, porta il prezzo sul conto *altri crediti* e la differenza a plusvalenza o minusvalenza.
Nell'anno della dismissione **non** si calcola la quota: è la scelta prudente e più semplice da verificare; chi
vuole la quota fino alla data la registra prima con una scrittura manuale. Gli ammortamenti di un anno non si
registrano se esistono già quelli di un anno successivo (`assets.later-depreciation`).
## Conseguenze
- Il registro, gli ammortamenti e la stampa funzionano anche senza la chiusura guidata; il passo 2 della chiusura
riusa lo stesso servizio e non duplica le quote.
- L'annullamento del passo 2 rimuove tutti gli ammortamenti dell'anno, anche quelli registrati a mano dalla pagina
Ammortamenti prima della chiusura.
- Le rivalutazioni previste dalle singole leggi restano un movimento `Revaluation` senza regole guidate: si aggiungono
quando servono.
@@ -0,0 +1,46 @@
# ADR 0042 - Intrastat e dichiarazioni d'intento
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.7, §8.1; milestone M10, issue #83; mockup 049 e 061
## Contesto
SPEC §11.7 chiede gli elenchi Intrastat generati dai documenti con il file per le Dogane e le dichiarazioni d'intento
degli esportatori abituali con il controllo del plafond. Fino a M9 la dichiarazione d'intento era un gruppo di campi
nei dati fiscali del cliente (protocollo, data, plafond) usato solo dal file FatturaPA. Le soglie, il tracciato e il
formato del protocollo sono regole italiane.
## Decisione
1. **Intrastat dai documenti confermati.** `IntrastatService` legge fatture e note di credito (vendite e acquisti)
confermate nel periodo verso soggetti di un altro Stato membro: i beni sono raggruppati per controparte,
nomenclatura e natura della transazione, i servizi hanno una riga per fattura, le note di credito diventano
rettifiche. Natura `11`, consegna `DAP` e trasporto `3` sono proposti e si correggono sulla riga. Le righe manuali
sopravvivono alla rigenerazione.
2. **Periodicità e file nel pacchetto.** `IIntrastatExporter` italiano (`IntrastatExporterIt`) calcola la
periodicità dai quattro trimestri precedenti con le soglie dal 2022 (cessioni 50.000 € per categoria; acquisti di
beni 350.000 € e di servizi 100.000 €, sotto le quali non sono dovuti) e scrive il file `SCAMBI.CEE` a record di
lunghezza fissa. Un elenco con righe incomplete non si esporta; dopo l'invio, con il protocollo, è di sola lettura.
3. **Il tracciato va validato.** Il file segue le specifiche pubblicate ma non è stato provato con il software di
controllo delle Dogane: STATUS lo indica come attività aperta e la wiki chiede il controllo prima del primo invio.
4. **Registro delle dichiarazioni.** Le dichiarazioni diventano una tabella (`intent_declarations`) con direzione
(ricevute o emesse), numero di registro per anno, protocollo (`IIntentRules`: 17 cifre, trattino o barra, 6
cifre), validità, plafond, utilizzato e stato. Il cliente conserva lo **specchio** della dichiarazione corrente
nei dati fiscali, così documenti e FatturaPA (`AltriDatiGestionali` tipo `INTENTO`) non cambiano. Le dichiarazioni
scritte nei dati fiscali prima della 0.10 vengono adottate nel registro alla prima lettura o al primo controllo.
5. **Controllo alla conferma.** `DocumentEngine` chiama `IntentDeclarationService.CheckAsync` quando conferma una
vendita con righe di natura N3.5: senza dichiarazione attiva che copre la data la conferma è rifiutata
(`intent.no-declaration`), oltre il residuo pure (`intent.ceiling-exceeded`); le note di credito restituiscono
plafond e non sono controllate. Dopo ogni conferma, annullamento o eliminazione l'utilizzato si **ricalcola** da
tutte le vendite N3.5 del cliente, ognuna sulla dichiarazione più recente che ne copre la data; dal 90 % il
registro mostra l'avviso.
6. **Moduli.** Intrastat è nel modulo **INTRA**; le dichiarazioni d'intento nel modulo base **CORE**, perché
riguardano la normale fatturazione.
## Conseguenze
- Il plafond è sempre coerente con le fatture, senza contatori da mantenere a mano; il costo è un ricalcolo per
cliente a ogni conferma di una vendita in N3.5.
- Il gruppo *dichiarazione d'intento* dei dati fiscali del cliente resta come specchio; il registro è la fonte.
- La trasmissione telematica (Dogane, Agenzia delle Entrate) resta fuori da Khaemhat.
+57
View File
@@ -0,0 +1,57 @@
# ADR 0043 - Ratei e risconti, chiusura guidata e bilancio
- **Stato:** accettata
- **Data:** 2026-11-13
- **Modifica:** SPEC §11.7, §14; milestone M10, issue #84, #85, #86, #87; mockup 050 e 051
## Contesto
SPEC §11.7 chiede ratei e risconti, differenze di cambio, la chiusura dell'esercizio guidata in passi ripetibili, la
riapertura, le stampe definitive, il bilancio CEE con riclassificato e indici e l'esportazione per il commercialista.
La chiusura scrive molte registrazioni che devono poter essere tolte finché i libri non sono definitivi; il bilancio
deve leggere i saldi dell'anno anche dopo la chiusura dei conti.
## Decisione
1. **Ratei e risconti per giorni.** `AccrualDeferral` conserva tipo, conto, importo e periodo di competenza; la
rettifica è la parte del periodo fuori dall'esercizio (risconti) o dentro (ratei), in giorni. I risconti si
propongono dalle fatture di acquisto registrate sui conti di costi tipicamente a cavallo dell'anno
(`IClosingRules.PrepaidCandidates`) con un periodo di un anno dalla data: l'utente controlla il periodo.
2. **Differenze di cambio sul residuo.** Le partite aperte in valuta si valutano al cambio dell'ultimo giorno
dell'anno sul **residuo** attuale della partita, non su quello al 31/12: per la chiusura fatta a inizio anno nuovo
la differenza è un'approssimazione accettata e documentata.
3. **Nove passi in ordine.** `ClosingService` esegue controlli, ammortamenti (ADR 0041), ratei e risconti, rimanenze
al costo medio ponderato, accantonamenti (svalutazione crediti 0,5 %, art. 106 TUIR; TFR stimato come retribuzioni
/ 13,5 meno quanto già accantonato), chiusura dei conti economici con il risultato a patrimonio, chiusura dei conti
patrimoniali per conto e soggetto, apertura dell'esercizio successivo con lo storno di ratei e risconti, stampe
definitive. Ogni registrazione ha origine `Closing` (o `FixedAsset`, `Accrual`, `ExchangeDifference`) e il numero
del passo, così l'ultimo passo eseguito si **ripete** o si **annulla** togliendo esattamente le sue scritture
(prima i riferimenti, poi le registrazioni, per le chiavi esterne).
4. **Il passo 9 è il punto di non ritorno.** Rende definitive tutte le registrazioni dell'anno (numerazione del
libro giornale) e conserva i PDF di libro giornale, registri IVA, registro cespiti e bilancio CEE. Non si annulla.
Le stampe dei registri IVA nella chiusura sono quelle dell'anno: vidimazione e numerazione delle pagine restano
quelle della pagina IVA. Dopo il passo 9 il **blocco** porta l'esercizio a `Closed` e lo rende di sola lettura.
5. **Conti del pacchetto.** I conti usati (rimanenze, ratei e risconti, fondi, conti di chiusura e apertura,
risultato) sono in `IClosingRules.Accounts` del pacchetto italiano e corrispondono al piano *PMI standard*. Il
risultato si riapre nel conto *utile (perdita) dell'esercizio* (`10.02.002`); la destinazione dell'utile è una
registrazione dell'utente dopo l'approvazione.
6. **Bilancio dai saldi mappati.** `CeeSchemaIt` (`IFinancialStatementsSchema`) descrive le voci degli art. 2424 e
2425 c.c., l'abbreviato (2435-bis) e il micro (2435-ter, con le voci dell'abbreviato), e le riclassificazioni
finanziaria e a valore aggiunto. Ogni conto porta la voce ordinaria; la natura del conto dice in quale prospetto
va. `FinancialStatementsService` **esclude le scritture dei passi 6 e 7**, così un esercizio chiuso mostra i suoi
saldi; segnala i conti con saldo senza voce. Gli indici sono undici, con formula e anno precedente.
7. **Esportazione semplice.** L'export per il commercialista è uno ZIP di cinque CSV (piano dei conti, bilancio di
verifica, movimenti, stato patrimoniale, conto economico) separati da punto e virgola: nessun formato proprietario
di software terzi.
8. **Prova di accettazione.** Il test di integrazione chiude l'anno demo su SQLite e PostgreSQL: bilancio quadrato
prima e dopo l'assestamento, conti a zero dopo il passo 7, apertura quadrata con il patrimonio uguale all'anno
precedente, stampe PDF, blocco ed export.
## Conseguenze
- Una correzione dopo un passo avanzato richiede di annullare i passi a ritroso: è più lungo ma ogni stato intermedio
resta coerente e verificabile.
- L'annullamento del passo 2 toglie tutti gli ammortamenti dell'anno (ADR 0041).
- Il TFR è una stima utile solo se le paghe non lo accantonano già; con le paghe esterne la chiusura non aggiunge
nulla.
- Il libro inventari non è tra le stampe: arriva con i report (M13).
@@ -0,0 +1,54 @@
# ADR 0044 - Schermate senza PNG, banche senza elenco, canali SDI rimandati
- **Stato:** accettata
- **Data:** 2026-11-16
- **Modifica:** emendamento E4 di `CLAUDE.md`; ADR 0011, 0026, 0027 punto 6, 0028 punto 7, 0040; issue #35, #45, #78
## Contesto
Tre issue aspettavano qualcosa dal titolare:
- **#35:** i PNG ad alta risoluzione delle 66 schermate che hanno solo la miniatura.
- **#45:** una fonte con licenza compatibile per l'elenco delle banche ABI/CAB.
- **#78:** la scelta degli intermediari SDI, l'accreditamento SdICoop e una casella PEC di prova.
Il 2026-11-16 il titolare ha risposto su tutte e tre:
- **#35:** il materiale consegnato è tutto quello che esiste. Sono 22 schermate ad alta risoluzione più la galleria,
e nessun'altra fonte (repository, cartella privata, allegati delle issue) ne contiene altre.
- **#45:** rinuncia ai dati precaricati delle banche. Indicherà una fonte se e quando la troverà.
- **#78:** intermediari, SdICoop e PEC reale sono lasciati da parte per ora.
## Decisione
1. **Le miniature sono la specifica finale delle schermate senza PNG.** Nessun PNG ad alta risoluzione verrà
aggiunto alle 66 schermate *solo miniatura*. Le schermate si disegnano in base a tre fonti:
- la miniatura, che fissa disposizione, gruppi e colonne;
- SPEC §10-§12;
- i componenti dell'applicazione già costruiti, con i token di `mockup.css` e i mattoni della schermata più
simile (SPEC §10.1 regola 4).
Dove la miniatura non basta, decide chi sviluppa seguendo lo stile del gestionale, senza chiedere un PNG.
I dettagli scelti così vanno nella pagina wiki della schermata.
2. **Banche senza elenco precaricato.** I dati di base non contengono l'elenco ABI/CAB e `ItalianBankDirectory`
resta vuoto. Dall'IBAN si leggono sempre ABI e CAB. Nome della banca e BIC vengono da un conto dell'azienda
presso la stessa banca, oppure si scrivono a mano (ADR 0027 punto 6). Se il titolare indicherà una fonte con una
licenza che permette di ridistribuirla in un repository pubblico, l'elenco entrerà come nuova versione dei dati di
base, solo in aggiunta (ADR 0026 punto 3).
3. **Canali SDI reali rimandati.** Lo sviluppo continua con i canali simulati dell'ADR 0040. Fino a una scelta del
titolare valgono queste regole:
- i connettori A e B restano generici;
- l'endpoint SdICoop resta disponibile ma non accreditato;
- la PEC si prova contro il server di posta finto dei test.
L'issue #78 resta aperta nel backlog, senza milestone e senza l'etichetta `Status/In attesa utente`.
## Conseguenze
- Le issue #35 e #45 si chiudono. L'issue #78 non blocca nessuna milestone.
- Le schermate di M11-M14 non aspettano materiale dal titolare. Il rischio è che una di esse si discosti dall'idea
originale in un dettaglio che la miniatura non mostra; si corregge con un'issue quando il titolare la vede.
- Chi usa più conti presso banche diverse scrive nome e BIC una volta per banca. La compilazione automatica li
riprende poi dal conto dell'azienda.
- Prima di usare in produzione la fatturazione elettronica serve comunque una PEC o un intermediario reale. La guida
*Fatturazione elettronica* della wiki lo dice già.
+4 -4
View File
@@ -20,10 +20,10 @@ I mockup sono la **specifica visiva vincolante** dell'interfaccia (SPEC §10.1).
| `thumbs/` | Miniature 401x241 di **tutte** le 88 schermate, ritagliate dalla galleria, con lo stesso nome file |
| `mockup.css` | Token (`--kh-*`) e classi dei componenti usati per disegnare i mockup |
Le schermate segnate *solo miniatura* non sono ancora disponibili in alta risoluzione: si lavora con la miniatura,
`mockup.css` e le descrizioni di SPEC §10-§12 (regola 4). La richiesta dei PNG mancanti è tracciata da un'issue con
etichetta `Status/In attesa utente` nella milestone M3. Quando un PNG arriva va copiato in `png/` con lo stesso nome
e questa tabella va aggiornata.
Le schermate segnate *solo miniatura* non hanno e non avranno un PNG ad alta risoluzione (ADR 0044, issue #35): si
lavora con la miniatura, `mockup.css`, le descrizioni di SPEC §10-§12 e i mattoni della schermata più simile
(regola 4). I dettagli che la miniatura non mostra si decidono seguendo la grafica dei componenti già costruiti e si
descrivono nella pagina wiki della schermata.
Alcuni mockup contengono dettagli superati dagli emendamenti di `CLAUDE.md` (ad esempio 085 mostra ancora `ghcr.io`
come registro): in quei casi prevale l'emendamento (registro pacchetti di Gitea).
+123 -121
View File
@@ -1,178 +1,180 @@
# Acquisti
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M6)
> **Modulo di licenza:** CORE (XML delle autofatture e canale SDI con EINV, registrazione con ACCT) · **Permessi principali:** famiglia `purchases.*` (codici esatti definiti in sviluppo) · **Specifica:** SPEC §11.3, §11.5
> **Stato:** completa per la versione 0.6 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.6.0 (M6)
> **Modulo di licenza:** CORE (XML delle autofatture con EINV, registrazione contabile con ACCT) · **Permessi principali:** `purchases.order.*` (ordini fornitore), `inventory.entry.*` (DDT fornitore), `purchases.invoice.*` (fatture, note di credito, import, autofatture) · **Specifica:** SPEC §11.3, §11.5, ADR 0035
Il modulo **Acquisti** copre il ciclo passivo: **ordini ai fornitori** (anche generati dalla proposta di riordino),
**DDT di carico** con controllo delle quantità ricevute, **fatture di acquisto** con protocollo IVA e conti per riga,
**note di credito** dei fornitori, **import delle fatture passive** XML/P7M ricevute dallo SDI e le **autofatture e
integrazioni** (TD16-TD29) per reverse charge e acquisti dall'estero.
Il modulo **Acquisti** copre il ciclo passivo: **ordini ai fornitori** (anche dalla proposta di riordino),
**ricevimento della merce** con il DDT del fornitore, **fatture e note di credito dei fornitori** con il protocollo
IVA, **import delle fatture elettroniche** ricevute (XML, P7M, ZIP) e le **autofatture e integrazioni** (TD16-TD29)
per inversione contabile e acquisti dall'estero.
> **In questa versione** ci sono ordini, ricevimenti, fatture e note di credito fornitore con protocollo, carico a
> magazzino e costo medio, controllo dei prezzi rispetto a ordine e ricevimento, import delle fatture elettroniche e
> autofatture in bozza con la loro scadenza. Dalla 0.7 le fatture e le note fornitore **si contabilizzano** da sole
> con i registri IVA (vedi [Contabilità](Contabilita) e [IVA](IVA)). Dalla 0.8 le fatture fornitore **si pagano** dallo [Scadenzario](Scadenzario), anche con le distinte di bonifici SEPA. Arrivano più avanti: il **file XML** delle autofatture e lo scarico dal canale SDI (M9).
## Dove si trova
Menu **Acquisti** → *Ordini fornitori*, *DDT di carico*, *Fatture di acquisto*, *Import XML SDI*, *Autofatture*.
Menu **Acquisti** → *Ordini fornitori*, *Ricevimenti merce*, *Fatture passive*, *Importa fatture*, *Autofatture*.
Le maschere sono quelle comuni a tutti i documenti (toolbar, intestazione, schede, righe con castelletto e totali):
vedi [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie) e [Vendite](Vendite) per il motore documenti.
Le maschere sono quelle comuni a tutti i documenti (toolbar, intestazione, schede, righe con castelletto e totali,
trasformazioni, stampa, allegati): vedi [Vendite](Vendite) per il funzionamento del motore documenti e
[Interfaccia e scorciatoie](Interfaccia-e-scorciatoie) per la tastiera.
```
Proposta di riordino ──► Ordine fornitore ──ricevi merce──► DDT di carico ──registra fattura──► Fattura di acquisto
▲
Fattura passiva XML/P7M (SDI) ──import──┘ (abbinamento all'ordine o al DDT)
Proposta di riordino ──► Ordine fornitore ──Crea DDT fornitore (carico)──► Ricevimento ──Crea Fattura fornitore──► Fattura
▲
Fattura elettronica XML / P7M / ZIP ──Importa fatture──► Fattura in bozza ─┘
Fattura di un fornitore estero o in reverse charge ──Crea autofattura──► Autofattura / integrazione (TD16-TD29)
```
## Ordini fornitori
![031 · Ordine fornitore generato dalla proposta di riordino](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/031-ordine-fornitore.png)
*Mockup 031 — ordine fornitore confermato, nato dalla proposta di riordino, con il pannello Origine del fabbisogno (anteprima ridotta).*
Un **ordine fornitore** (`OF`) dice al fornitore che cosa ti serve; non muove il magazzino ma, una volta
**confermato**, aumenta l'**ordinato** degli articoli finché non arriva la merce (vedi [Magazzino](Magazzino)).
Azioni: **Invia al fornitore** (e-mail con il PDF dell'ordine), **Ricevi merce (DDT carico)**, **Chiudi residuo**.
- Scegliendo il fornitore si applicano le sue condizioni (pagamento, banca, porto, valuta).
- Scegliendo un articolo, Khaemhat propone il **prezzo del fornitore** dalla scheda articolo (*Fornitori*).
- Gli ordini nascono a mano, dalla **proposta di riordino** (un ordine in bozza per fornitore, vedi
[Magazzino](Magazzino#proposta-di-riordino)) o copiando un altro documento.
- Quando la merce arriva, **Crea DDT fornitore (carico)** porta le righe ancora da ricevere nel ricevimento: puoi scegliere
righe e quantità, così un ordine può essere ricevuto in più volte. Lo stato diventa *Evaso in parte* ed *Evaso*;
**Chiudi** chiude un residuo che non arriverà più.
- L'intestazione mostra la **data prevista** di consegna, calcolata come data dell'ordine + **lead time** del
fornitore, e lo stato di ricevimento (*Ricevuto 0%*…).
- Le righe riportano il **codice del fornitore** per l'articolo; il prezzo proposto è quello del fornitore.
- Il pannello **Origine del fabbisogno** spiega perché si ordina: sottoscorta, impegni da ordini clienti, lotto di
riordino.
- Schede: *Righe*, *Testata*, *Totali*, *Ricevimenti*, *Note*, *Allegati*, *Collegamenti*.
- Un ordine confermato aggiorna l'**ordinato** degli articoli (vedi [Magazzino](Magazzino)).
![Khaemhat 0.6.0 · ricevimento della merce](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-ricevimento.png)
Gli ordini nascono a mano, dalla **proposta di riordino** (un ordine in bozza per fornitore, vedi
[Magazzino](Magazzino)) o dall'azione **Ordina a fornitore** di un ordine cliente.
## Ricevimenti merce (DDT fornitore)
## DDT di carico
Il **DDT fornitore (carico)** (`DDTF`) registra la merce arrivata. Non ha un numero interno: nella testata scrivi il
**numero e la data del DDT del fornitore**, che lo identificano (nell'elenco compare come *Senza numero*).
![032 · DDT di carico con controllo quantità ricevute](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/032-ddt-di-carico.png)
*Mockup 032 — ricevimento con confronto ordinato/ricevuto, riga con 20 pezzi mancanti e aggiornamento del costo medio (anteprima ridotta).*
1. Dall'ordine premi **Crea DDT fornitore (carico)**, oppure crea un ricevimento e richiama l'ordine.
2. Controlla le **quantità ricevute** riga per riga e il **deposito** di arrivo.
3. **Conferma**: la merce viene **caricata a magazzino** con la causale `CAR` e aggiorna **costo medio** e **ultimo
costo** degli articoli; l'ordine segna le quantità evase.
Il **DDT di carico** registra la merce ricevuta. Azioni: **Registra fattura da questo DDT**, **Stampa etichette**,
**Riapri**.
Un ricevimento confermato resta modificabile finché non è fatturato; dal ricevimento **Crea Fattura fornitore**
prepara la fattura con le stesse righe.
1. Dall'ordine fornitore premi **Ricevi merce** oppure crea un DDT di carico e usa **Evadi da…** per richiamare
l'ordine.
2. Indica numero e data del **DDT del fornitore**.
3. Conta la merce: per ogni riga inserisci la quantità **ricevuta**; si può **scansionare l'EAN o il codice
fornitore** per contare. La colonna *Controllo* segnala le differenze (*OK*, *Mancanti 20*…).
4. **Conferma**: la merce viene **caricata a magazzino** (causale *Carico da fornitore*, deposito indicato), si
aggiornano **ultimo costo** e **costo medio ponderato** dell'articolo.
## Fatture passive
Se arriva meno del previsto, il **residuo** resta aperto sull'ordine; se non arriverà più si chiude con **Chiudi
residuo**. Un messaggio sotto le righe riassume differenze e variazioni del costo medio.
![Khaemhat 0.6.0 · fattura fornitore con differenza di prezzo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-fattura-differenze.png)
## Fatture di acquisto
![033 · Fattura di acquisto da XML con conti e centri di costo per riga](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/033-fattura-di-acquisto.png)
*Mockup 033 — fattura di acquisto in bozza nata da XML, con protocollo, flag Verifica prezzi, righe con conto e centro di costo, castelletto con IVA detraibile (anteprima ridotta).*
Azioni: **Registra (protocolla)**, **Contabilizza**, **Confronta con ordine**, **Apri XML**.
La **fattura fornitore** (`FF`) e la **nota di credito fornitore** (`NCF`) registrano i documenti del fornitore.
| Dato | Descrizione |
|---|---|
| **Data di registrazione** e **data/numero del documento** del fornitore | la registrazione determina il periodo IVA |
| **Protocollo** | numero progressivo del registro IVA acquisti (es. `ACQ/2026/000613`), assegnato alla registrazione |
| **Conto e centro di costo per riga** | ogni riga ha il proprio conto di costo e centro di costo (proposti da articolo, categoria o fornitore) |
| **Indetraibilità** | codici IVA con indetraibilità parziale o totale (es. telefonia 50%): il castelletto mostra imponibile, imposta e quota **detraibile** |
| **Ritenute e cassa** | per i professionisti: ritenuta d'acconto, cassa previdenza; il totale mostra il **netto a pagare** |
| **Registrazione contabile** | scheda con l'anteprima della registrazione (con modulo Contabilità) |
| **N. documento fornitore** e **data** | numero e data scritti dal fornitore (nella testata) |
| **Data** | data di registrazione: decide il periodo IVA |
| **Protocollo** | numero progressivo del registro IVA acquisti (numeratore `PRA`), assegnato alla **conferma**; nell'elenco compare nella colonna *Protocollo* |
| **Righe** | articoli, righe descrittive e spese con il codice IVA di ogni riga; per i professionisti ritenuta d'acconto e cassa come nelle vendite |
| **Scadenze** | calcolate dal pagamento del fornitore |
Schede: *Righe*, *Testata*, *Totali*, *Scadenze*, *Ritenute e cassa*, *Registrazione contabile*, *Note*,
*Allegati*, *Collegamenti*.
La fattura nasce dal ricevimento (**Crea Fattura fornitore**), dall'ordine (per servizi o merce senza DDT), dall'**import
della fattura elettronica** (vedi sotto) o a mano. **Conferma** assegna il protocollo e la rende definitiva; una
fattura confermata si corregge con una **nota di credito fornitore** (**Crea Nota di credito fornitore**).
**Registra (protocolla)** assegna il protocollo e rende la fattura definitiva; **Contabilizza** crea la registrazione
(automatica alla conferma o in batch, secondo le preferenze). La fattura può nascere:
**Magazzino.** Una fattura di merce senza DDT carica il magazzino alla conferma; una fattura nata da un ricevimento
non carica di nuovo, ma il suo **prezzo corregge il costo** del carico. La nota di credito fornitore scarica la merce
resa (causale `RESF`).
- dal **DDT di carico** (**Registra fattura da questo DDT**), che la collega ai carichi;
- dall'**import XML** (vedi sotto);
- a mano, ad esempio per fatture cartacee o estere.
**Controllo dei prezzi.** Se una riga della fattura ha un prezzo diverso da quello dell'ordine o del ricevimento da
cui viene, sopra le righe compare un avviso con la differenza totale e, riga per riga, il prezzo atteso e quello
fatturato. È un avviso: decidi tu se registrare la fattura o chiedere una nota di credito.
Le **note di credito dei fornitori** si registrano allo stesso modo e chiudono le partite collegate.
## Importare le fatture elettroniche
## Import delle fatture passive XML/P7M
![Khaemhat 0.6.0 · import delle fatture passive](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-importa-fatture.png)
![034 · Import fatture passive XML/P7M](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/034-import-xml-sdi.png)
*Mockup 034 — quattro file in import (pronto, con ritenuta e cassa, fornitore da creare, duplicato) e mappatura delle righe sull'ordine con differenza di prezzo (anteprima ridotta).*
**Acquisti → Importa fatture** (o il link nell'elenco delle fatture passive) registra in bozza le fatture ricevute
dallo SDI o dal tuo intermediario. Dalla 0.9 le fatture che arrivano dai canali SDI si registrano anche da
**Fatturazione elettronica → Fatture ricevute**, con lo stesso import.
1. Carica i file con **Carica XML / P7M / ZIP**, oppure **Leggi inbox** (cartella di ingresso dell'istanza) o
**Scarica dal canale SDI** (con il modulo Fatturazione elettronica).
2. Per ogni file Khaemhat legge fornitore, numero, data, tipo documento (TD) e totale e mostra un **esito**:
*Pronto*, *Fornitore da creare*, *Duplicato*, oppure avvisi (ad esempio *Ritenuta 20% · cassa 4%*).
3. Il **fornitore** viene riconosciuto da **partita IVA o codice fiscale**; se non esiste si crea al volo dai dati
dell'XML.
4. **Mappatura righe**: ogni riga XML viene abbinata a un articolo cercando, in ordine, il **codice del fornitore**,
l'**EAN** e la **descrizione** (ricerca approssimata). Le righe non abbinate diventano descrittive o si abbinano a
mano.
5. **Abbina a ordine**: confronta prezzi e quantità con l'ordine fornitore; le differenze sono evidenziate (es.
*+3,4%*).
6. **Salva bozza** o **Registra fattura di acquisto**. Se ci sono differenze la fattura nasce **in bozza** con il
flag *Verifica prezzi*.
1. **Caricamento**: scegli uno o più file: **XML FatturaPA**, file firmati **.p7m** o archivi **ZIP** che li
contengono (fino a 50 MB per file). I file che non sono fatture elettroniche leggibili sono elencati a parte con il
motivo.
2. **Controllo**: per ogni fattura vedi fornitore (nuovo o già in anagrafica), numero, data, tipo, totale e un esito:
*Pronta*, oppure *Già registrata* (stesso fornitore, stesso numero, stesso anno), *Non è un acquisto* (per esempio
un'autofattura emessa dall'azienda stessa), *Totale diverso* (il totale del file non torna con le righe), *Firma non
verificata*, *Sconto sul totale*. **Leggi** mostra righe, riepilogo IVA e pagamento del file.
3. **Registrazione**: spunta le fatture e premi **Registra in bozza**. Per ognuna Khaemhat:
- trova il **fornitore** dalla partita IVA o dal codice fiscale, o lo **crea** dai dati del file;
- crea una **fattura fornitore** (tipi TD01, TD02, TD03, TD05, TD06, TD24-TD27) o una **nota di credito fornitore**
(TD04, TD08) in bozza, con numero e data del fornitore e la causale nelle note;
- abbina ogni riga a un **articolo** cercando il **codice del fornitore** (scheda articolo, *Fornitori*), poi l'**EAN**,
poi il **codice articolo**; le righe non abbinate diventano righe libere con descrizione, prezzo e IVA;
- riporta gli **sconti** percentuali come sconto di riga e gli altri nel prezzo netto;
- sceglie il **codice IVA** dell'azienda con la stessa aliquota e natura;
- **allega il file** originale alla fattura (scheda *Allegati*, tipo *Fattura elettronica*).
L'**XML originale** viene allegato alla fattura; per i file **P7M** la **firma CAdES** viene verificata. I file già
importati sono riconosciuti come duplicati.
Le fatture importate restano **in bozza**: controllale e confermale per protocollarle. Se un codice IVA manca (per
esempio una natura non usata finora), aggiungilo in [Tabelle azienda](Tabelle-azienda) → *Codici IVA* e ripeti
l'import.
## Autofatture e integrazioni (TD16-TD29)
![035 · Autofattura / integrazione reverse charge](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/035-autofattura-integrazione.png)
*Mockup 035 — integrazione TD17 per servizi da un fornitore estero: IVA integrata, effetto neutro, registri RC vendite e acquisti, scadenza di invio allo SDI (anteprima ridotta).*
![Khaemhat 0.6.0 · integrazione da emettere su una fattura intracomunitaria](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-fattura-autofattura.png)
Quando l'IVA è dovuta dall'acquirente (inversione contabile) l'azienda deve **integrare** la fattura ricevuta o
emettere un'**autofattura**, trasmettendola allo SDI. In Khaemhat questi documenti stanno in **Acquisti →
Autofatture** e nascono dalla fattura di acquisto d'origine.
Quando l'IVA è dovuta da chi compra (inversione contabile, acquisti dall'estero) l'azienda deve **integrare** la
fattura ricevuta o emettere un'**autofattura** e trasmetterla allo SDI. Khaemhat lo riconosce da solo dalla fattura
fornitore (paese del fornitore, beni o servizi, natura IVA delle righe) e mostra sopra le righe quale documento serve e **entro quando**:
| Codice | Documento | Quando si usa |
| Tipo | Quando | Scadenza |
|---|---|---|
| **TD16** | Integrazione fattura reverse charge interno | acquisti nazionali in inversione contabile (art. 17 c.6 DPR 633/72, es. subappalto edile) |
| **TD17** | Integrazione/autofattura per acquisto di servizi dall'estero | servizi da fornitori UE ed extra-UE |
| **TD18** | Integrazione per acquisto di beni intracomunitari | beni da fornitori UE |
| **TD19** | Integrazione/autofattura per acquisto di beni ex art. 17 c.2 DPR 633/72 | beni già in Italia acquistati da soggetti non residenti |
| **TD20** | Autofattura per regolarizzazione e integrazione delle fatture | regolarizzazione nei casi previsti (definizione aggiornata dalle specifiche v1.9) |
| **TD21** | Autofattura per splafonamento | acquisti oltre il plafond dell'esportatore abituale |
| **TD22** | Estrazione beni da deposito IVA | |
| **TD23** | Estrazione beni da deposito IVA con versamento dell'IVA | |
| **TD28** | Acquisti da San Marino con IVA | fatture cartacee con IVA da operatori sammarinesi |
| **TD29** | Comunicazione per omessa o irregolare fatturazione | introdotto con le specifiche v1.9 (dal 1° aprile 2025) |
| **AF16** (TD16) | inversione contabile interna: righe con natura N6.x (subappalti, rottami, cellulari…) | 15 del mese dopo il ricevimento |
| **AF17** (TD17) | servizi da un fornitore estero, UE o extra UE | 15 del mese dopo |
| **AF18** (TD18) | beni da un fornitore di un altro Paese UE | 15 del mese dopo |
| **AF19** (TD19) | beni già in Italia comprati da un soggetto non residente (art. 17 c.2) | 15 del mese dopo |
| **AF28** (TD28) | acquisti da San Marino con IVA in fattura | 15 del mese dopo |
| **AF20**, **AF29** | regolarizzazione di una fattura non ricevuta o irregolare | 90 giorni |
| AF21, AF22, AF23 | splafonamento, estrazione da deposito IVA | a mano, quando servono |
Come funziona (esempio TD17, mockup 035):
![Khaemhat 0.6.0 · integrazioni da emettere](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-autofatture-in-attesa.png)
1. La fattura estera viene registrata negli acquisti.
2. Si crea l'integrazione: le righe sono **riprese dalla fattura estera** con imponibile e aliquota; Khaemhat
calcola l'**IVA integrata**.
3. **Conferma e genera XML**: nell'XML il **fornitore estero** compare come cedente/prestatore e la **nostra azienda**
come cessionario/committente.
4. La registrazione va contemporaneamente nel **registro IVA vendite RC** e nel **registro IVA acquisti RC**: l'effetto
è **neutro** (IVA a debito = IVA a credito, salvo indetraibilità). Il pannello *Effetto contabile* mostra le due
righe.
5. L'XML va inviato **entro il 15 del mese successivo**: Khaemhat mostra la scadenza nel documento e un promemoria
nella dashboard.
**Acquisti → Autofatture** elenca in alto le **integrazioni da emettere**, la scadenza più vicina per prima. **Crea
autofattura** (qui o nella fattura fornitore) prepara il documento in bozza: le righe della fattura con il **codice IVA
ordinario** al posto della natura, il numero e la data della fattura del fornitore come documento collegato, la data
di oggi. Controllalo ed **emettilo**: prende il numero dal numeratore `AUT` delle autofatture.
Schede: *Righe*, *Testata*, *Registrazione IVA*, *XML SDI*, *Collegamenti*. Le definizioni ufficiali dei codici sono
in [Fiscalità italiana](Fiscalita-italiana).
Il **file XML** dell'autofattura (con il fornitore come cedente e l'azienda come cessionario) e l'invio allo SDI
si fanno dalla vista *Autofatture* della [Fatturazione elettronica](Fatturazione-elettronica) (dalla 0.9); la doppia registrazione nei registri IVA
vendite e acquisti si fa da sola alla conferma dell'autofattura (dalla 0.7, vedi [IVA](IVA)). Le definizioni ufficiali dei codici TD sono in
[Fiscalità italiana](Fiscalita-italiana).
## Fatture da fornitori forfettari
Le fatture dei fornitori in **regime forfettario** non hanno IVA (natura N2.2 nell'XML del fornitore) e riportano il
**bollo** quando dovuto; non sono soggette a ritenuta d'acconto. Nella scheda del fornitore il flag *Regime
forfettario* (gruppo *Ritenute e contributi*) indica questa situazione; i controlli automatici sulla fattura
importata saranno definiti in sviluppo.
Le fatture dei fornitori in **regime forfettario** non hanno IVA (natura N2.2) e riportano il **bollo** quando dovuto;
non sono soggette a ritenuta. All'import la riga prende il codice IVA dell'azienda con natura N2.2; non serve
nessuna autofattura.
## Stati
Ordini e DDT di carico seguono gli stati del motore documenti: *Bozza*, *Confermato*, *Ricevuto parzialmente* /
*Ricevuto*, *Chiuso*, *Annullato*. Le fatture di acquisto sono *Bozza* finché non vengono **registrate
(protocollate)**; i badge indicano anche *Da XML SDI*, *Verifica prezzi*, *Caricato a magazzino*, *Da fatturare*.
| Documento | Stati |
|---|---|
| Ordine fornitore, ricevimento | *Bozza*, *Confermato*, *Evaso in parte*, *Evaso*, *Chiuso*, *Annullato* |
| Fattura e nota di credito fornitore | *Bozza*, *Confermato* (protocollata), *Annullato* |
| Autofattura | *Bozza*, *Emessa* e, con la fatturazione elettronica, gli stati dello SDI |
## Permessi e licenza
Ordini, carichi, fatture di acquisto e import da file sono nel modulo **CORE**. La generazione e l'invio dell'XML
delle autofatture e lo scarico dal canale SDI richiedono **EINV**; la registrazione contabile e i registri IVA
**ACCT**; i pagamenti **FIN**. Costi e margini sono visibili solo a chi ha il permesso `items.cost.read`.
Ordini, ricevimenti, fatture, import e autofatture sono nel modulo **CORE**. Gli ordini richiedono
`purchases.order.read`/`write`; i ricevimenti, che muovono il magazzino, `inventory.entry.read`/`write` (e
`inventory.entry.post` per confermarli); fatture, note di credito, import e autofatture `purchases.invoice.read`/`write`.
L'XML delle autofatture richiederà **EINV**, la registrazione contabile **ACCT**, i pagamenti **FIN**. Costi e margini
sono visibili solo con `items.cost.read`.
## Domande frequenti
- **L'import segna "Duplicato".** La fattura risulta già importata: non va registrata una seconda volta (il
criterio esatto di riconoscimento sarà definito in sviluppo).
- **Una riga dell'XML non trova l'articolo.** Aggiungi il codice del fornitore nella scheda articolo (*Fornitori*):
la volta successiva l'abbinamento sarà automatico.
- **Ho ricevuto meno merce di quella ordinata.** Conferma il DDT con la quantità ricevuta: il residuo resta aperto
sull'ordine.
- **L'import dice "Già registrata".** Lo stesso fornitore ha già un documento con quel numero nello stesso anno: non
va registrata due volte.
- **Una riga dell'XML non trova l'articolo.** Aggiungi il codice che usa il fornitore nella scheda articolo
(*Fornitori*, codice fornitore): dalla volta successiva l'abbinamento è automatico.
- **Ho ricevuto meno merce di quella ordinata.** Conferma il ricevimento con la quantità arrivata: il residuo resta
aperto sull'ordine e l'ordinato degli articoli lo tiene in conto.
- **La fattura ha un prezzo diverso dall'ordine.** L'avviso sopra le righe lo segnala; se la fattura è giusta
confermala e il costo medio si allinea al prezzo fatturato.
- **Non vedo l'avviso dell'autofattura.** Compare sulle fatture di fornitori esteri o con righe in natura N6.x,
finché non c'è un'autofattura collegata. L'elenco *Integrazioni da emettere* mostra solo le fatture **confermate**.
## Pagine correlate
+56 -17
View File
@@ -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**.
![024 · Allegati del documento e generazione file](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/024-allegati-e-file-generati.png)
*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 · allegati](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/allegati-pannello.png)
*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 · anteprima di un XLSX](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/allegati-anteprima.png)
*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
![025 · Anteprima di stampa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/025-anteprima-stampa-pdf.png)
*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 · anteprima di stampa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/stampa-anteprima.png)
*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
+106 -69
View File
@@ -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,69 @@ i controlli e i valori proposti: codice destinatario SDI, split payment, bollo,
![012 · Clienti · radar](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/012-clienti-radar.png)
*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 · radar dei clienti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/anagrafiche-radar.png)
*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 i report dei clienti (M12); lo scaduto di un cliente si vede già nello
[Scadenzario](Scadenzario) (*Estratto conto*).
- 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
![014 · Cliente · scheda anagrafica a gruppi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/014-cliente-scheda.png)
*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 · scheda cliente](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/anagrafiche-scheda.png)
*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 +110,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 +119,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 +147,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 +160,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 +215,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.
+151 -90
View File
@@ -1,153 +1,214 @@
# 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 dalla 0.6.0, 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 · radar degli articoli](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/articoli-radar.png)
*Khaemhat 0.4.0 — il radar dei 120 articoli di esempio con categoria, UM, marca, tipo, costo medio e prezzo base.*
## La scheda articolo
![017 · Articolo · scheda con prezzi, riordino e giacenze](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/017-articolo-scheda.png)
*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 · scheda articolo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/articoli-scheda.png)
*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 calcolano i carichi di magazzino (DDT fornitore, fatture fornitore, esistenze
iniziali, movimenti di carico) dalla versione 0.6.0. Il costo medio è il criterio di valorizzazione del magazzino
(vedi [Magazzino](Magazzino#costo-medio-e-valorizzazione)).
- 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 partecipa a movimenti, giacenze per deposito (*Giacenza, Impegnato,
Ordinato, Disponibile, Valore*) e **proposta di riordino** (vedi [Magazzino](Magazzino)). **Scorta minima**, **punto
di riordino** e **lotto di riordino** decidono lo stato dell'articolo nelle giacenze e la quantità proposta; il
**fornitore preferito** della scheda *Fornitori*, con prezzo, minimo d'ordine e lead time, è quello a cui la
proposta ordina.
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
![018 · Listini](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/018-listini.png)
*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 · griglia dei listini](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/listini-griglia.png)
*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
+7 -2
View File
@@ -50,7 +50,7 @@ Esempi presenti nel mockup (dati dimostrativi):
| `dunning` | Solleciti di pagamento | Procedura | `0 9 * * 1` |
| `vat-reminder` | Promemoria liquidazione IVA | Notifica | mensile |
| `ecb-rates` | Aggiornamento cambi BCE | Procedura | nei giorni feriali |
| `sdi-inbox` | Lettura inbox e canali SDI | Procedura | ogni 30 minuti |
| `einvoice.poll` | Lettura dei canali SDI (notifiche e fatture ricevute) | Procedura | `*/15 * * * *` |
| `report-sales-weekly` | Report vendite settimanale a direzione | Report via e-mail | `0 7 * * 1` |
| `reorder` | Proposta di riordino | Procedura | `0 6 * * *` |
| `stock-check` | Verifica coerenza giacenze | Verifica | settimanale |
@@ -137,13 +137,18 @@ 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`):
Nella versione 0.7.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 |
| `system.attachments-trash` | svuota il cestino degli allegati oltre i giorni di conservazione | ogni notte alle 03:45 |
| `system.ecb-rates` | scarica i cambi di riferimento della BCE (richiede la rete) | nei giorni feriali alle 16:30 |
| `inventory.rebuild` | ricostruisce il magazzino di ogni azienda attiva dai documenti in vigore (vedi [Magazzino](Magazzino#ricostruzione)) | la domenica alle 02:15 |
| `ledger.recurring` | crea le registrazioni ricorrenti arrivate alla loro data in ogni azienda con la contabilità (vedi [Contabilità](Contabilita)) | ogni giorno alle 05:00 |
| `finance.dunning` | invia per e-mail e PEC i solleciti dei livelli segnati *Automatico* in ogni azienda con il modulo FIN (vedi [Scadenzario](Scadenzario#solleciti); richiede la rete) | nei giorni feriali alle 07:00 |
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,
+101 -72
View File
@@ -1,113 +1,142 @@
# Cespiti
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M10)
> **Modulo di licenza:** ASSET · **Permessi principali:** `assets.asset.write`, `assets.depreciation.post`, `assets.asset.dispose` · **Specifica:** SPEC §11.7, §14
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** ASSET · **Permessi principali:** `assets.asset.read` (registro, piano, stampe),
> `assets.asset.write` (cespiti, categorie, dismissioni), `assets.depreciation.post` (registrare e annullare gli
> ammortamenti) · **Specifica:** SPEC §11.7, §14, ADR 0041
## A cosa serve
Il modulo Cespiti tiene il **registro dei beni ammortizzabili**: anagrafica dei beni, categorie con coefficienti,
piano di ammortamento civilistico e fiscale, calcolo e contabilizzazione delle quote annuali, dismissioni con
plusvalenza o minusvalenza, rivalutazioni e stampa del registro.
Il modulo Cespiti tiene il **registro dei beni ammortizzabili**: le categorie con i coefficienti ministeriali, i beni
con il piano di ammortamento civilistico e fiscale, la registrazione delle quote di fine anno, le dismissioni con la
plusvalenza o la minusvalenza e la stampa del **registro dei beni ammortizzabili** (libro cespiti).
## Dove si trova
Menu laterale **Cespiti**, con le voci **Registro cespiti**, **Ammortamenti**, **Categorie**.
## Schermate
![048 · Registro cespiti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/048-cespiti-registro.png)
*Mockup 048 — registro dei beni con categoria, coefficiente, data di acquisto, costo storico, fondo, residuo, quota dell'anno e stato; sotto, il piano di ammortamento del cespite selezionato (civilistico e fiscale) e la scheda con conti, fattura di acquisto, deducibilità e ubicazione (anteprima ridotta)*
Menu laterale **Cespiti**, con tre voci: **Registro cespiti**, **Ammortamenti**, **Categorie**. Gli ammortamenti si
registrano anche dal passo 2 della [chiusura dell'esercizio](Chiusura-e-bilancio).
## Il registro
| Colonna | Significato |
![Khaemhat 0.10.0 · registro cespiti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/cespiti-registro.png)
*Il registro dell'azienda demo: quattro beni con categoria, aliquota, entrata in funzione, costo storico, fondo e
valore netto; sotto, il piano di ammortamento del furgone selezionato e il dettaglio con i movimenti.*
La striscia in alto riassume i cespiti **attivi**, il **costo storico**, il **fondo** e il **valore netto**. Si filtra
per testo (codice, descrizione, matricola), esercizio, categoria e stato. Un clic sulla riga apre sotto:
- il **piano di ammortamento**: per ogni esercizio il fondo iniziale, l'aliquota, la quota civilistica e quella
fiscale, il fondo e il valore netto a fine anno; l'anno scelto nei filtri è evidenziato;
- il **dettaglio**: categoria, data di acquisto, fornitore e documento, ubicazione, fondo fiscale, ultimo esercizio
ammortizzato e l'elenco dei **movimenti** (acquisto, apertura, incremento, rivalutazione, ammortamento,
dismissione); da qui **Modifica**, **Dismetti** ed **Elimina**.
| Stato | Significato |
|---|---|
| **Codice** | automatico, maschera `CESP-{seq:0000}` (es. `CESP-0041`; vedi [Tabelle azienda](Tabelle-azienda)) |
| Descrizione, Categoria, Coeff. | il coefficiente viene dalla categoria |
| Acquisto | data di entrata in funzione / acquisto |
| Costo storico, Fondo, Residuo | valori alla data |
| Quota anno | quota di ammortamento dell'esercizio |
| Stato | *In uso*, *Primo anno (50 %)*, *Limite fiscale raggiunto*, *Ammortizzato*, *Dismesso* (con plus o minusvalenza) |
| **In ammortamento** | il bene ha ancora un valore da ammortizzare |
| **Ammortizzato** | il fondo ha raggiunto il costo (meno l'eventuale valore residuo) |
| **Dismesso** | il bene è uscito dal patrimonio; resta nel registro con il movimento di dismissione |
Filtri per esercizio, categoria e stato. In testa un avviso ricorda se gli ammortamenti dell'anno non sono ancora
contabilizzati. Il pannello **Dati cespite** mostra categoria e coefficiente, **conto cespite**, **conto fondo**,
**conto quota** (ammortamento), fattura di acquisto, percentuale di deducibilità e ubicazione.
## Inserire un cespite
Un cespite nasce di solito dalla **fattura di acquisto** (righe con articolo di tipo *cespite*, vedi
[Acquisti](Acquisti)) oppure si inserisce a mano con **+**.
1. **Registro cespiti → Nuovo cespite**.
2. Scegli la **categoria** (aliquote e conti vengono da lì) e scrivi la descrizione. Il **codice** vuoto prende il
prossimo numero; la matricola e l'ubicazione sono facoltative.
3. Indica **data di acquisto** e **data di entrata in funzione**: l'ammortamento parte dall'anno di entrata in
funzione, che non può precedere l'acquisto.
4. Scrivi il **costo** e, se serve, il valore residuo. Le aliquote civilistica e fiscale vuote seguono la categoria;
compilale solo per il singolo bene.
5. Per un bene acquistato **prima dell'avvio di Khaemhat** indica i **fondi iniziali** (civilistico e fiscale) e
l'**ultimo esercizio già ammortizzato** fuori da Khaemhat: i fondi entrano con la scrittura di apertura dei conti.
Facoltativi anche quantità, fornitore, documento di acquisto, ubicazione e matricola.
6. Salva. Il piano si ricalcola subito.
Un cespite con ammortamenti già registrati non si elimina: si dismette.
## Categorie e coefficienti
Le **categorie** sono caricate con i dati di base e riportano i coefficienti della tabella ministeriale (**DM 31
dicembre 1988**), per esempio fabbricati industriali, macchinari, automezzi, autovetture, macchine elettroniche
d'ufficio. Per ogni categoria si impostano:
![Khaemhat 0.10.0 · categorie cespiti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/cespiti-categorie.png)
*Le categorie standard create dal pacchetto fiscale italiano, con le aliquote e i conti di cespite, fondo e quota.*
- coefficiente fiscale e coefficiente civilistico (possono differire);
- conti contabili (cespite, fondo, quota, plus/minusvalenze);
- eventuale **limite di costo fiscalmente rilevante** e **percentuale di deducibilità** (vedi autovetture);
- se applicare la riduzione al 50 % nel primo esercizio.
**Cespiti → Categorie → Categorie standard** crea le categorie più comuni con i coefficienti della tabella allegata
al **DM 31/12/1988** (fabbricati, impianti, attrezzature, mobili, macchine d'ufficio elettroniche, autocarri,
autovetture, software e altri beni immateriali con i limiti dell'art. 103 TUIR). La tabella dipende dal settore di
attività: ogni aliquota si può cambiare sulla propria categoria.
## Regole di ammortamento
| Campo | A cosa serve |
|---|---|
| **Tipo** | materiale o immateriale (decide la voce di bilancio del fondo) |
| **Aliquota civilistica** e **fiscale** | la quota annua in percentuale; la fiscale non supera il coefficiente ministeriale |
| **Metà aliquota civilistica nel primo esercizio** | applica la riduzione al 50 % anche al piano civilistico (quello fiscale la applica sempre) |
| **Limite di costo** e **deducibilità %** | per le autovetture (art. 164 TUIR): ad esempio 18.075,99 di costo e 20 % di deducibilità |
| **Conto del cespite**, **del fondo**, **dell'ammortamento** | i conti della scrittura di fine anno e della dismissione |
## Regole di calcolo
| Regola | Come la applica Khaemhat |
|---|---|
| **Primo anno al 50 %** | nell'esercizio di entrata in funzione la quota fiscale è la metà di quella ordinaria |
| **Civilistico e fiscale** | due piani paralleli (quota e fondo civilistici, quota e fondo fiscali); le differenze restano visibili nel piano |
| **Autovetture** | limite al costo fiscalmente rilevante e deducibilità ridotta secondo la normativa (art. 164 TUIR); i valori sono parametri della categoria, oggi € 18.075,99 di costo massimo per le autovetture a uso promiscuo, e vanno verificati a ogni aggiornamento normativo |
| **Beni di costo non superiore a € 516,46** | possono essere ammortizzati interamente nell'esercizio di acquisto |
| **Fine ammortamento** | la quota si azzera quando il residuo arriva a zero (stato *Ammortizzato*) |
| **Quote costanti** | aliquota per costo, mai più di quanto resta da ammortizzare |
| **Primo anno al 50 %** | nel piano fiscale sempre; nel civilistico se la categoria lo chiede |
| **Civilistico e fiscale** | due piani paralleli; la differenza è una variazione in dichiarazione dei redditi e non genera scritture |
| **Beni di costo unitario fino a 516,46 €** | si mettono in una categoria con aliquota 100 %: sono ammortizzati per intero nel primo anno |
| **Fine ammortamento** | quando il fondo raggiunge il costo il bene passa a *Ammortizzato* |
Il **piano di ammortamento** (riquadro in basso nel mockup) elenca per ogni esercizio quota e fondo civilistici,
quota e fondo fiscali, residuo e stato: *Contabilizzato* per gli anni registrati, *Simulato* per quelli futuri.
## Ammortamenti di fine anno
## Piano simulato
![Khaemhat 0.10.0 · ammortamenti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/cespiti-ammortamenti.png)
*Gli ammortamenti 2026 dell'azienda demo prima della registrazione: quote civilistiche e fiscali per cespite e
totali.*
Il piano degli esercizi futuri è sempre una **simulazione**: cambia se si modificano coefficiente, valore o date.
Serve a prevedere le quote dei prossimi anni (budget, bilancio previsionale) senza produrre registrazioni.
1. **Cespiti → Ammortamenti**, scegli l'esercizio.
2. Controlla le quote: la striscia mostra il totale civilistico, quello fiscale e la loro differenza.
3. **Registra ammortamenti** scrive una registrazione al 31/12 con una riga per categoria (quota in Dare sul conto di
ammortamento, fondo in Avere) e aggiorna fondi e movimenti dei beni.
4. Finché le registrazioni non sono definitive, **Annulla registrazione** toglie la scrittura e riporta i fondi
indietro.
## Calcolo e contabilizzazione annuale
1. **Cespiti → Registro cespiti**, scegli l'esercizio e premi **Calcola ammortamenti AAAA**.
2. Controlla le quote calcolate e gli stati (primo anno, limite fiscale raggiunto…).
3. Premi **Contabilizza**: viene generata la registrazione con causale **AMM** (quote a costo, fondi in avere).
4. Le quote dell'esercizio risultano *Contabilizzate* nel piano.
Il calcolo è anche il passo 2 della [chiusura dell'esercizio](Contabilita) e la procedura **Ammortamenti** del catalogo
([Automazioni](Automazioni)). La procedura è idempotente: rieseguirla non duplica le quote.
Il passo 2 della [chiusura](Chiusura-e-bilancio) registra gli ammortamenti se non sono già stati registrati qui.
## Dismissioni
1. Apri il cespite e scegli l'azione di dismissione (per esempio vendita o eliminazione; l'elenco dei tipi di
movimento sarà fissato in sviluppo).
2. Se è una **vendita**, Khaemhat propone la fattura di **cessione cespite (TD26)** in [Vendite](Vendite).
3. Alla data di dismissione calcola la quota dell'anno, chiude fondo e costo e rileva la **plusvalenza** o la
**minusvalenza** sui conti della categoria.
4. Il cespite passa allo stato *Dismesso* e resta nel registro.
1. Seleziona il cespite e premi **Dismetti**.
2. Indica data e **prezzo** (la contropartita è il conto *altri crediti*, che si chiude con l'incasso o con la
fattura). Il **costo dismesso** vuoto significa dismissione totale; un importo minore è una dismissione parziale.
3. Khaemhat toglie dai conti il costo e la quota corrispondente del fondo, porta il prezzo sulla contropartita e la
differenza a **plusvalenza** o **minusvalenza** (conti del pacchetto fiscale).
4. Nell'anno della dismissione non si calcola la quota di ammortamento (scelta prudente spiegata nell'ADR 0041): se
serve, registra prima gli ammortamenti fino alla data con una registrazione manuale.
## Rivalutazioni
La fattura di vendita del bene si emette come una normale fattura in [Vendite](Vendite).
Le **rivalutazioni** aumentano il valore del bene (e, a seconda della norma, il fondo) da una data; il piano di
ammortamento si ricalcola da quella data. Le modalità di ogni specifica legge di rivalutazione saranno definite in
sviluppo quando servono.
## Stampa del registro
## Registro dei beni ammortizzabili
**Stampa registro** (dal registro o dagli ammortamenti) produce il PDF del registro dei beni ammortizzabili
dell'esercizio, con costo, fondo, quota e valore netto per categoria. La stampa definitiva è una delle stampe del
passo 9 della [chiusura](Chiusura-e-bilancio).
**Registro cespiti** stampa il registro dei beni ammortizzabili (provvisorio o definitivo). La stampa definitiva è
uno dei passi della [chiusura dell'esercizio](Contabilita). Il registro si esporta anche in XLSX e PDF.
## Dati di esempio
I dati dimostrativi creano le categorie standard e quattro beni (un furgone, scaffalature, arredi già in uso con i
fondi iniziali, e un server acquistato nell'anno con la sua registrazione), così il registro, gli ammortamenti e la
chiusura si possono provare subito. Vedi [Dati di base e di esempio](Dati-di-base-e-esempio).
## Permessi e licenza
Serve il modulo **ASSET**; per contabilizzare servono anche ACCT e i permessi di prima nota. I codici dei permessi in
testa sono indicativi (convenzione `modulo.entità.azione`, SPEC §7.2) e saranno fissati in sviluppo.
| Permesso | Consente |
|---|---|
| `assets.asset.read` | registro, piano, ammortamenti (sola lettura), stampe |
| `assets.asset.write` | inserire, modificare, eliminare e dismettere cespiti; categorie |
| `assets.depreciation.post` | registrare e annullare gli ammortamenti |
Serve il modulo **ASSET**; le registrazioni richiedono anche **ACCT**.
## Domande frequenti
**Ho contabilizzato e poi corretto un coefficiente.** Annulla la registrazione AMM (storno) e rilancia il calcolo:
la procedura ricalcola le quote dell'esercizio.
**Ho registrato gli ammortamenti e poi corretto un'aliquota.** Annulla la registrazione, correggi e registra di nuovo:
è possibile finché la registrazione non è definitiva.
**Il bene è in uso da metà anno: la quota fiscale è ridotta?** Sì, se la categoria applica il primo anno al 50 %.
**Perché la quota fiscale è diversa dalla civilistica?** Le aliquote possono differire e il primo anno al 50 % vale
sempre per il fiscale; la differenza si gestisce in dichiarazione dei redditi.
## Pagine correlate
[Contabilità](Contabilita) · [Acquisti](Acquisti) · [Vendite](Vendite) · [IVA](IVA) · [Automazioni](Automazioni) ·
[Report](Report) · [Fiscalità italiana](Fiscalita-italiana)
[Chiusura e bilancio](Chiusura-e-bilancio) · [Contabilità](Contabilita) · [Acquisti](Acquisti) · [Vendite](Vendite) ·
[Fiscalità italiana](Fiscalita-italiana)
+11 -2
View File
@@ -1,6 +1,6 @@
# Changelog
> **Stato:** completa per 0.1.0 · **Ultima revisione:** 2026-11-11
> **Stato:** completa per 0.10.0 · **Ultima revisione:** 2026-11-13
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,21 @@ Le novità di ogni versione sono nel file
| Versione | Data | Contenuto |
|---|---|---|
| 0.10.0 | 2026-11-13 | M10 — Cespiti, Intrastat, chiusura, bilancio: categorie con i coefficienti ministeriali, registro cespiti con piano civilistico e fiscale, ammortamenti e dismissioni; elenchi Intrastat dai documenti con periodicità dalle soglie e file SCAMBI.CEE; registro delle dichiarazioni d'intento con plafond controllato alla conferma della fattura; ratei, risconti e differenze di cambio; chiusura guidata in nove passi con riapertura, stampe definitive e blocco; bilancio CEE ordinario, abbreviato e micro con riclassificato, indici ed export per il commercialista |
| 0.9.0 | 2026-11-13 | M9 — Fatturazione elettronica: file FatturaPA con controllo prima dell'invio e i codici dello SDI; canali PEC, SdICoop e due intermediari con regole di instradamento e canale di riserva; lettura dei canali ogni 15 minuti e ricezione push di SdICoop; notifiche che aggiornano file e documenti; correzione degli scarti; copia di cortesia PDF con l'XML allegato; fatture ricevute da registrare; pacchetti per la conservazione; fatturazione elettronica nei dati di esempio e rimozione dei dati di esempio. |
| 0.8.0 | 2026-11-13 | M8 — Scadenzario e tesoreria: partite aperte con aging, incassi e pagamenti con abbuoni, spese e differenze cambio; distinte RiBa, SDD e bonifici SEPA con insoluti, mandati SDD; riconciliazione bancaria CSV, CBI e CAMT.053 con abbinamento automatico; solleciti con interessi di mora; flusso di cassa; tesoreria nei dati di esempio. |
| 0.7.0 | 2026-11-13 | M7 — Contabilità generale e IVA: piano dei conti PMI a tre livelli, causali, prima nota con registrazioni provvisorie, definitive e storni, ricorrenti; contabilizzazione automatica di fatture, note e autofatture con righe IVA, partite e ritenute; registri IVA con stampa definitiva, liquidazione mensile o trimestrale con acconto, F24 e LIPE; ritenute d'acconto e dati CU; bollo virtuale; partitari, mastrini, bilancio di verifica e libro giornale; contabilità nei dati di esempio. |
| 0.6.0 | 2026-11-12 | M6 — Acquisti e Magazzino: ordini fornitori, ricevimenti, fatture e note di credito fornitore con protocollo e controllo dei prezzi; import delle fatture elettroniche XML, P7M e ZIP con fornitore e articoli abbinati; autofatture e integrazioni TD16-TD29 con la loro scadenza; giacenze per deposito con impegnato, ordinato e costo medio ponderato, movimenti e trasferimenti, inventario fisico, proposta di riordino, valorizzazione con classi ABC, ricostruzione; giacenze iniziali da file; acquisti e magazzino nei dati di esempio. |
| 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
+157
View File
@@ -0,0 +1,157 @@
# Chiusura dell'esercizio e bilancio
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** ACCT · **Permessi principali:** `ledger.year.close` (ratei e risconti, chiusura, blocco),
> `ledger.entry.read` (bilancio), `reports.accountant.export` (esportazione per il commercialista) · **Specifica:**
> SPEC §11.7, ADR 0043
A fine anno la contabilità va **assestata** (ammortamenti, ratei e risconti, rimanenze, accantonamenti), **chiusa**
(conti economici e patrimoniali) e **riaperta** nell'esercizio successivo; poi si stampano i libri definitivi e si
redige il **bilancio**. Khaemhat guida tutto in **nove passi**, ognuno ripetibile e annullabile fino alle stampe
definitive, e mostra il bilancio CEE, il riclassificato e gli indici in ogni momento dell'anno.
## Dove si trova
Menu **Contabilità**: **Ratei e risconti**, **Chiusura esercizio**, **Bilancio** (schede *Verifica*, *CEE*,
*Riclassificato*, *Indici*). Gli ammortamenti stanno in [Cespiti](Cespiti).
## Ratei e risconti
![Khaemhat 0.10.0 · ratei e risconti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/ratei-risconti.png)
*I ratei e risconti 2026 dell'azienda demo: il risconto attivo del premio di assicurazione del furgone, pagato il
1° ottobre per dodici mesi, di cui 273 giorni su 365 sono di competenza del 2027.*
I costi e i ricavi che stanno a cavallo di due esercizi si ripartiscono **per giorni**:
| Tipo | Quando | Scrittura al 31/12 |
|---|---|---|
| **Rateo attivo** | ricavo di competenza dell'anno che si incasserà dopo | ratei attivi in Dare, ricavo in Avere |
| **Rateo passivo** | costo di competenza dell'anno che si pagherà dopo | costo in Dare, ratei passivi in Avere |
| **Risconto attivo** | costo già registrato, in parte di competenza dell'anno dopo | risconti attivi in Dare, costo in Avere |
| **Risconto passivo** | ricavo già registrato, in parte di competenza dell'anno dopo | ricavo in Dare, risconti passivi in Avere |
1. **Contabilità → Ratei e risconti**, scegli l'esercizio.
2. **Proponi dai documenti** crea i risconti delle fatture di acquisto registrate sui conti di costi che di solito
stanno a cavallo dell'anno (assicurazioni, affitti, leasing, noleggi, software, abbonamenti), con un periodo di
dodici mesi dalla data del documento: **controlla sempre il periodo**. Un costo già proposto non si ripropone.
3. **Nuovo rateo o risconto** per inserirne uno a mano: tipo, conto, descrizione, importo totale e periodo di
competenza. La **rettifica** si calcola subito (giorni fuori dall'esercizio su giorni totali).
4. Un clic sulla riga la modifica o la elimina, finché la chiusura non l'ha registrata.
Sotto, **Differenze di cambio al 31/12** elenca le partite aperte in valuta con il residuo in valuta, il cambio del
documento, il cambio dell'ultimo giorno dell'anno (da *Tabelle azienda → Valute*, aggiornato anche dai cambi BCE) e
l'**utile o perdita su cambi**. Se il cambio manca la riga lo segnala.
Il **passo 3** della chiusura registra ratei, risconti e differenze di cambio; il **passo 8** li storna il primo giorno
dell'esercizio successivo.
## La chiusura guidata
![Khaemhat 0.10.0 · chiusura esercizio](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/chiusura-esercizio.png)
*La chiusura 2026 dell'azienda demo con i nove passi eseguiti: per ognuno le registrazioni, l'importo, l'esito e chi
l'ha eseguito; sotto, le stampe definitive da scaricare.*
**Contabilità → Chiusura esercizio**, scegli l'esercizio e premi **Esegui passo N**. I passi si eseguono **in
ordine**; l'ultimo eseguito si può **ripetere** (dopo una correzione) o **annullare** (le sue registrazioni
spariscono) finché non si arriva alle stampe definitive. In alto i badge mostrano lo stato degli esercizi (*aperto*,
*in chiusura*, *chiuso*).
| # | Passo | Cosa fa |
|---|---|---|
| 1 | **Controlli preliminari** | nessuna registrazione provvisoria, registrazioni quadrate, bilancio di verifica in pareggio; segnala i conti con saldo senza voce di bilancio, l'esercizio non ancora terminato e gli esercizi precedenti ancora aperti. L'importo è il risultato provvisorio |
| 2 | **Ammortamenti** | registra le quote civilistiche dei [cespiti](Cespiti), una riga per categoria, se non sono già registrate |
| 3 | **Ratei e risconti** | registra ratei, risconti e differenze di cambio al 31/12 |
| 4 | **Rimanenze finali** | storna le rimanenze iniziali a costo e carica le rimanenze finali di [magazzino](Magazzino) al **costo medio ponderato** |
| 5 | **Accantonamenti** | svalutazione crediti dello **0,5 %** dei crediti verso clienti aperti (limite dell'art. 106 TUIR) e quota **TFR** dell'anno (retribuzioni diviso 13,5, meno quanto già accantonato dalle paghe) |
| 6 | **Chiusura conti economici** | gira costi e ricavi a *Conto economico* e porta il **risultato** (utile o perdita) a patrimonio netto; l'esercizio passa a *in chiusura* |
| 7 | **Chiusura conti patrimoniali** | chiude attività e passività a *Stato patrimoniale finale*, per conto e per cliente o fornitore |
| 8 | **Apertura esercizio successivo** | crea l'esercizio se manca, riapre i conti con *Stato patrimoniale iniziale* (partite di clienti e fornitori comprese) e storna ratei e risconti |
| 9 | **Stampe definitive** | rende **definitive** tutte le registrazioni dell'anno, numera il libro giornale e conserva le stampe: libro giornale, registri IVA, registro cespiti, bilancio CEE |
Accanto a ogni passo compaiono i messaggi: in grigio le informazioni, in arancione ciò che va verificato, in rosso gli
errori che bloccano (il passo 1 con un errore non lascia proseguire).
![Khaemhat 0.10.0 · controlli preliminari](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/chiusura-controlli.png)
*Il passo 1 eseguito a novembre: tutto quadra, ma l'esercizio non è ancora terminato e la chiusura risulta
anticipata (esito «Da verificare»).*
### Prima del passo 9
Il passo 9 **non si annulla**: prima controlla il bilancio, i registri IVA (le stampe dei registri dentro la chiusura
sono quelle dell'anno; per la vidimazione e la numerazione delle pagine fa fede [IVA](IVA)), i cespiti e i ratei.
Le registrazioni del nuovo esercizio si possono fare anche durante la chiusura.
### Blocco dell'esercizio
Dopo il passo 9 **Blocca esercizio** chiude definitivamente l'anno: diventa di **sola lettura** e non si può più
registrare nulla con data fino al 31/12. L'esercizio passa a *chiuso*.
## Bilancio CEE
![Khaemhat 0.10.0 · bilancio CEE](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/bilancio-cee.png)
*Il bilancio CEE 2026 dell'azienda demo, schema ordinario: stato patrimoniale e conto economico con l'anno
precedente e la variazione percentuale.*
**Contabilità → Bilancio → CEE** costruisce lo **stato patrimoniale** (art. 2424 c.c.) e il **conto economico**
(art. 2425 c.c.) dell'esercizio scelto, con l'anno precedente e la variazione, dai saldi dei conti a cui il piano dei
conti associa una **voce di bilancio** (vedi [Contabilità](Contabilita#piano-dei-conti)).
- **Schema**: *Ordinario*, *Abbreviato* (art. 2435-bis) o *Micro-impresa* (art. 2435-ter, stesse voci
dell'abbreviato).
- La striscia mostra totale attivo e passivo, risultato d'esercizio e quadratura.
- Se ci sono conti con saldo **senza voce**, un avviso li elenca: assegna la voce nel piano dei conti.
- Un clic su una voce mostra i **conti** che la compongono con i saldi dei due anni.
- Le scritture dei passi 6 e 7 della chiusura non entrano nel calcolo: un esercizio chiuso mostra comunque i suoi
saldi.
- **Stampa bilancio** produce il PDF; **Esporta per il commercialista** scarica uno ZIP con cinque file CSV (piano
dei conti, bilancio di verifica, movimenti, stato patrimoniale, conto economico).
## Riclassificato e indici
![Khaemhat 0.10.0 · riclassificato](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/bilancio-riclassificato.png)
*Lo stato patrimoniale riclassificato secondo il criterio finanziario.*
La scheda **Riclassificato** propone lo **stato patrimoniale finanziario** (attivo per liquidità, passivo per
esigibilità) e il **conto economico a valore aggiunto**.
![Khaemhat 0.10.0 · indici](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/bilancio-indici.png)
*Gli indici di bilancio con la formula e il valore dei due anni.*
La scheda **Indici** calcola redditività (ROE, ROI, ROS, rotazione del capitale investito), liquidità (indice di
disponibilità e di liquidità), solidità (indipendenza finanziaria, leva, copertura delle immobilizzazioni) e i giorni
medi di incasso e di pagamento. Un indice senza denominatore mostra un trattino.
## Prova con i dati di esempio
I dati dimostrativi aprono l'anno con una scrittura di apertura (cespiti e fondi, rimanenze, banca, capitale),
registrano un premio di assicurazione da riscontare e i cespiti: la chiusura dell'anno demo si può eseguire dal
passo 1 al 9 e verificare il bilancio. Le prove automatiche fanno proprio questo, su SQLite e su PostgreSQL.
## Permessi e licenza
| Permesso | Consente |
|---|---|
| `ledger.entry.read` | bilancio CEE, riclassificato, indici, stampa |
| `ledger.year.close` | ratei e risconti, chiusura guidata, blocco dell'esercizio |
| `reports.accountant.export` | esportazione per il commercialista |
Serve il modulo **ACCT**; il passo 2 usa i cespiti se è attivo **ASSET**.
## Domande frequenti
**Il passo 1 è rosso.** Leggi i messaggi: di solito ci sono registrazioni provvisorie da registrare o eliminare in
[Prima nota](Contabilita#prima-nota). Correggi e premi **Ripeti passo 1**.
**Ho dimenticato una fattura dopo il passo 6.** Annulla i passi dal più recente fino al 5 (uno alla volta), registra
la fattura e riesegui i passi.
**Dove finisce il risultato?** Nel conto *utile (perdita) dell'esercizio* del patrimonio netto; la destinazione
dell'utile si registra a mano nel nuovo esercizio dopo l'approvazione del bilancio.
**Il TFR è giusto?** È una stima (retribuzioni dell'anno diviso 13,5 meno quanto già accantonato): se le paghe sono
elaborate fuori, registra la quota del consulente e la chiusura non aggiunge nulla.
## Pagine correlate
[Contabilità](Contabilita) · [Cespiti](Cespiti) · [IVA](IVA) · [Magazzino](Magazzino) · [Scadenzario](Scadenzario) ·
[Fiscalità italiana](Fiscalita-italiana) · [Report](Report)
+276 -227
View File
@@ -1,272 +1,321 @@
# Contabilità generale
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M7; chiusura esercizio e bilancio CEE in M10)
> **Modulo di licenza:** ACCT · **Permessi principali:** `ledger.entry.write`, `ledger.entry.finalize`, `ledger.entry.reopen`, `ledger.account.write`, `ledger.closing.run`, `ledger.export` · **Specifica:** SPEC §11.7, §11.1, §14
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** ACCT · **Permessi principali:** `ledger.account.read`/`write` (piano dei conti e causali), `ledger.entry.read`/`write` (prima nota, partitari, bilancio), `ledger.entry.finalize` (registrazioni definitive) · **Specifica:** SPEC §11.7, §14, ADR 0036, ADR 0037
## A cosa serve
Il modulo **Contabilità** tiene la **contabilità generale in partita doppia** dell'azienda: piano dei conti, causali,
prima nota, registrazioni ricorrenti, partitari di clienti e fornitori, mastrini, bilancio di verifica e libro
giornale. È collegato al resto del gestionale: ogni fattura, nota di credito o autofattura confermata scrive da sola
la sua registrazione, con le righe IVA e le partite.
Il modulo Contabilità tiene la **contabilità generale in partita doppia** dell'azienda: piano dei conti, causali,
prima nota, partitari e mastrini, esercizi e periodi, chiusura dell'esercizio e bilancio. È collegato al resto del
gestionale: ogni documento confermato (fattura di vendita o di acquisto, nota di credito, incasso, pagamento,
ammortamento…) genera da solo la propria registrazione partendo dalla **causale contabile** del tipo di documento.
La parte fiscale (registri IVA, liquidazione, acconto, F24, LIPE, ritenute d'acconto, bollo virtuale) è descritta
nella pagina [IVA](IVA); le regole italiane usate (piano dei conti modello, codici tributo, scadenze) in
[Fiscalità italiana](Fiscalita-italiana).
La parte IVA (registri, liquidazione, F24, LIPE, ritenute, bollo, dichiarazioni d'intento) è descritta nella pagina
[IVA](IVA); i cespiti nella pagina [Cespiti](Cespiti); partite, incassi e banche nello [Scadenzario](Scadenzario).
> **In questa versione** ci sono il piano dei conti modello *PMI standard* con voci CEE, le causali contabili, la
> prima nota manuale con castelletto IVA, la **contabilizzazione automatica** di fatture, note e autofatture, le
> registrazioni ricorrenti, lo storno, le registrazioni definitive con il numero di libro giornale, i partitari con
> estratto conto e partite, i mastrini, il bilancio di verifica e le stampe del bilancio e del libro giornale.
> Dalla 0.8 incassi, pagamenti, distinte e riconciliazione bancaria scrivono le loro registrazioni dallo
> [Scadenzario](Scadenzario). Dalla 0.10 ci sono la **chiusura guidata dell'esercizio** con ratei e risconti, il
> **bilancio CEE** con riclassificato e indici e l'export per il commercialista ([Chiusura e bilancio](Chiusura-e-bilancio)),
> e i [Cespiti](Cespiti). Non c'è ancora l'import del piano dei conti da file.
## Dove si trova
Menu laterale **Contabilità**, con le voci **Prima nota**, **Piano dei conti**, **Causali contabili**, **Registri IVA**,
**Liquidazione IVA**, **Ritenute**, **Chiusura esercizio**, **Bilancio**. Esercizi e periodi si gestiscono da
**Tabelle azienda → Esercizi** (mockup 052). Le voci compaiono solo se il modulo ACCT è licenziato e l'utente ha i
permessi (vedi [Licenze e moduli](Licenze-e-moduli) e [Utenti e permessi](Utenti-e-permessi)).
Menu **Contabilità** → *Prima nota*, *Piano dei conti*, *Causali*, *Partitari*, *Registri IVA*, *Liquidazione IVA*,
*Ritenute e F24*, *Bollo virtuale*, *Bilancio*. Le ultime quattro voci fiscali sono spiegate in [IVA](IVA).
## Schermate
Il menu compare solo se la licenza dell'azienda comprende il modulo **ACCT** e l'utente ha i permessi (vedi
[Licenze e moduli](Licenze-e-moduli) e [Utenti e permessi](Utenti-e-permessi)). Esercizi e periodi si gestiscono da
**Tabelle azienda → Esercizi** (vedi [Tabelle azienda](Tabelle-azienda)); periodicità IVA e pro rata sono nel
**profilo azienda**.
![040 · Prima nota](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/040-prima-nota.png)
*Mockup 040 — registrazione di prima nota generata da una fattura di acquisto: intestazione con causale FA, stato *Provvisoria* e *Quadrata*, righe in partita doppia con centro di costo e partita, riquadro delle righe IVA (anteprima ridotta)*
![041 · Prima nota manuale non quadrata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/041-prima-nota-manuale-non-quadrata.png)
*Mockup 041 — giroconto manuale in bozza con sbilancio di € 300,00 evidenziato e suggerimento "Ctrl+D quadra sull'ultima riga" (anteprima ridotta)*
![042 · Piano dei conti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/042-piano-dei-conti.png)
*Mockup 042 — albero dei conti con saldi, dettaglio del sottoconto (natura, tipo, conto padre, voce CEE, riclassificato, flag) e mastrino sotto (anteprima ridotta)*
![043 · Causali contabili](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/043-causali-contabili.png)
*Mockup 043 — elenco delle causali con area, registro IVA e "genera partita"; sotto, il modello righe della causale FA con ruoli, segno e base d'importo (anteprima ridotta)*
![044 · Partitario](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/044-partitario-estratto-conto.png)
*Mockup 044 — partitario di un cliente con saldo iniziale, dare/avere del periodo, saldo e scaduto; movimenti con saldo progressivo e stato della partita (anteprima ridotta)*
![050 · Chiusura esercizio](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/050-chiusura-esercizio.png)
*Mockup 050 — procedura guidata di chiusura in nove passi raggruppati in cinque fasi (Controlli, Assestamento, Chiusura, Apertura, Stampe), con esito e autore di ogni passo*
![051 · Bilancio CEE](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/051-bilancio-cee.png)
*Mockup 051 — bilancio CEE con stato patrimoniale espandibile e conto economico a confronto con l'esercizio precedente (Δ %); viste Verifica, CEE, Riclassificato, Indici*
![052 · Esercizi e periodi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/052-esercizi-periodi.png)
*Mockup 052 — elenco degli esercizi con stato, registrazioni e ultimo periodo IVA liquidato; sotto, i periodi mensili con stato (Aperto, Liquidato, Bloccato) e interruttore di blocco*
## Piano dei conti
Il piano dei conti ha tre livelli con codice **`MM.CC.SSS`** (mastro, conto, sottoconto; per esempio `01.04.001`
*Clienti Italia*). Alla creazione dell'azienda viene **precaricato un piano standard per PMI** con le voci di bilancio
CEE già associate (nel mockup 042 l'intestazione mostra la versione del modello caricato).
| Campo | Significato |
|---|---|
| **Codice** | `MM.CC.SSS`, gerarchico; il conto padre è il livello superiore |
| **Descrizione** | obbligatoria |
| **Natura** | patrimoniale (attività/passività), economica (costi/ricavi), d'ordine |
| **Tipo** | mastro, conto, sottoconto |
| **Voce CEE** | voce dello schema di stato patrimoniale (art. 2424 c.c.) o conto economico (art. 2425 c.c.) |
| **Riclassificato** | voce del riclassificato finanziario/gestionale (es. *Crediti commerciali*) |
| **Partitario clienti/fornitori** | il conto si articola per controparte (vedi sotto) |
| **Rilevante IVA** | il conto entra nei controlli IVA |
| **Chiusura automatica** | il conto viene chiuso dalla procedura di fine esercizio |
| **Movimentabile** | si possono registrare movimenti (di norma solo i sottoconti) |
| **Attivo** | i conti disattivati restano nello storico ma non si propongono |
Selezionando un conto nell'albero si vedono a destra i suoi dati e sotto il **mastrino** (data, registrazione,
descrizione, dare, avere, saldo); il pulsante **Mastrino completo** apre la vista intera con i filtri.
### Importare un piano dei conti
Non esiste in Italia un formato standard per scambiare il piano dei conti, quindi Khaemhat accetta tre formati:
| Formato | Uso | Contenuto |
|---|---|---|
| **CSV** (separatore `;`) | import da altri gestionali o da foglio di calcolo | colonne `codice;descrizione;livello;padre;natura;tipo;voce_cee;riclassifica;flag` |
| **XLSX** | come il CSV | stesso tracciato, una riga per conto |
| **JSON** (`khaemhat-coa.json`) | export/import completo fra installazioni Khaemhat | conti, voci di bilancio, causali e mappature |
1. Apri **Contabilità → Piano dei conti** e premi **Importa piano dei conti** (oppure usa la procedura guidata di
[Import-Export](Import-Export)).
2. Scegli il file e verifica la **mappatura delle colonne**.
3. Controlla l'**anteprima**: Khaemhat verifica la coerenza gerarchica (ogni conto ha un padre esistente, il livello
corrisponde al codice, le voci CEE esistono) e segnala le righe errate.
4. Conferma. Il risultato e gli eventuali errori restano nel report dell'importazione.
I valori ammessi nelle colonne `natura`, `tipo` e `flag` saranno fissati in sviluppo e riportati qui.
## Causali contabili e ruoli
Una **causale contabile** è il modello di una registrazione. Ogni causale ha **righe modello** che non indicano un
conto fisso ma un **ruolo**; il ruolo viene risolto nel conto reale al momento della registrazione (il conto del
cliente, il conto di ricavo dell'articolo o della sua categoria, il conto IVA del codice IVA…).
| Ruolo | Esempio di conto risolto |
|---|---|
| cliente / fornitore | sottoconto del partitario della controparte |
| ricavo / costo | conto della riga, dell'articolo o della categoria |
| IVA vendite / IVA acquisti | conti IVA del codice IVA |
| banca / cassa | conto collegato al conto bancario o alla cassa |
| Erario ritenute, cassa previdenza, bollo | conti configurati per azienda |
| abbuoni, contropartita | conti configurati o indicati a mano |
Per ogni riga si indicano anche **dare/avere**, la base dell'importo (totale documento, imponibile riga, IVA
detraibile, IVA indetraibile, ritenuta, cassa…), il **registro IVA** e se la riga **genera una partita** nello
scadenzario. Il pulsante **Prova su documento** mostra la registrazione che la causale produrrebbe su un documento
esistente, senza salvarla.
Causali di base precaricate: **FV** fattura di vendita, **NCV** nota di credito a cliente, **FA** fattura di
acquisto, **NCA** nota di credito da fornitore, **AFRC** integrazione reverse charge (autofatture TD16-TD19),
**CORR** corrispettivi, **INC** incasso, **PAG** pagamento, **INS** insoluto, **GIRO** giroconto, **AMM**
ammortamenti, **RAT** ratei e risconti, **RIM** rimanenze, chiusura e apertura, **F24**, ritenute versate, stipendi
(da import), interessi e commissioni.
```
Fattura / nota / autofattura ──Conferma──► Registrazione "Da documento" (righe, castelletto IVA, partite)
Registrazione manuale ──Registra──► Registrata ──Rendi definitive──► Definitiva (n. libro giornale) ──Storna──► Storno
Ricorrente ──ogni notte alle 5:00──► Registrazione "Ricorrente" alla data prevista
```
## Prima nota
Ogni registrazione ha un numero per esercizio (es. `2026/001205`), data di registrazione, data di competenza,
causale, descrizione, documento d'origine, registro IVA e protocollo, stato, periodo e fonte.
![Khaemhat 0.7.0 · prima nota con le registrazioni dell'esercizio](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-prima-nota.png)
*La prima nota dell'azienda demo: fatture di vendita (FV) e di acquisto (FA), nota di credito (NCV), liquidazioni IVA
(LIQ), versamenti F24, ritenuta (RIT) e il noleggio mensile ricorrente, tutte nello stato* Registrata.
### Registrare a mano
**Contabilità → Prima nota** elenca le registrazioni dell'esercizio, la più recente per prima, con numero, data,
causale, descrizione, documento, cliente o fornitore, importo e stato. In alto la ricerca (descrizione, numero o
documento) e i filtri **Dal**, **Al** e **Stato**; in fondo la paginazione. Un clic sul numero apre la registrazione.
1. **Contabilità → Prima nota**, premi **+** (Ctrl+N) e scegli la causale.
2. Nella scheda **Righe contabili** inserisci conto (F4 apre il piano dei conti), descrizione, controparte, dare o
avere, centro di costo, commessa e partita. Ctrl+↓ aggiunge una riga.
3. Se la registrazione ha IVA, compila la scheda **Righe IVA** (codice IVA, imponibile, aliquota, imposta, % di
indetraibilità, detraibile, natura).
4. Controlla la **quadratura** nell'intestazione: Dare, Avere e **Sbilancio**. Se c'è uno sbilancio, **Ctrl+D**
lo assegna all'ultima riga.
5. **Salva** (Ctrl+S). La registrazione resta *provvisoria*; quando è corretta premi **Rendi definitiva**.
La scheda **Registrazioni** contiene l'elenco; la scheda **Ricorrenti** le registrazioni che si ripetono (vedi
[sotto](#registrazioni-ricorrenti)). I pulsanti della barra:
Una registrazione che non quadra si può salvare **solo come bozza** (mockup 041: badge rosso con lo sbilancio) e non
può mai diventare definitiva.
### Stati e regole
| Stato | Cosa significa | Cosa si può fare |
| Pulsante | Cosa fa | Permesso |
|---|---|---|
| **Bozza / Provvisoria** | in lavorazione, entra nei saldi ma non sul libro giornale definitivo | modificare, eliminare, rendere definitiva (solo se quadra) |
| **Definitiva** | numerata in modo continuo sul libro giornale | **immutabile**: si corregge solo con uno **storno** collegato |
| **Nuova registrazione** | apre una registrazione vuota | `ledger.entry.write` |
| **Contabilizza documenti** | registra in prima nota i documenti di vendita e acquisto confermati di un periodo che non sono ancora contabilizzati | `ledger.entry.write` |
| **Rendi definitive** | rende definitive tutte le registrazioni fino a un giorno | `ledger.entry.finalize` |
- Le registrazioni **generate da un documento** si modificano solo stornando o correggendo il documento d'origine
(pulsante **Documento origine** per aprirlo).
- Le date sono ammesse solo in **periodi aperti**: un periodo liquidato o bloccato e un esercizio chiuso rifiutano
nuove registrazioni con data interna.
- **Storna** crea la registrazione inversa collegata all'originale (campo *storno di*).
- **Registrazioni ricorrenti**: da una registrazione manuale **Salva modello ricorrente** crea un modello riusabile
(affitti, canoni, stipendi…).
- **Valuta**: le righe possono essere in valuta estera con il cambio; le differenze cambio si rilevano alla chiusura
della partita (vedi [Scadenzario](Scadenzario)).
### Gli stati di una registrazione
| Stato | Significato | Cosa si può fare |
|---|---|---|
| **Bozza** | in lavorazione, senza numero; può non quadrare; non entra nei saldi | modificare, registrare, eliminare |
| **Registrata** | numerata (per esempio `2026/00011`), quadrata, entra nei saldi e nei registri IVA | modificare ed eliminare (se manuale), stornare, rendere definitiva |
| **Definitiva** | ha il numero di **libro giornale** | solo **stornare**: non si modifica né si elimina |
Ogni registrazione indica anche la sua **origine**: *Manuale*, *Da documento*, *Liquidazione IVA*, *Versamento F24*,
*Ricorrente*, *Storno*, *Ritenuta*.
## Registrare a mano
![Khaemhat 0.7.0 · registrazione generata da una fattura di acquisto](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-registrazione-fattura.png)
*La registrazione di una fattura di acquisto intracomunitaria: causale FA, registro ACQ1, fornitore in Avere e merci
in Dare; nel castelletto IVA il codice NI41 (natura N3.2). La striscia in alto riassume Dare, Avere, Sbilancio e
righe.*
1. **Contabilità → Prima nota → Nuova registrazione**.
2. Nella **Testata** scegli la **data** e la **causale**: la causale propone le righe con conti e segni e il
**registro IVA**. Scrivi la **descrizione** e, se serve, **numero** e **data del documento**.
3. Nelle **Righe** completa per ogni riga il **conto** (si registra solo sui **sottoconti**), il **cliente o
fornitore** (obbligatorio sui conti con partitario, come *Clienti Italia* e *Fornitori Italia*), la descrizione,
il **centro di costo** e l'importo in **Dare** oppure in **Avere**. **Aggiungi riga** e il cestino aggiungono e
tolgono righe.
4. Se la registrazione ha IVA, compila il **Castelletto IVA** con **Aggiungi aliquota**: codice IVA, imponibile,
imposta e parte indetraibile. Con righe IVA serve un registro IVA.
5. Controlla la striscia in alto: **Dare**, **Avere**, **Sbilancio** e numero di **righe**. **Chiudi lo
sbilancio** mette la differenza sull'ultima riga senza importo (o su una nuova riga, a cui dai il conto).
6. **Salva bozza** conserva il lavoro anche se non quadra; **Registra** salva la registrazione, che deve quadrare, e
le assegna il numero.
Una registrazione con righe IVA non si può datare in un periodo già **liquidato** (vedi [IVA](IVA#liquidazione-iva));
nessuna registrazione si può datare in un periodo **bloccato**, in un esercizio chiuso o **prima dell'ultima
registrazione definitiva**.
### Registrazioni che vengono dai documenti
Le registrazioni *Da documento* non si modificano né si eliminano dalla prima nota: si corregge il **documento** e
Khaemhat riscrive la registrazione con lo stesso numero. Se il documento viene annullato, la registrazione sparisce
oppure, se era già definitiva, viene stornata.
### Stornare ed eliminare
- **Storna** chiede la **data dello storno** e crea una nuova registrazione con Dare e Avere invertiti, collegata
all'originale (che diventa *Stornata*). Si stornano solo le registrazioni registrate o definitive, una volta sola.
- **Elimina** toglie una registrazione manuale non definitiva. Una registrazione usata come modello di una ricorrente
si elimina solo dopo aver tolto la ricorrente.
### Rendere definitive le registrazioni
**Rendi definitive** chiede un giorno e rende definitive tutte le registrazioni registrate fino a quel giorno: ognuna
riceve il **numero di libro giornale**, in ordine di data, e da quel momento si corregge solo con uno storno.
L'operazione non si annulla ed è rifiutata se nel periodo ci sono ancora **bozze** (registrale o eliminale prima).
Dopo, nessuna nuova registrazione può avere una data anteriore all'ultima definitiva.
## Contabilizzazione automatica dei documenti
Alla conferma di un documento (o in un secondo momento con la procedura **Contabilizzazione documenti**, vedi
[Automazioni](Automazioni)) Khaemhat applica la causale contabile del **tipo documento** e genera la registrazione
con le righe IVA e le partite di scadenzario, nella stessa transazione del documento. Il documento mostra il flag
*contabilizzato* e il collegamento alla registrazione; la registrazione mostra il documento d'origine.
Con il modulo ACCT attivo, quando **confermi** (o emetti) uno di questi documenti Khaemhat scrive la sua registrazione
**nella stessa operazione**, con le righe IVA nel suo registro, le **partite** dalle rate di scadenza e l'eventuale
**ritenuta d'acconto**:
## Partitari, mastrini ed estratti conto
Il **partitario** (mockup 044) mostra per un cliente o fornitore: saldo iniziale, dare e avere del periodo, saldo,
di cui scaduto e l'elenco dei movimenti con saldo progressivo e stato della partita. Filtri per periodo, conto,
stato e "solo definitive". Da qui:
- **Estratto conto**: genera il PDF da inviare al cliente (resta come allegato, vedi [Allegati e file](Allegati-e-file));
- **Sollecito**: apre i solleciti dello [Scadenzario](Scadenzario).
Il **drill-down** è completo: dal bilancio al conto, dal conto al mastrino, dal mastrino alla registrazione, dalla
registrazione al documento.
## Esercizi e periodi
In **Tabelle azienda → Esercizi** (mockup 052) ogni esercizio ha inizio, fine, stato, numero di registrazioni,
ultimo periodo IVA liquidato, data di blocco, prima pagina del libro giornale e ultima registrazione definitiva.
| Esercizio | Periodo (mese o trimestre) |
|---|---|
| **Aperto** — si registra normalmente | **Aperto** — accetta registrazioni |
| **In chiusura** — è in corso la procedura di chiusura | **Liquidato** — la liquidazione IVA è stata confermata |
| **Chiuso** — sola lettura | **Bloccato** — rifiuta ogni registrazione con data interna |
**Nuovo esercizio** crea l'esercizio successivo; di norma lo crea la chiusura stessa, in stato provvisorio, per
permettere di registrare nel nuovo anno prima di aver chiuso il vecchio. I periodi si bloccano e sbloccano con
l'interruttore **Blocco** (permesso di riapertura richiesto).
## Chiusura dell'esercizio guidata
**Contabilità → Chiusura esercizio** (mockup 050) guida la chiusura in nove passi. Ogni passo è **ripetibile e
annullabile**; le registrazioni generate sono marcate con la fonte `closing/<passo>` e restano provvisorie fino alle
stampe definitive.
| # | Passo | Cosa fa |
| Documento | Causale | Registro IVA |
|---|---|---|
| 1 | Controlli preliminari | nessuna registrazione provvisoria, partite quadrate, IVA liquidata, numerazioni continue |
| 2 | Ammortamenti | quote civilistiche e fiscali dei [Cespiti](Cespiti) |
| 3 | Ratei e risconti | da competenze dei documenti e inserimenti manuali (**Verifica ratei/risconti**) |
| 4 | Rimanenze finali | valorizzazione del [Magazzino](Magazzino) al 31/12 e storno delle iniziali |
| 5 | Accantonamenti | svalutazione crediti, TFR (da import) |
| 6 | Chiusura conti economici | giroconto a Conto economico e rilevazione del risultato |
| 7 | Chiusura conti patrimoniali | giroconto a Stato patrimoniale finale |
| 8 | Apertura nuovo esercizio | riporto dei saldi e delle partite aperte |
| 9 | Stampe definitive | libro giornale, libro inventari, registri IVA, registro cespiti |
| Fattura immediata, accompagnatoria, differita, di acconto; nota di debito; parcella | `FV` | `VEN1` |
| Nota di credito a cliente | `NCV` | `VEN1` |
| Fattura fornitore | `FA` | `ACQ1` |
| Nota di credito fornitore | `NCA` | `ACQ1` |
| Autofatture e integrazioni (AF16-AF29) | `AFRC` | `VEN-RC` e `ACQ-RC` |
1. Apri la procedura e premi **Esegui passo N**: il passo mostra il numero di registrazioni prodotte e l'esito
(*Superato*, *Eseguito*, *Da verificare*, *In attesa*).
2. Controlla i risultati con l'icona di anteprima e, se serve, torna indietro di un passo.
3. Dopo le stampe definitive premi **Blocca esercizio**: l'esercizio diventa **chiuso**, in sola lettura, e le date
precedenti al nuovo esercizio vengono rifiutate.
Come si formano le righe:
La chiusura è anche nel catalogo delle procedure ([Automazioni](Automazioni)).
- **Vendita**: il **cliente** in Dare per il totale; i **ricavi** in Avere, raggruppati per conto; la **rivalsa
della cassa previdenziale** e il **bollo addebitato** al cliente in Avere; l'**IVA vendite** in Avere. Con lo
**split payment** l'IVA viene subito tolta al cliente (il cliente paga solo l'imponibile).
- **Acquisto**: il **fornitore** in Avere; i **costi** in Dare, con l'**IVA indetraibile** aggiunta al costo;
l'**IVA acquisti** in Dare.
- **Autofattura e integrazione**: **IVA acquisti** in Dare e **IVA vendite** in Avere, senza cliente né fornitore;
il documento compare in entrambi i registri RC, con effetto neutro sulla liquidazione.
- **Note di credito**: le stesse righe con i segni invertiti.
- Lo **sconto in calce** e gli **arrotondamenti** si ripartiscono sulle righe; i centesimi di differenza vanno sulla
riga più grande.
## Bilancio
**Quale conto.** Per ogni riga Khaemhat usa il **Conto ricavi** o **Conto costi** dell'articolo (scheda articolo),
per gli acquisti il **Conto di costo** del fornitore, poi il conto del codice IVA e, se manca, quello della causale
(`30.01.001` *Ricavi per vendita di merci*, `20.01.001` *Merci c/acquisti*). Il cliente e il fornitore usano il
**Conto cliente** o **Conto fornitore** della loro scheda, altrimenti `05.01.001` *Clienti Italia* e `14.01.001`
*Fornitori Italia*. Se manca un conto la conferma del documento si ferma con un messaggio che lo dice.
**Contabilità → Bilancio** (mockup 051) offre quattro viste:
**Contabilizza documenti.** I documenti confermati quando ACCT non era attivo (o prima della versione 0.7) si
registrano in blocco: **Prima nota → Contabilizza documenti**, scegli **Dal** e **Al** e premi **Contabilizza**. La
casella *Ricontabilizza anche i documenti già registrati* riscrive anche le registrazioni esistenti, purché non
siano definitive.
| Vista | Contenuto |
## Registrazioni ricorrenti
![Khaemhat 0.7.0 · la scheda Ricorrenti della prima nota](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-ricorrenti.png)
*Il noleggio mensile della stampante dei dati demo: frequenza mensile, prossima data, registrazione modello e stato.*
Affitti, canoni, noleggi: una registrazione **ricorrente** copia una **registrazione modello** alle date previste.
1. Registra una volta la scrittura da ripetere (per esempio *Noleggi* in Dare e *Banca c/c* in Avere).
2. **Prima nota → Ricorrenti → Nuova ricorrente**: descrizione, **numero della registrazione modello** (il numero di
prima nota, per esempio `2026/00018`), **frequenza** (*Mensile*, *Trimestrale*, *Semestrale*, *Annuale*),
**prossima data**, data **Fino al** facoltativa, casella **Sospesa**.
3. Ogni notte alle **5:00** l'attività di sistema *Registrazioni ricorrenti* (vedi
[Attività programmate](Attivita-programmate)) scrive le registrazioni arrivate a scadenza, con origine
*Ricorrente*, e sposta in avanti la prossima data. **Genera ora** fa lo stesso subito.
Una data di fine mese resta di fine mese (31/01, poi 28/02, poi 31/03). **Apri il modello** apre la registrazione da
copiare; eliminando una ricorrente le registrazioni già generate restano.
## Piano dei conti
![Khaemhat 0.7.0 · piano dei conti con il mastrino di Clienti Italia](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-piano-dei-conti.png)
*L'albero dei 240 conti del modello PMI standard, il dettaglio del sottoconto 05.01.001 Clienti Italia (sottoconto,
attività, tipo Clienti, voce CEE C.II.1, con partitario) e il suo mastrino con il saldo progressivo.*
Il piano dei conti ha tre livelli con codice **`MM.CC.SSS`**: **mastro** (`05` *Crediti verso clienti*), **conto**
(`05.01` *Clienti*) e **sottoconto** (`05.01.001` *Clienti Italia*). Si registra solo sui sottoconti. Con le tabelle
di base dell'azienda viene caricato il modello **PMI standard** del pacchetto fiscale: 240 conti con le voci di
bilancio CEE già associate (vedi [Fiscalità italiana](Fiscalita-italiana#piano-dei-conti-modello)).
| Campo | Significato |
|---|---|
| **Verifica** | bilancio di verifica per conto (dare, avere, saldo); bilancini per centro di costo e commessa |
| **CEE** | schema civilistico **ordinario**, **abbreviato** o **micro**, con confronto con l'esercizio precedente e Δ % |
| **Riclassificato** | riclassificato finanziario e gestionale |
| **Indici** | indici di bilancio |
| **Codice** | mastro, conto e sottoconto separati da punti; il conto padre deve esistere |
| **Descrizione** | obbligatoria |
| **Natura** | *Attività*, *Passività*, *Costo*, *Ricavo*, *Conto d'ordine* |
| **Tipo** | *Generico*, *Clienti*, *Fornitori*, *Banca*, *Cassa*, *IVA*, *Tributi*: dice alle registrazioni automatiche che cosa cercare |
| **Voce di bilancio CEE** | voce dello schema civilistico (art. 2424 e 2425 c.c.), per esempio `C.II.1` |
| **Riclassificazione** | voce del riclassificato, facoltativa |
| **Partitario** | le righe indicano il cliente o il fornitore |
| **Rilevante IVA** | il conto entra nelle registrazioni con IVA |
| **Chiuso in automatico a fine esercizio** | il conto è chiuso dalla [chiusura dell'esercizio](Chiusura-e-bilancio) |
| **Disattivato** | il conto resta nello storico ma non si usa più |
L'intestazione indica la data di situazione (anche **infrannuale**) e se include le registrazioni provvisorie.
Doppio clic su una voce apre i conti, poi il mastrino, la registrazione e il documento. Il bilancio si stampa e si
esporta in XLSX e PDF; la **nota integrativa** è prodotta in bozza. Il formato XBRL è previsto in fase 2
([Roadmap](Roadmap)).
A sinistra l'**albero** con la ricerca per codice o descrizione; a destra i dati del conto scelto e, per i
sottoconti, il **mastrino**: i movimenti del periodo (**Dal**, **Al**) con saldo iniziale, Dare, Avere, **saldo
progressivo**, totali e paginazione. **Stampa** scarica il mastrino in PDF; il numero della registrazione la apre.
## Export per il commercialista
**Nuovo conto**, **Modifica** ed **Elimina** richiedono `ledger.account.write`. Un conto con **movimenti** non si
elimina (disattivalo); un conto con **sottoconti** si elimina solo dopo di loro.
Pacchetto **ZIP mensile** con libro giornale, registri IVA, partitari e bilancio in XLSX, CSV e PDF. Si genera a mano
o in automatico con la procedura **Export per il commercialista** pianificata ogni mese (vedi [Automazioni](Automazioni)
e [Attività programmate](Attivita-programmate)).
## Causali contabili
## Report del modulo
![Khaemhat 0.7.0 · causali contabili, la causale FA con le righe proposte](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-causali.png)
*Le causali di base con il loro registro IVA; a destra la causale FA Fattura di acquisto: area Acquisti, registro
ACQ1, apre partite, e le righe proposte con ruolo, segno e conto.*
Libro giornale, mastrini, bilancini per centro di costo e commessa, registri IVA, liquidazioni, scadenzario IVA,
elenco clienti e fornitori per fatturato, riepilogo per natura IVA, dati dei quadri VE/VF, estratti conto, export per
il commercialista. Vedi [Report](Report).
Una **causale** è il modello di una registrazione: propone conti, segni e registro IVA. Ogni causale ha:
## Scorciatoie
| Tasto | Azione |
| Campo | Significato |
|---|---|
| Ctrl+N / Ctrl+S | nuova registrazione / salva |
| Ctrl+D | quadra la registrazione sull'ultima riga |
| F4 | ricerca nel piano dei conti dalla cella *Conto* |
| Ctrl+↓ | nuova riga |
| Ctrl+↑ / Ctrl+↓ (fuori dalla griglia) | registrazione precedente / successiva |
| Alt+1…9 | cambia scheda |
| **Codice**, **Descrizione** | per esempio `FA` *Fattura di acquisto* |
| **Area** | *Generale*, *Vendite*, *Acquisti*, *Tesoreria*, *Imposte*, *Chiusura esercizio* |
| **Registro IVA** | il registro delle registrazioni con IVA |
| **Apre partite** | le registrazioni aprono partite di clienti o fornitori |
| **Causale di storno** | note di credito: i segni del documento si invertono |
| **Disattivato** | la causale non si propone più |
| **Righe proposte** | per ogni riga **ruolo** (*Cliente*, *Fornitore*, *Ricavo*, *Costo*, *IVA vendite*, *IVA acquisti*, *Banca*, *Cassa*, *Ritenute da versare*, *Ritenute subite*, *Contributo cassa*, *Bollo*, *Arrotondamenti*, *Erario c/IVA*, *IVA split payment* o *Conto indicato*), **segno** Dare o Avere, **conto** e descrizione |
Elenco completo in [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie).
Causali di base: **FV** fattura di vendita, **NCV** nota di credito a cliente, **FA** fattura di acquisto, **NCA**
nota di credito da fornitore, **AFRC** autofattura e integrazione reverse charge, **CORR** corrispettivi giornalieri,
**INC** incasso da cliente, **PAG** pagamento a fornitore, **RIT** ritenuta d'acconto operata, **RITS** ritenuta
d'acconto subita, **LIQ** liquidazione IVA periodica, **F24** versamento con modello F24, **GIRO** giroconto, **SPB**
spese e commissioni bancarie, **STO** storno di scrittura.
Le causali dei documenti, della liquidazione, delle ritenute e dell'F24 sono usate dalle registrazioni automatiche:
cambiarne i conti cambia le registrazioni future. Una causale usata da registrazioni non si elimina: disattivala.
Per un'azienda creata con una versione precedente, conti, causali e registri mancanti si aggiungono con
`scripts/seed.sh --base` (vedi [Dati di base e di esempio](Dati-di-base-e-esempio)).
## Partitari ed estratto conto
![Khaemhat 0.7.0 · partitario clienti, estratto conto e partite](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-partitari.png)
*Il partitario clienti con Dare, Avere, saldo e partite aperte; a destra l'estratto conto di Edilizia Moderna S.p.A. e
le sue partite, con le scadenze passate in rosso.*
**Contabilità → Partitari** ha due schede, **Clienti** e **Fornitori**. L'elenco mostra per ogni soggetto con
movimenti Dare, Avere, **Saldo** e numero di partite **aperte**, con ricerca per nome o codice e il **saldo
complessivo**.
Scegliendo un soggetto si vedono:
- l'**estratto conto** del periodo (**Dal**, **Al**): saldo iniziale, movimenti con documento e saldo progressivo,
totali; **Stampa** lo scarica in PDF;
- le **partite**: una per rata di ogni documento, con data documento, numero della rata, **scadenza**, importo,
pagato e **residuo**; le scadenze superate sono in rosso. *Mostra anche le partite chiuse* aggiunge quelle saldate.
Le partite nascono dai documenti e si chiudono con gli incassi e i pagamenti registrati nello
[Scadenzario](Scadenzario), dove ci sono anche distinte, solleciti e riconciliazione bancaria.
## Bilancio di verifica e libro giornale
![Khaemhat 0.7.0 · bilancio di verifica](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-bilancio.png)
*Il bilancio di verifica dell'azienda demo al livello dei sottoconti, con i totali di conti e mastri; la striscia
riassume Dare, Avere, quadratura e risultato del periodo.*
**Contabilità → Bilancio** mostra i saldi di tutti i conti in un periodo:
- filtri **Dal** e **Al**, **Centro di costo** (tutti o uno), **Dettaglio** (*Mastri*, *Conti*, *Sottoconti*) e
**Comprendi le bozze**;
- per ogni conto **saldo iniziale**, **Dare**, **Avere**, **Saldo Dare** o **Saldo Avere**, con i totali di conti e
mastri;
- la striscia con i totali **Dare** e **Avere**, la **Quadratura** (*Dare e Avere quadrano* o no) e il **Risultato
del periodo** (ricavi meno costi: *Utile* o *Perdita*).
Le stampe sono file PDF da scaricare:
| Pulsante | Contenuto |
|---|---|
| **Stampa bilancio** | il bilancio di verifica del periodo e del centro di costo scelti |
| **Libro giornale di prova** | registrazioni registrate e definitive del periodo, in ordine di data, con le righe |
| **Libro giornale definitivo** | solo le registrazioni definitive, con il numero di libro giornale e le pagine numerate dall'inizio dell'anno |
Le altre schede della pagina, **CEE**, **Riclassificato** e **Indici**, mostrano il bilancio d'esercizio: sono
spiegate in [Chiusura e bilancio](Chiusura-e-bilancio).
## Dati demo
Con i dati di esempio (`scripts/seed.sh --demo`) la contabilità parte già popolata: i documenti demo sono
contabilizzati, la fattura del professionista *Studio Rag. Neri Paola* è pagata e la sua ritenuta è da versare, il
noleggio mensile della stampante (45 euro, conto `22.01.003` *Noleggi* contro la banca) è una registrazione
ricorrente, le liquidazioni IVA dei mesi già finiti sono confermate e gli F24 già scaduti sono pagati. Vedi
[Dati di base e di esempio](Dati-di-base-e-esempio).
## Permessi e licenza
Serve il modulo **ACCT**. Il permesso `ledger.entry.finalize` è necessario per rendere definitiva una registrazione;
gli altri codici indicati in testa seguono la convenzione `modulo.entità.azione` (SPEC §7.2) e saranno fissati in
sviluppo. Il ruolo predefinito **Contabilità** li comprende. Senza licenza ACCT le voci del menu non compaiono, ma i
dati restano conservati.
Serve il modulo **ACCT**: senza, il menu Contabilità non compare, i documenti non vengono contabilizzati (si
recuperano dopo con **Contabilizza documenti**) e i dati già registrati restano conservati.
## Attenzione
| Permesso | Cosa consente |
|---|---|
| `ledger.account.read` | vedere piano dei conti e causali |
| `ledger.account.write` | creare, modificare ed eliminare conti e causali |
| `ledger.entry.read` | prima nota, mastrini, partitari, bilancio e stampe del libro giornale |
| `ledger.entry.write` | registrazioni manuali, storni, ricorrenti, contabilizzazione dei documenti |
| `ledger.entry.finalize` | rendere definitive le registrazioni |
- Una registrazione **definitiva** non si modifica: va stornata. Usa lo stato provvisorio finché non hai controllato.
- Confermare una liquidazione IVA blocca il periodo: correzioni successive richiedono la riapertura (permesso
dedicato) e vanno ricalcolate.
- I numeri del libro giornale definitivo sono continui; la procedura di chiusura verifica che non ci siano buchi.
I permessi della parte IVA (`vat.register.read`, `vat.settlement.read`, `vat.settlement.confirm`) sono in [IVA](IVA).
## Domande frequenti
- **Il pulsante Registra è spento.** Dare e Avere non quadrano: guarda lo *Sbilancio* nella striscia, correggi gli
importi o usa **Chiudi lo sbilancio**. Intanto puoi usare **Salva bozza**.
- **"Si registra solo sui sottoconti".** Hai scelto un mastro o un conto: scegli un sottoconto (codice a tre parti).
- **"Le righe su clienti e fornitori indicano il soggetto".** Il conto ha il partitario: indica il cliente o il
fornitore nella riga.
- **Non riesco a modificare la registrazione di una fattura.** Viene dal documento: correggi la fattura e la
registrazione si aggiorna. Se è già definitiva, la correzione del documento la storna e la riscrive.
- **"Manca un conto per contabilizzare il documento".** Una causale o il piano dei conti non hanno il conto che
serve (per esempio dopo aver cancellato un sottoconto): controlla la causale del documento e il conto dell'articolo.
- **La data è rifiutata.** Il periodo è liquidato (solo per registrazioni con IVA), bloccato, l'esercizio è chiuso o
c'è già una registrazione definitiva successiva.
- **La ricorrente non ha generato nulla.** È sospesa, la data *Fino al* è passata o la prossima data è nel futuro;
**Genera ora** mostra l'eventuale problema.
## Pagine correlate
[IVA](IVA) · [Cespiti](Cespiti) · [Scadenzario](Scadenzario) · [Vendite](Vendite) · [Acquisti](Acquisti) ·
[Magazzino](Magazzino) · [Tabelle azienda](Tabelle-azienda) · [Report](Report) · [Automazioni](Automazioni) ·
[Import-Export](Import-Export) · [Fiscalità italiana](Fiscalita-italiana) · [Glossario](Glossario)
[IVA](IVA) · [Fiscalità italiana](Fiscalita-italiana) · [Vendite](Vendite) · [Acquisti](Acquisti) ·
[Scadenzario](Scadenzario) · [Cespiti](Cespiti) · [Tabelle azienda](Tabelle-azienda) ·
[Attività programmate](Attivita-programmate) · [Dati di base e di esempio](Dati-di-base-e-esempio) ·
[Glossario](Glossario)
+67 -22
View File
@@ -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*.
![004 · Dashboard](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/004-dashboard.png)
*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 · dashboard](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-home.png)
*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).*
![005 · Dashboard in tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/005-dashboard-tema-scuro.png)
*Mockup 005 — la stessa dashboard in tema scuro (anteprima ridotta).*
![Khaemhat 0.3.0 · tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-tema-scuro.png)
*Khaemhat 0.3.0 — la stessa dashboard in tema scuro.*
![006 · Dashboard · personalizzazione](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/006-dashboard-personalizza.png)
*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](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/dashboard-personalizza.png)
*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 |
|---|---|---|
@@ -40,41 +56,69 @@ La griglia ha 12 colonne; ogni widget può occupare 3, 4, 6, 8 o 12 colonne.
| **Attività CRM** | le attività del giorno (chiamate, riunioni, visite) | richiede il modulo CRM |
| **Promemoria personali** | note libere, visibili solo a te | |
| **Scorciatoie** | pulsanti configurabili verso maschere e azioni frequenti | |
| **Sottoscorta** | articoli sotto la scorta minima | |
| **Sottoscorta** | gli articoli più urgenti da riordinare (esauriti, sottoscorta, sotto il punto di riordino) con disponibile e scorta; un clic apre i movimenti dell'articolo, **Riordina** la proposta di riordino | dalla 0.6.0 |
| **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) |
Dalla 0.8 lo [Scadenzario](Scadenzario) aggiunge alle **Scadenze** gli incassi e i pagamenti dei prossimi giorni (al
massimo 12, area *Tesoreria*) e a **Da fare oggi** il totale dei crediti scaduti, con il link ai solleciti; servono
il modulo FIN e il permesso `finance.schedule.read`. I moduli delle prossime versioni aggiungono le loro righe
(scarti SDI, 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 +129,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.
+148 -15
View File
@@ -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 la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **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 |
@@ -52,10 +52,37 @@ Il pacchetto italiano fa parte del pacchetto fiscale Italia (vedi [Fiscalità it
| **Cespiti** | categorie di beni con i coefficienti di ammortamento ministeriali |
| **Codici tributo F24** | IVA, ritenute, bollo, acconti |
| **Code list SDI** | tipi documento (TD), modalità di pagamento (MP), regimi fiscali (RF) e altre liste della FatturaPA; regime RF01 predefinito |
| **Banche ABI/CAB** | tabella per ricavare banca e BIC dall'IBAN |
| **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. L'**elenco delle banche ABI/CAB** non è incluso: dall'IBAN
Khaemhat legge ABI e CAB, mentre nome della banca e BIC vengono da un conto dell'azienda presso la stessa banca o si
scrivono a mano la prima volta. Un comune soppresso per fusione resta nella tabella finché non lo disattivi.
Le categorie dei cespiti si creano da **Cespiti → Categorie → Categorie standard** (vedi [Cespiti](Cespiti)). Le altre
voci dell'elenco (piano dei conti, causali contabili, registri IVA, 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 +91,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`).
@@ -85,7 +116,7 @@ reale. Contiene:
| Articoli | 120 |
| Documenti | 12 mesi coerenti: ordini → DDT → fatture differite, fatture immediate e accompagnatorie, note di credito, pro-forma, parcelle; ordini fornitore → carichi → fatture di acquisto; autofatture; inventario, movimenti, trasferimenti |
| Contabilità | registrazioni dai documenti, incassi e pagamenti anche parziali, un insoluto RiBa, giroconti, liquidazioni IVA confermate fino al mese precedente, ritenute, 58 cespiti con ammortamenti, esercizio precedente chiuso con bilancio |
| Fatturazione elettronica | XML SDI in stati diversi, con notifiche |
| Fatturazione elettronica | file FatturaPA in stati diversi con le notifiche, canali e regole di instradamento, fatture ricevute da registrare |
| Tesoreria | un estratto conto da riconciliare |
| CRM | 23 lead, 18 opportunità, attività, 3 campagne, 2 ticket |
| Servizi e canali | 2 contratti di assistenza con interventi, 1 canale e-commerce generico con ordini |
@@ -94,6 +125,83 @@ 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.
**Da M6** ci sono anche **acquisti e magazzino**, costruiti allo stesso modo:
| Documenti | Che cosa mostrano |
|---|---|
| 1 movimento di esistenze iniziali al 1° gennaio (`APE`) | la giacenza di partenza di ogni articolo; un articolo su cinque parte con poca merce, così le vendite lo portano sotto scorta e la [proposta di riordino](Magazzino#proposta-di-riordino) ha qualcosa da proporre |
| 2 ordini fornitori | uno ricevuto per intero, uno ricevuto in parte (il resto è nell'*ordinato*) |
| 2 ricevimenti merce | i carichi dei due ordini |
| 3 fatture fornitore | una dal ricevimento con un prezzo più alto dell'ordine (vedi l'avviso sulle differenze), la parcella del commercialista, la fattura di un fornitore tedesco che aspetta la sua **integrazione AF18** |
| 1 inventario aperto | 12 articoli già contati, due con una differenza |
Il caricamento non si ripete se l'azienda ha già documenti di acquisto o di magazzino.
**Da M7** documenti e fatture sono **contabilizzati** e ci sono un noleggio ricorrente, le liquidazioni IVA
confermate fino al mese precedente, le ritenute e il bollo virtuale (vedi [Contabilità](Contabilita) e [IVA](IVA)).
**Da M8**, se la licenza comprende il modulo **FIN**, c'è anche la **tesoreria** (vedi [Scadenzario](Scadenzario)):
| Dati | Che cosa mostrano |
|---|---|
| La banca *Banca Popolare Dimostrativa* | conto predefinito con IBAN, SIA, CUC e identificativo creditore; i versamenti dei soci al 1° gennaio |
| Incassi e pagamenti | i fornitori scaduti pagati con le spese, i clienti scaduti incassati (uno solo in parte), con il CRO |
| Distinte RiBa | una distinta presentata e accreditata con l'ultimo effetto **insoluto** e le spese; una distinta *salvo buon fine* in bozza con le scadenze dei prossimi 45 giorni |
| Mandato SDD | un mandato *Core* firmato da un cliente |
| Estratto conto | un CSV di quattro movimenti da riconciliare: il saldo della fattura incassata in parte, un pagamento già registrato, le commissioni riconosciute dalla regola *Canone e commissioni* e una spesa da registrare su conto |
| Solleciti | un primo sollecito già inviato al cliente con lo scaduto più vecchio |
**Da M9**, se la licenza comprende il modulo **EINV**, c'è anche la **fatturazione elettronica** (vedi
[Fatturazione elettronica](Fatturazione-elettronica)):
| Dati | Che cosa mostrano |
|---|---|
| File FatturaPA | le fatture e le note già emesse hanno il loro file: la maggior parte **consegnata** (RC), una **scartata** (NS 00305) e poi corretta e consegnata, una con **mancata consegna** (MC), le ultime in attesa o ancora da inviare |
| Notifiche | le ricevute di ogni file, scaricabili come sono arrivate |
| Canali | la PEC configurata ma **in pausa** con credenziali finte, l'Intermediario A abbozzato e disattivato: nessun dato di esempio raggiunge lo SDI |
| Instradamento | tre regole: PA su PEC, oltre 200 file al giorno sull'Intermediario A, sempre PEC con l'Intermediario A di riserva |
| Fatture ricevute | tre fatture di fornitori da registrare |
**Da M10** ci sono anche i dati di **fine anno** (vedi [Cespiti](Cespiti), [Intrastat](Intrastat),
[Dichiarazioni d'intento](Dichiarazioni-d-intento) e [Chiusura e bilancio](Chiusura-e-bilancio)):
| Dati | Che cosa mostrano |
|---|---|
| Apertura dei conti | una registrazione al 1° gennaio con cespiti e fondi, rimanenze di magazzino, banca, capitale sociale e utili portati a nuovo |
| Cespiti | le categorie standard e quattro beni: furgone, scaffalature e arredi già in uso con i fondi iniziali, un server acquistato nell'anno con la sua registrazione |
| Risconto | il premio di assicurazione del furgone pagato il 1° ottobre per dodici mesi |
| Dichiarazione d'intento | quella di Idrotermica Piemonte nel registro, con una fattura in N3.5 che consuma il plafond |
| Intrastat | una fattura non imponibile art. 41 a Bergwerk Bau (Austria) con codici doganali e pesi, se la licenza comprende **INTRA** |
Con questi dati la chiusura dell'anno si esegue dal passo 1 al 9.
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.
@@ -108,8 +216,13 @@ alternativa si caricano al primo avvio con `KHAEMHAT_SEED_DEMO=true` (solo se il
### Rimuovi dati di esempio
1. Premi **Rimuovi dati di esempio** (solo **super utente**).
2. Khaemhat elimina le righe dimostrative in ordine di dipendenza e **si rifiuta** se esistono dati reali collegati
a righe dimostrative (ad esempio una fattura vera intestata a un cliente demo).
2. Khaemhat elimina le righe dimostrative (`is_demo`) e quelle che appartengono loro (le righe di un documento demo,
le giacenze di un articolo demo) in **una sola transazione**, e **si rifiuta** se esistono dati reali collegati a
righe dimostrative (ad esempio una fattura vera intestata a un cliente demo): in quel caso elenca le tabelle
coinvolte e non tocca nulla.
Le tabelle e i loro collegamenti si leggono dalle migrazioni, quindi la rimozione copre anche i moduli aggiunti in
seguito. Da riga di comando: `scripts/seed.sh --remove-demo [--company CODICE]` (vedi sotto).
Usalo quando un'azienda nata come demo diventa l'azienda reale; per partire puliti è comunque preferibile creare
un'azienda nuova (vedi [Istanza e database](Istanza-e-database)).
@@ -125,14 +238,34 @@ 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
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --remove-demo --company DEMO
```
`--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 |
| `--remove-demo` | rimuove solo i dati di esempio (non si combina con le altre opzioni); stampa le righe rimosse per tabella o le tabelle che lo impediscono |
| `--company CODICE` | lavora solo su quell'azienda invece che su tutte quelle attive |
Il caricamento completo dell'azienda di esempio richiede pochi secondi su SQLite (circa 2,5 s in sviluppo) e stampa
il tempo impiegato per ogni azienda.
I dati di esempio si caricano anche al primo avvio con `KHAEMHAT_SEED_DEMO=true`.
## Migrazioni
+47 -11
View File
@@ -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 · documento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-documento.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 · tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-tema-scuro.png)
*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 · anteprima di stampa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/stampa-anteprima.png)
*Khaemhat 0.3.0 — l'anteprima di stampa del documento di prova.*
## Regola di aggiornamento
+91
View File
@@ -0,0 +1,91 @@
# Dichiarazioni d'intento
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** CORE · **Permessi principali:** `sales.intent.read` (registro e stampa), `sales.intent.write`
> (inserire, modificare, revocare) · **Specifica:** SPEC §11.7, ADR 0042
Gli **esportatori abituali** acquistano senza IVA, entro un **plafond**, presentando al fornitore una **dichiarazione
d'intento** trasmessa all'Agenzia delle Entrate. Khaemhat tiene il **registro cronologico** delle dichiarazioni
ricevute dai clienti (e di quelle emesse verso i fornitori), aggiorna l'**utilizzato** con le fatture emesse,
avvisa quando il plafond è quasi esaurito e **rifiuta la conferma** di una fattura senza dichiarazione valida o oltre
il plafond.
## Dove si trova
**Fatturazione elettronica → Dichiarazioni d'intento** (anche all'indirizzo `/vendite/dichiarazioni-intento`). La
funzione è nel modulo base CORE.
![Khaemhat 0.10.0 · dichiarazioni d'intento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/dichiarazioni-intento.png)
*Il registro delle dichiarazioni ricevute nel 2026: la dichiarazione di Idrotermica Piemonte con protocollo
telematico, plafond, utilizzato, residuo e percentuale di utilizzo.*
## Il registro
Due schede: **Ricevute (clienti)** ed **Emesse (fornitori)**, filtrate per esercizio.
| Colonna | Significato |
|---|---|
| **Numero**, **Data** | numero progressivo del registro e data della dichiarazione |
| **Cliente** / **Fornitore**, **Codice** | la controparte |
| **Protocollo telematico** | protocollo della ricevuta dell'Agenzia: 17 cifre, trattino (o barra) e 6 cifre di progressivo |
| **Plafond**, **Utilizzato**, **Residuo** | importo dichiarato, fatture già emesse, quanto resta |
| **Esercizio** | anno di riferimento |
| **Stato** | *Attiva* (con la percentuale di utilizzo, in arancione dal 90 %), *Esaurita*, *Revocata* |
**Stampa registro** produce il PDF del registro dell'anno.
## Registrare una dichiarazione ricevuta
1. **Nuova dichiarazione**, scheda *Ricevute*.
2. Scegli il **cliente**, scrivi numero e data, il **protocollo telematico** e il **plafond**.
3. Indica il periodo di validità (**valida dal**, **valida al**): ogni fattura va sulla dichiarazione più recente che ne copre la data.
4. L'**utilizzato** si aggiorna da solo con le fatture: compilalo solo se una parte del plafond è già stata usata con
fatture emesse fuori da Khaemhat.
5. Salva. Il cliente riceve una copia della dichiarazione corrente nei suoi dati fiscali, usata dai documenti e dalla
fattura elettronica.
Una dichiarazione si **revoca** (per esempio quando il cliente la annulla) e da quel momento non copre più le
fatture. Il plafond non può scendere sotto l'utilizzato; una dichiarazione mai usata si può eliminare.
## Fatturare a un esportatore abituale
1. Nella fattura usa per le righe il codice IVA di **natura N3.5** (*non imponibile a seguito di dichiarazione
d'intento*), di solito impostato come codice IVA preferito del cliente.
2. Alla **conferma** Khaemhat cerca una dichiarazione attiva del cliente valida alla data della fattura:
- se **non c'è**, la conferma è rifiutata con il messaggio *nessuna dichiarazione d'intento valida*;
- se l'imponibile in N3.5 **supera il residuo**, la conferma è rifiutata indicando quanto resta;
- altrimenti la fattura è confermata e l'importo si aggiunge all'**utilizzato**; dal 90 % compare l'avviso.
3. La fattura elettronica riporta gli estremi della dichiarazione nel blocco *AltriDatiGestionali* con tipo
`INTENTO` (vedi [Fatturazione elettronica](Fatturazione-elettronica)).
Le note di credito in N3.5 riducono l'utilizzato; eliminare o annullare una fattura lo ricalcola.
## Dichiarazioni emesse
Se l'azienda stessa è esportatore abituale registra nella scheda **Emesse** le dichiarazioni inviate ai propri
fornitori, con lo stesso protocollo e plafond: servono come promemoria e per la stampa del registro.
## Dati di esempio
I dati dimostrativi registrano la dichiarazione di **Idrotermica Piemonte** (plafond 150.000 €) ed emettono una
fattura in N3.5 che ne consuma una parte; una fattura in N3.5 a un cliente senza dichiarazione viene rifiutata.
## Permessi e licenza
| Permesso | Consente |
|---|---|
| `sales.intent.read` | registro e stampa |
| `sales.intent.write` | inserire, modificare e revocare le dichiarazioni |
## Domande frequenti
**La fattura non si conferma: «plafond superato».** Il residuo della dichiarazione non basta. Chiedi al cliente una
nuova dichiarazione (o un'integrazione del plafond) e registrala, oppure fattura la parte eccedente con IVA.
**Avevo scritto il protocollo nell'anagrafica del cliente.** Le dichiarazioni inserite nei dati fiscali del cliente
prima della versione 0.10 diventano automaticamente righe del registro alla prima apertura.
## Pagine correlate
[Vendite](Vendite) · [Anagrafiche](Anagrafiche) · [IVA](IVA) · [Fatturazione elettronica](Fatturazione-elettronica) ·
[Intrastat](Intrastat) · [Fiscalità italiana](Fiscalita-italiana)
+270 -141
View File
@@ -1,200 +1,329 @@
# Fatturazione elettronica e canali SDI
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M9)
> **Modulo di licenza:** EINV · **Permessi principali:** `sales.invoice.issue`, `einvoice.document.send`, `einvoice.channel.manage`, `einvoice.inbox.import` · **Specifica:** SPEC §11.9, §11.3, §11.5, §9.4
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** EINV · **Permessi principali:** `einvoice.document.read` (cruscotto, notifiche,
> conservazione), `einvoice.document.send` (generare, inviare, importare notifiche), `einvoice.inbox.read` e
> `einvoice.inbox.import` (fatture ricevute), `einvoice.channel.manage` (canali e instradamento) · **Specifica:**
> SPEC §11.9, ADR 0039 e 0040
## A cosa serve
Il modulo produce il **file FatturaPA** delle fatture emesse, lo **controlla** come farebbe il Sistema di
Interscambio (SDI), lo **trasmette** attraverso il canale scelto dalle regole di instradamento e segue le
**notifiche** che tornano indietro (consegna, scarto, mancata consegna, esito della pubblica amministrazione). Dalla
stessa sezione arrivano le **fatture dei fornitori**, che si registrano come fatture di acquisto, e si prepara il
**pacchetto per la conservazione**.
Il modulo genera l'**XML FatturaPA** delle fatture emesse, lo **valida**, lo **trasmette al Sistema di
Interscambio (SDI)** attraverso uno dei canali configurati, importa le **notifiche** e le **fatture passive**,
gestisce le **autofatture** da inviare e prepara il **pacchetto per la conservazione**. Il **cruscotto SDI** riunisce
tutto in una schermata ordinata per priorità.
Lo SDI è il sistema dell'Agenzia delle Entrate e non fa parte di Khaemhat. Per raggiungerlo Khaemhat offre quattro
canali con lo stesso modo di lavorare: la **PEC dell'azienda** (nessun servizio esterno), il web service **SdICoop**
e **due intermediari** accreditati.
Lo SDI è il sistema dell'Agenzia delle Entrate e non può essere "inglobato" in un gestionale. Khaemhat include però un
**canale proprio via PEC** che non richiede alcun servizio esterno, e supporta con la stessa interfaccia **SdICoop**
(web service dell'Agenzia) e **due intermediari**.
> **In questa versione** ci sono il file FatturaPA (`FPR12`, `FPA12`, `FSM10`) con controllo prima dell'invio, i
> quattro canali con prova di connessione, pausa e regole di instradamento con canale di riserva, la lettura
> automatica dei canali ogni 15 minuti, la ricezione push di SdICoop, l'import manuale delle notifiche, la correzione
> delle fatture scartate, la copia di cortesia in PDF con l'XML allegato, le fatture ricevute con registrazione in
> blocco, l'elenco delle notifiche e i pacchetti per la conservazione. Dalla 0.10 il menu comprende anche
> [Intrastat](Intrastat) e le [dichiarazioni d'intento](Dichiarazioni-d-intento), i cui estremi entrano nel file
> (`AltriDatiGestionali` di tipo `INTENTO`). Arriva più avanti il formato europeo **EN 16931 / UBL** ([Roadmap](Roadmap)).
## Dove si trova
Menu laterale **Fatturazione elettronica**: **Cruscotto SDI**, **Fatture emesse**, **Fatture ricevute**,
**Notifiche**, **Bollo virtuale**, **Intrastat**, **LIPE**; la configurazione dei canali è in **Fatturazione
elettronica → Canali**. Il contatore accanto alla voce di menu indica i documenti che richiedono attenzione.
Bollo virtuale, dichiarazioni d'intento e LIPE sono descritti nella pagina [IVA](IVA), Intrastat in [Intrastat](Intrastat).
Menu laterale **Fatturazione elettronica** → *Cruscotto SDI*, *Fatture ricevute*, *Notifiche SDI*,
*Conservazione*, *Canali di trasmissione* (e *Dichiarazioni d'intento*, ancora da sviluppare).
## Schermate
Il menu compare solo se la licenza comprende il modulo **EINV** e l'utente ha i permessi (vedi
[Licenze e moduli](Licenze-e-moduli) e [Utenti e permessi](Utenti-e-permessi)). Ogni voce chiede il suo permesso:
chi non ha `einvoice.channel.manage`, per esempio, non vede i canali.
![058 · Cruscotto SDI](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/058-cruscotto-sdi.png)
*Mockup 058 — cruscotto con i contatori per stato (da generare, da inviare, inviate in attesa, consegnate, scartate, mancata consegna), azioni Genera + invia, Correggi, Importa notifiche e l'elenco dei documenti con TD, canale, stato SDI e ultima notifica o errore*
Prima di iniziare servono:
![059 · Canali di trasmissione SDI](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/059-canali-trasmissione-sdi.png)
*Mockup 059 — i quattro canali (PEC integrata, SdICoop, Intermediario A, Intermediario B) con il loro stato, le regole di instradamento e le impostazioni della casella PEC*
- il **profilo dell'azienda** completo in [Impostazioni](Impostazioni): partita IVA, codice fiscale, sede e
**regime fiscale** (RF01…). Senza questi dati la generazione si ferma con un messaggio che dice cosa manca;
- per ogni cliente il **codice destinatario** o la **PEC**, e per la pubblica amministrazione il **codice
ufficio IPA** di sei caratteri ([Anagrafiche](Anagrafiche));
- almeno un **canale attivo** (vedi [I canali di trasmissione](#i-canali-di-trasmissione)). Senza canali si può
comunque generare il file, caricarlo dal portale *Fatture e Corrispettivi* e segnarlo come inviato.
## Il ciclo di una fattura
1. La fattura viene **confermata ed emessa** in [Vendite](Vendite) (numero definitivo, sola lettura).
2. **Genera XML**: Khaemhat produce il file FatturaPA e lo allega al documento (bloccato dopo l'invio).
3. **Valida**: il validatore controlla il file prima dell'invio.
4. **Invia**: il canale scelto dalle regole di instradamento trasmette il file allo SDI.
5. **Notifiche**: lo SDI risponde con ricevute e notifiche che aggiornano lo stato del documento.
1. La fattura, la nota di credito, la parcella o l'autofattura viene **confermata** in [Vendite](Vendite) o in
[Acquisti](Acquisti): da quel momento ha il numero definitivo e compare fra i *documenti da generare*.
2. **Genera**: Khaemhat scrive il file FatturaPA e lo controlla. Il documento passa a *XML generato*.
3. **Invia**: il canale scelto dalle regole di instradamento trasmette il file. Il documento passa a *Inviato*.
4. **Notifiche**: lo SDI risponde e lo stato del file e del documento cambia da solo.
Il pulsante **Genera + invia** esegue i passi 2-4 sui documenti selezionati.
Il pulsante **Genera + invia** fa i passi 2 e 3 in un colpo solo sui documenti selezionati.
| Stato del documento | Quando |
|---|---|
| **Bozza** | fattura in lavorazione |
| **Emessa** | confermata, senza XML (*Da generare*) |
| **XML generato** | XML prodotto e validato (*Da inviare*) |
| **Inviata** | trasmessa allo SDI, in attesa di ricevuta |
| **Consegnata** | ricevuta di consegna (RC) |
| **Scartata** | notifica di scarto (NS): va corretta e rigenerata |
| **Mancata consegna** | lo SDI non è riuscito a recapitarla (MC) |
| Stato del file | Quando | Stato del documento |
|---|---|---|
| **Generata** | file scritto e controllato, non ancora trasmesso | XML generato |
| **Inviata** | trasmessa allo SDI, in attesa della ricevuta | Inviato |
| **Consegnata** | ricevuta di consegna (RC) | Consegnato |
| **Scartata** | notifica di scarto (NS): la fattura **non è emessa** e va corretta | Scartato |
| **Mancata consegna** | lo SDI non è riuscito a recapitarla (MC): è comunque emessa | Non consegnato |
| **Accettata** / **Rifiutata** | esito del committente PA, EC01 o EC02 (NE) | |
| **Decorrenza termini** | la PA non ha risposto entro 15 giorni (DT) | |
| **Impossibile recapitare** | attestazione di trasmissione verso una PA (AT) | |
Una fattura emessa non si modifica: se l'XML **non è ancora stato inviato** si può annullare indicando il motivo;
altrimenti si emette una nota di credito. Una fattura **scartata** non è emessa ai fini fiscali: con **Correggi** si
corregge il dato e si rigenera l'XML (nuova versione dell'allegato).
## Cruscotto SDI
## L'XML FatturaPA
![Khaemhat 0.9.0 · cruscotto SDI con i contatori, i documenti da generare e i file trasmessi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-cruscotto.png)
*Khaemhat 0.9.0 — il cruscotto dell'azienda di esempio: i sei contatori, i documenti emessi senza file e i file
trasmessi con stato SDI, canale, ultima notifica e azioni.*
In alto sei **contatori**: *Da generare* (documenti emessi senza XML), *Da inviare* (file generati e controllati),
*Inviate in attesa*, *Consegnate* (RC, esito EC01, decorrenza termini), *Scartate* e *Mancata consegna*. Sopra, a
destra, il collegamento alle **fatture ricevute da registrare**, **Importa notifiche** e, per chi gestisce i canali,
**Leggi i canali ora**.
Il pannello ha tre viste:
- **Emesse**: fatture, note di credito e parcelle verso i clienti;
- **Autofatture**: i documenti TD16-TD29 nati dagli [acquisti](Acquisti) (integrazioni del reverse charge,
servizi e beni dall'estero, estrazione da deposito IVA, splafonamento…), che vanno trasmessi **entro il 15 del
mese successivo**;
- **Da fare**: solo ciò che chiede un intervento, cioè documenti da generare, file da inviare, scartati, non
consegnati e rifiutati. Gli avvisi della Home su fatture scartate o da inviare portano qui.
Sotto la vista si filtrano **stato** e **periodo** e si cerca per numero, nome del file, identificativo SDI o
controparte.
### Documenti da generare
La prima tabella elenca i documenti confermati che non hanno ancora un file. Si selezionano e si preme **Genera +
invia**; **Controlla senza generare** (icona a forma di scudo) prova il file senza salvarlo e mostra gli errori,
utile per sistemare i dati prima di trasmettere.
![Khaemhat 0.9.0 · il controllo di un documento prima della generazione](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-controllo.png)
*Khaemhat 0.9.0 — Controlla senza generare: il file supera i controlli dello SDI.*
### File trasmessi
La seconda tabella ha un file per riga: nome (`IT01234567890_0000A.xml`), documento, cliente, data, totale, tipo
documento, **canale**, **stato SDI** e **ultima notifica o errore** con la data. I file *Generata* hanno la casella
per **Invia (n)**. Le azioni della riga:
| Azione | Quando | Cosa fa |
|---|---|---|
| **Correggi** | file scartato | apre il documento, che torna modificabile; dopo la correzione si genera un **nuovo file** con un nuovo progressivo, il vecchio resta nello storico come *sostituito* |
| **Segna come inviata** | file generato | per chi lo ha caricato dal portale *Fatture e Corrispettivi*: si può indicare l'identificativo SDI; le notifiche si importano poi a mano |
| **XML** | sempre | scarica il file trasmesso |
| **Copia di cortesia (PDF)** | sempre | il PDF del documento con il file FatturaPA **allegato dentro il PDF**, da mandare al cliente: non sostituisce l'invio allo SDI |
| **Storico del file** | sempre | tutte le versioni del file con generazione, invio, identificativo SDI e notifiche |
![Khaemhat 0.9.0 · lo storico di un file scartato e rigenerato](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-storico.png)
*Khaemhat 0.9.0 — lo storico SDI di una fattura: la prima versione scartata con l'errore dello SDI, sostituita da
quella corretta e consegnata.*
Dopo **Invia** o **Genera + invia** una finestra riassume l'esito file per file: preso in carico da quale canale,
oppure il motivo per cui non è partito.
![Khaemhat 0.9.0 · l'esito della trasmissione](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-esito-invio.png)
*Khaemhat 0.9.0 — esito della trasmissione di due file.*
![Khaemhat 0.9.0 · la vista Da fare](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-da-fare.png)
*Khaemhat 0.9.0 — la vista Da fare: documenti da generare e file scartati o non consegnati.*
## Il file FatturaPA
| Formato | Uso |
|---|---|
| `FPR12` | fatture verso privati (aziende e consumatori) |
| `FPA12` | fatture verso la Pubblica Amministrazione |
| `FPA12` | fatture verso la pubblica amministrazione |
| `FSM10` | fattura semplificata |
Khaemhat segue le **specifiche tecniche dell'Agenzia delle Entrate**: alla stesura di questa pagina la **versione
1.9, in vigore dal 1° aprile 2025** (con il tipo documento TD29 e il TD20 ridefinito). La versione supportata è
indicata nel programma; prima di ogni rilascio va **sempre verificata l'ultima versione pubblicata** dall'Agenzia.
Khaemhat segue le **specifiche tecniche 1.9.1** dell'Agenzia delle Entrate (tipi documento fino a TD29). La
versione è scritta nel pacchetto fiscale italiano; prima di ogni rilascio va confrontata con l'ultima pubblicata
dall'Agenzia.
L'XML contiene, fra l'altro: dati di trasmissione, cedente e cessionario, dati generali con tipo documento (TD),
ritenuta, bollo, cassa previdenziale, sconti e causale; riferimenti a ordine d'acquisto, contratto, convenzione,
ricezione e fatture collegate (con CIG e CUP per la PA); DDT, trasporto, righe di dettaglio, riepilogo IVA,
pagamento e allegati.
Il file contiene i dati di trasmissione, cedente e cessionario (con stabile organizzazione e rappresentante fiscale
quando servono), i dati generali con tipo documento, ritenute, bollo virtuale, cassa previdenziale, sconti e
causale, i riferimenti a ordine, contratto, convenzione, ricezione e fatture collegate (con CIG e CUP per la PA),
DDT e trasporto, le righe, il riepilogo IVA con nature ed esigibilità, i pagamenti e gli allegati.
**Nome del file**: `IT<identificativo fiscale del trasmittente>_<progressivo>.xml`, con progressivo alfanumerico
univoco in base 36 (es. `IT01234567890_00A1Z.xml`).
**Nome del file**: `IT` + identificativo fiscale del trasmittente + `_` + progressivo di cinque caratteri in base 36
(per esempio `IT01234567890_0000A.xml`). Il progressivo non si ripete mai: un file rigenerato dopo uno scarto ne
prende uno nuovo.
## Validazione e scarti noti
### I controlli prima dell'invio
Prima dell'invio il validatore controlla:
Il file viene controllato **prima** di partire, con gli stessi codici di errore dello SDI, così il messaggio è
quello che si leggerebbe nello scarto:
- valori ammessi delle code list (TD, nature, modalità di pagamento, regime fiscale…) e lunghezze dei campi;
- totali coerenti con tolleranza di ± 0,01;
- **nature IVA** (`N1`…`N7` con sotto-codici) e relativi riferimenti normativi;
- codice destinatario o PEC del cliente; per la **PA** codice IPA a 6 caratteri, CIG e CUP quando servono;
- codice fiscale dei gruppi IVA;
- bollo virtuale.
- **struttura** del file contro lo schema del formato;
- **totali**: `PrezzoTotale` e imposta con tolleranza di un centesimo, imponibile del riepilogo con tolleranza di un
euro (00421, 00422, 00423);
- **riepilogo IVA** presente per ogni aliquota e natura (00419);
- **nature IVA** e aliquote su righe, cassa previdenziale e riepilogo (00400, 00401, 00413, 00414, 00429, 00430),
con i sotto-codici obbligatori al posto delle nature generiche N2, N3 e N6 (00445);
- **ritenute** (00411, 00415) e **sconti e maggiorazioni** (00437, 00438);
- **cliente**: partita IVA o codice fiscale presenti e ben formati (00305, 00306, 00417), codice destinatario e PEC
coerenti con il formato (00311, 00426, 00427);
- **autofatture**: cedente e cessionario devono essere diversi o uguali secondo il tipo (00471, 00472, 00473).
Esempi di scarto dello SDI visti nel cruscotto e usati nei test: **00311** (CodiceDestinatario non valido),
**00423** (PrezzoTotale non calcolato correttamente), **00327**. Il messaggio dell'errore compare nella colonna
*Ultima notifica / errore*.
Alcuni controlli richiedono i registri dell'Agenzia (partita IVA esistente, codice destinatario accreditato, codice
IPA presente nell'indice delle PA): Khaemhat ne verifica solo la **forma**.
## I quattro canali di trasmissione
> Lo schema usato per il controllo della struttura è scritto per Khaemhat sulle regole del formato 1.2: non è il file
> XSD ufficiale dell'Agenzia, che non è incluso. Gli scarti più comuni sono comunque coperti dai controlli di
> contenuto.
Tutti i canali hanno la stessa interfaccia (invia, stato, notifiche, scarica passive): cambiare canale non cambia il
modo di lavorare.
## Le notifiche dello SDI
| Canale | Come funziona | Pro | Contro |
|---|---|---|---|
| **PEC integrata** | l'XML parte come allegato dalla **PEC aziendale** (SMTP) verso la PEC dello SDI; notifiche e fatture passive si leggono dalla stessa casella con il client **IMAP** interno, filtrando per mittente e oggetto e archiviando in una cartella | nessun servizio esterno, nessun accreditamento, costo della sola casella PEC | più lento; i volumi elevati vanno distribuiti (regola di *throttling*); dipende dalla disponibilità della casella; non include la conservazione |
| **SdICoop** | web service dell'Agenzia; richiede l'**accreditamento** e un **certificato** rilasciato all'azienda; Khaemhat costruisce la chiamata SOAP con certificato client | notifiche e fatture passive in tempo reale; adatto ai volumi alti | procedura di accreditamento; certificato da rinnovare (il mockup ne mostra la scadenza); per ricevere, lo SDI deve raggiungere un servizio dell'azienda: i requisiti di rete saranno verificati in sviluppo |
| **Intermediario A** | connettore REST verso il servizio di un intermediario accreditato: upload dell'XML, stato, notifiche, download delle passive | semplice da attivare; la **conservazione a norma** può essere inclusa nel servizio | costo del servizio; dipendenza da un terzo; credenziali e token API con scadenza |
| **Intermediario B** | secondo connettore REST, stessa interfaccia, con la propria mappatura di stati ed errori | alternativa o riserva al primo | come l'intermediario A |
![Khaemhat 0.9.0 · elenco delle notifiche SDI](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-notifiche.png)
*Khaemhat 0.9.0 — Notifiche SDI: ogni ricevuta con il file a cui si riferisce, scaricabile così come è arrivata.*
Gli intermediari A e B sono i due servizi scelti dal titolare del progetto; le credenziali sono conservate cifrate.
| Sigla | Notifica | Effetto |
|---|---|---|
| **RC** | ricevuta di consegna | *Consegnata* |
| **NS** | notifica di scarto, con codice e descrizione degli errori | *Scartata*: correggi e rigenera; l'Agenzia indica di ritrasmettere entro 5 giorni |
| **MC** | mancata consegna | la fattura è emessa ma il cliente la trova nel suo cassetto fiscale: conviene mandargli la **copia di cortesia** |
| **NE** | esito del committente PA: **EC01** accettazione, **EC02** rifiuto | *Accettata* o *Rifiutata*; un rifiuto richiede una nota di credito |
| **DT** | decorrenza termini (PA) | *Decorrenza termini*: vale come consegna |
| **AT** | attestazione di avvenuta trasmissione con impossibilità di recapito (PA) | *Impossibile recapitare* |
| **SE** | scarto dell'esito inviato dal committente PA | conservata fra le notifiche |
| **MT** | file metadati di una fattura ricevuta | tenuto con la fattura in *Fatture ricevute* |
### Configurare il canale PEC
Le notifiche arrivano in tre modi:
1. **Fatturazione elettronica → Canali**, riquadro **PEC · impostazioni**.
2. Inserisci **Casella PEC**, server **SMTP** (es. porta 465) e **IMAP** (es. porta 993), la frequenza del
**Controllo notifiche** (es. ogni 15 minuti) e la **Cartella archivio**.
3. Premi **Prova connessione**, poi **Salva**. Il riquadro del canale mostra casella, ultimo controllo e notifiche lette.
- **dai canali**, con l'attività programmata *Lettura dei canali SDI* (`einvoice.poll`) **ogni 15 minuti**, o subito
con **Leggi i canali ora**;
- **in push da SdICoop**, appena lo SDI le consegna (vedi sotto);
- **a mano** con **Importa notifiche** sul cruscotto: file XML, P7M o lo ZIP scaricato dal portale. La stessa
notifica non viene importata due volte.
Il primo invio via PEC va all'indirizzo `sdi01@pec.fatturapa.it`; con la prima risposta lo SDI indica l'indirizzo
PEC da usare per gli invii successivi. La gestione di questo indirizzo sarà verificata in sviluppo.
Nella pagina **Notifiche SDI** si filtrano periodo (dal 1° gennaio a oggi in partenza) e tipo. Le righe evidenziate
sono notifiche che non corrispondono a nessun file emesso.
## Fatture ricevute
![Khaemhat 0.9.0 · fatture ricevute dai fornitori](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-ricevute.png)
*Khaemhat 0.9.0 — Fatture ricevute: le fatture dei fornitori da registrare, con fornitore, numero, totale, tipo,
canale e identificativo SDI.*
Le fatture dei fornitori arrivano dai canali o si caricano con **Carica file**: XML, **P7M** firmati CAdES (anche
annidati o in base64; l'XML viene estratto dalla busta), il file metadati e lo ZIP del portale. Lo stesso file non
entra due volte (impronta SHA-256).
| Stato | Significato |
|---|---|
| **Da registrare** | arrivata, da trasformare in fattura di acquisto |
| **Registrata** | diventata una fattura o nota di credito di acquisto: **Apri** la porta al documento |
| **Scartata** | messa da parte a mano (**Ripristina** la riporta indietro) |
| **Illeggibile** | il file non è una FatturaPA leggibile: l'errore è scritto sotto lo stato |
Si selezionano le fatture e si preme **Registra (n)**, oppure **Registra come fattura di acquisto** sulla riga.
La registrazione usa l'import del ciclo passivo ([Acquisti](Acquisti)): il fornitore si riconosce dalla partita
IVA e, se manca, viene creato; righe, IVA e scadenze vengono dal file. Gli avvisi dell'import compaiono nel messaggio
di esito.
## I canali di trasmissione
![Khaemhat 0.9.0 · canali di trasmissione e regole di instradamento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-canali.png)
*Khaemhat 0.9.0 — i quattro canali con il loro stato, le impostazioni del canale scelto e le regole di
instradamento.*
Tutti i canali fanno le stesse cose (inviare, leggere notifiche e fatture ricevute, provare la connessione): cambiare
canale non cambia il modo di lavorare. Ogni scheda mostra lo stato (*Attivo*, *Configurato · in pausa*, *Non
configurato*), l'ultima prova e l'ultima lettura. Password, chiavi e certificati sono **cifrati** nel database; nel
modulo un campo segreto lasciato vuoto mantiene il valore memorizzato.
| Canale | Come funziona | Impostazioni |
|---|---|---|
| **PEC** | il file parte come allegato dalla PEC dell'azienda (SMTP) verso lo SDI; ricevute e fatture si leggono dalla stessa casella (IMAP) e i messaggi letti vanno nella cartella di archivio | casella, server e porte SMTP e IMAP, TLS, utente, password, indirizzo PEC dello SDI, cartella di archivio |
| **SdICoop** | web service dell'Agenzia con **certificato client**; lo SDI consegna notifiche e fatture al servizio di ricezione di Khaemhat | indirizzo del servizio, certificato PKCS#12 (`.p12`) con password, chiave di ricezione, ambiente di prova |
| **Intermediario A** | API REST di un intermediario accreditato con **chiave API** | indirizzo del servizio, chiave API, ambiente di prova |
| **Intermediario B** | API REST di un intermediario accreditato con **utente e password** | indirizzo del servizio, utente, password, ambiente di prova |
Per ogni canale: **Prova connessione**, **Metti in pausa** / **Riprendi** e **Salva**. Gli indirizzi dei servizi
devono essere `https`.
> **Quale canale usare.** Per iniziare usa la **PEC**: non richiede accreditamento né contratti. *Intermediario A* e
> *Intermediario B* sono connettori generici, provati con servizi simulati: per collegarli a un intermediario reale
> servono le sue API, quindi vanno adattati al fornitore scelto. **SdICoop** richiede l'accreditamento dell'azienda
> presso l'Agenzia delle Entrate, il certificato client e un reverse proxy con verifica reciproca dei certificati
> (mTLS): conviene solo con volumi alti.
**PEC.** Il primo invio va all'indirizzo `sdi01@pec.fatturapa.it`; con la prima risposta lo SDI comunica la casella
da usare da lì in poi, che Khaemhat ricorda e mostra nel campo *Indirizzo PEC dello SDI*. La PEC non richiede
accreditamento ma è il canale più lento: per volumi alti conviene una regola che sposti il traffico su un altro
canale.
Della casella si leggono solo i messaggi dello SDI (mittente `fatturapa.it`); le ricevute di accettazione e consegna
del gestore PEC restano dove sono. Imposta sempre la **cartella di archivio**: i messaggi elaborati vengono spostati
lì. Senza cartella vengono solo segnati come letti, e un messaggio aperto dalla webmail prima della lettura di
Khaemhat verrebbe saltato.
**SdICoop in ricezione.** Lo SDI chiama il servizio `POST /sdicoop/<codice azienda>` di Khaemhat. Il servizio
accetta solo le chiamate con l'intestazione `X-Khaemhat-SdiCoop-Key` uguale alla **chiave di ricezione** del canale.
Il certificato reciproco (mTLS) richiesto dall'Agenzia si configura sul **reverse proxy** davanti a Khaemhat, che
aggiunge l'intestazione: vedi [Installazione con Docker](Installazione-Docker).
### Instradamento
Le **regole di instradamento** decidono quale canale usa ogni documento. Esempio del mockup:
Le regole decidono quale canale usa ogni file. Vale **la prima regola attiva che si applica**, nell'ordine indicato;
il **canale di riserva** si usa se il primo è in pausa, disattivato o non risponde. Senza regole si usa il primo
canale attivo.
| Regola | Canale | Condizione |
|---|---|---|
| Predefinito | PEC | tutti i documenti |
| Clienti PA | SdICoop | cessionario PA (codice IPA) |
| Volumi > 50/giorno | SdICoop | throttling della PEC |
| Conservazione | Intermediario A | pacchetti trimestrali |
| Condizione | Si applica a |
|---|---|
| **Sempre** | tutti i file |
| **Cliente pubblica amministrazione** | i clienti con codice IPA (formato `FPA12`) |
| **Cliente specifico** | il cliente con il codice indicato |
| **Tipo documento** | un tipo (TD01, TD17…) |
| **Volume giornaliero** | i file oltre un numero di invii nella giornata |
Il canale usato è registrato su ogni documento (colonna *Canale* del cruscotto).
## Notifiche SDI
| Sigla | Notifica | Effetto in Khaemhat |
|---|---|---|
| **RC** | ricevuta di consegna | stato *Consegnata* |
| **NS** | notifica di scarto | stato *Scartata*, con codice e descrizione dell'errore; la regola predefinita avvisa l'amministrazione ([Automazioni](Automazioni)) |
| **MC** | mancata consegna | la fattura è emessa ma non recapitata: è messa a disposizione del cliente nella sua area riservata dell'Agenzia; conviene inviargli la **copia di cortesia** |
| **NE** | notifica di esito del committente PA (**EC01** accettazione, **EC02** rifiuto) | stato *Accettata* o *Rifiutata* |
| **DT** | decorrenza termini (PA) | nessun esito del committente nei termini previsti |
| **AT** | attestazione di avvenuta trasmissione con impossibilità di recapito (PA) | come la mancata consegna |
Le notifiche si importano in automatico dal canale (procedura **Import inbox SDI**, pianificata) o con **Importa
notifiche**; restano come allegati del documento ([Allegati e file](Allegati-e-file)). Sono letti anche i
**metadati** che accompagnano le fatture ricevute.
## Fatture passive
Le fatture ricevute arrivano dal canale (PEC, SdICoop o intermediario) o si caricano a mano (anche come file
**P7M** firmati CAdES: la firma viene verificata e l'XML estratto). Khaemhat le legge, riconosce il fornitore da
P.IVA o codice fiscale e prepara la **fattura di acquisto in bozza** con mappatura delle righe e confronto con
l'ordine: il dettaglio è nella pagina [Acquisti](Acquisti) (import XML). La vista **Ricevute** del cruscotto elenca
le passive e il loro stato di importazione.
## Cruscotto SDI
- **Contatori**: *Da generare* (emesse senza XML), *Da inviare* (XML validati), *Inviate · in attesa*,
*Consegnate* (nell'anno), *Scartate* (da correggere), *Mancata consegna*.
- **Elenco prioritizzato**: prima le scartate, poi le da inviare, poi quelle in attesa.
- **Viste**: **Emesse**, **Ricevute**, **Autofatture**.
- **Azioni**: genera, valida, invia, scarica, **Correggi** e rigenera, **Importa notifiche** e passive.
- In testa: canali attivi e ora dell'ultima sincronizzazione.
### Autofatture da inviare
Le autofatture e integrazioni (TD16 reverse charge interno, TD17 servizi dall'estero, TD18 beni intra-UE, TD19, TD20
e TD29, TD21, TD22/TD23, TD28) nascono da [Acquisti](Acquisti) e compaiono nella vista **Autofatture** fino all'invio.
L'XML va trasmesso **entro il 15 del mese successivo**; Khaemhat mostra un promemoria.
## Copia di cortesia
Da ogni fattura si può generare la **copia di cortesia** (PDF + XML in uno ZIP) da inviare al cliente via e-mail o
PEC. Non sostituisce l'invio allo SDI.
Le regole dell'azienda di esempio: PA → PEC; oltre 200 file al giorno → Intermediario A con PEC di riserva;
sempre → PEC con Intermediario A di riserva. Il canale usato resta scritto su ogni file.
## Conservazione
Khaemhat **non è un sistema di conservazione a norma**. Prepara per ogni periodo un **pacchetto di esportazione**
(XML, notifiche e indice) da affidare a un **conservatore** o al servizio messo a disposizione dall'Agenzia delle
Entrate. Se l'intermediario scelto include la conservazione, la regola di instradamento *Conservazione* gli invia i
pacchetti.
![Khaemhat 0.9.0 · pacchetti per la conservazione](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/fatturazione-conservazione.png)
*Khaemhat 0.9.0 — la preparazione di un pacchetto e l'elenco di quelli già preparati con l'impronta.*
## Sviluppi futuri
Khaemhat **non è un sistema di conservazione a norma**: prepara il materiale da consegnare al conservatore (o al
servizio gratuito dell'Agenzia). Si sceglie il periodo (in partenza il mese precedente, al massimo due anni) e si
preme **Prepara e scarica**: lo ZIP contiene le cartelle `emesse/`, `ricevute/` e `notifiche/`, l'indice
`indice.csv` con l'impronta SHA-256 di ogni file e un `LEGGIMI.txt`. L'elenco dei pacchetti preparati ricorda
periodo, numero di file, dimensione e impronta dello ZIP.
Il formato europeo **EN 16931 / UBL (Peppol)** è previsto come implementazione successiva della stessa interfaccia
dei formati ([Roadmap](Roadmap)).
## Dati di esempio
L'azienda di esempio ([Dati di base e di esempio](Dati-di-base-e-esempio)) ha i canali, le tre regole di
instradamento sopra, alcune fatture già trasmesse con ricevute di consegna,
uno scarto (00305) corretto e rigenerato, una mancata consegna e tre fatture di fornitori da registrare. Nessun
dato di esempio raggiunge lo SDI: il canale PEC dell'esempio è configurato ma **in pausa**, con credenziali finte,
e l'Intermediario A è solo abbozzato e disattivato.
## Permessi e licenza
Serve il modulo **EINV**. `sales.invoice.issue` è il permesso di emissione delle fatture (SPEC §7.2); gli altri
codici in testa sono indicativi e saranno fissati in sviluppo. La configurazione dei canali e delle credenziali è
riservata a chi gestisce le impostazioni dell'azienda.
| Permesso | Cosa consente |
|---|---|
| `einvoice.document.read` | cruscotto, storico, download di XML e copia di cortesia, notifiche, conservazione |
| `einvoice.document.send` | generare, inviare, segnare come inviata, importare le notifiche |
| `einvoice.inbox.read` | vedere le fatture ricevute |
| `einvoice.inbox.import` | caricare, registrare, scartare e ripristinare le fatture ricevute |
| `einvoice.channel.manage` | canali, credenziali, regole di instradamento, *Leggi i canali ora* |
Serve il modulo **EINV**. Le modifiche ai canali e alle regole finiscono nel registro delle modifiche; invii,
notifiche e letture dei canali sono scritti nel [log](Log) dell'applicazione.
## Domande frequenti
**Una fattura è scartata per codice destinatario non valido (00311).** Correggi il codice destinatario o la PEC
nella scheda fiscale del cliente ([Anagrafiche](Anagrafiche)), poi **Correggi** nel cruscotto e reinvia. Secondo le
indicazioni dell'Agenzia la fattura corretta va ritrasmessa entro 5 giorni dallo scarto.
nella scheda del cliente ([Anagrafiche](Anagrafiche)), poi **Correggi** nel cruscotto, salva il documento e genera
di nuovo il file. Secondo l'Agenzia la fattura corretta va ritrasmessa entro 5 giorni dallo scarto, con lo stesso
numero e la stessa data.
**Posso usare più canali insieme?** Sì: le regole di instradamento scelgono il canale per ogni documento.
**Ho inviato la fattura dal portale dell'Agenzia.** Usa **Segna come inviata** con l'identificativo SDI e poi
**Importa notifiche** con le ricevute scaricate dal portale.
**Dove trovo la ricevuta di consegna?** Fra gli allegati della fattura e nella voce **Notifiche**.
**Posso usare più canali insieme?** Sì: le regole di instradamento scelgono il canale per ogni file e il canale di
riserva interviene se il primo non risponde.
**Il cliente non ha ricevuto la fattura (MC).** È comunque emessa: la trova nel suo cassetto fiscale. Mandagli la
**copia di cortesia** dal cruscotto.
**Una PA ha rifiutato la fattura (EC02).** La fattura resta emessa: va stornata con una nota di credito
([Vendite](Vendite)).
## Pagine correlate
+181 -54
View File
@@ -1,21 +1,30 @@
# Fiscalità italiana
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M4-M10)
> **Modulo di licenza:** CORE, ACCT, EINV, INTRA · **Specifica:** SPEC §11.1, §11.3-§11.9, §14
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** CORE, ACCT, EINV, INTRA · **Specifica:** SPEC §11.1, §11.3-§11.9, §14, ADR 0036, ADR 0037, ADR 0038, ADR 0039
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.
SDI, nature IVA, modalità e condizioni di pagamento, regimi fiscali, il **piano dei conti modello**, i **codici
tributo F24** con le scadenze, la **LIPE**, le **ritenute d'acconto** e il **bollo virtuale**. Serve come riferimento
rapido mentre si compilano anagrafiche, codici IVA e documenti e mentre si liquida l'IVA.
Tutte queste tabelle sono **caricate dai dati di base** (pacchetto dati, per esempio `IT 2026.2`) 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.
Tutto ciò che è italiano sta nel **pacchetto fiscale Italia** del programma: le 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** (o con `scripts/seed.sh --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.
> **Attenzione.** Khaemhat calcola e prepara i dati (F24, LIPE, Intrastat, bollo) ma **non sostituisce il
> commercialista** né invia F24 e LIPE: l'invio telematico avviene tramite intermediario o home banking, come
> indicato nella maschera della liquidazione. Le norme cambiano: la versione delle specifiche SDI supportata è
> indicata nel programma ed è verificata a ogni rilascio.
> **In questa versione** sono in uso i codici dei documenti, delle nature, dei pagamenti e dei regimi (dalla 0.4),
> e con la 0.7 il piano dei conti *PMI standard*, i registri IVA, le regole della liquidazione e dell'acconto, i
> codici tributo e le scadenze dell'F24, il tracciato LIPE, le ritenute d'acconto e il bollo virtuale. Con la 0.9 il
> file FatturaPA e le notifiche SDI sono in uso nella [Fatturazione elettronica](Fatturazione-elettronica). Con la 0.10
> sono in uso anche le regole di [Cespiti](Cespiti), [Intrastat](Intrastat),
> [dichiarazioni d'intento](Dichiarazioni-d-intento) e lo schema del bilancio CEE ([Chiusura e bilancio](Chiusura-e-bilancio)).
> **Attenzione.** Khaemhat calcola e prepara i dati (F24, LIPE, Certificazione Unica, bollo) ma **non sostituisce il
> commercialista** né invia F24, LIPE e CU: l'invio telematico avviene con i servizi dell'Agenzia delle Entrate,
> l'home banking o l'intermediario, come ricordato nelle maschere. Le norme cambiano: la versione delle specifiche SDI
> supportata (oggi la 1.9.1) è scritta nel pacchetto fiscale ed è verificata a ogni rilascio.
## Dove si trovano questi codici nel programma
@@ -25,10 +34,12 @@ caso di dubbio fa fede il testo mostrato dal programma, non questa pagina.
| Nature IVA (N…) | **Tabelle azienda → Codici IVA** | [Tabelle-azienda](Tabelle-azienda), [IVA](IVA) |
| Modalità di pagamento (MP) | **Tabelle azienda → Metodi di pagamento** | [Tabelle-azienda](Tabelle-azienda) |
| Regime fiscale (RF) | **Tabelle azienda → Profilo azienda**, scheda fornitore | [Tabelle-azienda](Tabelle-azienda), [Anagrafiche](Anagrafiche) |
| Codici tributo F24 | liquidazione IVA, ritenute, bollo virtuale | [IVA](IVA), [Contabilita](Contabilita) |
| Piano dei conti, causali, registri IVA | **Contabilità → Piano dei conti**, *Causali*, *Registri IVA* | [Contabilita](Contabilita), [IVA](IVA) |
| Codici tributo F24 | liquidazione IVA, acconto, ritenute, bollo virtuale | [IVA](IVA) |
| Tipi di ritenuta (RT) e casse (TC) | scheda fiscale del fornitore e del cliente, parcelle, fatture dei professionisti | [Anagrafiche](Anagrafiche), [IVA](IVA#ritenute-dacconto) |
![076 · Codici IVA con nature SDI](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/076-codici-iva.png)
*Mockup 076 — tabella dei codici IVA con aliquota, natura SDI, riferimento normativo ed esigibilità; sotto, il dettaglio del codice selezionato (anteprima ridotta).*
![Khaemhat · codici IVA con natura SDI](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/tabelle-codici-iva.png)
*La tabella dei codici IVA dell'azienda in Tabelle azienda: ogni codice porta aliquota o natura SDI.*
## Tipi documento SDI (TD)
@@ -58,6 +69,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 +84,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 +93,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).
@@ -151,71 +179,170 @@ fatture passive. Il codice RF03 non esiste più nelle specifiche correnti.
| MC | Mancata consegna | fattura **non consegnata**: messa a disposizione nell'area riservata del cliente |
| NE | Notifica di esito (PA: EC01 accettazione, EC02 rifiuto) | esito del committente pubblico |
| DT | Decorrenza termini | la PA non ha risposto nei termini |
| AT | Attestazione di avvenuta trasmissione con impossibilità di recapito (PA) | fattura **impossibile da recapitare** |
Il dettaglio di come Khaemhat usa ogni notifica è nella pagina [Fatturazione elettronica](Fatturazione-elettronica#le-notifiche-dello-sdi).
| AT | Attestazione di avvenuta trasmissione con impossibilità di recapito | come mancata consegna, per la PA |
I dettagli operativi sono in [Fatturazione-elettronica](Fatturazione-elettronica).
## Piano dei conti modello
Il pacchetto fiscale porta il piano dei conti **PMI standard**: **240 conti** in tre livelli con codice `MM.CC.SSS`
(mastro, conto, sottoconto), ognuno con natura, tipo e voce dello schema di bilancio civilistico (art. 2424 e 2425
c.c.). Si carica con le tabelle di base dell'azienda e si modifica liberamente da **Contabilità → Piano dei conti**
(vedi [Contabilità](Contabilita#piano-dei-conti)).
| Mastri | Natura | Contenuto |
|---|---|---|
| `01`-`09` | Attività | immobilizzazioni immateriali, materiali e finanziarie, rimanenze, crediti verso clienti, altri crediti (IVA, tributi), disponibilità liquide, ratei e risconti attivi, fondi di ammortamento |
| `10`-`17` | Passività | patrimonio netto, fondi rischi, TFR, debiti verso banche, fornitori, debiti tributari e previdenziali, altri debiti, ratei e risconti passivi |
| `20`-`29` | Costi | acquisti, servizi, godimento di beni di terzi, personale, ammortamenti, variazioni delle rimanenze, accantonamenti, oneri diversi, oneri finanziari, imposte sul reddito |
| `30`-`32` | Ricavi | vendite e prestazioni, altri ricavi e proventi, proventi finanziari |
| `90` | Conti d'ordine | conti di apertura e chiusura |
I conti usati dalle registrazioni automatiche:
| Conto | Uso |
|---|---|
| `05.01.001` Clienti Italia | cliente delle fatture di vendita (se la scheda cliente non indica un altro conto) |
| `14.01.001` Fornitori Italia | fornitore delle fatture di acquisto |
| `30.01.001` Ricavi per vendita di merci, `30.02.001` Resi e sconti su vendite | ricavi delle fatture e delle note di credito senza conto sull'articolo |
| `20.01.001` Merci c/acquisti, `20.02.001` Resi e sconti su acquisti | costi delle fatture e note di credito fornitore senza conto sull'articolo o sul fornitore |
| `06.02.001` IVA su acquisti, `15.01.001` IVA su vendite | IVA dei registri acquisti e vendite |
| `15.01.002` Erario c/liquidazione IVA | saldo della liquidazione periodica e suo versamento |
| `15.02.001` Erario c/ritenute lavoro autonomo, `06.03.001` Erario c/ritenute subite | ritenute operate e subite |
| `31.01.002` Rimborso spese di bollo, `27.01.002` Imposta di bollo | bollo addebitato al cliente (ricavo) e bollo a carico dell'azienda (costo) |
| `31.01.003` Rivalsa contributi previdenziali | rivalsa della cassa previdenziale sulle parcelle |
| `27.01.003` IVA indetraibile | IVA indetraibile delle autofatture e del pro rata |
| `28.01.003` Interessi sulla liquidazione IVA trimestrale | interessi dei contribuenti IVA trimestrali |
| `07.01.001` Banca c/c, `07.02.001` Cassa contanti | banca predefinita per i versamenti F24, cassa dei corrispettivi |
**Registri IVA di base:** `VEN1` fatture emesse, `ACQ1` fatture acquisti, `CORR` corrispettivi, `VEN-RC` e `ACQ-RC`
per autofatture e integrazioni. **Causali di base:** FV, NCV, FA, NCA, AFRC, CORR, INC, PAG, RIT, RITS, LIQ, F24,
GIRO, SPB, STO (vedi [Contabilità](Contabilita#causali-contabili)). Fatture, note di debito e parcelle si registrano
con FV su VEN1, le note di credito con NCV, le fatture fornitore con FA su ACQ1, le note di credito fornitore con NCA,
le autofatture AF16-AF29 con AFRC su VEN-RC e ACQ-RC.
## Codici tributo F24
Khaemhat propone il codice tributo e prepara i **dati F24** da passare a intermediario o home banking.
Khaemhat propone il codice tributo e prepara i **dati F24** da passare all'home banking o all'intermediario (vedi
[IVA](IVA#prospetto-f24-e-pagamento)).
| Codice | Uso | Maschera |
| Codice | Uso | Dove nasce |
|---|---|---|
| 6001 … 6012 | IVA mensile, da gennaio (6001) a dicembre (6012) | Liquidazione IVA (046) |
| 6031 … 6034 | IVA trimestrale, dal 1° (6031) al 4° trimestre (6034, contribuenti trimestrali "speciali") | Liquidazione IVA |
| 6013 | Acconto IVA mensili | Liquidazione IVA (acconto di dicembre) |
| 6035 | Acconto IVA trimestrali | Liquidazione IVA (acconto di dicembre) |
| 6099 | IVA dovuta in base alla dichiarazione annuale | Liquidazione IVA |
| 1040 | Ritenute su redditi di lavoro autonomo | Ritenute (047) |
| 1038 | Ritenute su provvigioni | Ritenute (047) |
| 2521 … 2524 | Imposta di bollo sulle fatture elettroniche, dal 1° (2521) al 4° trimestre (2524) | Bollo virtuale (060) |
| 6001 … 6012 | IVA mensile, da gennaio (6001) a dicembre (6012) | Liquidazione IVA |
| 6031, 6032, 6033 | IVA trimestrale del 1°, 2° e 3° trimestre | Liquidazione IVA |
| 6099, rateazione `0101` | saldo IVA del 4° trimestre dei trimestrali, versato con la dichiarazione annuale | Liquidazione IVA |
| 6013 | Acconto IVA mensili | Acconto IVA |
| 6035 | Acconto IVA trimestrali | Acconto IVA |
| 1040 | Ritenute su redditi di lavoro autonomo | Ritenute |
| 1038 | Ritenute su provvigioni | Ritenute |
| 1019 | Ritenute del 4% operate dal condominio | tabella dei codici |
| 1001 | Ritenute su retribuzioni e pensioni | tabella dei codici |
| 2521 … 2524 | Imposta di bollo sulle fatture elettroniche, dal 1° (2521) al 4° trimestre (2524) | Bollo virtuale |
![046 · Liquidazione IVA, F24, LIPE](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/046-liquidazione-iva.png)
*Mockup 046 — liquidazione periodica: registri del periodo con controlli, calcolo dell'IVA da versare, riquadro Versamento con codice tributo, scadenza e termine della LIPE.*
Il codice 6034 (4° trimestre dei trimestrali "speciali") non è usato: per i trimestrali ordinari il saldo del 4°
trimestre si versa con il 6099. Il file **Dati F24** è un CSV con separatore `;`: una riga di intestazione (scadenza,
codice fiscale e denominazione dell'azienda), poi una riga per codice della sezione Erario con rateazione o mese,
anno di riferimento, importo a debito, importo a credito e descrizione, e in fondo il saldo. Il tracciato telematico
degli intermediari non viene prodotto.
![047 · Ritenute, casse previdenza, prospetto F24](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/047-ritenute-parcelle-f24.png)
*Mockup 047 — ritenute operate su parcelle e provvigioni con cassa previdenziale ed ENASARCO; in basso il prospetto F24 con i codici 1040, 1038 e IVA.*
## Liquidazione e acconto IVA
| Regola | Valore in Khaemhat | Riferimento |
|---|---|---|
| Periodicità | mensile o trimestrale, dal profilo azienda | |
| Versamento minimo | se il dovuto (con gli interessi) è sotto **25,82 euro** non si versa e passa al periodo dopo | art. 1 c. 4 DPR 100/1998 |
| Interessi dei trimestrali | **1%** sul saldo a debito di ogni trimestre | |
| Pro rata | percentuale di detraibilità del profilo azienda, applicata all'IVA detraibile degli acquisti | art. 19-bis DPR 633/72 |
| Esigibilità differita e split payment | l'IVA resta fuori dal debito del periodo | |
| Acconto di dicembre | **88%** della base con i metodi storico e previsionale, tutto l'importo con il metodo effettivo (operazioni fino al 20 dicembre); non dovuto sotto **103,29 euro**; versamento entro il **27 dicembre** | L. 405/1990 |
## Comunicazione LIPE
La **comunicazione delle liquidazioni periodiche IVA** (art. 21-bis DL 78/2010) si prepara come file XML nel
tracciato **IVP18** dell'Agenzia delle Entrate: un file per trimestre, con un modulo per ogni mese (o uno per il
trimestre). Ogni modulo riporta totale delle operazioni attive e passive, IVA esigibile e detratta, IVA dovuta o a
credito, debito e credito del periodo precedente, interessi, acconto e importo da versare o a credito. Gli importi
hanno la virgola e due decimali. Il file si chiama `IT<codice fiscale>_LI_<anno>_T<trimestre>.xml`; va firmato e
inviato con i servizi dell'Agenzia o dall'intermediario.
| Trimestre | Scadenza della LIPE |
|---|---|
| 1° | 31 maggio |
| 2° | 16 settembre |
| 3° | 30 novembre |
| 4° | fine febbraio dell'anno dopo |
## Ritenute d'acconto e casse previdenziali
| Tipo | Aliquota | Su | Codice F24 | Tipo e causale nell'XML |
|---|---|---|---|---|
| Lavoro autonomo professionale | 20% | tutto il compenso | 1040 | RT01, causale A |
| Lavoro autonomo occasionale | 20% | tutto il compenso | 1040 | RT01, causale M |
| Provvigioni ad agenti e rappresentanti | 23% | 50% della provvigione | 1038 | RT01, causale R |
| Provvigioni ad agenti con dipendenti o terzi | 23% | 20% della provvigione | 1038 | RT01, causale R |
I tipi di ritenuta della fattura elettronica sono **RT01** (persone fisiche), **RT02** (persone giuridiche),
**RT03**-**RT06** (contributi INPS, ENASARCO, ENPAM, altri); le casse previdenziali vanno da **TC01** (avvocati) a
**TC22** (per esempio **TC04** ingegneri e architetti). La ritenuta operata diventa dovuta quando si **paga** la
fattura del professionista (criterio di cassa) e si versa entro il **16 del mese successivo** al pagamento. I dati
della **Certificazione Unica** (compenso lordo, somme non soggette, imponibile, ritenute per percipiente e causale)
si esportano in CSV; la CU si invia con i servizi dell'Agenzia o dall'intermediario.
## Imposta di bollo
| Regola | Valore |
|---|---|
| Quando | fatture senza IVA (esenti, non imponibili, fuori campo) sopra **77,47 euro** |
| Importo | **2,00 euro** per fattura |
| Nature che contano | 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 |
| Versamento | per trimestre: 1° entro il **31 maggio** (2521), 2° entro il **30 settembre** (2522), 3° entro il **30 novembre** (2523), 4° entro **fine febbraio** dell'anno dopo (2524) |
| Importi bassi | se il bollo del 1° trimestre non supera **5.000 euro** si versa con il 2°; se 1° e 2° insieme non superano 5.000 euro, con il 3° (DM 4/12/2023) |
## Scadenze e regole principali
| 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 |
| 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 |
| 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 |
| Liquidazione IVA mensile | versamento entro il **16 del mese successivo** | la conferma della liquidazione segna il periodo come **liquidato** |
| Liquidazione IVA trimestrale | 1°-3° trimestre entro il 16 del secondo mese successivo al trimestre, con **interessi dell'1%**; il 4° trimestre entro il **16 marzo** con il codice 6099 | 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 IVA | importo sotto **25,82 euro** non versato e riportato al periodo successivo | *debito sotto la soglia* nella liquidazione |
| Acconto IVA | entro il **27 dicembre**; metodo **storico**, **previsionale** o **effettivo**; non dovuto sotto 103,29 euro | riquadro *Acconto IVA* della liquidazione |
| LIPE | 1° trimestre entro 31 maggio, 2° entro 16 settembre, 3° entro 30 novembre, 4° entro fine febbraio | file XML dalla liquidazione |
| Ritenute d'acconto operate | versamento entro il **16 del mese successivo** al pagamento della fattura (1040/1038) | la ritenuta diventa dovuta con **Fattura pagata** |
| Bollo virtuale | versamento trimestrale (vedi sopra), con la soglia dei 5.000 euro | elenco da confrontare con quello proposto dall'Agenzia |
| Autofatture e integrazioni (TD16-TD19) | XML da trasmettere **entro il 15 del mese successivo** | promemoria nelle autofatture |
| Fattura differita (TD24) | emissione entro il 15 del mese successivo a quello delle consegne documentate da DDT | procedura **Fatturazione differita** |
| Interessi di mora | D.Lgs. 231/2002 per i ritardi nelle transazioni commerciali | calcolati nei solleciti |
![060 · Bollo virtuale trimestrale](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/060-bollo-virtuale.png)
*Mockup 060 — imposta di bollo del trimestre: fatture con bollo, importo, codice tributo 2524 e scadenza; in fondo la regola dei € 77,47.*
| Interessi di mora | D.Lgs. 231/2002 per i ritardi nelle transazioni commerciali: tasso BCE di riferimento del semestre + 8 punti (10,15% nel primo semestre 2026, 10,40% nel secondo) | nei solleciti e nell'estratto conto dello [Scadenzario](Scadenzario); la tabella dei tassi va aggiornata ogni semestre (ADR 0038) |
## Altri riferimenti usati dal programma
| Tema | Regola | Pagina |
|---|---|---|
| Split payment | IVA versata dalla PA cessionaria (esigibilità **S**) | [Vendite](Vendite) |
| Split payment | IVA versata dalla PA cessionaria (esigibilità **S**): in contabilità l'IVA viene tolta subito al cliente | [Vendite](Vendite), [Contabilita](Contabilita) |
| Reverse charge interno | IVA a carico del cessionario, registri RC vendite e acquisti (IVA neutra) | [Acquisti](Acquisti), [IVA](IVA) |
| Dichiarazione d'intento | operazioni non imponibili N3.5 con controllo di plafond, utilizzato e residuo | [Fatturazione-elettronica](Fatturazione-elettronica) |
| Ritenuta e cassa previdenza | parcelle TD06: cassa (ad esempio 4%) e ritenuta d'acconto; ENASARCO per gli agenti | [Contabilita](Contabilita) |
| Dichiarazione d'intento | operazioni non imponibili N3.5 con controllo di plafond, utilizzato e residuo; protocollo di 17 + 6 cifre; avviso dal 90 % | [Dichiarazioni d'intento](Dichiarazioni-d-intento) |
| Ritenuta e cassa previdenza | parcelle TD06: cassa (ad esempio 4%) e ritenuta d'acconto | [IVA](IVA#ritenute-dacconto) |
| Cespiti | coefficienti del DM 31/12/1988, primo anno al 50%, limiti per le autovetture, beni sotto € 516,46 | [Cespiti](Cespiti) |
| Intrastat | elenchi INTRA cessioni e acquisti, periodicità da soglie, nomenclatura NC8 | [Intrastat](Intrastat) |
| Bilancio | schemi CEE art. 2424 (stato patrimoniale) e 2425 (conto economico), ordinario/abbreviato/micro | [Contabilita](Contabilita) |
| Intrastat | elenchi INTRA cessioni e acquisti, periodicità dalle soglie (50.000 € per le cessioni, 350.000 e 100.000 € per gli acquisti), nomenclatura NC8, file SCAMBI.CEE | [Intrastat](Intrastat) |
| Bilancio | schemi CEE art. 2424 e 2425 c.c., abbreviato (art. 2435-bis) e micro (art. 2435-ter); svalutazione crediti allo 0,5 % (art. 106 TUIR) e TFR nella chiusura | [Chiusura e bilancio](Chiusura-e-bilancio) |
## Domande frequenti
**Dove vedo la versione delle specifiche SDI supportata?** In **Amministrazione → Stato sistema** e nel cruscotto
SDI: è registrata nel programma e aggiornata con i rilasci.
**Quale versione delle specifiche SDI segue Khaemhat?** La 1.9.1 (in Khaemhat 0.9.0): è scritta nel pacchetto
fiscale, riportata nelle note di ogni rilascio e aggiornata quando l'Agenzia pubblica una nuova versione. La pagina
*Stato sistema* la mostrerà con le pagine di amministrazione (M12).
**Una natura o un codice non c'è nella tabella.** Lancia **Aggiorna tabelle di base**: il pacchetto dati porta i
codici correnti. Se manca ancora, segnalalo: le code list sono parte del pacchetto fiscale italiano.
**Khaemhat invia l'F24?** No: prepara i dati e la stampa; l'invio passa da intermediario o home banking.
**Posso usare un mio piano dei conti?** Sì: il modello *PMI standard* si modifica, si ampliano i sottoconti e si
disattivano quelli che non servono. L'import di un piano dei conti da file non c'è ancora.
**Khaemhat invia l'F24?** No: prepara i dati e il file; l'invio passa da home banking o intermediario.
## Pagine correlate
+224
View File
@@ -0,0 +1,224 @@
# Guida all'uso
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
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.10.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, costo medio e ultimo costo dai movimenti | — |
| Vendite | preventivi, ordini, DDT, fatture, note, pro forma, fatturazione differita, stampa PDF, invio per e-mail, scarico del magazzino e impegno, registrazione contabile automatica, incassi dallo scadenzario, file FatturaPA e invio allo SDI | — |
| Acquisti | ordini fornitori, ricevimenti, fatture e note di credito fornitore con protocollo, controllo dei prezzi, import delle fatture elettroniche XML/P7M/ZIP, autofatture e integrazioni in bozza con scadenza, registrazione contabile e registri IVA, pagamenti dallo scadenzario, file e invio delle autofatture | — |
| Magazzino | giacenze per deposito, impegnato e ordinato, costo medio, movimenti e trasferimenti, inventario fisico, proposta di riordino, valorizzazione con classi ABC, ricostruzione | libro inventari M13 |
| Contabilità | piano dei conti, causali, prima nota, contabilizzazione automatica dei documenti, registrazioni ricorrenti e definitive, partitari, mastrini, bilancio di verifica, libro giornale, ratei e risconti, chiusura guidata dell'esercizio, bilancio CEE con riclassificato e indici, export per il commercialista | — |
| IVA | registri IVA, liquidazione con F24, acconto, file LIPE, ritenute d'acconto con prospetto F24 e dati CU, bollo virtuale, dichiarazioni d'intento con plafond, elenchi Intrastat | — |
| Cespiti | categorie con i coefficienti ministeriali, registro con piano civilistico e fiscale, ammortamenti registrati e annullabili, dismissioni con plus e minusvalenze, stampa del registro | rivalutazioni guidate più avanti |
| Scadenzario | partite aperte con aging, incassi e pagamenti, distinte RiBa/SDD/bonifici SEPA con insoluti, mandati SDD, riconciliazione bancaria CSV/CBI/CAMT.053, solleciti con interessi di mora, flusso di cassa | collegamento diretto con la banca e report di tesoreria M12 |
| Fatturazione elettronica | file FatturaPA con controllo prima dell'invio, canali PEC, SdICoop e due intermediari con instradamento, notifiche, correzione degli scarti, copia di cortesia, fatture ricevute da registrare, pacchetti per la conservazione | formato europeo UBL più avanti |
| Import ed export | clienti, fornitori, articoli, prezzi e giacenze iniziali da CSV, Excel e JSON; esportazione dai radar | import del piano dei conti: più avanti |
| Amministrazione da interfaccia | utenti e licenze da variabili e riga di comando | pagine di amministrazione: M12 |
Le voci di menu delle aree non ancora pronte aprono una pagina che dice che cosa conterranno.
## 1. Entrare
![Pagina di accesso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/accesso-login.png)
Scegli l'**azienda**, scrivi **nome utente** e **password** e premi **Accedi**. Se il tuo account ha la verifica in
due passaggi, Khaemhat chiede il codice a 6 cifre dell'app di autenticazione (o un codice di recupero). Al primo
accesso può chiederti di cambiare la password. Vedi [Primi passi](Primi-passi) e
[Utenti e permessi](Utenti-e-permessi).
## 2. Orientarsi
![La Home](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-home.png)
- **Barra superiore**: logo e versione, l'**azienda** su cui lavori (si cambia da qui), la **ricerca globale**
(`Ctrl+K`), cronologia, **notifiche**, tema chiaro o scuro, **aiuto** (`F1`) e il menu del tuo profilo.
- **Menu a sinistra**: le aree del gestionale; si comprime per avere più spazio.
- **Schede**: ogni maschera si apre in una scheda; puoi tenerne aperte più insieme e passare dall'una all'altra.
- **Barra di stato** in basso: azienda, esercizio, utente, stato della connessione e versione.
La **Home** è una dashboard a widget che ognuno personalizza. Le scorciatoie da tastiera sono elencate in
[Interfaccia e scorciatoie](Interfaccia-e-scorciatoie#tabella-completa-delle-scorciatoie); la dashboard in
[Dashboard](Dashboard).
![Ricerca globale](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-ricerca.png)
## 3. Preparare l'azienda
![Codici IVA](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/tabelle-codici-iva.png)
Prima dei documenti controlla in **Tabelle azienda**:
1. **Profilo azienda**: ragione sociale, partita IVA, indirizzo, REA, contatti, logo e la nota a piè di pagina delle
stampe. Questi dati compaiono su ogni documento stampato.
2. **Esercizi e periodi**: l'esercizio dell'anno deve essere aperto, altrimenti i documenti non si confermano.
3. **Pagamenti**, **banche**, **codici IVA**, **depositi**: le tabelle di base sono già caricate; aggiungi le tue.
4. **Tipi documento** e **numeratori**: il formato dei numeri (`7/2026`, `OC-2026-0004`) e i sezionali.
5. **Codici automatici**: come si numerano clienti, fornitori e articoli.
Dettagli in [Tabelle azienda](Tabelle-azienda) e [Dati di base e di esempio](Dati-di-base-e-esempio).
## 4. Clienti e fornitori
![Radar dei clienti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/anagrafiche-radar.png)
**Anagrafiche → Clienti** apre il **radar**, l'elenco con ricerca, filtri, colonne a scelta e viste salvate.
`Ctrl+N` crea un cliente; un doppio clic apre la scheda.
![Scheda cliente](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/anagrafiche-scheda.png)
Nella scheda compili i dati anagrafici e fiscali (partita IVA e codice fiscale sono controllati; la partita IVA UE si
verifica sul VIES), gli indirizzi di consegna, i contatti e le **condizioni commerciali**: pagamento, listino,
agente, banca. I documenti di vendita le propongono da soli. Vedi [Anagrafiche](Anagrafiche).
## 5. Articoli e prezzi
![Scheda articolo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/articoli-scheda.png)
**Anagrafiche → Articoli**: codice, descrizione, categoria, unità di misura, codice IVA, prezzo, codici a barre,
fornitori abituali. **Listini** gestisce i prezzi per listino con date di validità; nella scheda del cliente puoi
fissare prezzi netti. Vedi [Articoli e listini](Articoli-e-listini).
![Griglia dei listini](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/listini-griglia.png)
## 6. Vendere
![Radar delle fatture](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatture-radar.png)
Il menu **Vendite** raccoglie preventivi, ordini, DDT, fatture e note di credito. Il percorso tipico:
1. **Preventivo** → **Crea Ordine cliente** quando il cliente accetta.
2. **Ordine** → **Crea DDT** a ogni consegna (anche parziale) oppure **Crea Fattura immediata**.
3. **Fatturazione differita** a fine mese: tutti i DDT del periodo diventano fatture, una per cliente.
4. **Nota di credito** dalla fattura per un reso o una correzione.
![Fattura emessa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento.png)
Nella maschera del documento scegli il cliente, inserisci le righe (`F4` cerca l'articolo) e controlla castelletto
IVA, scadenze e totali; **Conferma** (o **Emetti** per le fatture) assegna il numero. I documenti restano collegati
riga per riga, così Khaemhat sa che cosa resta da consegnare o da fatturare.
![Fatturazione differita](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatturazione-differita.png)
Tutto il ciclo è spiegato in [Vendite](Vendite).
## 7. Stampare e inviare
![Anteprima di stampa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-stampa.png)
La **stampante** della toolbar (`Ctrl+P`) apre l'anteprima: **Stampa** con la stampante del computer, **Apri PDF** o
**Scarica PDF**, **Salva come allegato** per conservarne una copia.
![Invio per e-mail](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-email.png)
Dal menu **⋯** del documento, **Invia per e-mail** propone destinatario, oggetto e testo; il PDF parte in allegato e
l'esito finisce nel log. Vedi [Vendite](Vendite#invio-per-e-mail).
## 8. Comprare
![Fattura fornitore con differenza di prezzo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-fattura-differenze.png)
Il ciclo passivo usa le stesse maschere delle vendite. In **Acquisti → Ordini fornitori** prepari l'ordine (il prezzo
è quello del fornitore nella scheda articolo); quando arriva la merce **Crea DDT fornitore (carico)** registra il
ricevimento, anche in più volte, e alla conferma carica il magazzino. **Crea Fattura fornitore** prepara la fattura:
alla conferma prende il **protocollo** IVA. Se il prezzo fatturato è diverso da quello dell'ordine o del ricevimento,
un avviso sopra le righe lo segnala.
![Import delle fatture passive](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/acquisti-importa-fatture.png)
Le fatture elettroniche ricevute si caricano da **Acquisti → Importa fatture**: XML, P7M o ZIP, anche molti file
insieme. Khaemhat trova o crea il fornitore, abbina gli articoli, scarta i doppioni e registra le fatture in bozza con
il file allegato. Per le fatture di fornitori esteri o in inversione contabile indica quale **autofattura** serve ed
entro quando; **Acquisti → Autofatture** le elenca tutte. Vedi [Acquisti](Acquisti).
## 9. Il magazzino
![Giacenze e disponibilità](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-giacenze.png)
**Magazzino → Giacenze** mostra per ogni articolo giacenza, impegnato, ordinato, disponibile, costo medio e valore,
con lo stato rispetto a scorta minima e punto di riordino; apri una riga per vedere i movimenti. I documenti
confermati muovono il magazzino da soli: non serve registrare a parte carichi e scarichi.
![Proposta di riordino](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-riordino.png)
**Proposte di riordino** calcola che cosa ordinare e a quale fornitore e crea gli ordini in bozza, uno per fornitore.
**Inventario** guida il conteggio fisico (anche dal file del lettore di codici a barre) e registra le rettifiche;
**Valorizzazione** calcola il valore del magazzino a una data con le classi ABC. Vedi [Magazzino](Magazzino).
## 10. La contabilità
![Prima nota](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-prima-nota.png)
Con il modulo contabile ogni fattura, nota e autofattura confermata scrive da sola la sua **registrazione** in
partita doppia, con le righe IVA nel registro giusto e le **partite** da incassare o pagare. **Contabilità → Prima
nota** elenca le registrazioni e serve per quelle manuali (giroconti, spese, versamenti); **Liquidazione IVA** calcola
l'IVA del periodo e prepara l'F24; **Bilancio** dà il bilancio di verifica e, nelle altre schede, il bilancio CEE,
il riclassificato e gli indici. A fine anno **Chiusura esercizio** guida ammortamenti, ratei e risconti, rimanenze,
chiusura dei conti, riapertura e stampe definitive in nove passi. Vedi [Contabilità](Contabilita), [IVA](IVA),
[Cespiti](Cespiti) e [Chiusura e bilancio](Chiusura-e-bilancio).
## 11. Incassare, pagare e la banca
![Partite aperte](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-partite.png)
**Scadenzario → Partite aperte** mostra che cosa devono pagarti i clienti e che cosa devi ai fornitori, con lo scaduto
per anzianità. Quando un cliente paga, seleziona le sue partite e premi **Registra incasso**: indichi data, banca e
importo (anche parziale, o con un abbuono) e Khaemhat chiude le partite e scrive la registrazione. Per i fornitori
passa a **Fornitori** e usa **Registra pagamento**.
![Riconciliazione bancaria](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-riconciliazione.png)
Le **Distinte RiBa/SDD** raccolgono gli effetti in scadenza e generano il file da caricare nell'home banking (anche i
bonifici ai fornitori); **Riconciliazione bancaria** importa l'estratto conto e propone per ogni movimento la partita
o la spesa corrispondente; **Solleciti** prepara i promemoria ai clienti in ritardo con gli interessi di mora;
**Flusso di cassa** mostra quanto ci sarà in banca nelle prossime settimane. Vedi [Scadenzario](Scadenzario).
## 12. Allegati
![Pannello allegati](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/allegati-pannello.png)
Ogni anagrafica e ogni documento ha la scheda **Allegati**: carichi file dal computer, li vedi in anteprima, scarichi tutto in un archivio ZIP. I PDF che Khaemhat genera sono **versionati**: ogni stampa salvata o
e-mail inviata aggiunge una versione e le precedenti restano. Vedi [Allegati e file](Allegati-e-file).
## 13. Importare ed esportare
![Mappatura delle colonne](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/import-export-mappatura.png)
**Amministrazione → Import/Export** porta in Khaemhat clienti, fornitori, articoli, prezzi di listino e giacenze iniziali 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).
## 14. Personalizzare
![Il mio profilo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/preferenze-profilo.png)
Dal menu del tuo nome, **Il mio profilo**: tema chiaro, scuro o automatico, colore d'accento, densità e carattere,
dati personali, password e verifica in due passaggi, sessioni aperte e pagina iniziale. Le preferenze dell'azienda (ad esempio i decimali dei
prezzi) sono in **Tabelle azienda → Preferenze**. Vedi [Preferenze utente](Preferenze-utente).
![Tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-tema-scuro.png)
## Se qualcosa non va
- **`F1`** apre l'aiuto della pagina in cui sei: la pagina di questa wiki, anche senza connessione a Gitea.
- La pagina di errore riporta un **codice di traccia**: comunicalo all'amministratore, che lo ritrova nel
[Log](Log).
- Le domande più comuni sono in [FAQ](FAQ); i termini del gestionale nel [Glossario](Glossario).
## Pagine correlate
[Primi passi](Primi-passi) · [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie) · [Anagrafiche](Anagrafiche) ·
[Articoli e listini](Articoli-e-listini) · [Tabelle azienda](Tabelle-azienda) · [Vendite](Vendite) ·
[Acquisti](Acquisti) · [Magazzino](Magazzino) · [Contabilità](Contabilita) · [IVA](IVA) ·
[Allegati e file](Allegati-e-file) · [Import/Export](Import-Export) · [Preferenze utente](Preferenze-utente)
+9 -4
View File
@@ -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.10.0 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10; sviluppo in corso)
![Khaemhat](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/assets/icon-v1.0-128.png)
@@ -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) |
@@ -33,7 +37,8 @@ Il nome viene da uno scriba dell'antico Egitto che sovrintendeva ai granai del r
- **Anagrafiche e tabelle:** [Anagrafiche](Anagrafiche) · [Articoli e listini](Articoli-e-listini) ·
[Tabelle azienda](Tabelle-azienda)
- **Ciclo attivo e passivo:** [Vendite](Vendite) · [Acquisti](Acquisti) · [Magazzino](Magazzino)
- **Amministrazione e fisco:** [Contabilità](Contabilita) · [IVA](IVA) · [Cespiti](Cespiti) · [Intrastat](Intrastat) ·
- **Amministrazione e fisco:** [Contabilità](Contabilita) · [Chiusura e bilancio](Chiusura-e-bilancio) · [IVA](IVA) ·
[Cespiti](Cespiti) · [Intrastat](Intrastat) · [Dichiarazioni d'intento](Dichiarazioni-d-intento) ·
[Scadenzario](Scadenzario) · [Fatturazione elettronica](Fatturazione-elettronica) ·
[Fiscalità italiana](Fiscalita-italiana)
- **Clienti e servizi:** [CRM](CRM) · [Servizi](Servizi) · [Canali e-commerce](Canali-e-commerce)
+231 -142
View File
@@ -1,199 +1,288 @@
# IVA
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M7; dichiarazioni d'intento in M10)
> **Modulo di licenza:** ACCT (bollo virtuale e dichiarazioni d'intento anche con EINV) · **Permessi principali:** `vat.settlement.confirm`, `vat.register.print`, `vat.withholding.write`, `vat.intent.write` · **Specifica:** SPEC §11.7, §11.9, §11.3, §14
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** ACCT · **Permessi principali:** `vat.register.read` (registri IVA), `vat.settlement.read` (liquidazione, ritenute, bollo, F24), `vat.settlement.confirm` (conferme, versamenti, stampe definitive) · **Specifica:** SPEC §11.7, §11.9, §14, ADR 0037
## A cosa serve
Questa pagina descrive l'IVA e i versamenti collegati, tutti nel menu **Contabilità**:
Questa pagina descrive tutto ciò che riguarda l'IVA e i versamenti collegati:
- **registri IVA** con protocollo, stampa di prova e stampa definitiva;
- **liquidazione periodica** mensile o trimestrale, con credito e debito riportati, pro rata, interessi trimestrali e
minimo di versamento; **acconto di dicembre**; file della **comunicazione LIPE** e dati del modello **F24**;
- **ritenute d'acconto** operate e subite, **prospetto F24** con il suo pagamento e dati per la **Certificazione
Unica**;
- **imposta di bollo virtuale** sulle fatture elettroniche, per trimestre.
- **registri IVA** con protocollo e stampe definitive;
- **liquidazione periodica** con esigibilità differita, IVA per cassa, pro-rata, acconto di dicembre, interessi,
minimo di versamento, **dati F24** e **LIPE**;
- **ritenute d'acconto** e **casse previdenziali**, con prospetto F24 e dati per la **CU**;
- **imposta di bollo virtuale** sulle fatture elettroniche;
- **dichiarazioni d'intento** ricevute ed emesse, con plafond.
> **Khaemhat non trasmette nulla.** Prepara i file della LIPE, i dati dell'F24 e i dati della Certificazione Unica;
> l'invio telematico si fa con i servizi dell'Agenzia delle Entrate, con l'home banking o tramite l'intermediario.
Khaemhat **non trasmette** F24, LIPE e CU: prepara i dati, i file e le stampe; l'invio telematico avviene tramite
intermediario o home banking (avviso presente nel mockup 046).
> **In questa versione** ci sono i cinque registri IVA con stampe di prova e definitive, la liquidazione con la sua
> registrazione e il versamento F24, l'acconto IVA, il file LIPE, le ritenute con il prospetto F24 e il pagamento, i
> dati della CU e il bollo virtuale. Dalla 0.8 il pagamento di una parcella dallo
> [Scadenzario](Scadenzario) rende dovuta la ritenuta da solo. Dalla 0.10 ci sono le [dichiarazioni d'intento](Dichiarazioni-d-intento) con il plafond e gli
> elenchi [Intrastat](Intrastat). Arriva più avanti l'**IVA per cassa** completa (fase 2). Non ci sono ancora la **dichiarazione IVA annuale** e l'**invio
> telematico** di F24, LIPE e CU.
## Dove si trova
- **Contabilità → Registri IVA**, **Contabilità → Liquidazione IVA**, **Contabilità → Ritenute**.
- **Fatturazione elettronica → Bollo virtuale**, **→ Dichiarazioni d'intento**, **→ LIPE**.
Menu **Contabilità** → *Registri IVA*, *Liquidazione IVA*, *Ritenute e F24*, *Bollo virtuale*. La **periodicità**
IVA (mensile o trimestrale) e la **percentuale di pro rata** si impostano nel **profilo azienda** (vedi
[Tabelle azienda](Tabelle-azienda)). Le registrazioni che queste pagine scrivono sono in **Prima nota** (vedi
[Contabilità](Contabilita)).
## Schermate
![045 · Registri IVA](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/045-registri-iva.png)
*Mockup 045 — registro Vendite 1 del mese con protocolli, imponibile, aliquota o natura, imposta ed esigibilità; in alto l'ultima stampa definitiva (anteprima ridotta)*
![046 · Liquidazione IVA](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/046-liquidazione-iva.png)
*Mockup 046 — liquidazione mensile provvisoria: parametri, registri del periodo con i controlli superati, calcolo dell'IVA da versare e riquadro del versamento (codice tributo, scadenza, export F24, scadenza LIPE)*
![047 · Ritenute e F24](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/047-ritenute-parcelle-f24.png)
*Mockup 047 — ritenute operate e subite con cassa previdenziale, periodo e stato del versamento; sotto, il prospetto F24 del 16 del mese con i tributi 1040, 1038 e 6009*
![060 · Bollo virtuale](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/060-bollo-virtuale.png)
*Mockup 060 — fatture del trimestre soggette a bollo con natura, importo esente e addebito; riquadri con importo, codice tributo, scadenza e trimestre precedente*
![061 · Dichiarazioni d'intento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/061-dichiarazioni-intento.png)
*Mockup 061 — dichiarazioni d'intento ricevute con protocollo AdE, plafond, utilizzato, residuo e stato (attiva, avviso al 97 %, esaurita)*
```
Documenti confermati ──► Registri IVA ──Calcola──► Liquidazione ──Conferma──► registrazione LIQ + riga F24
Fattura del professionista ──Fattura pagata──► Ritenuta da versare ──► riga F24 (1040)
Fatture con bollo del trimestre ──Metti in F24──► riga F24 (2521-2524)
Righe F24 della scadenza ──► Prospetto F24 ──Registra pagamento──► registrazione F24
```
## Registri IVA
Registri previsti: **vendite**, **acquisti**, **corrispettivi**, **vendite reverse charge**, **acquisti reverse
charge** e i **sezionali** che servono (es. `VEN1`, `ACQ1`, `VEN-RC`, `ACQ-RC`, `ACQ-SP` per lo split payment,
`CORR`). Ogni documento registrato riceve un **protocollo** progressivo nel suo registro.
![Khaemhat 0.7.0 · registro IVA delle fatture emesse](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-registri-iva.png)
*Il registro VEN1 di ottobre: una scheda per registro, la striscia con tipo, imponibile, imposta, ultima stampa
definitiva e ultima pagina, le righe con protocollo e il riepilogo per aliquota.*
La griglia mostra protocollo, data di registrazione, documento, data del documento, controparte, P.IVA o codice
fiscale, imponibile, aliquota o natura, imposta, totale ed **esigibilità** (`I` immediata, `D` differita, `S`
scissione dei pagamenti).
**Contabilità → Registri IVA** ha una scheda per registro:
**Stampe**
| Stampa | Effetto |
| Registro | Contenuto |
|---|---|
| **Provvisoria** | in qualunque momento, senza effetti |
| **Stampa definitiva** del periodo | pagine numerate, totali per aliquota e natura; aggiorna "ultima stampa definitiva" |
| **Riepilogo aliquote** | totali del periodo per codice IVA e natura |
| **VEN1** Registro fatture emesse | fatture, note di debito, parcelle e note di credito di vendita |
| **VEN-RC** Registro fatture emesse - autofatture e integrazioni | il lato *vendite* delle autofatture e integrazioni (TD16-TD29) |
| **ACQ1** Registro fatture acquisti | fatture e note di credito dei fornitori |
| **ACQ-RC** Registro fatture acquisti - autofatture e integrazioni | il lato *acquisti* delle stesse autofatture |
| **CORR** Registro dei corrispettivi | le registrazioni dei corrispettivi (causale `CORR`) |
Le autofatture reverse charge (TD16-TD19) sono annotate sia nel registro vendite RC sia nel registro acquisti RC,
Scegli il periodo con **Dal** e **Al**. Ogni riga mostra **protocollo** (il link apre la registrazione), **data di
registrazione IVA**, documento e data, cliente o fornitore, **aliquota** o natura, **imponibile**, **imposta**,
**indetraibile** ed **esigibilità** (*Immediata*, *Differita*, *Scissione dei pagamenti*). Sotto, il **riepilogo per
aliquota** e il totale del registro.
Le autofatture e integrazioni compaiono in **VEN-RC** e in **ACQ-RC** con la stessa imposta: a debito e a credito,
con effetto neutro sulla liquidazione.
## Liquidazione IVA periodica
### Stampe
| Stampa | Effetto | Permesso |
|---|---|---|
| **Stampa di prova** | PDF del registro nel periodo scelto, in qualunque momento, senza effetti | `vat.register.read` |
| **Stampa definitiva** | PDF dal giorno dopo l'ultima stampa definitiva fino al giorno scelto, con le pagine numerate di seguito all'ultima pagina dell'anno | `vat.settlement.confirm` |
La stampa definitiva non si annulla: la striscia mostra la data dell'**ultima stampa definitiva** e l'**ultima
pagina**, e la stampa successiva riparte da lì (la prima dell'anno parte dal 1° gennaio e dalla pagina 1). La stampa
definitiva **non blocca** le registrazioni: a bloccare il periodo è la conferma della liquidazione (vedi sotto).
## Liquidazione IVA
![Khaemhat 0.7.0 · liquidazione IVA di ottobre confermata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-liquidazione-iva.png)
*La liquidazione mensile di ottobre 2026 confermata: registri del periodo, calcolo con il credito di settembre,
riquadro del versamento (codice 6010, scadenza 16/11/2026, trimestre LIPE) e l'elenco delle liquidazioni dell'anno.*
### Come si fa
1. **Contabilità → Liquidazione IVA**. Controlla i parametri: **Periodicità** (mensile o trimestrale, dal profilo
azienda), **Periodo**, **Data liquidazione**, **Credito precedente**, **Pro-rata**.
2. Premi **Calcola**. Khaemhat esegue i **controlli preliminari** (mostrati con il segno di spunta sopra i registri):
numerazione continua, nessuna bozza, date coerenti, periodo precedente confermato.
3. Controlla la tabella **Registri del periodo** (documenti, imponibile, IVA, indetraibile, note come *neutra* per il
reverse charge) e il riquadro **Calcolo**.
4. Premi **Conferma**: la liquidazione diventa definitiva e il **periodo viene bloccato** (vedi
[Contabilità](Contabilita), esercizi e periodi). Serve il permesso `vat.settlement.confirm`.
5. Premi **Dati F24** per esportare i dati del versamento e **LIPE XML** per il file della comunicazione.
1. **Contabilità → Liquidazione IVA**. La **periodicità** viene dal profilo azienda; scegli **Anno** e **Periodo**
(mese o trimestre).
2. Premi **Calcola** (serve `vat.settlement.read`). Khaemhat legge i registri del periodo e mostra la tabella
**Registri del periodo** (documenti, imponibile, imposta, indetraibile, esigibilità differita), il riquadro
**Calcolo** e il riquadro **Versamento** con codice tributo, anno, importo, scadenza e trimestre LIPE. Puoi
ricalcolare quante volte vuoi finché la liquidazione non è confermata.
3. Premi **Conferma liquidazione** (serve `vat.settlement.confirm`). Le liquidazioni si confermano in ordine: se un
periodo precedente è calcolato ma non confermato, va confermato prima. Alla conferma Khaemhat:
- scrive in prima nota la registrazione **LIQ**: *IVA su vendite* in Dare, *IVA su acquisti* in Avere, gli
interessi trimestrali in Dare, l'eventuale IVA resa indetraibile dal pro rata a costo, e la differenza su
*Erario c/liquidazione IVA*;
- segna i periodi dell'esercizio come **liquidati**;
- se c'è da versare, aggiunge la riga del modello **F24** con codice tributo e scadenza (vedi
[Prospetto F24](#prospetto-f24-e-pagamento)).
4. **Dati F24** scarica i dati del modello F24 della scadenza; **Comunicazione LIPE** scarica il file del trimestre
(vedi [sotto](#comunicazione-lipe)).
**Riapri** annulla la conferma: la registrazione LIQ viene eliminata (o stornata, se è già definitiva), la riga F24
viene tolta e i periodi tornano aperti. Non si riapre se l'F24 della liquidazione è già **pagato** (annulla prima il
pagamento) né se una liquidazione **successiva** è confermata (riapri prima quella).
**Periodi liquidati.** Dopo la conferma, documenti e registrazioni **con IVA** datati nei periodi liquidati sono
rifiutati: per correggere bisogna riaprire la liquidazione. Le registrazioni senza IVA restano libere.
### Le voci del calcolo
| Voce | Regola |
| Voce | Regola in Khaemhat |
|---|---|
| IVA a debito | dai registri vendite e corrispettivi del periodo (esigibilità immediata) |
| IVA a credito | dai registri acquisti, al netto dell'**indetraibile** e del **pro-rata** |
| Esigibilità differita | l'IVA delle fatture a esigibilità differita entra quando si incassa (o alla scadenza di legge) |
| IVA per cassa | con il regime dell'IVA per cassa attivo nel profilo azienda, debito e credito seguono incassi e pagamenti; il regime completo è previsto in fase 2 ([Roadmap](Roadmap)) |
| Credito del periodo precedente | riportato automaticamente |
| Acconto versato | sottratto nella liquidazione di dicembre (o del 4° trimestre) |
| Interessi 1 % | maggiorazione dell'1 % per i contribuenti **trimestrali** |
| Minimo di versamento | se l'IVA dovuta non supera **€ 25,82** non si versa e si **riporta** al periodo successivo |
| **IVA a debito sulle vendite** | imposta dei registri vendite e corrispettivi del periodo, tolta quella a esigibilità differita e in scissione dei pagamenti |
| **IVA a credito sugli acquisti** | imposta dei registri acquisti, tolta la parte **indetraibile** dei codici IVA, poi ridotta dal **pro rata** del profilo azienda |
| **IVA indetraibile** | indetraibile per codice IVA più la parte tolta dal pro rata |
| **IVA a esigibilità differita** | mostrata a parte: non entra nel debito del periodo |
| **Credito / debito periodo precedente** | riportati dalla liquidazione confermata precedente |
| **Acconto versato** | l'acconto di dicembre registrato, tolto nell'ultima liquidazione dell'anno (dicembre o 4° trimestre) |
| **Interessi trimestrali 1%** | per i contribuenti trimestrali, sul saldo a debito |
| **Da versare** | se il totale (con gli interessi) è sotto **25,82 euro** non si versa: diventa *debito sotto la soglia* e passa al periodo dopo; se il saldo è a credito diventa *credito da riportare* |
### Acconto di dicembre
### Codici tributo e scadenze
L'acconto si calcola con uno dei tre metodi: **storico**, **previsionale**, **analitico**. Khaemhat propone gli
importi di tutti e tre e l'utente sceglie. Percentuali e scadenza seguono le regole in vigore (al momento della
stesura: 88 % per storico e previsionale, liquidazione al 20 dicembre per l'analitico, versamento entro il 27
dicembre) e sono aggiornate con il pacchetto fiscale. Codici tributo: **6013** (mensili) e **6035** (trimestrali).
| Periodo | Codice | Scadenza |
|---|---|---|
| Mese (gennaio-dicembre) | **6001**-**6012** | 16 del mese dopo |
| 1°, 2°, 3° trimestre | **6031**, **6032**, **6033** | 16 del secondo mese dopo il trimestre (16/5, 20/8, 16/11) |
| 4° trimestre | **6099**, rateazione **0101** | 16 marzo dell'anno dopo, con il saldo annuale |
### Codici tributo F24
Le scadenze di sabato, domenica o festivo passano al primo giorno lavorativo; i versamenti dal 1° al 20 agosto
passano al **20 agosto**. Codici e calendario sono in [Fiscalità italiana](Fiscalita-italiana#codici-tributo-f24).
| Codice | Versamento |
### Acconto IVA di dicembre
Il riquadro **Acconto IVA** (sotto l'elenco delle liquidazioni, con `vat.settlement.confirm`) calcola l'acconto da
versare entro il **27 dicembre** (primo giorno lavorativo successivo se festivo) con il codice **6013** (mensili) o
**6035** (trimestrali).
| Metodo | Base di calcolo | Acconto |
|---|---|---|
| **Storico** | l'IVA dell'ultimo periodo dell'anno prima (dicembre o 4° trimestre), al lordo dell'acconto di allora e senza interessi | 88% della base |
| **Previsionale** | l'IVA che prevedi per l'ultimo periodo dell'anno: la scrivi tu | 88% della base |
| **Effettivo** | l'IVA dall'inizio dell'ultimo periodo al **20 dicembre** | tutta la base |
1. Scegli il **metodo**: la **base di calcolo** si compila con il valore che Khaemhat conosce (il riquadro *Basi di
calcolo* mostra storico ed effettivo; **Ricalcola le basi** le rilegge). Per il previsionale scrivila tu.
2. **Registra acconto** aggiunge la riga F24 dell'acconto. Sotto **103,29 euro** l'acconto non è dovuto e non viene
registrato. Finché non è pagato puoi registrarlo di nuovo con un altro metodo: la riga si aggiorna.
L'acconto registrato viene tolto nella liquidazione di dicembre o del 4° trimestre.
### Comunicazione LIPE
**Comunicazione LIPE** scarica il file XML della **comunicazione delle liquidazioni periodiche IVA** di un trimestre,
nel tracciato **IVP18** dell'Agenzia delle Entrate: un modulo per ogni mese (o per il trimestre), con operazioni
attive e passive, IVA esigibile e detratta, debiti e crediti riportati, interessi, acconto e importo da versare o a
credito. Il pulsante si accende quando è confermata la liquidazione dell'ultimo mese del trimestre (o del trimestre).
Il file si chiama `IT<codice fiscale>_LI_<anno>_T<trimestre>.xml` e va firmato e inviato con i servizi dell'Agenzia
o dall'intermediario. Le scadenze sono in [Fiscalità italiana](Fiscalita-italiana#comunicazione-lipe).
## Ritenute d'acconto
![Khaemhat 0.7.0 · ritenute operate e prospetto F24](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/contabilita-ritenute.png)
*La ritenuta operata sulla fattura dello Studio Rag. Neri Paola (RT01, causale A, cassa TC04, 20% di 450 euro) già
pagata e da versare; sotto, il prospetto F24 della scadenza del 16/11/2026 con l'IVA di ottobre.*
**Contabilità → Ritenute e F24** elenca le ritenute dei documenti di un **anno**, nelle schede **Operate**, **Subite**
e **Tutte**:
- **operate**: quelle che l'azienda trattiene sulle **fatture dei professionisti** e degli agenti (fatture fornitore
con ritenuta);
- **subite**: quelle che i clienti trattengono sulle **parcelle** e fatture emesse dall'azienda con ritenuta.
Le ritenute nascono da sole quando il documento viene contabilizzato. Per ognuna: documento (il link apre la
registrazione), data, cliente o fornitore, **tipo** e causale di pagamento (per esempio `RT01 · A`), imponibile,
**cassa** previdenziale e contributo, **aliquota** (con la quota dell'imponibile, per esempio *20% su 50%* per gli
agenti), importo, data di pagamento della fattura e **stato**:
| Stato | Significato |
|---|---|
| 6001 … 6012 | IVA mensile, da gennaio (6001) a dicembre (6012) |
| 6031 … 6034 | IVA trimestrale, dal 1° (6031) al 4° trimestre (6034); il 6034 riguarda i trimestrali "speciali", per gli altri il saldo del 4° trimestre si versa con la dichiarazione annuale (6099) |
| 6013 / 6035 | acconto IVA mensili / trimestrali |
| 6099 | IVA da dichiarazione annuale |
| 1040 | ritenute su redditi di lavoro autonomo |
| 1038 | ritenute su provvigioni (agenti e rappresentanti) |
| *In attesa del pagamento* | ritenuta operata su una fattura non ancora pagata |
| *Da versare* | la fattura è pagata: la ritenuta va versata con l'F24 |
| *Versata* | l'F24 che la contiene è pagato |
| *Subita* | ritenuta trattenuta dal cliente su una fattura dell'azienda |
I codici sono caricati con i dati di base ([Dati di base e di esempio](Dati-di-base-e-esempio)) e riepilogati in
[Fiscalità italiana](Fiscalita-italiana).
### Registrare il pagamento della fattura
### LIPE
La ritenuta operata diventa dovuta **quando paghi la fattura** del professionista (criterio di cassa). Se paghi la
fattura dallo [Scadenzario](Scadenzario) succede da solo, quando la fattura è saldata del tutto. Se l'hai pagata
fuori da Khaemhat, registralo a mano:
La **Comunicazione delle liquidazioni periodiche IVA** si genera come file XML nel tracciato dell'Agenzia delle
Entrate dalle liquidazioni confermate del trimestre (voce di menu **Fatturazione elettronica → LIPE** o pulsante
**LIPE XML**). Il riquadro **Versamento** mostra il trimestre di riferimento e la scadenza.
1. Sulla riga della ritenuta premi **Fattura pagata** e indica la data di pagamento.
2. Khaemhat scrive la registrazione **RIT** (*fornitore* in Dare, *Erario c/ritenute lavoro autonomo* in Avere) e
aggiunge la ritenuta alla riga F24 del suo codice tributo (**1040** lavoro autonomo, **1038** provvigioni) e del
mese di pagamento, con scadenza il **16 del mese dopo**. Le ritenute dello stesso codice e mese si sommano.
3. Per una ritenuta **subita**, **Fattura pagata** chiede la data in cui il cliente ha pagato e scrive la registrazione
**RITS** (*Erario c/ritenute subite* in Dare, *cliente* in Avere): è un credito d'imposta.
## Ritenute d'acconto e casse previdenziali
Il pulsante con la freccia annulla il pagamento della fattura (e la sua registrazione) finché l'F24 non è pagato.
**Contabilità → Ritenute** (mockup 047) elenca le ritenute **operate** (sulle parcelle e provvigioni che paghiamo) e
quelle **subite** (sulle nostre fatture, ad esempio verso la PA), con i filtri **Operate / Subite / Tutte**.
### Dati per la Certificazione Unica
| Colonna | Significato |
|---|---|
| Tipo | professionista TD06, agente ENASARCO, ritenuta subita… |
| Imponibile, Cassa, Importo cassa | contributo previdenziale (es. 4 % INPS di rivalsa, 4 % cassa professionale) |
| Ritenuta | aliquota (es. 20 %; per gli agenti l'aliquota si applica a una quota della provvigione) |
| Periodo → F24 | mese di pagamento della fattura e data del modello F24 in cui confluisce |
| Stato | *Da versare*, *In F24*, *Versata*, *Subita* |
**Dati Certificazione Unica** scarica un file CSV con i **percipienti** dell'anno: una riga per professionista e
causale con codice fiscale, denominazione, causale, anno, compenso lordo, somme non soggette, imponibile, ritenute,
codice tributo e documenti. Contiene le ritenute operate sulle fatture pagate nell'anno. La CU si compila e si invia
con i servizi dell'Agenzia delle Entrate o dall'intermediario.
Regole:
## Prospetto F24 e pagamento
- La ritenuta nasce come **debito verso l'Erario al pagamento** della fattura (criterio di cassa) e confluisce nel
prospetto F24 del mese successivo (tributi **1040** e **1038**).
- Sulle **parcelle (TD06)** cassa previdenziale, ritenuta e netto a pagare sono calcolati in automatico; **ENASARCO**
si applica agli agenti con i relativi massimali.
- **Registra versamento** registra il pagamento del modello F24 e chiude le ritenute versate.
- **CU export** produce i dati della Certificazione Unica da consegnare all'intermediario.
Il riquadro **Prospetto F24** (nella pagina *Ritenute e F24*) raccoglie tutto ciò che va versato con l'F24: IVA della
liquidazione, acconto IVA, ritenute operate, bollo virtuale.
Il **Prospetto F24** del giorno di scadenza riepiloga tributi, periodi e importi (ritenute e IVA) con il totale.
1. Scegli la **scadenza** nell'elenco (si apre sulla prima non pagata).
2. Il prospetto mostra una riga per **codice tributo** e periodo con descrizione, periodo di riferimento, importo a
debito e a credito, e il **saldo** dell'F24.
3. **Dati F24** scarica un file CSV (separatore `;`, sezione Erario) con intestazione, una riga per codice tributo e il
saldo, da passare all'home banking o all'intermediario.
4. Pagato l'F24, **Registra pagamento** chiede la data: Khaemhat scrive la registrazione **F24** (*Erario
c/liquidazione IVA*, *Erario c/ritenute* e *imposta di bollo* in Dare secondo le righe, la **banca** in Avere) e
segna versate le righe e le ritenute. La banca è quella predefinita dell'azienda (il suo *conto contabile*), o
`07.01.001` *Banca c/c*.
**Annulla pagamento** toglie la registrazione del pagamento (o la storna, se è definitiva) e riporta le righe da
versare.
## Imposta di bollo virtuale
Sulle fatture con operazioni **esenti, non imponibili o fuori campo IVA** di importo **superiore a € 77,47** si
applica il bollo di **€ 2,00**, calcolato in automatico sul documento e indicato nell'XML (`DatiBollo`).
Sulle fatture elettroniche **senza IVA** (operazioni esenti, non imponibili o fuori campo) di importo **superiore a
77,47 euro** si applica il bollo di **2 euro**. Khaemhat lo calcola già sul documento di vendita (vedi
[Vendite](Vendite)), che dice anche se è **addebitato al cliente** o **a carico dell'azienda**.
**Fatturazione elettronica → Bollo virtuale** (mockup 060) mostra le fatture del trimestre con il bollo, la natura
IVA, l'importo esente e l'**addebito** (*addebitato al cliente*, *a carico azienda*; per le fatture ricevute *a
carico fornitore*). I riquadri riportano numero di fatture, importo, codice tributo del trimestre (**2521-2524**),
scadenza e stato del trimestre precedente.
**Contabilità → Bollo virtuale** riepiloga il bollo per **anno** e **trimestre**:
1. A fine trimestre controlla l'elenco e confrontalo con quello messo a disposizione dall'Agenzia delle Entrate.
2. **Esporta per F24** produce i dati del versamento.
3. A pagamento avvenuto premi **Segna versato**.
- la striscia del trimestre: numero di **fatture**, **importo**, **codice tributo**, **scadenza** e lo stato del
**trimestre precedente**;
- l'elenco delle fatture del trimestre con il bollo: documento (il link lo apre), data, cliente, imponibile, bollo e
**addebito**;
- il riepilogo dei quattro trimestri dell'anno con fatture, importo, scadenza e stato (*Da mettere in F24*, *In F24*,
*pagato il*).
> **Attenzione:** alcune operazioni non imponibili sono escluse dal bollo per legge (per esempio le cessioni
> intracomunitarie e le esportazioni). L'esclusione sarà gestita sul codice IVA; la regola precisa sarà verificata in
> sviluppo con la normativa vigente.
| Trimestre | Codice | Scadenza |
|---|---|---|
| 1° | **2521** | 31 maggio |
| 2° | **2522** | 30 settembre |
| 3° | **2523** | 30 novembre |
| 4° | **2524** | fine febbraio dell'anno dopo |
## Dichiarazioni d'intento e plafond
Se il bollo del **1° trimestre** non supera **5.000 euro** si versa con il 2° (30 settembre); se quello del 1° e del
2° insieme non supera 5.000 euro si versa con il 3° (30 novembre). Le scadenze festive passano al primo giorno
lavorativo.
**Fatturazione elettronica → Dichiarazioni d'intento** (mockup 061) gestisce:
- **Ricevute**: dichiarazioni degli esportatori abituali nostri clienti (numero, data, cliente, **protocollo AdE**,
plafond, utilizzato, residuo, anno, stato);
- **Emesse (plafond nostro)**: dichiarazioni che l'azienda presenta ai propri fornitori.
Regole:
- Il plafond si aggiorna a ogni fattura con codice IVA **N3.5** (non imponibile a seguito di dichiarazione d'intento).
- Al **90 %** di utilizzo compare un avviso (e la regola di automazione predefinita *Avviso plafond* avvisa
l'amministrazione, vedi [Automazioni](Automazioni)); al **100 %** la fattura è bloccata.
- Il protocollo della dichiarazione è riportato nell'XML della fattura (blocco `AltriDatiGestionali`).
- **Registro cronologico** stampa il registro delle dichiarazioni.
La dichiarazione è collegata alla scheda fiscale del cliente ([Anagrafiche](Anagrafiche)).
1. Scegli il trimestre e confronta l'elenco con quello che l'Agenzia delle Entrate mette a disposizione nell'area
riservata.
2. **Metti in F24** (serve `vat.settlement.confirm`) aggiunge la riga del bollo al prospetto F24 della scadenza. Se
il bollo del trimestre cambia (una fattura in più), premilo di nuovo: finché non è pagata la riga si aggiorna.
3. **Dati F24** scarica i dati dell'F24 di quella scadenza; il pagamento si registra dal
[Prospetto F24](#prospetto-f24-e-pagamento).
## Permessi e licenza
- Registri, liquidazione, F24, LIPE, ritenute: modulo **ACCT**.
- Bollo virtuale e dichiarazioni d'intento: compaiono nel menu Fatturazione elettronica e la specifica li elenca sia
in ACCT sia in EINV; l'abbinamento definitivo sarà fissato in sviluppo.
- `vat.settlement.confirm` è richiesto per confermare la liquidazione; gli altri codici in testa sono indicativi
(convenzione `modulo.entità.azione`, SPEC §7.2).
Tutto è nel modulo **ACCT**.
| Permesso | Cosa consente |
|---|---|
| `vat.register.read` | vedere i registri IVA e farne la stampa di prova |
| `vat.settlement.read` | calcolare e vedere le liquidazioni, ritenute, bollo, prospetto F24; scaricare LIPE, dati F24 e CU |
| `vat.settlement.confirm` | confermare e riaprire le liquidazioni, registrare acconto, pagamenti delle fatture, pagamenti F24, bollo in F24, stampa definitiva dei registri |
## Domande frequenti
**Ho trovato un errore in un periodo già liquidato.** Il periodo è bloccato: un utente con il permesso di
riapertura sblocca il periodo, si corregge, si ricalcola e si conferma di nuovo. Se l'F24 è già stato versato, la
differenza va gestita nella liquidazione successiva o con ravvedimento (fuori da Khaemhat).
**Khaemhat invia l'F24?** No. Prepara dati e stampe; l'invio è dell'intermediario o dell'home banking.
**Dove imposto la periodicità IVA e il pro-rata?** Nel profilo azienda ([Tabelle azienda](Tabelle-azienda)).
- **"Conferma prima la liquidazione del periodo precedente".** Un mese (o trimestre) precedente è calcolato ma non
confermato: confermalo prima. Il credito e il debito si riportano solo da una liquidazione confermata.
- **Ho trovato un errore in un periodo già liquidato.** Riapri la liquidazione (e prima quelle successive, se
confermate), correggi il documento, ricalcola e conferma di nuovo. Se l'F24 è già pagato, annulla prima il
pagamento; se l'hai davvero versato, la differenza va gestita nella liquidazione successiva o con il ravvedimento,
fuori da Khaemhat.
- **Il pulsante Comunicazione LIPE è spento.** Il trimestre non è finito o la liquidazione del suo ultimo mese non è
confermata.
- **La ritenuta non compare nel prospetto F24.** È *In attesa del pagamento*: registra **Fattura pagata**. La ritenuta
va nella scadenza del 16 del mese dopo il pagamento.
- **La stampa definitiva del registro è rifiutata.** Deve partire dal giorno dopo l'ultima stampa definitiva: la
striscia del registro mostra quale.
- **Khaemhat invia F24, LIPE o CU?** No: prepara i dati e i file; l'invio è dell'home banking, dei servizi
dell'Agenzia delle Entrate o dell'intermediario.
- **Dove imposto periodicità e pro rata?** Nel profilo azienda, in [Tabelle azienda](Tabelle-azienda).
## Pagine correlate
[Contabilità](Contabilita) · [Fatturazione elettronica](Fatturazione-elettronica) · [Vendite](Vendite) ·
[Acquisti](Acquisti) · [Intrastat](Intrastat) · [Scadenzario](Scadenzario) · [Fiscalità italiana](Fiscalita-italiana) ·
[Automazioni](Automazioni) · [Report](Report)
[Contabilità](Contabilita) · [Fiscalità italiana](Fiscalita-italiana) · [Vendite](Vendite) · [Acquisti](Acquisti) ·
[Scadenzario](Scadenzario) · [Fatturazione elettronica](Fatturazione-elettronica) · [Tabelle azienda](Tabelle-azienda) ·
[Glossario](Glossario)
+172 -76
View File
@@ -1,103 +1,174 @@
# 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 (giacenze iniziali dalla 0.6.0, piano dei conti dalla 0.7.0; saldi e partite di apertura più avanti)
> **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
![077 · Import/Export · procedura guidata CSV/XLSX/JSON](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/077-import-export-wizard.png)
*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 · mappatura colonne](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/import-export-mappatura.png)
*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 · anteprima e validazione](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/import-export-anteprima.png)
*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
`articolo`\*, `deposito` (vuoto: il deposito dell'articolo, poi quello predefinito), `quantita`\* (maggiore di zero),
`costo_unitario` (vuoto: costo medio, standard o ultimo costo dell'articolo). L'articolo deve essere merce gestita a
magazzino e non può comparire due volte nello stesso deposito. Dalla 0.6.0 l'import scrive **un movimento di
magazzino per deposito** con la causale `APE` (esistenza iniziale) alla data dell'import e lo conferma: giacenze e
costo medio partono da lì (vedi [Magazzino](Magazzino#esistenze-iniziali)). Se la causale `APE` manca, le righe sono
saltate con un messaggio: aggiungila con *Aggiorna da tabelle base*.
### Piano dei conti
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, piano dei conti |
| **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 è **precaricato** con la contabilità (dalla 0.7, vedi [Contabilità](Contabilita));
l'importazione serve a chi vuole usare il piano del proprio commercialista o del gestionale precedente. I conti nuovi
si aggiungono; quelli che esistono si aggiornano se l'opzione **Se il codice esiste** è *Aggiorna*, altrimenti si
saltano. Lo stesso tracciato si usa per esportare il piano dell'azienda.
### 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 +176,79 @@ 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 nella mappatura ma non si importano ancora: le causali si gestiscono in
*Contabilità → Causali*.
## 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)). Le giacenze hanno per ora solo il
modello; il piano dei conti si esporta per intero. 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 +256,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)
+14
View File
@@ -55,6 +55,20 @@ Khaemhat invia e-mail (inviti, recupero password, documenti, report, avvisi) tra
I valori iniziali possono arrivare dalle variabili `KHAEMHAT_SMTP_HOST`, `_PORT`, `_USER`, `_PASSWORD`, `_FROM`,
`_SECURITY`; quelli salvati qui li sovrascrivono.
> **In 0.5.0** la pagina *Impostazioni* non c'è ancora (arriva con M12): il server SMTP si configura **solo con le
> variabili d'ambiente** e serve all'invio dei documenti per e-mail (vedi [Vendite](Vendite#invio-per-e-mail)).
>
> | Variabile | Valore |
> |---|---|
> | `KHAEMHAT_SMTP_HOST` | nome del server; senza, l'invio è spento |
> | `KHAEMHAT_SMTP_FROM` | indirizzo del mittente (solo l'indirizzo, ad esempio `ufficio@azienda.it`); obbligatorio insieme all'host |
> | `KHAEMHAT_SMTP_SECURITY` | `STARTTLS` (predefinito), `SSL` (o `TLS`, connessione cifrata dall'inizio) oppure `NONE` (solo su reti fidate) |
> | `KHAEMHAT_SMTP_PORT` | predefinita 587, oppure 465 con `SSL` |
> | `KHAEMHAT_SMTP_USER`, `KHAEMHAT_SMTP_PASSWORD` | credenziali, se il server le chiede (AUTH PLAIN o LOGIN); la password anche come `KHAEMHAT_SMTP_PASSWORD_FILE` |
>
> Il client SMTP è scritto in Khaemhat, senza librerie esterne: un messaggio per connessione, tre tentativi, l'esito
> nel [Log](Log), sezione *E-mail / PEC*.
**Prova:** premi **Invia e-mail di prova** dopo aver salvato: arriva un messaggio all'indirizzo indicato. L'esito
compare anche in [Stato sistema](Stato-sistema) (controllo *SMTP*) e nel [Log](Log), sezione *E-mail / PEC*.
+1
View File
@@ -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 |
+82 -22
View File
@@ -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.
![013 · Clienti · radar con menu compresso e sottomenu a comparsa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/013-clienti-radar-menu-compresso.png)
*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](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-home.png)
*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.
![007 · Menu laterale compresso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/007-menu-compresso.png)
*Mockup 007 — dashboard con il menu compresso a sole icone e accento Turchese (anteprima ridotta).*
![Khaemhat 0.3.0 · menu compresso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-menu-compresso.png)
*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 · su telefono](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-mobile.png)
*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)`).
![009 · Ricerca globale](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/009-ricerca-globale.png)
*Mockup 009 — ricerca "rossi": risultati raggruppati per clienti, articoli, documenti, contabilità e azioni (anteprima ridotta).*
![Khaemhat 0.3.0 · ricerca globale](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-ricerca.png)
*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
![010 · Pannello notifiche](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/010-notifiche.png)
*Mockup 010 — pannello laterale delle notifiche con filtri e azioni (anteprima ridotta).*
![Khaemhat 0.3.0 · notifiche](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-notifiche.png)
*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)
![011 · Aiuto in app](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/011-aiuto-in-app-wiki.png)
*Mockup 011 — l'aiuto della maschera Fatture: indice delle pagine a sinistra, pagina wiki con stato e revisione a destra.*
![Khaemhat 0.3.0 · aiuto in app](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/interfaccia-aiuto.png)
*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
![020 · Fattura di vendita · righe](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/020-fattura-vendita-righe.png)
*Mockup 020 — fattura di vendita: toolbar a icone con il suggerimento "Salva Ctrl+S", azioni contestuali, intestazione documento e righe (anteprima ridotta).*
![Khaemhat 0.3.0 · toolbar e documento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/design-documento.png)
*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 · Storico](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/allegati-storico.png)
*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`.
+78 -56
View File
@@ -1,83 +1,105 @@
# Intrastat
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M10)
> **Modulo di licenza:** INTRA · **Permessi principali:** `intrastat.declaration.write`, `intrastat.declaration.export` · **Specifica:** SPEC §11.7, §8.1
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** INTRA · **Permessi principali:** `intrastat.list.read` (elenchi), `intrastat.list.write`
> (generare e correggere), `intrastat.list.export` (file e invio) · **Specifica:** SPEC §11.7, ADR 0042
## A cosa serve
Il modulo Intrastat prepara gli **elenchi riepilogativi delle operazioni intracomunitarie** a partire dalle fatture
di vendita e di acquisto già registrate, controlla i dati mancanti e produce il **file nel tracciato dell'Agenzia
delle Dogane**, da trasmettere con i canali telematici previsti (la trasmissione avviene fuori da Khaemhat).
Gli **elenchi riepilogativi Intrastat** raccolgono le cessioni e gli acquisti di beni e servizi con soggetti di altri
Paesi dell'Unione europea. Khaemhat li **genera dalle fatture e note di credito confermate**, controlla i dati di ogni
riga, propone la **periodicità** dovuta e produce il file **SCAMBI.CEE** nel tracciato dell'Agenzia delle Dogane, da
trasmettere con i servizi telematici (la trasmissione avviene fuori da Khaemhat).
## Dove si trova
Nel mockup la voce è **Fatturazione elettronica → Intrastat**; il modulo di licenza è comunque **INTRA**, separato
da EINV.
**Fatturazione elettronica → Intrastat** (la voce compare con il modulo **INTRA**, separato da EINV).
## Schermate
![Khaemhat 0.10.0 · elenco Intrastat](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/intrastat-elenco.png)
*L'elenco delle cessioni di novembre 2026 dell'azienda demo: la fattura a Bergwerk Bau (Austria) con nomenclatura,
natura della transazione, consegna, trasporto, ammontare e massa netta; sotto, gli elenchi dell'anno.*
![049 · Intrastat](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/049-intrastat.png)
*Mockup 049 — elenchi di settembre (mensile): riquadri con i totali per sezione e le anomalie, elenco delle operazioni con paese, P.IVA, NC8, natura della transazione, consegna, trasporto, valore, massa e controllo; pulsanti Genera elenco e File SCAMBI.CEE*
## Flussi e sezioni
## Gli elenchi
| Flusso | Sezione | Modello |
|---|---|---|
| **Cessioni** | Beni · Rettifiche beni · Servizi · Rettifiche servizi | INTRA-1 bis, ter, quater, quinquies |
| **Acquisti** | Beni · Rettifiche beni · Servizi · Rettifiche servizi | INTRA-2 bis, ter, quater, quinquies |
| Modello | Contenuto |
|---|---|
| **INTRA-1 bis** | cessioni di beni verso altri Paesi UE |
| **INTRA-1 ter** | rettifiche alle cessioni di beni di periodi precedenti |
| **INTRA-1 quater** | servizi resi a soggetti UE |
| **INTRA-2 bis** | acquisti di beni da altri Paesi UE |
| **INTRA-2 ter** | rettifiche agli acquisti di beni di periodi precedenti |
| **INTRA-2 quater** | servizi ricevuti da soggetti UE |
I riquadri in testa mostrano il periodo e la periodicità, i totali di ogni sezione e il numero di **anomalie**.
La striscia in alto riporta il **periodo**, i totali di cessioni e acquisti di beni, dei servizi resi e ricevuti e il
numero di righe **da completare**.
## Periodicità
La periodicità (**mensile** o **trimestrale**) è determinata dalle **soglie di legge** in base agli importi delle
operazioni, separatamente per cessioni e acquisti. Le soglie sono parametri del pacchetto fiscale italiano e vengono
aggiornate con esso; Khaemhat propone la periodicità e la mostra nel riquadro *Periodo*.
Sotto i filtri Khaemhat indica la **periodicità dovuta** in base agli importi dei quattro trimestri precedenti, per
beni e servizi separatamente, con le soglie in vigore dal 2022:
## Dati richiesti per ogni operazione
| Flusso | Mensile se in almeno un trimestre | Altrimenti |
|---|---|---|
| Cessioni (beni o servizi) | più di 50.000 € | trimestrale |
| Acquisti di beni | più di 350.000 € | non dovuto |
| Acquisti di servizi | più di 100.000 € | non dovuto |
| Dato | Da dove viene |
La periodicità dell'elenco si sceglie nei filtri (mensile o trimestrale) insieme a esercizio e periodo.
## Generare l'elenco
1. Scegli **flusso**, **esercizio**, **periodicità** e **periodo**.
2. Premi **Genera** *periodo*. Khaemhat legge le fatture e le note di credito confermate nel periodo verso soggetti con
sede in un altro Paese UE:
- i **beni** sono raggruppati per controparte, nomenclatura e natura della transazione;
- i **servizi** hanno una riga per fattura, con il codice CPA;
- le **note di credito** diventano righe di rettifica.
3. Le righe aggiunte a mano con **Aggiungi riga** restano quando rigeneri l'elenco.
| Colonna | Da dove viene |
|---|---|
| Paese e partita IVA della controparte | anagrafica (P.IVA comunitaria verificata con VIES, vedi [Anagrafiche](Anagrafiche)) |
| **NC8** (nomenclatura combinata a 8 cifre) | scheda articolo ([Articoli e listini](Articoli-e-listini)) |
| Descrizione | riga del documento |
| **Natura della transazione** | causale del documento, modificabile (es. `11` vendita) |
| **Condizioni di consegna** | Incoterms del documento (es. DAP, FCA, EXW) |
| **Modo di trasporto** | dal documento (es. 1 mare, 3 strada) |
| Valore | imponibile in euro |
| **Massa netta** e unità supplementare | peso dell'articolo x quantità |
| Controparte, Paese, Partita IVA | anagrafica (vedi [Anagrafiche](Anagrafiche)) |
| **Nomenclatura / CPA** | codice doganale della scheda articolo ([Articoli e listini](Articoli-e-listini)) |
| **Natura** | proposta `11` (vendita o acquisto a titolo definitivo) |
| **Consegna**, **Trasporto** | proposti `DAP` e `3` (strada) |
| **Ammontare €** | imponibile della riga in euro |
| **Massa netta kg** | peso netto dell'articolo per quantità |
La colonna **Controllo** segnala lo stato di ogni riga: *OK*, *Manca peso netto* (riga evidenziata), *Extra-UE:
escluso* (la controparte non è comunitaria e la riga non entra negli elenchi), *INTRA-2 quater* (servizio ricevuto).
I dati richiesti dipendono dal modello e dalla periodicità; il tracciato preciso segue le istruzioni dell'Agenzia
delle Dogane in vigore.
Un clic sulla riga apre la scheda per correggere sezione, paese, partita IVA, codice, descrizione, ammontare,
massa, natura, consegna e trasporto; le righe si possono anche eliminare finché l'elenco non è inviato.
## Come si prepara l'elenco
## Controlli
1. Apri **Intrastat**, scegli **Periodo** e **Sezione**.
2. Premi **Genera elenco** del periodo: Khaemhat raccoglie le fatture intracomunitarie registrate.
3. Correggi le **anomalie** aprendo l'articolo o il documento (NC8 o peso mancanti, P.IVA non valida…).
4. Rigenera e controlla i totali con i registri IVA ([IVA](IVA)).
5. Premi **File SCAMBI.CEE** per scaricare il file nel tracciato dell'Agenzia delle Dogane; il file resta come
allegato della dichiarazione ([Allegati e file](Allegati-e-file)).
6. Trasmetti il file con il servizio telematico e registra l'avvenuto invio.
| Controllo | Cosa fare |
|---|---|
| **Completa** | niente |
| **Manca la nomenclatura** | completa il codice doganale sull'articolo e rigenera |
| **Manca la massa netta** | completa il peso netto sull'articolo, o la massa sulla riga |
| **Manca la partita IVA** | completa la partita IVA comunitaria della controparte |
| **Manca il codice CPA** | servizio senza codice: completalo sull'articolo |
| **Fuori UE** | la controparte non è comunitaria: la riga non entra nell'elenco |
## File e invio
1. **File SCAMBI.CEE** scarica il file a lunghezza fissa (frontespizio e record per beni, servizi e rettifiche).
Un elenco con righe da completare non si esporta. L'elenco passa a *File generato*.
2. Controlla il file con il software di controllo delle Dogane e trasmettilo.
3. **Segna come inviato** chiede il **protocollo di invio**: da quel momento l'elenco è di sola lettura.
> **Attenzione.** Il tracciato segue le specifiche pubblicate ma non è ancora stato verificato con il software di
> controllo delle Dogane: prima del primo invio controlla sempre il file (vedi [Roadmap](Roadmap)).
## Dati di esempio
I dati dimostrativi emettono una fattura non imponibile (art. 41) a **Bergwerk Bau GmbH** (Austria) con articoli che
hanno codice doganale e peso netto: generando l'elenco del mese corrente si vede una riga completa.
## Permessi e licenza
Serve il modulo **INTRA**. I codici dei permessi in testa sono indicativi (convenzione `modulo.entità.azione`, SPEC
§7.2) e saranno fissati in sviluppo.
| Permesso | Consente |
|---|---|
| `intrastat.list.read` | consultare gli elenchi |
| `intrastat.list.write` | generare, aggiungere e correggere righe |
| `intrastat.list.export` | scaricare il file e segnare l'invio |
## Attenzione
- Gli elenchi dipendono dalla qualità delle anagrafiche: NC8 e peso netto sugli articoli, P.IVA comunitarie valide.
- Soglie, modelli e campi obbligatori cambiano con le determinazioni dell'Agenzia delle Dogane: verificare sempre le
istruzioni in vigore prima dell'invio.
Serve il modulo **INTRA**.
## Pagine correlate
[IVA](IVA) · [Vendite](Vendite) · [Acquisti](Acquisti) · [Articoli e listini](Articoli-e-listini) ·
[Fatturazione elettronica](Fatturazione-elettronica) · [Fiscalità italiana](Fiscalita-italiana)
[Fatturazione elettronica](Fatturazione-elettronica) · [Dichiarazioni d'intento](Dichiarazioni-d-intento) ·
[Fiscalità italiana](Fiscalita-italiana)
+2 -2
View File
@@ -59,7 +59,7 @@ Ogni modulo scrive nella **propria sezione**. Il pannello a sinistra le elenca c
| **Autenticazione** | accessi, errori di password, blocchi, 2FA, nuovi dispositivi |
| **Database** | connessioni, manutenzione |
| **Migrazioni** | migrazioni applicate e loro esito |
| **Documenti** | creazione, emissione, annullamento di documenti |
| **Documenti** | conferma ed emissione con il numero assegnato, chiusura, riapertura, annullamento, eliminazione delle bozze (da 0.5.0) |
| **Contabilità** | registrazioni, liquidazioni, chiusure |
| **Magazzino** | movimenti, ricostruzioni |
| **SDI / e-invoicing** | generazione XML, invii, notifiche, scarti |
@@ -68,7 +68,7 @@ Ogni modulo scrive nella **propria sezione**. Il pannello a sinistra le elenca c
| **Attività programmate** | inizio, fine, durata, esito di ogni esecuzione |
| **Backup** | backup, copie remote, verifiche, ripristini |
| **API / MCP** | chiamate API e strumenti MCP |
| **E-mail / PEC** | invii e letture di posta |
| **E-mail / PEC** | invii e letture di posta: da 0.5.0 ogni messaggio messo in coda, inviato, ritentato o fallito, con la risposta del server SMTP |
| **Integrazioni** | VIES, cambi BCE, intermediari SDI |
| **UI / circuiti** | errori dell'interfaccia con lo stack completo |
| **Prestazioni** | query oltre 500 ms, richieste lente, garbage collection |
+137 -90
View File
@@ -1,148 +1,195 @@
# Magazzino
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M6)
> **Modulo di licenza:** CORE · **Permessi principali:** `inventory.entry.post`, `items.cost.read`, famiglia `inventory.*` · **Specifica:** SPEC §11.6, §22
> **Stato:** completa per la versione 0.10 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.10.0 (M10)
> **Modulo di licenza:** CORE · **Permessi principali:** `inventory.stock.read` (giacenze), `inventory.entry.*` (movimenti, inventario), `inventory.entry.post` (conferma, rettifiche, ricostruzione), `items.cost.read` (costi e valori) · **Specifica:** SPEC §11.6, ADR 0035
Il **magazzino** tiene la quantità e il valore di ogni articolo in ogni **deposito**. Le giacenze si aggiornano da
sole con i documenti (DDT, fatture accompagnatorie, carichi, resi) e con i movimenti manuali; da qui si fanno
trasferimenti tra depositi, inventari fisici, la proposta di riordino e la valorizzazione.
sole quando confermi un documento che muove la merce (DDT, fatture accompagnatorie, carichi dai fornitori, resi,
movimenti manuali); da qui consulti giacenze e movimenti, fai l'**inventario fisico**, generi la **proposta di
riordino** e calcoli la **valorizzazione** a una data.
> **In questa versione** ci sono giacenze per deposito, impegnato e ordinato, costo medio ponderato, movimenti per
> articolo, movimenti manuali e trasferimenti, inventario fisico con import dei conteggi, proposta di riordino,
> valorizzazione con analisi ABC e ricostruzione. Dalla 0.10 la [chiusura dell'esercizio](Chiusura-e-bilancio) registra le
> rimanenze finali al costo medio ponderato. Arrivano più avanti: il **libro inventari** e i report di magazzino
> stampabili (M13), FIFO e LIFO a lotti (dopo la 1.0).
## Dove si trova
Menu **Magazzino** → *Giacenze*, *Movimenti*, *Inventario fisico*, *Sottoscorta* (proposta di riordino),
*Trasferimenti*. I depositi e le causali di magazzino sono in [Tabelle azienda](Tabelle-azienda).
Menu **Magazzino** → *Giacenze*, *Movimenti*, *Inventario*, *Proposte di riordino*. I **depositi** e le **causali
di magazzino** sono in [Tabelle azienda](Tabelle-azienda); scorta minima, punto e lotto di riordino e fornitori
abituali sono nella scheda dell'articolo (vedi [Articoli e listini](Articoli-e-listini)).
## Le quattro quantità
## Le quantità
| Quantità | Significato | Da dove nasce |
|---|---|---|
| **Giacenza** | merce fisicamente presente nel deposito | carichi e scarichi confermati |
| **Impegnato** | merce riservata a ordini clienti confermati e non ancora evasi | ordini clienti, trasferimenti in bozza |
| **Ordinato** | merce in arrivo dai fornitori | ordini fornitore confermati e non ancora ricevuti |
| **Disponibile** | **giacenza - impegnato** | calcolata |
| **Giacenza** | merce presente nel deposito | movimenti dei documenti confermati |
| **Impegnato** | merce riservata a ordini clienti confermati e non ancora evasi | residuo degli ordini clienti |
| **Ordinato** | merce in arrivo dai fornitori | residuo degli ordini fornitore confermati |
| **Disponibile** | giacenza meno impegnato | calcolata |
Il sistema registra anche la merce **in transito** e il **valore medio** per articolo e deposito. Tutte queste
quantità sono aggiornate **nella stessa transazione** del documento che le muove: non c'è mai un momento in cui il
documento è confermato e la giacenza no.
Tutte si aggiornano **nella stessa operazione** che conferma il documento: non c'è mai un momento in cui il documento
è confermato e la giacenza no. Se annulli il documento, i suoi movimenti spariscono e le quantità tornano come prima.
## Quali documenti muovono il magazzino
Ogni tipo documento ha una **causale di magazzino** (in *Tabelle azienda → Tipi documento*) che decide se carica,
scarica o trasferisce. Con i tipi di base:
| Documento | Causale | Effetto |
|---|---|---|
| DDT, fattura immediata, fattura accompagnatoria | `SCA` scarico per vendita | scarica al costo medio |
| DDT fornitore (carico), fattura fornitore | `CAR` carico da acquisto | carica e aggiorna il costo medio |
| Nota di credito fornitore | `RESF` reso a fornitore | scarica |
| Movimento di magazzino (`MM`) | quella scelta nel movimento | carico, scarico o trasferimento |
| Ordini clienti e fornitori, preventivi, fatture differite | nessuna | solo impegnato e ordinato |
Una fattura nata da un DDT **non muove di nuovo** la merce: le sue righe trovano il carico o lo scarico già fatto
dal DDT. Il prezzo della fattura fornitore però **corregge il costo** del carico: se il fornitore fattura a un prezzo
diverso da quello del DDT, il costo medio viene ricalcolato con il prezzo fatturato.
Le causali di base sono: `CAR` carico da acquisto, `SCA` scarico per vendita, `RESC` reso da cliente, `RESF` reso a
fornitore, `TRA` trasferimento tra depositi, `INVP` e `INVN` rettifiche inventariali, `CVU` e `CVR` uscita e rientro
in conto visione (solo quantità), `OMA` omaggio, `AUTO` autoconsumo, `APE` esistenza iniziale. Per un'azienda creata
con una versione precedente le causali e i tipi documento mancanti si aggiungono con **Aggiorna da tabelle base** nel
menu `…` della tabella (vedi [Tabelle azienda](Tabelle-azienda)) o, per tutte le tabelle, con `scripts/seed.sh --base`.
## Giacenze e disponibilità
![036 · Giacenze, disponibilità, sottoscorta](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/036-giacenze.png)
*Mockup 036 — striscia di indicatori (valore magazzino, articoli gestiti, sottoscorta, sotto riordino, in arrivo) e griglia giacenze con stato (anteprima ridotta).*
![Khaemhat 0.6.0 · giacenze e disponibilità](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-giacenze.png)
In alto una **striscia di indicatori**: valore del magazzino, articoli gestiti, articoli **sottoscorta**, articoli
**sotto il punto di riordino**, valore **in arrivo** (ordinato).
In alto la striscia degli indicatori: **articoli in giacenza**, **sottoscorta**, **esauriti**, **articoli in
arrivo** (con ordini fornitore aperti) e **valore di magazzino** (visibile solo con `items.cost.read`).
La griglia mostra per ogni articolo: categoria, UM, **giacenza**, **impegnato**, **ordinato**, **disponibile**,
**scorta minima**, **punto di riordino**, **costo medio**, **valore** e uno **stato**:
Sotto, il filtro **Deposito** (tutti o uno solo) e la casella **Anche gli articoli senza giacenza**; poi il radar
con ricerca per codice o descrizione e i filtri rapidi **Categoria** e **Stato**. Per ogni articolo: categoria, unità,
giacenza, impegnato, ordinato, disponibile, scorta minima, costo medio, valore e uno **stato**:
| Stato | Quando |
|---|---|
| *OK* | disponibilità sopra il punto di riordino |
| *Sotto riordino* | disponibilità sotto il punto di riordino |
| *Sottoscorta* | disponibilità sotto la scorta minima (riga evidenziata) |
| *Esaurito · in arrivo* | giacenza a zero con ordini fornitore aperti |
| *Disponibile* | il disponibile più l'ordinato supera il punto di riordino |
| *Da riordinare* | disponibile più ordinato pari o sotto il punto di riordino |
| *Sottoscorta* | disponibile sotto la scorta minima |
| *Esaurito* | disponibile sotto zero, o a zero per un articolo con scorta minima o punto di riordino |
Filtri: ricerca (articolo, EAN, descrizione), **Deposito**, **Categoria**, **Mostra** (*Solo gestiti a magazzino*),
chip *Evidenzia sottoscorta*. Azioni: **Proposta di riordino**, **Inventario**. Il dettaglio per deposito di un
singolo articolo è anche nella scheda articolo (vedi [Articoli e listini](Articoli-e-listini)).
Le colonne *Ultimo carico* e *Ultimo scarico* si aggiungono dal selettore delle colonne del radar. I pulsanti
portano alla **proposta di riordino** e all'**inventario**, aprono la **valorizzazione** e la **ricostruzione**.
## Movimenti e trasferimenti
## Movimenti di un articolo
![037 · Movimento di magazzino manuale (trasferimento)](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/037-movimento-magazzino.png)
*Mockup 037 — trasferimento in bozza dal deposito SEDE al deposito furgone, con disponibilità all'origine e valore (anteprima ridotta).*
![Khaemhat 0.6.0 · movimenti di un articolo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-movimenti-articolo.png)
I **movimenti manuali** servono per tutto ciò che non passa da un documento di vendita o acquisto: carichi e scarichi
rettificativi, omaggi interni, consumi, **trasferimenti** tra depositi. Ogni movimento ha una **causale di
magazzino** che ne stabilisce l'effetto (carico, scarico, trasferimento).
Apri una riga delle giacenze (doppio clic o **Invio**) per vedere i movimenti dell'articolo in ordine di data: il
documento che li ha generati (il link lo apre), la causale, il cliente o fornitore, il deposito, la quantità, il
costo unitario e il **saldo progressivo**. **Apri l'articolo** porta alla scheda. Il widget *Sottoscorta* della
[Dashboard](Dashboard) apre direttamente questa finestra sull'articolo scelto.
Per un trasferimento:
## Movimenti manuali e trasferimenti
1. **Magazzino → Trasferimenti** (o *Movimenti*), **Nuovo**.
2. Scegli la causale di trasferimento, il **deposito di origine** e quello di **destinazione**.
3. Inserisci le righe: la colonna *Disp. origine* mostra quanto è disponibile nel deposito di partenza.
4. Se serve, **Stampa lista prelievo** per chi prepara la merce.
5. **Conferma**.
Per tutto ciò che non passa da un documento di vendita o acquisto (rettifiche, omaggi, autoconsumi, conto visione,
trasferimenti) usa **Magazzino → Movimenti** e crea un **Movimento di magazzino**: è un documento come gli altri
(vedi [Vendite](Vendite) per la maschera), con in più la **causale** e il **deposito**.
Un trasferimento genera **due movimenti collegati** (scarico dall'origine e carico nella destinazione) nella stessa
transazione. Finché il movimento è in bozza la merce dell'origine risulta **impegnata**.
1. Scegli la **causale**: decide se il movimento carica, scarica o trasferisce.
2. Indica il **deposito**; per un trasferimento anche il **deposito di destinazione**, diverso dall'origine.
3. Inserisci le righe con articolo e quantità; nei carichi il prezzo è il costo unitario.
4. **Conferma**: il magazzino si aggiorna. Un trasferimento scarica l'origine e carica la destinazione al costo medio,
senza cambiare il valore complessivo.
Un movimento confermato si può annullare: i suoi movimenti vengono tolti e le giacenze ricalcolate.
## Inventario fisico
![038 · Inventario fisico con conteggi e rettifiche](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/038-inventario-fisico.png)
*Mockup 038 — inventario guidato in cinque passi, griglia con giacenza teorica, contato, differenza, valore e rettifica (anteprima ridotta).*
![Khaemhat 0.6.0 · inventario fisico in conteggio](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-inventario.png)
L'inventario è una procedura guidata:
L'inventario confronta la merce contata con la **giacenza contabile** e trasforma le differenze in rettifiche.
1. **Preparazione**: scegli il **deposito**, la **data** e il criterio di **valorizzazione** (es. costo medio);
l'opzione **Blocca movimenti durante il conteggio** congela le giacenze del deposito.
2. **Conteggio**: **Stampa liste di conteggio** (anche per ubicazione e squadra) e inserisci i quantitativi contati
nella griglia oppure **Importa conteggi CSV**.
3. **Verifica differenze**: la griglia confronta **giacenza teorica** e **contato** e mostra differenza e valore;
il filtro *Solo differenze e da contare* aiuta a chiudere il lavoro.
4. **Rettifiche**: **Genera rettifiche** crea i movimenti di carico o scarico per allineare la giacenza al contato.
5. **Chiusura**: sblocca il deposito.
1. **Apertura**: in **Magazzino → Inventario** scegli il **deposito**, la **data del conteggio**, se vuoi una
**categoria** e una descrizione, poi **Apri inventario**. Khaemhat fotografa la giacenza contabile di ogni articolo
gestito a magazzino a quella data.
2. **Conteggio**: scrivi le quantità contate nella colonna *Contato* e premi **Salva conteggi**, oppure **Importa
conteggi** da un file CSV o di testo del lettore di codici a barre: una riga per articolo con *codice articolo* e
*quantità*, separati da punto e virgola, tabulazione o virgola (con la virgola la quantità usa il punto decimale).
Una riga di intestazione viene saltata; i codici non in lista sono segnalati.
3. **Verifica differenze**: il filtro **Mostra** (*Tutti*, *Da contare*, *Con differenze*) aiuta a chiudere il
lavoro; le righe con differenza sono evidenziate e la striscia in alto riassume articoli contati, differenze e
valore delle differenze.
4. **Registrazione**: **Registra rettifiche** crea alla data del conteggio un movimento `INVP` per le eccedenze e uno
`INVN` per gli ammanchi, e chiude l'inventario. Gli articoli **non contati restano come sono**.
**Annulla inventario** lo chiude senza muovere il magazzino; i conteggi restano consultabili. I movimenti successivi
alla data del conteggio non disturbano: le rettifiche sono alla data del conteggio e la giacenza di oggi tiene conto
di entrambi.
## Proposta di riordino
![039 · Proposta di riordino fornitori dal sottoscorta](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/039-proposta-di-riordino.png)
*Mockup 039 — proposta di riordino: indicatori, criterio di calcolo, quantità proposta modificabile e fornitore per riga (anteprima ridotta).*
![Khaemhat 0.6.0 · proposta di riordino](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-riordino.png)
La proposta elenca gli articoli sotto il punto di riordino con giacenza, impegnato, ordinato, disponibile, scorta
minima, punto e **lotto** di riordino, **quantità proposta** (modificabile), **fornitore** abituale, lead time,
prezzo e valore. In alto gli indicatori: articoli sotto riordino, proposte, valore, fornitori coinvolti, articoli
già coperti da ordini.
La proposta elenca gli articoli il cui **disponibile più ordinato** non copre più il **punto di riordino** (o, se manca,
la **scorta minima**). Per ogni articolo propone:
1. Scegli **deposito**, **fornitore** (o tutti) e il **criterio di calcolo** (es. *disponibile + ordinato < punto
di riordino*, con o senza l'impegnato).
2. **Ricalcola**, controlla e correggi le quantità proposte, togli la spunta alle righe da non ordinare.
3. **Genera ordini fornitore**: Khaemhat crea **un ordine in bozza per fornitore** (vedi [Acquisti](Acquisti)).
- la **quantità**: il **lotto di riordino** dell'articolo se c'è, altrimenti quanto riporta al punto di riordino (o
alla scorta minima); mai meno del **minimo d'ordine** del fornitore;
- il **fornitore abituale** (il preferito nella scheda articolo, *Fornitori*) con il suo prezzo e la **data di arrivo
prevista** dal lead time.
Il mockup indica come fabbisogno il maggiore tra il lotto e la differenza fra punto di riordino e disponibile più
ordinato; la formula definitiva (compresi gli arrotondamenti al lotto) sarà fissata in sviluppo. La proposta può
anche essere eseguita da una procedura pianificata o alimentata da una regola di automazione (evento *articolo sotto
il punto di riordino*, vedi [Automazioni](Automazioni)).
Correggi le quantità, cambia il fornitore di una riga o togli la spunta alle righe da non ordinare; **Ricalcola**
rilegge le giacenze. **Genera ordini fornitore** crea **un ordine in bozza per fornitore** con prezzi e condizioni del
fornitore: controllali e confermali da **Acquisti → Ordini fornitori** (vedi [Acquisti](Acquisti)). Le righe senza
fornitore non vengono ordinate.
## Costo medio e valorizzazione
- Il criterio di valorizzazione è il **costo medio ponderato**: a ogni carico il nuovo costo medio è
(valore della giacenza esistente + valore del carico) / (giacenza esistente + quantità caricata). FIFO e LIFO sono
predisposti ma non attivi.
- Il **valore** di una giacenza è quantità x costo medio.
- La **valorizzazione a data** ricostruisce quantità e valore a una data passata (ad esempio al 31 dicembre).
- Le **rimanenze finali** valorizzate alimentano la chiusura dell'esercizio e il **libro inventari** (vedi
[Contabilità](Contabilita)); sono disponibili le **scritture ausiliarie di magazzino** e l'**analisi ABC**.
![Khaemhat 0.6.0 · valorizzazione con classi ABC](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/magazzino-valorizzazione.png)
- Il criterio è il **costo medio ponderato** per articolo, su tutti i depositi: a ogni carico con valore il nuovo
costo medio è (valore della giacenza + valore del carico) / (giacenza + quantità caricata). Scarichi, trasferimenti
e conto visione escono al costo medio del momento e non lo cambiano.
- La scheda articolo mostra **costo medio** e **ultimo costo** calcolati dai movimenti.
- La **valorizzazione** (pulsante nelle giacenze) calcola quantità e valore **a una data** qualsiasi, anche passata,
con il criterio scelto: *costo medio ponderato*, *ultimo costo* o *costo standard*. Divide gli articoli in **classi
ABC**: A gli articoli che fanno l'80% del valore, B fino al 95%, C il resto.
- FIFO e LIFO sono previsti con la gestione a lotti. Il passo 4 della [chiusura](Chiusura-e-bilancio) registra le
rimanenze finali al costo medio ponderato.
## Ricostruzione
Se le giacenze risultassero non allineate (ad esempio dopo un ripristino o un import), la **ricostruzione** ricalcola
giacenze, impegnato, ordinato e costi medi ripercorrendo tutti i movimenti. È una procedura eseguibile a mano o da
attività programmata e non modifica i documenti. Vedi [Automazioni](Automazioni) e
[Attività programmate](Attivita-programmate).
Se le giacenze sembrano non tornare (dopo un ripristino, un import diretto nel database, un cambio di causale su un
tipo documento), **Ricostruisci** nelle giacenze riscrive tutti i movimenti dai documenti in vigore, dal più vecchio,
e ricalcola giacenze, impegnato, ordinato e costi. I documenti non cambiano e i dati restano consultabili durante il
lavoro, che mostra l'avanzamento. Richiede `inventory.entry.post`.
## Stati dei movimenti
La stessa ricostruzione gira ogni **domenica alle 2:15** come attività di sistema *Ricostruzione del magazzino* (vedi
[Attività programmate](Attivita-programmate)), su tutte le aziende attive.
| Stato | Effetto |
|---|---|
| **Bozza** | nessun effetto sulla giacenza (nei trasferimenti l'origine è impegnata) |
| **Confermato** | giacenze aggiornate; righe non più modificabili |
| **Annullato** | movimenti stornati |
## Esistenze iniziali
Per partire con le giacenze di un altro gestionale importa il tracciato **Giacenze iniziali** da
[Import ed export](Import-Export): articolo, deposito, quantità e costo unitario. Khaemhat crea e conferma un
movimento con causale `APE` per deposito, alla data dell'import.
## Permessi e licenza
Il magazzino è nel modulo **CORE**. Confermare un movimento richiede `inventory.entry.post`; vedere costi e valori
richiede `items.cost.read`.
Il magazzino è nel modulo **CORE**. Vedere giacenze e movimenti richiede `inventory.stock.read`; scrivere movimenti
e conteggi `inventory.entry.write`; confermare i movimenti, registrare le rettifiche e ricostruire
`inventory.entry.post`. Costi, valori e valorizzazione sono visibili solo con `items.cost.read`.
## Domande frequenti
- **Il disponibile è negativo.** Gli ordini clienti confermati impegnano più merce di quella in giacenza: ordina al
fornitore o rivedi le consegne.
- **Il costo medio è cambiato dopo un carico.** È il comportamento previsto del costo medio ponderato; il messaggio
sul DDT di carico indica il vecchio e il nuovo valore.
- **Durante l'inventario non riesco a scaricare merce dal deposito.** È attivo il blocco dei movimenti: termina la
procedura o disattiva il blocco.
- **La giacenza è negativa.** È stato confermato uno scarico senza merce a sufficienza (Khaemhat non lo blocca, per
non fermare le consegne): registra il carico mancante o fai un inventario.
- **Il costo medio è cambiato dopo una fattura fornitore.** Il prezzo fatturato era diverso da quello del DDT di
carico: il costo del carico viene corretto con il prezzo della fattura.
- **Un articolo non compare nelle giacenze.** Non ha movimenti: spunta *Anche gli articoli senza giacenza*. Se non
compare comunque, nella scheda non è *gestito a magazzino* o non è un bene.
- **L'articolo non è nella proposta di riordino.** Non ha punto di riordino né scorta minima, oppure l'ordinato già
lo copre.
## Pagine correlate
[Articoli e listini](Articoli-e-listini) · [Acquisti](Acquisti) · [Vendite](Vendite) ·
[Tabelle azienda](Tabelle-azienda) · [Report](Report) · [Contabilità](Contabilita) · [Automazioni](Automazioni)
[Tabelle azienda](Tabelle-azienda) · [Import ed export](Import-Export) · [Dashboard](Dashboard) ·
[Attività programmate](Attivita-programmate)
+1 -1
View File
@@ -30,7 +30,7 @@ volume `/data/files/<azienda>`; nel database c'è la loro scheda (nome, tipo, di
| Documenti | `sale_quotations`, `sale_orders`, `sale_documents`, `purchase_orders`, `purchase_documents`, ciascuno con righe, castelletto IVA e rate; `document_links` per l'evasione | [Vendite](Vendite), [Acquisti](Acquisti) |
| Magazzino | `inventory_entries` e righe, `item_balances` (giacenza, impegnato, ordinato per articolo e deposito) | [Magazzino](Magazzino) |
| Contabilità e IVA | `gl_accounts`, `gl_entries` e righe, `vat_registers`, `vat_settlements` | [Contabilita](Contabilita), [IVA](IVA) |
| Scadenzario | `open_items` (partite), `payments` | [Scadenzario](Scadenzario) |
| Scadenzario | `gl_open_items` (partite), `payments` e righe, `remittances` e righe, `sdd_mandates`, `bank_statements` e righe, `bank_match_rules`, `dunning_levels`, `dunning_letters` | [Scadenzario](Scadenzario) |
| CRM | `crm_leads`, `crm_opportunities`, `crm_activities`, `crm_campaigns`, `crm_tickets` | [CRM](CRM) |
| Canali | `sales_channels`, `channel_orders` | [Canali-e-commerce](Canali-e-commerce) |
| Utenti e sicurezza | `users`, `roles`, `role_permissions`, `user_sessions`, `api_keys` | [Utenti-e-permessi](Utenti-e-permessi) |
+46 -33
View File
@@ -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.
![008 · Preferenze utente · tema notturno e 8 colori di accento](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/008-preferenze-tema-colori.png)
*Mockup 008 — scheda Aspetto con tema Scuro (notturno) e accento Ocra selezionati; a destra l'anteprima dal vivo.*
![Khaemhat 0.3.0 · Il mio profilo, Aspetto](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/preferenze-profilo.png)
*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 |
|---|---|---|
+16 -6
View File
@@ -1,6 +1,6 @@
# Primi passi
> **Stato:** parziale (passi 1-4 completi) · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (passi 1-4), passi successivi M3-M5
> **Stato:** parziale (passi 1-4, 7, 10 e 12 completi; amministrazione da interfaccia con M12) · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0
> **Modulo di licenza:** CORE · **Livello richiesto:** super utente, poi amministratore · **Specifica:** SPEC §5.4, §7, §8, §12, §14
Questa pagina accompagna chi ha appena installato Khaemhat dal primo avvio del container fino alla prima fattura
@@ -57,6 +57,10 @@ disattivata al primo cambio password.
*Mockup 001 — pagina di accesso: a sinistra marca e funzioni principali, a destra il modulo con azienda, nome utente,
password e l'avviso della modalità Trial (anteprima ridotta).*
![Khaemhat 0.5.0 · pagina di accesso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/accesso-login.png)
*La pagina di accesso di Khaemhat 0.5.0.*
1. Nel campo **Azienda** lascia la prima azienda, già proposta (quella creata dal container, ad esempio
*Khaemhat Demo S.r.l.*). Il super utente e gli amministratori possono anche scegliere **Nessuna (account di
istanza)** per lavorare solo sulle pagine di amministrazione dell'istanza.
@@ -111,6 +115,10 @@ telefono. Non c'è un codice QR, perché generarlo richiederebbe una libreria es
*Mockup 002 — verifica in due passaggi: sei caselle per il codice, pulsante Verifica e nota sul codice che cambia
ogni 30 secondi (anteprima ridotta).*
![Khaemhat 0.5.0 · verifica in due passaggi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/accesso-verifica.png)
*La verifica in due passaggi di Khaemhat 0.5.0: il codice dell'app oppure un codice di recupero.*
Agli accessi successivi, dopo la password, compare la schermata **Verifica in due passaggi**: scrivi le 6 cifre
mostrate dall'app e premi **Verifica**. Il codice cambia ogni 30 secondi.
@@ -275,12 +283,14 @@ Con l'azienda configurata puoi emettere la prima fattura:
4. Scegli il cliente: pagamento, listino e agente vengono proposti dalla sua scheda.
5. Nella scheda **Righe** aggiungi l'articolo (`F4` apre la ricerca), la quantità e controlla prezzo e IVA.
6. Premi **Salva** (`Ctrl+S`): la fattura è in *bozza*.
7. Premi **Conferma ed emetti**: la fattura riceve il numero, diventa immutabile e, con il modulo ACCT attivo,
viene contabilizzata.
8. Dalla toolbar genera il PDF o l'XML FatturaPA: ogni file generato diventa un allegato della fattura.
7. Premi **Emetti**: la fattura riceve il numero e diventa immutabile.
8. Premi la **stampante** (`Ctrl+P`): l'anteprima di stampa offre il PDF e **Salva come allegato**; dal menu **⋯**
**Invia per e-mail** manda il PDF al cliente (serve il server SMTP, vedi [Impostazioni](Impostazioni#e-mail-smtp)).
La guida completa è in [Vendite](Vendite); l'invio allo SDI richiede il modulo EINV (vedi
[Fatturazione elettronica](Fatturazione-elettronica)).
![Khaemhat 0.5.0 · una fattura emessa](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento.png)
La guida completa è in [Vendite](Vendite). Dalla 0.7 la fattura confermata è già in [Contabilità](Contabilita); l'XML FatturaPA per lo SDI con M9
(modulo EINV, vedi [Fatturazione elettronica](Fatturazione-elettronica)).
## Domande frequenti
+8 -3
View File
@@ -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), M6 (0.6.0), M7 (0.7.0), M8 (0.8.0), M9 (0.9.0), M10 (0.10.0). **Prossima:** M11.
| # | 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
+252 -105
View File
@@ -1,165 +1,312 @@
# Scadenzario e tesoreria
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M8)
> **Modulo di licenza:** FIN · **Permessi principali:** `finance.openitem.read`, `finance.payment.post`, `finance.remittance.write`, `finance.bank.reconcile`, `finance.dunning.send` · **Specifica:** SPEC §11.8
> **Stato:** completa per la versione 0.8 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.8.0 (M8)
> **Modulo di licenza:** FIN (con ACCT per le registrazioni) · **Permessi principali:** `finance.schedule.read`/`write`
> (scadenzario, distinte, mandati, solleciti, flusso di cassa), `finance.payment.read`/`write` (incassi e pagamenti),
> `finance.bank.reconcile` (riconciliazione bancaria) · **Specifica:** SPEC §11.8, ADR 0038
## A cosa serve
Lo **scadenzario** tiene le **partite aperte** di clienti e fornitori, cioè le rate dei documenti ancora da incassare
o da pagare. Da qui si registrano **incassi e pagamenti** (con abbuoni, spese e differenze cambio), si preparano le
**distinte RiBa, SDD e bonifici SEPA** con il file per l'home banking, si gestiscono gli **insoluti**, si
**riconcilia** l'estratto conto della banca, si inviano i **solleciti** con gli interessi di mora e si guarda il
**flusso di cassa** dei prossimi mesi. Ogni operazione scrive da sola la sua registrazione in
[Contabilità](Contabilita): non serve passare dalla prima nota.
Lo scadenzario tiene le **partite aperte** di clienti e fornitori (le rate generate dai documenti), registra
**incassi e pagamenti** con abbuoni e spese, prepara le **distinte RiBa, SDD e bonifici SEPA**, gestisce gli
**insoluti**, **riconcilia** l'estratto conto della banca, invia i **solleciti** e mostra il **flusso di cassa**.
Ogni movimento genera da solo la registrazione contabile ([Contabilità](Contabilita)).
> **In questa versione** ci sono partite aperte con aging, incassi e pagamenti multipli e parziali, abbuoni, spese e
> differenze cambio, storno di un incasso, estratto conto del cliente con gli interessi di mora, distinte RiBa (CBI), SDD core e B2B
> (`pain.008`) e bonifici SEPA (`pain.001`) con presentazione, accredito e insoluti, mandati SDD, import
> dell'estratto conto CSV, CBI e CAMT.053 con abbinamento automatico e regole, solleciti su tre livelli con
> interessi di mora e invio automatico, flusso di cassa a 30-365 giorni e le scadenze sulla Home. Arrivano più
> avanti: il **blocco per fido** su ordini e documenti (con le vendite avanzate), il collegamento diretto con la
> banca (CBI online, PSD2) e le **stampe** dei report di tesoreria nella sezione [Report](Report) (M12).
## Dove si trova
Menu laterale **Scadenzario**: **Partite aperte**, **Incassi**, **Pagamenti**, **Solleciti**, **Distinte RiBa/SDD**,
**Riconciliazione bancaria**.
Menu laterale **Scadenzario** → *Partite aperte*, *Incassi*, *Pagamenti*, *Solleciti*, *Distinte RiBa/SDD*,
*Mandati SDD*, *Riconciliazione bancaria*, *Flusso di cassa*.
## Schermate
Il menu compare solo se la licenza comprende il modulo **FIN** e l'utente ha i permessi (vedi
[Licenze e moduli](Licenze-e-moduli) e [Utenti e permessi](Utenti-e-permessi)). Senza ACCT le partite esistono
comunque, ma le operazioni che scrivono in contabilità chiedono il modulo.
![053 · Partite aperte](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/053-scadenzario-partite.png)
*Mockup 053 — partite aperte dei clienti con riquadri di aging (non scaduto, 1-30, 31-60, 61-90, oltre 90 giorni), selezione multipla e azioni Registra incasso, Sollecito, Distinta RiBa (anteprima ridotta)*
Prima di iniziare servono:
![054 · Registra incasso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/054-scadenzario-incasso.png)
*Mockup 054 — dialogo Registra incasso su due partite: cliente, data, metodo, importo, banca, riferimento CRO, causale INC; abbuono di € 10,00 sulla seconda rata e anteprima della registrazione che verrà generata*
- almeno un **conto bancario dell'azienda** in **Tabelle azienda → Banche aziendali** con IBAN, conto contabile e, per le
distinte, **codice SIA** (RiBa), **CUC** e **identificativo creditore SEPA** (SDD) — vedi
[Tabelle azienda](Tabelle-azienda);
- i **metodi di pagamento** con il codice MP della fattura elettronica (MP05 bonifico, MP12 RiBa, MP19-MP21 SDD…);
- per RiBa e SDD, le **coordinate bancarie del cliente** nella sua anagrafica ([Anagrafiche](Anagrafiche)).
![055 · Distinte](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/055-distinte-riba-sdd-sepa.png)
*Mockup 055 — distinta RiBa con banca di presentazione, date, importo, salvo buon fine e passi guidati; a destra gli effetti con il controllo (OK, IBAN mancante, scaduta da escludere)*
## Partite aperte
![056 · Solleciti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/056-solleciti-pagamento.png)
*Mockup 056 — proposta di invio dei solleciti per cliente con livello, canale e interessi di mora; sotto, la tabella dei tre livelli con giorni, modello, canale e azione*
![Khaemhat 0.8.0 · partite aperte dei clienti con aging e stati](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-partite.png)
*Khaemhat 0.8.0 — partite aperte dei clienti di esempio: i riquadri di aging, i filtri, la selezione per registrare
l'incasso e gli stati (parziale, insoluta, scaduta, in distinta con il numero della distinta).*
![057 · Riconciliazione bancaria](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/png/057-riconciliazione-bancaria.png)
*Mockup 057 — movimenti dell'estratto conto con stato (abbinato, suggerito, insoluto, da abbinare), abbinamento proposto e confidenza; riquadri con saldo banca, saldo contabile e differenza*
Una **partita** è una rata di un documento: controparte, documento, numero della rata, scadenza, metodo, importo,
già incassato o pagato, residuo e stato. Le partite nascono dalla registrazione contabile delle fatture e delle note
di credito ([Vendite](Vendite), [Acquisti](Acquisti), [Contabilità](Contabilita)) secondo le condizioni di
pagamento; si vedono anche nei **partitari**.
## Partite e stati
Una **partita** è una rata di un documento: controparte, documento, numero rata, scadenza, importo, pagato, residuo,
metodo di pagamento, banca, stato e registrazione collegata. Le partite nascono dalle condizioni di pagamento dei
documenti ([Vendite](Vendite), [Acquisti](Acquisti)) o dall'import delle partite di apertura
([Import-Export](Import-Export)).
In alto cinque **riquadri di aging** sommano il residuo per anzianità: *non scaduto*, *1-30*, *31-60*, *61-90* e
*oltre 90 giorni*. I badge accanto al titolo danno il totale aperto e il totale scaduto.
| Stato | Significato |
|---|---|
| **Aperta** | non ancora incassata/pagata, non scaduta |
| **Parziale** | incassata in parte |
| **Aperta** | non ancora incassata o pagata |
| **Parziale** | incassata o pagata in parte |
| **Chiusa** | saldata |
| **Insoluta** | effetto tornato insoluto, riaperta con le spese |
| **In distinta** | inserita in una distinta RiBa/SDD presentata |
| **Contestata** | esclusa dai solleciti e dalle distinte finché non si risolve |
| **Insoluta** | effetto o addebito tornato indietro: la partita è di nuovo da incassare |
| **In distinta** | inserita in una distinta RiBa, SDD o bonifici: non si incassa a mano finché resta lì |
La griglia mostra anche i **giorni** rispetto alla scadenza (positivi se scaduta) e le etichette *Scaduta*,
*In scadenza*, *Aperta · split* (fatture in split payment). Il selettore **Clienti / Fornitori** cambia lato.
Oltre allo stato la griglia segnala **Scaduta** (in rosso), **In scadenza** entro 7 giorni e **Contestata** (una
partita contestata resta fuori da distinte e solleciti). La colonna **Gg** conta i giorni dalla scadenza: positivi
se scaduta, negativi se manca ancora tempo.
**Filtri.** Ricerca per controparte o documento; **Mostra** (*Aperte*, *Scadute*, *Insolute*, *In distinta*,
*Contestate*, *Chiuse*, *Tutte*); **Metodo** di pagamento; il selettore **Clienti / Fornitori** cambia lato (dal
menu *Pagamenti → Registra pagamento* si arriva direttamente ai fornitori). **Esporta** scarica la griglia in CSV.
![Khaemhat 0.8.0 · partite aperte dei fornitori](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-fornitori.png)
*Khaemhat 0.8.0 — Lo stesso elenco sul lato fornitori, con il pulsante Registra pagamento.*
**Modificare una partita.** La matita apre la scheda della rata: si cambiano **scadenza**, **metodo**, **banca** e
**contestazione** (con una nota). L'importo no: si corregge il documento.
**Estratto conto.** Selezionata una partita, **Estratto conto** mostra per quella controparte le partite aperte con
lo scaduto, gli interessi di mora maturati a oggi e gli incassi o pagamenti registrati.
## Registrare un incasso o un pagamento
1. In **Partite aperte** seleziona una o più partite dello stesso cliente e premi **Registra incasso**.
2. Compila **Data**, **Metodo** (es. bonifico MP05), **Importo**, **Banca azienda**, **Riferimento** (CRO) e
**Causale** (INC per gli incassi, PAG per i pagamenti).
3. Nella tabella *Partite da chiudere* distribuisci l'importo: per ogni rata **Incassato**, **Abbuono** e
**Residuo dopo**.
4. Leggi l'anteprima della prima nota che verrà generata (banca in dare, cliente in avere, abbuono sul suo conto).
![Khaemhat 0.8.0 · dialogo Registra incasso](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-incasso.png)
*Khaemhat 0.8.0 — Registra incasso su una partita del cliente: data, metodo, banca, riferimento, spese, la tabella
delle partite da chiudere e l'anteprima della registrazione.*
1. In **Partite aperte** seleziona una o più partite della **stessa controparte** (le partite in distinta non si
selezionano) e premi **Registra incasso** (o **Registra pagamento** sul lato fornitori).
2. Compila **Data**, **Metodo**, **Banca** dell'azienda (o la cassa), **Riferimento** (CRO o TRN), eventuali
**Spese** bancarie e **Note**.
3. Nella tabella *Partite da chiudere* ogni rata propone tutto il residuo: abbassa l'importo per un incasso
**parziale** oppure indica un **abbuono** per chiudere la differenza (es. il cliente arrotonda per difetto).
*Residuo dopo* mostra cosa resta aperto.
4. Leggi l'anteprima: *Banca (D) / Clienti (A)* per un incasso, *Fornitori (D) / Banca (A)* per un pagamento,
con gli abbuoni sul loro conto.
5. Premi **Registra e chiudi partite**.
Regole:
Cosa succede:
- **Abbuoni**: piccola differenza fra dovuto e incassato chiusa come abbuono attivo o passivo.
- **Differenze cambio** per le partite in valuta, **spese** bancarie e **storno** dell'incasso sono gestiti nello
stesso movimento.
- Un pagamento a un professionista rileva la **ritenuta d'acconto** da versare ([IVA](IVA)).
- viene scritta la registrazione con causale **INC** (incassi) o **PAG** (pagamenti), collegata al movimento;
- gli **abbuoni** vanno su *abbuoni passivi* (concessi al cliente) o *abbuoni attivi* (ottenuti dal fornitore);
- le **spese** vanno su *spese bancarie*; per le partite in valuta la **differenza cambio** fra il cambio della
fattura e quello dell'incasso va su *utili* o *perdite su cambi*;
- le **note di credito** aperte della stessa controparte si possono selezionare insieme alle fatture: riducono
l'importo da incassare;
- per una fattura di un **professionista** con ritenuta d'acconto, quando la fattura è pagata del tutto la ritenuta
diventa **da versare** e compare in *Ritenute e F24* ([IVA](IVA)).
**Incassi** e **Pagamenti** elencano i movimenti del periodo con controparte, documenti saldati, riferimento, banca,
origine (*Manuale*, *Distinta*, *Estratto conto*), importo, abbuoni, spese e la registrazione. La freccia
**Annulla** storna il movimento: la registrazione viene annullata e le partite tornano aperte com'erano.
![Khaemhat 0.8.0 · l'elenco degli incassi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-incassi.png)
*Khaemhat 0.8.0 — Incassi del periodo con documento saldato, riferimento CRO, banca e registrazione contabile.*
![Khaemhat 0.8.0 · l'elenco dei pagamenti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-pagamenti.png)
*Khaemhat 0.8.0 — Pagamenti ai fornitori con le spese bancarie e la freccia per annullarli.*
## Distinte RiBa, SDD e bonifici SEPA
| Tipo | Uso | File prodotto |
|---|---|---|
| **RiBa** | incasso di ricevute bancarie dai clienti | file CBI (tracciato standard RiBa) |
| **SDD core / B2B** | addebito diretto sul conto del cliente, con **mandati** | `pain.008` |
| **Bonifici SEPA** | pagamento dei fornitori | `pain.001` |
| MAV / RAV | gestiti come semplici scadenze | — |
| **RiBa (CBI)** | incasso delle ricevute bancarie dei clienti | file CBI RiBa a record di 120 caratteri |
| **SDD Core** | addebito diretto sul conto di un privato, con mandato | XML SEPA `pain.008.001.08` |
| **SDD B2B** | addebito diretto sul conto di un'impresa, con mandato B2B | XML SEPA `pain.008.001.08` |
| **Bonifici SEPA** | pagamento dei fornitori | XML SEPA `pain.001.001.09` |
1. **Distinte RiBa/SDD**, scegli **Tipo**, **Banca di presentazione**, **Data presentazione** e **Scadenze fino al**.
2. **Selezione effetti**: Khaemhat propone gli effetti; la colonna **Controllo** segnala *IBAN mancante* o
*Scaduta: escludere?*.
3. **Controlli**: IBAN, CIN, scadenze.
4. **Genera file CBI** (o il file SEPA): il file resta come allegato della distinta.
5. **Contabilizza distinta**: effetti attivi presentati in banca, con l'opzione **Salvo buon fine (anticipo)** per gli
anticipi s.b.f.
6. **Presentazione**: carica il file nell'home banking.
![Khaemhat 0.8.0 · nuova distinta RiBa con i passi guidati](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-distinte.png)
*Khaemhat 0.8.0 — Nuova distinta: tipo, banca, date, salvo buon fine e i passi; a destra gli effetti candidati con il
controllo (qui due effetti scaduti da valutare).*
**Storico distinte** mostra le distinte precedenti.
### Creare una distinta
### Insoluti
1. **Distinte RiBa/SDD → Nuova distinta**: scegli **Tipo**, **Banca di presentazione**, **Data presentazione** e
**Scadenze fino al**. Per le RiBa puoi spuntare **Salvo buon fine (anticipo)** se la banca anticipa gli importi.
2. A destra compaiono gli effetti candidati (partite con metodo RiBa, SDD o bonifico, non contestate, non già in
distinta). La colonna **Controllo** segnala cosa non va: *IBAN mancante* (o ABI/CAB per le RiBa), *mandato mancante* (SDD),
*Scaduta: escludere?*. Spunta gli effetti da includere: totale e numero si aggiornano.
3. **Crea distinta**: la distinta nasce in **Bozza** con il numero dell'anno (es. 2026/002) e le partite passano
*In distinta*.
Quando un effetto torna insoluto (anche dalla riconciliazione bancaria), la partita viene **riaperta** con le
**spese** addebitate e la registrazione con causale **INS**; lo stato diventa *Insoluta*.
### Dalla bozza alla chiusura
![Khaemhat 0.8.0 · dettaglio di una distinta in bozza](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-distinta-dettaglio.png)
*Khaemhat 0.8.0 — Storico distinte e dettaglio di una distinta s.b.f. in bozza, con gli effetti e le azioni.*
Da **Storico distinte** si apre una distinta e si procede:
| Passo | Azione | Effetto |
|---|---|---|
| 1 | **Genera file** | crea il file CBI o XML (scaricabile e conservato come allegato); stato *File generato* |
| 2 | **Contabilizza presentazione** | RiBa e SDD: i crediti passano da *Clienti* a *Effetti all'incasso* (con anticipo s.b.f. la banca accredita subito su *Banche c/anticipi*); bonifici: i fornitori sono pagati e la distinta si chiude |
| 3 | **Accredito** | alla scadenza la banca accredita: *Banca* in dare, *Effetti all'incasso* (o *Banche c/anticipi*) in avere; la distinta si chiude |
| — | **Insoluto** su una riga | l'effetto torna indietro: la partita torna *Insoluta*, la banca riprende l'importo e le **spese** dell'insoluto diventano una nuova partita del cliente |
Finché la distinta è in bozza si può togliere una riga (la ✕) o **eliminarla** del tutto: le partite tornano
aperte. Il file va poi caricato nell'home banking: Khaemhat non lo invia alla banca.
### Mandati SDD
![Khaemhat 0.8.0 · mandati SEPA Direct Debit](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-mandati.png)
*Khaemhat 0.8.0 — Mandati SDD con riferimento univoco (UMR), data di firma, schema, IBAN, ultimo incasso e stato.*
Ogni cliente che paga con addebito diretto deve aver firmato un **mandato**. In **Mandati SDD → Nuovo mandato**
indica cliente, **riferimento del mandato** (UMR, unico per creditore), data di firma, **schema** (*Core* per i
privati, *B2B* per le imprese), IBAN e BIC del debitore. Il primo addebito esce come **FRST**, i successivi come
**RCUR**. Un mandato **revocato** (o un mandato *una tantum* già usato) non vale più: la distinta segnala il cliente
come *mandato mancante*.
## Riconciliazione bancaria
1. **Riconciliazione bancaria**, scegli il conto e premi **Importa estratto conto**: formati **CSV**, **CBI** e
**CAMT.053**.
2. **Abbina automatico**: Khaemhat cerca l'abbinamento per importo, data, CRO/riferimento e nome, e indica una
**confidenza** in percentuale.
3. **Conferma suggeriti ≥ 90 %** conferma in blocco gli abbinamenti più sicuri; gli altri si confermano o si
correggono riga per riga.
4. Le righe senza documento (commissioni, F24, addebiti) si registrano direttamente; con una **regola salvata**
(es. "COMMISSIONI" → spese bancarie) i movimenti ricorrenti vengono riconosciuti in automatico.
5. I riquadri **Saldo banca**, **Saldo contabile** e **Differenza** mostrano cosa resta da abbinare.
![Khaemhat 0.8.0 · riconciliazione dell'estratto conto](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-riconciliazione.png)
*Khaemhat 0.8.0 — Movimenti dell'estratto conto con stato, abbinamento proposto e confidenza; in alto saldo banca,
saldo contabile e differenza.*
| Stato riga | Significato |
|---|---|
| **Abbinato** | collegato a incasso/pagamento registrato |
| **Suggerito** | abbinamento proposto, da confermare |
| **Da abbinare** | più candidati o nessuno |
| **Insoluto** | riapre la partita con le spese |
1. Scegli la **Banca** e premi **Importa estratto conto**. Formati accettati:
- **CSV** dell'home banking: Khaemhat riconosce da solo separatore e colonne dalla riga di intestazione
(*Data contabile*, *Data valuta*, *Descrizione*, *Importo* oppure *Entrate*/*Uscite*, anche in inglese);
- **CBI** (rendicontazione movimenti di conto corrente, record RH/61/62/63/64/EF);
- **CAMT.053** (XML ISO 20022).
I movimenti **già importati** vengono riconosciuti e saltati, anche se carichi due volte lo stesso file o due
file che si sovrappongono.
2. Khaemhat propone per ogni movimento cosa potrebbe essere, con una **confidenza** in percentuale:
| Abbinamento | Quando |
|---|---|
| **Partite** | importo uguale al residuo di una o più partite della stessa controparte |
| **Movimento registrato** | un incasso o pagamento già registrato a mano |
| **F24** | un versamento di imposte registrato in *Ritenute e F24* |
| **Accredito distinta** / **Insoluto** | l'accredito di una distinta presentata o un effetto respinto |
| **Regola** | una **regola salvata** riconosce il testo (es. *COMMISSIONI* → spese bancarie) |
La confidenza parte dall'importo (esatto o entro la tolleranza) e sale con il numero del documento o il CRO
nella descrizione, l'IBAN e il nome della controparte e la vicinanza delle date; una regola vale 98%.
3. **Conferma suggeriti ≥ 90%** conferma in blocco le proposte più sicure; le altre si confermano con ✓ o si
correggono riga per riga:
- ☰ **Abbina a partite** — scegli le partite: viene registrato l'incasso o il pagamento;
- € **Abbina a incasso o pagamento registrato** — collega un movimento già registrato a mano;
- 📖 **Registra su conto** — per le righe senza documento (commissioni, canoni, carburante) scegli il conto e,
se vuoi, salva una **regola** per le prossime volte;
- **Ignora** — il movimento non va riconciliato.
La freccia **Annulla abbinamento** riporta la riga da riconciliare e annulla quello che aveva registrato.
4. La striscia in alto mostra **saldo banca** (dall'ultimo estratto), **saldo contabile** del conto, **differenza** e
movimenti ancora da riconciliare. Le schede **Regole** ed **Estratti importati** elencano le regole salvate (con
quante volte sono state usate) e i file caricati.
## Solleciti
**Solleciti** (mockup 056) gestisce tre **livelli**, ciascuno con giorni di ritardo, modello, canale, interessi e
azione. Esempio del mockup:
![Khaemhat 0.8.0 · proposta di invio dei solleciti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-solleciti.png)
*Khaemhat 0.8.0 — Proposta di invio per cliente con prossimo livello, canale e interessi di mora; sotto i tre livelli.*
I solleciti seguono tre **livelli**, ciascuno con i giorni dopo la scadenza, il modello del messaggio, i **canali**
(e-mail, PEC, lettera PDF), gli interessi di mora e un'**azione**:
| Livello | Dopo (gg) | Modello | Canale | Interessi | Azione |
|---|---|---|---|---|---|
| 1 | 7 | Promemoria cortese | e-mail | no | — |
| 2 | 20 | Sollecito formale | PEC + e-mail | sì | notifica agente |
| 3 | 45 | Messa in mora | PEC + lettera PDF | sì | blocco cliente, notifica amministrazione |
| 2 | 20 | Sollecito | e-mail + PEC | sì | avvisa l'agente (in copia) |
| 3 | 45 | Diffida e blocco forniture | PEC + lettera PDF | sì | blocca il cliente |
- La **proposta di invio** elenca per cliente partite, scaduto, giorni massimi, ultimo sollecito, prossimo livello,
canale, interessi di mora e l'interruttore **Includi**. Sono esclusi per regola la PA e i clienti con partite
contestate.
- Gli **interessi di mora** seguono il D.Lgs. 231/2002 (transazioni commerciali); il tasso è un parametro aggiornato
periodicamente.
- **Anteprima** mostra i messaggi; **Invia N solleciti** li spedisce e li annota nel **registro invii**.
- Il livello 3 può **bloccare il cliente** (ordini e documenti richiedono un override).
- I solleciti si eseguono anche da **attività programmata** (riquadro *Prossima esecuzione*), vedi
[Automazioni](Automazioni).
![Khaemhat 0.8.0 · modifica di un livello di sollecito](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-sollecito-livello.png)
*Khaemhat 0.8.0 — Un livello si modifica con la matita: giorni, azione, canali, interessi, invio automatico, oggetto e
testo con i segnaposto.*
## Flusso di cassa e report
Nel testo si usano i **segnaposto** `{cliente}`, `{azienda}`, `{elenco}` (le partite scadute), `{totale}`,
`{interessi}`, `{riferimento}` e `{giorni}`.
| Report | Contenuto |
- La **Proposta di invio** elenca i clienti con partite scadute oltre i giorni del livello successivo a quello già
inviato: partite, scaduto, giorni massimi, ultimo sollecito, prossimo livello, canale e interessi. Sono esclusi per
regola la **pubblica amministrazione**, le partite **contestate** e quelle in distinta. L'interruttore
**Includi** toglie un cliente dall'invio.
- **Anteprima** scarica il PDF del sollecito del primo cliente incluso; **Invia N solleciti** mette in coda e-mail e
PEC con il PDF allegato (vedi [Impostazioni](Impostazioni) per SMTP e PEC) e scarica in un unico PDF le **lettere**
da stampare e spedire. Un cliente senza indirizzo e-mail o PEC viene saltato, con un avviso, se il livello non
prevede la lettera.
- Gli **interessi di mora** seguono il D.Lgs. 231/2002: tasso BCE di riferimento del semestre più 8 punti
(10,15% nel primo semestre 2026, 10,40% nel secondo), calcolati giorno per giorno sul residuo di ogni partita.
Gli interessi compaiono nel messaggio e nel PDF; non vengono addebitati in contabilità.
- Il livello con azione **Blocca il cliente** imposta il blocco nelle condizioni di vendita dell'anagrafica.
- Il **Registro invii** conserva ogni sollecito con data, livello, canale, destinatari, importo, interessi e stato
dell'invio.
- I livelli segnati **Automatico** partono da soli con l'attività programmata *Solleciti* (giorni feriali alle 7:00,
vedi [Attività programmate](Attivita-programmate)); solo e-mail e PEC, mai la lettera.
## Flusso di cassa
![Khaemhat 0.8.0 · flusso di cassa previsto a 90 giorni](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/scadenzario-flusso-di-cassa.png)
*Khaemhat 0.8.0 — Disponibilità di oggi, entrate e uscite previste per settimana con il saldo progressivo e i
movimenti che lo compongono.*
Il **flusso di cassa** parte dalla disponibilità di oggi (saldo contabile di banche e cassa) e aggiunge, periodo per
periodo, i movimenti attesi da sei **fonti** che si accendono e spengono con le caselle:
| Fonte | Da dove |
|---|---|
| Scadenzario | partite per scadenza, cliente/fornitore, metodo |
| Aging | crediti per fasce di ritardo (come i riquadri del mockup 053) |
| Estratto conto | per cliente/fornitore, anche in PDF da inviare |
| **Flusso di cassa 90 giorni** | entrate e uscite previste da partite, distinte e saldi bancari |
| Insoluti | effetti tornati insoluti con spese |
| Posizione bancaria | saldi dei conti e effetti presentati |
| Incassi da clienti | partite aperte dei clienti e gli effetti presentati senza anticipo, alla loro scadenza |
| Pagamenti a fornitori | partite aperte dei fornitori |
| Ordini clienti / fornitori | il residuo degli ordini non ancora fatturati, 30 giorni dopo la consegna prevista (o la data dell'ordine) |
| Ricorrenti | le registrazioni ricorrenti della contabilità (affitti, noleggi…) che muovono la banca |
| Imposte | i versamenti F24 non ancora pagati (IVA, acconto, ritenute) alla loro scadenza |
Vedi [Report](Report).
L'**orizzonte** va da 30 a 365 giorni, il **periodo** è la settimana o il mese. Le partite già scadute cadono nel
primo periodo. La striscia riassume disponibilità di oggi, entrate e uscite previste, saldo finale e **punto più
basso** (in rosso se il conto andrebbe in negativo).
## Sulla Home
Con il permesso `finance.schedule.read` la [Dashboard](Dashboard) mostra:
- nelle **Scadenze** gli incassi e i pagamenti dei prossimi giorni (al massimo 12), con il link alla partita;
- nelle **Cose da fare** il totale dei crediti scaduti, con il link ai solleciti.
## Dati di esempio
L'azienda demo (se la licenza comprende FIN) arriva con la banca *Banca Popolare Dimostrativa*, i versamenti dei
soci, incassi e pagamenti già registrati (uno parziale), una distinta RiBa accreditata con un **insoluto**, una
distinta s.b.f. in bozza, un mandato SDD, un estratto conto CSV da riconciliare con una regola per le commissioni e
un primo sollecito già inviato. Vedi [Dati di base e di esempio](Dati-di-base-e-esempio).
## Permessi e licenza
Serve il modulo **FIN** (e ACCT per le registrazioni contabili automatiche). I codici dei permessi in testa sono
indicativi (convenzione `modulo.entità.azione`, SPEC §7.2) e saranno fissati in sviluppo.
| Permesso | Cosa consente |
|---|---|
| `finance.schedule.read` | vedere partite, distinte, mandati, solleciti, flusso di cassa e le scadenze sulla Home |
| `finance.schedule.write` | modificare le partite, creare e presentare le distinte, gestire mandati e solleciti |
| `finance.payment.read` | vedere incassi e pagamenti |
| `finance.payment.write` | registrare e stornare incassi e pagamenti |
| `finance.bank.reconcile` | importare gli estratti conto, riconciliare, gestire le regole |
Serve il modulo **FIN**; le registrazioni contabili chiedono anche **ACCT**.
## Domande frequenti
**Il cliente ha pagato due fatture con un bonifico solo.** Seleziona entrambe le partite e registra un unico incasso,
distribuendo l'importo.
**Il cliente ha pagato due fatture con un bonifico solo.** Seleziona entrambe le partite e registra un unico incasso:
l'importo si distribuisce sulle rate, la più vecchia per prima. Se il bonifico arriva dall'estratto conto, *Abbina a
partite* fa la stessa cosa.
**Ho caricato l'estratto conto due volte.** Il riconoscimento dei movimenti già importati non è ancora definito
dalla specifica: sarà stabilito in sviluppo e descritto qui.
**Ho caricato l'estratto conto due volte.** Nessun problema: i movimenti già presenti vengono riconosciuti
dall'impronta (banca, data, importo, descrizione, riferimento) e saltati; il messaggio dice quanti.
**Ho registrato un incasso sbagliato.** In *Incassi* premi **Annulla** sulla riga: la registrazione viene stornata e
le partite riaperte. Se l'incasso veniva dalla riconciliazione, la riga dell'estratto torna *Da abbinare*.
**Una RiBa è tornata insoluta.** Apri la distinta in *Storico distinte* e premi **Insoluto** sulla riga (o confermalo
dalla riconciliazione): la partita torna aperta e le spese diventano una nuova partita da addebitare al cliente.
**Perché un cliente non compare tra i solleciti?** È una pubblica amministrazione, ha partite contestate o in
distinta, oppure il prossimo livello non è ancora maturato.
## Pagine correlate
[Contabilità](Contabilita) · [Vendite](Vendite) · [Acquisti](Acquisti) · [Anagrafiche](Anagrafiche) · [IVA](IVA) ·
[Automazioni](Automazioni) · [Report](Report) · [Attività programmate](Attivita-programmate)
[Contabilità](Contabilita) · [IVA](IVA) · [Vendite](Vendite) · [Acquisti](Acquisti) · [Anagrafiche](Anagrafiche) ·
[Tabelle azienda](Tabelle-azienda) · [Dashboard](Dashboard) · [Attività programmate](Attivita-programmate) ·
[Fiscalità italiana](Fiscalita-italiana) · [Report](Report)
+1 -1
View File
@@ -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
+119 -49
View File
@@ -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 · Tabelle azienda](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/tabelle-indice.png)
*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
![075 · Profilo azienda](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/075-profilo-azienda.png)
*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 riaprendo la liquidazione IVA (vedi [IVA](IVA)).
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,13 +92,13 @@ 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) |
| **Condizioni di pagamento** | con righe: rata, giorni, fine mese, giorno fisso, percentuale, IVA sulla prima rata; tipo SDI `TP01` (a rate), `TP02` (completo), `TP03` (anticipo) |
| **Banche aziendali** | IBAN, BIC, conto contabile, codici SIA/CUC per RiBa e SDD |
| **Banche aziendali** | IBAN, BIC, conto contabile, codice SIA (RiBa), CUC e identificativo creditore SEPA (SDD), banca predefinita; usate da incassi, distinte e riconciliazione dello [Scadenzario](Scadenzario) |
| **Agenti** | provvigione, iscrizione ENASARCO |
| **Vettori** | corrieri e trasportatori |
| **Porti** (condizioni di spedizione) | franco, assegnato… |
@@ -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
![076 · Codici IVA con nature SDI](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/076-codici-iva.png)
*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 · codici IVA](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/tabelle-codici-iva.png)
*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
![074 · Codici automatici e compilazione automatica](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/074-preferenze-codici-automatici.png)
*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 · codici automatici](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/tabelle-codici-automatici.png)
*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 da un conto dell'azienda presso la stessa banca (l'elenco ABI non è precaricato) | 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
+276 -212
View File
@@ -1,288 +1,352 @@
# 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. Dalla 0.6 i documenti **muovono il magazzino** (DDT e fatture
> accompagnatorie scaricano, gli ordini impegnano: vedi [Magazzino](Magazzino)). Dalla 0.7 fatture e note
> **si contabilizzano** da sole (vedi [Contabilità](Contabilita)). Dalla 0.8 gli **incassi** si registrano dallo [Scadenzario](Scadenzario).
> Dalla 0.9 le fatture emesse diventano **file FatturaPA** e si trasmettono allo SDI dalla
> [Fatturazione elettronica](Fatturazione-elettronica). Arrivano più avanti: il controllo del fido 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)
![Khaemhat 0.5.0 · radar delle fatture di vendita](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatture-radar.png)
*Le fatture dell'azienda di esempio: numero, data, tipo, cliente, riferimento, imponibile, totale e stato. Le bozze
non hanno ancora un numero.*
Ogni voce del menu apre un **radar** (vedi [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie#radar)): cerca per
numero, riferimento o cliente, filtra per **tipo**, **stato** e **anno**, ordina, scegli le colonne e salva la vista.
Un doppio clic (o `Invio`) apre il documento in una nuova scheda.
![Khaemhat 0.5.0 · radar dei preventivi](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-preventivi-radar.png)
*I preventivi: quelli evasi sono diventati ordini, uno è stato rifiutato, uno è in bozza.*
**Nuovo** chiede il tipo quando l'elenco ne raccoglie più d'uno (ad esempio fattura immediata, accompagnatoria,
differita, di acconto, parcella o pro forma):
![Khaemhat 0.5.0 · scelta del tipo di fattura](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-nuovo-tipo.png)
## La maschera del documento
![Khaemhat 0.5.0 · fattura immediata, scheda Righe](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento.png)
*Una fattura emessa: toolbar, intestazione con tipo, numero, stato, cliente e totale; righe; castelletto IVA,
scadenze e totali.*
- **Toolbar**: nuovo, salva (`Ctrl+S`), annulla le modifiche, elimina (solo bozze), **stampa** (`Ctrl+P`),
**allegati**, le azioni del documento (*Conferma*, *Emetti*, *Crea …*) e il menu **⋯** con *Duplica*, *Chiudi*,
*Riapri*, *Annulla documento*, *Invia per e-mail*. A destra il **radar** e i pulsanti per il documento precedente e
successivo.
- **Intestazione**: tipo e numero (in bozza *Numero alla conferma*), data, stato, badge *Dato dimostrativo* per i dati
di esempio; cliente con codice, località e partita IVA, condizioni proposte (pagamento, listino, agente); il totale
del documento con imponibile e IVA.
- **Schede**: *Righe* (si apre lì), *Testata*, *Trasporto* (DDT e fatture accompagnatorie), *Totali*, *Scadenze*,
*Note*, *Allegati*, *Collegamenti*, *Storico*. Il numero accanto al nome della scheda conta righe, rate o
collegamenti.
### Righe
Ogni riga ha articolo (`F4` per cercarlo), descrizione, unità di misura, quantità, prezzo, sconti a cascata (`10+3`),
codice IVA e importo. Scegliendo l'articolo Khaemhat propone descrizione, unità, codice IVA e prezzo secondo l'ordine
*prezzo netto del cliente → listino del cliente → listino base → prezzo dell'articolo* (vedi
[Articoli e listini](Articoli-e-listini)). Oltre alle righe di merce ci sono le righe **descrittive** (solo testo),
le righe di **spesa** (trasporto, incasso) e le righe di **sconto**; i DDT non accettano spese né sconti.
Sotto le righe: **castelletto IVA** (imponibile e imposta per codice IVA), **scadenze** (le rate della condizione di
pagamento) e **totali**.
### Testata
![Khaemhat 0.5.0 · fattura, scheda Testata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-documento-testata.png)
*La Testata con i gruppi Documento, Cliente, Condizioni e Dati fiscali.*
| Gruppo | Campi |
|---|---|
| **Documento** | tipo, numero (alla conferma), **data** *, validità (preventivi), data di consegna (ordini), revisione, riferimento e data del cliente, documento rettificato (note) |
| **Cliente** | **cliente** *, agente, valuta, listino |
| **Condizioni** | pagamento, modalità, banca, sconto di piede, prezzi IVA inclusa |
| **Dati fiscali** | esigibilità IVA, split payment, bollo a carico del cliente, CIG e CUP per la PA |
| **Ritenuta, cassa previdenza, ENASARCO** | per parcelle e provvigioni: aliquote, base, tipo e causale della ritenuta, cassa |
| **Note** | note stampate sul documento |
Scegliendo il cliente Khaemhat propone destinazione, listino, pagamento, agente e banca dalle sue **condizioni
commerciali** (vedi [Anagrafiche](Anagrafiche)). Per emettere una fattura ogni riga (tranne le descrittive) deve
avere il codice IVA.
### Trasporto (DDT e fatture accompagnatorie)
![Khaemhat 0.5.0 · DDT, scheda Trasporto](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-ddt-trasporto.png)
*Causale del trasporto, trasporto a cura del mittente, del destinatario o del vettore, porto, aspetto dei beni,
colli, pesi, inizio del trasporto.*
I dati di trasporto finiscono nella stampa insieme agli spazi per le **firme** del conducente, del vettore e del
destinatario.
### Collegamenti
![Khaemhat 0.5.0 · ordine cliente, scheda Collegamenti](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-collegamenti.png)
*Un ordine evaso: da quale preventivo nasce e quali DDT lo hanno evaso, con le quantità.*
I documenti sono **collegati riga per riga**: quando un DDT evade un ordine, ogni riga del DDT ricorda la riga
d'ordine di origine e la quantità evasa. Così Khaemhat calcola i **residui**, permette di riaprirli e scrive nel file
XML della fattura i riferimenti all'ordine (*DatiOrdineAcquisto*) e ai DDT (*DatiDDT*).
d'ordine e la quantità evasa. Così Khaemhat calcola i **residui** e lo stato (*Evaso in parte*, *Evaso*). Il
collegamento vale dalla **conferma** del documento che evade: una bozza non toglie nulla al residuo, un documento
annullato lo restituisce. Una nota di credito mostra qui la fattura che rettifica.
## Dal preventivo alla fattura: Crea …
```
Preventivo ──trasforma──► Ordine cliente ──evadi──► DDT ──fattura differita──► Fattura TD24
└────────────── evadi ──────────────► Fattura immediata TD01
Preventivo ──Crea Ordine──► Ordine cliente ──Crea DDT──► DDT ──Fatturazione differita──► Fattura differita (TD24)
└──────────── Crea Fattura immediata ─────────────► Fattura immediata (TD01)
Fattura ──Crea Nota di credito──► Nota di credito (TD04)
```
Alla **conferma**, in un'unica operazione indivisibile, il documento riceve il numero, muove il magazzino, genera
le scadenze e le partite, crea la registrazione contabile e gli allegati: o riesce tutto o non cambia nulla.
![Khaemhat 0.5.0 · Crea ordine dal preventivo](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-trasforma.png)
*Crea Ordine cliente da un preventivo: si scelgono le righe; per un documento che evade, la quantità proposta è
quella ancora da evadere.*
## La maschera di un documento di vendita
I pulsanti **Crea …** della toolbar elencano i documenti che si possono generare da quello aperto. Se il nuovo tipo
**evade** il vecchio (preventivo → ordine, ordine → DDT o fattura, DDT → fattura differita) le righe prendono solo le
**quantità residue**, che puoi ridurre, e restano collegate; altrimenti (ad esempio fattura → nota di credito) le
righe si **copiano**. Il nuovo documento nasce in **bozza** e si apre in una nuova scheda. **Duplica** crea invece un
documento dello stesso tipo con la data di oggi.
![020 · Fattura di vendita · righe](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/020-fattura-vendita-righe.png)
*Mockup 020 — fattura in bozza: toolbar con Conferma ed emetti, XML SDI, Contabilizza, Evadi da…; intestazione; righe con riga descrittiva; castelletto IVA, scadenze e totali (anteprima ridotta).*
## Preventivi
![021 · Fattura di vendita · testata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/021-fattura-vendita-testata.png)
*Mockup 021 — scheda Testata con i gruppi Documento, Controparte, Condizioni, Magazzino e trasporto (anteprima ridotta).*
Il preventivo ha una **validità** (giorni o data) che compare nella stampa. Quando il cliente accetta, **Crea Ordine
cliente**; se rifiuta, **⋯ → Segna come rifiutato** (il preventivo passa a *Chiuso*). Un preventivo trasformato in
ordine risulta *Evaso*.
![022 · Fattura di vendita · tema scuro](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/022-fattura-vendita-tema-scuro.png)
*Mockup 022 — la stessa fattura in tema scuro con accento Malachite (anteprima ridotta).*
## Ordini clienti
La struttura è quella descritta in [Interfaccia e scorciatoie](Interfaccia-e-scorciatoie): toolbar, intestazione a
tre blocchi, schede **Righe** (si apre lì), *Testata*, *Totali*, *Trasporto*, *Scadenze*, *Dati SDI/PA*, *Note*,
*Allegati*, *Collegamenti*, *Storico*.
L'ordine raccoglie gli impegni presi con il cliente. Da un ordine confermato si creano **DDT** o **fatture
immediate**, anche più di uno, finché resta un residuo; la scheda *Collegamenti* mostra chi ha evaso cosa. **⋯ →
Chiudi** chiude il residuo che non verrà consegnato, **Riapri** lo riporta aperto. Per la PA la Testata raccoglie CIG
e CUP, riportati nella stampa.
| Gruppo della Testata | Campi |
## DDT (documenti di trasporto)
Il DDT accompagna la merce: si compila la scheda *Trasporto* e si stampa con gli spazi per le firme. Un DDT confermato
non ancora fatturato compare nella **fatturazione differita**; un DDT fatturato risulta *Evaso*. Finché non è
fatturato le righe si possono ancora correggere; **Annulla documento** lo annulla con un motivo. Alla conferma il DDT
**scarica il magazzino** (causale `SCA`); la fattura differita che lo fattura non scarica di nuovo.
## Fatture
1. **Vendite → Fatture → Nuova fattura**, scegli il tipo, oppure parti da un ordine con **Crea Fattura immediata**.
2. Scegli il cliente: condizioni, listino, agente e destinazione vengono proposti.
3. Inserisci le righe e controlla castelletto IVA, scadenze e totali.
4. **Emetti** (permesso `sales.invoice.issue`): assegna il numero e blocca il documento.
Una fattura **emessa non si modifica**. Per correggerla si emette una **nota di credito**; finché il file XML non è
stato inviato allo SDI si può **annullare** indicando il motivo (il numero resta usato).
## Note di credito (TD04) e di debito (TD05)
![Khaemhat 0.5.0 · nota di credito](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-nota-credito.png)
*Una nota di credito che storna un articolo difettoso: l'intestazione indica la fattura rettificata.*
Si crea dalla fattura con **Crea Nota di credito** (le righe si copiano e si tolgono quelle che non vanno stornate) o
da **Vendite → Note di credito → Nuova nota**. Usa lo stesso numeratore delle fatture.
## Pro forma e parcelle
La **pro forma** è un documento **non fiscale** (ad esempio per chiedere un anticipo): stessa maschera della fattura,
numerazione propria (`PF-2026-0001`), nessun file XML e nessun effetto contabile; si trasforma in fattura quando
serve. La **parcella** (TD06) calcola la **cassa previdenza** e la **ritenuta d'acconto** e mostra il **netto a
pagare**; gli acconti su parcella usano TD03.
## Fatturazione differita
![Khaemhat 0.5.0 · fatturazione differita](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-fatturazione-differita.png)
*Ottobre: tre DDT da fatturare, uno per cliente; a destra la fattura in cui finirà ciascuno.*
1. **Periodo e cliente**: *DDT dal* e *DDT al*, un cliente (vuoto per tutti), la **data delle fatture** e il
**raggruppamento** (*una fattura per cliente* o *una fattura per DDT*). Spunta *Emetti subito le fatture* per
numerarle subito; altrimenti restano in bozza da controllare. Premi **Cerca i DDT**.
2. **Scelta dei DDT**: l'elenco mostra i DDT confermati e non ancora fatturati con la fattura che verrà generata;
togli la spunta a quelli da fatturare più avanti.
3. **Genera fatture**: crea una fattura differita (TD24) per gruppo, con i riferimenti ai DDT nelle righe; i DDT
diventano *Evasi*. Il riepilogo indica quante fatture sono state create; un clic le apre.
Con *una fattura per cliente* i DDT dello stesso cliente finiscono in una sola fattura, che prende pagamento,
banca e condizioni dal primo DDT; se un cliente ha DDT con condizioni diverse scegli *una fattura per DDT*. La fattura differita va emessa entro il giorno 15 del mese successivo a quello delle consegne.
## Stampa e PDF
![Khaemhat 0.5.0 · anteprima di stampa di una fattura](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-stampa.png)
*L'anteprima di stampa: intestazione dell'azienda, cliente, righe, riepilogo IVA, scadenze e totali.*
La **stampante** della toolbar (`Ctrl+P`) salva il documento se serve e apre l'**anteprima di stampa**:
| Pulsante | Che cosa fa |
|---|---|
| **Documento** | Tipo documento, Sezionale/Numero, **Data** *, Registro IVA, Competenza IVA, Valuta, Cambio, Vostro riferimento |
| **Controparte** | **Cliente** *, Destinazione, Fatturare a, Agente, Listino |
| **Condizioni** | Pagamento, Inizio rate (es. fine mese), Banca azienda, Sconto piede %, Spese incasso, Bollo (automatico) |
| **Magazzino e trasporto** | Causale magazzino, Deposito, Vettore, Porto, Colli |
| **Stampa** | la stampa del browser (scegli la stampante o *Salva come PDF*) |
| **Apri PDF** / **Scarica PDF** | il PDF disegnato da Khaemhat, identico all'anteprima |
| **Salva come allegato** | conserva il PDF tra gli **allegati** del documento come nuova versione e segna il documento come *stampato* |
| 75% · 100% · 125% | lo zoom dell'anteprima |
Scegliendo il cliente, Khaemhat propone destinazione, listino, pagamento, agente e banca dalle sue condizioni
commerciali; dal tipo documento propone causale e deposito.
La stampa riporta i dati dell'azienda dal **profilo azienda** (ragione sociale, indirizzo, partita IVA, REA, capitale
sociale, contatti e la nota a piè di pagina; vedi [Tabelle azienda](Tabelle-azienda)), il logo (nel PDF se è un
JPEG), il cliente, i campi utili (pagamento, banca, riferimento, validità, agente, CIG e CUP), le righe, il
**riepilogo IVA**, le **scadenze**, i totali con bollo e ritenuta e le diciture previste (split payment, pro forma non
valida ai fini fiscali, fattura differita con i DDT). Le bozze, i documenti annullati e i dati dimostrativi portano
una scritta in evidenza. Il DDT ha in più il riquadro del trasporto e le firme:
Le **righe** hanno: articolo, descrizione, UM, quantità, prezzo, sconti (anche `5+2`), codice IVA, importo, deposito,
data di consegna. Le righe descrittive (solo testo) servono per riferimenti e note. Sotto la griglia: **castelletto
IVA** (imponibile e imposta per codice IVA, esigibilità), **scadenze** (rate con data, metodo e importo) e
**totali**.
![Khaemhat 0.5.0 · anteprima di stampa di un DDT](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-stampa-ddt.png)
Ogni PDF salvato diventa un **allegato versionato** (vedi [Allegati e file](Allegati-e-file)): nella scheda
*Allegati* si vedono tutte le versioni, con chi le ha create e quando. Il generatore si chiama *Stampa del documento
in PDF*.
## Invio per e-mail
![Khaemhat 0.5.0 · invio di una fattura per e-mail](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/wiki/img/vendite-email.png)
*Destinatario dall'anagrafica del cliente, oggetto e testo dal modello; il PDF parte in allegato.*
**⋯ → Invia per e-mail** (su un documento salvato) propone:
- **Destinatari**: l'e-mail del cliente; più indirizzi separati da virgola o punto e virgola.
- **Oggetto** e **Messaggio** dal modello, con i campi `{{Documento}}`, `{{Numero}}`, `{{Data}}`, `{{Cliente}}`,
`{{Azienda}}` e `{{Totale}}` già compilati. Puoi cambiare tutto prima di inviare.
**Invia** salva il PDF tra gli allegati come nuova versione, lo allega al messaggio, mette il messaggio **in coda** e
segna il documento come *inviato*. Il messaggio parte in background: tre tentativi a distanza crescente; l'esito (o
l'errore del server) è nel [Log](Log), sezione **E-mail/PEC**. La coda vive in memoria: un messaggio ancora in attesa
quando Khaemhat si ferma non parte, e il log lo dice.
L'invio richiede un **server SMTP** configurato dall'amministratore con le variabili `KHAEMHAT_SMTP_*` (vedi
[Impostazioni](Impostazioni#e-mail-smtp)); senza, la finestra lo segnala e il pulsante *Invia* è spento.
## Tipi di documento e codici TD
| Documento | Codice TD (SDI) | Note |
|---|---|---|
| Fattura immediata | **TD01** | emessa contestualmente alla cessione o prestazione |
| Fattura accompagnatoria | **TD01** | fattura con i dati di trasporto, fa anche da documento di trasporto e scarica il magazzino |
| Fattura accompagnatoria | **TD01** | fattura con i dati di trasporto, fa anche da documento di trasporto |
| Fattura di acconto/anticipo su fattura | **TD02** | |
| Fattura di acconto/anticipo su parcella | **TD03** | |
| Nota di credito | **TD04** | riferita alla fattura da stornare |
| Nota di debito | **TD05** | |
| Parcella | **TD06** | con ritenuta d'acconto e cassa previdenza |
| Fattura semplificata | **TD07** | per importi fino a 400 euro |
| Nota di credito semplificata | **TD08** | |
| Nota di debito semplificata | **TD09** | |
| Nota di credito / di debito semplificata | **TD08** / **TD09** | |
| Fattura differita (beni con DDT, servizi documentati) | **TD24** | art. 21, comma 4, lett. a) DPR 633/72 |
| Fattura differita (triangolazioni interne) | **TD25** | art. 21, comma 4, terzo periodo, lett. b) |
| Cessione di beni ammortizzabili e passaggi interni | **TD26** | anche dalle dismissioni dei cespiti |
| Cessione di beni ammortizzabili e passaggi interni | **TD26** | |
| Autoconsumo o cessioni gratuite senza rivalsa (omaggi) | **TD27** | |
| Pro-forma | — | non è un documento fiscale: niente numerazione fiscale né XML |
| Pro forma | — | non è un documento fiscale: niente numerazione fiscale né XML |
Le autofatture e le integrazioni (TD16-TD29) sono negli [Acquisti](Acquisti). L'elenco completo dei codici è in
[Fiscalità italiana](Fiscalita-italiana).
## Preventivi
![026 · Preventivo / offerta con revisioni](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/026-preventivo-offerta.png)
*Mockup 026 — preventivo inviato, revisione 2 di 2, collegato a un'opportunità CRM; azioni Trasforma in ordine, Nuova revisione, Accettato, Rifiutato (anteprima ridotta).*
Il preventivo (offerta) ha una **validità** (es. 30 giorni, con data di scadenza) e uno stato (*Bozza*, *Inviato*,
*Accettato*, *Rifiutato*). Le schede sono *Righe*, *Testata*, *Totali*, *Condizioni e note*, *Revisioni*, *Allegati*,
*CRM*; sotto le righe il pannello **Revisioni** elenca le versioni con data, totale ed esito (*Superata*, *Inviata*).
1. Crea il preventivo, inserisci le righe e invialo per e-mail.
2. Se il cliente chiede modifiche usa **Nuova revisione**: la versione precedente resta consultabile come
*superata*.
3. Segna l'esito con **Accettato** o **Rifiutato**.
4. **Trasforma in ordine** crea l'ordine cliente con le stesse righe e collega i due documenti.
Con il modulo CRM il preventivo è collegato all'**opportunità** e ne aggiorna valore e fase (vedi [CRM](CRM)).
L'intestazione mostra anche il **margine** a chi può vedere i costi.
## Ordini clienti
![027 · Ordine cliente · evasione e residui](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/027-ordine-cliente.png)
*Mockup 027 — ordine di una PA con split payment, evaso al 38%: righe con ordinato, evaso, residuo, disponibile e stato; documenti collegati (anteprima ridotta).*
Azioni contestuali: **Genera DDT**, **Genera fattura**, **Impegna**, **Ordina a fornitore**, **Chiudi residuo**.
- **Evasione**: la griglia *Righe e stato di evasione* mostra per ogni riga quantità ordinata, evasa, residua e
disponibile, con uno stato (*Evaso*, *Parziale*, *Impegnato*, *Da ordinare*, *Aperto*) e una barra di avanzamento.
Il pannello **Documenti collegati** elenca DDT e fatture già generati e gli ordini fornitore nati dall'ordine.
- **Impegnato**: un ordine confermato **impegna** la merce, che resta in giacenza ma non è più disponibile per altri.
- **Residui**: le quantità non evase restano aperte finché non vengono consegnate o chiuse con **Chiudi residuo**.
- **Ordina a fornitore**: per le righe non disponibili crea un ordine fornitore.
- **Fido e scaduto**: se il cliente supera il fido o ha pagamenti scaduti, la conferma è bloccata; chi ha il
permesso di forzatura può procedere indicando il motivo.
- **Dati PA**: per la pubblica amministrazione la scheda *Dati PA (CIG/CUP)* raccoglie CIG, CUP e riferimenti alla
determina, riportati poi nell'XML della fattura.
## DDT (documenti di trasporto)
![028 · DDT · dati di trasporto, colli, firme](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/028-ddt-trasporto.png)
*Mockup 028 — DDT confermato e scaricato, da fatturare: scheda Trasporto con causale, vettore, porto, colli e pesi, firme (anteprima ridotta).*
Il DDT accompagna la merce e **scarica il magazzino** alla conferma. Azioni: **Stampa 3 copie**, **Fattura questo
DDT**, **Etichette colli**, **Riapri**.
| Gruppo (scheda Trasporto) | Campi |
|---|---|
| **Trasporto** | Causale del trasporto (vendita, reso, conto visione…), Trasporto a mezzo (mittente, destinatario, vettore), Vettore, Porto, resa (Incoterms), Inizio trasporto (data e ora), Targa, Annotazioni |
| **Colli e pesi** | Aspetto esteriore dei beni, Numero colli, Peso lordo, Peso netto, Volume, Pallet, Tracking |
| **Firme** | Conducente, Vettore, Destinatario (firme sulla stampa) |
Il DDT si stampa in **tre copie**. Un DDT confermato ha le righe non modificabili; **Riapri** (permesso
`sales.deliverynote.reopen`) storna lo scarico e lo rigenera alla nuova conferma. I **resi** da cliente si
registrano con un DDT con causale di reso, che ricarica il magazzino.
## Fatture
1. **Vendite → Fatture**, **Nuovo** (`Ctrl+N`) oppure parti da un ordine o da un DDT con **Evadi da…**.
2. Scegli il cliente (F4 per cercare): condizioni, listino, agente e destinazione vengono proposti.
3. Inserisci le righe: il prezzo segue l'ordine *netto cliente → listino cliente → listino base → prezzo articolo*
(vedi [Articoli e listini](Articoli-e-listini)).
4. Controlla castelletto IVA, scadenze e totali.
5. **Conferma ed emetti**: assegna il numero, blocca il documento, scarica il magazzino (accompagnatoria), genera
scadenze e registrazione contabile.
6. **XML SDI** genera il file FatturaPA, che si invia dal canale configurato (vedi
[Fatturazione elettronica](Fatturazione-elettronica)).
Una fattura **emessa non si modifica**. Per correggerla si emette una **nota di credito**; se l'XML non è ancora
stato inviato allo SDI si può **annullare** indicando il motivo.
## Note di credito (TD04)
![029 · Nota di credito TD04](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/029-nota-di-credito.png)
*Mockup 029 — nota di credito che storna una riga della fattura per reso merce difettosa, con rientro a magazzino e compensazione della partita (anteprima ridotta).*
La nota di credito indica la **fattura stornata**, il **motivo** e la causale (ad esempio *reso da cliente*); se
c'è un reso la merce **rientra a magazzino**. Il pannello **Partite** mostra l'effetto sulla partita della fattura
(ad esempio *chiude parzialmente la rata 1/1*). L'XML è di tipo TD04 e riporta il riferimento alla fattura
d'origine. La nota di debito (TD05) funziona allo stesso modo per gli addebiti integrativi.
## Pro-forma
Documento **non fiscale** (ad esempio per chiedere un anticipo): stessa maschera della fattura, senza numerazione
fiscale, senza XML e senza registrazione contabile. Si trasforma in fattura quando serve.
## Parcelle (TD06)
Per le aziende o gli studi che emettono parcelle: la parcella calcola la **cassa previdenza** (contributo
integrativo, con IVA propria) e la **ritenuta d'acconto** che il cliente tratterrà, e mostra il **netto a pagare**.
Gli acconti su parcella usano TD03.
## Fatturazione differita guidata
![030 · Fatturazione differita · procedura guidata](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/030-fatturazione-differita.png)
*Mockup 030 — procedura in quattro passi: parametri, selezione dei DDT non fatturati nel periodo, anteprima delle fatture, generazione (anteprima ridotta).*
1. **Parametri**: DDT dal… al…, **data fattura**, **sezionale**, tipo (*Fattura differita TD24*), **raggruppa**
(*per cliente, rispettando la preferenza* di raggruppamento del cliente), *Genera XML SDI*, *Invia e-mail al
cliente*.
2. **Selezione DDT**: elenco dei DDT non fatturati nel periodo con la fattura che verrà generata; togli la spunta
ai DDT da escludere.
3. **Anteprima fatture**: numero di fatture e totale.
4. **Generazione**: numera le fatture, le contabilizza e, se richiesto, genera l'XML. I riferimenti ai DDT sono
riportati in riga e nell'XML (*DatiDDT*).
La fattura differita va emessa entro il giorno 15 del mese successivo a quello delle consegne. La stessa procedura
è eseguibile da attività programmata (vedi [Automazioni](Automazioni)).
[Fiscalità italiana](Fiscalita-italiana). I tipi, i numeratori e i sezionali si configurano in *Tipi documento* (vedi
[Tabelle azienda](Tabelle-azienda)).
## Stati
| Documenti (preventivi, ordini, DDT) | Significato |
| Preventivi, ordini, DDT, pro forma | Significato |
|---|---|
| **Bozza** | modificabile, senza numero definitivo, nessun effetto |
| **Confermato** | numerato, effetti applicati (impegno, scarico) |
| **Evaso parzialmente** / **Evaso** | una parte o tutto è passato al documento successivo |
| **Chiuso** | concluso (anche con residuo chiuso a mano) |
| **Annullato** | annullato con motivo |
| **Bozza** | modificabile, senza numero, nessun effetto |
| **Confermato** | numerato; le righe si possono ancora cambiare finché non sono evase |
| **Evaso in parte** / **Evaso** | una parte o tutto è passato al documento successivo |
| **Chiuso** | concluso, anche con residuo chiuso a mano (o preventivo rifiutato) |
| **Annullato** | annullato con motivo; il numero resta usato |
| Fatture e note | Significato |
|---|---|
| **Bozza** | modificabile |
| **Emessa** | numerata, contabilizzata, immutabile |
| **XML generato** | file FatturaPA pronto |
| **Inviata allo SDI** | in attesa di esito |
| **Consegnata** | recapitata al cliente |
| **Scartata** | rifiutata dallo SDI: va corretta e rigenerata |
| **Non consegnata** | impossibile recapitarla: è disponibile nell'area riservata del cliente |
| **Emessa** | numerata e immutabile |
| **XML generato**, **Inviata allo SdI**, **Consegnata**, **Scartata**, **Non consegnata** | gli stati della [fatturazione elettronica](Fatturazione-elettronica) |
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
![025 · Anteprima di stampa / PDF](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/025-anteprima-stampa-pdf.png)
*Mockup 025 — anteprima di stampa della fattura: modello, copie, lingua, zoom (anteprima ridotta).*
`Ctrl+P` apre l'**anteprima di stampa** in una nuova scheda: si scelgono **modello**, numero di **copie** e
**lingua**, si ingrandisce (50%, 100%, adatta) e si stampa, si scarica il PDF o lo si invia. La stampa contiene le
diciture di legge previste ed è sempre in tema chiaro. Ogni PDF generato diventa un **allegato versionato** del
documento (vedi [Allegati e file](Allegati-e-file)).
L'invio per **e-mail o PEC** allega il PDF (e, se richiesto, l'XML o la copia di cortesia ZIP) usando i modelli
e-mail dell'azienda; il canale preferito è nelle condizioni del cliente.
## Collegamenti, duplicazione e corrispettivi
- **Collegamenti**: la scheda omonima mostra i documenti di origine e quelli generati (ordine → DDT → fattura) con
le quantità; l'icona *Collegamenti* della toolbar apre lo stesso elenco.
- **Duplica** crea un nuovo documento in bozza con le stesse righe; 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)
+5
View File
@@ -1,5 +1,8 @@
**[Khaemhat](Home)**
**Guida**
- [Guida all'uso](Guida-utente)
**Installazione**
- [Primi passi](Primi-passi)
- [Unraid](Installazione-Unraid)
@@ -25,9 +28,11 @@
**Contabilità e fisco**
- [Contabilità](Contabilita)
- [Chiusura e bilancio](Chiusura-e-bilancio)
- [IVA](IVA)
- [Cespiti](Cespiti)
- [Intrastat](Intrastat)
- [Dichiarazioni d'intento](Dichiarazioni-d-intento)
- [Scadenzario](Scadenzario)
- [Fatturazione elettronica](Fatturazione-elettronica)
- [Fiscalità italiana](Fiscalita-italiana)
Binary file not shown.

After

Width:  |  Height:  |  Size: 188 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 182 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 113 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 121 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 69 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 119 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 122 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 119 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 84 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 119 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 150 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 211 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 98 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 103 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 106 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 129 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 146 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 138 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 205 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 165 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 174 KiB

Loaded 100 of 732 files, more files were not shown because too many files have changed in this diff. Show more