alla-allaos-fullstack/docs/implementation/task-d57-opportunity-quotation-synchronization-foundation.md

Task D.5.7 Opportunity / Quotation Synchronization Foundation

Summary

• Reused opportunityId as the active quotation link field.
• Added service-side synchronization foundations instead of embedding sync logic in routes.
• Kept Opportunity as sales pipeline source of truth.
• Kept Quotation as commercial document source of truth.

New Service Foundations

• src/features/crm/opportunities/server/quotation-sync.service.ts
  • syncOpportunityFromQuotationCreated()
  • syncOpportunityFromQuotationApproval()
  • syncOpportunityFromQuotationWon()
  • syncOpportunityFromQuotationLost()
• src/features/crm/quotations/server/opportunity-link.service.ts
  • assertOpportunityLinkIntegrity()
  • assertRevisionOpportunityLinkIntegrity()
  • auditQuotationOpportunityLink()

Sync Trigger Map

• Quotation created
  • Opportunity stage moves to quotation_created
  • Outcome stays open
• Quotation pending approval
  • Opportunity stage stays quotation_created
• Quotation approved
  • Opportunity stage moves to negotiation
• Quotation sent to customer
  • Opportunity stage can move to negotiation
• Quotation won
  • Opportunity stage becomes closed
  • Opportunity outcome becomes won
• Quotation lost
  • Opportunity closes as lost only when no other viable quotation remains

Guard Rules

• Quotation cannot link to an opportunity outside the same organization.
• Closed opportunities cannot create new quotations.
• Quotation customer must match linked opportunity customer.
• Quotation product type must match linked opportunity product type.
• Revisions keep the same opportunityId.

Audit Actions

• sync_opportunity_from_quotation_created
• sync_opportunity_from_quotation_approved
• sync_opportunity_from_quotation_sent
• sync_opportunity_from_quotation_won
• sync_opportunity_from_quotation_lost
• sync_quotation_opportunity_link

Current UI Integration

• Opportunity detail now shows richer linked quotation context.
• Quotation detail linkage foundation remains ready for follow-up UI expansion.

Known Limitations

• Manual quotation accept / reject operations are not fully exposed in UI yet.
• Opportunity detail shows linked quotations, but full quotation outcome highlighting can still be expanded.
• Quotation detail linked opportunity card can be extended further in a follow-up pass.