api/documentation/economic/layout-selection-flow.md

E-conomic Draft-Invoice Layout-Selection Flow (TRU-198)

Status: Complete (investigation only — no code changes) Date: 2026-08-17 Scope: Inventory every code path in copenhagentruckwash/api that creates an e-conomic draft invoice or sends draft lines, and document whether each path currently picks a layout, which one it picks, and how the planned with-discounts / without-discounts two-layout selection should apply.

Related work:

• TRU-197 (documentation/economic/invoice-template-audit.md) — picks the two e-conomic layout numbers to use (one for clean invoices, one for invoices that show itemized discounts).
• TRU-193 (documentation/economic/export-field-audit.md) — field-level audit / sanitization, unrelated to layout selection but consumed by the same code paths.
• PR #391 — economic_export_sanitizer, the sanitizer that all draft-line paths now run their text through.

---

Overview

A draft invoice in this codebase is built in two phases:

1. Create the draft envelope — POST /invoices/drafts with a payload that contains customer, paymentTerms, layout.layoutNumber, recipient, currency, date, etc. This is the only place where layout.layoutNumber is set on the draft.
2. Add lines to the draft — POST /invoices/drafts/{id}/lines with an array of product / text / discount lines. Lines are added either one order at a time (single-order draft flow) or in accumulated batches (collected-invoice flow). The layout is already fixed at this point and is not re-sent.

There are therefore only two code paths in the entire backend that create the draft envelope and could pick a layout. Both already implement a discount-aware selector that returns either invoice_layout (no discounts) or invoice_discount_layout (itemized discounts present):

Selector function	Used by	File
collected_order_invoices_o::resolveInvoiceLayoutNumber()	collected_order_invoices_o::createInvoiceDraft() → economic_invoices_drafts_endpoint::add()	objects/collected_order_invoices_o.php:673
economic_invoice_draft_mo::resolveLayoutNumber()	economic_invoice_draft_mo::createInvoiceDraftExample()	modules/economic/invoices/draft/economic_invoice_draft_mo.php:115

The two selectors are independent implementations of the same idea. They both:

1. Inspect the lines that will be sent (or the orders that will be added to the draft).
2. If any line / order has a non-zero discountPercentage (or, in the collected-invoice path, any "billable discount" per economic_invoice_draft::orderItemHasBillableDiscount()), return invoice_discount_layout.
3. Otherwise return invoice_layout.
4. Throw a RuntimeException / Exception if the discount layout is required but invoiceDiscountLayoutNumber is unconfigured (≤ 0).

The two config variables are defined in:

• services/nginx/app/modules/economic/config/economic_invoice_layout_c.php — invoiceLayoutNumber, int, required (default 1).
• services/nginx/app/modules/economic/config/economic_invoice_discount_layout_c.php — invoiceDiscountLayoutNumber, int, optional (default null).
• Both are wired into classes\economic::$config via services/nginx/app/modules/economic/economic_c.php lines 25–48.

Net result of the audit: the two-layout selection is already implemented in both places where a draft envelope is created. There is no code path that creates a draft without going through one of these two selectors. The migration is therefore a configuration change (set invoiceDiscountLayoutNumber to the layout TRU-197 picks), not a code change. See §5 Migration plan for the small set of files that still touch the layout topic and may need follow-up.

---

1. Inventory of code paths

The table below lists every PHP function in services/nginx/app/ that either (a) creates a draft invoice envelope (POST /invoices/drafts) or (b) sends draft lines (POST /invoices/drafts/{id}/lines). Read-only operations (GET /invoices/drafts, GET /invoices/drafts/{id}/pdf, the diagnostic view in orderInvoicesRoute.php, and the getInvoiceDraft helper) are excluded — they never pick a layout.

