alla-allaos-fullstack/docs/implementation/task-d3-lead-enquiry-ownership-refinement.md

Task D.3: Lead / Enquiry Ownership Refinement

1. Files Added

• drizzle/0012_odd_fat_cobra.sql
• docs/adr/0011-lead-enquiry-ownership-model.md
• docs/implementation/task-d3-lead-enquiry-ownership-refinement.md

2. Files Modified

• src/db/schema.ts
• src/lib/auth/rbac.ts
• src/features/users/components/user-form-sheet.tsx
• src/features/crm/enquiries/api/types.ts
• src/features/crm/enquiries/server/service.ts
• src/features/crm/quotations/server/service.ts
• src/app/api/crm/enquiries/route.ts
• src/app/api/crm/enquiries/[id]/route.ts
• src/app/api/crm/enquiries/[id]/assign/route.ts
• src/app/api/crm/enquiries/[id]/reassign/route.ts
• src/app/api/crm/enquiries/[id]/customers/route.ts
• src/app/api/crm/enquiries/[id]/followups/route.ts
• src/app/api/crm/enquiries/[id]/followups/[followupId]/route.ts
• src/app/api/crm/dashboard/route.ts
• src/app/api/crm/dashboard/export/route.ts
• src/app/dashboard/crm/enquiries/page.tsx
• src/app/dashboard/crm/enquiries/[id]/page.tsx
• src/config/nav-config.ts
• src/features/crm/enquiries/components/enquiry-form-sheet.tsx
• src/features/crm/enquiries/components/enquiry-assignment-dialog.tsx
• src/features/crm/enquiries/components/enquiry-columns.tsx
• src/features/crm/enquiries/components/enquiry-detail.tsx
• src/features/crm/enquiries/components/enquiry-cell-action.tsx
• src/features/crm/dashboard/api/types.ts
• src/features/crm/dashboard/server/service.ts
• src/features/crm/dashboard/components/crm-dashboard.tsx
• src/features/crm/dashboard/components/dashboard-summary-cards.tsx
• src/features/crm/dashboard/components/dashboard-funnel.tsx
• src/features/crm/dashboard/components/dashboard-sales-ranking.tsx
• src/features/crm/dashboard/components/dashboard-followups.tsx
• src/features/crm/dashboard/components/dashboard-hot-projects.tsx

3. Pipeline Changes

• Added crm_enquiries.pipeline_stage
• Allowed values:
  • lead
  • enquiry
  • closed_won
  • closed_lost
• Backfilled legacy enquiry rows:
  • assigned rows -> enquiry
  • unassigned rows -> lead
  • closed-lost/cancelled status rows -> closed_lost
• Assign flow now converts lead -> enquiry
• Quotation accepted/lost/rejected outcomes can synchronize linked enquiry lifecycle to won/lost stages

4. Ownership Changes

• Added business role marketing
• Marketing-created records default to lead
• Sales-created records default to enquiry
• sales and sales_support now use server-enforced own-or-assigned enquiry visibility
• managers, admins, and marketing retain broader monitoring visibility

5. Visibility Rules Added

• Marketing can read CRM lead/enquiry monitoring surfaces
• Marketing cannot see quotation pricing or approval analytics
• Enquiry detail hides related quotation links when the user lacks quotation read access
• CRM dashboard hides quotation, revenue, hot-enquiry, sales-ranking, and approval sections when the user lacks those permissions

6. KPI Changes

• Dashboard summary now uses pipelineStage for:
  • lead count
  • enquiry count
  • won count
  • lost count
• User-facing KPI language changed from Opportunity to Enquiry
• Funnel wording now follows lead -> enquiry -> quotation flow
• Follow-up and ownership labels now use Enquiry Owner

7. ADR Added

• Added docs/adr/0011-lead-enquiry-ownership-model.md
• This freezes:
  • lead ownership
  • enquiry ownership
  • assignment conversion behavior
  • marketing visibility restriction boundaries
  • won/lost lifecycle naming

8. Migration Notes

• Apply drizzle/0012_odd_fat_cobra.sql
• Existing crm_enquiries rows are backfilled in-place; no new lead table is introduced
• Existing forms and APIs remain shared across lead and enquiry flows
• Existing quotation routes remain intact; only linked enquiry lifecycle sync was added

9. Remaining Risks

• closed_won still has no dedicated timestamp field; lifecycle timing remains coarse
• dashboard/export visibility now follows permission boundaries, but any future custom report endpoints must preserve the same commercial-data guardrails
• quotation-to-enquiry lifecycle sync currently depends on quotation status transitions and does not yet model reopen scenarios explicitly

Verification

• npx tsc --noEmit