# Partner Lifecycle

## Overview

The Business Partner is the unified entity representing any external party — customer, vendor, 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. All downstream modules — sales, purchasing, and accounting — reference the business partner as the authoritative counterparty record.

## Business Purpose

Organizations need a single source of truth for counterparty master data to avoid duplication and ensure consistency across transaction domains:

- **Unified counterparty record**: A single partner entity can act as both customer and vendor, eliminating redundant records
- **Type distinction**: Separating ORGANIZATION and INDIVIDUAL partners enables different compliance, tax, and legal handling
- **Lifecycle gating**: Only ACTIVE partners can be referenced in new transactions, preventing accidental use of incomplete or retired records
- **Company scoping**: Partners are isolated per company, supporting multi-tenant and multi-entity deployments
- **Audit preservation**: INACTIVE partners are retained for historical reference rather than deleted

## Process Flow

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

## Scenario Patterns

- **New Vendor Onboarding**: A procurement team creates a new ORGANIZATION partner in DRAFT, validates the legal name and tax details, then activates it before issuing the first purchase order
- **New Individual Customer**: A sales team creates an INDIVIDUAL partner in DRAFT for a sole trader, completes KYC review, and activates before raising a sales order
- **Partner Retirement**: A vendor is no longer used; the partner is deactivated to prevent new transactions while preserving full history on past orders
- **Reactivated Supplier**: A previously inactive supplier resumes business; the partner is reactivated rather than creating a duplicate record
- **Draft Cleanup**: An incomplete partner record created in error is deleted while still in DRAFT status before it enters any transactions
- **Dual-Role Partner**: A single ORGANIZATION partner is classified as both customer and vendor through partner-role-classification, referencing the same lifecycle-managed record

## Test Cases

- Partner lifecycle follows DRAFT → ACTIVE ↔ INACTIVE state machine
- Partners can only be created in DRAFT status
- Partner name is required and must be non-empty
- Partner type is required and must be either ORGANIZATION or INDIVIDUAL
- Only DRAFT partners can be deleted; ACTIVE and INACTIVE partners cannot
- Only ACTIVE partners can be referenced in new downstream transactions (sales orders, purchase orders, invoices)
- Activating a DRAFT partner transitions status to ACTIVE
- Activating an already ACTIVE partner fails with an invalid status transition error
- Deactivating an ACTIVE partner transitions status to INACTIVE
- Deactivating a DRAFT partner fails with an invalid status transition error
- Reactivating an INACTIVE partner transitions status to ACTIVE
- Partners are scoped to a company; partners from different companies are isolated
- Preferred transaction currency, when provided, must reference a valid currency from the primitives module

## Reference Links

- [SAP Business Partner Concept](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f325a3e3a5514e85aab72db8bab710c8/4b0a1e1c2d6b3e41e10000000a42189c.html)
- [Odoo Contacts (res.partner)](https://www.odoo.com/documentation/19.0/applications/contacts.html)
- [ISO 17442 Legal Entity Identifier (LEI)](https://www.iso.org/standard/59771.html)
