Report Builder: group-band repetition (group_by, per-group totals)

[nielsdrost7]

Parent: #130 (Report Builder) · Hanging item from #608

Story
As a company admin, I want the Group Header / Group Footer bands to repeat per group of line items (e.g. per project, per product category), so long invoices read as grouped sections with per-group subtotals instead of one flat item table.

Current state (as of PR #608)
Modules/Core/Services/ReportRenderer.php renders every band exactly once, in ReportBand::ordered() order. The group_header and group_footer bands exist in the five-band model and are editable in the builder, but nothing ever repeats them — grouping is not configurable anywhere.

Spec to settle in this issue

• A group_by setting — either in the template manifest or as per-details-band config (decide: manifest band_options.details.group_by fits the existing band-options pattern used by keep_together).
• The whitelist of valid group keys: which item attributes may be grouped on (candidates from ReportDataMapper::itemData(): none today — grouping keys like project_id/category must first be added to the item data array; enumerate them explicitly, never accept arbitrary strings).
• Per-group data exposure: Group Header bricks receive the current group key/label; Group Footer bricks receive per-group totals (subtotal, tax, total computed over the group's items) alongside the document-level totals.
• Renderer loop: for each group — group_header bands → details (group's items only) → group_footer bands; header/footer bands stay document-level.

Acceptance criteria

• bands.json/manifest carry an optional, enum-validated group_by (unknown keys rejected on load, same pattern as ReportTemplateStorage::sanitizeBands())
• With group_by unset, rendering is byte-identical to today (golden fixtures unchanged)
• With group_by set, Group Header/Footer bands repeat per group and the details band iterates only that group's items
• Group Footer bricks can render per-group totals; document totals remain correct
• PHPUnit: renderer unit tests for grouped vs ungrouped output; golden fixture for one grouped template

[nielsdrost7]

SMART Plan — Report Builder: group-band repetition (group_by, per-group totals)

Context/Epic: Core (Reports) — hanging follow-up from PR #608, parent #130

Specific

Group Header/Footer bands should repeat per group of line items (e.g. per project or category) instead of rendering once. Current state on develop: this depends entirely on ReportRenderer, which does not exist anywhere in the codebase (confirmed by grep across Modules and Tests) — so there is nothing on develop to add grouping logic to yet. The issue is well-specified (proposing band_options.details.group_by in the manifest, mirroring the keep_together pattern from #599) but is explicitly framed as "settle the spec in this issue" — the whitelist of valid group keys (candidate: project_id, category) doesn't exist on any item-data mapper today, since no such mapper exists either.

Measurable

• With group_by unset, rendering is unchanged (regression safety once a renderer exists).
  • PHPUnit: it_renders_identically_to_ungrouped_output_when_group_by_is_unset()
• With group_by set, group_header/footer bands repeat once per group and details shows only that group's items.
  • PHPUnit: it_repeats_group_header_and_footer_bands_once_per_group()
• Group footer totals are computed per-group and document totals remain correct.
  • PHPUnit: it_computes_correct_per_group_and_document_level_totals()
• An unwhitelisted group_by key is rejected on load.
  • PHPUnit: it_rejects_an_unwhitelisted_group_by_key_on_load()

Achievable

1. Hard-blocked on [Reports]: Report Builder — bands + bricks #130/PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 landing — there is no ReportRenderer to extend yet.
2. Once unblocked, first enumerate the whitelist of valid group keys — this issue itself flags that as unresolved, and it requires adding grouping-capable fields (e.g. project_id, category) to whatever item-data mapper Phase 3 introduces, since none exists on develop today.
3. Golden-fixture (HTML snapshot) testing, as this issue proposes, implies snapshot tooling that also doesn't exist on develop yet — it would need to be introduced alongside Phase 3, not invented fresh here.

Relevant

Long invoices/quotes with many line items are hard to read as a flat table; per-group subtotals are a common v1-parity expectation for anything beyond a handful of items.

Time-bound

Sprint 8 — blocked until #130 lands; the valid group-key whitelist needs settling first regardless.