alla-allaos-fullstack/docs/implementation/task-d56-opportunity-lifecycle-won-lost-alignment.md

Task D.5.6 Opportunity Lifecycle / Won-Lost Alignment

Summary

• Added explicit opportunity outcome fields in crm_opportunities:
  • outcomeStatus
  • closedAt
  • lostDetail
  • cancelReason
  • noQuotationReason
• Preserved legacy compatibility fields:
  • pipelineStage
  • closedWonAt
  • closedLostAt

Lifecycle Model

• Working stage continues to use crm_opportunities.status for now.
• UI/API now expose stage as an alias of status.
• Final result is tracked with outcomeStatus.

Closed outcomes

• won
• lost
• cancelled
• no_quotation

Reopen behavior

• Reopen clears final outcome data.
• Reopen returns the opportunity to:
  • status = quotation_created
  • outcomeStatus = open
  • pipelineStage = opportunity

Master Options

• Added/seeded:
  • crm_opportunity_stage
  • crm_opportunity_outcome_status
  • crm_opportunity_lost_reason
  • crm_opportunity_cancel_reason
  • crm_opportunity_no_quotation_reason
• Kept legacy compatibility categories:
  • crm_opportunity_status
  • crm_lost_reason

API Routes

• POST /api/crm/opportunities/[id]/mark-won
• POST /api/crm/opportunities/[id]/mark-lost
• POST /api/crm/opportunities/[id]/mark-cancelled
• POST /api/crm/opportunities/[id]/mark-no-quotation
• POST /api/crm/opportunities/[id]/reopen

Quotation Alignment

• Quotation creation is blocked when linked opportunity has a closed outcomeStatus.
• Quotation creation keeps outcome as open.
• Opportunity stage sync remains compatibility-first and moves to quotation_created.

Audit Actions

• mark_opportunity_won
• mark_opportunity_lost
• mark_opportunity_cancelled
• mark_opportunity_no_quotation
• reopen_opportunity

Encoding Guard

• Verified repository text encoding with npm run verify:encoding.
• Repaired mojibake on CRM dashboard components in the sales ranking, follow-up, and hot-project sections.