alla-allaos-fullstack/docs/implementation/task-d55-opportunity-sales-workspace-refinement.md

Task D.5.5: Opportunity / Sales Workspace Refinement

Objective

Refine the sales-facing enquiry workspace so lead-origin enquiries are presented as opportunities without renaming the underlying crm_enquiries model or changing quotation, dashboard, report, or approval foundations.

Review Completed

• AGENTS.md
• plans/task-d.5.5.md
• docs/standards/project-foundations.md
• docs/standards/task-catalog.md
• docs/adr/0018-lead-enquiry-domain-separation.md
• docs/implementation/task-d5-lead-enquiry-domain-separation.md
• docs/implementation/task-d52-lead-domain-service-api-foundation.md
• docs/implementation/task-d53-lead-assignment-create-enquiry-foundation.md
• docs/implementation/task-d54-lead-enquiry-workspace-separation-ui-foundation.md
• docs/security/crm-authorization-boundaries.md
• existing enquiry list/detail/form/assignment UI
• existing quotation reference-data and creation UI

What Changed

• Updated enquiries page to use sales-facing opportunity wording in page title and description while keeping the same enquiry route.
• Refined list-loading and table UI in:
  • enquiry-listing.tsx
  • enquiries-table.tsx
  • enquiry-columns.tsx
• Opportunity list now emphasizes sales execution fields:
  • opportunity code
  • source lead indicator
  • customer
  • project name
  • product type
  • sales owner
  • status
  • estimated value
  • chance percent
  • expected close date
  • next follow-up
  • created date
• Updated opportunity detail page to load:
  • optional source lead summary
  • quotation reference data when quotation creation permission exists
• Rebuilt enquiry-detail.tsx around clearer sales sections:
  • Opportunity Summary
  • Source Lead
  • Customer / Contact
  • Requirement
  • Sales Qualification
  • Follow-up Timeline
  • Linked Quotations
  • Activity
  • Quotation Readiness
• Added source-lead-card.tsx for read-only lead provenance visibility.
• Added quotation-readiness-panel.tsx for non-blocking readiness checks.
• Extended types.ts with optional list-only fields for future source lead and follow-up enrichment without breaking existing API consumers.

UI Wording Decisions

• Route kept as /dashboard/crm/enquiries
• Page title changed to CRM Opportunities
• Detail title changed to Opportunity Detail
• Technical code and API names remain enquiry / crm_enquiries

APIs and Foundations Reused

• Existing enquiry APIs remained unchanged:
  • GET /api/crm/enquiries
  • GET /api/crm/enquiries/[id]
  • existing follow-up and assignment APIs
• Existing quotation reference-data foundation reused for the Create Quotation action.
• Lead detail service reused for source lead summary display.

Permission Mapping

• Opportunity list/detail still rely on existing enquiry permissions:
  • crm.enquiry.read
  • crm.enquiry.update
  • crm.enquiry.assign
  • crm.enquiry.reassign
  • crm.enquiry.followup.create
  • crm.enquiry.followup.update
  • crm.enquiry.followup.delete
• Quotation action is shown only when crm.quotation.create is available.
• Source lead visibility on the opportunity page does not widen lead permissions; it is only rendered for users who can already access the enquiry page.

Compatibility Notes

• crm_enquiries, /api/crm/enquiries, and existing quotation flows were not renamed.
• Records without lead_id continue to render as direct sales opportunities.
• Dashboard, reports, approvals, and quotation services were not changed.

Known Limitations

• The current Create Quotation action opens the existing quotation creation sheet without automatically preselecting the current opportunity.
• Source-lead-specific list enrichment is prepared at the UI contract level, but the list still uses lightweight lead linkage signaling rather than a fully joined source-lead dataset.

Verification

• npm exec tsc --noEmit