# CreatePartnerBankAccount

## Permission Scope

partnerDetail

## Overview

createPartnerBankAccount adds a bank account to a business partner. Bank accounts store banking details needed for financial transactions such as payments and receivables. At least one account identifier (accountNumber or iban) is required. The first bank account added to a partner is automatically designated as the default. Bank accounts can be added regardless of the partner's lifecycle status (DRAFT, ACTIVE, or INACTIVE), allowing finance teams to prepare or retain payment details at any stage.

## Business Rules

- Partner must exist in the system
- Partner status is not checked — bank accounts can be added in any lifecycle state (DRAFT, ACTIVE, or INACTIVE)
- Bank name is required and must be non-empty
- Account holder name is required and must be non-empty
- At least one of accountNumber or iban must be provided
- `routingNumber` is optional — used for domestic routing conventions (e.g., ACH/wire)
- `swiftBic` is optional — used for international transfers
- Currency must reference an existing Currency in the primitives module
- The first bank account added to a partner is automatically set as default
- Subsequent bank accounts are created as non-default

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Partner exists?}
    B -->|No| C[Return error: partner not found]
    B -->|Yes| D{Bank name non-empty?}
    D -->|No| E[Return error: invalid bank name]
    D -->|Yes| F{Account holder name non-empty?}
    F -->|No| G[Return error: invalid account holder name]
    F -->|Yes| H{accountNumber or iban provided?}
    H -->|No| I[Return error: missing account identifier]
    H -->|Yes| J{Currency exists?}
    J -->|No| K[Return error: currency not found]
    J -->|Yes| L{First account for partner?}
    L -->|Yes| M[Create bank account as default]
    L -->|No| N[Create bank account as non-default]
    M --> O[Return created bank account]
    N --> O
```

## External Dependencies

- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates that the referenced currency exists

## Error Scenarios

- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
- **MISSING_ACCOUNT_IDENTIFIER**: Neither accountNumber nor iban was provided
- **INVALID_BANK_NAME**: Bank name is empty, whitespace-only, or not provided
- **INVALID_ACCOUNT_HOLDER_NAME**: Account holder name is empty, whitespace-only, or not provided

## Test Cases

- creates bank account for partner
- creates bank account with iban
- creates bank account with both accountNumber and iban
- creates bank account with routingNumber
- creates bank account with swiftBic
- creates bank account for DRAFT partner
- creates bank account for INACTIVE partner
- auto-sets first account as default
- does not set default when partner already has accounts
- returns error when partner not found
- returns error when bank name is empty
- returns error when account holder name is empty
- returns error when neither account number nor iban provided
- returns error when currency not found
