alla-allaos-fullstack/docs/implementation/task-k2-pipeline-reports.md

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