task-j1
This commit is contained in:
phaichayon
74
docs/implementation/task-j-crm-dashboard-kpi.md
Normal file
74
docs/implementation/task-j-crm-dashboard-kpi.md
Normal file
@@ -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
|
||||
@@ -0,0 +1,85 @@
|
||||
# Task J.1: CRM Admin Configuration Center
|
||||
|
||||
## Files Added
|
||||
|
||||
- `src/app/api/crm/settings/**`
|
||||
- `src/app/dashboard/crm/settings/approval-workflows/page.tsx`
|
||||
- `src/features/foundation/approval/components/approval-workflow-settings.tsx`
|
||||
- `src/features/foundation/document-sequence/client-service.ts`
|
||||
- `src/features/foundation/document-sequence/components/document-sequence-settings.tsx`
|
||||
- `src/features/foundation/document-sequence/mutations.ts`
|
||||
- `src/features/foundation/document-sequence/queries.ts`
|
||||
- `src/features/foundation/document-template/mutations.ts`
|
||||
- `docs/implementation/task-j1-crm-admin-configuration-center.md`
|
||||
|
||||
## Files Modified
|
||||
|
||||
- `src/config/nav-config.ts`
|
||||
- `src/lib/auth/rbac.ts`
|
||||
- `src/app/dashboard/crm/settings/document-sequences/page.tsx`
|
||||
- `src/features/foundation/approval/{mutations,queries,server/service,service,types}.ts`
|
||||
- `src/features/foundation/document-sequence/{service,types}.ts`
|
||||
- `src/features/foundation/document-template/{components/template-settings,mutations,server/service,service,types}.ts`
|
||||
|
||||
## What Was Added
|
||||
|
||||
- CRM Settings menu now includes `Approval Workflows` and uses CRM-specific permission checks for `Document Sequences`.
|
||||
- `/dashboard/crm/settings/templates` now supports:
|
||||
- create/edit template metadata
|
||||
- create/edit template versions with JSON schema textarea
|
||||
- create/edit/delete template mappings
|
||||
- table-column mapping input for `table` data type
|
||||
- `/dashboard/crm/settings/approval-workflows` now supports:
|
||||
- create/edit/delete workflows
|
||||
- manage sequential workflow steps
|
||||
- role-based step definitions using CRM business roles
|
||||
- `/dashboard/crm/settings/document-sequences` now supports:
|
||||
- create/edit/delete sequences
|
||||
- reset sequence counters
|
||||
- preview next code from stored sequence state
|
||||
|
||||
## API Routes Added
|
||||
|
||||
- `/api/crm/settings/document-templates/**`
|
||||
- `/api/crm/settings/approval-workflows/**`
|
||||
- `/api/crm/settings/document-sequences/**`
|
||||
|
||||
## Permissions Added
|
||||
|
||||
- `crm.approval.workflow.read`
|
||||
- `crm.approval.workflow.create`
|
||||
- `crm.approval.workflow.update`
|
||||
- `crm.approval.workflow.delete`
|
||||
- `crm.document_sequence.read`
|
||||
- `crm.document_sequence.create`
|
||||
- `crm.document_sequence.update`
|
||||
- `crm.document_sequence.reset`
|
||||
|
||||
## Audit Coverage
|
||||
|
||||
- `crm_document_template_version`
|
||||
- `crm_document_template_mapping`
|
||||
- `crm_approval_workflow`
|
||||
- `crm_approval_step`
|
||||
- `crm_document_sequence`
|
||||
|
||||
## Verification
|
||||
|
||||
- `npx tsc --noEmit` passed on June 17, 2026.
|
||||
- `npm run lint` still fails because of pre-existing repo lint errors outside Task J.1 scope, including:
|
||||
- `src/components/ui/input-group.tsx`
|
||||
- `src/features/chat/components/message-composer.tsx`
|
||||
- `src/components/forms/demo-form.tsx`
|
||||
|
||||
## Remaining Risks
|
||||
|
||||
- Template settings UI is functional but not yet a polished table-first admin experience.
|
||||
- Document template version activation currently supports state updates, but the page focuses on version edit/create over dedicated activate/deactivate action buttons.
|
||||
- Sequence reset UI currently resets to `0`; custom reset value can be added later if the product needs it.
|
||||
- Approval step management currently replaces the full ordered step list in one save flow rather than exposing per-row move controls.
|
||||
|
||||
## Task K Readiness
|
||||
|
||||
- CRM settings foundations are now exposed through organization-scoped admin routes.
|
||||
- Query invalidation is wired for template, workflow, and sequence mutations.
|
||||
- The configuration center is ready for KPI/report consumers to reference the same settings data in later tasks.
|
||||
@@ -297,3 +297,51 @@ Future:
|
||||
- decide whether approved quotation snapshots or another immutable reporting snapshot should become the historical source of truth
|
||||
- define how reporting should behave if project parties change after quotation approval or after a won/lost outcome
|
||||
- add backfill or reconciliation tooling if historical party drift becomes a business issue
|
||||
|
||||
## After Task J
|
||||
|
||||
### Closed-won lifecycle fidelity
|
||||
|
||||
Task J ships a live CRM dashboard, but the current schema still lacks a first-class enquiry `closed_won` lifecycle field and dedicated close timestamps.
|
||||
|
||||
Current:
|
||||
|
||||
- dashboard won-stage metrics currently use quotation status `accepted` as the practical proxy for `closed_won`
|
||||
|
||||
Future:
|
||||
|
||||
- add explicit enquiry lifecycle support for `closed_won`
|
||||
- add `closedWonAt` to support precise won-date analytics
|
||||
- remove dashboard proxy logic once the lifecycle model is formalized
|
||||
|
||||
### Follow-up completion semantics
|
||||
|
||||
Task J adds follow-up analytics, but the follow-up model still has no explicit completion flag.
|
||||
|
||||
Current:
|
||||
|
||||
- dashboard `Completed` follow-up metrics infer completion from `outcome` presence
|
||||
|
||||
Future:
|
||||
|
||||
- add an explicit completion state or activity outcome model for follow-ups
|
||||
- separate scheduled, completed, cancelled, and skipped follow-up reporting cleanly
|
||||
|
||||
### Dashboard own-scope policy
|
||||
|
||||
Task J introduces `crm.dashboard.read`, but sales users still view organization-wide KPI data for now.
|
||||
|
||||
Future:
|
||||
|
||||
- add own-scope dashboard filtering for sales roles
|
||||
- define whether mixed-role users see own, team, or organization scope by default
|
||||
- keep exports aligned with the same scope policy once enforced
|
||||
|
||||
### Global project-party filter coverage
|
||||
|
||||
Task J adds a global `Project Party Role` filter in the dashboard UI, but the strongest enforcement today is in revenue analytics and export sections.
|
||||
|
||||
Future:
|
||||
|
||||
- decide which non-revenue widgets should fully honor project-party role filtering
|
||||
- add a unified filtered reporting projection if cross-widget party-role filtering becomes a hard requirement
|
||||
|
||||
Reference in New Issue
Block a user