task-j1

docs/implementation/task-j-crm-dashboard-kpi.md

@@ -0,0 +1,74 @@
+# Task J: CRM Dashboard KPI and Sales Analytics
+
+## Files added
+
+- `src/features/crm/dashboard/api/types.ts`
+- `src/features/crm/dashboard/api/service.ts`
+- `src/features/crm/dashboard/api/queries.ts`
+- `src/features/crm/dashboard/server/service.ts`
+- `src/features/crm/dashboard/components/crm-dashboard.tsx`
+- `src/features/crm/dashboard/components/dashboard-filters.tsx`
+- `src/features/crm/dashboard/components/dashboard-summary-cards.tsx`
+- `src/features/crm/dashboard/components/dashboard-funnel.tsx`
+- `src/features/crm/dashboard/components/dashboard-revenue-cards.tsx`
+- `src/features/crm/dashboard/components/dashboard-sales-ranking.tsx`
+- `src/features/crm/dashboard/components/dashboard-followups.tsx`
+- `src/features/crm/dashboard/components/dashboard-approval-metrics.tsx`
+- `src/features/crm/dashboard/components/dashboard-hot-projects.tsx`
+- `src/app/api/crm/dashboard/route.ts`
+- `src/app/api/crm/dashboard/export/route.ts`
+
+## Files modified
+
+- `src/app/dashboard/crm/page.tsx`
+- `src/config/nav-config.ts`
+- `src/lib/auth/rbac.ts`
+- `src/lib/searchparams.ts`
+- `docs/implementation/technical-debt.md`
+
+## KPI widgets added
+
+- Replaced the CRM placeholder route with a production dashboard at `/dashboard/crm`.
+- Added summary cards for lead, opportunity, quotation, and revenue metrics.
+- Added a funnel widget for lead -> opportunity -> quotation -> pending approval -> approved -> closed won.
+- Added a hot-project widget based on real enquiry data.
+
+## Revenue analytics added
+
+- Added top end-customer, billing-customer, contractor, and consultant revenue tables.
+- Reused the Task D.2.1 reporting helpers so revenue attribution follows the frozen governance rules.
+- Added export support for revenue analytics through the dashboard export route.
+
+## Sales ranking added
+
+- Added a production sales ranking table using enquiry assignment and quotation salesman ownership rules.
+- Added CSV export for sales ranking.
+
+## Approval and follow-up analytics added
+
+- Added approval KPI cards and a `My Pending Approvals` table.
+- Added follow-up KPI cards and an `Upcoming Follow Ups` table from enquiry and quotation follow-up sources.
+
+## Export and permissions added
+
+- Added `crm.dashboard.read`.
+- Added `crm.dashboard.export`.
+- Added audit logging for `crm_dashboard_export` with `export_csv` and `export_excel`.
+- Added sidebar navigation for the CRM dashboard.
+
+## Remaining risks
+
+- `closed_won` is not yet a first-class enquiry lifecycle field, so the dashboard currently uses quotation status `accepted` as the practical won-stage proxy.
+- follow-up completion is inferred from `outcome` presence because the follow-up model still has no explicit completion flag.
+- the global `Project Party Role` filter currently influences revenue analytics and exports, but the rest of the dashboard still depends mainly on enquiry and quotation core filters.
+- sales users currently read organization-wide dashboard data; own-scope filtering is still future work.
+
+## Task K readiness
+
+- the CRM dashboard now uses real production data
+- KPI widgets are live
+- revenue analytics is reusable
+- sales ranking is exportable
+- approval and follow-up analytics exist
+- export and audit hooks are in place
+- the app is ready for Task K report-center expansion