Fuchs_Intranet/Fuchs/Docs/Decisions/0016-user-defined-set-structure.md

---
status: Accepted
date: 2026-09-09
applyTo:
  - "Fuchs/code/InvoiceSetStructure.cs"
  - "Fuchs/code/InvoiceSetPricing.cs"
  - "Fuchs/Services/InvoiceDraft*"
  - "Fuchs/Services/IInvoiceDraft*"
  - "Fuchs/code/InvoiceDraftCalculator.cs"
  - "Fuchs/code/FuchsPdf.cs"
  - "Fuchs/js/intranet/modules/fis.inv_sets.js"
  - "Fuchs/js/intranet/modules/fis.inv_shared.js"
  - "Fuchs/Docs/INVOICE_SET_PRICING.md"
supersededBy: ""
---

# 0016 — Set membership is an explicit, user-editable parent link on the cached lines; sets may nest; the server linearises

## Context
Set membership on an invoice draft was purely **implicit**: `fds__prepInvoice` tags every item
that follows a zero-priced `Type = 'Set'` header (until the next such header) with that header's
id (`SetItmId`), and the set-item switch (ADR [0009](0009-block-setprice-modes-are-irreversible-mutations.md),
function 1) sums exactly those tagged lines. Users had no way to correct that grouping — a
trailing item that does not belong, a material line that should sit inside the set, a set that
should contain another set — nor to introduce a set (or a free-text line) that does not exist
in mfr. The product owner asked for a dialog that lets the user define which line belongs to
which set, create new set/text lines, change a line's level, and nest sets, with every change
applied **immediately** to the cached draft and reflected in the editor.

## Decision
1. **The implicit derivation stays as the initial structure.** `fds__prepInvoice`'s
   `SetItmId` window function is unchanged; a freshly opened draft shows exactly the grouping
   it delivered.

2. **Membership is an explicit parent link on every cached line.** Each line in a block's
   `itm` array carries `SetItmId` = the id of the `typ == "set"` line that owns it (null, or a
   self-reference as delivered for headers, = top level). The links form a forest per
   service-request block; the block is the boundary — a line is never assigned to a set of
   another block. `InvoiceSetStructure.ParentOf` normalises the link (self-reference, unknown
   id, non-set target → top level).

3. **Sets may contain sets.** A set's own `SetItmId` names its parent set. Moving a set keeps
   its members attached — they simply sit one level deeper/shallower. The depth of every line is
   published as `lvl` (co shape) / `level` (items contract) and mirrored onto `items[].setId`,
   so the PDF and the editor read one structure.

4. **Four new backend-authoritative deltas** (`inv/dpatch`, handled by
   `InvoiceDraftSetStructureDeltas` → pure `InvoiceSetStructure`):
   - `set.assign` (Ref = item, Value `{ parent }`; `""` = top level) — drop a line onto a set
     (it becomes the set's **last** member) or pull it out (placed right after the subtree it
     came from). Rejected as a no-op: unknown item, target not a set of the same block, target
     is the item itself or one of its descendants (cycle), parent unchanged.
   - `set.level` (Ref = item, Value ±1) — indent = join the nearest **preceding sibling set**
     as its last member; outdent = join the grandparent right after the former parent's
     subtree. No-op when no such move exists.
   - `set.create` (Ref = block, Value `{ typ: "set" | "text", title, parent }`) — a new
     zero-priced set header (convertible later via the item switch) or a free-text line, as the
     last member of `parent` / end of the block. Both line shapes are written; the title is
     HTML-encoded for the text line.
   - `set.move` (Ref = item, Value ±1 or `{ anchor, where: "before" | "after" }`) — reorder:
     one step up/down among the line's siblings, or become the anchor's sibling placed before
     it / after its subtree (drag between rows). The line's own subtree travels with it, so a
     set can be reordered folded or unfolded alike. Rejected: anchor inside the item's subtree.

5. **The server linearises after every structural change**: the block's lines are reordered
   depth-first (each set immediately followed by its members, recursively; siblings keep their
   relative order), levels are recomputed and the `items` contract is mirrored (order,
   `setId`, `level`). `InvoiceSetPricing.Build` is therefore **order-preserving**: it no longer
   regroups members next to their header at render time; a line is governed by its nearest
   converted ancestor (blank in SetPrice, dropped in SetOnly). Editor and PDF print the same
   sequence and the same per-level indent (ADR 0008).

6. **The set-item switch sums transitive descendants.** `item.setprice` on a set now sums and
   nulls the header's whole subtree: an unconverted nested set contributes its members'
   prices, an already-converted nested set contributes its own set price — so converting inner
   then outer, or outer directly, both conserve the total and count nothing twice.

7. **The dialog is a view, not a model.** `$inv.sets` (fis.inv_sets.js) renders
   `state.req[].itm` (pos, type, quantity, title, indent, ▲▼ order and ◀▶ level buttons, fold
   toggles, per-block create bar), posts one delta per action and re-renders from the next
   `dstate`. Folding (`collapsed` set ids) is browser-only view state. The dialog performs no
   restructuring, ordering or numbering itself (ADR 0006).

## Consequences
- `Refresh` runs `InvoiceSetStructure.RecomputeLevels` on every patch, so a `block.replace`
  posted by the editor (rows carry `SetItmId` from `rrw`) keeps the user-defined structure; the
  editor never has to re-derive it. Levels are rendered as an indent class (`lvl1…`) in the
  editor and a per-level left indent in the PDF.
- `invSumUpdate` now tags a nested **set** with its `setId` too (previously only non-set
  members were tagged), and `BuildSetDisplay` blanks the whole subtree of a converted set —
  including nested headers, which stay emphasised.
- Structural deltas never change a value: totals, VAT splits and `NetByBlock` are unaffected;
  only positions are renumbered along the new order.
- Row drag in the editor (the existing `Sortable`) reorders rows without touching parent links;
  a member dragged away from its set keeps its membership and indent. The structure dialog is
  the place to change membership.
- Tests: `InvoiceSetStructureTests` (pure forest logic), `InvoiceDraftServiceTests` (deltas,
  history, nested set price, state), `InvoiceSetPricingTests` (nesting, order preservation).

## Alternatives considered
- **Derive membership from row order (everything after a set until the next set)** as the
  live model: rejected — that is exactly what the user cannot correct, and it cannot express
  nesting or an item that follows a set but does not belong to it.
- **A separate structure table (tree) beside the lines**: rejected — a parent link per line
  keeps the single `itm`/`items` shape the calculator, the PDF, the persistence path and the
  editor already consume, so nothing else had to be re-shaped.
- **Render-time regrouping (keep `Build` moving members next to their header)**: rejected —
  with explicit links the server can guarantee contiguity by linearising once, and an
  order-preserving `Build` is the only way the editor and the PDF are guaranteed to show the
  same sequence.
- **Client-side restructuring with a full block re-post**: rejected per ADR 0006/0008 — one
  delta per action, the server owns the mutation, the browser mirrors.