# CreatePartner

## Permission Scope

partner

## Overview

createPartner establishes a new business partner in the system. Partners represent external entities (organizations or individuals) with which the company conducts business. Every partner is created in DRAFT status, allowing review and enrichment before activation. The partner type (ORGANIZATION or INDIVIDUAL) is set at creation and cannot be changed afterward.

## Business Rules

- Name is required and must be non-empty
- Type is required and must be one of ORGANIZATION or INDIVIDUAL
- Type is immutable after creation — it cannot be changed once assigned
- Partner is always created in DRAFT status regardless of input
- Preferred currency, if provided, must reference an existing Currency in the primitives module
- Company ID must reference an existing Company in the organization module

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Company exists?}
    B -->|No| C[Return error: company not found]
    B -->|Yes| D{Name non-empty?}
    D -->|No| E[Return error: invalid name]
    D -->|Yes| F{Type valid?}
    F -->|No| G[Return error: invalid partner type]
    F -->|Yes| H{Currency provided?}
    H -->|Yes| I{Currency exists?}
    I -->|No| J[Return error: currency not found]
    I -->|Yes| K[Create partner in DRAFT status]
    H -->|No| K
    K --> L[Return created partner]
```

## External Dependencies

- [organization::Company](../../../organization/docs/models/Company.md) - Validates that the referenced company exists
- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates that the referenced preferred currency exists (when provided)

## Error Scenarios

- **COMPANY_NOT_FOUND**: Specified company ID does not exist
- **INVALID_NAME**: Name is empty, whitespace-only, or not provided
- **INVALID_PARTNER_TYPE**: Type is not ORGANIZATION or INDIVIDUAL
- **CURRENCY_NOT_FOUND**: Referenced currency does not exist

## Test Cases

- creates partner in DRAFT status
- returns error when company not found
- returns error when type is invalid
- returns error when name is empty
- creates partner without preferred currency
- creates partner with preferred currency
- returns error when currency not found
