Add tax category "O" (outside scope of tax) for third-country B2B services

[aaronspring]

Summary

Fixes #390.

Tuttle derived the EN16931 tax category from the VAT rate alone (tuttle/einvoice.py: 0 → "Z", else "S"). A German Freiberufler invoicing a US client for B2B services therefore emitted a zero-rated invoice, when under §3a (2) UStG / Art. 44 VAT Directive the supply is outside the scope of German VAT — UNTDID 5305 category O, a distinct category from Z.

Tax category is now an explicit field on the contract, snapshotted onto each invoice item, driving both the Factur-X XML and the human-readable PDF.

What the schematron actually requires

I pulled the official CII schematron from ConnectingEurope/eInvoicing-EN16931 rather than relying on secondary sources, which disagree on two points. The flag="fatal" rules for category O:

Rule	Requirement	Implementation
BR-O-01	Exactly one VAT breakdown with CategoryCode O	Breakdown keyed by (category, rate)
BR-O-02	No seller VAT id, seller tax-representative VAT id, or buyer VAT id	VA registrations omitted
BR-O-05	Invoice line carries no RateApplicablePercent	Element left unset
BR-O-09	Breakdown tax amount is 0	—
BR-O-10	Breakdown carries ExemptionReason or ExemptionReasonCode	VATEX-EU-O + text
BR-O-11/12	O never mixes with another category	Guarded at invoice creation

BR-O-02 is why this PR also adds User.tax_number (Steuernummer): §14 UStG still requires an identifier on the invoice, and CII carries the Steuernummer under a different scheme (FC).

Changes

• TaxCategory enum (S/Z/O, values are the UNTDID codes) on Contract and InvoiceItem. The item snapshots the contract's category, so editing a contract cannot retroactively alter an issued invoice.
• User.tax_number, emitted as CII scheme FC on outside-scope invoices.
• Tax breakdown keyed by (category, rate) — a zero-rated and an outside-scope line both sit at 0% and previously would have collapsed into one wrong ApplicableTradeTax group.
• All 7 invoice templates: — instead of 0 % in the VAT column, suppressed VAT total row, and a localized legal note (en/de/es).
• Contract form gains a tax-category selector that zeroes and disables the VAT rate for non-standard categories; settings gains the tax number field.
• Alembic migration backfilling categories from the VAT rate and the client's country.

Two things reviewers should know

1. @validates is dead code on SQLModel(table=True) classes here. Pydantic's __setattr__ overwrites whatever the SQLAlchemy validator returns, so the pre-existing _normalize_vat_rate hook never fired — which is why _validated_save calls normalize_vat_rate by hand. Both hooks are replaced by an explicit validate_vat() invoked on write paths, in the same style as the existing validate_pricing(). A per-attribute hook would also have wrongly rejected switching a contract from O back to S, since save_from_dict assigns attributes in payload order.

2. The migration is a semantic rewrite, not just a schema change. Existing zero-rate contracts with a non-EU client become category O, so re-rendering an already-issued invoice will produce different output than what was originally sent. A zero-rate line under a taxed contract deliberately stays Z — promoting it to O would create a mixed-category invoice violating BR-O-11/12. An unresolvable client country keeps the historical Z reading rather than silently reclassifying.

Verification

• 485 tests pass, up from 371 on main. tsc --noEmit is clean.
• The three load-bearing behaviours were mutation-tested: re-adding the seller VAT id, the line VAT rate, or reverting the breakdown key to rate-only each fails exactly the intended test and nothing else.
• End-to-end through the real dispatch layer: contract saved as "O" over JSON-RPC → invoice created → PDF rendered → factur-x.xml extracted back out of the resulting PDF and checked against BR-O-02/05/09/10.
• Driven through the running app (Electron + demo data, not a mock): contract form, settings, invoice view, and both rendered PDFs. Screenshots and the XML extracted from the app-generated PDF are in the comments below.

Note for reviewers on the merge

main gained 8ec5efc5316d (add task table) with the same down_revision as this branch's migration, which left two Alembic heads — alembic upgrade head failed on a fresh database. main is merged in here and the tax-category migration is re-chained onto 8ec5efc5316d, giving a single linear head. It was re-pointed rather than joined with a merge revision because it has not been released; the append-only rule protects revisions already on main.

Out of scope, worth separate issues: no AE (intra-EU reverse charge) category; CI validates against the XSD only, which checks none of the BR-O rules — those live in Schematron, so wiring it in would turn the hand-written assertions in test_einvoice.py into a real conformance gate.

