306 lines
5.4 KiB
Markdown
306 lines
5.4 KiB
Markdown
# Task Fix: CRM Dashboard Opportunity Rename Compatibility
|
|
|
|
## Objective
|
|
|
|
Fix CRM Dashboard API/runtime errors after the force rename from Enquiry to Opportunity.
|
|
|
|
The current issue appears when the CRM dashboard query returns `500 Internal Server Error`, causing TanStack Query hydration to reject:
|
|
|
|
```txt
|
|
["crm-dashboard", {...}]
|
|
```
|
|
|
|
This task aligns dashboard, reports, query keys, imports, SQL, DTOs, and permissions with the new Opportunity domain.
|
|
|
|
---
|
|
|
|
## Error Context
|
|
|
|
Observed error:
|
|
|
|
```txt
|
|
A query that was dehydrated as pending ended up rejecting.
|
|
[["crm-dashboard", {...}]]: Error: API error: 500 Internal Server Error
|
|
```
|
|
|
|
Likely root cause:
|
|
|
|
```txt
|
|
Dashboard API still references old Enquiry domain after D.5.5.1 rename.
|
|
```
|
|
|
|
Examples of stale references:
|
|
|
|
```txt
|
|
crm_enquiries
|
|
crmEnquiries
|
|
enquiryId
|
|
Enquiry
|
|
enquiry-aging
|
|
crm.enquiry.*
|
|
```
|
|
|
|
---
|
|
|
|
## Mandatory Review
|
|
|
|
Review:
|
|
|
|
```txt
|
|
src/features/crm/dashboard/**
|
|
src/app/api/crm/dashboard/**
|
|
src/app/dashboard/crm/**
|
|
src/app/api/crm/reports/**
|
|
src/app/dashboard/crm/reports/**
|
|
src/features/crm/reports/**
|
|
src/db/schema.ts
|
|
src/features/crm/opportunities/**
|
|
src/config/nav-config.ts
|
|
src/db/seeds/foundation.seed.ts
|
|
```
|
|
|
|
---
|
|
|
|
## Scope 1: Identify Stale References
|
|
|
|
Run:
|
|
|
|
```bash
|
|
rg "crmEnquir|crm_enquir|enquiry|Enquiry|enquiryId|crm\.enquiry|/crm/enquiries" src/features/crm/dashboard src/app/api/crm/dashboard src/app/dashboard/crm src/features/crm/reports src/app/api/crm/reports src/app/dashboard/crm/reports
|
|
```
|
|
|
|
Expected action:
|
|
|
|
* Replace active application references with Opportunity terminology.
|
|
* Historical docs can remain unchanged.
|
|
* No active dashboard/report runtime code should depend on Enquiry naming.
|
|
|
|
---
|
|
|
|
## Scope 2: Dashboard API Fix
|
|
|
|
Update dashboard API/service to use:
|
|
|
|
```txt
|
|
crmOpportunities
|
|
crm_opportunities
|
|
opportunityId
|
|
crm.opportunity.*
|
|
```
|
|
|
|
instead of:
|
|
|
|
```txt
|
|
crmEnquiries
|
|
crm_enquiries
|
|
enquiryId
|
|
crm.enquiry.*
|
|
```
|
|
|
|
Ensure all dashboard metrics still return successfully.
|
|
|
|
Required dashboard response areas to verify:
|
|
|
|
```txt
|
|
summary cards
|
|
pipeline counts
|
|
sales ranking
|
|
follow-up due / overdue
|
|
hot projects
|
|
quotation summary
|
|
won / lost summary
|
|
project party filters
|
|
```
|
|
|
|
---
|
|
|
|
## Scope 3: SQL / Drizzle Query Fix
|
|
|
|
Fix all raw SQL and Drizzle queries that reference old table/column names.
|
|
|
|
Replace:
|
|
|
|
```txt
|
|
crm_enquiries
|
|
crm_enquiry_followups
|
|
crm_enquiry_customers
|
|
enquiry_id
|
|
```
|
|
|
|
with:
|
|
|
|
```txt
|
|
crm_opportunities
|
|
crm_opportunity_followups
|
|
crm_opportunity_customers
|
|
opportunity_id
|
|
```
|
|
|
|
If any remaining DB column intentionally keeps legacy naming, document it and map it at service boundary only.
|
|
|
|
---
|
|
|
|
## Scope 4: Dashboard DTO / Mapper Fix
|
|
|
|
Update dashboard DTOs, mappers, and labels.
|
|
|
|
Rename:
|
|
|
|
```txt
|
|
enquiryCount
|
|
enquiryPipeline
|
|
enquiryValue
|
|
enquiryAging
|
|
```
|
|
|
|
to:
|
|
|
|
```txt
|
|
opportunityCount
|
|
opportunityPipeline
|
|
opportunityValue
|
|
opportunityAging
|
|
```
|
|
|
|
Rules:
|
|
|
|
* API response should use Opportunity naming.
|
|
* UI labels should use Opportunity naming.
|
|
* Do not expose Enquiry naming in active CRM dashboard.
|
|
|
|
---
|
|
|
|
## Scope 5: Report Route Compatibility
|
|
|
|
Verify renamed routes:
|
|
|
|
```txt
|
|
/api/crm/reports/opportunity-aging
|
|
/dashboard/crm/reports/opportunity-aging
|
|
```
|
|
|
|
Remove or replace active references to:
|
|
|
|
```txt
|
|
/api/crm/reports/enquiry-aging
|
|
/dashboard/crm/reports/enquiry-aging
|
|
```
|
|
|
|
Update nav config if needed.
|
|
|
|
---
|
|
|
|
## Scope 6: Permissions
|
|
|
|
Replace dashboard/report permission checks:
|
|
|
|
```txt
|
|
crm.enquiry.*
|
|
```
|
|
|
|
with:
|
|
|
|
```txt
|
|
crm.opportunity.*
|
|
```
|
|
|
|
Verify seed/config contains the required permissions:
|
|
|
|
```txt
|
|
crm.opportunity.read
|
|
crm.opportunity.create
|
|
crm.opportunity.update
|
|
crm.opportunity.delete
|
|
crm.opportunity.assign
|
|
crm.opportunity.followup.create
|
|
crm.opportunity.followup.update
|
|
crm.opportunity.followup.delete
|
|
crm.opportunity.lifecycle.update
|
|
crm.opportunity.lifecycle.reopen
|
|
```
|
|
|
|
---
|
|
|
|
## Scope 7: Error Handling Improvement
|
|
|
|
Prevent dashboard SSR hydration from failing hard when API returns an error.
|
|
|
|
Improve dashboard query behavior:
|
|
|
|
* Server prefetch should catch API failure and return a safe empty dashboard model, or
|
|
* Client component should render an error state instead of causing hydration failure.
|
|
|
|
Do not hide backend errors in development logs.
|
|
|
|
Recommended:
|
|
|
|
```txt
|
|
dashboard API logs detailed server error
|
|
dashboard UI shows recoverable error message
|
|
query fallback uses empty dashboard model only when safe
|
|
```
|
|
|
|
---
|
|
|
|
## Scope 8: Verification
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npm exec tsc --noEmit
|
|
npm run build
|
|
```
|
|
|
|
Search validation:
|
|
|
|
```bash
|
|
rg "crmEnquir|crm_enquir|enquiry|Enquiry|enquiryId|crm\.enquiry|/crm/enquiries" src
|
|
```
|
|
|
|
Allowed only if:
|
|
|
|
```txt
|
|
historical docs
|
|
comments explicitly marked legacy
|
|
migration history
|
|
```
|
|
|
|
Manual verification:
|
|
|
|
```txt
|
|
Open CRM Dashboard
|
|
Dashboard API returns 200
|
|
No TanStack hydration rejection
|
|
Opportunity counts render
|
|
Quotation counts render
|
|
Won/Lost summary renders
|
|
Sales ranking renders
|
|
Follow-up widgets render
|
|
Hot project widgets render
|
|
Opportunity aging report opens
|
|
Navigation links use opportunity routes
|
|
```
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
Task is complete when:
|
|
|
|
* CRM Dashboard no longer returns 500
|
|
* Dashboard no longer references active Enquiry domain
|
|
* Reports use Opportunity naming
|
|
* Permissions use `crm.opportunity.*`
|
|
* API response and UI labels use Opportunity terminology
|
|
* TanStack hydration error is gone
|
|
* `npm exec tsc --noEmit` passes
|
|
* `npm run build` passes
|
|
|
|
Result:
|
|
|
|
```txt
|
|
Dashboard Opportunity Rename Compatibility = Fixed
|
|
CRM Dashboard Runtime = Restored
|
|
Ready to continue Approval + Notification roadmap
|
|
```
|