541 lines
5.3 KiB
Markdown
541 lines
5.3 KiB
Markdown
# 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
|