Compare commits

...
52 Commits
Author SHA1 Message Date
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
Alby96 1c30054e3d Merge M2 · Sistema e sicurezza (#118)
Wiki / Publish the wiki (push) Successful in 8s
Release / Image and release (push) Successful in 2m25s
CI / PostgreSQL 16 integration (push) Successful in 1m23s
CI / Build and test (SQLite) (push) Successful in 1m0s
CI / Docker image (push) Skipped
CI / YAML check (push) Successful in 4s
CI / PostgreSQL 17 integration (push) Failing after 2m38s
2026-11-11 15:56:07 +01:00
Alby96andClaude Opus 5.5 4502526f4d ci: start the smoke-test containers with the variables M2 requires
CI / Build and test (SQLite) (pull_request) Successful in 59s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 4s
CI / Docker image (pull_request) Successful in 1m20s
Since M2 the instance refuses to start without a secret key, a super user and a
first company, and the home page redirects to the login. The CI and release smoke
tests now pass a throwaway key and test values, wait for /health/ready and check
the login page and its security headers.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:35:06 +01:00
Alby96andClaude Opus 5.5 032c602b49 feat: system and security - start-up, accounts, sign-in, licences, log, jobs, companies (M2)
CI / Build and test (SQLite) (pull_request) Successful in 55s
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) Failing after 2m4s
The instance now starts on its own from KHAEMHAT_* variables: it migrates the system
and company databases, creates the super user and the first company, and only then
reports ready. Users sign in with password and TOTP through revocable database
sessions, and licences decide which modules and how many companies are available.

- Configuration: every wrong variable reported at once (exit code 2), _FILE variants
- Accounts, password policy and lockout, TOTP with recovery codes, session states
  with token rotation, security audit with a hash chain
- Sign-in pages (mockups 001-003), authorization attributes, security headers and a
  CSP without inline scripts, login rate limit
- Signed licences, activation codes, test mode, licence tool
- DataProtection keys in the system database, encrypted with the instance key
- Memory or Redis cache (in-house RESP client) that falls back to memory
- Database log by section with trace id; cron scheduler with locks and system jobs;
  record history (audit_log)
- Company creation, states, company context and X-Company, 503 in maintenance
- In-memory SQLite databases stay alive for the process (tests, demo)
- Tests for all of the above, ADR 0019, wiki, SECURITY, CHANGELOG, STATUS, DATA-MODEL

