task-j1

plans/task-j.md

@@ -0,0 +1,540 @@
+# Task J: CRM Dashboard KPI & Sales Analytics
+
+## Background
+
+Task J.0 KPI Definition Freeze completed.
+
+Task D.2.1 Revenue Attribution and Party Governance completed.
+
+Dashboard implementation MUST follow:
+
+```txt
+Lead Definition
+Opportunity Definition
+Revenue Attribution Rules
+Project Party Reporting Rules
+```
+
+No dashboard logic may redefine KPI formulas.
+
+---
+
+# Must Read
+
+```txt
+Layout.md
+
+.agents/skills/kiranism-shadcn-dashboard
+
+docs/adr/0010-revenue-attribution-governance.md
+
+docs/implementation/technical-debt.md
+
+src/features/crm/reporting/server/**
+src/features/crm/customers/**
+src/features/crm/enquiries/**
+src/features/crm/quotations/**
+src/features/foundation/approval/**
+src/features/foundation/document-artifact/**
+src/db/schema.ts
+```
+
+---
+
+# Goal
+
+Replace CRM placeholder dashboard with a production KPI dashboard powered by real CRM data.
+
+Route:
+
+```txt
+/ dashboard / crm
+```
+
+No mock data allowed.
+
+---
+
+# Scope J1: Dashboard Foundation
+
+Create:
+
+```txt
+src/features/crm/dashboard/**
+```
+
+Recommended structure:
+
+```txt
+api/
+  types.ts
+  service.ts
+  queries.ts
+
+server/
+  service.ts
+
+components/
+  dashboard-summary-cards.tsx
+  dashboard-funnel.tsx
+  dashboard-sales-ranking.tsx
+  dashboard-followups.tsx
+  dashboard-approval-metrics.tsx
+  dashboard-revenue-cards.tsx
+  dashboard-hot-projects.tsx
+```
+
+Use:
+
+```txt
+Server Components First
+React Query
+PageContainer
+Bento Grid Layout
+```
+
+Follow:
+
+```txt
+Layout.md
+kiranism-shadcn-dashboard
+```
+
+---
+
+# Scope J2: Executive Summary Cards
+
+Cards:
+
+## Lead
+
+```txt
+Lead Count
+New Leads
+Unassigned Leads
+Lead Aging Average
+```
+
+Formula:
+
+```txt
+pipelineStage = lead
+```
+
+---
+
+## Opportunity
+
+```txt
+Opportunity Count
+Open Opportunities
+Hot Opportunities
+Opportunity Value
+```
+
+Formula:
+
+```txt
+pipelineStage = opportunity
+```
+
+Source:
+
+```txt
+crm_enquiries.estimatedValue
+```
+
+---
+
+## Quotation
+
+```txt
+Draft Quotations
+Pending Approval
+Approved Quotations
+Sent Quotations
+```
+
+---
+
+## Revenue
+
+```txt
+Quotation Value
+Won Value
+Lost Value
+```
+
+Use frozen revenue rules.
+
+---
+
+# Scope J3: Sales Pipeline Funnel
+
+Create funnel widget:
+
+```txt
+Lead
+↓
+Opportunity
+↓
+Quotation
+↓
+Pending Approval
+↓
+Approved
+↓
+Closed Won
+```
+
+Display:
+
+```txt
+Count
+Value
+Conversion %
+```
+
+Formulas must follow Task J.0.
+
+---
+
+# Scope J4: Revenue Analytics
+
+Use:
+
+```txt
+src/features/crm/reporting/server/**
+```
+
+Cards:
+
+```txt
+Top End Customers
+Top Billing Customers
+Top Contractors
+Top Consultants
+```
+
+Metrics:
+
+```txt
+Revenue
+Quotation Count
+Won Revenue
+```
+
+Revenue Attribution:
+
+```txt
+End Customer
+Fallback Billing Customer
+```
+
+must follow ADR.
+
+---
+
+# Scope J5: Sales Ranking
+
+Create table:
+
+Columns:
+
+```txt
+Sales Person
+Lead Count
+Opportunity Count
+Quotation Count
+Approved Quotations
+Won Revenue
+Conversion Rate
+```
+
+Ownership:
+
+```txt
+Lead / Opportunity
+→ assignedToUserId
+
+Quotation
+→ salesmanId
+```
+
+Use KPI Freeze definitions.
+
+---
+
+# Scope J6: Follow-up Dashboard
+
+Source:
+
+```txt
+crm_enquiry_followups
+crm_quotation_followups
+```
+
+Cards:
+
+```txt
+Due Today
+Due This Week
+Overdue
+Completed
+```
+
+Table:
+
+```txt
+Upcoming Follow Ups
+```
+
+Display:
+
+```txt
+Date
+Customer
+Opportunity
+Assigned Sales
+```
+
+---
+
+# Scope J7: Approval Analytics
+
+Source:
+
+```txt
+approval module
+```
+
+Cards:
+
+```txt
+Pending Approvals
+Approved Today
+Rejected Today
+Returned Today
+```
+
+Metrics:
+
+```txt
+Average Approval Time
+```
+
+Table:
+
+```txt
+My Pending Approvals
+```
+
+---
+
+# Scope J8: Hot Projects
+
+Source:
+
+```txt
+crm_enquiries.isHotProject
+crm_quotations.isHotProject
+```
+
+Widget:
+
+```txt
+Top Hot Opportunities
+```
+
+Display:
+
+```txt
+Project
+Customer
+Value
+Assigned Sales
+Probability
+```
+
+---
+
+# Scope J9: Global Filters
+
+Add filters:
+
+```txt
+Date Range
+Branch
+Sales Person
+Project Party Role
+Product Type
+```
+
+Use:
+
+```txt
+nuqs
+```
+
+Rules:
+
+```txt
+organization scoped
+server query aware
+```
+
+---
+
+# Scope J10: Permissions
+
+Add:
+
+```txt
+crm.dashboard.read
+crm.dashboard.export
+```
+
+Rules:
+
+```txt
+super_admin
+organization_admin
+sales_manager
+```
+
+full access
+
+sales:
+
+```txt
+own scope only (future-ready)
+```
+
+For now:
+
+```txt
+organization scope allowed
+```
+
+Document as technical debt.
+
+---
+
+# Scope J11: Export
+
+Support:
+
+```txt
+CSV
+Excel
+```
+
+Exports:
+
+```txt
+Sales Ranking
+Revenue Analytics
+Pipeline Funnel
+```
+
+Use current export patterns.
+
+Do NOT generate PDF dashboards.
+
+---
+
+# Scope J12: Performance Rules
+
+Required:
+
+```txt
+Aggregate queries
+Server-side calculations
+No N+1 queries
+Pagination for tables
+Reusable KPI service layer
+```
+
+Dashboard should remain fast with:
+
+```txt
+100k+
+quotations
+enquiries
+customers
+```
+
+---
+
+# Scope J13: Audit
+
+Audit:
+
+```txt
+crm_dashboard_export
+```
+
+Actions:
+
+```txt
+export_csv
+export_excel
+```
+
+Reading dashboard does not require audit.
+
+---
+
+# Explicit Non-Scope
+
+Do NOT implement:
+
+```txt
+AI Forecasting
+Predictive Sales
+Power BI
+Data Warehouse
+Notification Center
+Report Builder
+```
+
+---
+
+# Output
+
+1. Files Added
+2. Files Modified
+3. KPI Widgets Added
+4. Revenue Analytics Added
+5. Sales Ranking Added
+6. Approval Analytics Added
+7. Export Added
+8. Permissions Added
+9. Remaining Risks
+10. Task K Readiness
+
+---
+
+# Definition of Done
+
+✔ Dashboard uses real data
+
+✔ KPI summary cards complete
+
+✔ Revenue analytics complete
+
+✔ Sales ranking complete
+
+✔ Approval analytics complete
+
+✔ Follow-up analytics complete
+
+✔ Pipeline funnel complete
+
+✔ Filters working
+
+✔ Export working
+
+✔ No mock data
+
+✔ Ready for Task K Report Center