# Partner Address Management

## Overview

PartnerAddress is a reusable child entity in the global BusinessPartner aggregate. It remains in a separate database table, while create, update, deactivate, and reactivate operations go through the owning aggregate. It contains only location facts: line1, line2, city, state, postalCode, and ISO 3166-1 alpha-2 country.

Business purpose is account-specific and is therefore stored separately:

- CustomerAddressUsage assigns an address to BILL_TO or SHIP_TO.
- SupplierAddressUsage assigns an address to ORDER_FROM, REMIT_TO, SHIP_FROM, or RETURN_TO.
- Each Account may designate at most one default address per purpose.

The same physical address can be reused by several customer or supplier accounts without duplicating the address record.

## Business Purpose

- The parent BusinessPartner must exist.
- New addresses may be added only while the partner's `active` flag is `true`.
- New addresses start with `active=true` and are deactivated rather than physically deleted.
- Inactive addresses remain readable for historical references but cannot be assigned to new Account usages.
- line1, city, postalCode, and country are required.
- country must be a two-letter uppercase country code.
- PartnerAddress does not contain purpose, account scope, or default state.
- A usage may reference only an address owned by the usage Account's BusinessPartner.
- Default uniqueness is enforced per Account and purpose.

## Process Flow

```mermaid
flowchart TD
    A[Create reusable PartnerAddress] --> B[Create or update Account]
    B --> C[Assign address through AddressUsage]
    C --> D[Choose account-specific purpose]
    D --> E{Default for purpose?}
    E --> F[Persist usage]
```

## Scenario Patterns

- A customer account uses one reusable address as BILL_TO and another as SHIP_TO.
- Several supplier accounts reuse the same registered address with different purposes.
- A new default is selected for one account and purpose without changing other accounts.

## Test Cases

- An address cannot be created without an existing partner.
- Required address fields and the country code are validated.
- An inactive partner cannot receive a new address.
- Listing partner addresses returns reusable address records without usage fields.
- Account creation rejects an address owned by a different partner.
- An Account cannot have multiple defaults for the same address purpose.

## Reference Links

- [PartnerAddress](../model/PartnerAddress.md)
- [CustomerAddressUsage](../model/CustomerAddressUsage.md)
- [SupplierAddressUsage](../model/SupplierAddressUsage.md)