@tailor-platform/erp-kit 0.3.0 → 0.4.1

package/src/modules/business-partner/docs/commands/UpdateContactPerson.md

@@ -0,0 +1,66 @@
+# UpdateContactPerson
+
+## Overview
+
+updateContactPerson modifies the details of an existing contact person. All fields are optional, but validation rules are enforced for any provided values. The contact person's association with its organization partner cannot be changed. After the update, at least one communication channel (email or phone) must remain present.
+
+## Business Rules
+
+- Contact person must exist in the system
+- First name, if provided, must be non-empty and not whitespace-only
+- Last name, if provided, must be non-empty and not whitespace-only
+- Email, if provided, must be in a valid format
+- After update, at least one of email or phone must still be present (whitespace-only values do not count)
+- The organization association is immutable and cannot be changed
+- The primary contact designation (isPrimary) is not modifiable through this command; it is preserved as-is
+- Only provided fields are updated; omitted fields retain their current values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Contact person exists?}
+    B -->|No| C[Return error: contact person not found]
+    B -->|Yes| B2{firstName provided?}
+    B2 -->|Yes| B3{firstName non-empty after trim?}
+    B3 -->|No| B4[Return error: invalid first name]
+    B3 -->|Yes| B5{lastName provided?}
+    B2 -->|No| B5
+    B5 -->|Yes| B6{lastName non-empty after trim?}
+    B6 -->|No| B7[Return error: invalid last name]
+    B6 -->|Yes| D{Email provided?}
+    B5 -->|No| D
+    D -->|Yes| E{Email format valid?}
+    E -->|No| F[Return error: invalid email format]
+    E -->|Yes| G{At least one communication channel remains?}
+    D -->|No| G
+    G -->|No| H[Return error: missing communication channel]
+    G -->|Yes| I[Update contact person record]
+    I --> J[Return updated contact person]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CONTACT_PERSON_NOT_FOUND**: Specified contact person ID does not exist
+- **INVALID_FIRST_NAME**: Provided first name is empty or whitespace-only
+- **INVALID_LAST_NAME**: Provided last name is empty or whitespace-only
+- **INVALID_EMAIL_FORMAT**: Provided email is not in a valid format
+- **MISSING_COMMUNICATION_CHANNEL**: Update would result in neither email nor phone being present
+
+## Test Cases
+
+- updates contact person details
+- returns error when contact not found
+- returns error when first name is empty
+- returns error when first name is whitespace-only
+- returns error when last name is empty
+- returns error when last name is whitespace-only
+- returns error when email format is invalid
+- returns error when update would leave no communication channel
+- returns error when whitespace-only phone would leave no communication channel
+- does not change organization association
+- preserves primary contact designation

package/src/modules/business-partner/docs/commands/UpdatePartner.md

