task-k.2

docs/implementation/task-k2-pipeline-reports.md

@@ -0,0 +1,65 @@
+# Task K.2 Pipeline Reports
+
+## Delivered
+
+- Added production CRM report APIs for:
+  - `GET /api/crm/reports/pipeline`
+  - `GET /api/crm/reports/lead-aging`
+  - `GET /api/crm/reports/enquiry-aging`
+  - `GET /api/crm/reports/export`
+- Added production CRM report pages:
+  - `/dashboard/crm/reports/pipeline`
+  - `/dashboard/crm/reports/lead-aging`
+  - `/dashboard/crm/reports/enquiry-aging`
+- Added shared dataset layer at `src/features/crm/reports/server/datasets/pipeline-report.dataset.ts`
+- Extended report query contracts, React Query keys, and API client services for the new report suite
+- Added report export support for CSV and Excel with scoped security enforcement
+- Added audit logging for:
+  - `view_pipeline_report`
+  - `export_pipeline_report_csv`
+  - `export_pipeline_report_excel`
+- Extended CRM report definitions seed with:
+  - `lead_pipeline`
+  - `lead_aging`
+  - `enquiry_pipeline`
+  - `enquiry_aging`
+  - `pipeline_funnel`
+  - `lead_conversion`
+  - `enquiry_conversion`
+- Added report navigation entries under CRM side menu and report catalog deep links
+
+## Security and Scope
+
+- Report data is filtered by:
+  - organization
+  - branch scope
+  - product scope
+  - own-record scope for `ownershipScope = own`
+- Revenue-like funnel values are hidden when the user does not have quotation pricing visibility
+- Export uses the same filter contract and resolved access context as on-screen reports
+
+## Report Coverage
+
+- Pipeline suite page includes:
+  - Lead Pipeline
+  - Enquiry Pipeline
+  - Lead to Enquiry Conversion
+  - Enquiry to Quotation Conversion
+  - Pipeline Funnel
+- Lead Aging page includes bucket summary and drill-down rows
+- Enquiry Aging page includes bucket summary and drill-down rows with last follow-up visibility
+
+## Verification
+
+- `npx tsc --noEmit`
+  - passed
+- `npx oxlint src/features/crm/reports src/app/api/crm/reports src/app/dashboard/crm/reports src/config/nav-config.ts`
+  - passed
+- `npm run lint`
+  - still fails because of pre-existing repository-wide lint issues outside Task K.2 scope
+
+## Notes
+
+- Lead reporting is derived from the frozen lifecycle stored on `crm_enquiries`
+- Lead conversion is treated as progression beyond `lead` stage or assignment into active sales handling
+- Enquiry to quotation conversion is derived from `crm_quotations.enquiry_id`