[Reports] Epic: Module Reports

[nielsdrost7]

Parent epic for all reporting features: income vs expenses, VAT reports, tax reports, profit/loss reports, invoice group reports, and report builder. V1 parity required before launch.

---

Three tracks

Track	Scope	Issues	Notes
A — Report Builder	Band-based designer (header / group header / details / group footer / footer) with code-defined mason Bricks; configs stored as files in storage/, deliver-and-clone model; PDF generation for invoices & quotes consumes these templates	Master story #130 → sub-tasks #521, #528 (Phase 1), #523, #519, #525 (Phase 2); then per-document template selection #411 (Phase 4); page-break support (#95) lands inside Phase 3	Status 2026-07-13: Phases 0–4 implemented on feature/130-report-builder (PR) — see #130 for as-built notes
B — Tabular reports	v1-parity report pages: payment history, invoicing history, invoiced amount by client, sales by date, invoices per client — Filament pages + CSV export	#145	Status 2026-07-13: implemented (PR)
C — Small items	Email template variable for the invoicing contact	#363	Status 2026-07-13: implemented (PR)

---

Phased roadmap (Track A detail)

Phase	Work	Issue(s)	Depends on	Acceptance criteria
0 ✅	Merge PR #575 (dompdf driver + invoice blade)	—	—	PR #575 merged to develop
1 ✅	Pure-file storage service, manifest/bands schema, reports:sync-system command, brick registry harvest	#521, #528	—	Storage round-trip test passes; clone copies folder + rewrites manifest; ../ in a slug is rejected; Company A cannot load Company B's template; sync command is idempotent
2 ✅	Builder UI: list/clone pages, five-band builder page, band-filtered bricks, brick config slide-over, move-to-band action	#519, #523, #525	Phase 1	Builder page loads per band; save persists bands.json; band filtering excludes disallowed bricks; system templates are not editable or deletable
3 ✅	ReportRenderer, default invoice/quote system templates, page-break support	#130 (master), #95 (portion)	Phases 0, 1	Renderer output contains HTML for configured bricks and omits toggled-off fields; PDF bytes are non-empty via the dompdf driver; page-break-inside: avoid present when band "keep together" is on; golden-file HTML snapshot matches for invoice/default
4 ✅	Per-document template selection	#411	Phase 3	Per #411's existing five test scenarios (adapted to disk-based slug resolution)
5 ✅ (parallel)	Tabular reports (payment history, sales by date, invoiced-by-client, etc.)	#145	—	Per #145's existing three Livewire test scenarios (naui95's spec, unchanged)
6 ✅ (parallel)	Invoicing-contact variables in email templates	#363	—	Scoped test criteria per #363, independent of the rendering pipeline

Architecture, storage layout, and security constraints are specified in #130. Key decisions (2026-07-04): pure-file storage, no DB tables; bricks defined only in code; one Mason canvas per band; fresh branch feature/130-report-builder, harvesting the old feature/145-report-builder branch (PR #532 closed, branch kept for harvesting).

[nielsdrost7]

SMART Plan — Reports module epic status

Context/Epic: Core

This is an epic/tracking issue, not a single feature — it aggregates the sub-issues below. The Measurable section tracks sub-issue completion rather than fabricating tests for the epic itself.

Specific

Track delivery of the Reports module across three tracks: A — Report Builder (band-based designer with code-defined "Bricks", file-based persistence, PDF rendering), B — Tabular reports (v1-parity report pages), C — Small items (email template variable). This epic's own body marks all three tracks "implemented" as of 2026-07-13, each pointing at a specific PR (#608, #609, #610). Grounded against develop today, none of those PRs are merged — gh pr view confirms #608, #609, and #610 are all still OPEN. What actually exists on develop is orphaned scaffolding only: Modules\Core\Enums\ReportBand/ReportDataSource, Modules\Core\Services\ReportFieldService, and unwired blade-only "brick" views — no ReportRenderer, ReportBricksCollection, ReportTemplateStorage, or any Reports Filament pages exist anywhere in the module. This epic should not be treated as done until those PRs are actually reviewed and merged.

