# 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