# AssignRoleToPartner

## Permission Scope

partner

## Overview

assignRoleToPartner assigns a business role (CUSTOMER or SUPPLIER) to an active partner. Roles determine which business processes a partner can participate in. A partner can hold multiple roles simultaneously (e.g., both CUSTOMER and SUPPLIER). The operation is idempotent — assigning a role that is already present does not produce an error.

## Business Rules

- Partner must exist in the system
- Partner must be in ACTIVE status
- Role must be a valid value (CUSTOMER or SUPPLIER)
- A partner can hold multiple roles simultaneously
- Assignment is idempotent — re-assigning an existing role succeeds without error

## Process Flow

```mermaid
flowchart TD
    A[Receive assign role request] --> B{Partner exists?}
    B -->|No| C[Return error: partner not found]
    B -->|Yes| D{Partner is ACTIVE?}
    D -->|No| E[Return error: partner not active]
    D -->|Yes| F{Role valid?}
    F -->|No| G[Return error: invalid role]
    F -->|Yes| H{Role already assigned?}
    H -->|Yes| I[Return success - idempotent]
    H -->|No| J[Assign role to partner]
    J --> K[Return updated partner]
```

## External Dependencies

- None

## Error Scenarios

- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
- **PARTNER_NOT_ACTIVE**: Partner is not in ACTIVE status
- **INVALID_ROLE**: Provided role is not one of CUSTOMER or SUPPLIER

## Test Cases

- assigns CUSTOMER to partner with no roles
- assigns SUPPLIER to partner that already holds CUSTOMER
- idempotent when role already assigned
- returns error when partner not found
- returns error when partner is INACTIVE
- returns error when partner is DRAFT
- returns error when role is invalid
