alla-allaos-fullstack/plans/task-j.md

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:

Lead Definition
Opportunity Definition
Revenue Attribution Rules
Project Party Reporting Rules

No dashboard logic may redefine KPI formulas.

---

Must Read

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:

/ dashboard / crm

No mock data allowed.

---

Scope J1: Dashboard Foundation

Create:

src/features/crm/dashboard/**

Recommended structure:

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:

Server Components First
React Query
PageContainer
Bento Grid Layout

Follow:

Layout.md
kiranism-shadcn-dashboard

---

Scope J2: Executive Summary Cards

Cards:

Lead

Lead Count
New Leads
Unassigned Leads
Lead Aging Average

Formula:

pipelineStage = lead

---

Opportunity

Opportunity Count
Open Opportunities
Hot Opportunities
Opportunity Value

Formula:

pipelineStage = opportunity

Source:

crm_enquiries.estimatedValue

---

Quotation

Draft Quotations
Pending Approval
Approved Quotations
Sent Quotations

---

Revenue

Quotation Value
Won Value
Lost Value

Use frozen revenue rules.

---

Scope J3: Sales Pipeline Funnel

Create funnel widget:

Lead
↓
Opportunity
↓
Quotation
↓
Pending Approval
↓
Approved
↓
Closed Won

Display:

Count
Value
Conversion %

Formulas must follow Task J.0.

---

Scope J4: Revenue Analytics

Use:

src/features/crm/reporting/server/**

Cards:

Top End Customers
Top Billing Customers
Top Contractors
Top Consultants

Metrics:

Revenue
Quotation Count
Won Revenue

Revenue Attribution:

End Customer
Fallback Billing Customer

must follow ADR.

---

Scope J5: Sales Ranking

Create table:

Columns:

Sales Person
Lead Count
Opportunity Count
Quotation Count
Approved Quotations
Won Revenue
Conversion Rate

Ownership:

Lead / Opportunity
→ assignedToUserId

Quotation
→ salesmanId

Use KPI Freeze definitions.

---

Scope J6: Follow-up Dashboard

Source:

crm_enquiry_followups
crm_quotation_followups

Cards:

Due Today
Due This Week
Overdue
Completed

Table:

Upcoming Follow Ups

Display:

Date
Customer
Opportunity
Assigned Sales

---

Scope J7: Approval Analytics

Source:

approval module

Cards:

Pending Approvals
Approved Today
Rejected Today
Returned Today

Metrics:

Average Approval Time

Table:

My Pending Approvals

---

Scope J8: Hot Projects

Source:

crm_enquiries.isHotProject
crm_quotations.isHotProject

Widget:

Top Hot Opportunities

Display:

Project
Customer
Value
Assigned Sales
Probability

---

Scope J9: Global Filters

Add filters:

Date Range
Branch
Sales Person
Project Party Role
Product Type

Use:

nuqs

Rules:

organization scoped
server query aware

---

Scope J10: Permissions

Add:

crm.dashboard.read
crm.dashboard.export

Rules:

super_admin
organization_admin
sales_manager

full access

sales:

own scope only (future-ready)

For now:

organization scope allowed

Document as technical debt.

---

Scope J11: Export

Support:

CSV
Excel

Exports:

Sales Ranking
Revenue Analytics
Pipeline Funnel

Use current export patterns.

Do NOT generate PDF dashboards.

---

Scope J12: Performance Rules

Required:

Aggregate queries
Server-side calculations
No N+1 queries
Pagination for tables
Reusable KPI service layer

Dashboard should remain fast with:

100k+
quotations
enquiries
customers

---

Scope J13: Audit

Audit:

crm_dashboard_export

Actions:

export_csv
export_excel

Reading dashboard does not require audit.

---

Explicit Non-Scope

Do NOT implement:

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