@@ -0,0 +1,48 @@
+# UpdatePartner
+
+## Overview
+
+updatePartner modifies the mutable fields of an existing business partner. Only name and preferred currency can be updated. The partner type remains immutable after creation. This command supports incremental enrichment of partner data throughout the partner lifecycle.
+
+## Business Rules
+
+- Partner must exist in the system
+- Name, if provided, must be non-empty
+- Preferred currency, if provided, must reference an existing Currency in the primitives module
+- Partner type cannot be changed via this command
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Partner exists?}
+    B -->|No| C[Return error: partner not found]
+    B -->|Yes| D{Name provided?}
+    D -->|Yes| E{Name non-empty?}
+    E -->|No| F[Return error: invalid name]
+    E -->|Yes| G{Currency provided?}
+    D -->|No| G
+    G -->|Yes| H{Currency exists?}
+    H -->|No| I[Return error: currency not found]
+    H -->|Yes| J[Update partner record]
+    G -->|No| J
+    J --> K[Return updated partner]
+```
+
+## External Dependencies
+
+- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates that the referenced preferred currency exists (when provided)
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **CURRENCY_NOT_FOUND**: Referenced preferred currency does not exist
+- **INVALID_NAME**: Provided name is empty
+
+## Test Cases
+
+- updates partner name
+- updates preferred currency
+- returns error when partner not found
+- returns error when name is empty
+- returns error when currency not found

package/src/modules/business-partner/docs/commands/UpdatePartnerAddress.md

@@ -0,0 +1,46 @@
+# UpdatePartnerAddress
+
+## Overview
+
+updatePartnerAddress modifies the fields of an existing partner address. The address type is immutable and cannot be changed after creation. All other address fields (line1, line2, city, state, postalCode, country) can be updated individually. Country validation is enforced when a new country value is provided. Updates are permitted regardless of the parent partner's lifecycle status (DRAFT, ACTIVE, or INACTIVE) — existing addresses always remain updatable.
+
+## Business Rules
+
+- Address must exist in the system
+- Parent partner's lifecycle status is not checked — updates are permitted in any state (DRAFT, ACTIVE, or INACTIVE)
+- Address type is immutable — it cannot be changed after creation
+- Country, if provided, must be a valid ISO 3166-1 alpha-2 code
+- Only provided fields are updated; omitted fields retain their current values
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Address exists?}
+    B -->|No| C[Return error: address not found]
+    B -->|Yes| D{Country provided?}
+    D -->|Yes| E{Country code valid?}
+    E -->|No| F[Return error: invalid country code]
+    E -->|Yes| G[Update address record]
+    D -->|No| G
+    G --> H[Return updated address]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADDRESS_NOT_FOUND**: Specified address ID does not exist
+- **INVALID_COUNTRY_CODE**: Country is not a valid ISO 3166-1 alpha-2 code
+
+## Test Cases
+
+- updates address fields
+- updates address for DRAFT partner
+- updates address for ACTIVE partner
+- updates address for INACTIVE partner
+- returns error when address not found
+- returns error when country code is invalid
+- returns error when country code is lowercase

package/src/modules/business-partner/docs/commands/UpdatePartnerBankAccount.md

@@ -0,0 +1,64 @@
+# UpdatePartnerBankAccount
+
+## Overview
+
+updatePartnerBankAccount modifies the details of an existing bank account. All fields are optional, but the same validation rules that apply at creation are enforced for any provided values. This allows incremental updates to banking information as details change. Updates are permitted regardless of the parent partner's lifecycle status (DRAFT, ACTIVE, or INACTIVE).
+
+## Business Rules
+
+- Bank account must exist in the system
+- Parent partner's status is not checked — updates are permitted in any lifecycle state (DRAFT, ACTIVE, or INACTIVE)
+- Bank name, if provided, must be non-empty
+- Account holder name, if provided, must be non-empty
+- After update, at least one of accountNumber or iban must still be present
+- `routingNumber` is optional — can be added, updated, or cleared
+- `swiftBic` is optional — can be added, updated, or cleared
+- Currency, if provided, must reference an existing Currency in the primitives module
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Bank account exists?}
+    B -->|No| C[Return error: bank account not found]
+    B -->|Yes| D{bankName provided and empty?}
+    D -->|Yes| D1[Return error: invalid bank name]
+    D -->|No| E2{accountHolderName provided and empty?}
+    E2 -->|Yes| E3[Return error: invalid account holder name]
+    E2 -->|No| F1{Currency provided?}
+    F1 -->|Yes| F2{Currency exists?}
+    F2 -->|No| F3[Return error: currency not found]
+    F2 -->|Yes| G{At least one account identifier remains?}
+    F1 -->|No| G
+    G -->|No| H[Return error: missing account identifier]
+    G -->|Yes| I[Update bank account record]
+    I --> J[Return updated bank account]
+```
+
+## External Dependencies
+
+- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates that the referenced currency exists (when provided)
+
+## Error Scenarios
+
+- **BANK_ACCOUNT_NOT_FOUND**: Specified bank account ID does not exist
+- **INVALID_BANK_NAME**: Bank name is provided but empty
+- **INVALID_ACCOUNT_HOLDER_NAME**: Account holder name is provided but empty
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
+- **MISSING_ACCOUNT_IDENTIFIER**: Update would result in neither accountNumber nor iban being present
+
+## Test Cases
+
+- updates bank account details
+- updates routingNumber
+- updates swiftBic
+- clears routingNumber when null is passed
+- clears swiftBic when null is passed
+- updates bank account for DRAFT partner
+- updates bank account for ACTIVE partner
+- updates bank account for INACTIVE partner
+- returns error when account not found
+- returns error when bank name is empty
+- returns error when account holder name is empty
+- returns error when currency not found
+- returns error when update would remove all identifiers

