@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/modules/business-partner/docs/features/partner-lifecycle.md

@@ -0,0 +1,59 @@
+# 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)

package/src/modules/business-partner/docs/features/partner-role-classification.md

@@ -0,0 +1,73 @@
+# 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)

package/src/modules/business-partner/docs/models/BusinessPartner.md

@@ -0,0 +1,64 @@
+# 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
+```
+
+### 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

package/src/modules/business-partner/docs/models/ContactPerson.md

@@ -0,0 +1,62 @@
+# 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)
+```
+
+### 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

package/src/modules/business-partner/docs/models/PartnerAddress.md

@@ -0,0 +1,52 @@
+# PartnerAddress
+
+## Description
+
+PartnerAddress is a child entity of BusinessPartner that stores structured addresses classified by purpose (BILLING, SHIPPING, REGISTERED, or OTHER). Each address carries the same structured format as the organization module's Site entity: line1, line2, city, state, postalCode, and country (ISO 3166-1 alpha-2). One address per partner per address type may be designated as the default.
+
+Adding new addresses requires the partner to be in DRAFT or ACTIVE state; INACTIVE partners may only have existing addresses read or updated.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createPartnerAddress](../commands/CreatePartnerAddress.md) - Add an address to a partner
+- [updatePartnerAddress](../commands/UpdatePartnerAddress.md) - Update address fields
+- [deletePartnerAddress](../commands/DeletePartnerAddress.md) - Remove an address (with referential integrity check)
+- [setDefaultPartnerAddress](../commands/SetDefaultPartnerAddress.md) - Designate an address as the default for its type
+
+### Query Definitions
+
+- [GetPartnerAddress](../queries/GetPartnerAddress.md) - Retrieve an address by id
+- [GetDefaultPartnerAddress](../queries/GetDefaultPartnerAddress.md) - Retrieve the default address for a partner and address type
+- [ListPartnerAddressesByPartner](../queries/ListPartnerAddressesByPartner.md) - List addresses for a partner with optional type filter
+
+### Models
+
+- PartnerAddress
+
+### Invariants
+
+- `line1`, `city`, `postalCode`, `country`, and `addressType` are required at creation
+- `line2` and `state` are optional
+- `country` must be a valid ISO 3166-1 alpha-2 code
+- `addressType` must be one of BILLING, SHIPPING, REGISTERED, OTHER
+- `addressType` is immutable after creation; changing type requires deleting the old address and creating a new one
+- A partner may hold multiple addresses of the same type
+- Only one address per partner per addressType may be marked as default at any time
+- A partner can have independent defaults for BILLING, SHIPPING, REGISTERED, and OTHER simultaneously
+- Setting isDefault = true for an addressType automatically unsets isDefault on the previous default of the same type for the same partner
+- Deleting the default address does not automatically promote another address of the same type to default; no default exists until one is explicitly set
+- Deleting an address referenced on historical or open transactions is rejected (referential integrity)
+- Adding new addresses requires the partner to be in DRAFT or ACTIVE state; adding to an INACTIVE partner is rejected
+- Reading and updating existing addresses is permitted regardless of partner status (DRAFT, ACTIVE, or INACTIVE)
+- A partner with no addresses returns an empty list, not an error
+- When no default address exists for a requested type, the system returns an error rather than silently picking an arbitrary address
+
+### Relationships
+
+- **References BusinessPartner**: Each address belongs to exactly one BusinessPartner

package/src/modules/business-partner/docs/models/PartnerBankAccount.md

@@ -0,0 +1,50 @@
+# PartnerBankAccount
+
+## Description
+
+PartnerBankAccount is a child entity of BusinessPartner that stores the banking details required to execute financial transactions with that partner. Each record captures bank name, account holder name, account number, routing number, IBAN, SWIFT/BIC, and transaction currency. A partner may hold multiple bank accounts, and one account per partner may be designated as the default.
+
+Bank account records can be created and maintained regardless of the partner's current lifecycle state (DRAFT, ACTIVE, or INACTIVE).
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createPartnerBankAccount](../commands/CreatePartnerBankAccount.md) - Add a bank account to a partner
+- [updatePartnerBankAccount](../commands/UpdatePartnerBankAccount.md) - Update bank account details
+- [deletePartnerBankAccount](../commands/DeletePartnerBankAccount.md) - Remove a bank account from a partner
+- [setDefaultPartnerBankAccount](../commands/SetDefaultPartnerBankAccount.md) - Designate a bank account as the default for a partner
+
+### Query Definitions
+
+- [GetPartnerBankAccount](../queries/GetPartnerBankAccount.md) - Retrieve a bank account by id
+- [GetDefaultPartnerBankAccount](../queries/GetDefaultPartnerBankAccount.md) - Retrieve the default bank account for a partner
+- [ListPartnerBankAccountsByPartner](../queries/ListPartnerBankAccountsByPartner.md) - List all bank accounts for a partner
+
+### Models
+
+- PartnerBankAccount
+
+### Invariants
+
+- `bankName` is required and must be non-empty
+- `accountHolderName` is required and must be non-empty
+- At least one of `accountNumber` or `iban` must be provided; both may be provided simultaneously
+- `routingNumber` is optional (domestic routing conventions)
+- `swiftBic` is optional (international transfers)
+- `currencyId` must reference a valid, existing Currency from the primitives module
+- Bank accounts can be added to a partner in any lifecycle state (DRAFT, ACTIVE, or INACTIVE)
+- At most one bank account per partner can be designated as default at any time
+- Marking a bank account as default automatically unsets the default flag on all other accounts for that partner
+- The first bank account added to a partner is automatically designated as the default
+- Removing the default bank account does not automatically promote another account; the partner has no default until one is explicitly designated
+- Bank accounts are isolated per partner; accounts belonging to one partner are not visible on another
+
+### Relationships
+
+- **References BusinessPartner**: Each bank account belongs to exactly one BusinessPartner
+- **References Currency**: Each bank account references a Currency from the primitives module

