docs(economic): map draft-invoice layout code paths (TRU-198) (#395)

## Summary

Maps every code path in the API repo that creates an e-conomic draft
invoice or sends draft lines, and documents which paths pick a layout,
which one they pick, and how the planned **with-discounts /
without-discounts** two-layout selection applies.

**Key finding:** the two envelope creators already implement a
discount-aware selector. No code change is required for the TRU-197
rollout — only the two `invoice*LayoutNumber` config variables need to
be set in the `economic` module.

## Findings at a glance

- **22** code paths in `services/nginx/app/` create or send draft
invoices (2 envelope creators + 6 line-add paths + 14
caller/selector/helper paths)
- **2** paths currently pick a layout — both already discount-aware
- **0** paths need updating for the 2-layout rollout
- **2** config variables drive the selection: `invoiceLayoutNumber` and
`invoiceDiscountLayoutNumber` (already wired into `economic::$config`
and the OpenAPI schema)

## The two selectors

1. `economic_invoice_draft_mo::resolveLayoutNumber()` at
`services/nginx/app/modules/economic/invoices/draft/economic_invoice_draft_mo.php:115`
— used by `createInvoiceDraftExample()` for the single-order draft flow.
2. `collected_order_invoices_o::resolveInvoiceLayoutNumber()` at
`services/nginx/app/objects/collected_order_invoices_o.php:673` — used
by `createInvoiceDraft()` for the collected-invoice flow.

Both return `invoice_discount_layout` if any item has a non-zero
discount, otherwise `invoice_layout`. They throw if the discount layout
is required and `invoiceDiscountLayoutNumber` is unconfigured.

## Document

`documentation/economic/layout-selection-flow.md` — full inventory
table, current/desired state, and migration plan.

## Related

- TRU-197 — `documentation/economic/invoice-template-audit.md`
- TRU-193 — `documentation/economic/export-field-audit.md`
- PR #391 — `economic_export_sanitizer`

Refs: TRU-198

---------

Co-authored-by: openhands <openhands@all-hands.dev>
Co-authored-by: OpenClaw <openclaw@copenhagentruckwash.io>
Co-authored-by: TRU-198 Subagent <subagent@openhands.dev>

services/nginx/app/classes/economic_layout_selector.php

@@ -0,0 +1,92 @@
+<?php
+
+namespace classes;
+
+/**
+ * Centralized selection of e-conomic invoice layout numbers.
+ *
+ * This class is the **skeleton** introduced by TRU-197. It exposes the two
+ * layout numbers that the backend should use for the two invoice variants:
+ *
+ *   - `LAYOUT_WITHOUT_DISCOUNTS`  — clean invoice, no discount clutter
+ *   - `LAYOUT_WITH_DISCOUNTS`     — invoice with itemized discount line(s)
+ *
+ * The constants below are placeholders for the layout numbers that the
+ * e-conomic account admin must pick in e-conomic (Settings → Design and
+ * Layouts) and write into the module-config DB variables
+ * `invoiceLayoutNumber` and `invoiceDiscountLayoutNumber`. The numbers
+ * themselves are intentionally left as `0` in this skeleton — they are
+ * resolved at runtime from the module-config variables by the two existing
+ * call sites:
+ *
+ *   - `services/nginx/app/modules/economic/invoices/draft/economic_invoice_draft_mo.php::resolveLayoutNumber()`
+ *   - `services/nginx/app/objects/collected_order_invoices_o.php::resolveInvoiceLayoutNumber()`
+ *
+ * Wiring those call sites to read from this selector (instead of from the
+ * module-config variables directly) is intentionally **out of scope** for
+ * TRU-197. See `documentation/economic/invoice-template-audit.md` for the
+ * full audit and follow-up plan.
+ *
+ * Constants in this class are the *single source of truth* for the
+ * env-var-style aliases:
+ *
+ *   - `LAYOUT_WITHOUT_DISCOUNTS`  ⇄  `ECONOMIC_LAYOUT_WITHOUT_DISCOUNTS`
+ *   - `LAYOUT_WITH_DISCOUNTS`     ⇄  `ECONOMIC_LAYOUT_WITH_DISCOUNTS`
+ */
+class economic_layout_selector
+{
+    /**
+     * Layout number for invoices WITHOUT itemized discount lines.
+     *
+     * Intent: a clean invoice — no "Rabat" line, no discount column, just
+     * the line items and totals.
+     *
+     * @var int
+     */
+    public const LAYOUT_WITHOUT_DISCOUNTS = 0;
+
+    /**
+     * Layout number for invoices WITH itemized discount lines.
+     *
+     * Intent: an invoice that visibly itemizes the negative `Rabat`
+     * (product `TotDiscount`) line so the customer can see the discount
+     * broken out instead of folded into per-product `discountPercentage`.
+     *
+     * @var int
+     */
+    public const LAYOUT_WITH_DISCOUNTS = 0;
+
+    /**
+     * Module-config variable name for the without-discounts layout.
+     *
+     * @var string
+     */
+    public const CONFIG_VAR_WITHOUT_DISCOUNTS = 'invoiceLayoutNumber';
+
+    /**
+     * Module-config variable name for the with-discounts layout.
+     *
+     * @var string
+     */
+    public const CONFIG_VAR_WITH_DISCOUNTS = 'invoiceDiscountLayoutNumber';
+
+    /**
+     * Friendly alias for `LAYOUT_WITHOUT_DISCOUNTS` (env-var-style name).
+     *
+     * @return string
+     */
+    public static function nameWithoutDiscounts(): string
+    {
+        return 'ECONOMIC_LAYOUT_WITHOUT_DISCOUNTS';
+    }
+
+    /**
+     * Friendly alias for `LAYOUT_WITH_DISCOUNTS` (env-var-style name).
+     *
+     * @return string
+     */
+    public static function nameWithDiscounts(): string
+    {
+        return 'ECONOMIC_LAYOUT_WITH_DISCOUNTS';
+    }
+}