Measurable

• Track A — Report Builder ([Reports]: Report Builder — bands + bricks #130 master; Report Builder: code-defined Bricks (fields + config schema) #521, Report Builder: file-based persistence (manifest + bands JSON), clone + sync-system #528 Phase 1; Report Builder: drag & drop bricks within band canvases #519, Report Builder: five band canvases (header, group header, details, group footer, footer) #523, Report Builder: move bricks between bands (move-to-band action) #525 Phase 2) — designed and claimed-implemented on branch feature/130-report-builder, but PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 is open/unmerged; nothing present on develop.
• [Reports]: Custom field support in Report Builder #133 — Custom field support in Report Builder — not started; depends on the builder existing at all.
• Report Builder: group-band repetition (group_by, per-group totals) #597 — Group-band repetition — not started; depends on [Reports]: Report Builder — bands + bricks #130/PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 landing (needs ReportRenderer, which doesn't exist on develop).
• Report Builder: per-brick width editing in the builder UI #598 — Per-brick width editing in the builder UI — not started; same dependency.
• Report Builder: band keep-together toggle in the builder UI #599 — Band keep-together toggle in the builder UI — not started; same dependency.
• Track B — Tabular reports ([Reports]: Reports module — v1 feature parity #145) — designed and claimed-implemented, but PR [IP-145]: tabular reports — five company-panel report pages #609 is open/unmerged; nothing present on develop.
• Track C — Email template invoicing-contact variable ([Core]: Add template variable for Contact (Invoicing) in Email Templates #363) — designed and claimed-implemented, but PR [IP-363]: invoicing-contact variables in email templates #610 is open/unmerged.
• [Reports]: Report — Net Profit made in a financial year #72 — Net Profit report for a financial year — not started; no "financial year" concept exists anywhere in the codebase yet (no fiscal-year-start setting on Company).
• [Invoices]: Ability to select from multiple invoice templates #411 — Per-document template selection (Phase 4) — depends on [Reports]: Report Builder — bands + bricks #130's renderer landing first.

Definition of done for this epic: PRs #608/#609/#610 are reviewed and either merged or explicitly abandoned (in which case their scope needs re-estimating from the current bare state), and #72/#133/#597/#598/#599/#411 are closed against whatever lands on develop.

Achievable

1. The immediate blocker for almost everything in this epic is a code-review decision on PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 (Report Builder) and PR [IP-145]: tabular reports — five company-panel report pages #609 (tabular reports) — both are large, both claim full test coverage on their branch, and neither has been checked against develop's current baseline.
2. Report Builder: code-defined Bricks (fields + config schema) #521 and Report Builder: file-based persistence (manifest + bands JSON), clone + sync-system #528 (Phase 1: brick registry, file persistence) have no code dependencies on each other and, if PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 doesn't land, would be the correct starting point for a rebuild.
3. Report Builder: drag & drop bricks within band canvases #519, Report Builder: five band canvases (header, group header, details, group footer, footer) #523, Report Builder: move bricks between bands (move-to-band action) #525 (Phase 2) all depend on Phase 1 landing first — this was true in the original roadmap and remains true regardless of the PR's fate.
4. Report Builder: group-band repetition (group_by, per-group totals) #597, Report Builder: per-brick width editing in the builder UI #598, Report Builder: band keep-together toggle in the builder UI #599 are explicitly "hanging items" from PR [IP-130]: Report Builder — bands + bricks (IP-130, Phases 1-4 + Browsershot driver) #608 and cannot start until that PR (or an equivalent rebuild) lands.
5. [Reports]: Reports module — v1 feature parity #145 (Track B) and [Reports]: Report — Net Profit made in a financial year #72 (net profit) have no dependency on the Report Builder and can proceed independently of tracks A/C.

Relevant

Reporting is required for v1 parity and is currently the largest single gap between the two versions; three substantial PRs already exist claiming to close most of it, but until they're merged this epic's real completion state on develop is close to zero.

Time-bound

No fixed date — re-review at each sprint boundary; the highest-leverage next step is scheduling review time for PR #608 and #609, not new development.