package/src/modules/business-partner/docs/commands/UpdatePartnerIdentification.md

@@ -0,0 +1,52 @@
+# UpdatePartnerIdentification
+
+## Overview
+
+updatePartnerIdentification modifies the fields of an existing partner identification. The identification type is immutable and cannot be changed after creation. When the value is updated, uniqueness is re-validated against the company scope to prevent duplicate registrations.
+
+## Business Rules
+
+- Identification must exist in the system
+- Type is immutable — it cannot be changed after creation
+- If value is provided, it must be non-empty and not whitespace-only
+- If value is changed, the new (type, value) combination must be unique within the company scope
+- When both validFrom and validTo are set, validTo must be greater than or equal to validFrom
+- Issuing country and validity dates are optional
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Identification exists?}
+    B -->|No| C[Return error: identification not found]
+    B -->|Yes| D{Value provided?}
+    D -->|Yes| D2{Value non-empty after trim?}
+    D2 -->|No| D3[Return error: invalid value]
+    D2 -->|Yes| E{Value changed and new type + value unique in company?}
+    E -->|No| F[Return error: duplicate identification]
+    E -->|Yes| G{Validate validity period}
+    D -->|No| G
+    G -->|validTo < validFrom| H[Return error: invalid validity period]
+    G -->|Valid| I[Update identification record]
+    I --> J[Return updated identification]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **IDENTIFICATION_NOT_FOUND**: Specified identification ID does not exist
+- **INVALID_VALUE**: Provided value is empty or whitespace-only
+- **DUPLICATE_IDENTIFICATION**: Updated (type, value) combination already exists within the company
+- **INVALID_VALIDITY_PERIOD**: validTo is earlier than validFrom
+
+## Test Cases
+
+- updates identification value
+- returns error when identification not found
+- returns error when value is empty
+- returns error when value is whitespace-only
+- returns error when updated value creates duplicate
+- returns error when validity period is invalid

package/src/modules/business-partner/docs/features/contact-person-management.md

