# CreatePartnerAddress

## Permission Scope

partnerDetail

## Overview

createPartnerAddress adds reusable physical or mailing address data through the owning BusinessPartner aggregate. Addresses can be added only while the partner has `status=ACTIVE`. Account-specific purposes such as BILL_TO, SHIP_TO, or REMIT_TO and default selection are modeled in CustomerAddressUsage and SupplierAddressUsage.

## Business Rules

- Partner must exist in the system
- The owning BusinessPartner aggregate is loaded with a row lock before the address is added
- Partner must have `status=ACTIVE`
- Line1, city, postal code, and country are required
- Country must contain exactly two uppercase ASCII letters; validation checks the format without looking up assigned country codes
- Address purpose and default selection are not stored on PartnerAddress

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> A1[Lock and load BusinessPartner aggregate]
    A1 --> B{Partner exists?}
    B -->|No| C[Return error: partner not found]
    B -->|Yes| D{Partner active?}
    D -->|No| E[Return error: partner inactive]
    D -->|Yes| H1{line1, city, postalCode non-empty?}
    H1 -->|No| H2[Return error: missing required address field]
    H1 -->|Yes| H{Country code valid?}
    H -->|No| I[Return error: invalid country code]
    H -->|Yes| L[Add reusable address to aggregate]
    L --> M[Save aggregate and return address ID]
```

## External Dependencies

- None

## Error Scenarios

- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
- **PARTNER_INACTIVE**: Partner status is `INACTIVE`
- **MISSING_REQUIRED_ADDRESS_FIELD**: One or more required fields (line1, city, postalCode) are empty or not provided
- **INVALID_COUNTRY_CODE**: Country does not contain exactly two uppercase ASCII letters

## Test Cases

- adds an address through the BusinessPartner aggregate
- returns error when the partner does not exist
- rejects adding an address to an inactive partner
- rejects missing required address fields
- rejects an invalid country code