package/src/modules/business-partner/docs/models/PartnerIdentification.md

@@ -0,0 +1,46 @@
+# PartnerIdentification
+
+## Description
+
+PartnerIdentification is a child entity of BusinessPartner that stores official registration numbers — tax IDs, VAT numbers, DUNS numbers, company registry codes, national IDs, and other identification documents. Each record captures the type, value, and optional metadata including issuing country and validity period.
+
+Uniqueness is enforced on the combination of (type, value) within a company scope. Identifications can be added at any point in the partner's lifecycle.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createPartnerIdentification](../commands/CreatePartnerIdentification.md) - Add an identification record to a partner
+- [updatePartnerIdentification](../commands/UpdatePartnerIdentification.md) - Update identification details
+- [deletePartnerIdentification](../commands/DeletePartnerIdentification.md) - Remove an identification record
+
+### Query Definitions
+
+- [GetPartnerIdentification](../queries/GetPartnerIdentification.md) - Retrieve an identification record by id
+- [ListPartnerIdentificationsByPartner](../queries/ListPartnerIdentificationsByPartner.md) - List all identification records for a partner
+
+### Models
+
+- PartnerIdentification
+
+### Invariants
+
+- `type` and `value` are both required; records missing either field are rejected
+- Supported types are: TAX_ID, VAT, DUNS, COMPANY_REGISTRY, NATIONAL_ID, OTHER
+- The combination of (type, value) must be unique within the company scope (cross-company deduplication is not enforced)
+- Two partners within the same company may not share an identification record with the same (type, value) combination
+- A single partner can hold multiple identification records with different types
+- `type` is immutable after creation; changing the identification type requires deleting the existing record and creating a new one
+- `issuingCountry`, `validFrom`, and `validTo` are optional and may be omitted
+- When both `validFrom` and `validTo` are set, `validTo` must be equal to or later than `validFrom`
+- Identifications can be added to partners in any lifecycle state (DRAFT, ACTIVE, INACTIVE)
+- Updating an identification's value must re-validate the (type, value) uniqueness constraint
+- Deleting an identification record does not affect the parent partner or other identifications
+
+### Relationships
+
+- **References BusinessPartner**: Each identification record belongs to exactly one BusinessPartner

package/src/modules/business-partner/docs/models/PartnerRole.md

@@ -0,0 +1,42 @@
+# PartnerRole
+
+## Description
+
+PartnerRole is a child entity that assigns a role classification (CUSTOMER or SUPPLIER) to a business partner. A single partner can hold multiple roles simultaneously — for example, both CUSTOMER and SUPPLIER — without record duplication. Role assignment is additive and follows the SAP unified Business Partner model.
+
+Roles can only be assigned to or removed from ACTIVE partners. A partner with no roles is a valid state.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [assignRoleToPartner](../commands/AssignRoleToPartner.md) - Assign a CUSTOMER or SUPPLIER role to an ACTIVE partner
+- [removeRoleFromPartner](../commands/RemoveRoleFromPartner.md) - Remove a role from an ACTIVE partner
+
+### Query Definitions
+
+- [GetPartnerRole](../queries/GetPartnerRole.md) - Retrieve a role assignment by partnerId and role
+- [ListPartnersByRole](../queries/ListPartnersByRole.md) - List all partners holding a specified role
+
+### Models
+
+- PartnerRole
+
+### Invariants
+
+- Role must be one of CUSTOMER or SUPPLIER
+- The combination of (partnerId, role) must be unique — no duplicate role assignments
+- Roles can only be assigned to or removed from ACTIVE partners; assigning or removing a role on a DRAFT or INACTIVE partner is rejected
+- Assigning a role that is already held is idempotent — no error, no duplicate
+- Removing a role that is not held is idempotent — no error
+- A partner with no roles assigned is a valid state
+- Role assignment does not modify any other partner fields (name, status, identifiers)
+- Partners can be filtered by role; a partner holding both roles appears in results for both CUSTOMER and SUPPLIER queries
+
+### Relationships
+
+- **References BusinessPartner**: Each role assignment belongs to exactly one BusinessPartner

