task-k.1

docs/adr/0017-report-foundation.md

@@ -0,0 +1,48 @@
+# ADR 0017: CRM Report Foundation
+
+## Status
+
+Accepted
+
+## Context
+
+CRM now has stable foundations for:
+
+- access control and scope resolution
+- customer ownership and contact sharing
+- lead and enquiry lifecycle
+- won/lost governance
+- revenue attribution
+- dashboard KPI
+
+Future report modules need one shared architecture so they do not re-implement:
+
+- report discovery
+- filter contracts
+- export helpers
+- access resolution
+- audit logging
+
+## Decision
+
+We introduce a dedicated report foundation under `src/features/crm/reports/`.
+
+The foundation includes:
+
+- `crm_report_definitions` as the report registry
+- `crm_report_category` master options for grouping and future permissions
+- shared filter metadata endpoint
+- `ResolvedReportContext` for organization, scope, and permission resolution
+- `resolveCrmAccess()` as the common context adapter for reports
+- dataset and builder layers for report queries
+- shared CSV/XLS export helpers
+- `crm_report` audit entries for `view`, `export_csv`, and `export_excel`
+
+Reports must not query the database directly from UI routes. Route handlers call the report server layer instead.
+
+## Consequences
+
+- K.2-K.7 can add business reports without redefining report plumbing
+- scope and permission enforcement stays aligned with CRM authorization work from Task L
+- export behavior becomes reusable instead of dashboard-specific
+- report navigation can be driven from the seeded registry and category metadata