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

docs/implementation/task-k1-report-foundation.md

@@ -0,0 +1,39 @@
+# Task K.1 Implementation Summary
+
+## Completed
+
+- added `crm_report_definitions` schema and migration
+- seeded `crm_report_category` master options
+- seeded system report definitions:
+  - `lead_pipeline`
+  - `enquiry_pipeline`
+  - `sales_performance`
+  - `lost_analysis`
+  - `revenue_by_customer`
+- added permissions:
+  - `crm.report.read`
+  - `crm.report.export`
+- created `src/features/crm/reports/` foundation with:
+  - API contracts
+  - shared query options
+  - `ResolvedReportContext`
+  - `resolveCrmAccess()`
+  - dataset layer
+  - builder layer
+  - shared filter metadata builder
+  - export helpers
+- added report discovery APIs:
+  - `GET /api/crm/reports`
+  - `GET /api/crm/reports/catalog`
+  - `GET /api/crm/reports/filters`
+- added audit logging for report foundation reads
+- added CRM Reports landing page and sidebar navigation entry
+
+## Verification
+
+- `npm exec tsc --noEmit`
+
+## Notes
+
+- this task creates the shared report platform only; it does not implement business report execution pages yet
+- export helpers are centralized and ready for future report-specific export routes