# Partner Role Classification

## Overview

Partner Role Classification allows a single business partner record to be designated as a CUSTOMER, a SUPPLIER, or both simultaneously. Rather than maintaining separate customer and vendor master records for the same real-world entity, the system attaches roles to one canonical partner record and tracks role-specific data alongside it.

This approach follows the SAP unified Business Partner (BP) model, which eliminates duplicate records and the reconciliation problems they create. A partner with no roles assigned is a valid state — for example, a newly created partner that has not yet been classified.

## Business Purpose

A unified role model provides practical advantages across finance and operations:

- **No duplicate records**: A manufacturer who is also a customer for returned goods does not require two separate master records, keeping data consistent and avoiding reconciliation overhead
- **Additive assignment**: Assigning the SUPPLIER role to an existing CUSTOMER partner does not remove the CUSTOMER role; roles accumulate independently
- **Controlled classification**: Only ACTIVE partners can have roles assigned or removed, preventing accidental classification of partners that are not yet fully set up
- **Flexible starting state**: Newly created partners carry no roles, allowing data entry to be completed before classification
- **Downstream filtering**: Systems consuming partner data (purchasing, sales, accounts payable, accounts receivable) can filter partners by role without joining separate entity tables

## Process Flow

Role assignment and removal share the same prerequisite — the partner must be ACTIVE:

```mermaid
flowchart TD
    A[Partner Created] --> B{Partner Status?}
    B -->|ACTIVE| C[Assign Role]
    B -->|INACTIVE / other| D[Return Error: PARTNER_NOT_ACTIVE]
    C --> E{Role already assigned?}
    E -->|Yes| F[No-op / Idempotent]
    E -->|No| G[Role Added to Partner]
    G --> H[Partner holds role]
```

A partner can accumulate both roles independently:

```mermaid
flowchart LR
    P[Partner]
    P -->|assignRole CUSTOMER| C[CUSTOMER role]
    P -->|assignRole SUPPLIER| S[SUPPLIER role]
    C & S -->|both present| B[Partner is CUSTOMER + SUPPLIER]
    B -->|removeRole CUSTOMER| S2[Partner is SUPPLIER only]
    B -->|removeRole SUPPLIER| C2[Partner is CUSTOMER only]
```

## Scenario Patterns

- **Pure customer**: A retail buyer is created and activated. The CUSTOMER role is assigned. The partner appears in sales order lookups but not in purchasing workflows.
- **Pure supplier**: A raw-material vendor is created and activated. The SUPPLIER role is assigned. The partner appears in purchase order lookups but not in sales workflows.
- **Dual role — same entity**: An existing CUSTOMER partner is discovered to also supply services. The SUPPLIER role is assigned without any change to the CUSTOMER role. The partner is now visible in both sales and purchasing workflows under the same record.
- **Role removal**: A supplier relationship ends. The SUPPLIER role is removed. The partner retains its CUSTOMER role and continues to appear in sales workflows.
- **Idempotent assignment**: Assigning CUSTOMER to a partner that already holds CUSTOMER produces no error and no duplicate.
- **Inactive partner guard**: Attempting to assign or remove a role on an INACTIVE partner is rejected, ensuring classification only occurs for properly onboarded partners.
- **Unclassified partner**: A partner is created but not yet approved for trading. No roles are assigned. The partner record exists in the system but does not appear in role-filtered lookups.

## Test Cases

- Assigning CUSTOMER to an ACTIVE partner with no roles should succeed and result in exactly one role: CUSTOMER
- Assigning SUPPLIER to an ACTIVE partner that already holds CUSTOMER should succeed and result in both roles present
- Assigning CUSTOMER to a partner that already holds CUSTOMER should be idempotent — no error, no duplicate
- Removing CUSTOMER from a partner that holds both CUSTOMER and SUPPLIER should leave SUPPLIER intact
- Removing a role from a partner that does not hold that role should be idempotent — no error
- Assigning a role to an INACTIVE partner should fail with PARTNER_NOT_ACTIVE error
- Removing a role from an INACTIVE partner should fail with PARTNER_NOT_ACTIVE error
- A newly created partner with no roles assigned is a valid state — no validation error
- Partners can be filtered by role; a partner holding both roles appears in results for both CUSTOMER and SUPPLIER queries
- Role assignment does not modify any other partner fields (name, status, identifiers)

## Reference Links

- [SAP Business Partner Roles](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f4b14f75b28e4af6acc6fc8a8cc25600/4631dda7ec8c6d1be10000000a42189d.html)
- [Odoo Contact Customer/Vendor Flags](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/products/vendor_bill.html)
- [Oracle Trading Community Architecture — Party Model](https://docs.oracle.com/en/applications/oracle-fusion-applications/implementation-guide/party-model.html)
