# README

## Overview

The Business Partner module manages the master data for all external parties the organization transacts with — suppliers, customers, or both. It provides a unified business partner entity following SAP's Business Partner model, where a single record can hold multiple roles (CUSTOMER, SUPPLIER) without duplication. Each partner is classified by type (ORGANIZATION or INDIVIDUAL), carries its own lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE), and is scoped to a company.

Partners serve as the authoritative counterparty reference for all downstream transactional modules. Sales orders reference a partner as the customer; purchase orders reference a partner as the supplier; accounting entries reference partners for accounts payable and receivable. The module also manages partner-owned sub-entities: addresses (billing, shipping, registered), contact persons (individuals at an organization), bank accounts (for AP/AR payments), and identification documents (tax IDs, VAT numbers, DUNS).

## Key Features

- **[Partner Lifecycle](docs/features/partner-lifecycle.md)**: Unified business partner entity with type distinction (ORGANIZATION/INDIVIDUAL), lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE), and core master data. The central entity that all downstream modules reference as the counterparty
- **[Partner Address Management](docs/features/partner-address-management.md)**: Multiple addresses per partner with type classification (BILLING, SHIPPING, REGISTERED, OTHER). Structured address format consistent with organization's Site addresses but separately owned for external parties
- **[Contact Person Management](docs/features/contact-person-management.md)**: Link individual contacts to their parent organization with name, email, phone, job title, and primary contact designation. Contact persons are sub-entities of ORGANIZATION-type partners, distinct from user-management login accounts
- **[Partner Role Classification](docs/features/partner-role-classification.md)**: Assign roles (CUSTOMER, SUPPLIER) to a partner additively. A single partner can serve multiple roles without record duplication, following SAP's unified BP model
- **[Partner Bank Account](docs/features/partner-bank-account.md)**: Store partner banking details (bank name, account number, routing, IBAN/SWIFT) for AP/AR payments. Multiple accounts per partner with default designation and currency reference
- **[Partner Identification](docs/features/partner-identification.md)**: Store tax IDs, VAT numbers, DUNS, company registry numbers, and other identification documents per partner. Supports multiple identification types with optional validity periods

## Module Scope

### In Scope

- Business partner master data management (create, update, delete, status transitions)
- Partner type distinction (ORGANIZATION and INDIVIDUAL)
- Partner lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE)
- Company-scoped partner records (each partner belongs to a company)
- Multiple addresses per partner with type classification and default designation
- Contact person management for ORGANIZATION-type partners
- Role classification (CUSTOMER, SUPPLIER) with additive assignment
- Bank account storage with default designation and currency reference
- Identification document storage (tax IDs, VAT, DUNS, etc.) with uniqueness enforcement

### Out of Scope

- Customer relationship management and sales pipeline (CRM module)
- Lead/prospect qualification and conversion workflows (CRM module)
- Supplier onboarding workflows with approval gates (`purchase` module)
- Supplier qualification, certification, and performance scoring (`purchase` module)
- Supplier catalog — linking suppliers to items they supply (`purchase` module)
- Payment term and pricing rule definitions (`purchase` module); business-partner may still expose supplier defaults or references consumed by purchase
- Duplicate detection and automated merge (future enhancement)
- Partner portal and self-service capabilities (future enhancement)
- Activity logging — calls, emails, meetings, notes (CRM module)
- Know Your Customer (KYC) and sanctions screening workflows (compliance module)

### Scope Decision Rationale

Business-partner is scoped to **external party master data** — the "who we transact with" foundation. It owns the identity, classification, and contact details of every customer, supplier, or dual-role partner the organization deals with. This is separated from internal organizational structure (organization module) because external parties have fundamentally different lifecycles, data requirements, and access patterns than internal entities like companies, departments, and sites.

The unified partner model (one entity with role classification rather than separate Customer and Supplier entities) follows the SAP Business Partner pattern. This prevents duplicate records when the same company is both a customer and a supplier, simplifies address and contact management, and provides a single reference point for downstream modules.

Addresses are included here rather than in the organization module because partner addresses belong to external parties (billing/shipping for customers and suppliers), while organization's Site addresses belong to company-owned facilities. The address structure is consistent across both modules, but ownership and semantics differ.

Contact persons are included because knowing who to communicate with at a partner organization is core master data, not a CRM concern. However, activity tracking (logging calls, meetings, emails) is excluded as CRM functionality.

Supplier catalog (which suppliers provide which items), payment term definitions, and pricing are excluded because they involve transactional business rules that change at different rates than partner master data. A supplier catalog naturally fits in the purchase module where it integrates with PO workflows. Purchase also owns payment-term and pricing definitions because they directly drive supplier-facing procurement documents, while business-partner may only expose supplier defaults or references that purchase consumes.

## Module Dependencies

- [organization](../organization/README.md) — Company reference for partner scoping (each partner belongs to a company)
- [primitives](../primitives/README.md) — Currency definitions for bank account currency assignment
