def prepare_jira_fields(
    *,
    title: str,
    description: str,
    priority: int,
    reporter: str,
    incident_category: str,
    environments: list[str],
    platforms: list[str],
    impacts_data: dict[str, ImpactLevel],
    optional_fields: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Prepare all fields for jira_client.create_issue().

    This function centralizes Jira field preparation for both P1-P3 and P4-P5 incidents,
    ensuring all custom fields are properly passed.

    Args:
        title: Incident title
        description: Incident description
        priority: Priority value (1-5)
        reporter: Jira user account ID
        incident_category: Category name
        environments: List of environment values (e.g. ["PRD", "STG"])
        platforms: List of platform values (e.g. ["platform-FR", "platform-DE"])
        impacts_data: Dictionary of impact data for business_impact computation
        optional_fields: Optional dictionary containing:
            - zendesk_ticket_id: Zendesk ticket ID (customer-specific)
            - seller_contract_id: Seller contract ID (seller-specific)
            - zoho_desk_ticket_id: Zoho Desk ticket ID (seller-specific)
            - is_key_account: Key account flag (seller-specific)
            - is_seller_in_golden_list: Golden list flag (seller-specific)
            - suggested_team_routing: Suggested team routing (P4-P5 only)

    Returns:
        Dictionary of kwargs ready for jira_client.create_issue()
    """
    business_impact = get_business_impact(impacts_data)
    platform = platforms[0] if platforms else PlatformChoices.ALL.value

    # Extract optional fields with defaults
    opt = optional_fields or {}
    zendesk_ticket_id = opt.get("zendesk_ticket_id", "")
    seller_contract_id = opt.get("seller_contract_id", "")
    zoho_desk_ticket_id = opt.get("zoho_desk_ticket_id", "")
    is_key_account = opt.get("is_key_account")
    is_seller_in_golden_list = opt.get("is_seller_in_golden_list")
    suggested_team_routing = opt.get("suggested_team_routing")

    return {
        "issuetype": "Incident",
        "summary": title,
        "description": description,
        "priority": priority,
        "reporter": reporter,
        "assignee": None,
        "incident_category": incident_category,
        "environments": environments,  # ✅ Always pass environments list
        "platform": platform,
        "business_impact": business_impact,
        "zendesk_ticket_id": zendesk_ticket_id,
        "seller_contract_id": seller_contract_id,
        "zoho_desk_ticket_id": zoho_desk_ticket_id,
        "is_key_account": is_key_account if is_key_account is not None else False,
        "is_seller_in_golden_list": is_seller_in_golden_list if is_seller_in_golden_list is not None else False,
        "suggested_team_routing": suggested_team_routing,
    }

def validate_no_spaces(value: str) -> None:
    """Ensure the string does not contain spaces."""
    if " " in value:
        raise serializers.ValidationError("The string cannot contain spaces.")

def check_issue_id(issue: JiraObject, title: str, reporter: str) -> int | str:
    """Check and return the issue ID from a JiraObject.

    Raises JiraAPIError if the issue ID is missing or invalid.
    """
    issue_id = issue.get("id")
    if issue_id is None:
        logger.error(
            f"Could not create Jira ticket for the incident {title} and the reporter {reporter}"
        )
        raise JiraAPIError(error_jira_ticket_creation)
    return issue_id

def create_issue_customer(
    title: str,
    description: str,
    reporter: str,
    issue_data: CustomerIssueData,
) -> JiraObject:
    """Creates a Jira Incident issue of type Customer.

    Args:
        title (str): Summary of the issue
        description (str): Description of the issue
        reporter (str): Jira account id of the reporter
        issue_data (CustomerIssueData): Container with issue parameters
    """
    issue = jira_client.create_issue(
        issuetype="Incident",
        summary=title,
        description=description,
        assignee=None,
        reporter=reporter,
        priority=issue_data.priority,
        labels=issue_data.labels,
        platform=issue_data.platform,
        business_impact=issue_data.business_impact,
        suggested_team_routing=issue_data.team_to_be_routed,
        zendesk_ticket_id=issue_data.zendesk_ticket_id,
        incident_category=issue_data.incident_category,
    )
    check_issue_id(issue, title=title, reporter=reporter)
    return issue

def create_issue_documentation_request(
    title: str,
    description: str,
    reporter: str,
    priority: int | None,
    labels: list[str] | None,
    platform: str,
) -> JiraObject:
    """Creates a Jira issue of type Documentation/Process Request.

    Args:
        title (str): Summary of the issue
        description (str): Description of the issue
        reporter (str): Jira account id of the reporter
        priority (int): Priority of the issue
        labels (list[str]): Labels to add to the issue
        platform (str): Platform of the issue
    """
    if labels is None:
        labels = [""]
    if "documentation-request" not in labels:
        labels.append("documentation-request")
    issue = jira_client.create_issue(
        issuetype="Documentation/Process Request",
        summary=title,
        description=description,
        assignee=None,
        reporter=reporter,
        priority=priority,
        labels=labels,
        platform=platform,
    )
    check_issue_id(issue, title=title, reporter=reporter)
    return issue

def create_issue_feature_request(
    title: str,
    description: str,
    reporter: str,
    priority: int | None,
    labels: list[str] | None,
    platform: str,
) -> JiraObject:
    """Creates a Jira issue of type Feature Request.

    Args:
        title (str): Summary of the issue
        description (str): Description of the issue
        reporter (str): Jira account id of the reporter
        priority (int): Priority of the issue
        labels (list[str]): Labels to add to the issue
        platform (str): Platform of the issue
    """
    if labels is None:
        labels = [""]
    if "feature-request" not in labels:
        labels.append("feature-request")
    issue = jira_client.create_issue(
        issuetype="Feature Request",
        summary=title,
        description=description,
        assignee=None,
        reporter=reporter,
        priority=priority,
        labels=labels,
        platform=platform,
    )
    check_issue_id(issue, title=title, reporter=reporter)
    return issue

def create_issue_internal(
    title: str,
    description: str,
    reporter: str,
    priority: int | None,
    labels: list[str] | None,
    platform: str,
    business_impact: str | None,
    team_to_be_routed: str | None,
    incident_category: str | None,
) -> JiraObject:
    """Creates a Jira Incident Issue of type Internal.

    Args:
        title (str): Summary of the issue
        description (str): Description of the issue
        reporter (str): Jira account id of the reporter
        priority (int): Priority of the issue
        labels (list[str]): Labels to add to the issue
        platform (str): Platform of the issue
        business_impact (str): Business impact of the issue
        team_to_be_routed (str): Team to be routed
        incident_category (str): Incident category of the issue
    """
    issue = jira_client.create_issue(
        issuetype="Incident",
        summary=title,
        description=description,
        assignee=None,
        reporter=reporter,
        priority=priority,
        labels=labels,
        platform=platform,
        business_impact=business_impact,
        suggested_team_routing=team_to_be_routed,
        incident_category=incident_category,
    )
    check_issue_id(issue, title=title, reporter=reporter)
    return issue

def create_issue_seller(  # noqa: PLR0913
    title: str,
    description: str,
    reporter: str,
    priority: int | None,
    labels: list[str] | None,
    platform: str,
    business_impact: str | None,
    team_to_be_routed: str | None,
    incident_category: str | None,
    seller_contract_id: str | None,
    is_key_account: bool | None,
    is_seller_in_golden_list: bool | None,
    zoho_desk_ticket_id: str | None,
) -> JiraObject:
    """Creates a Jira Incident issue of type Seller.

    Args:
        title (str): Summary of the issue
        description (str): Description of the issue
        reporter (str): Jira account id of the reporter
        priority (int): Priority of the issue
        labels (list[str]): Labels to add to the issue
        platform (str): Platform of the issue
        business_impact (str): Business impact of the issue
        team_to_be_routed (str): Team to be routed
        incident_category (str): Incident category of the issue
        seller_contract_id (str): Seller contract id
        is_key_account (bool): Is key account
        is_seller_in_golden_list (bool): Is seller in golden list
        zoho_desk_ticket_id (str): Zoho desk ticket id
    """
    issue = jira_client.create_issue(
        issuetype="Incident",
        summary=title,
        description=description,
        assignee=None,
        reporter=reporter,
        priority=priority,
        labels=labels,
        platform=platform,
        business_impact=business_impact,
        suggested_team_routing=team_to_be_routed,
        seller_contract_id=seller_contract_id,
        is_key_account=is_key_account,
        is_seller_in_golden_list=is_seller_in_golden_list,
        zoho_desk_ticket_id=zoho_desk_ticket_id,
        incident_category=incident_category,
    )
    check_issue_id(issue, title=title, reporter=reporter)
    return issue

def get_jira_user_from_user(user: User) -> JiraUser:
    """Returns the JiraUser object for a given user, if it exists in DB or can be fetched on Jira API. Returns the default JiraUser if not found."""
    try:
        jira_user = jira_client.get_jira_user_from_user(user)
    except JiraAPIError:
        logger.exception(f"Could not find Jira user for {user.id}")

        logger.warning(f"User {user.id} has no Jira user")
        try:
            jira_user = jira_client.get_jira_user_from_jira_id(
                RAID_DEFAULT_JIRA_QRAFT_USER_ID
            )
        except JiraUserNotFoundError:
            logger.exception(
                f"Could not find Jira user with account id {RAID_DEFAULT_JIRA_QRAFT_USER_ID}"
            )
            jira_user = JiraUser.objects.get(id=RAID_DEFAULT_JIRA_QRAFT_USER_ID)
    return jira_user