feat: Deposit & Final Invoices (Abschlagsrechnung / Schlussrechnung)

[clstaudt]

Closes #326

Rebased onto current main (the branch was 171 commits behind, predating the ContractCharge system and the non-nullable InvoiceItem.VAT_category), then finished.

What this does

A fixed-price contract can carry a payment schedule — milestones by percentage or by amount. Each milestone is billed as a deposit invoice (Abschlagsrechnung); the last one produces a final invoice (Schlussrechnung) that states the full contract price, deducts every deposit already issued with the VAT contained in each, and shows the remaining balance.

• Schema: PaymentMilestone table, Invoice.document_type extended with "deposit" / "final", deposit_for_id chain, milestone_id, Alembic revision 1100c34b90c6 (re-parented onto head 9cad5ae77a79).
• Invoicing: generate_deposit_invoice() / generate_final_invoice(), create_deposit / create_final intents, deposits carry the contract's VAT_category, paid status propagates from a settlement to the deposits it settles.
• Rendering: document-type banner, deposit context (which milestone of which contract), per-deposit deduction lines with "VAT included therein", and remaining balance — in all seven templates, driven by shared partials in templates/_shared/ so the settlement layout cannot drift between skins.
• UI: payment-schedule editor on contracts, document-type picker in the create dialog (final enabled only once deposits exist), open-milestone picker, deposit chain grouping, milestone schedule badge.

Scope decisions

• Contract charges are not billed on deposits. A deposit bills a milestone amount and nothing else; charges appear on the final invoice, where the full contract scope is settled.
• Deposit and final invoices ship as PDF without embedded ZUGFeRD XML, with a logged warning. The builder emits type code 380 with full document totals, while EN16931 wants 386 for a prepayment and BT-113 prepaid amounts on the settlement — emitting 380 would state an amount the client does not owe. Correct prepayment support is follow-up scope.

Fixed since the draft

• Stale milestone badge — the schedule progress is now derived from the invoice chain, which the view reloads, instead of from milestone.invoiced flags on a contract snapshot embedded in an older invoice. Ordinary invoices on a schedule contract no longer show the badge at all.
• Final-invoice rendering failures — invoices are reloaded from the data source after the insert, so the deduction payload renders from a session-bound graph.
• Deposits silently dropped from the deduction list — writing the milestone flags through save_invoice merged a contract graph loaded before the settlement existed, whose cascade wrote the old deposit_for_id back, leaving only the newest deposit deducted. Linking and flagging now go through targeted writes (link_deposits_to_final, mark_milestones_invoiced).

Test plan

• uv run pytest — 580 passed, 1 skipped; ruff check / ruff format --check clean; npx tsc --noEmit clean.
• tuttle_tests/test_deposit_invoices.py: VAT settlement math against the exact example in Deposit & Final Invoices (Abschlagsrechnung / Schlussrechnung) #326 (10,000 net / 1,900 VAT / 11,900 gross, less a 5,950 deposit containing 950 VAT, leaves 5,950), schedule validation (percentages sum to 100, amounts sum to the fixed price, no mixing, invoiced milestones cannot be repriced or removed), and the e-invoice guard.
• test_rpc_dispatch.py::test_deposit_and_final_invoice_lifecycle: a 40/40/20 schedule end to end over real RPC — two deposits, the final deducting both, JSON-serialisable throughout (a deposit chain is what provokes DetachedInstanceError), paid status reaching the whole chain.
• Deposit and final PDFs rendered in all seven templates, EN and DE, and read for layout and localisation.
• Playwright Electron smoke run of the schedule → deposit → final flow (ui/scripts/smoke-deposit.ts); screenshots in the thread below.

Demo data

Two schedules, per the AGENTS.md demo-data rule: Sam Lowry's Heating Repair is settled (deposit + final, 50/50), and Central Services' Heating Modernisation is mid-flight — one deposit paid, two milestones open — so the workflow can be walked in the app.

Made with Cursor

[aaronspring]

never worked with Abschlagsrechnung but seems a useful feature.

Comments:

• Invoice Details view:
  • same for "Final" and "Half upfront": what should the details view show? currently the different deposits and the remaining balance.
• only for fixed-price contracts. do you see deposit invoices used for time-based?
• in contracts -> fixed-price, if I add milestones and then click on collapse, payment schedule disappears and only reappears if I click on "add milestone". should rather be > collapsed hiding the milestones only and when user wants to add should click on > collapsed