task-k.2

plans/task-k.2.md

@@ -0,0 +1,549 @@
+# Task K.2: Pipeline Reports
+
+## Objective
+
+Deliver the first production report suite for CRM by providing operational visibility into:
+
+* Leads
+* Enquiries
+* Quotation Conversion
+* Pipeline Aging
+
+using the Report Foundation built in Task K.1.
+
+---
+
+# Background
+
+Completed:
+
+* Lead / Enquiry Ownership Model (D.3)
+* Lead / Enquiry Navigation Separation (D.3.1)
+* Won / Lost Governance (D.4)
+* Dashboard KPI (J)
+* Report Foundation (K.1)
+
+Pipeline lifecycle is frozen as:
+
+```txt
+Lead
+→ Enquiry
+→ Quotation
+→ Closed Won
+→ Closed Lost
+```
+
+Task K.2 builds reporting on top of this lifecycle.
+
+---
+
+# Scope K2.1 Lead Pipeline Report
+
+Add:
+
+```txt
+Lead Pipeline Report
+```
+
+Purpose:
+
+Marketing visibility.
+
+Metrics:
+
+```txt
+Total Leads
+New Leads
+Assigned Leads
+Unassigned Leads
+Converted Leads
+```
+
+Dimensions:
+
+```txt
+Lead Source
+Customer Owner
+Created By
+Branch
+Product Type
+```
+
+Filters:
+
+```txt
+Date Range
+Lead Source
+Branch
+Product Type
+Customer Owner
+```
+
+---
+
+# Scope K2.2 Lead Aging Report
+
+Purpose:
+
+Identify stagnant leads.
+
+Metrics:
+
+```txt
+Lead Count
+Average Aging Days
+Maximum Aging Days
+```
+
+Buckets:
+
+```txt
+0-7 Days
+8-14 Days
+15-30 Days
+31-60 Days
+60+ Days
+```
+
+Drill-down:
+
+```txt
+Lead Number
+Customer
+Assigned User
+Created Date
+Aging Days
+```
+
+---
+
+# Scope K2.3 Enquiry Pipeline Report
+
+Purpose:
+
+Sales pipeline visibility.
+
+Metrics:
+
+```txt
+Open Enquiries
+Converted To Quotation
+Won
+Lost
+```
+
+Dimensions:
+
+```txt
+Salesman
+Branch
+Product Type
+Customer Owner
+```
+
+Filters:
+
+```txt
+Date Range
+Salesman
+Branch
+Product Type
+```
+
+---
+
+# Scope K2.4 Enquiry Aging Report
+
+Purpose:
+
+Identify stalled opportunities.
+
+Metrics:
+
+```txt
+Open Enquiries
+Average Aging
+Maximum Aging
+```
+
+Buckets:
+
+```txt
+0-14 Days
+15-30 Days
+31-60 Days
+60+ Days
+```
+
+Drill-down:
+
+```txt
+Enquiry No
+Customer
+Salesman
+Last Follow-Up
+Aging Days
+```
+
+---
+
+# Scope K2.5 Lead → Enquiry Conversion Report
+
+Purpose:
+
+Marketing effectiveness.
+
+Formula:
+
+```txt
+Converted Enquiries
+/
+Total Leads
+```
+
+Show:
+
+```txt
+Conversion Rate %
+```
+
+Dimensions:
+
+```txt
+Lead Source
+Branch
+Product Type
+Marketing User
+```
+
+---
+
+# Scope K2.6 Enquiry → Quotation Conversion Report
+
+Purpose:
+
+Sales effectiveness.
+
+Formula:
+
+```txt
+Enquiries With Quotation
+/
+Total Enquiries
+```
+
+Dimensions:
+
+```txt
+Salesman
+Branch
+Product Type
+```
+
+---
+
+# Scope K2.7 Pipeline Funnel Report
+
+Add dedicated report.
+
+Stages:
+
+```txt
+Lead
+Enquiry
+Quotation
+Closed Won
+Closed Lost
+```
+
+Show:
+
+```txt
+Count
+Value
+Conversion %
+```
+
+Support:
+
+```txt
+Date Range
+Branch
+Product Type
+Salesman
+```
+
+---
+
+# Scope K2.8 Pipeline Detail Dataset
+
+Create reusable dataset:
+
+```txt
+pipeline-report.dataset.ts
+```
+
+Shared by:
+
+```txt
+Lead Report
+Enquiry Report
+Funnel Report
+```
+
+No duplicate SQL.
+
+---
+
+# Scope K2.9 Report Pages
+
+Add:
+
+```txt
+/dashboard/crm/reports/pipeline
+/dashboard/crm/reports/lead-aging
+/dashboard/crm/reports/enquiry-aging
+```
+
+Use:
+
+```txt
+Report Foundation
+Shared Filters
+Export Foundation
+```
+
+from K.1
+
+---
+
+# Scope K2.10 Export Support
+
+All Pipeline Reports support:
+
+```txt
+CSV
+Excel
+```
+
+Exports must respect:
+
+```txt
+ResolvedReportContext
+CRM Authorization
+Branch Scope
+Product Scope
+Ownership Scope
+```
+
+---
+
+# Scope K2.11 Security
+
+Marketing:
+
+Can see:
+
+```txt
+Lead Reports
+Pipeline Reports
+Outcome Summary
+```
+
+Cannot see:
+
+```txt
+Quotation Pricing
+Revenue Values
+```
+
+---
+
+Sales:
+
+Can see:
+
+```txt
+Own / Scoped Pipeline
+```
+
+---
+
+Managers:
+
+Can see:
+
+```txt
+Team Pipeline
+```
+
+---
+
+CRM Admin:
+
+Can see:
+
+```txt
+Organization-wide Pipeline
+```
+
+---
+
+# Scope K2.12 Audit Logging
+
+Entity:
+
+```txt
+crm_report
+```
+
+Actions:
+
+```txt
+view_pipeline_report
+export_pipeline_report_csv
+export_pipeline_report_excel
+```
+
+Payload:
+
+```txt
+reportCode
+filters
+recordCount
+```
+
+---
+
+# Scope K2.13 Report Definitions
+
+Register:
+
+```txt
+lead_pipeline
+lead_aging
+enquiry_pipeline
+enquiry_aging
+pipeline_funnel
+lead_conversion
+enquiry_conversion
+```
+
+in:
+
+```txt
+crm_report_definitions
+```
+
+---
+
+# Verification
+
+Scenario 1
+
+```txt
+Lead
+→ Assign
+→ Enquiry
+```
+
+Expected:
+
+```txt
+Lead Conversion Report updates
+```
+
+---
+
+Scenario 2
+
+```txt
+Enquiry
+→ Create Quotation
+```
+
+Expected:
+
+```txt
+Quotation Conversion updates
+```
+
+---
+
+Scenario 3
+
+```txt
+Won
+Lost
+```
+
+Expected:
+
+```txt
+Pipeline Funnel updates
+```
+
+---
+
+Scenario 4
+
+Marketing User
+
+Expected:
+
+```txt
+No Revenue Values
+```
+
+---
+
+Scenario 5
+
+Sales User
+
+Expected:
+
+```txt
+Scoped Pipeline Only
+```
+
+---
+
+# Deliverables
+
+1. Lead Pipeline Report
+2. Lead Aging Report
+3. Enquiry Pipeline Report
+4. Enquiry Aging Report
+5. Conversion Reports
+6. Pipeline Funnel Report
+7. Shared Dataset Layer
+8. Export Support
+9. Security Enforcement
+10. Report Registration
+
+---
+
+# Definition of Done
+
+Task K.2 is complete when:
+
+* Lead reports work
+* Enquiry reports work
+* Funnel report works
+* Conversion reports work
+* Aging reports work
+* Export works
+* Security works
+* Audit logging works
+
+Result:
+
+```txt
+Marketing Pipeline Analytics = READY
+Sales Pipeline Analytics = READY
+
+Ready for:
+
+K.3 Outcome Analytics
+```