task-d.5.7

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

@@ -0,0 +1,65 @@
+# 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.