{
  "jira_key": "AN-88",
  "summary": "Opportunity Contact Role Close-Won Guard",
  "approach": "Technical Design \u2014 AN-88\n\n1. Overview\nPrevent an Opportunity from transitioning to Closed Won when it has no related Opportunity Contact Role (OCR), with the specified error shown on Stage.\n\n2. Scope\nEnforce the transition check in before-update automation. No custom fields, page layouts, picklists, flows, or data-model changes are required. Production deployment, merge, sharing/OWD redesign, and destructive deletes are excluded.\n\n3. Data Model\nUse the standard Opportunity.StageName field and standard OpportunityContactRole records related by OpportunityId. No new fields or objects.\n\n4. Picklist Configuration\nNo picklist configuration. Closed Won is the existing Opportunity Stage value.\n\n5. Page Layout Configuration\nNo page layout changes. The error is raised on the Stage field.\n\n6. Validation Rule\nDo not create a ValidationRule: Salesforce validation formulas cannot query child OpportunityContactRole records. Enforce the check in Apex instead. Error text: \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\n\n7. Processing Behavior\nOn Opportunity before update, detect records whose StageName changes to Closed Won. Query OCRs in bulk for the affected Opportunity IDs, collect those with no OCR, and add the specified error to StageName. Do not block edits to already Closed Won records or transitions to other stages. The handler performs no DML, so no recursion guard is needed.\n\n8. Security and Access\nThis is server-side enforcement and applies regardless of UI or API entry point unless a verified integration-user bypass is added. Apex must query OCRs in a context that can see all related OCRs, avoiding false blocks caused by record visibility; it returns no OCR data to users. The org must identify any standard system integration users to exclude, if applicable. Salesforce does not provide a reliable general trigger signal distinguishing UI edits from API edits, and no integration identities were supplied.\n\n9. Deployment Components\nOpportunity trigger, bulkified handler, and Apex tests. No ValidationRule, Flow, PermissionSet, or other metadata is planned. Deploy only through the authorized non-production/repository workflow.\n\n10. Testing Strategy\nTest that a transition to Closed Won without an OCR fails with the exact message; that a transition with an OCR succeeds; that non-Closed-Won transitions and edits to already Closed Won records are not blocked; and that bulk updates correctly distinguish Opportunities with and without OCRs. Add an integration-bypass test only after the relevant identities and bypass mechanism are confirmed.\n\n11. Acceptance Criteria Traceability\n- Transition to Closed Won checks for at least one OCR: handler and positive/negative transition tests.\n- No OCR blocks save and displays the exact requested text: StageName addError and exact-message assertion.\n- UI edits and applicable standard integration-user exclusions: trigger enforces the rule; integration exclusion requires org confirmation because neither the identities nor a reliable UI/API discriminator were supplied.\n\n12. Implementation Summary\nCreate a single Opportunity trigger that delegates to a handler; use one bulk OCR query and field-level errors. Confirm integration-user treatment and inspect existing Opportunity automation before implementation is finalized.",
  "metadata_plan": [
    {
      "metadata_type": "ApexTrigger",
      "api_name": "OpportunityTrigger",
      "action": "create",
      "object": "Opportunity",
      "notes": "Before update only; delegate all logic to OpportunityContactRoleCloseWonHandler. Follow TRIG-01 through TRIG-04. Confirm no project-owned Opportunity trigger exists in the complete org/repository inventory before creating; if one exists, update it rather than adding another."
    },
    {
      "metadata_type": "ApexClass",
      "api_name": "OpportunityContactRoleCloseWonHandler",
      "action": "create",
      "object": "Opportunity",
      "notes": "PascalCase Handler suffix per APEX-07. Bulkify: detect StageName transitions to Closed Won, query OpportunityContactRole once for the affected Opportunity IDs, and add the exact acceptance-criteria error to StageName for those with no OCR. Use an access context that can see all related OCRs. Do not implement an unverified integration-user bypass."
    },
    {
      "metadata_type": "ApexClass",
      "api_name": "OpportunityContactRoleCloseWonHandlerTest",
      "action": "create",
      "object": "Opportunity",
      "notes": "Apex test class covering blocked and allowed transitions, exact error text, already-Closed-Won edits, unrelated stage changes, and bulk behavior. Add bypass coverage only if an integration-user exclusion mechanism is confirmed."
    }
  ],
  "dependencies": [
    "Standard Opportunity.StageName and OpportunityContactRole relationship.",
    "Inspect the two repository Apex classes for established handler conventions and interactions before implementation; their names and contents were not included in the supplied inventory.",
    "Inspect the complete org/repository inventory for existing project-owned or managed-package Opportunity triggers and Opportunity automation. None were identified in the supplied repository hits; existing Flows/triggers on the object were not confirmed.",
    "Confirm whether standard system integration users exist and provide a stable, approved way to identify them if they must be excluded.",
    "No open pull requests or ticket branches were identified in the supplied inputs."
  ],
  "risks_or_escalations": [
    "Escalate for confirmation of standard system integration-user identities and the intended bypass mechanism. Trigger logic cannot reliably distinguish UI edits from API edits in general; without confirmation, the rule would apply to all execution contexts.",
    "Verify the full org/repository inventory before creating OpportunityTrigger to avoid violating the one-project-owned-trigger-per-object standard.",
    "The repository inventory contains only customizations and omits standard fields and may not represent all org automation; verify actual Opportunity and OCR metadata before implementation."
  ],
  "out_of_allowlist": false,
  "confidence": 0.84,
  "notes": "The requested child-record existence check is not expressible as a Salesforce ValidationRule formula, so the allowlisted ApexTrigger and ApexClass types are used. Integration-user exclusion remains unresolved pending org-specific information."
}