@tailor-platform/erp-kit 0.3.0 → 0.4.1

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

@@ -0,0 +1,68 @@
+# CreatePartnerBankAccount
+
+## Overview
+
+createPartnerBankAccount adds a bank account to a business partner. Bank accounts store banking details needed for financial transactions such as payments and receivables. At least one account identifier (accountNumber or iban) is required. The first bank account added to a partner is automatically designated as the default. Bank accounts can be added regardless of the partner's lifecycle status (DRAFT, ACTIVE, or INACTIVE), allowing finance teams to prepare or retain payment details at any stage.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner status is not checked — bank accounts can be added in any lifecycle state (DRAFT, ACTIVE, or INACTIVE)
+- Bank name is required and must be non-empty
+- Account holder name is required and must be non-empty
+- At least one of accountNumber or iban must be provided
+- `routingNumber` is optional — used for domestic routing conventions (e.g., ACH/wire)
+- `swiftBic` is optional — used for international transfers
+- Currency must reference an existing Currency in the primitives module
+- The first bank account added to a partner is automatically set as default
+- Subsequent bank accounts are created as non-default
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Partner exists?}
+    B -->|No| C[Return error: partner not found]
+    B -->|Yes| D{Bank name non-empty?}
+    D -->|No| E[Return error: invalid bank name]
+    D -->|Yes| F{Account holder name non-empty?}
+    F -->|No| G[Return error: invalid account holder name]
+    F -->|Yes| H{accountNumber or iban provided?}
+    H -->|No| I[Return error: missing account identifier]
+    H -->|Yes| J{Currency exists?}
+    J -->|No| K[Return error: currency not found]
+    J -->|Yes| L{First account for partner?}
+    L -->|Yes| M[Create bank account as default]
+    L -->|No| N[Create bank account as non-default]
+    M --> O[Return created bank account]
+    N --> O
+```
+
+## External Dependencies
+
+- [primitives::Currency](../../../primitives/docs/models/Currency.md) - Validates that the referenced currency exists
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
+- **MISSING_ACCOUNT_IDENTIFIER**: Neither accountNumber nor iban was provided
+- **INVALID_BANK_NAME**: Bank name is empty
+- **INVALID_ACCOUNT_HOLDER_NAME**: Account holder name is empty
+
+## Test Cases
+
+- creates bank account for partner
+- creates bank account with iban
+- creates bank account with both accountNumber and iban
+- creates bank account with routingNumber
+- creates bank account with swiftBic
+- creates bank account for DRAFT partner
+- creates bank account for INACTIVE partner
+- auto-sets first account as default
+- does not set default when partner already has accounts
+- returns error when partner not found
+- returns error when bank name is empty
+- returns error when account holder name is empty
+- returns error when neither account number nor iban provided
+- returns error when currency not found

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

@@ -0,0 +1,59 @@
+# CreatePartnerIdentification
+
+## Overview
+
+createPartnerIdentification adds an identification document or number to a business partner. Identifications represent external references such as tax IDs, registration numbers, or government-issued identifiers. The combination of type and value must be unique within the company scope to prevent duplicate registrations. Identifications can be added regardless of the partner's lifecycle status (DRAFT, ACTIVE, or INACTIVE).
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner status is not checked — identifications can be added in any lifecycle state (DRAFT, ACTIVE, or INACTIVE)
+- Type is required and must be a valid identification type enum value
+- Value is required and must be non-empty
+- The combination of (type, value) must be unique within the company scope
+- When both validFrom and validTo are provided, validTo must be greater than or equal to validFrom
+- Issuing country, validFrom, and validTo are optional
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Partner exists?}
+    B -->|No| C[Return error: partner not found]
+    B -->|Yes| D{Type valid?}
+    D -->|No| E[Return error: invalid identification type]
+    D -->|Yes| D2{Value non-empty?}
+    D2 -->|No| D3[Return error: invalid value]
+    D2 -->|Yes| F{type + value unique in company?}
+    F -->|No| G[Return error: duplicate identification]
+    F -->|Yes| H{Both validFrom and validTo provided?}
+    H -->|Yes| I{validTo >= validFrom?}
+    I -->|No| J[Return error: invalid validity period]
+    I -->|Yes| K[Create identification record]
+    H -->|No| K
+    K --> L[Return created identification]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **INVALID_IDENTIFICATION_TYPE**: Type is not a valid identification type enum value
+- **INVALID_VALUE**: Value is empty or not provided
+- **DUPLICATE_IDENTIFICATION**: An identification with the same type and value already exists within the company
+- **INVALID_VALIDITY_PERIOD**: validTo is earlier than validFrom
+
+## Test Cases
+
+- creates identification for partner
+- creates identification for DRAFT partner
+- creates identification for INACTIVE partner
+- returns error when partner not found
+- returns error when type is invalid
+- returns error when value is empty
+- returns error when duplicate (type, value) in company
+- returns error when validTo is before validFrom
+- creates with optional fields omitted

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

@@ -0,0 +1,42 @@
+# DeactivateContactPerson
+
+## Overview
+
+deactivateContactPerson transitions a contact person from ACTIVE to INACTIVE status. This is used when a contact person is no longer a valid point of contact for the organization. If the contact person holds the primary designation, that designation is automatically removed upon deactivation.
+
+## Business Rules
+
+- Contact person must exist in the system
+- Contact person must be in ACTIVE status
+- If the contact person is the primary contact, the primary designation is removed upon deactivation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Contact person exists?}
+    B -->|No| C[Return error: contact person not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F{Is primary contact?}
+    F -->|Yes| G[Remove primary designation]
+    G --> H[Update status to INACTIVE]
+    F -->|No| H
+    H --> I[Return deactivated contact person]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CONTACT_PERSON_NOT_FOUND**: Specified contact person ID does not exist
+- **INVALID_STATE_TRANSITION**: Contact person is not in ACTIVE status
+
+## Test Cases
+
+- deactivates an active contact person
+- removes primary designation when deactivating primary contact
+- returns error when contact not found
+- returns error when contact is already inactive

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

@@ -0,0 +1,39 @@
+# DeactivatePartner
+
+## Overview
+
+deactivatePartner transitions a business partner from ACTIVE to INACTIVE status. Deactivation is used when a business relationship is suspended or terminated. Only partners in ACTIVE status can be deactivated. Inactive partners cannot participate in new transactions but their historical data is preserved.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be in ACTIVE status
+- After deactivation, the partner cannot participate in new transactions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Partner exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to INACTIVE]
+    F --> G[Return deactivated partner]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **INVALID_STATE_TRANSITION**: Partner is not in ACTIVE status
+
+## Test Cases
+
+- deactivates an ACTIVE partner
+- returns error when partner not found
+- returns error when partner is DRAFT
+- returns error when partner is INACTIVE

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

@@ -0,0 +1,43 @@
+# DeleteContactPerson
+
+## Overview
+
+deleteContactPerson permanently removes a contact person from the system. Contact persons who currently hold the primary designation cannot be deleted — the primary designation must be removed or transferred first. This safeguard prevents accidental loss of the primary contact designation; once removed or transferred, the organization may have no primary contact until one is explicitly set.
+
+## Business Rules
+
+- Contact person must exist in the system
+- Contact person must be in ACTIVE status — only active contact persons can be deleted
+- Contact person must not be the primary contact — primary contacts cannot be deleted
+- Deletion is permanent and cannot be undone
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Contact person exists?}
+    B -->|No| C[Return error: contact person not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: contact not active]
+    D -->|Yes| F{Is primary contact?}
+    F -->|Yes| G[Return error: contact is primary]
+    F -->|No| H[Delete contact person record]
+    H --> I[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CONTACT_PERSON_NOT_FOUND**: Specified contact person ID does not exist
+- **CONTACT_NOT_ACTIVE**: Contact person is not in ACTIVE status and cannot be deleted
+- **CONTACT_IS_PRIMARY**: Contact person is currently the primary contact and cannot be deleted
+
+## Test Cases
+
+- deletes a non-primary active contact person
+- returns error when contact not found
+- returns error when contact is not active
+- returns error when contact is primary

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

@@ -0,0 +1,40 @@
+# DeletePartner
+
+## Overview
+
+deletePartner permanently removes a business partner from the system. Only partners in DRAFT status can be deleted, ensuring that partners who have been activated and potentially referenced in transactions cannot be accidentally removed. For partners that have been activated, use deactivatePartner instead.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be in DRAFT status
+- Deletion is permanent and cannot be undone
+- ACTIVE and INACTIVE partners cannot be deleted
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Partner exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Delete partner record]
+    F --> G[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **INVALID_STATE_TRANSITION**: Partner is not in DRAFT status
+
+## Test Cases
+
+- deletes a DRAFT partner
+- returns error when partner not found
+- returns error when partner is ACTIVE
+- returns error when partner is INACTIVE

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

@@ -0,0 +1,40 @@
+# DeletePartnerAddress
+
+## Overview
+
+deletePartnerAddress removes an address from a business partner. Addresses that are currently referenced on transactions (e.g., sales orders, purchase orders) cannot be deleted to preserve data integrity. If the deleted address was the default for its type, no other address is automatically promoted to default.
+
+## Business Rules
+
+- Address must exist in the system
+- Address cannot be deleted if it is referenced on existing transactions
+- Deleting the default address does not auto-promote another address to default
+- Deletion is permanent and cannot be undone
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Address exists?}
+    B -->|No| C[Return error: address not found]
+    B -->|Yes| D{Address referenced on transactions?}
+    D -->|Yes| E[Return error: address in use]
+    D -->|No| F[Delete address record]
+    F --> G[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADDRESS_NOT_FOUND**: Specified address ID does not exist
+- **ADDRESS_IN_USE**: Address is referenced on existing transactions and cannot be deleted
+
+## Test Cases
+
+- deletes an address
+- returns error when address not found
+- returns error when address is referenced on transactions
+- deleting default does not promote another

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

@@ -0,0 +1,35 @@
+# DeletePartnerBankAccount
+
+## Overview
+
+deletePartnerBankAccount removes a bank account from a business partner. If the deleted account was the default, no other account is automatically promoted to default — the partner will have no default bank account until one is explicitly set.
+
+## Business Rules
+
+- Bank account must exist in the system
+- Deleting the default bank account does not auto-promote another account to default
+- Deletion is permanent and cannot be undone
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Bank account exists?}
+    B -->|No| C[Return error: bank account not found]
+    B -->|Yes| D[Delete bank account record]
+    D --> E[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BANK_ACCOUNT_NOT_FOUND**: Specified bank account ID does not exist
+
+## Test Cases
+
+- deletes an existing bank account
+- deletes default bank account without promoting another
+- returns error when account not found

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

@@ -0,0 +1,33 @@
+# DeletePartnerIdentification
+
+## Overview
+
+deletePartnerIdentification removes an identification record from a business partner. This permanently deletes the identification, such as a tax ID or registration number, from the system.
+
+## Business Rules
+
+- Identification must exist in the system
+- Deletion is permanent and cannot be undone
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Identification exists?}
+    B -->|No| C[Return error: identification not found]
+    B -->|Yes| D[Delete identification record]
+    D --> E[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **IDENTIFICATION_NOT_FOUND**: Specified identification ID does not exist
+
+## Test Cases
+
+- deletes an existing identification
+- returns error when identification not found

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

@@ -0,0 +1,38 @@
+# ReactivateContactPerson
+
+## Overview
+
+reactivateContactPerson transitions a contact person from INACTIVE back to ACTIVE status, restoring the contact person as a valid point of contact for the organization. Only contact persons in INACTIVE status can be reactivated. Reactivation does not restore a previous primary designation.
+
+## Business Rules
+
+- Contact person must exist in the system
+- Contact person must be in INACTIVE status
+- Reactivation does not automatically restore primary designation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Contact person exists?}
+    B -->|No| C[Return error: contact person not found]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return reactivated contact person]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CONTACT_PERSON_NOT_FOUND**: Specified contact person ID does not exist
+- **INVALID_STATE_TRANSITION**: Contact person is not in INACTIVE status
+
+## Test Cases
+
+- reactivates an inactive contact person
+- returns error when contact not found
+- returns error when contact is already active

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

@@ -0,0 +1,39 @@
+# ReactivatePartner
+
+## Overview
+
+reactivatePartner transitions a business partner from INACTIVE back to ACTIVE status, restoring the partner's ability to participate in new transactions. This supports scenarios where a previously suspended business relationship is resumed. Only partners in INACTIVE status can be reactivated.
+
+## Business Rules
+
+- Partner must exist in the system
+- Partner must be in INACTIVE status
+- After reactivation, the partner can participate in new transactions again
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Partner exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return reactivated partner]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **INVALID_STATE_TRANSITION**: Partner is not in INACTIVE status
+
+## Test Cases
+
+- reactivates an INACTIVE partner
+- returns error when partner not found
+- returns error when partner is DRAFT
+- returns error when partner is ACTIVE

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

@@ -0,0 +1,46 @@
+# RemoveRoleFromPartner
+
+## Overview
+
+removeRoleFromPartner removes a business role (CUSTOMER or SUPPLIER) from an active partner. This restricts which business processes the partner can participate in going forward. The operation is idempotent — removing a role that is not currently assigned does not produce an error.
+
+## Business Rules
+
+- Role must be one of CUSTOMER or SUPPLIER; any other value is rejected
+- Partner must exist in the system
+- Partner must be in ACTIVE status
+- Removal is idempotent — removing a role that is not present succeeds without error
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive remove role request] --> B{Role is CUSTOMER or SUPPLIER?}
+    B -->|No| C[Return error: invalid role]
+    B -->|Yes| D{Partner exists?}
+    D -->|No| E[Return error: partner not found]
+    D -->|Yes| F{Partner is ACTIVE?}
+    F -->|No| G[Return error: partner not active]
+    F -->|Yes| H{Role currently assigned?}
+    H -->|No| I[Return success - idempotent]
+    H -->|Yes| J[Remove role from partner]
+    J --> K[Return updated partner]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **INVALID_ROLE**: Provided role is not one of CUSTOMER or SUPPLIER
+- **PARTNER_NOT_FOUND**: Specified partner ID does not exist
+- **PARTNER_NOT_ACTIVE**: Partner is not in ACTIVE status
+
+## Test Cases
+
+- removes CUSTOMER from partner holding both roles
+- idempotent when role not present
+- returns error when partner not found
+- returns error when partner is INACTIVE
+- returns error for invalid role value

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

@@ -0,0 +1,38 @@
+# SetDefaultPartnerAddress
+
+## Overview
+
+setDefaultPartnerAddress designates a specific address as the default for its address type within a partner. The previous default address of the same type for the same partner is automatically unset. This ensures that each partner has at most one default address per address type, which is used as the preferred address for that type in business transactions.
+
+## Business Rules
+
+- Address must exist in the system
+- The previous default address of the same type for the same partner is automatically unset
+- Each partner can have at most one default address per address type
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive set default request] --> B{Address exists?}
+    B -->|No| C[Return error: address not found]
+    B -->|Yes| D{Partner has existing default of same type?}
+    D -->|Yes| E[Unset previous default]
+    E --> F[Set new default address]
+    D -->|No| F
+    F --> G[Return updated address]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ADDRESS_NOT_FOUND**: Specified address ID does not exist
+
+## Test Cases
+
+- sets address as default
+- unsets previous default of same type
+- returns error when address not found

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

@@ -0,0 +1,38 @@
+# SetDefaultPartnerBankAccount
+
+## Overview
+
+setDefaultPartnerBankAccount designates a specific bank account as the default for its partner. The previous default bank account for the same partner is automatically unset. This ensures that each partner has at most one default bank account at any time, which is used as the preferred account for financial transactions.
+
+## Business Rules
+
+- Bank account must exist in the system
+- The previous default bank account for the same partner is automatically unset
+- Each partner can have at most one default bank account
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive set default request] --> B{Bank account exists?}
+    B -->|No| C[Return error: bank account not found]
+    B -->|Yes| D{Partner has existing default?}
+    D -->|Yes| E[Unset previous default]
+    E --> F[Set new default bank account]
+    D -->|No| F
+    F --> G[Return updated bank account]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **BANK_ACCOUNT_NOT_FOUND**: Specified bank account ID does not exist
+
+## Test Cases
+
+- sets account as default
+- unsets previous default account
+- returns error when account not found

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

@@ -0,0 +1,43 @@
+# SetPrimaryContactPerson
+
+## Overview
+
+setPrimaryContactPerson designates a contact person as the primary contact for their organization partner. The previous primary contact person for the same organization is automatically unset. Only ACTIVE contact persons can be designated as primary. This ensures that each organization partner has at most one primary contact person at any time.
+
+## Business Rules
+
+- Contact person must exist in the system
+- Contact person must be in ACTIVE status
+- The previous primary contact person for the same organization is automatically unset
+- Each organization partner can have at most one primary contact person
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive set primary request] --> B{Contact person exists?}
+    B -->|No| C[Return error: contact person not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F{Organization has existing primary?}
+    F -->|Yes| G[Unset previous primary]
+    G --> H[Set new primary contact person]
+    F -->|No| H
+    H --> I[Return updated contact person]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CONTACT_PERSON_NOT_FOUND**: Specified contact person ID does not exist
+- **INVALID_STATE_TRANSITION**: Contact person is not in ACTIVE status
+
+## Test Cases
+
+- sets contact as primary
+- unsets previous primary contact
+- returns error when contact not found
+- returns error when contact is inactive