@@ -0,0 +1,70 @@
+# Contact Person Management
+
+## Overview
+
+Contact Person Management enables organizations to track individual people who represent a business partner organization. Each contact person is a sub-entity linked to exactly one ORGANIZATION-type partner — they are not business partners themselves, but named individuals who act on behalf of that organization. Contact persons carry their own identifying information (name, and at least one of email or phone, plus optional job title and department) and maintain an independent ACTIVE/INACTIVE status.
+
+One contact person per organization can be designated as the primary contact, providing a single point of first contact for that partner relationship.
+
+## Business Purpose
+
+Business interactions with partner organizations are typically conducted through specific individuals. Tracking contact persons enables:
+
+- **Named communication**: Sales, procurement, and support teams can reach the right person at a partner organization rather than relying on generic email addresses or phone numbers
+- **Role clarity**: Job title and department fields identify who is responsible for purchasing, accounts payable, technical escalation, and other functional areas
+- **Primary contact designation**: Each organization has one primary contact, reducing ambiguity about who to contact first for general enquiries
+- **Status tracking**: Contacts who leave or change roles can be marked INACTIVE without losing historical records tied to past transactions or communications
+- **CRM alignment**: Mirrors industry-standard models (SAP BP relationships, Odoo child contacts, Salesforce Contact-Account) for interoperability and familiarity
+
+## Process Flow
+
+The relationship between a partner organization and its contact persons:
+
+```mermaid
+flowchart TD
+    A[ORGANIZATION-type Partner] -->|has zero or more| B[Contact Person]
+    B --> C{Is primary contact?}
+    C -->|Yes| D[Designated as primary contact\nfor the organization]
+    C -->|No| E[Regular contact person]
+    D -->|another contact promoted| F[Primary designation transferred]
+```
+
+Contact person lifecycle:
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createContactPerson
+    Active --> Inactive: deactivateContactPerson
+    Inactive --> Active: reactivateContactPerson
+    Active --> [*]: deleteContactPerson (only when not primary)
+```
+
+## Scenario Patterns
+
+- **New supplier onboarding**: When a new supplier partner is registered, the procurement team adds the account manager's name, email, and phone as a contact person and marks them as primary contact
+- **Multiple contacts per organization**: A customer organization has separate contacts for accounts payable and technical support — both are recorded with distinct job titles and departments
+- **Primary contact change**: The existing primary contact leaves the organization; their record is marked INACTIVE, and a newly added colleague is designated as the primary contact
+- **Contact details update**: A contact person's phone number or job title changes; the record is updated without affecting their link to the parent organization or their primary status
+- **Departed contact retention**: A contact person who has left the partner organization is deactivated rather than deleted, preserving references in historical correspondence and past transactions
+- **Organization type enforcement**: Attempting to link a contact person to an INDIVIDUAL-type partner is rejected; contact persons may only belong to ORGANIZATION-type partners
+
+## Test Cases
+
+- A contact person can only be linked to an ORGANIZATION-type partner; linking to an INDIVIDUAL-type partner must be rejected
+- Contact person fields firstName and lastName are required; email, phone, jobTitle, and department are optional. At least one communication channel (email or phone) must be provided
+- Email format must be validated on creation and update
+- A contact person is 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
+
+## Reference Links
+
+- [SAP Business Partner Relationships](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/7b24a64d9d0941bda1afa753263d9e39/4e4dece7db1b59cde10000000a42189b.html)
+- [Odoo Contacts as Child Partners](https://www.odoo.com/documentation/19.0/applications/general/contacts.html)
+- [Salesforce Contact Object](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_contact.htm)

package/src/modules/business-partner/docs/features/partner-address-management.md

@@ -0,0 +1,96 @@
+# Partner Address Management
+
+## Overview
+
+Partner Address Management allows each business partner to maintain multiple addresses, each classified by purpose (BILLING, SHIPPING, REGISTERED, or OTHER). Addresses are child entities — they cannot exist without a parent partner record — and they carry the same structured format used by the organization module's Site entity: line1, line2, city, state/province, postalCode, and country (ISO 3166-1 alpha-2). While a Site models a company-owned physical facility, a partner address models an external party's location and is owned entirely by the business-partner module.
+
+One address per partner may be designated as the default for each address type, eliminating ambiguity when downstream modules (accounts payable, order management, shipping) need to resolve where to send an invoice, a shipment, or a legal notice. When no explicit override is provided on a transaction, the relevant default address is used automatically.
+
+## Business Purpose
+
+Partners routinely operate out of more than one location and require different addresses for different purposes. This feature enables:
+
+- Separate billing and shipping addresses so that invoices reach the accounts-payable office while goods arrive at the warehouse
+- A registered address that captures the legal domicile of a corporate partner for compliance, contract, and regulatory correspondence
+- An OTHER classification for secondary or informal locations not covered by the primary types
+- A default-per-type designation that downstream modules can resolve without bespoke selection logic
+- Structured, country-aware address fields that support postal validation and country-specific formatting rules
+- Independent address lifecycle — addresses can be added, updated, or removed without altering the partner's own record or status. Adding new addresses requires the partner to be in DRAFT or ACTIVE state; INACTIVE partners may only have their existing addresses read or updated, not extended with new entries
+- Preservation of address history: removing an address that has been referenced on historical transactions is prevented to maintain referential integrity
+
+## Process Flow
+
+The following diagram shows the end-to-end flow for managing addresses on a partner:
+
+```mermaid
+flowchart TD
+    A[Partner exists in system] --> B[Add address to partner]
+    B --> C[Provide structured address fields\nline1, city, postalCode, country, addressType]
+    C --> D{Mark as default\nfor this type?}
+    D -->|Yes| E[Set isDefault = true\nfor this addressType]
+    D -->|No| F[Address saved as non-default]
+    E --> G[Previous default of same type\nautomatically unset]
+    G --> H[Address available for\ndownstream resolution]
+    F --> H
+    H --> I{Update needed?}
+    I -->|Yes| J[Update address fields]
+    J --> H
+    I -->|No| K{Remove address?}
+    K -->|Yes| L{Address referenced\non transactions?}
+    L -->|Yes| M[Reject removal —\npreserve referential integrity]
+    L -->|No| N[Delete address]
+    K -->|No| H
+```
+
+The default-resolution flow used by downstream modules:
+
+```mermaid
+flowchart TD
+    A[Downstream module needs address] --> B[Specify partner + addressType]
+    B --> C{Default address\nexists for this type?}
+    C -->|Yes| D[Return default address]
+    C -->|No| E{Any address\nof this type exists?}
+    E -->|Yes| F[Return error —\ncaller must select explicitly]
+    E -->|No| G[Return error —\nno address of this type exists]
+```
+
+## Scenario Patterns
+
+- **Separate billing and shipping**: A distributor's finance department is located at the head office, but deliveries go to a regional warehouse. Two addresses are added to the partner: one with type BILLING marked as default, one with type SHIPPING marked as default. Purchase orders automatically route the invoice to the head office and the shipment to the warehouse
+- **Legal registered address**: A corporate partner is registered with a government authority at a different location from its operational offices. A REGISTERED address is added to hold the statutory address used for compliance filings and contract headers
+- **Multiple shipping sites**: A large retail chain partner has three distribution centers. Three SHIPPING addresses are maintained; one is marked as the default and the others are available for explicit selection on individual orders
+- **Address correction**: A partner's postal code changes after a municipal rezoning. The affected address record is updated in place without creating a new address or touching the partner's master record
+- **Expanding to a new country**: A partner opens a new subsidiary in another country. A second BILLING address is added with the appropriate country code and regional postal format, and the default BILLING designation is moved to the new address
+- **Removing an obsolete address**: A partner closes one of its warehouses. The corresponding SHIPPING address is removed, provided no open or historical transactions reference it
+- **OTHER address for informal site**: A partner uses a forwarding agent at a location that does not fit BILLING, SHIPPING, or REGISTERED. An OTHER address is recorded to capture the forwarding address for ad hoc use
+
+## Test Cases
+
+- An address cannot be created without a valid, existing parent partner
+- address fields line1, city, postalCode, country, and addressType are required at creation
+- line2 is optional
+- country must be a valid ISO 3166-1 alpha-2 code
+- addressType must be one of BILLING, SHIPPING, REGISTERED, OTHER
+- A partner may hold multiple addresses of the same type
+- Setting isDefault = true for an addressType automatically unsets isDefault on any previous default of the same type for the same partner
+- Only one address per partner per addressType may be marked as default at any time
+- Retrieving the default address for a partner and type returns exactly the address with isDefault = true for that type
+- A partner can have independent defaults for BILLING, SHIPPING, REGISTERED, and OTHER simultaneously
+- Updating address fields (line1, line2, city, state, postalCode, country) on an existing address record is permitted
+- addressType is immutable after creation; changing type requires deleting the old address and creating a new one
+- Deleting an address that is referenced on a historical or open transaction is rejected to preserve referential integrity
+- Deleting the default address of a type does not automatically promote another address of the same type to default; no default exists until one is explicitly set
+- Querying addresses by partner returns all addresses for that partner
+- Querying addresses by partner and addressType returns only addresses of the requested type
+- A partner with no addresses returns an empty list, not an error
+- Reading and updating existing addresses is permitted regardless of partner status (DRAFT, ACTIVE, or INACTIVE)
+- Adding new addresses to a partner requires the partner to be in DRAFT or ACTIVE state; adding to an INACTIVE partner is rejected
+- When no default address exists for a requested type, the system returns an error rather than silently picking an arbitrary address; the caller must either set a default or select an address explicitly
+
+## Reference Links
+
+- [SAP Business Partner Address Management (BP)](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f76052846e404ea8811eb06534b6e099/5e13e82b8ca111d1a6090000e8353423.html)
+- [Odoo Contact Addresses (child records under res.partner)](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/shipping_receiving/setup_configuration/delivery_countries.html)
+- [Dynamics 365 Party postal addresses](https://learn.microsoft.com/en-us/dynamics365/finance/accounts-payable/vendor-posting-profiles)
+- [Oracle Supplier Sites and Addresses](https://docs.oracle.com/en/cloud/saas/procurement/24d/faaps/supplier-addresses.html)
+- [ISO 3166-1 alpha-2 Country Codes](https://www.iso.org/iso-3166-country-codes.html)

package/src/modules/business-partner/docs/features/partner-bank-account.md

@@ -0,0 +1,70 @@
+# Partner Bank Account
+
+## Overview
+
+Partner Bank Accounts are child entities of a Business Partner that store the banking details required to execute financial transactions with that partner. Each record captures identifying information for a single bank account: bank name, account holder name, account number, routing number, IBAN, SWIFT/BIC, and the transaction currency. A partner may hold multiple bank accounts, and one account per partner may be designated as the default to streamline payment processing.
+
+Bank account records can be created and maintained regardless of the partner's current lifecycle state (DRAFT, ACTIVE, or INACTIVE), allowing finance teams to prepare payment details in advance and retain them after a partner is deactivated.
+
+## Business Purpose
+
+Accurate bank account data is a prerequisite for both accounts payable (paying suppliers) and accounts receivable (collecting from customers). Maintaining this data on the partner record ensures downstream payment and collection workflows always have a reliable, auditable source:
+
+- **Accounts payable**: Supplier bank details are referenced when generating payment runs, wire transfers, or ACH batches for purchase invoices
+- **Accounts receivable**: Customer bank details support direct debit collection and refund processing
+- **Multi-account flexibility**: Partners operating across multiple currencies or banking jurisdictions can have separate accounts per bank or currency
+- **Default designation**: Finance teams can mark one account as default to reduce manual selection during routine payment processing
+- **Regional field coverage**: The model supports both account-number/routing-number conventions (US/Canada) and IBAN/SWIFT conventions (Europe and international), enabling global counterparty management
+- **Currency association**: Each bank account references a Currency from the primitives module, clarifying which denomination the account handles
+
+## Process Flow
+
+The following diagram shows how a bank account is added to a partner and how the default designation is managed:
+
+```mermaid
+flowchart TD
+    A[Select Business Partner] --> B[Add Bank Account]
+    B --> C[Enter Bank Details\nbankName, accountHolderName,\naccountNumber / IBAN,\nroutingNumber / SWIFT/BIC,\ncurrency]
+    C --> D{First account\nfor this partner?}
+    D -->|Yes| E[Auto-designate as default]
+    D -->|No| F[Save as non-default]
+    E --> G[Bank Account Saved]
+    F --> G
+    G --> H{Change default?}
+    H -->|Yes| I[Mark account as default\nPrevious default is unset]
+    H -->|No| J[No further action]
+    I --> K[Default Updated]
+```
+
+## Scenario Patterns
+
+- **New supplier payment setup**: A procurement team onboards a new vendor. Before the first purchase order is issued, the AP team adds the supplier's EUR bank account (IBAN + SWIFT/BIC) and it is automatically designated as the default. Payment runs will reference this account.
+- **US domestic vendor with routing**: A US-based supplier provides an ABA routing number and checking account number instead of an IBAN. Finance adds the account using `routingNumber` and `accountNumber` fields, omitting IBAN and SWIFT/BIC.
+- **Multi-currency supplier**: An international supplier invoices in both USD and EUR. Two bank accounts are added — one per currency — each referencing the appropriate Currency from the primitives module. The USD account is marked as the default for domestic transactions.
+- **Customer direct debit**: A customer agreement includes a direct debit mandate. The AR team records the customer's bank account so that collection runs can reference it without re-entering details each cycle.
+- **Updating the default account**: A supplier notifies the company of a new primary bank account. The finance team adds the new account and marks it as default; the previous default account is retained for reference and audit but is no longer automatically selected.
+- **Inactive partner retention**: A vendor is deactivated following contract expiry. Their bank accounts remain in the system for audit and potential reactivation, but the partner cannot be referenced in new payment runs while INACTIVE.
+
+## Test Cases
+
+- A bank account can be added to a partner in DRAFT, ACTIVE, or INACTIVE state
+- The first bank account added to a partner is automatically designated as the default
+- A partner can have more than one bank account
+- Marking a bank account as default unsets the default flag on all other accounts for that partner
+- At most one bank account per partner can be designated as default at any time
+- `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 and applicable for domestic (ACH/wire) routing conventions
+- `swiftBic` is optional and applicable for international transfers
+- `currency` must reference a valid, existing Currency from the primitives module
+- Removing a bank account that is currently designated as the default 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
+
+## Reference Links
+
+- [SAP Business Partner Bank Details](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f325a3e3a5514e85aab72db8bab710c8/4b2011bb2d6b3e41e10000000a42189c.html)
+- [Odoo Partner Bank Accounts (res.partner.bank)](https://www.odoo.com/documentation/19.0/applications/accounting/payments/pay.html)
+- [Oracle Supplier Bank Accounts](https://docs.oracle.com/en/cloud/saas/financials/24b/fappp/manage-supplier-bank-accounts.html)
+- [ISO 9362 SWIFT/BIC Standard](https://www.iso.org/standard/60390.html)
+- [ISO 13616 IBAN Standard](https://www.iso.org/standard/81090.html)

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

@@ -0,0 +1,76 @@
+# Partner Identification
+
+## Overview
+
+Partner Identification allows storing official registration numbers — such as tax IDs, VAT numbers, DUNS numbers, and company registry codes — against a business partner. Each identification record captures the type, value, and optional metadata including issuing country and validity period. A single partner can hold multiple identification records of different types, reflecting the reality that organisations are often registered across multiple jurisdictions or recognised by more than one authority.
+
+Identifications are child entities of a business partner and can be added at any point in the partner's lifecycle. Uniqueness is enforced on the combination of type and value within a company scope, preventing the same registration number from being attached to duplicate partner records. This scoping is intentionally company-level; cross-company deduplication is out of scope for the initial implementation and may be introduced as a future enhancement if shared-counterparty scenarios arise.
+
+## Business Purpose
+
+Accurate partner identification data is required for legal compliance and operational integrity:
+
+- **Tax reporting and invoicing**: Tax ID and VAT number must appear on invoices in many jurisdictions. Storing them on the partner record ensures they are available for document generation without manual entry
+- **Know Your Customer (KYC)**: Onboarding processes in regulated industries require verified registration numbers to confirm a partner's legal identity before commencing trade
+- **Duplicate detection**: Enforcing uniqueness on (type, value) within a company scope prevents the same real-world entity from existing as multiple partner records
+- **Cross-border trade**: A partner operating in multiple countries may hold a domestic tax ID, a regional VAT number (e.g., EU VAT), and an international identifier (e.g., DUNS). All can be stored concurrently
+- **Audit trail and compliance**: Validity dates on identification records support time-bounded compliance checks and historical audit requirements
+
+## Process Flow
+
+The typical flow for recording and using partner identifications:
+
+```mermaid
+flowchart TD
+    A[Select Business Partner] --> B[Add Identification]
+    B --> C{Type already present\nwith same value?}
+    C -->|Yes - duplicate| D[Reject: uniqueness violation]
+    C -->|No| E[Store Identification\ntype + value + metadata]
+    E --> F{More IDs to add?}
+    F -->|Yes| B
+    F -->|No| G[Partner Identifications Complete]
+    G --> H[Use in invoicing / tax reporting / KYC]
+```
+
+Identification validity is checked at the point of use:
+
+```mermaid
+flowchart TD
+    A[Retrieve Partner Identification] --> B{validFrom / validTo set?}
+    B -->|No| C[Identification is always valid]
+    B -->|Yes| D{Current date within range?}
+    D -->|Yes| E[Identification is valid]
+    D -->|No| F[Identification is expired or not yet active]
+```
+
+## Scenario Patterns
+
+- **Domestic tax registration**: A supplier is onboarded for a single country. A `TAX_ID` identification is added with the national tax number and the issuing country set to the supplier's home country
+- **EU VAT number**: A European partner holds both a domestic `TAX_ID` and an EU-wide `VAT` number. Both are stored as separate identification records on the same partner
+- **DUNS for procurement**: A large enterprise uses DUNS numbers in its supplier qualification process. A `DUNS` identification is added and used to cross-reference the partner against third-party credit and risk databases
+- **Company registry reference**: A partner's legal registration number from a national company registry is stored as `COMPANY_REGISTRY`, enabling verification against public registers
+- **National ID for individual partners**: An individual business partner (e.g., a sole trader) has a `NATIONAL_ID` stored as their primary identification
+- **Time-bounded VAT registration**: A partner's VAT registration is valid from a specific date. The `validFrom` field is set so that downstream processes can determine whether the VAT number applies to a given transaction date
+- **Duplicate partner prevention**: An operator attempts to add a `TAX_ID` with a value already recorded on another partner. The system rejects the entry, surfacing the conflict so the operator can merge or review the existing partner record
+- **Other / custom identifiers**: A partner holds an identifier that does not fit any standard type (e.g., an industry-specific accreditation number). It is stored under type `OTHER` with a descriptive value
+
+## Test Cases
+
+- An identification requires both `type` and `value`; 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 (intentionally company-level; cross-company deduplication is not enforced); attempting to create a duplicate within the same company is rejected
+- A single partner can hold multiple identification records with different types
+- Two partners may not share an identification record with the same (type, value) combination
+- `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)
+- An identification record can be deleted without affecting the parent partner or other identifications
+- `type` is immutable after creation; changing the identification type requires deleting the existing record and creating a new one
+- Updating an identification's value must re-validate the (type, value) uniqueness constraint
+
+## Reference Links
+
+- [SAP Business Partner — Tax Numbers and Identification](https://help.sap.com/docs/SAP_S4HANA_ON-PREMISE/f544846954f24b9183edd4ca52275847/d6a0de9fd00f4ab2843e013d7a8f5380.html)
+- [Odoo Fiscal Information — VAT and Company Registry](https://www.odoo.com/documentation/19.0/applications/accounting/accounting/taxes/taxcloud.html)
+- [Oracle Supplier Tax Registrations](https://docs.oracle.com/en/cloud/saas/financials/24a/fappp/supplier-registration.html)
+- [DUNS Number — Dun & Bradstreet](https://www.dnb.com/duns-number.html)