# ListPartnersByRole

## Overview

ListPartnersByRole retrieves all business partners that hold a specified role (CUSTOMER or SUPPLIER). This supports downstream filtering where systems consuming partner data (purchasing, sales, accounts payable, accounts receivable) need to list partners by their role classification.

## Business Rules

- Accepts `{ role, status? }` as input where role is CUSTOMER or SUPPLIER
- Role must be one of CUSTOMER or SUPPLIER; any other value is rejected
- When `status` is provided, returns only partners with the specified lifecycle status (DRAFT, ACTIVE, or INACTIVE); downstream modules that need partners for new transactions should pass `status = ACTIVE`
- When `status` is omitted, returns partners regardless of their lifecycle status (DRAFT, ACTIVE, INACTIVE)
- A partner holding both CUSTOMER and SUPPLIER roles appears in results for either query
- Returns an empty array when no partners match the criteria — not an error

## Process Flow

```mermaid
flowchart TD
    A[Receive input] --> B{Role is CUSTOMER or SUPPLIER?}
    B -->|No| C[Return error: invalid role]
    B -->|Yes| D{status filter provided?}
    D -->|Yes| E[SELECT partners via PartnerRole where role = input.role AND partner.status = input.status]
    D -->|No| F[SELECT partners via PartnerRole where role = input.role]
    E --> G{Any partners found?}
    F --> G
    G -->|Yes| H[Return partner records]
    G -->|No| I[Return empty array]
```

## External Dependencies

- None

## Error Scenarios

- **INVALID_ROLE**: Provided role is not one of CUSTOMER or SUPPLIER

## Test Cases

- returns all partners with CUSTOMER role
- returns all partners with SUPPLIER role
- returns only ACTIVE partners when status filter is ACTIVE
- returns partners of all statuses when status filter is omitted
- returns partner in both queries when partner holds both roles
- returns empty array when no partners match the criteria
- returns error for invalid role value
