# 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.