# ContactPerson

## Description

ContactPerson is a child entity of an ORGANIZATION-type BusinessPartner that tracks individual people who represent that organization. Each contact person carries their own identifying information (firstName, lastName, email, phone, jobTitle, department) and maintains an independent ACTIVE/INACTIVE status.

One contact person per organization can be designated as the primary contact. Contact persons are not business partners themselves — they are named individuals who act on behalf of a partner organization.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Active: createContactPerson
    Active --> Inactive: deactivateContactPerson
    Inactive --> Active: reactivateContactPerson
    Active --> [*]: deleteContactPerson (only when not primary)
```

| Operation | From | To | Command |
|-----------|------|----|---------|
| deactivate | ACTIVE | INACTIVE | [deactivateContactPerson](../commands/DeactivateContactPerson.md) |
| reactivate | INACTIVE | ACTIVE | [reactivateContactPerson](../commands/ReactivateContactPerson.md) |

### Command Definitions

- [createContactPerson](../commands/CreateContactPerson.md) - Add a contact person to an ORGANIZATION-type partner
- [updateContactPerson](../commands/UpdateContactPerson.md) - Update contact person details
- [deactivateContactPerson](../commands/DeactivateContactPerson.md) - Transition contact person from ACTIVE to INACTIVE
- [reactivateContactPerson](../commands/ReactivateContactPerson.md) - Transition contact person from INACTIVE to ACTIVE
- [deleteContactPerson](../commands/DeleteContactPerson.md) - Permanently delete a non-primary contact person
- [setPrimaryContactPerson](../commands/SetPrimaryContactPerson.md) - Designate a contact person as the primary for the organization

### Query Definitions

- [GetContactPerson](../queries/GetContactPerson.md) - Retrieve a contact person by id
- [GetPrimaryContactPerson](../queries/GetPrimaryContactPerson.md) - Retrieve the primary contact person for a partner
- [ListContactPersonsByPartner](../queries/ListContactPersonsByPartner.md) - List all contact persons for an organization partner

### Models

- ContactPerson

### Invariants

- Contact persons can only be linked to ORGANIZATION-type partners; linking to an INDIVIDUAL-type partner is rejected
- `firstName` and `lastName` are required
- `email`, `phone`, `jobTitle`, and `department` are optional; however at least one communication channel (`email` or `phone`) must be provided
- Email format must be validated on creation and update
- Contact persons are created with ACTIVE status by default
- An ACTIVE contact person can be deactivated; an INACTIVE contact person can be reactivated
- At most one contact person per organization may hold primary contact designation at any given time
- Designating a new primary contact automatically removes the designation from the previous primary contact
- A contact person marked as primary cannot be deleted; the primary designation must be transferred first
- Deactivating a primary contact person removes their primary designation; the organization has no primary contact until one is explicitly set
- Multiple contact persons with distinct roles may exist under the same organization
- Updating a contact person's details does not change their organization association or primary status
- Listing contact persons for an organization returns only those linked to that specific organization

### Relationships

- **References BusinessPartner**: Each contact person belongs to exactly one ORGANIZATION-type BusinessPartner