#	File:line	Function	What it does	Picks layout?	Layout used	Discount-aware?	Recommendation
1	modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php:107	economic_invoices_drafts_endpoint::add()	Low-level POST /invoices/drafts envelope builder; accepts an optional $layout_number arg.	Yes (caller-driven). Sets layout.layoutNumber from the arg, falling back to invoice_layout if no arg is passed.	invoice_layout (default) or whatever the caller passes.	No — does not inspect lines.	Keep as-is. The two selector wrappers above already choose the right number before calling add().
2	modules/economic/invoices/draft/economicInvoicesDrafts.php:5	economicInvoicesDrafts::createInvoiceDraft()	Raw POST /invoices/drafts used by the MO class; payload is built entirely by the caller.	No (caller-driven). The data array the caller passes must already contain layout.layoutNumber.	Whatever the caller put in data['layout']['layoutNumber'].	No.	Keep as-is. Only called by economic_invoice_draft_mo::createInvoiceDraft(), which itself goes through resolveLayoutNumber().
3	modules/economic/invoices/draft/economic_invoice_draft_mo.php:45	economic_invoice_draft_mo::createInvoiceDraftExample()	The single-order draft envelope builder. Builds the full payload including lines and layout.layoutNumber, then calls createInvoiceDraft().	Yes — discount-aware. Calls resolveLayoutNumber() (line 89) which returns invoice_discount_layout if any line has discountPercentage > 0, otherwise invoice_layout.	invoice_layout (no discount) or invoice_discount_layout (with discount).	Yes via hasDiscountedItemizedLines() (line 130).	Already correct. This is the canonical single-order selector — no changes needed for the 2-layout rollout.
4	modules/economic/invoices/draft/economic_invoice_draft_mo.php:115	economic_invoice_draft_mo::resolveLayoutNumber() (private)	The selector for path #3.	Yes.	invoice_layout or invoice_discount_layout.	Yes.	Keep as-is.
5	modules/economic/invoices/draft/economic_invoice_draft_mo.php:130	economic_invoice_draft_mo::hasDiscountedItemizedLines() (private)	Line scan: any line with product set and discountPercentage > 0.	n/a (read-only)	n/a	Yes.	Keep as-is.
6	modules/economic/invoices/draft/economic_invoice_draft_mo.php:151	economic_invoice_draft_mo::createInvoiceDraft()	Thin wrapper around economicInvoicesDrafts::createInvoiceDraft().	No (caller-driven).	Whatever the caller put in $data.	No.	Keep as-is.
7	modules/economic/invoices/draft/economic_invoice_draft_mo.php:209	economic_invoice_draft_mo::addLinesToInvoiceDraft()	POST /invoices/drafts/{id}/lines — adds already-buffered $this->lines to an existing draft.	No — the draft's layout is already set when it was created.	Whatever the draft was created with.	n/a.	No change. Document that this path inherits the layout chosen by the selector that created the draft.
8	modules/economic/endpoints/invoices/draft/economic_invoices_draft_endpoint.php:114	economic_invoices_draft_endpoint::add_lines()	Raw POST /invoices/drafts/{id}/lines with caller-supplied $draft_lines.	No.	n/a.	n/a.	No change.
9	modules/economic/endpoints/invoices/draft/economic_invoices_draft_endpoint.php:75	economic_invoices_draft_endpoint::add_orders()	Iterates over orders_o[] and adds them to an existing draft via economic_invoice_draft (helper). Batched.	No.	n/a.	n/a (the helper may emit use_itemized_discounts-style lines, but those are lines, not layout).	No change.
10	modules/economic/endpoints/invoices/draft/economic_invoices_draft_endpoint.php:144	economic_invoices_draft_endpoint::add_environmental_and_oil_fees()	Adds env/oil fee product lines to an existing draft.	No.	n/a.	n/a.	No change.
11	modules/economic/helpers/economic_invoice_draft.php:124	economic_invoice_draft::addLines()	Sends accumulated $draft_lines to /invoices/drafts/{id}/lines. Optionally runs preflight validation.	No.	n/a.	n/a.	No change.
12	modules/economic/helpers/economic_invoice_draft.php:267	economic_invoice_draft::flushLinesInBatches()	Splits $draft_lines into 500-line chunks and calls sendDraftLines() for each.	No.	n/a.	n/a.	No change.
13	classes/economic_transfer_executor.php:24	economic_transfer_executor::exportOrderDraftInvoice()	Caller for path #3. Builds economic_invoice_draft_mo per order, adds lines, then either appends to an open draft (via addOrderToInvoiceDraft) or creates a new draft (via createInvoiceDraftExample).	Inherits path #3's selector.	invoice_layout or invoice_discount_layout.	Yes (via path #3).	No change.
14	classes/economic_transfer_executor.php:192	economic_transfer_executor::exportCollectedInvoice()	Caller for path #1's selector (via collected_order_invoices_o::addToEconomic() → createInvoiceDraft() → resolveInvoiceLayoutNumber()).	Inherits path #1's selector.	invoice_layout or invoice_discount_layout.	Yes (via path #15).	No change.
15	classes/economic_transfer_executor.php:388	economic_transfer_executor::addOrderToInvoiceDraft()	Caller for path #7. Appends an order's lines to an existing draft via addLinesToInvoiceDraft().	No — draft already has a layout.	n/a.	n/a.	No change. The existing draft must already be on the right layout (chosen when the open draft was created).
16	objects/collected_order_invoices_o.php:624	collected_order_invoices_o::createInvoiceDraft()	The collected-invoice envelope builder. Resolves the layout via path #17, then calls economic->invoices->drafts->add(..., $layout_number).	Yes — discount-aware.	invoice_layout or invoice_discount_layout.	Yes (via path #18).	Already correct. Canonical collected-invoice selector.
17	objects/collected_order_invoices_o.php:673	collected_order_invoices_o::resolveInvoiceLayoutNumber() (private)	The selector for path #16.	Yes.	invoice_layout or invoice_discount_layout.	Yes (via path #18).	Keep as-is.
18	objects/collected_order_invoices_o.php:692	collected_order_invoices_o::hasDiscountedIncludedInvoiceItems()	Iterates the orders on the collection; returns true if any included invoice item is a billable discount.	n/a (read-only)	n/a	Yes.	Keep as-is.
19	objects/collected_order_invoices_o.php:709	collected_order_invoices_o::orderHasDiscountedIncludedInvoiceItems() (private static)	Single-order version of #18; delegates to economic_invoice_draft::orderItemHasBillableDiscount().	n/a (read-only)	n/a	Yes.	Keep as-is.
20	objects/collected_order_invoices_o.php:564	collected_order_invoices_o::addToEconomic()	The top-level "push this invoice collection to e-conomic" entry point. Calls path #16 then path #21.	Inherits path #16.	invoice_layout or invoice_discount_layout.	Yes.	No change.
21	objects/collected_order_invoices_o.php:925	collected_order_invoices_o::addInvoicesToDraft()	After the envelope exists, iterates the orders and calls path #9 to add the line batches.	No — line-add path.	n/a.	n/a.	No change.
22	routes/economicInvoiceRoute.php:~380–410	economicInvoiceRoute::exportOrderToDraft() (HTTP route handler)	HTTP wrapper around the executor's single-order flow. Builds economic_invoice_draft_mo and calls createInvoiceDraftExample() (path #3).	Inherits path #3.	invoice_layout or invoice_discount_layout.	Yes.	No change.

