[Invoices]: Sumex Swiss TARMED medical invoicing (decision needed) #660

Defer/decision issue — niche (Swiss medical practices only) and heavy (893-line XML builder + dedicated invoice sub-entity + external PDF service + PDF-embedding). No existing issue anywhere in the tracker before this one. This issue exists so the decision to build or explicitly decline is tracked rather than silently omitted — v2's config/report-fields.php:111-112 already reserves sumex_casedate/sumex_casenumber report fields, so the Report Builder anticipates it. This issue also covers the v1 Sumex PDF generation actions (generate_sumex_pdf/generate_sumex_copy), consolidating what would otherwise be a duplicate item in the PDF/Templates parity domain.

Swiss medical providers bill insurers via the Forum Datenaustausch "general invoice request" XML (TARMED). v1 implements this end-to-end (READ-ONLY repo): application/libraries/Sumex.php — builds generalInvoiceRequest_440.xsd XML (http://www.forum-datenaustausch.ch/invoice namespace) from invoice + patient + case data and renders the PDF either by POSTing the XML to an external SUMEX_URL service or internally by embedding the XML in the invoice PDF; application/modules/invoices/models/Mdl_invoice_sumex.php — per-invoice Sumex record (ip_invoice_sumex: reason enum disease/accident/maternity/prevention/birthdefect/unknown, diagnosis, observations, treatment start/end, case date, case number); patient fields on client (birthdate, gender, AVS/insured number) and provider fields on user (GLN, RCC); settings (role, place, canton, ESR slip type) in application/modules/settings/views/partial_settings_invoices.php:569+; controller actions generate_sumex_pdf / generate_sumex_copy (Invoices.php:333-356, copy/storno flags) and a dedicated invoices/view_sumex view.

Specific

1. Optional Sumex mode per company (setting) adding: a sumex_invoices companion table (reason enum, diagnosis, observations, treatment_start/end, case_date, case_number, FK invoice), patient fields on the customer (birthdate, gender, AVS number, insured number), provider fields on the company (GLN, RCC), and settings for role, place, canton, ESR slip type.
2. SumexXmlGenerator service producing generalInvoiceRequest_440.xsd-valid XML (port Sumex::xml() node-by-node).
3. PDF actions "Sumex PDF" and "Sumex copy" (copy=1/storno flags) on the invoice: external mode (POST XML to configured Sumex service URL, SSRF-guarded, stream returned PDF) and internal mode (embed XML into the invoice PDF as in v1 Sumex::pdf() internal branch).
4. Invoice view switches to a Sumex-aware layout when a Sumex record exists (v1 Invoices.php:236).

Measurable

• Generated XML validates against generalInvoiceRequest_440.xsd.
• Sumex actions hidden unless the company enables Sumex mode and the invoice has a Sumex record.
• Report Builder sumex_casedate/sumex_casenumber fields (already in config/report-fields.php) resolve to real data.

Achievable

Direct port of Sumex.php (self-contained DOMDocument builder, constant tables for ROLES/PLACES/CANTONS already enumerated in the class) plus one migration per new field group; external-PDF mode is a single guarded HTTP POST.

Relevant

Parity item for the existing Swiss medical user base of v1; without a decision, migration silently strips their billing format.

Time-Bound

Deferred backlog — schedule only after #126 core e-invoicing ships, or explicitly close as out-of-scope for v2.

Arrange

• Company with Sumex mode enabled, GLN/RCC set; customer with birthdate, gender, AVS number; invoice with a Sumex record (reason accident, treatment dates, case number) and taxed items.

Act

• Run SumexXmlGenerator for the invoice; invoke the "Sumex PDF" and "Sumex copy" actions (external service faked with Http::fake()).

Assert

• XML root is invoice:request in namespace http://www.forum-datenaustausch.ch/invoice with schemaLocation generalInvoiceRequest_440.xsd and validates against the XSD.
• Patient, provider (GLN/RCC), treatment, and case data appear in the correct nodes; reason maps through the six-value enum.
• External mode POSTs the XML to the configured URL and streams the returned PDF; private/loopback URLs are rejected.
• Copy action sets the copy flag in the XML; actions are hidden when Sumex mode is off or no Sumex record exists.
• Report Builder resolves sumex_casedate and sumex_casenumber for the invoice.