{
  "jira_key": "AN-87",
  "summary": "Opportunity Contact Role Close-Won Guard",
  "approach": "1. Overview \u2014 Prevent an Opportunity from being moved to Closed Won without an associated Opportunity Contact Role (OCR).\n2. Scope \u2014 Enforce on Opportunity updates that transition StageName to Closed Won. UI edits are blocked when no OCR exists. Exempt AutomatedProcess and users on an integration-specific user license; do not exempt generic API users. Confirm the org\u2019s integration-user classification before deployment.\n3. Data Model \u2014 Use standard Opportunity.StageName and OpportunityContactRole.OpportunityId; no fields or data-model changes.\n4. Picklist Configuration \u2014 None.\n5. Page Layout Configuration \u2014 None; users can add contacts through the standard Opportunity Contact Roles related list.\n6. Validation Rule \u2014 Not suitable: Salesforce validation formulas cannot reliably check child OCR records. Enforce in Apex before update and attach the exact error to the Opportunity: \u201cValidation Error: You cannot close-win this Opportunity without assigning at least one Contact Role. Please add a contact to the Opportunity Contact Roles related list and try again.\u201d\n7. Processing Behavior \u2014 A thin Opportunity trigger delegates before-update processing to a handler. The handler checks only records transitioning to Closed Won, queries OCRs in bulk for the affected Opportunity IDs, and calls addError on records with no OCR. No trigger queries or business logic; repeated execution is limited by checking the StageName transition.\n8. Security and Access \u2014 No new permissions are required. The handler checks the executing user\u2019s context and integration-specific user license for the stated exclusions. Confirm the exact license/profile convention used by this org; do not use hardcoded user IDs.\n9. Deployment Components \u2014 Opportunity trigger, handler, and Apex tests. Deploy to a non-production environment first; no production deployment is included.\n10. Testing Strategy \u2014 Test bulk updates, transition to Closed Won with and without OCRs, unchanged Closed Won records, and the integration/system-context exemption. Verify the exact error text and that unrelated Opportunities save successfully.\n11. Acceptance Criteria Traceability \u2014 A transition to Closed Won with no OCR is rejected with the required message; one or more OCRs permits the transition; UI edits are covered; designated system integration contexts are exempt.\n12. Implementation Summary \u2014 Add a bulk-safe before-update guard using standard metadata only. Repository inventory reports two Apex classes but no matching code; inspect trigger inventory and those classes before implementation. Extend any existing project-owned Opportunity trigger rather than adding a second one.",
  "metadata_plan": [
    {
      "metadata_type": "ApexTrigger",
      "api_name": "OpportunityTrigger",
      "action": "create",
      "object": "Opportunity",
      "notes": "Before update only; delegate to OpportunityContactRoleGuardHandler and contain no business logic or queries. Repository hits show no existing trigger, but confirm the org and repository before creating; extend an existing project-owned Opportunity trigger if present."
    },
    {
      "metadata_type": "ApexClass",
      "api_name": "OpportunityContactRoleGuardHandler",
      "action": "create",
      "object": "Opportunity",
      "notes": "Bulk-query OpportunityContactRole by affected Opportunity IDs; reject only transitions into Closed Won when no role exists. Exempt AutomatedProcess and users with an integration-specific user license, after confirming the org\u2019s license convention. Add the required exact error using addError."
    },
    {
      "metadata_type": "ApexClass",
      "api_name": "OpportunityContactRoleGuardTest",
      "action": "create",
      "object": null,
      "notes": "Apex tests for bulk behavior, missing/present OCRs, stage transitions, exact error text, and applicable system/integration exemption behavior."
    }
  ],
  "dependencies": [
    "Standard Opportunity.StageName and OpportunityContactRole.OpportunityId.",
    "Repository inventory reports two existing Apex classes with no matching code identified; review them for interactions before implementation.",
    "No existing trigger was reported in repository hits. Confirm org/project-owned Opportunity trigger inventory and preserve the one-trigger-per-object convention.",
    "Confirm which user license or other stable org convention identifies the standard system integration users to exempt."
  ],
  "risks_or_escalations": [
    "The org\u2019s standard system integration users are not identified in the supplied data. Confirm the exact integration-specific license/profile convention and approve the exemption scope before deployment; generic API users will not be exempted by default.",
    "If an Opportunity trigger already exists in the target org or outside the repository inventory, the implementation must extend it rather than create a second trigger."
  ],
  "out_of_allowlist": false,
  "confidence": 0.95,
  "notes": "No ValidationRule is planned because a validation formula cannot query associated OCR child records. No fields, layouts, picklists, or non-allowlisted metadata are required."
}