Read-only paths (excluded from the migration list):

• modules/economic/endpoints/invoices/draft/economic_invoices_draft_endpoint.php:21 — get(int $invoice_id)
• modules/economic/endpoints/invoices/draft/economic_invoices_draft_endpoint.php:39 — get_from_external_id(string $external_id)
• modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php:35 — get(array $filters, array $pagination)
• modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php:60 — get_all()
• modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php:73 — get_invoice_lines(array $invoice_ids, array $filters)
• modules/economic/endpoints/invoices/economic_invoices_drafts_endpoint.php:201 — exists(int $draft_invoice_number)
• modules/economic/invoices/draft/economic_invoice_draft_mo.php:200 — getInvoiceDraft(int $int)
• modules/economic/invoices/draft/economic_invoice_draft_mo.php:170 — getInvoicePdf(int $param)
• modules/economic/invoices/draft/economic_invoice_draft_mo.php:160 — deleteInvoiceDraft(int $value)
• modules/economic/invoices/draft/economic_invoice_draft_mo.php:166 — publishInvoiceDraft(int $invoiceDraftId) — important: this is the book step (POST /invoices/booked with {draftInvoice:{draftInvoiceNumber:N}}). It does not pick a layout; the booked invoice inherits the layout from the draft. Keep as-is.
• routes/orderInvoicesRoute.php:2178 — diagnostic fetch ($economic->invoices->draft->get(...))
• modules/economic/helpers/economic_tasks.php:48, 192 — sanity / sync checks (read-only)

Out of scope (no draft creation):

• classes/economic_v2_distribution_service.php — distribution reporting (read-only aggregations over booked invoices). Never creates a draft.
• modules/economic/helpers/economic_invoice_booked.php — the booked-invoice data class. No HTTP calls.

---

2. Current state

