# BusinessPartner

## Description

BusinessPartner is the unified entity representing any external party — customer, supplier, or both — with whom the organization conducts business. Partners are classified by type: ORGANIZATION (a legal entity such as a company) or INDIVIDUAL (a natural person). Each partner has a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE) that controls when the partner can be referenced in downstream transactions.

Partners are scoped to a company (via `companyId` from the organization module) and carry core master data such as name, type, and optional preferred transaction currency.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Draft: createPartner
    Draft --> Active: activatePartner
    Active --> Inactive: deactivatePartner
    Inactive --> Active: reactivatePartner
    Draft --> [*]: deletePartner
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| activatePartner | DRAFT | ACTIVE | [activatePartner](../commands/ActivatePartner.md) |
| deactivatePartner | ACTIVE | INACTIVE | [deactivatePartner](../commands/DeactivatePartner.md) |
| reactivatePartner | INACTIVE | ACTIVE | [reactivatePartner](../commands/ReactivatePartner.md) |

### Command Definitions

- [createPartner](../commands/CreatePartner.md) - Create a new business partner in DRAFT status
- [updatePartner](../commands/UpdatePartner.md) - Update mutable fields (name, preferredCurrencyId) of an existing partner
- [activatePartner](../commands/ActivatePartner.md) - Transition partner from DRAFT to ACTIVE
- [deactivatePartner](../commands/DeactivatePartner.md) - Transition partner from ACTIVE to INACTIVE
- [reactivatePartner](../commands/ReactivatePartner.md) - Transition partner from INACTIVE to ACTIVE
- [deletePartner](../commands/DeletePartner.md) - Permanently delete a DRAFT partner

### Query Definitions

- [GetPartner](../queries/GetPartner.md) - Retrieve a partner by id

### Models

- BusinessPartner

### Invariants

- Partner name is required and must be non-empty
- Partner type is required and must be either ORGANIZATION or INDIVIDUAL
- Partner type is immutable after creation
- Partners are always created in DRAFT status
- Only DRAFT partners can be deleted; ACTIVE and INACTIVE partners are preserved
- Only ACTIVE partners can be referenced in new downstream transactions (sales orders, purchase orders, invoices)
- Activating an already ACTIVE partner fails with an invalid status transition error
- Deactivating a DRAFT partner fails with an invalid status transition error
- Preferred currency, when provided, must reference a valid Currency from the primitives module
- Partners are scoped to a company; partners from different companies are isolated

### Relationships

- **References Company**: Each partner is scoped to a company via `companyId` from the organization module
- **References Currency**: Each partner optionally references a Currency from the primitives module as preferred transaction currency
- **Referenced By PartnerRole**: Partners hold zero or more roles (CUSTOMER, SUPPLIER) via PartnerRole
- **Referenced By PartnerBankAccount**: Partners hold zero or more bank accounts via PartnerBankAccount
- **Referenced By PartnerAddress**: Partners hold zero or more addresses via PartnerAddress
- **Referenced By PartnerIdentification**: Partners hold zero or more identification records via PartnerIdentification
- **Referenced By ContactPerson**: ORGANIZATION-type partners hold zero or more contact persons via ContactPerson