Refs #15 #16 #17 #18 #19 #20 #21 #22 #23 #24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 15:29:24 +01:00
Alby96 4582837b70 Merge docs: chiusura M1 (#117)
Wiki / Publish the wiki (push) Successful in 13s
2026-11-11 13:27:42 +01:00
Alby96andClaude Opus 5.5 edce4702da docs: close M1 in STATUS and describe the data layer in the Architettura wiki page
CI / Build and test (SQLite) (pull_request) Successful in 54s
CI / PostgreSQL 16 integration (pull_request) Skipped
CI / PostgreSQL 17 integration (pull_request) Skipped
CI / YAML check (pull_request) Successful in 3s
CI / Docker image (pull_request) Successful in 1m21s
M1 is tagged v0.1.0. STATUS now points at M2 and lists what M1 handed over to it (migration log section, startup
refusal without a valid KHAEMHAT_SECRET_KEY, PostgreSQL performance numbers); the wiki explains the encrypted
company registry and the two engines in plain words.

Refs #14

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 13:19:12 +01:00
634 changed files with 111897 additions and 1544 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
+15 -5
View File
@@ -135,19 +135,29 @@ jobs:
docker build -f docker/Dockerfile --build-arg VERSION=0.0.0-ci --build-arg GIT_SHA="$(git rev-parse --short HEAD)" \
--label khaemhat-ci.job="$(hostname)" -t "$NAME:image" .
- name: Smoke test (/health/live, non-root user, PUID/PGID)
- name: Smoke test (start-up, login page, non-root user, PUID/PGID)
run: |
docker network create --label khaemhat-ci.job="$(hostname)" "$NAME"
docker network connect "$NAME" "$(hostname)"
# Since M2 the instance needs a key, a super user and a first company; the key is thrown away with the run.
docker run -d --name "$NAME-app" --network "$NAME" --label khaemhat-ci.job="$(hostname)" \
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test -e PUID=99 -e PGID=100 "$NAME:image"
for i in $(seq 1 30); do
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/live"; then echo; break; fi
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test \
-e KHAEMHAT_SECRET_KEY="$(head -c 32 /dev/urandom | base64)" \
-e KHAEMHAT_SUPERUSER=root -e KHAEMHAT_SUPERUSER_PASSWORD=Ci-Smoke-Test-2026 -e KHAEMHAT_COMPANY_CODE=CI \
-e PUID=99 -e PGID=100 "$NAME:image"
for i in $(seq 1 60); do
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/ready"; then echo; break; fi
sleep 2
done
curl -fsS --max-time 5 "http://$NAME-app:8080/health"
echo
curl -fsS --max-time 5 "http://$NAME-app:8080/" | grep -q "in costruzione"
test "$(curl -s -o /dev/null -w '%{http_code}' --max-time 5 "http://$NAME-app:8080/")" = "302"
# Read the whole response first: grep -q closes the pipe at the first match, and with pipefail the
# write error of curl (exit 23) would fail the step depending on timing.
login="$(curl -fsS --max-time 5 "http://$NAME-app:8080/login")"
grep -q "Accedi" <<<"$login"
headers="$(curl -fsS -D - -o /dev/null --max-time 5 "http://$NAME-app:8080/login")"
grep -qi "content-security-policy" <<<"$headers"
test "$(docker exec "$NAME-app" sh -c 'stat -c %u:%g /proc/1')" = "99:100"
test "$(docker exec "$NAME-app" stat -c %u:%g /data)" = "99:100"
docker exec "$NAME-app" pg_dump --version
+7 -4
View File
@@ -113,15 +113,18 @@ jobs:
--label khaemhat-ci.job="$(hostname)" \
-t "$IMAGE:$VERSION" .
- name: Smoke test (/health/live)
- name: Smoke test (/health/ready)
if: env.PUBLISHED != 'true'
run: |
docker network create --label khaemhat-ci.job="$(hostname)" "$NAME"
docker network connect "$NAME" "$(hostname)"
docker run -d --name "$NAME-app" --network "$NAME" --label khaemhat-ci.job="$(hostname)" \
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test "$IMAGE:$VERSION"
for i in $(seq 1 30); do
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/live"; then echo; break; fi
-e KHAEMHAT_SYSTEM_DB=sqlite:///data/system.db -e KHAEMHAT_LICENSE_MODE=test \
-e KHAEMHAT_SECRET_KEY="$(head -c 32 /dev/urandom | base64)" \
-e KHAEMHAT_SUPERUSER=root -e KHAEMHAT_SUPERUSER_PASSWORD=Ci-Smoke-Test-2026 -e KHAEMHAT_COMPANY_CODE=CI \
"$IMAGE:$VERSION"
for i in $(seq 1 60); do
if curl -fsS --max-time 5 "http://$NAME-app:8080/health/ready"; then echo; break; fi
sleep 2
done
report="$(curl -fsS --max-time 5 "http://$NAME-app:8080/health")"
+1
View File
@@ -424,3 +424,4 @@ deploy/.env
out/
# License signing keys (tools/Khaemhat.LicenseTool): the private key never enters the repository (ADR 0008).
*.khkey
*.pem
+369
View File
@@ -7,6 +7,375 @@ un'immagine `gitea.encke-hake.ts.net/balbosoft/khaemhat:X.Y.Z`.
## [Unreleased]
## [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
verifica in due passaggi.
### Added
- Avvio guidato dalle variabili `KHAEMHAT_*` (anche `_FILE`): tutte le variabili sbagliate elencate insieme e uscita
con codice 2; migrazioni del sistema e delle aziende all'avvio, super utente e prima azienda al primo avvio,
pagina "Avvio in corso" e `/health/ready` a 503 finché non è pronto (ADR 0019).
- Account di istanza (super utente, amministratori) e utenti aziendali, password PBKDF2-SHA256 con storico, blocco
dopo 5 errori, limite di 10 accessi al minuto per indirizzo IP.
- Pagine di accesso (mockup 001-003): scelta dell'azienda, cambio password obbligatorio, attivazione e verifica in
due passaggi (TOTP, RFC 6238) con 10 codici di recupero; uscita con `POST /logout`.
- Sessioni nel database con token salvato come hash, rigenerato a ogni passo, revocabili, riverificate dal circuito
Blazor ogni minuto; audit di sicurezza in `sys_security_audit` con catena di hash.
- Ruoli predefiniti, permessi `modulo.area.azione` con override per utente, attributi `[RequirePermission]`,
`[RequireLevel]`, `[RequireModule]`.
- Licenze: trial di 60 giorni, file `.khl` firmati ECDSA P-256, codici di attivazione dei moduli, modalità test con
i codici fittizi, limite di aziende e di utenti contemporanei; strumento `tools/Khaemhat.LicenseTool`.
- Chiavi DataProtection nel database di sistema, cifrate con la chiave di istanza.
- Cache in memoria o su Redis (client RESP scritto in casa, `KHAEMHAT_REDIS`), con ritorno alla memoria se Redis non
risponde.
- Log su database (`sys_log`) per sezioni, con identificativo di traccia (`X-Trace-Id`), utente e azienda; query
lente nella sezione *Prestazioni*; esito delle migrazioni nella sezione *Migrazioni*.
- Attività programmate: cron a 5 campi con fuso orario, lock, timeout, tentativi, storico; job di sistema per pulizia
sessioni, controllo licenza e retention del log.
- Storico dei record (`audit_log` aziendale) con i soli campi cambiati.
- Aziende: creazione e collegamento, stati attiva / manutenzione / sola lettura / disattivata, contesto azienda per
pagine e API (`X-Company`), risposta 503 per le aziende in manutenzione.
- Header di sicurezza su tutte le risposte (CSP senza script inline, `X-Frame-Options`, `nosniff`,
`Referrer-Policy`, `Permissions-Policy`).
- Tabelle di sistema e aziendali di M2, documentate in `docs/DATA-MODEL.md` (rigenerato).
### Changed
- La home richiede l'accesso: senza sessione porta a `/login`.
- I database SQLite in memoria restano disponibili per tutta la vita del processo.
## [0.1.0] - 2026-11-11
M1 — Strato dati. Nessuna funzione visibile nell'interfaccia: è il motore su cui si appoggiano tutte le milestone
+5
View File
@@ -88,6 +88,11 @@ fermandosi solo per blocchi reali (SDK mancante, credenziali, PNG o dati che sol
inglese che dicono *cosa cambia e perché*. Il push su Gitea e le pull request seguono le indicazioni dell'utente;
il tag `vX.Y.Z` si crea alla chiusura di ogni milestone (§20).
**E7 — Versioni 0.x fino al via dell'utente** (sostituisce la colonna versione di §20 per M13 e M14; deciso
dall'utente il 2026-11-12). Finché il prodotto è in sviluppo le versioni restano **0.x**: ogni milestone chiude con
`v0.<n>.0` (M13 `v0.13.0`, M14 `v0.14.0` e seguenti). La **1.0.0 non si crea** (tag, immagine, release, CHANGELOG)
finché l'utente non lo dice esplicitamente. L'icona versionata `icon-v1.0` resta il modello grafico.
## 4. Vincoli non negoziabili (sintesi di SPEC §1 — leggere l'originale)
1. C# 14 su .NET 10; JavaScript solo come interop minimo in `wwwroot/js`, senza framework né bundler.
+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
+2950 -16
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
+21 -13
View File
@@ -136,8 +136,8 @@ programmata passa da un controllo esplicito.
| Aspetto | Regola |
|---|---|
| Autenticazione | cookie ASP.NET Core con `CookieSessionAuthenticationHandler`; nessun ASP.NET Identity/EF |
| Attributi del cookie | `HttpOnly; Secure; SameSite=Lax` |
| Autenticazione | schema `KhaemhatSession` scritto in casa (`SessionAuthenticationHandler`, ADR 0019); nessun ASP.NET Identity/EF |
| Attributi del cookie | `khaemhat_session`, `HttpOnly; SameSite=Lax`; `Secure` quando la richiesta è HTTPS o `KHAEMHAT_PUBLIC_URL` è `https` |
| Identificatore | 256 bit casuali da `SecureTokenGenerator` (`RandomNumberGenerator`) |
| Stato | riga di sessione in `sys_sessions` (account di istanza) o `user_sessions` (utenti aziendali): dispositivo, IP, creazione, ultimo uso, revoca |
| Scadenza | scorrevole, con timeout di inattività da impostazioni (mockup 086: 480 minuti) |
@@ -148,9 +148,12 @@ programmata passa da un controllo esplicito.
| Antiforgery | sui form statici (login, cambio password, recupero) |
| Cookie ammessi | sessione e tema prima del login (SPEC §1.5); nessun cookie di profilazione |
Proposta: nella riga di sessione salvare l'**hash SHA-256** dell'identificatore, non il valore, così una lettura del
database non consente di impersonare le sessioni attive. Rigenerare l'identificatore dopo il login e dopo il
passaggio TOTP (prevenzione della session fixation).
**Implementato in M2.** La riga di sessione contiene solo l'**hash SHA-256** dell'identificatore: una lettura del
database non consente di impersonare le sessioni attive. L'identificatore viene **rigenerato a ogni passaggio di
stato** (password verificata, TOTP verificato, password cambiata), contro la session fixation. Una sessione che non è
ancora *attiva* (manca il TOTP o il cambio password) apre solo le pagine del suo passo. Il circuito Blazor ricontrolla
la sessione ogni minuto e si chiude se è stata revocata; mettere un'azienda in manutenzione o disattivarla revoca le
sessioni dei suoi utenti.
---
@@ -253,8 +256,8 @@ passaggio TOTP (prevenzione della session fixation).
interfaccia `ISecretProtector` in `Khaemhat.Core`.
- La chiave e i segreti in chiaro **non vanno mai** in log, messaggi d'errore, diagnostica, risposte API o file su
disco (SPEC §1.5: nessun `appsettings.<Env>.json` con segreti, nessun file temporaneo).
- Le varianti `_FILE` delle variabili (Docker secrets) sono previste per `KHAEMHAT_SYSTEM_DB` e le credenziali del
super utente; proposta: estenderle a `KHAEMHAT_SECRET_KEY` e alle altre variabili sensibili.
- Le varianti `_FILE` (Docker secrets) valgono per tutte le variabili sensibili, `KHAEMHAT_SECRET_KEY` compresa
(ADR 0014); impostare sia la variabile sia la sua `_FILE` è un errore di avvio.
### 7.2 Rotazione (`SecretRotationService`, `SecretRotation`)
@@ -275,8 +278,9 @@ della vecchia chiave come chiave di sola decifratura identificata dalla versione
- Le chiavi DataProtection di ASP.NET Core (cookie, antiforgery) sono nel **database di sistema**
(`sys_data_protection_keys`) tramite `DataProtectionDbXmlRepository`: nessun file su disco, cookie validi dopo un
riavvio o un nuovo container.
- Proposta: cifrare l'XML delle chiavi a riposo con un `IXmlEncryptor` basato su `SecretProtector`, così la sola
lettura del database di sistema non consente di falsificare cookie.
- **Implementato in M2** (`DataProtectionKeyStore`, `SecretKeyXmlEncryptor`): l'XML delle chiavi è cifrato a riposo
con `SecretProtector` (scopo `dataprotection:keys`), così la sola lettura del database di sistema non consente di
falsificare cookie o token antiforgery. Il database di sistema è migrato prima che DataProtection legga le chiavi.
---
@@ -286,14 +290,18 @@ della vecchia chiave come chiave di sola decifratura identificata dalla versione
| Header | Valore |
|---|---|
| `Content-Security-Policy` | `default-src 'self'`; script solo `'self'` + **nonce** per gli script di Blazor; `connect-src 'self'` (WebSocket del circuito sullo stesso host); `frame-ancestors 'none'`; `object-src 'none'`; `base-uri 'self'` (dettaglio proposto) |
| `Content-Security-Policy` | `default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self'; object-src 'none'` |
| `X-Frame-Options` | `DENY` |
| `Referrer-Policy` | proposta: `strict-origin-when-cross-origin` (o `no-referrer`) |
| `X-Content-Type-Options` | proposta: `nosniff` |
| `Referrer-Policy` | `same-origin` |
| `X-Content-Type-Options` | `nosniff` |
| `Permissions-Policy` | `camera=(), microphone=(), geolocation=(), payment=()` |
| `Cross-Origin-Opener-Policy` | `same-origin` |
| `Strict-Transport-Security` | impostato dal **reverse proxy**, che termina TLS |
- Nessuna risorsa da CDN, nessun font scaricato, nessuno script di terze parti (SPEC §1.2): la CSP può restare
rigorosa. JavaScript solo in `wwwroot/js`, senza `eval` né gestori inline.
rigorosa. In M2 non serve nemmeno il nonce: nessuna pagina ha script inline (la `<ImportMap />` di Blazor, che
ne scriverebbe uno, non è usata). `style-src 'unsafe-inline'` resta perché Blazor applica stili agli elementi
durante la riconnessione. JavaScript solo in `wwwroot/js`, senza `eval` né gestori inline.
- L'impostazione *CSP rigorosa (nonce)* (mockup 086) esiste per la diagnosi; disattivarla è un evento di audit.
- Blazor esegue l'escaping dell'output: vietato `MarkupString` su contenuti provenienti da utenti o da file
(eccezione: l'anteprima XML formattata, che va resa come testo).
+72 -13
View File
@@ -2,16 +2,24 @@
> Punto di ripresa per ogni sessione. Aggiornare a fine sessione.
**Ultimo aggiornamento:** 2026-11-11
**Milestone corrente:** M1 — Strato dati (in chiusura sul ramo `feat/7-strato-dati`)
**Prossimo passo:** chiudere M1 (PR verso `main`, CI verde compreso il job `postgres` avviato a mano sul ramo, tag
`v0.1.0`, immagine e release; misure PostgreSQL in `docs/DATA-MODEL.md` §6.1), poi M2 — Sistema e sicurezza,
partendo dall'issue #15.
**Ultimo aggiornamento:** 2026-11-13
**Milestone corrente:** M8 — Scadenzario e tesoreria (issue #69-#73), da iniziare. M7 chiusa: PR in `main`, tag
`v0.7.0`, immagine e release.
**Prossimo passo:** M8 dall'issue #69. #35 (PNG ad alta risoluzione) resta aperta e non blocca; #45 resta aperta solo
per le banche ABI/CAB (manca una fonte con licenza compatibile).
Da recuperare: misure di riferimento su PostgreSQL in `docs/DATA-MODEL.md` §6.1; indicatore di robustezza della
password (mockup 003); schede *Layout salvati* e *Notifiche* del profilo; rinomina e filtro predefinito nei radar;
logo PNG nel PDF (oggi solo JPEG, ADR 0034); coda della posta persistente e modelli e-mail per azienda (M12).
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`; scritture delle rimanenze e libro inventari (M10); chiusura delle partite con
incassi e pagamenti e IVA per cassa (M8).
## Fatto
- Specifica normativa in `docs/SPEC.md`; `CLAUDE.md` con emendamenti E1-E6.
- ADR 0001-0018.
- Specifica normativa in `docs/SPEC.md`; `CLAUDE.md` con emendamenti E1-E7.
- ADR 0001-0037.
- Mockup in `docs/mockups/` (22 in alta risoluzione + galleria, 88 miniature, `mockup.css`, indice).
- Icone in `assets/`; deploy in `deploy/` (compose Unraid, `.env.example`, template Unraid).
- Documentazione tecnica: `ARCHITECTURE.md`, `DATA-MODEL.md` (provvisorio, sarà generato), `MODULES.md`, `API.md`,
@@ -23,12 +31,63 @@ partendo dall'issue #15.
`/health/live`, `/health/ready`, `/health` (ADR 0012); `docker/Dockerfile`, `entrypoint.sh` con `PUID`/`PGID`
(ADR 0013), `postgres/init.sql`; `deploy/docker-compose.yml` e `docker-compose.sqlite.yml`; Gitea Actions `ci.yml`,
`release.yml`, `wiki.yml` con controllo YAML; script di build, test, avvio, pubblicazione e stub; ADR 0012-0017.
- **M1 (in chiusura, `v0.1.0`):** micro-ORM in `Khaemhat.Data` (mappe, query tipizzate, `SqlFragment`, unit of work,
- **M1 (chiusa, `v0.1.0`, PR #116):** micro-ORM in `Khaemhat.Data` (mappe, query tipizzate, `SqlFragment`, unit of work,
repository con audit e `row_version`), provider SQLite e PostgreSQL, `DatabaseUrl`, migrazioni con
`schema_version`, tabelle `sys_companies` e `sys_settings`, `CompanyRegistry` con URL cifrato, `SecretProtector`
(AES-256-GCM, formato `khs1`), `tools/Khaemhat.DataModelTool` e gli script `new-migration.sh` e
`gen-datamodel.sh`; ADR 0018. Test: 85 su SQLite verdi in locale, 21 su PostgreSQL eseguiti solo in CI (in locale
Docker non è disponibile).
`gen-datamodel.sh`; ADR 0018. Test: 106 test dello strato dati verdi su SQLite in locale e su PostgreSQL 16 e 17 in CI
(in locale Docker non è disponibile).
- **M2 (chiusa, `v0.2.0`, PR #118):** avvio da variabili con elenco degli errori, migrazioni all'avvio, super utente e
prima azienda; account di istanza e aziendali, password con storico e blocco, sessioni nel database, TOTP con codici
di recupero, pagine di accesso (mockup 001-003); ruoli, permessi e attributi di autorizzazione; licenze firmate,
codici di attivazione, modalità test, `tools/Khaemhat.LicenseTool`; DataProtection nel database cifrata; cache
memoria/Redis (client RESP in casa); log su database per sezioni con traccia; attività programmate con cron, lock e
job di sistema; storico dei record; aziende con stati e contesto (`X-Company`); header di sicurezza; ADR 0019.
Test: 180 verdi in locale, più 21 di PostgreSQL saltati senza Docker (girano in CI). La chiave privata delle licenze è fuori dal
repository (`Khaemhat-private/khaemhat-license.khkey`) e va conservata dal titolare.
- **M3 (chiusa, `v0.3.0`, PR #119):** shell con barra superiore, menu comprimibile con sottomenu a comparsa,
schede tenute in vita, barra di stato, scorciatoie con varianti `Alt`; testi in `Resources/it-IT/*.json` con test
anti-testo-letterale; preferenze utente e *Il mio profilo* (aspetto, pagina iniziale, dati personali, password e
2FA, sessioni, scorciatoie); libreria `Kh*` con campi all'italiana, toolbar a icone, intestazione documento e basi
`RecordPage`/`DocumentPage`/`MasterDataPage`; liste con `ListQuery`/`ListFields`, `KhGrid` virtualizzata, `KhRadar`
e `KhLinesGrid`; dashboard a widget con layout per utente e per ruolo e `company_settings`; ricerca globale a
fornitori, aiuto in app dalla copia della wiki, pannello notifiche; allegati con anteprime, *Genera file*, ZIP,
cestino e storico; anteprima di stampa A4; catalogo dei componenti e documento di prova per gli sviluppatori;
primi screenshot reali in `docs/wiki/img/`; ADR 0020-0024. Test: 368 verdi in locale, 21 di PostgreSQL saltati;
immagine costruita in locale e avviata da zero con SQLite.
- **M4 (chiusa, `v0.4.0`, PR #121):** pacchetto fiscale `IT 2026.3` (codici IVA, nature, code list FatturaPA, motore IVA,
calendario, ritenute, F24; ADR 0025); validatori e `ViesClient`; 26 tabelle azienda con un'unica maschera, profilo
azienda, esercizi e cambi BCE (ADR 0026); dati di base con province e comuni ISTAT e CAP GeoNames (ADR 0028) e
`scripts/seed.sh --base|--demo`; codici automatici e compilazione automatica (ADR 0027); clienti, fornitori e
contatti con radar, scheda, controlli e VIES (ADR 0029); articoli e listini con prezzi a validità, listini derivati e
aggiornamento massivo (ADR 0030); import/export guidato CSV/XLSX/JSON con tracciato del piano dei conti (ADR 0031);
21 anagrafiche e 120 articoli di esempio; screenshot reali nella wiki. Test: 631 verdi in locale, 21 di PostgreSQL
saltati; immagine costruita in locale e avviata da zero con SQLite e dati di esempio.
- **M5 (chiusa, `v0.5.0`, PR #124):** motore documenti (#47, ADR 0032): generi e definizioni dei tipi documento, sei famiglie
di tabelle con le righe e `document_links`, stati con azioni ammesse, numerazione atomica alla conferma (provata in
concorrenza su SQLite e su PostgreSQL 18 in locale), copia e trasformazione con evasione riga per riga; totali,
castelletto IVA, bollo, ritenute, cassa e scadenze (#48, ADR 0033); radar e maschera dei documenti di vendita con
*Crea …* (#49, #50); fatturazione differita guidata (#51); anteprima di stampa e PDF dallo stesso modello, invio per
e-mail con SMTP e coda scritti in casa (#52, ADR 0034); log *Documenti*; profilo e un anno di vendite di esempio;
wiki con la *Guida all'uso* e le schermate reali, README come guida per sviluppatori (#53). Test: 660 verdi in
locale, 23 di PostgreSQL saltati (girano in CI).
- **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).
- 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,
@@ -75,12 +134,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.
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.
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).
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.
+54
View File
@@ -0,0 +1,54 @@
# ADR 0019 - Sistema e sicurezza: scelte di M2
- **Stato:** accettata
- **Data:** 2026-11-11
- **Modifica:** SPEC §5.4, §6, §7, §8, §9.3, §9.5, §9.6; milestone M2, issue #15-#24
## Contesto
M2 costruisce avvio, account, accesso, licenze, cache, log, attività programmate e contesto azienda. La specifica
indica il risultato ma lascia aperti alcuni dettagli, o li descrive con componenti che non si possono usare senza
librerie esterne (SPEC §1.2). Questo ADR fissa le scelte fatte.
## Decisione
1. **Autenticazione con uno schema proprio.** Lo schema `KhaemhatSession` (`SessionAuthenticationHandler`) legge il
cookie `khaemhat_session` = `<database>.<token>`: `_` per gli account di istanza (`sys_sessions`), il codice
azienda per gli utenti aziendali (`user_sessions`). Nel database c'è solo l'hash SHA-256 del token. Non si usa il
cookie di autenticazione di ASP.NET Core: la sessione deve essere revocabile e contata per la licenza, e il suo
stato vive nel database, non nel cookie.
2. **Accesso in passi.** Una sessione nasce in uno stato (`PendingPasswordChange`, `PendingTotpSetup`,
`PendingTotp`, `Active`) e solo `Active` autentica le pagine. Ogni passaggio di stato rigenera il token. Le pagine
di accesso sono SSR statiche con `EditForm` (antiforgery incluso), escluse dal routing interattivo.
3. **Attivazione TOTP senza QR.** La pagina mostra la chiave in base32 a gruppi di quattro e il collegamento
`otpauth://`; un codice QR richiederebbe una libreria o un generatore scritto in casa che non vale il costo. Dopo
la conferma si mostrano 10 codici di recupero monouso (salvati come hash).
4. **Avvio in due tempi.** `BootstrapService.StartAsync` migra il database di sistema **prima** che parta il server
(DataProtection legge le chiavi da lì); il resto (licenza, super utente, prima azienda, migrazioni delle aziende)
gira in background mentre `/health/ready` risponde 503 e le pagine mostrano "Avvio in corso". Un errore di
configurazione ferma il processo con codice 2 ed elenca tutte le variabili sbagliate; un errore di avvio con
codice 1. Un'azienda che non si migra va in manutenzione senza fermare le altre.
5. **Chiavi DataProtection** in `sys_data_protection_keys`, cifrate con `SecretProtector`.
6. **Log su database** con un `ILoggerProvider` scritto in casa: coda limitata (20 000 eventi, si scartano i più
vecchi), scrittura a blocchi di 200 ogni secondo, sezione ricavata dalla categoria o dallo scope `Section`,
`TraceId`, utente e azienda dallo scope della richiesta. Gli eventi di `Microsoft.*` e `System.*` sotto
`Warning` non vanno nel database. Retention per livello con un job notturno.
7. **Redis** con un client RESP2 scritto in casa (una connessione, un comando alla volta, `AUTH`, `SELECT`, TLS
con `rediss://`). Se Redis non risponde la cache passa alla memoria e lo scrive nel log una volta al minuto:
la cache non fa mai fallire una richiesta.
8. **Attività programmate**: cron a 5 campi con fuso orario (le ore che non esistono al cambio dell'ora legale si
saltano), lock per attività in `sys_job_locks` con scadenza pari al timeout (un lock scaduto si riprende), una
riga di `sys_job_runs` per tentativo, notifica agli account di istanza quando l'ultimo tentativo fallisce.
9. **Contesto azienda**: gli utenti aziendali lavorano solo nella propria azienda; gli account di istanza la
scelgono (sessione, o header `X-Company` per le API). Un'azienda in manutenzione è chiusa agli utenti aziendali,
una disattivata a tutti: pagine con avviso 503, API con 503 e `Retry-After`; un `X-Company` di un'altra azienda
dà 403.
10. **Database SQLite in memoria** (test e demo): il provider tiene aperta una connessione per ogni database in
memoria creato con `EnsureDatabaseExistsAsync`, che altrimenti sparirebbe con l'ultima connessione.
## Conseguenze
- Nessuna dipendenza nuova; tutto è coperto da test (vettori RFC 6238, RESP, cron con ora legale, flusso di accesso
sull'host reale, isolamento di due aziende).
- Le schermate di amministrazione (utenti, ruoli, licenze, log, attività) arrivano in M12 sopra questi servizi.
- La pagina di cambio password è più semplice del mockup 003 (niente indicatore di robustezza) fino a M3.
+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,53 @@
# ADR 0026 - Tabelle azienda generiche e dati di base solo in aggiunta
- **Stato:** accettata
- **Data:** 2026-11-11
- **Modifica:** SPEC §4 (`scripts/seed.sh`), §11.1, §14; ADR 0025; milestone M4, issue #38, #39 e #45
## Contesto
SPEC §11.1 elenca una ventina di tabelle azienda (codici IVA, pagamenti, depositi, vettori, numeratori, categorie…),
ognuna con elenco, dettaglio, import ed export CSV. SPEC §14 chiede che le tabelle di base si carichino alla creazione
dell'azienda e si aggiornino a ogni versione "senza toccare le righe modificate dall'azienda", ma non dice come
riconoscere una riga modificata. Province, comuni con CAP e la tabella ABI/CAB delle banche sono elenchi pubblici
grandi (8.000 comuni, decine di migliaia di sportelli) che non sono nel repository e hanno licenze da verificare.
## Decisione
1. **Un servizio per tutte le tabelle codificate.** Ogni tabella è un'entità `CodedEntity` (codice, descrizione,
disattivata) descritta in `TableCatalog`: le regole comuni (codice unico, una sola riga predefinita, eliminazione
rifiutata se la riga è usata e proposta di disattivarla, storico, cache invalidata fra istanze, CSV tutto o niente)
stanno in `TableService`. Le regole proprie di una tabella sono funzioni del catalogo; quelle italiane (natura
IVA, codici SDI) arrivano dal pacchetto fiscale (ADR 0025).
2. **Una maschera generica.** L'interfaccia descrive ogni tabella in `TableScreens` (campi, tipo, lookup, code list
del pacchetto) e la mostra con un unico editor `KhTableEditor<T>` all'indirizzo `/tabelle/<slug>`. Profilo
azienda, esercizi e cambi hanno pagine proprie perché non sono elenchi di codici.
3. **Dati di base solo in aggiunta.** Il caricamento inserisce **solo i codici che mancano** e non modifica né
cancella righe esistenti, anche se identiche al pacchetto: una riga presente è dell'azienda. Non serve quindi
distinguere righe "modificate" da righe "originali". La versione caricata è salvata nelle impostazioni
dell'azienda (`seed.base.version`, ad esempio `IT 2026.2`). Correggere una riga di base già presente è un'azione
esplicita dell'utente, non dell'aggiornamento.
4. **Origine delle righe.** Righe fiscali (codici IVA, modalità e condizioni di pagamento, tipi documento) dal
pacchetto del paese tramite `IBaseTablesTemplate`; paesi ISO da un CSV incorporato; valute BCE, unità di misura,
trasporti, causali, deposito principale, listino base, numeratori ed esercizio corrente dal seeder di base.
5. **Comuni.** Il **codice** di un comune è il suo codice catastale (4 caratteri, quello del codice fiscale): non
serve una colonna in più.
6. **Elenchi pubblici caricati a parte.** Province, comuni con CAP e banche ABI/CAB non sono nel seed di 0.4.0:
arriveranno come file di dati con origine e licenza indicate (ISTAT, CC BY 4.0, per province e comuni) dopo il
via dell'utente al download. Fino ad allora le tabelle si riempiono a mano o con l'import CSV.
*Aggiornato dall'ADR 0028:* province e comuni ISTAT, con i CAP di GeoNames, sono nei dati di base dalla
versione `IT 2026.3`; le banche restano fuori.
7. **Riga di comando.** `scripts/seed.sh --base [--company CODICE]` esegue la sequenza di avvio senza servire pagine
(migrazioni, prima azienda) e aggiunge i dati di base a un'azienda o a tutte quelle attive. Nel container lo
script è in `/app/scripts/` e passa da `entrypoint.sh` con il verbo `seed`; in sviluppo usa `dotnet run`.
`--demo` e `--scale` arrivano con anagrafiche e articoli.
## Conseguenze
- Un aggiornamento delle tabelle di base non può mai rovinare una configurazione aziendale; il rovescio è che una
correzione a un codice già presente (ad esempio un riferimento normativo cambiato) va comunicata nel `CHANGELOG`
e fatta dall'utente, o con una migrazione mirata quando è obbligatoria.
- Aggiungere una tabella costa un'entità, una mappa, una voce in `TableCatalog` e una in `TableScreens`, più i testi:
i test controllano che ogni schermata abbia le chiavi di testo e ogni codice di errore la sua traduzione.
- Il pulsante *Aggiorna da tabelle base* delle maschere e la pagina di amministrazione (mockup 089) usano lo
stesso `SeedRunner`.
@@ -0,0 +1,49 @@
# ADR 0027 - Codici automatici con sequenze per chiave e compilazione a opzioni
- **Stato:** accettata
- **Data:** 2026-11-11
- **Modifica:** SPEC §11.12 (codici automatici, compilazione automatica); ADR 0025, 0026; milestone M4, issue #43
## Contesto
SPEC §11.12 chiede maschere di codice per archivio (`C{seq:000000}`, `{categoria}-{seq:0000}`, `L{anno}-{seq:0000}`…),
progressivo globale o per categoria/anno, codice manuale ammesso o no, anteprima del prossimo codice e sequenze in
`code_sequences` con assegnazione atomica. Non dice dove stanno le regole, come si chiamano le sequenze, cosa succede
se il codice successivo è già stato scritto a mano o se la maschera cambia. Per la compilazione automatica elenca le
opzioni senza dire chi le applica, e la banca dall'IBAN dipende da un elenco ABI che non è ancora nel repository
(ADR 0026).
## Decisione
1. **Regole nelle impostazioni dell'azienda.** La maschera e il codice manuale di ogni archivio stanno in
`company_settings` (`codes.<archivio>.mask`, `codes.<archivio>.manual`, `codes.items.unique-barcode`); un archivio
senza impostazioni usa la maschera di SPEC. Gli archivi sono un elenco fisso in `CodeRuleService.Definitions`, con
il modulo di licenza e la lunghezza massima del codice.
2. **Una sequenza per chiave.** `code_sequences` ha una riga per chiave: il nome dell'archivio, più l'anno se la
maschera contiene `{anno}`, più la categoria se contiene `{categoria}` (`customers`, `leads:2026`, `items:VALV`).
La maschera non fa parte della chiave: **cambiare maschera continua lo stesso progressivo** e non riscrive i codici
già assegnati.
3. **Assegnazione nella transazione del salvataggio.** `CodeRuleService.AssignAsync` prende un lock applicativo sulla
chiave (`AcquireLockAsync`, vuoto su SQLite dove le scritture sono già in fila), incrementa la sequenza e la scrive
nella stessa unità di lavoro del record: se il salvataggio fallisce il numero torna libero, e due salvataggi
contemporanei non ottengono mai lo stesso codice. Un codice già presente nella tabella (scritto a mano) viene
saltato; dopo 1.000 salti il salvataggio è rifiutato.
4. **Maschere controllate.** Letterali `A-Z 0-9 - _ / .` in maiuscolo, esattamente un `{seq}`, segnaposto
`{anno}`/`{year}` e `{categoria}`/`{category}`, lunghezza minima entro quella della tabella. Gli errori sono codici
(`codes.mask.*`) tradotti dall'interfaccia.
5. **Compilazione a opzioni.** `AutoFillService` raccoglie le funzioni (comune da CAP e viceversa, codice fiscale dal
pacchetto fiscale, VIES, banca da IBAN, data di consegna sul calendario del pacchetto) e le opzioni accese o spente
(`autofill.<opzione>`); le maschere chiedono `IsOnAsync` prima di compilare. Il job dei cambi BCE salta le aziende
che hanno spento l'opzione. Le opzioni sulle righe dei documenti e sui conti si applicano con i documenti (M5).
6. **Banca da IBAN senza elenco ABI.** `IBankDirectory.ReadIban` restituisce sempre ABI e CAB di un IBAN italiano;
nome e BIC arrivano dall'elenco quando c'è, altrimenti da un conto dell'azienda presso la stessa banca.
7. **Modulo.** SPEC mette codici automatici e preferenze nel modulo AUTO, ma servono a ogni azienda (mockup 074, M4):
stanno nel modulo CORE come le tabelle; le maschere degli archivi di CRM, Servizi e Cespiti si preparano anche
senza il modulo.
## Conseguenze
- Le anagrafiche (#41) e gli articoli (#42) chiamano `AssignAsync` quando il codice è vuoto e `CheckManual` quando è
scritto; gli import li trattano allo stesso modo.
- Una sequenza per categoria nasce al primo articolo della categoria; rinominare il codice di una categoria fa
ripartire il suo progressivo, ma i codici già assegnati restano e quelli ripetuti vengono saltati.
@@ -0,0 +1,53 @@
# ADR 0028 - Province e comuni dall'elenco ISTAT e CAP da GeoNames nel pacchetto fiscale
- **Stato:** accettata
- **Data:** 2026-11-12
- **Modifica:** ADR 0026 punto 6; SPEC §11.1, §11.12, §14; milestone M4, issue #45
## Contesto
L'ADR 0026 rimandava province, comuni con CAP e banche ABI/CAB a file di dati con origine e licenza verificate,
caricati dopo il via dell'utente. Il via è arrivato il 2026-11-12 per due fonti:
- l'**elenco dei codici dei comuni dell'ISTAT** (*Codici statistici delle unità amministrative territoriali*),
pubblicato con licenza **CC BY 4.0** (note legali ISTAT). Il file CSV allo stesso indirizzo è fermo al gennaio 2024
e ha ancora le 107 province precedenti al riordino della Sardegna; il file xlsx è aggiornato al **26/02/2026** e ha
le **110 province** e i **7.894 comuni** in vigore;
- il repository **comuni-json** per i CAP. La sua licenza non è MIT come si era ipotizzato: i comuni vengono
dall'ISTAT (CC BY), ma per i CAP l'autore dichiara che le fonti non indicano una licenza e che al repository
**non si applica nessuna licenza**. I dati sono fermi al 01/01/2020, prima delle fusioni di comuni successive.
## Decisione
1. **Province e comuni nel pacchetto fiscale.** Sono dati italiani, quindi stanno in `Khaemhat.Fiscal.Italy`
(`Data/province.csv`, `Data/comuni.csv`, risorse incorporate) dietro una nuova funzione facoltativa del pacchetto,
`IPlaceDirectory` (province, comuni, origine). `BaseTablesSeeder` li aggiunge come il resto dei dati di base: solo
i codici mancanti, mai modificando una riga già presente.
2. **Formato ridotto.** Dal foglio ISTAT si tengono, per le province, sigla, denominazione e regione; per i comuni,
codice catastale (il **codice** del comune, ADR 0026), denominazione in italiano, sigla della provincia, regione e
codice ISTAT a 6 cifre. I file si rigenerano dal foglio ISTAT con lo stesso schema; ogni aggiornamento porta una
nuova versione dei dati del pacchetto (da `IT 2026.2` a `IT 2026.3`).
3. **Attribuzione.** L'origine (ISTAT, data dell'elenco, CC BY 4.0; GeoNames per i CAP) è scritta in
`ItalianPlaces.ListSource`, nella wiki *Dati di base e di esempio* e in questo ADR.
4. **Niente CAP da comuni-json.** Un file senza licenza non entra in un repository pubblico né nell'immagine
distribuita, e i CAP del 2020 sarebbero comunque incompleti.
5. **CAP da GeoNames.** Con un secondo via dell'utente (2026-11-12) i CAP vengono dall'elenco dei codici postali
italiani di **GeoNames** (`IT.zip`, CC BY 4.0, attribuzione a www.geonames.org). GeoNames elenca località, non
comuni: una riga si assegna a un comune quando nome (senza accenti, apostrofi e trattini, parte italiana dei nomi
bilingui) e sigla della provincia coincidono con un solo comune; in Sardegna, dove le sigle sono cambiate, basta
il nome entro la regione. Le frazioni con nome proprio restano fuori. Risultato: **7.750 comuni su 7.894** hanno i
CAP (un CAP, una lista o intervalli come `10121-10156`); i 144 senza sono in gran parte comuni rinominati o nati da
fusioni (ad esempio Sanremo, che GeoNames chiama *San Remo*) e si completano a mano o con l'**Importa CSV**.
6. **Strumento di rigenerazione.** `tools/Khaemhat.PlacesTool` (non distribuito, solo framework) legge il foglio ISTAT
e `IT.zip` e riscrive `Data/province.csv` e `Data/comuni.csv`; i file scaricati restano fuori dal repository.
7. **Banche ABI/CAB** restano fuori finché non c'è una fonte aperta con licenza chiara (ADR 0026, ADR 0027 punto 6).
## Conseguenze
- Un'azienda nuova ha subito province, comuni e CAP: il calcolo del codice fiscale, la scelta del comune e la
compilazione dal CAP funzionano senza caricare nulla. Le aziende esistenti li ricevono al primo avvio con la
versione `IT 2026.3`, o con *Aggiorna tabelle di base*.
- Il caricamento di base aggiunge circa 8.000 righe alla creazione dell'azienda: su SQLite resta sotto i due secondi;
su PostgreSQL va misurato insieme alle altre misure di riferimento (`docs/DATA-MODEL.md` §6.1).
- Un comune soppresso per fusione resta nella tabella di chi lo aveva già: va disattivato a mano. Le variazioni
vanno annotate nel `CHANGELOG` quando si aggiorna l'elenco.
+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).
+122 -121
View File
@@ -1,178 +1,179 @@
# 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)). Arrivano più avanti: i **pagamenti** e lo scadenzario (M8), 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.
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
arrivano con la [Fatturazione elettronica](Fatturazione-elettronica) (M9); 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
+105 -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,68 @@ 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 le vendite (M5) e lo scadenzario (M9).
- Ricerca libera su codice, nome, partita IVA, codice fiscale e città.
- Filtri rapidi: **Tipo** (solo contatti), **Soggetto**, **Agente**, **Stato**; all'apertura sono mostrate solo le
anagrafiche attive.
- Tasti: `F9` radar, `Invio` o doppio clic apre la scheda, `Spazio` seleziona. Con più righe selezionate si usano
**Disattiva** e **Riattiva**; l'esportazione CSV/XLSX è quella di tutti i radar.
## La scheda anagrafica
![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 +109,8 @@ comune, provincia e regione; il **codice fiscale** di una persona fisica può es
| Gruppo | Campi |
|---|---|
| **Fatturazione elettronica** | **Codice destinatario** *, PEC destinatario, tipo destinatario, formato (FPR12 privati / FPA12 PA), riferimento amministrazione, *Allega PDF di cortesia*, *Invia copia via e-mail all'emissione* |
| **Regime IVA e ritenute** | *Split payment* (art. 17-ter), *Reverse charge* predefinito, codice IVA predefinito, esigibilità, *Soggetto a ritenuta*, cassa previdenza, bollo (a carico del cliente o dell'azienda), regime |
| **Regime IVA** | *Scissione dei pagamenti* (art. 17-ter), *Inversione contabile*, codice IVA abituale, esigibilità (I, D, S), bollo a carico del cliente |
| **Ritenute e casse** | *Ritenuta d'acconto* con aliquota e causale, cassa previdenziale con aliquota, *ENASARCO* |
| **Dichiarazione d'intento** (esportatore abituale) | Attiva, Numero, Data, Protocollo AdE, Codice IVA (non imponibile art. 8 c.1 lett. c, natura N3.5), **Plafond**, **Utilizzato**, **Residuo**, Validità |
| **Identificativi** | GLN, EORI, nostro codice presso il cliente |
@@ -101,21 +118,22 @@ comune, provincia e regione; il **codice fiscale** di una persona fisica può es
| Controparte | Valore |
|---|---|
| Azienda italiana (B2B) | 7 caratteri, comunicati dal cliente (in alternativa la PEC) |
| Azienda italiana (B2B) | 7 caratteri, comunicati dal cliente; con la sola PEC si usa `0000000` (proposto) |
| Pubblica amministrazione | **codice IPA** dell'ufficio, 6 caratteri |
| Estero (UE ed extra-UE) | `XXXXXXX` |
| Privato | `0000000` |
| Estero (UE ed extra-UE) | `XXXXXXX` (proposto se vuoto) |
| Privato | `0000000` (proposto se vuoto) |
**Dichiarazione d'intento**: quando il cliente è esportatore abituale, le fatture usano il codice IVA non
imponibile collegato e riportano numero e protocollo della dichiarazione; l'utilizzato si aggiorna con le fatture e
il residuo avvisa quando il plafond sta per esaurirsi (il mockup mostra un avviso all'80% e un blocco al 100%; le
soglie definitive saranno fissate in sviluppo). Il registro completo delle dichiarazioni ricevute ed emesse è nel
soglie si fissano con la fatturazione, M5). Una dichiarazione attiva richiede numero e plafond. Il registro completo delle dichiarazioni ricevute ed emesse è nel
modulo Fatturazione elettronica (vedi [Fatturazione elettronica](Fatturazione-elettronica)).
### Condizioni di vendita (clienti)
Listino, sconti, pagamento, banca d'appoggio per le RiBa, agente, vettore, porto, deposito, **fido** e **blocco**,
raggruppamento dei DDT in fattura differita, giorno di fatturazione, invio dei documenti per e-mail o PEC. Queste
Listino, due sconti, pagamento, nostra banca d'appoggio per le RiBa, vettore, porto, deposito, **fido** e **ordini
bloccati**, raggruppamento dei DDT in fattura differita, giorno di fatturazione, invio dei documenti per e-mail o PEC
con l'indirizzo dedicato. Queste
condizioni vengono proposte automaticamente nei documenti del cliente (vedi [Vendite](Vendite)).
Il **fido** è l'esposizione massima ammessa: quando viene superato, o se il cliente ha scaduto, gli ordini
@@ -128,13 +146,12 @@ segnalano il blocco, superabile solo da chi ha il permesso di forzarlo.
| Gruppo | Campi |
|---|---|
| **Condizioni di acquisto** | Pagamento, Valuta, **Lead time** (giorni), **Minimo d'ordine**, Sconto %, Porto, Registro IVA acquisti, Conto di costo predefinito |
| **Ritenute e contributi** | *Professionista (ritenuta d'acconto)*, aliquota ritenuta, causale, cassa previdenza, *Agente ENASARCO*, *Regime forfettario* (niente IVA, bollo), *Reverse charge* (es. subappalto edile) |
| **Banca e contatti** | IBAN, BIC, referente, e-mail per gli ordini |
| **Condizioni di acquisto** | Pagamento, **Tempo di consegna** (giorni), **Ordine minimo**, Sconto %, Porto, Registro IVA, Conto di costo, E-mail per gli ordini |
| **Ritenute e casse** (scheda *Fiscale e SDI*) | *Ritenuta d'acconto* con aliquota e causale, cassa previdenziale, *ENASARCO*; il tipo soggetto *Forfettario* per chi non applica l'IVA |
| **Banche** e **Contatti** | IBAN, BIC, banca, ABI e CAB; referenti |
L'intestazione del fornitore mostra il totale **acquisti** dell'anno, l'aperto, lo scaduto e gli ordini aperti; tra
le schede *Articoli forniti* elenca gli articoli che il fornitore ti vende. Il lead time viene usato per calcolare
le date di consegna previste negli ordini fornitore.
Il tempo di consegna servirà a calcolare le date previste negli ordini fornitore. Il totale **acquisti**, l'aperto,
lo scaduto e gli *Articoli forniti* del mockup arrivano con acquisti e articoli.
## Come si usa
@@ -142,41 +159,54 @@ le date di consegna previste negli ordini fornitore.
1. **Anagrafiche → Clienti**, premi **Nuovo cliente** (o `Ctrl+N`).
2. Scegli il **tipo soggetto**. Il codice viene assegnato automaticamente al salvataggio (vedi più sotto).
3. Inserisci ragione sociale e partita IVA: al salvataggio Khaemhat controlla la partita IVA e, se è comunitaria,
3. Inserisci ragione sociale e partita IVA: al salvataggio Khaemhat controlla la partita IVA e, per un'impresa UE,
la verifica sul servizio **VIES** (l'esito resta salvato con la data).
4. Compila la sede legale partendo dal CAP.
5. In **Fiscale e SDI** inserisci il codice destinatario o la PEC.
6. In **Condizioni commerciali** imposta pagamento, listino, agente e fido.
7. **Salva** (`Ctrl+S`).
6. In **Condizioni** imposta pagamento, listino e fido; l'agente è nei dati principali.
7. **Salva** (`Ctrl+S`). Gli errori portano alla scheda del primo campo da correggere; gli **avvisi** (ad esempio
una partita IVA già usata da un'altra anagrafica, che va bene per filiali e sedi distinte) non bloccano e compaiono
in un messaggio dopo il salvataggio.
Un lead si crea da **Contatti → Nuovo lead**, un prospect da **Contatti → Nuovo prospect**.
### Convertire un lead o un prospect in cliente
Dalla scheda del lead o del prospect usa l'azione di conversione: il soggetto diventa **cliente**, riceve il codice
cliente secondo la maschera automatica e mantiene la propria storia (attività, opportunità). Con il modulo CRM la
conversione si avvia anche dalla maschera dei lead (vedi [CRM](CRM)).
Dalla scheda del lead o del prospect usa **Converti in cliente**: il soggetto diventa **cliente**, riceve il codice
cliente secondo la maschera automatica e conserva il vecchio come **codice precedente** (si trova ancora con la
ricerca), insieme a storico e allegati. Con il modulo CRM la conversione si avvierà anche dalla maschera dei lead
(vedi [CRM](CRM)).
Su un **fornitore** la stessa azione lo rende anche cliente: il codice non cambia e l'anagrafica compare in entrambi
gli elenchi.
### Disabilitare invece di cancellare
Un'anagrafica che compare in almeno un documento **non si cancella**: si **disabilita** (azione **Disabilita** nel
radar o nella scheda). Un'anagrafica disabilitata non viene più proposta nei nuovi documenti né nelle ricerche
predefinite, ma resta consultabile con i suoi documenti. Si può cancellare solo un'anagrafica mai usata.
Un'anagrafica che compare in almeno un documento **non si cancella**: si **disattiva** (azione **Disattiva** nel
radar o nel menu della scheda). Un'anagrafica disattivata non viene più proposta nei nuovi documenti né nelle
ricerche predefinite, ma resta consultabile con i suoi documenti. Se si prova a eliminare un'anagrafica usata,
Khaemhat la disattiva e lo dice. Si cancella davvero solo un'anagrafica mai usata.
## Validazioni
| Dato | Controllo |
|---|---|
| **Partita IVA italiana** | 11 cifre con cifra di controllo |
| **Ragione sociale** | obbligatoria (per i privati cognome e nome) |
| **Partita IVA italiana** | 11 cifre con cifra di controllo; obbligatoria per un'impresa; un doppione è un avviso |
| **Partita IVA UE** | verifica sul servizio VIES della Commissione europea; esito e data salvati |
| **Codice fiscale** | 16 caratteri con carattere di controllo (11 cifre per le società); calcolabile dai dati anagrafici |
| **Codice fiscale** | 16 caratteri con carattere di controllo (11 cifre per le società); per un privato senza codice fiscale un avviso |
| **Pubblica amministrazione** | serve il codice fiscale o la partita IVA |
| **Paese** | nella tabella dei paesi; un'impresa UE ha sede in un altro paese dell'Unione, impresa italiana, privato, PA e forfettario nel paese dell'azienda |
| **IBAN** | struttura e controllo modulo 97 |
| **Codice destinatario** | 7 caratteri; 6 per la PA (codice IPA); `XXXXXXX` estero; `0000000` privato |
| **E-mail / PEC** | formato dell'indirizzo |
| **Codice** | unico fra tutte le anagrafiche |
## Codici automatici
Il codice di clienti, fornitori e lead è assegnato automaticamente secondo le maschere impostate in
Il codice di clienti, fornitori, prospect e lead è assegnato automaticamente secondo le maschere impostate in
*Tabelle azienda → Preferenze e codici automatici* (vedi [Tabelle azienda](Tabelle-azienda)): `C{seq:000000}` per i
clienti, `F{seq:000000}` per i fornitori, `L{anno}-{seq:0000}` per i lead. La maschera mostra l'anteprima del
clienti, `F{seq:000000}` per i fornitori, `L{anno}-{seq:0000}` per prospect e lead. La maschera mostra l'anteprima del
prossimo codice; un'impostazione decide se è ammesso scrivere un **codice manuale**. Il progressivo è assegnato in
modo atomico: due utenti che salvano insieme non ottengono mai lo stesso codice.
@@ -184,25 +214,31 @@ modo atomico: due utenti che salvano insieme non ottengono mai lo stesso codice.
| Quando | Khaemhat propone |
|---|---|
| inserisci il CAP | comune, provincia e regione |
| inserisci i dati anagrafici di una persona | il codice fiscale |
| inserisci il CAP | comune e provincia (scelta fra più comuni) |
| inserisci il comune | CAP e provincia |
| premi *Calcola* accanto al codice fiscale di un privato | il codice fiscale |
| salvi una P.IVA UE | la verifica VIES |
| inserisci un IBAN | banca e BIC (tabella ABI) |
| crei un documento per il cliente | destinazione, listino, pagamento, agente |
| inserisci un IBAN | ABI, CAB e banca (dalla tabella delle banche, quando caricata) |
| lasci vuoto il codice destinatario di un privato o di un estero | `0000000` o `XXXXXXX` |
| crei un documento per il cliente | destinazione, listino, pagamento, agente (con le vendite, M5) |
Le singole compilazioni si attivano o disattivano in *Tabelle azienda → Preferenze e codici automatici*.
## Permessi e licenza
Le anagrafiche fanno parte del modulo **CORE**. Il flag utente *vede solo i propri clienti* limita un agente ai
clienti a lui assegnati. Le schede *CRM* e *Scheda 360°* mostrano i dati CRM solo con il modulo **CRM** attivo; il
Le anagrafiche fanno parte del modulo **CORE**: `parties.party.read` per consultare, `parties.party.write` per
inserire, modificare, disattivare e convertire, `parties.party.delete` per eliminare. Il flag utente *vede solo i
propri clienti*, che limiterà un agente ai clienti assegnati, non è ancora attivo. Le schede *CRM* e *Scheda 360°* mostrano i dati CRM solo con il modulo **CRM** attivo; il
registro delle dichiarazioni d'intento richiede **EINV**. Ogni modifica è registrata nello **Storico**.
## Domande frequenti
- **Non riesco a cancellare un cliente.** Ha documenti collegati: disabilitalo.
- **La verifica VIES non risponde.** Il servizio europeo può essere temporaneamente non disponibile: salva
comunque e ripeti la verifica con l'azione **VIES** più tardi.
comunque e ripeti la verifica con l'azione **Verifica VIES** più tardi.
- **Ho convertito un prospect e il vecchio codice è sparito.** È nel campo *Codice precedente* e la ricerca lo trova.
- **Un fornitore compare anche fra i clienti.** È un cliente con *È anche fornitore*: un solo soggetto, un solo
codice.
- **Un cliente privato non ha codice destinatario.** È corretto: si usa `0000000` e la fattura resta disponibile
nell'area riservata del cliente sul sito dell'Agenzia delle Entrate; consegnagli comunque una copia di cortesia.
+9 -2
View File
@@ -1,7 +1,7 @@
# Architettura
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M0-M13)
> **Specifica:** SPEC §1-§5, §9, §13, §21 · ADR 0009-0011
> **Stato:** bozza · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.1.0 (accesso ai dati); il resto arriva con le milestone M2-M13
> **Specifica:** SPEC §1-§5, §9, §13, §21 · ADR 0004, 0009-0018
Come è fatto Khaemhat "dentro", spiegato senza entrare nel codice. Chi sviluppa trova il documento tecnico completo
(regole di dipendenza, contratti, elenco delle classi) in
@@ -63,6 +63,13 @@ I dati di un'azienda non si mescolano mai con quelli di un'altra: stanno fisicam
lavora solo nella sua azienda; gli amministratori scelgono l'azienda dalla barra superiore. Gestione in
[Istanza-e-database](Istanza-e-database).
Il database di sistema tiene l'elenco delle aziende e, per ciascuna, **dove si trova il suo database**: questa
informazione contiene la password del database ed è salvata **cifrata** con la chiave dell'istanza
(`KHAEMHAT_SECRET_KEY`), in modo che non si possa leggere nemmeno copiandola da un'azienda all'altra. Quando il
programma lavora per un'azienda apre il database giusto da solo; la struttura di ogni database viene aggiornata dalle
**migrazioni** ([Modello-dati](Modello-dati)). Tutto il programma funziona allo stesso modo su PostgreSQL (16 o
successivo) e su SQLite: i test girano su entrambi a ogni versione.
![078 · Istanza e database](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/078-admin-istanza-database.png)
*Mockup 078 — elenco dei database dell'istanza (sistema e aziende) con motore, dimensione, stato dello schema, ultimo backup e stato; sotto, le informazioni sul server PostgreSQL (anteprima ridotta).*
+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
+18 -1
View File
@@ -1,8 +1,13 @@
# Attività programmate
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2 e M12)
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2 e M12)
> **Modulo di licenza:** CORE (procedure oltre quelle di sistema: AUTO; report pianificati: REPORT) · **Livello richiesto:** amministratore · **Specifica:** SPEC §9, §11.12, §11.13, §12.5
> **Nella versione 0.2.0** c'è il motore: espressioni cron a 5 campi con fuso orario, lock per attività (una sola
> esecuzione anche con più istanze), timeout, tentativi, storico delle esecuzioni e notifica agli amministratori
> quando un'attività fallisce. Girano i tre job di sistema (pulizia sessioni, controllo licenza, retention del log).
> La schermata e le attività create dagli utenti arrivano in M12.
## A cosa serve
Le **attività programmate** fanno lavorare Khaemhat da solo a orari stabiliti: backup notturni, fatturazione
@@ -132,6 +137,18 @@ il dettaglio dell'ultima. Le esecuzioni sono registrate nel database di sistema.
## Job di sistema
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 |
Oltre alle attività degli amministratori, Khaemhat esegue sempre alcuni **job di sistema**: pulizia (log e sessioni
secondo la retention), controllo della licenza, aggiornamento dei cambi BCE, lettura dell'inbox e dei canali SDI,
coda delle e-mail, verifica delle giacenze, backup. Le attività di sistema predefinite sono create con le tabelle di
+8 -2
View File
@@ -1,6 +1,6 @@
# Changelog
> **Stato:** completa per 0.1.0 · **Ultima revisione:** 2026-11-11
> **Stato:** completa per 0.7.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,18 @@ Le novità di ogni versione sono nel file
| Versione | Data | Contenuto |
|---|---|---|
| 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
+275 -227
View File
@@ -1,272 +1,320 @@
# 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.7 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.7.0 (M7)
> **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.
> Arrivano più avanti: **scadenzario**, incassi e pagamenti bancari e riconciliazione (M8), **chiusura
> dell'esercizio**, ratei e risconti, **bilancio CEE** riclassificato e **cespiti** (M10). Non ci sono ancora
> l'import del piano dei conti da file e l'export per il commercialista.
## 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 237 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: 237 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 sarà chiuso dalla procedura di fine esercizio (M10) |
| **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.
In questa versione le partite nascono dai documenti; gli incassi e i pagamenti che le chiudono, i solleciti e lo
scadenzario arrivano con lo [Scadenzario](Scadenzario) (M8).
## 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 |
Il bilancio CEE (stato patrimoniale e conto economico civilistici), il riclassificato e gli indici arrivano con la
chiusura dell'esercizio (M10).
## 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)
+64 -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,66 @@ 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) |
I moduli delle prossime versioni aggiungono le loro righe (scarti SDI, liquidazioni, incassi, ordini da evadere…).
Se una fonte non risponde, il widget mostra le altre e l'errore finisce nel [log](Log).
I **promemoria** si scrivono nel campo in fondo al widget e si aggiungono con Invio (al massimo 20, di 300 caratteri
ciascuno); la casella li segna come fatti, la **×** li toglie.
## Come si personalizza
1. Premi **Personalizza** in alto a destra. I widget si contornano con un bordo tratteggiato e si apre il pannello
laterale **Personalizza dashboard**.
2. Nel pannello, sezione **Widget (trascina per ordinare)**, attiva o disattiva ciascun widget con l'interruttore e
trascinalo per cambiarne l'ordine.
3. Sulla griglia trascina i widget per spostarli e ridimensionali (3, 4, 6, 8 o 12 colonne).
4. Imposta, se vuoi, il periodo dei KPI.
5. Chiudi il pannello: la disposizione è salvata.
laterale **Personalizza dashboard**; la pagina resta utilizzabile e, sugli schermi larghi almeno 1280 px, si
stringe per lasciare spazio al pannello.
2. Nel pannello, sezione **Widget**, accendi o spegni ciascun widget con l'interruttore; per quelli accesi scegli la
larghezza (*Un quarto*, *Un terzo*, *Metà*, *Due terzi*, *Tutta la riga*) e spostali con le frecce. Un widget
acceso si aggiunge in fondo.
3. Sulla griglia trascina un widget sopra un altro per prenderne il posto. Ogni widget ha anche i pulsanti
**‹ ›** (sposta prima o dopo), **− +** (più stretto o più largo) e **×** (nascondi): tutto si fa anche da tastiera.
4. **Ripristina** cancella la tua disposizione: torna quella predefinita del tuo ruolo o, se non c'è, quella di
Khaemhat. **Fine** (o Esc) chiude il pannello.
Disposizione e scelte sono salvate nelle tue preferenze (sul database dell'azienda): le ritrovi su ogni dispositivo.
Ogni modifica si salva subito nelle tue preferenze: la ritrovi su ogni dispositivo. Il pannello dice da dove viene la
disposizione che stai usando (tua, del ruolo o di Khaemhat).
## Pagina iniziale e dashboard disattivabile
La dashboard si può **spegnere**. Nel pannello *Personalizza* (sezione **Pagina iniziale**) o in
[Il mio profilo → Pagina iniziale](Preferenze-utente) scegli:
- **All'accesso apri**: *Dashboard*, oppure l'*ultima scheda aperta*, un *radar* (ad esempio *Clienti*), la *prima
nota*, l'*agenda CRM*…
- **Pagina da aprire**: *La pagina iniziale* (la dashboard), l'*ultima scheda aperta* o una delle pagine che puoi
aprire (ad esempio *Clienti*).
- **Mostra la dashboard**: se disattivato, la voce *Home* non mostra più i widget e all'accesso si apre la pagina
scelta.
## Layout per ruolo
Gli amministratori possono definire un **layout predefinito per ruolo** (ad esempio un layout per *Vendite*, uno per
*Contabilità*): un nuovo utente parte dal layout del proprio ruolo e può poi modificarlo per sé. La maschera di
gestione dei layout per ruolo sarà definita in sviluppo (vedi [Utenti e permessi](Utenti-e-permessi)).
Chi ha il permesso **Modificare le impostazioni dell'azienda** (`company.settings.write`, ad esempio il ruolo
*Amministrazione*) trova in fondo al pannello la sezione **Predefinito per ruolo**: sceglie un ruolo e preme **Usa
questo layout per il ruolo** per dargli la disposizione che ha sulla pagina in quel momento; **Togli il predefinito**
lo riporta a quello di Khaemhat. I ruoli che hanno un predefinito sono segnati nell'elenco.
Chi non ha mai personalizzato la dashboard parte dal predefinito del suo ruolo (se ha più ruoli, il primo assegnato
che ne ha uno); appena cambia qualcosa la disposizione diventa sua. I predefiniti dei ruoli sono impostazioni
dell'azienda: ogni azienda ha i suoi. La sezione compare solo quando lavori in un'azienda.
## Permessi e licenza
@@ -85,9 +126,10 @@ se l'utente ha i permessi di lettura su quei dati; *Stato sistema* è riservato
- **Un widget non compare nell'elenco.** Il modulo relativo (ad esempio CRM) non è licenziato o non hai il permesso
di vederne i dati.
- **Voglio tornare alla disposizione iniziale.** Un comando per ripristinare il layout del ruolo non è ancora
definito nella specifica; sarà deciso in sviluppo e documentato qui. Nel frattempo riattiva o riordina i widget
da *Personalizza*.
- **Voglio tornare alla disposizione iniziale.** *Personalizza* → **Ripristina**: torna il predefinito del tuo ruolo
o quello di Khaemhat.
- **Ho spento la dashboard e voglio riaccenderla.** La *Home* mostra in alto **Mostra la dashboard**; in alternativa
[Il mio profilo → Pagina iniziale](Preferenze-utente).
- **"Da fare oggi" mostra cose che non riguardano il mio lavoro.** L'elenco segue i tuoi permessi; se vedi voci non
pertinenti, chiedi all'amministratore di verificare il tuo ruolo.
+93 -11
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 M5 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.6.0 (dati di esempio di contabilità con il modulo, completi in M9)
> **Modulo di licenza:** CORE · **Livello richiesto:** amministratore (rimozione dati di esempio: super utente) · **Specifica:** SPEC §6, §12.11, §14
## A cosa serve
@@ -21,26 +21,26 @@ alto a destra, es. *Database: khaemhat_demo*).
*Mockup 089 — riepilogo di tabelle di base, dati di esempio, documenti reali e utenti demo con i pulsanti **Aggiorna
tabelle di base**, **Carica dati di esempio**, **Rimuovi dati di esempio**, **Anteprima differenze**; a destra le
ultime migrazioni; sotto, i **pacchetti di dati di base** della versione `IT 2026.2` con contenuto, righe e stato
ultime migrazioni; sotto, i **pacchetti di dati di base** della versione `IT 2026.3` con contenuto, righe e stato
(anteprima ridotta)*
Il riepilogo mostra:
| Voce | Esempio |
|---|---|
| **Tabelle di base** | versione del pacchetto (`IT 2026.2`), righe, data dell'ultimo aggiornamento |
| **Tabelle di base** | versione del pacchetto (`IT 2026.3`), righe, data dell'ultimo aggiornamento |
| **Dati di esempio** | *presenti* con i conteggi (clienti, fornitori, articoli, documenti, registrazioni, cespiti, lead) oppure *assenti* |
| **Documenti reali** | numero di documenti non dimostrativi (0 in un'azienda demo) |
| **Utenti demo** | utenti dimostrativi e relativa password |
## Le tabelle di base
Sono raccolte in **pacchetti** con una **versione** (oggi `IT 2026.2`, salvata nelle impostazioni dell'azienda).
Sono raccolte in **pacchetti** con una **versione** (oggi `IT 2026.3`, salvata nelle impostazioni dell'azienda).
Il pacchetto italiano fa parte del pacchetto fiscale Italia (vedi [Fiscalità italiana](Fiscalita-italiana)).
| Pacchetto | Contenuto |
|---|---|
| **Paesi e comuni** | paesi ISO, province, comuni con CAP e codice catastale |
| **Paesi e comuni** | paesi ISO, province, comuni con codice catastale, codice ISTAT e CAP |
| **Valute e unità di misura** | valute, unità di misura |
| **Codici IVA e nature** | aliquote 22, 10, 5, 4; esenti (ESE10 N4); non imponibili (NI8 N3.1, NI41 N3.2, NI71 N3.3, NI8C N3.5); fuori campo (FC7 N2.1, altre N2.2); escluse (ESC15 N1); reverse charge (RC17 N6.x); split payment; non soggette; indetraibili 50% e 100%; forfettari |
| **Modalità e condizioni di pagamento** | modalità `MP01`-`MP23`, condizioni di pagamento |
@@ -56,6 +56,32 @@ Il pacchetto italiano fa parte del pacchetto fiscale Italia (vedi [Fiscalità it
| **CRM** | pipeline e fasi, modelli e-mail |
| **Sistema** | ruoli predefiniti, regole di automazione predefinite, attività programmate di sistema |
### Cosa c'è oggi
Dalla versione 0.4.0 il caricamento di base contiene: paesi ISO con appartenenza all'UE, le 30 valute dei cambi BCE,
unità di misura, codici IVA e nature, modalità `MP01`-`MP23` e condizioni di pagamento con le rate, tipi documento
con codice TD, numeratori, causali di magazzino, deposito principale, porti, trasporto a cura, causali di trasporto,
aspetto dei beni, rese, categorie, listino base e l'esercizio dell'anno in corso con i suoi mesi. Le righe fiscali
vengono dal pacchetto del paese dell'azienda.
**Province e comuni** (dalla versione `IT 2026.3`) vengono dall'elenco ISTAT dei codici dei comuni aggiornato al
26/02/2026: 110 province con sigla e regione, 7.894 comuni con codice catastale, provincia, regione e codice ISTAT.
Il **codice** di un comune è il suo codice catastale (es. `H501` per Roma), lo stesso del codice fiscale.
I **CAP** vengono dall'elenco dei codici postali di GeoNames e ci sono per 7.750 comuni: un CAP, una lista o un
intervallo come `10121-10156` per le città con più CAP.
> Fonti: ISTAT, *Codici statistici delle unità amministrative territoriali*, e GeoNames
> ([www.geonames.org](https://www.geonames.org)), entrambi con licenza
> [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/deed.it).
Ai comuni rinominati o nati da fusioni recenti (ad esempio Sanremo) il CAP può mancare: si completa a mano nella
tabella *Comuni* o con l'**Importa CSV** (colonne `Code` e `PostalCodes`, più CAP separati da virgola). La
compilazione dal CAP propone solo i comuni che hanno il CAP scritto. Le **banche ABI/CAB** non sono ancora incluse: banca e BIC dall'IBAN vengono da un conto
dell'azienda presso la stessa banca. Un comune soppresso per fusione resta nella tabella finché non lo disattivi.
Le altre voci dell'elenco (piano dei conti, causali contabili, registri IVA, cespiti, codici tributo, CRM) arrivano con i
moduli che le usano.
### Aggiorna tabelle di base
Ogni nuova versione di Khaemhat può portare un pacchetto aggiornato (nuovi codici IVA, nuovi tipi documento SDI,
@@ -64,8 +90,12 @@ nuovi codici tributo…).
1. Premi **Anteprima differenze** per vedere cosa cambierebbe.
2. Premi **Aggiorna tabelle di base**.
L'aggiornamento è **idempotente** (rieseguirlo non duplica nulla) e **aggiunge solo i codici mancanti senza
toccare le righe che l'azienda ha modificato**.
L'aggiornamento è **idempotente** (rieseguirlo non duplica nulla) e **aggiunge solo i codici mancanti**: una riga
già presente non viene mai modificata né cancellata, anche se l'azienda non l'ha mai toccata. Se una nuova versione
corregge un codice esistente (ad esempio un riferimento normativo), il [CHANGELOG](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/src/branch/main/CHANGELOG.md)
lo segnala e la correzione si fa nella tabella. La versione caricata è salvata nelle impostazioni dell'azienda.
Lo stesso aggiornamento si avvia dal menu `…` di ogni tabella con **Aggiorna da tabelle base**.
Le tabelle di base si caricano anche automaticamente alla creazione di un'azienda, se la variabile
`KHAEMHAT_SEED_BASE` non è `false` (predefinito `true`).
@@ -94,6 +124,43 @@ 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. Il resto della tabella arriva con le milestone dei rispettivi moduli.
I dati sono costruiti con gli stessi motori del programma (documenti, contabilità): ogni quadratura torna, e lo
stesso caricamento è usato come prova automatica di correttezza.
@@ -125,14 +192,29 @@ esempio.
## Da riga di comando
Lo script `scripts/seed.sh` esegue le stesse operazioni fuori dall'interfaccia (utile in sviluppo):
Lo script `scripts/seed.sh` aggiunge le tabelle di base e i dati di esempio fuori dall'interfaccia. Esegue la sequenza di avvio
(migrazioni, prima azienda) senza servire pagine, poi lavora su un'azienda o su tutte quelle attive e stampa le righe
aggiunte per tabella. Usa le stesse variabili `KHAEMHAT_*` del servizio.
Nel container (lo script è in `/app/scripts/`):
```
scripts/seed.sh --base
scripts/seed.sh --demo [--scale N] [--company CODICE]
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --base
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --base --company DEMO
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --demo --company DEMO
docker compose run --rm --entrypoint /app/scripts/seed.sh khaemhat --demo --scale 10 --company PROVA
```
`--scale N` moltiplica i volumi dei dati di esempio (usato per le prove di prestazione).
In sviluppo, dalla cartella del repository: `scripts/seed.sh --base|--demo [--scale N] [--company CODICE]`.
| Opzione | Effetto |
|---|---|
| `--base` | aggiunge i codici di base mancanti |
| `--demo` | prima i dati di base, poi i dati di esempio; ogni gruppo (anagrafiche, articoli) si carica solo nell'azienda che non ne ha ancora |
| `--scale N` | solo con `--demo`: ripete il catalogo articoli N volte (da 1 a 100), per le prove di prestazione |
| `--company CODICE` | lavora solo su quell'azienda invece che su tutte quelle attive |
I dati di esempio si caricano anche al primo avvio con `KHAEMHAT_SEED_DEMO=true`.
## Migrazioni
+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
+175 -53
View File
@@ -1,21 +1,29 @@
# 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.7 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.7.0 (M7)
> **Modulo di licenza:** CORE, ACCT, EINV, INTRA · **Specifica:** SPEC §11.1, §11.3-§11.9, §14, ADR 0036, ADR 0037
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. Le parti su
> notifiche SDI, dichiarazioni d'intento, Intrastat e cespiti descrivono regole che il programma userà con la
> [Fatturazione elettronica](Fatturazione-elettronica) (M9) e con [Cespiti](Cespiti) e [Intrastat](Intrastat) (M10).
> **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 è indicata nel programma ed è verificata a ogni rilascio.
## Dove si trovano questi codici nel programma
@@ -25,10 +33,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 +68,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 +83,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 +92,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).
@@ -155,57 +182,149 @@ fatture passive. Il codice RF03 non esiste più nelle specifiche correnti.
I dettagli operativi sono in [Fatturazione-elettronica](Fatturazione-elettronica).
## Piano dei conti modello
Il pacchetto fiscale porta il piano dei conti **PMI standard**: **237 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 | con i solleciti dello scadenzario (M8) |
## 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) |
| 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) |
| Dichiarazione d'intento | operazioni non imponibili N3.5 con controllo di plafond, utilizzato e residuo (M10) | [Fatturazione-elettronica](Fatturazione-elettronica) |
| 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 (M10) | [Cespiti](Cespiti) |
| Intrastat | elenchi INTRA cessioni e acquisti, periodicità da soglie, nomenclatura NC8 (M10) | [Intrastat](Intrastat) |
| Bilancio | schemi CEE art. 2424 (stato patrimoniale) e 2425 (conto economico): le voci sono già sui conti, gli schemi arrivano con M10 | [Contabilita](Contabilita) |
## Domande frequenti
@@ -215,7 +334,10 @@ SDI: è registrata nel programma e aggiornata con i rilasci.
**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
+195
View File
@@ -0,0 +1,195 @@
# Guida all'uso
> **Stato:** completa per la versione 0.7 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.7.0 (M7)
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.7.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 e scadenzario M8, XML SDI M9 |
| 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 M8, XML delle autofatture M9 |
| Magazzino | giacenze per deposito, impegnato e ordinato, costo medio, movimenti e trasferimenti, inventario fisico, proposta di riordino, valorizzazione con classi ABC, ricostruzione | scritture delle rimanenze e libro inventari con la chiusura dell'esercizio M10 |
| Contabilità | piano dei conti, causali, prima nota, contabilizzazione automatica dei documenti, registrazioni ricorrenti e definitive, partitari, mastrini, bilancio di verifica, libro giornale | chiusura dell'esercizio, bilancio CEE e cespiti M10 |
| IVA | registri IVA, liquidazione con F24, acconto, file LIPE, ritenute d'acconto con prospetto F24 e dati CU, bollo virtuale | dichiarazioni d'intento M10 |
| Scadenzario | partite aperte dai documenti, visibili nei partitari | incassi, pagamenti, banche e solleciti M8 |
| Fatturazione elettronica | — | M9 |
| 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. 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).
## 11. 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).
## 12. 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)
+7 -3
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.7.0 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.7.0 (M7; 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) |
+230 -142
View File
@@ -1,199 +1,287 @@
# 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.7 · **Ultima revisione:** 2026-11-13 · **Versione software:** 0.7.0 (M7)
> **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. Arrivano più avanti: i **pagamenti delle fatture** dallo scadenzario, che oggi
> per le ritenute si registrano a mano (M8), le **dichiarazioni d'intento** e il plafond e l'**Intrastat** (M10),
> 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). Finché i
pagamenti non arrivano con lo [Scadenzario](Scadenzario) (M8), si registra 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`.
+6 -1
View File
@@ -1,8 +1,13 @@
# Istanza e database
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2 e M12)
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2 e M12)
> **Modulo di licenza:** CORE (aziende oltre la prima: MULTI) · **Livello richiesto:** amministratore; azioni distruttive solo super utente · **Specifica:** SPEC §5.3, §5.4, §7.1, §12.1, §13
> **Nella versione 0.2.0** ci sono la creazione della prima azienda al primo avvio, la creazione e il collegamento
> di altre aziende (dal codice, con il modulo MULTI), gli stati *attiva / manutenzione / sola lettura / disattivata*
> con le sessioni chiuse quando un'azienda va in manutenzione e il contesto azienda per pagine e API (header
> `X-Company`). Le schermate descritte qui arrivano in M12.
## A cosa serve
Un'installazione di Khaemhat (una **istanza**, cioè un container) può servire più aziende. Ogni azienda ha il
+6 -1
View File
@@ -1,8 +1,13 @@
# Licenze e moduli
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2)
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2)
> **Modulo di licenza:** CORE · **Livello richiesto:** super utente (attivazione); amministratore (consultazione) · **Specifica:** SPEC §1.8, §6, §8, §12.2
> **Nella versione 0.2.0** ci sono verifica e applicazione della licenza: trial di 60 giorni, file `.khl` firmati
> (ECDSA P-256) da `KHAEMHAT_LICENSE` o caricati, codici di attivazione dei moduli, modalità test con i codici
> fittizi, controllo orario della scadenza con notifiche, limite di aziende e di utenti contemporanei. La schermata
> **Licenze e moduli** arriva in M12.
## A cosa serve
Khaemhat è diviso in **moduli** attivabili con licenza. La pagina **Licenze e moduli** mostra la licenza
+8 -3
View File
@@ -1,8 +1,13 @@
# Log
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2)
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2)
> **Modulo di licenza:** CORE · **Livello richiesto:** amministratore · **Specifica:** SPEC §7.3, §9.5, §12.7
> **Nella versione 0.2.0** il log è scritto nel database di sistema (`sys_log`) con sezione, livello, utente,
> azienda e identificativo di traccia (header `X-Trace-Id`), oltre che su console in JSON; la retention per livello
> gira ogni notte. La schermata **Log** con filtri e regole di avviso arriva in M12: fino ad allora si legge il log
> del container.
## A cosa serve
Il **log applicativo** registra ciò che succede in Khaemhat: accessi, documenti emessi, invii SDI, backup,
@@ -54,7 +59,7 @@ Ogni modulo scrive nella **propria sezione**. Il pannello a sinistra le elenca c
| **Autenticazione** | accessi, errori di password, blocchi, 2FA, nuovi dispositivi |
| **Database** | connessioni, manutenzione |
| **Migrazioni** | migrazioni applicate e loro esito |
| **Documenti** | creazione, emissione, annullamento di documenti |
| **Documenti** | conferma ed emissione con il numero assegnato, chiusura, riapertura, annullamento, eliminazione delle bozze (da 0.5.0) |
| **Contabilità** | registrazioni, liquidazioni, chiusure |
| **Magazzino** | movimenti, ricostruzioni |
| **SDI / e-invoicing** | generazione XML, invii, notifiche, scarti |
@@ -63,7 +68,7 @@ Ogni modulo scrive nella **propria sezione**. Il pannello a sinistra le elenca c
| **Attività programmate** | inizio, fine, durata, esito di ogni esecuzione |
| **Backup** | backup, copie remote, verifiche, ripristini |
| **API / MCP** | chiamate API e strumenti MCP |
| **E-mail / PEC** | invii e letture di posta |
| **E-mail / PEC** | invii e letture di posta: da 0.5.0 ogni messaggio messo in coda, inviato, ritentato o fallito, con la risposta del server SMTP |
| **Integrazioni** | VIES, cambi BCE, intermediari SDI |
| **UI / circuiti** | errori dell'interfaccia con lo stack completo |
| **Prestazioni** | query oltre 500 ms, richieste lente, garbage collection |
+136 -90
View File
@@ -1,148 +1,194 @@
# 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.6 · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.6.0 (M6)
> **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. Arrivano più avanti: le **scritture contabili** delle rimanenze e il
> **libro inventari** con la chiusura dell'esercizio (M10), 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; le rimanenze alimenteranno la chiusura dell'esercizio e il libro
inventari con la chiusura dell'esercizio (M10).
## 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)
+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 |
|---|---|---|
+43 -19
View File
@@ -1,6 +1,6 @@
# Primi passi
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2-M5)
> **Stato:** parziale (passi 1-4, 7, 10 e 12 completi; amministrazione da interfaccia con M12) · **Ultima revisione:** 2026-11-12 · **Versione software:** 0.5.0
> **Modulo di licenza:** CORE · **Livello richiesto:** super utente, poi amministratore · **Specifica:** SPEC §5.4, §7, §8, §12, §14
Questa pagina accompagna chi ha appena installato Khaemhat dal primo avvio del container fino alla prima fattura
@@ -57,15 +57,24 @@ disattivata al primo cambio password.
*Mockup 001 — pagina di accesso: a sinistra marca e funzioni principali, a destra il modulo con azienda, nome utente,
password e l'avviso della modalità Trial (anteprima ridotta).*
1. Nel campo **Azienda** scegli la prima azienda (quella creata dal container, ad esempio *Khaemhat Demo S.r.l.*).
![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.
2. In **Nome utente** scrivi il nome del super utente (`KHAEMHAT_SUPERUSER`, predefinito `root`).
3. In **Password** scrivi la password iniziale (`KHAEMHAT_SUPERUSER_PASSWORD`).
4. Spunta **Ricordami su questo dispositivo** solo su un computer personale.
5. Premi **Accedi**.
Il riquadro giallo in fondo al modulo ricorda che l'istanza è in **modalità Trial** finché non attivi una licenza
(passo 6). Il collegamento **Password dimenticata?** invia un link monouso all'indirizzo e-mail registrato; funziona
solo dopo aver configurato la posta (SMTP) in **Amministrazione → Impostazioni**.
(passo 6). Il collegamento **Password dimenticata?** invia un link monouso all'indirizzo e-mail registrato; arriva con
la posta (SMTP) in una milestone successiva: nella versione 0.2.0 non è ancora presente.
Dopo 5 tentativi sbagliati l'account resta bloccato per 15 minuti; da uno stesso indirizzo IP sono accettati al
massimo 10 invii al minuto del modulo di accesso.
## Passo 3 — Cambio password obbligatorio
@@ -74,11 +83,15 @@ solo dopo aver configurato la posta (SMTP) in **Amministrazione → Impostazioni
*Mockup 003 — cambio password al primo accesso, con indicatore di robustezza e avviso che la password del container
viene disattivata (anteprima ridotta).*
1. In **Password attuale (provvisoria)** riscrivi la password iniziale.
1. In **Password attuale o provvisoria** riscrivi la password iniziale.
2. In **Nuova password** scrivi la nuova password. La regola predefinita chiede almeno **10 caratteri** e **3 classi**
(lettere, numeri, simboli) e non ammette nessuna delle ultime 5 password usate.
3. Ripetila in **Conferma nuova password** e controlla la barra **Robustezza**.
4. Premi **Imposta password e continua**.
(minuscole, maiuscole, numeri, simboli), non deve contenere il nome utente e non ammette nessuna delle ultime 5
password usate.
3. Ripetila in **Ripeti la nuova password**.
4. Premi **Salva e continua**.
Nella versione 0.2.0 la pagina è più essenziale del mockup 003: l'indicatore di robustezza arriva con l'interfaccia
completa (M3).
Da questo momento la password scritta nelle variabili del container non vale più. Puoi toglierla dal file `.env` o
dal template: non viene più letta.
@@ -87,23 +100,32 @@ dal template: non viene più letta.
Per il super utente e per gli amministratori la verifica in due passaggi è **obbligatoria** (SPEC §7.3). Al primo
accesso Khaemhat chiede di collegare un'app di autenticazione (qualunque app compatibile con lo standard TOTP,
RFC 6238). La schermata di attivazione non è tra i mockup: il formato esatto (chiave testuale e/o codice QR) sarà
definito in sviluppo.
RFC 6238). La schermata **Configura la verifica in due passaggi** non è tra i mockup (ADR 0019): mostra la chiave
in gruppi di quattro caratteri e il collegamento **Apri nell'app di autenticazione** (`otpauth://`), utile sul
telefono. Non c'è un codice QR, perché generarlo richiederebbe una libreria esterna (SPEC §1.2).
1. Apri l'app di autenticazione sul telefono e aggiungi un nuovo account con la chiave mostrata da Khaemhat.
2. Scrivi in Khaemhat il codice a 6 cifre generato dall'app per confermare il collegamento.
3. Conserva in un luogo sicuro le eventuali informazioni di recupero proposte.
1. Apri l'app di autenticazione (Google Authenticator, Microsoft Authenticator, Aegis, 2FAS…) e aggiungi un nuovo
account scrivendo la chiave mostrata da Khaemhat, oppure tocca **Apri nell'app di autenticazione** dal telefono.
2. In **Primo codice dell'app** scrivi le 6 cifre generate dall'app e premi **Attiva**.
3. Khaemhat mostra **10 codici di recupero**: copiali in un luogo sicuro. Ognuno vale una volta sola al posto del
codice dell'app e non verrà mostrato di nuovo. Poi premi **Ho salvato i codici, continua**.
![002 · Accesso · verifica in due passaggi (TOTP)](https://gitea.encke-hake.ts.net/BalboSoft/Khaemhat/raw/branch/main/docs/mockups/thumbs/002-accesso-2fa.png)
*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.
Al posto delle 6 cifre puoi scrivere uno dei codici di recupero.
> **Attenzione.** Se perdi il telefono con l'app e sei il super utente, nessun altro può reimpostare il tuo accesso
> dall'interfaccia. Tieni una copia sicura della chiave TOTP o delle informazioni di recupero.
> dall'interfaccia. Tieni al sicuro i codici di recupero.
## Passo 5 — Creare un amministratore
@@ -261,12 +283,14 @@ Con l'azienda configurata puoi emettere la prima fattura:
4. Scegli il cliente: pagamento, listino e agente vengono proposti dalla sua scheda.
5. Nella scheda **Righe** aggiungi l'articolo (`F4` apre la ricerca), la quantità e controlla prezzo e IVA.
6. Premi **Salva** (`Ctrl+S`): la fattura è in *bozza*.
7. Premi **Conferma ed emetti**: la fattura riceve il numero, diventa immutabile e, con il modulo ACCT attivo,
viene contabilizzata.
8. Dalla toolbar genera il PDF o l'XML FatturaPA: ogni file generato diventa un allegato della fattura.
7. Premi **Emetti**: la fattura riceve il numero e diventa immutabile.
8. Premi la **stampante** (`Ctrl+P`): l'anteprima di stampa offre il PDF e **Salva come allegato**; dal menu **⋯**
**Invia per e-mail** manda il PDF al cliente (serve il server SMTP, vedi [Impostazioni](Impostazioni#e-mail-smtp)).
La guida completa è in [Vendite](Vendite); l'invio allo SDI richiede il modulo EINV (vedi
[Fatturazione elettronica](Fatturazione-elettronica)).
![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). **Prossima:** M8.
| # | 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
+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
+118 -48
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,8 +92,8 @@ periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura
| Tabella | Contenuto |
|---|---|
| **Paesi** | codici ISO 3166-1, appartenenza all'UE, codice SDI per l'estero (`XXXXXXX`) |
| **Province** e **Comuni** | CAP e codice catastale: servono per la compilazione da CAP e per il calcolo del codice fiscale |
| **Valute** e **Cambi** | valute con i cambi giornalieri della BCE |
| **Province** e **Comuni** | Sigla, regione, codice catastale (il codice del comune), codice ISTAT e CAP: servono per la compilazione da CAP e per il calcolo del codice fiscale. Province, comuni e CAP arrivano con i dati di base (elenco ISTAT, CAP da GeoNames); i pochi CAP mancanti si completano a mano o con l'Importa CSV, vedi [Dati di base e di esempio](Dati-di-base-e-esempio) |
| **Valute** e **Cambi** | valute con i cambi giornalieri della BCE; in *Cambi* (`/tabelle/cambi`) si vedono i cambi per data e origine e si inserisce un cambio manuale |
| **Unità di misura** | codici interni e codice usato nell'XML SDI |
| **Codici IVA** | aliquota, natura SDI, riferimento normativo, esigibilità, tipo, indetraibilità, conti IVA, validità (vedi sotto) |
| **Metodi di pagamento** | codici SDI `MP01`…`MP23` (es. MP01 contanti, MP02 assegno, MP05 bonifico, MP08 carta di pagamento, MP12 RiBa, MP19 SEPA Direct Debit) |
@@ -77,9 +111,9 @@ periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura
| **Depositi** | magazzini, anche mobili (es. furgone) |
| **Categorie articolo** | su tre livelli |
| **Categorie controparte** | classificazione di clienti e fornitori |
| **Listini** | intestazioni dei listini (i prezzi sono in [Articoli e listini](Articoli-e-listini)) |
| **Politiche di sconto** | regole di sconto riutilizzabili (struttura definita in sviluppo) |
| **Tipi documento** | catalogo dei documenti con numeratore, causale di magazzino, causale contabile, registro IVA, codice TD, modello di stampa |
| **Listini** | intestazioni dei listini: valuta, IVA inclusa, validità, **Listino base** (uno solo, in partenza `BASE`), **Derivato da** con ricarico % e arrotondamento (i prezzi sono in [Articoli e listini](Articoli-e-listini)) |
| **Politiche di sconto** | sconti in cascata con un codice, come formula (`10+5`), da richiamare nelle condizioni |
| **Tipi documento** | catalogo dei documenti con **genere** (obbligatorio), numeratore, causale di magazzino, causale contabile, registro IVA, codice TD, modello di stampa |
| **Centri di costo** | per l'analisi dei costi e dei ricavi |
| **Commesse** | progetti o cantieri a cui imputare costi e ricavi |
@@ -88,6 +122,9 @@ periodo (vedi [IVA](IVA)) e la chiusura dell'esercizio lo rende di sola lettura
![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 dall'elenco ABI o, finché l'elenco non è caricato, da un conto dell'azienda presso la stessa banca | accesa |
| Cambi BCE giornalieri | l'attività di sistema scarica i cambi nei giorni lavorativi; spenta, l'azienda usa solo cambi manuali | accesa |
| Descrizione articolo nelle righe | copia la descrizione dell'articolo nella riga del documento | accesa |
| Ultimo prezzo praticato al cliente | lo mostra come riferimento | accesa |
| Proponi ultimo documento simile | parte dal documento precedente dello stesso tipo e cliente | spenta |
| Data di consegna = data + lead time | aggiunge il tempo di approvvigionamento e sposta la data al primo giorno lavorativo | accesa |
| Conti contabili da articolo, categoria e causale | propone conti di ricavo e costo | accesa |
Le opzioni sulle righe e sui conti agiscono con i documenti e la contabilità (da M5). Oltre a queste, i documenti
ricevono sempre destinazione, listino, pagamento e agente dal cliente e causale e deposito dal tipo documento.
### Altre preferenze aziendali
| Scheda | Contenuto |
|---|---|
| **Arrotondamenti e controlli** | arrotondamenti di prezzi e totali, controlli bloccanti o di avviso (fido, scaduto, date) |
| **Default documenti** | sezionali, depositi, causali e condizioni proposti per tipo documento |
| **Modelli e-mail** | testi per l'invio di documenti, solleciti, notifiche |
| **Testi di stampa** | diciture e note in calce ai documenti |
In 0.4.0 le preferenze azienda hanno le schede *Codici automatici* e *Compilazione automatica*. Arriveranno con i
moduli che le usano:
La periodicità IVA e le numerazioni fanno parte delle preferenze aziendali e si impostano nel profilo e nei
numeratori. Il dettaglio di ogni opzione sarà completato in sviluppo.
| Scheda | Contenuto | Con |
|---|---|---|
| **Arrotondamenti e controlli** | arrotondamenti di prezzi e totali, controlli bloccanti o di avviso (fido, scaduto, date) | documenti (M5) |
| **Default documenti** | sezionali, depositi, causali e condizioni proposti per tipo documento | documenti (M5) |
| **Modelli e-mail** | testi per l'invio di documenti, solleciti, notifiche | e-mail (M5) |
| **Testi di stampa** | diciture e note in calce ai documenti | stampe (M5) |
La periodicità IVA e le numerazioni si impostano nel profilo azienda e nei numeratori.
## Permessi e licenza
@@ -188,8 +257,9 @@ con i rispettivi moduli attivi. La conferma della liquidazione e la chiusura del
modificare i codici predefiniti usati in documenti già emessi.
- **Non riesco a inserire un documento con data di agosto.** Il periodo è bloccato o liquidato: chiedi a chi gestisce
la contabilità.
- **Posso cambiare la maschera dei codici clienti a metà anno?** I codici già assegnati non vengono riscritti: la
nuova maschera vale per i codici successivi (il comportamento in caso di conflitti sarà definito in sviluppo).
- **Posso cambiare la maschera dei codici clienti a metà anno?** Sì: i codici già assegnati non vengono riscritti,
la nuova maschera vale per i codici successivi e continua lo stesso progressivo; un codice che esiste già viene
saltato.
## Pagine correlate
+7 -1
View File
@@ -1,8 +1,14 @@
# Utenti e permessi
> **Stato:** bozza · **Ultima revisione:** 2026-11-10 · **Versione software:** non ancora rilasciata (milestone M2)
> **Stato:** parziale · **Ultima revisione:** 2026-11-11 · **Versione software:** 0.2.0 (milestone M2)
> **Modulo di licenza:** CORE · **Livello richiesto:** amministratore (amministratori: solo super utente) · **Permessi principali:** `company.users.manage` · **Specifica:** SPEC §7, §12.3, §12.4
> **Nella versione 0.2.0** ci sono il motore e l'accesso: i tre livelli, gli account di istanza e gli utenti di
> azienda, password con storico e blocco, verifica in due passaggi con codici di recupero, sessioni revocabili, ruoli
> predefiniti e permessi `modulo.area.azione` con override, controlli sulle pagine (`[RequirePermission]`,
> `[RequireLevel]`, `[RequireModule]`). Le schermate **Utenti** e **Ruoli e permessi** descritte qui arrivano in M12:
> fino ad allora gli utenti si gestiscono solo con il super utente creato dal container.
## A cosa serve
Queste due pagine stabiliscono **chi entra** in Khaemhat e **cosa può fare**:
+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)). Arrivano più avanti: gli **incassi** e il controllo
> del fido (M8), il **file XML** per lo
> SDI (M9) e il collegamento alle opportunità del **CRM** (M11). I pulsanti di queste funzioni compaiono quando la
> funzione c'è.
## Dove si trova
Menu **Vendite** → *Preventivi*, *Ordini clienti*, *DDT*, *Fatture*, *Note di credito*, *Fatturazione differita*.
Le pro forma, le fatture di acconto e le parcelle stanno nell'elenco *Fatture*; le note di debito in *Note di credito*.
## Il motore dei documenti in sintesi
## Un giro completo in cinque minuti
Ogni tipo di documento è descritto da una definizione che stabilisce: numeratore e sezionale, causale di magazzino
(se il documento carica o scarica merce), **effetti** (impegno, scarico, partite, registrazione contabile), da quali
documenti può essere **evaso** (ad esempio un DDT da un ordine), tipo documento SDI (TD), causale contabile, registro
IVA e modello di stampa.
Con l'azienda di esempio (vedi [Dati di base e di esempio](Dati-di-base-e-esempio)) trovi già un anno di vendite in
tutti gli stati. Per provare il ciclo da zero:
1. **Vendite → Preventivi → Nuovo preventivo** (`Ctrl+N`): scegli il cliente, aggiungi due righe, **Conferma**.
2. Sul preventivo premi **Crea Ordine cliente**: le righe passano all'ordine, collegate al preventivo.
3. Sull'ordine confermato premi **Crea DDT**: puoi consegnare solo una parte delle quantità.
4. **Vendite → Fatturazione differita**: indica il mese, **Cerca i DDT**, **Genera fatture**.
5. Apri la fattura, premi la **stampante** (`Ctrl+P`) per l'anteprima e il PDF, poi **⋯ → Invia per e-mail**.
## Gli elenchi (radar)
![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 (M9) |
Altri badge indicano lo stato contabile (*Non contabilizzata*), del magazzino (*Scaricato*) o della fatturazione
(*Da fatturare*).
Che cosa si può fare:
- Si **modifica** una bozza; di ordini, preventivi, DDT e pro forma confermati si possono ancora cambiare le righe
finché non sono evasi del tutto, ma una quantità non scende sotto quella già evasa e una riga evasa non si toglie.
- Si **elimina** solo una bozza, che non ha mai avuto un numero.
- Si **annulla** un documento confermato non ancora evaso: il numero resta e le quantità che aveva evaso tornano ai
documenti d'origine. Una fattura si annulla **con un motivo** finché il file non è stato inviato allo SDI; dopo, si
fa una nota di credito.
- Si **chiude** il residuo di un documento evaso in parte; **Riapri** lo riporta allo stato che dicono le sue righe.
- Si **duplica** o si **crea** un altro documento da uno in qualunque stato.
## Numerazione
- Formato `{prefisso}/{anno}/{numero a 6 cifre}`, ad esempio `FT/2026/000418`, per **sezionale** (FT, NC, DDT…) e
anno, configurato nei numeratori (vedi [Tabelle azienda](Tabelle-azienda)).
- Il numero è assegnato **alla conferma**, in modo atomico: le bozze non consumano numeri.
- Per fatture e note di credito **non sono ammessi buchi** e la data non può essere anteriore a quella dell'ultimo
documento numerato nello stesso sezionale.
- La data deve cadere in un **periodo fiscale aperto** (vedi esercizi e periodi in [Tabelle azienda](Tabelle-azienda)).
- Il formato è quello del numeratore del tipo documento, per **sezionale** e anno: ad esempio `{number}/{year}` per
fatture, note e DDT (`7/2026`), `OC-{year}-{number:D4}` per gli ordini (`OC-2026-0004`), `PRE-{year}-{number:D4}`
per i preventivi.
- Il numero è assegnato **alla conferma**, in modo atomico: le bozze non consumano numeri, due conferme contemporanee
non ricevono mai lo stesso numero e una conferma non riuscita restituisce il numero. Fatture, note di credito e note
di debito condividono il numeratore delle fatture.
- Per fatture e note **non sono ammessi buchi** e la data non può essere anteriore a quella dell'ultimo documento
numerato nello stesso numeratore.
- La data deve cadere in un **esercizio aperto** (vedi [Tabelle azienda](Tabelle-azienda)); con il primo documento
di un anno nuovo la numerazione riparte da 1.
## Calcolo dei totali
| Elemento | Regola |
|---|---|
| **Imponibile di riga** | quantità x prezzo x (1 - sconto 1) x (1 - sconto 2)…, arrotondato a 2 decimali (arrotondamento commerciale) |
| **Imponibile di riga** | quantità × prezzo × (1 − sconto 1) × (1 − sconto 2)…, arrotondato a 2 decimali (arrotondamento commerciale) |
| **Castelletto IVA** | imponibili raggruppati per codice IVA; imposta calcolata per aliquota sul totale del gruppo |
| **Spese** | trasporto, incasso ecc. con il proprio codice IVA |
| **Sconto piede** | ripartito sulle righe |
| **Bollo** | 2,00 euro automatici se le operazioni esenti, non imponibili o fuori campo IVA superano 77,47 euro; la scheda del cliente indica se è a carico del cliente |
| **Sconto di piede** | ripartito sulle righe |
| **Bollo** | 2,00 euro automatici se le operazioni esenti, non imponibili o fuori campo IVA superano 77,47 euro; la scheda del cliente indica se è a suo carico |
| **Ritenuta d'acconto** | sulle parcelle, calcolata sull'imponibile previsto; il netto a pagare la esclude |
| **Cassa previdenza** | contributo sulle parcelle, con IVA propria |
| **Split payment** | per PA e soggetti obbligati: l'IVA è esposta ma versata dal cliente all'Erario; il totale *da versare* è il solo imponibile (esigibilità **S**) |
| **Split payment** | per PA e soggetti obbligati: l'IVA è esposta ma versata dal cliente all'Erario (esigibilità **S**) |
| **Reverse charge** | fattura senza IVA con natura N6.x: l'imposta la integra il cliente |
| **IVA per cassa** | esigibilità differita al pagamento per chi ha aderito al regime (gestione completa prevista in fase 2) |
**Scadenze**: generate dalla condizione di pagamento (rate, giorni, fine mese, giorno fisso, percentuali, IVA sulla
prima rata, sconto cassa); l'eventuale differenza di arrotondamento va sull'ultima rata.
## Stampa, PDF ed e-mail
![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)
+3
View File
@@ -1,5 +1,8 @@
**[Khaemhat](Home)**
**Guida**
- [Guida all'uso](Guida-utente)
**Installazione**
- [Primi passi](Primi-passi)
- [Unraid](Installazione-Unraid)
Binary file not shown.

After

Width:  |  Height:  |  Size: 188 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 182 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 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: 165 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 118 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 174 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 149 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 190 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 100 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 73 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 97 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 159 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 93 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 127 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 115 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 215 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 89 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 54 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 98 KiB

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