package/src/modules/business-partner/docs/queries/GetContactPerson.md

@@ -0,0 +1,34 @@
+# GetContactPerson
+
+## Overview
+
+GetContactPerson retrieves a single contact person record by id. This serves as the lookup for update, deactivate, reactivate, delete, and setPrimary contact person commands.
+
+## Business Rules
+
+- Accepts `{ id }` as input — retrieves by unique identifier
+- Returns the full ContactPerson record or null if no matching contact person is found
+- Used by update, deactivate, reactivate, delete, and setPrimary commands to verify the contact person exists before operating on it
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from ContactPerson where id = input.id]
+    B --> C{Contact person found?}
+    C -->|Yes| D[Return contact person record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CONTACT_PERSON_NOT_FOUND**: No contact person matches the given id — caller receives null
+
+## Test Cases
+
+- returns contact person when found
+- returns null when not found

package/src/modules/business-partner/docs/queries/GetDefaultPartnerAddress.md

@@ -0,0 +1,40 @@
+# GetDefaultPartnerAddress
+
+## Overview
+
+GetDefaultPartnerAddress retrieves the default address for a partner and address type. This is used by downstream modules (AP, order management, shipping) to resolve the relevant default address for a given business partner.
+
+## Business Rules
+
+- Accepts `{ partnerId, addressType }` as input — retrieves the address with isDefault=true for the given partner and type
+- Returns the PartnerAddress record where isDefault is true for the specified address type
+- At most one address per partner per address type can be marked as default
+- When no default address exists for the requested type, returns an error — the caller must either set a default or select an address explicitly
+- When the partner has no addresses of the given type, returns an error indicating no address of that type exists
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerAddress where partnerId = input.partnerId AND addressType = input.addressType AND isDefault = true]
+    B --> C{Default address found?}
+    C -->|Yes| D[Return address record]
+    C -->|No| E{Any address of this type exists?}
+    E -->|Yes| F[Return error: no default set — caller must select explicitly]
+    E -->|No| G[Return error: no address of this type exists]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NO_DEFAULT_ADDRESS**: Addresses of the requested type exist for the partner, but none is marked as default — the caller must set a default or select an address explicitly
+- **NO_ADDRESS_OF_TYPE**: The partner has no addresses of the requested address type
+
+## Test Cases
+
+- returns default address when one exists
+- returns error when addresses of the type exist but no default is set
+- returns error when partner has no addresses of the given type

package/src/modules/business-partner/docs/queries/GetDefaultPartnerBankAccount.md

@@ -0,0 +1,36 @@
+# GetDefaultPartnerBankAccount
+
+## Overview
+
+GetDefaultPartnerBankAccount retrieves the default bank account for a partner. This is used by downstream payment modules to resolve the default payment account for a given business partner.
+
+## Business Rules
+
+- Accepts `{ partnerId }` as input — retrieves the bank account with isDefault=true for the given partner
+- Returns the PartnerBankAccount record where isDefault is true, or null if no default is set
+- At most one bank account per partner can be marked as default
+- Returns null when the partner has no bank accounts at all
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerBankAccount where partnerId = input.partnerId AND isDefault = true]
+    B --> C{Default bank account found?}
+    C -->|Yes| D[Return bank account record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- No explicit error — returns null when no default bank account exists
+
+## Test Cases
+
+- returns default bank account when one exists
+- returns null when no default is set
+- returns null when partner has no bank accounts

package/src/modules/business-partner/docs/queries/GetPartner.md

@@ -0,0 +1,35 @@
+# GetPartner
+
+## Overview
+
+GetPartner retrieves a single business partner record by id. This serves as the core partner lookup for existence checks, state validation, and all partner lifecycle commands.
+
+## Business Rules
+
+- Accepts `{ id }` as input — retrieves by unique identifier
+- Returns the full partner record including all fields (id, companyId, name, type, status, preferredCurrencyId, timestamps)
+- Returns null if no matching partner is found
+- All comparisons are exact (case-sensitive)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from Partner where id = input.id]
+    B --> C{Partner found?}
+    C -->|Yes| D[Return partner record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: No partner matches the given id — caller receives null
+
+## Test Cases
+
+- returns partner when found by id
+- returns null when partner not found

package/src/modules/business-partner/docs/queries/GetPartnerAddress.md

@@ -0,0 +1,34 @@
+# GetPartnerAddress
+
+## Overview
+
+GetPartnerAddress retrieves a single address record by id. This serves as the lookup for update, delete, and setDefault address commands.
+
+## Business Rules
+
+- Accepts `{ id }` as input — retrieves by unique identifier
+- Returns the full PartnerAddress record or null if no matching address is found
+- Used by update, delete, and setDefault commands to verify the address exists before operating on it
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive input] --> B[SELECT from PartnerAddress where id = input.id]
+    B --> C{Address found?}
+    C -->|Yes| D[Return address record]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADDRESS_NOT_FOUND**: No address matches the given id — caller receives null
+
+## Test Cases
+
+- returns address when found
+- returns null when not found