Checklist

• I have read the Contributing guide.
• I have installed and tested the application for my platform (just dev). — the built Electron app was launched and clicked through against a fresh database with demo data; see the screenshots in the comments.
• The test suite passes locally (just test). — 485 passed, 1 skipped.
• Pre-commit hooks are installed and pass (just precommit). — the pinned black==22.6.0 cannot run on Python 3.14 (asyncio.get_event_loop() removal); new code was formatted with current black instead.
• I have added or updated tests where appropriate.
• I have updated the documentation / docstrings where appropriate.
• If my change touches the schema (tuttle/model.py), I generated and reviewed an Alembic migration (just migrate "<msg>").
• If my change affects the graphical user interface, I have provided screenshots. — contract form (standard vs. outside scope), contract detail, settings, invoice view, and both rendered PDFs; in the comments below.
• I understand and can explain all submitted changes; if AI assistance was significant, I have disclosed it in the summary above.

🤖 Generated with Claude Code

[aaronspring]

Changing stadtwerke metropolis contract to "Outside scope of Tax" creates invoice with no mention of VAT and uses Tax ID in footer.

[aaronspring]

GUI verification — contract form

Driven through the real Electron app (Playwright over the packaged renderer) against a fresh DB with demo data, not a mock.

Standard rated — VAT rate editable, as before:

Outside scope of tax — selecting a non-standard category zeroes the VAT rate and disables the input. Asserted in the DOM, so it is genuinely disabled, not just dimmed:

{ value: "0", disabled: true }

Saving persists VAT_rate=0, VAT_category=outside_scope, and re-opening the form keeps 0 — this is the @validates / 0 → 19% default bug the PR describes, confirmed fixed.

Contract detail now reads the category rather than inferring it from the rate:

[aaronspring]

GUI verification — settings and invoice

Settings — the new User.tax_number (Steuernummer), which BR-O-02 makes necessary: it forbids the VAT number on an outside-scope invoice, but §14 UStG still requires an identifier.

Invoice created from the outside-scope contract. The line item snapshots the category at creation, so editing the contract afterwards cannot retroactively alter an issued invoice — verified: the pre-existing invoices on that contract stayed standard.

VAT is shown as — in the summary tile, the line item, and the Details tab, consistent with the rendered PDF beside it:

[aaronspring]

Rendered PDF, and the XML extracted back out of it

Both PDFs below were produced by the running app, not by a test fixture.

Outside scope (category O)

— instead of 0 % in the VAT column, no VAT total row, the localized legal note, and Tax No. in the footer instead of the VAT number:

The footer is load-bearing: BR-O-02 keeps the VAT number out of the embedded CII, so a PDF that still printed it would contradict its own XML. Pulling factur-x.xml back out of that exact file:

Rule	Requirement	Found
BR-O-01	exactly one breakdown, category O	1
BR-O-02	no seller/buyer VAT id	0 × schemeID="VA", 1 × schemeID="FC"
BR-O-05	no line VAT rate	0 × RateApplicablePercent
BR-O-09	zero tax amount	<ram:CalculatedAmount>0.00</ram:CalculatedAmount>
BR-O-10	exemption reason	VATEX-EU-O

<ram:ApplicableTradeTax>
  <ram:CalculatedAmount>0.00</ram:CalculatedAmount>
  <ram:TypeCode>VAT</ram:TypeCode>
  <ram:ExemptionReason>Not subject to VAT</ram:ExemptionReason>
  <ram:BasisAmount>1885.00000000000</ram:BasisAmount>
  <ram:CategoryCode>O</ram:CategoryCode>
  <ram:ExemptionReasonCode>VATEX-EU-O</ram:ExemptionReasonCode>
</ram:ApplicableTradeTax>

Standard rated (category S) — regression check

A freshly created standard invoice is the exact mirror: 19.0 % in the VAT column, VAT total row present, VAT No. in the footer, no legal note. Its XML keeps CategoryCode S, the line rate, and schemeID="VA", with no VATEX. Nothing regressed for the common case:

[clstaudt]

Should we wait with merging for a while and leave this here as an example for how a PR should look like?

[aaronspring]

regardless of merge, I think this could serve as an example (maybe for PR templates and listed in AGENTS.md) for how to create review artefacts, also referencing #406. unfortunately the PR grew quite large

[clstaudt]

Thank you @aaronspring