• Both envelope creators (path #3 / createInvoiceDraftExample and path #16 / createInvoiceDraft) already have a working discount-aware selector that returns one of two layout numbers from the config store.
• The selectors read from the same two config variables (invoiceLayoutNumber and invoiceDiscountLayoutNumber) which are already wired into economic::$config and surfaced in the EconomicConfigEntry OpenAPI schema.
• The invoiceDiscountLayoutNumber config var is currently optional (see economic_invoice_discount_layout_c.php — setupConfigVariable(..., true, ...) with required = true in the call signature but the constructor's third arg false means a null value is allowed; the selectors throw if it is required and ≤ 0).
• The selectors are independent code paths. They each inspect lines slightly differently:
  • The MO selector (hasDiscountedItemizedLines) checks discountPercentage > 0 per line.
  • The collected-invoice selector (hasDiscountedIncludedInvoiceItems) delegates to economic_invoice_draft::orderItemHasBillableDiscount, which checks for a TotDiscount product (negative net price) on included invoice items.
  • Both reach the same boolean result: does this draft need the discount layout? — so the layout chosen by either selector is consistent.

---

3. Desired state

After TRU-197 picks the two layout numbers and the operator configures them in the economic module:

• invoiceLayoutNumber = the layout TRU-197 picked for clean invoices.
• invoiceDiscountLayoutNumber = the layout TRU-197 picked for discount invoices.

Then:

• A single-order draft with no itemized discount goes out with layout.layoutNumber = invoiceLayoutNumber (path #3 / selector #4).
• A single-order draft with an itemized discount goes out with layout.layoutNumber = invoiceDiscountLayoutNumber (path #3 / selector #4).
• A collected-invoice draft with no billable discount goes out with invoiceLayoutNumber (path #16 / selector #17).
• A collected-invoice draft with a billable discount goes out with invoiceDiscountLayoutNumber (path #16 / selector #17).

No code changes are required to achieve this — only the two config variables need to be set in the economic module (and validated by the superuser status probe at superuser_system_status_service.php:866).

---

4. Migration plan

Because the selectors already exist, the migration is a configuration rollout plus a small handful of defensive tasks. Files to touch:

4.1 Required for rollout

• services/nginx/app/modules/economic/config/economic_invoice_layout_c.php — confirm invoiceLayoutNumber is configured to TRU-197's "clean" layout.
• services/nginx/app/modules/economic/config/economic_invoice_discount_layout_c.php — set invoiceDiscountLayoutNumber to TRU-197's "discount" layout. (The constructor signature already allows this to be a non-required variable, but the selectors will throw a RuntimeException / Exception if the discount layout is required and the value is 0 or null — so the rollout must include setting this var in every environment.)

4.2 Verify-only (no edits expected)

• services/nginx/app/classes/superuser_system_status_service.php:866 — already lists invoiceLayoutNumber and invoiceDiscountLayoutNumber as required keys for the economic module probe. Confirm the probe treats invoiceDiscountLayoutNumber as required and surfaces a clear error when missing (it currently appears in the required array, which is the correct behavior).
• services/nginx/app/openapi.yaml:18644 — EconomicConfigEntry.variable enum already includes invoiceDiscountLayoutNumber. No change.
• services/nginx/app/tests/Unit/SystemStatus/SuperuserSystemStatusServiceTest.php:893–894 — test fixtures already cover both layout config vars. Confirm values match TRU-197's picks.

4.3 Optional follow-ups (not blocking the rollout)

• Defensive logging in the two selector functions (economic_invoice_draft_mo::resolveLayoutNumber and collected_order_invoices_o::resolveInvoiceLayoutNumber) to log which layout was chosen and why (e.g. [TRU-198] draft {id} uses discount layout (3 discounted lines)). This is useful for post-rollout verification in the e-conomic UI.
• A single, shared selector helper that both paths use, to avoid drift between the two private selectors. Recommended location: services/nginx/app/modules/economic/helpers/economic_invoice_draft.php or a new services/nginx/app/modules/economic/helpers/economic_invoice_layout_resolver.php. Out of scope for the configuration rollout; consider for a follow-up refactor.
• E2E / integration test that:
  1. Creates a single-order draft with at least one discounted line and asserts the resulting draft's layout.layoutNumber equals invoiceDiscountLayoutNumber.
  2. Creates a single-order draft with no discounted lines and asserts invoiceLayoutNumber.
  3. Creates a collected-invoice draft with at least one TotDiscount line and asserts invoiceDiscountLayoutNumber.
  4. Creates a collected-invoice draft with no TotDiscount lines and asserts invoiceLayoutNumber. See tests/Unit/Invoicing/EconomicDraftCustomerOpenApiSpecTest.php and EconomicLegacyDraftPayloadWiringTest.php for the existing patterns.

4.4 Files that explicitly need NO changes

• services/nginx/app/classes/economic_v2_distribution_service.php — distribution reporting, not a draft creator.
• services/nginx/app/modules/economic/helpers/economic_invoice_booked.php — booked-invoice data class.
• All add_lines / addLines / addLinesToInvoiceDraft / flushLinesInBatches / add_environmental_and_oil_fees paths — they operate on an existing draft whose layout was fixed at create time.

---

5. Summary

Metric	Count
Code paths in services/nginx/app/ that create or send draft invoices	22 (2 envelope creators + 6 line-add paths + 14 caller / selector / helper paths)
Paths that currently pick a layout	2 (economic_invoice_draft_mo::createInvoiceDraftExample and collected_order_invoices_o::createInvoiceDraft, both via private selectors)
Paths that need updating for the 2-layout rollout	0 — both selectors already implement the with/without-discount logic
Config variables that drive the 2-layout selection	2 — invoiceLayoutNumber (required, default 1) and invoiceDiscountLayoutNumber (optional, default null). Already wired into economic::$config and the OpenAPI schema.
Files that need editing for the rollout	2 — economic_invoice_layout_c.php and economic_invoice_discount_layout_c.php (config only)

The 2-layout selection is already wired through the backend. The TRU-198 investigation confirms that the rollout reduces to setting the two invoice*LayoutNumber config variables to the layout numbers TRU-197 picks, plus optional defensive logging and an E2E test for verification.