alla-allaos-fullstack/docs/adr/0017-report-foundation.md

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