# 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