@tailor-platform/erp-kit 0.4.0 → 0.5.0

package/src/modules/sales/docs/commands/CreateSalesPriceList.md

@@ -0,0 +1,37 @@
+# CreateSalesPriceList
+
+## Overview
+
+CreateSalesPriceList creates a draft company-scoped price list used to group reusable sales pricing rules.
+
+## Business Rules
+
+- Record is always created in DRAFT status.
+- Company must be ACTIVE or otherwise eligible for commercial configuration.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Validate references and required fields]
+    B --> C{Validation passed?}
+    C -->|No| D[Return validation error]
+    C -->|Yes| E[Insert draft SalesPriceList record]
+    E --> F[Return created SalesPriceList]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the price list.
+
+## Error Scenarios
+
+- **SALESPRICELIST_NOT_FOUND**: Prerequisite context for SalesPriceList is missing.
+- **COMPANY_NOT_FOUND**: Referenced company does not exist.
+
+## Test Cases
+
+- creates a draft price list for a valid company
+- throws when required SalesPriceList fields are missing
+- creates the SalesPriceList in DRAFT status
+- throws when the company does not exist

package/src/modules/sales/docs/commands/CreateSalesPriceRule.md

@@ -0,0 +1,46 @@
+# CreateSalesPriceRule
+
+## Overview
+
+CreateSalesPriceRule creates a draft pricing condition inside a sales price list so customer- or channel-specific selling prices can be resolved deterministically.
+
+## Business Rules
+
+- Record is always created in DRAFT status.
+- Unit price must be positive.
+- Effective end date cannot precede start date.
+- Minimum quantity cannot be negative.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Validate references and required fields]
+    B --> C{Validation passed?}
+    C -->|No| D[Return validation error]
+    C -->|Yes| E[Insert draft SalesPriceRule record]
+    E --> F[Return created SalesPriceRule]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate the referenced sellable item.
+- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate currency assignment.
+- [primitives::GetUnit](../../../primitives/docs/queries/GetUnit.md) - Validate sales UoM assignment.
+- [getSalesPriceList](../queries/GetSalesPriceList.md) - Validate parent price-list scope.
+
+## Error Scenarios
+
+- **SALESPRICERULE_NOT_FOUND**: Prerequisite context for SalesPriceRule is missing.
+- **PRICE_LIST_NOT_FOUND**: Parent sales price list does not exist.
+- **INVALID_UNIT_PRICE**: Unit price must be greater than zero.
+- **INVALID_EFFECTIVE_RANGE**: Effective end date precedes start date.
+
+## Test Cases
+
+- creates a draft price rule with item, currency, and UoM context
+- throws when required SalesPriceRule fields are missing
+- creates the SalesPriceRule in DRAFT status
+- throws when the parent price list does not exist
+- throws on invalid unit price
+- throws on invalid effective date range

package/src/modules/sales/docs/commands/CreateShipment.md

@@ -0,0 +1,38 @@
+# CreateShipment
+
+## Overview
+
+CreateShipment creates a draft shipment against open sales-order lines that are ready for fulfillment. It records draft quantities, dates, ship-from site, and optional tracking context before posting.
+
+## Business Rules
+
+- Referenced sales order must be in an executable status and have open shippable quantity.
+- Each shipment line must reference a valid sales-order line and a quantity greater than zero.
+- Draft shipment data must remain within the same company scope as the order.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B[Load sales order]
+    B --> C[Validate open shippable quantities]
+    C --> D[Insert draft shipment and shipment lines]
+    D --> E[Return draft shipment]
+```
+
+## External Dependencies
+
+- [getSalesOrder](../queries/GetSalesOrder.md) - Validate the source sales order and open quantities.
+- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Validate ship-from site context.
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **ORDER_NOT_SHIPPABLE**: Sales order does not allow new shipment creation.
+- **INVALID_SHIPMENT_LINE**: Shipment line quantity or reference is invalid.
+
+## Test Cases
+
+- creates a draft shipment against a confirmed order
+- throws when order has no open shippable quantity
+- throws when shipment line quantity is not positive

package/src/modules/sales/docs/commands/DeactivateChannel.md

@@ -0,0 +1,35 @@
+# DeactivateChannel
+
+## Overview
+
+DeactivateChannel removes an active Channel from future operational use while preserving historical references.
+
+## Business Rules
+
+- Only ACTIVE Channel records may be deactivated.
+- Historical references to the Channel must remain valid after deactivation.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B[Load Channel]
+    B --> C{Status is ACTIVE?}
+    C -->|No| D[Return INVALID_CHANNEL_STATUS]
+    C -->|Yes| E[Set status to INACTIVE]
+    E --> F[Return deactivated Channel]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHANNEL_NOT_FOUND**: Referenced Channel does not exist.
+- **INVALID_CHANNEL_STATUS**: Only ACTIVE Channel records may be deactivated.
+
+## Test Cases
+
+- deactivates an active Channel
+- throws when Channel is not active

package/src/modules/sales/docs/commands/DeactivateSalesPaymentTerm.md

@@ -0,0 +1,35 @@
+# DeactivateSalesPaymentTerm
+
+## Overview
+
+DeactivateSalesPaymentTerm removes an active SalesPaymentTerm from future operational use while preserving historical references.
+
+## Business Rules
+
+- Only ACTIVE SalesPaymentTerm records may be deactivated.
+- Historical references to the SalesPaymentTerm must remain valid after deactivation.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B[Load SalesPaymentTerm]
+    B --> C{Status is ACTIVE?}
+    C -->|No| D[Return INVALID_SALESPAYMENTTERM_STATUS]
+    C -->|Yes| E[Set status to INACTIVE]
+    E --> F[Return deactivated SalesPaymentTerm]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALESPAYMENTTERM_NOT_FOUND**: Referenced SalesPaymentTerm does not exist.
+- **INVALID_SALESPAYMENTTERM_STATUS**: Only ACTIVE SalesPaymentTerm records may be deactivated.
+
+## Test Cases
+
+- deactivates an active SalesPaymentTerm
+- throws when SalesPaymentTerm is not active

package/src/modules/sales/docs/commands/DeactivateSalesPriceList.md

@@ -0,0 +1,35 @@
+# DeactivateSalesPriceList
+
+## Overview
+
+DeactivateSalesPriceList removes an active SalesPriceList from future operational use while preserving historical references.
+
+## Business Rules
+
+- Only ACTIVE SalesPriceList records may be deactivated.
+- Historical references to the SalesPriceList must remain valid after deactivation.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B[Load SalesPriceList]
+    B --> C{Status is ACTIVE?}
+    C -->|No| D[Return INVALID_SALESPRICELIST_STATUS]
+    C -->|Yes| E[Set status to INACTIVE]
+    E --> F[Return deactivated SalesPriceList]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALESPRICELIST_NOT_FOUND**: Referenced SalesPriceList does not exist.
+- **INVALID_SALESPRICELIST_STATUS**: Only ACTIVE SalesPriceList records may be deactivated.
+
+## Test Cases
+
+- deactivates an active SalesPriceList
+- throws when SalesPriceList is not active

package/src/modules/sales/docs/commands/DeactivateSalesPriceRule.md

@@ -0,0 +1,35 @@
+# DeactivateSalesPriceRule
+
+## Overview
+
+DeactivateSalesPriceRule removes an active SalesPriceRule from future operational use while preserving historical references.
+
+## Business Rules
+
+- Only ACTIVE SalesPriceRule records may be deactivated.
+- Historical references to the SalesPriceRule must remain valid after deactivation.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B[Load SalesPriceRule]
+    B --> C{Status is ACTIVE?}
+    C -->|No| D[Return INVALID_SALESPRICERULE_STATUS]
+    C -->|Yes| E[Set status to INACTIVE]
+    E --> F[Return deactivated SalesPriceRule]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALESPRICERULE_NOT_FOUND**: Referenced SalesPriceRule does not exist.
+- **INVALID_SALESPRICERULE_STATUS**: Only ACTIVE SalesPriceRule records may be deactivated.
+
+## Test Cases
+
+- deactivates an active SalesPriceRule
+- throws when SalesPriceRule is not active

package/src/modules/sales/docs/commands/IssueSalesCreditNote.md

@@ -0,0 +1,38 @@
+# IssueSalesCreditNote
+
+## Overview
+
+IssueSalesCreditNote validates a draft credit note and freezes it as commercial correction evidence. It ensures cumulative credited quantity or amount remains within the allowed baseline of the original invoice.
+
+## Business Rules
+
+- Only DRAFT credit notes may be issued.
+- The cumulative credited quantity or amount for each invoice line must not exceed the original issued baseline.
+- Issueing the credit note must snapshot correction reason, tax basis, customer, and invoice identity.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive issue request] --> B[Load draft credit note]
+    B --> C[Validate cumulative credit baseline]
+    C --> D[Snapshot correction metadata]
+    D --> E[Set status to ISSUED]
+    E --> F[Return issued credit note]
+```
+
+## External Dependencies
+
+- [getSalesCreditNote](../queries/GetSalesCreditNote.md) - Load draft credit-note context and linked invoice lines.
+
+## Error Scenarios
+
+- **SALES_CREDIT_NOTE_NOT_FOUND**: Referenced sales credit note does not exist.
+- **INVALID_CREDIT_NOTE_STATUS**: Only DRAFT credit notes may be issued.
+- **CREDIT_LIMIT_EXCEEDED**: Cumulative credited quantity or amount exceeds the original invoice baseline.
+
+## Test Cases
+
+- issues a credit note within the original invoice baseline
+- throws when credit quantity exceeds original billed quantity
+- throws when credit note is not in DRAFT status

package/src/modules/sales/docs/commands/IssueSalesInvoice.md

@@ -0,0 +1,43 @@
+# IssueSalesInvoice
+
+## Overview
+
+IssueSalesInvoice validates billing policy and freezes the invoice as customer-facing commercial evidence. It snapshots due schedule, payment-term, tax, and pricing context for downstream receivable processing.
+
+## Business Rules
+
+- Only DRAFT invoices may be issued.
+- Shipment-gated invoices must not exceed posted shipment quantity unless policy explicitly allows pre-shipment billing.
+- Order-based invoices must not exceed ordered quantity or diverge from the order price snapshot.
+- Issueing the invoice must compute and store the invoice due schedule.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive issue request] --> B[Load draft invoice]
+    B --> C[Validate billing policy and line quantities]
+    C --> D[Calculate due schedule and snapshot commercial context]
+    D --> E[Set status to ISSUED]
+    E --> F[Return issued invoice]
+```
+
+## External Dependencies
+
+- [getSalesInvoice](../queries/GetSalesInvoice.md) - Load invoice and line context.
+- [calculateInvoiceDueSchedule](../queries/CalculateInvoiceDueSchedule.md) - Compute receivable due schedule from invoice date and payment term.
+- [getShipment](../queries/GetShipment.md) - Validate posted shipment evidence for shipment-gated billing.
+
+## Error Scenarios
+
+- **SALES_INVOICE_NOT_FOUND**: Referenced sales invoice does not exist.
+- **INVALID_INVOICE_STATUS**: Only DRAFT invoices may be issued.
+- **BILLING_POLICY_VIOLATION**: Invoice quantity exceeds allowed order-based or shipment-based quantity.
+- **DUE_SCHEDULE_NOT_COMPUTABLE**: The assigned payment term cannot produce a due schedule.
+
+## Test Cases
+
+- issues an order-based invoice when quantities and prices are valid
+- issues a shipment-gated invoice when posted shipment evidence exists
+- throws when draft invoice exceeds allowed billed quantity
+- throws when due schedule cannot be computed

package/src/modules/sales/docs/commands/MarkChannelOrderException.md

@@ -0,0 +1,37 @@
+# MarkChannelOrderException
+
+## Overview
+
+MarkChannelOrderException moves a pending channel order into EXCEPTION status with actionable retry context. It separates recoverable normalization or mapping failure from successful conversion flow.
+
+## Business Rules
+
+- Only PENDING_CONVERSION channel orders may enter EXCEPTION through this command.
+- A non-empty error summary or retry context is required.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive exception request] --> B[Load channel order]
+    B --> C{Status is PENDING_CONVERSION?}
+    C -->|No| D[Return INVALID_CHANNEL_ORDER_STATUS]
+    C -->|Yes| E[Store error context and set status to EXCEPTION]
+    E --> F[Return exceptional channel order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHANNEL_ORDER_NOT_FOUND**: Referenced channel order does not exist.
+- **INVALID_CHANNEL_ORDER_STATUS**: Only pending channel orders may move to EXCEPTION.
+- **EXCEPTION_CONTEXT_REQUIRED**: Retry or troubleshooting context is required.
+
+## Test Cases
+
+- marks a pending channel order as exception with retry context
+- throws when channel order is not pending conversion
+- throws when exception context is empty

package/src/modules/sales/docs/commands/PauseListing.md

@@ -0,0 +1,36 @@
+# PauseListing
+
+## Overview
+
+PauseListing temporarily removes a listing from active sellability while preserving all historical identifiers and audit context.
+
+## Business Rules
+
+- Only ACTIVE listings may be paused.
+- Pausing a listing must not erase external identifiers needed for future reactivation or historical order support.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive pause request] --> B[Load listing]
+    B --> C{Status is ACTIVE?}
+    C -->|No| D[Return INVALID_LISTING_STATUS]
+    C -->|Yes| E[Set status to PAUSED]
+    E --> F[Return paused listing]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **LISTING_NOT_FOUND**: Referenced listing does not exist.
+- **INVALID_LISTING_STATUS**: Only ACTIVE listings may be paused.
+
+## Test Cases
+
+- pauses an active listing
+- preserves identifiers when listing is paused
+- throws when listing is not active

package/src/modules/sales/docs/commands/PlaceSalesOrderOnCreditHold.md

@@ -0,0 +1,41 @@
+# PlaceSalesOrderOnCreditHold
+
+## Overview
+
+PlaceSalesOrderOnCreditHold suspends further shipment or invoice release on an executable order without cancelling the underlying customer commitment. The command is used for credit, compliance, or dispute review events that temporarily block execution.
+
+## Business Rules
+
+- Only executable orders may be placed on credit hold.
+- A non-empty hold reason is required.
+- Placing the order on hold must not erase already posted shipment or issued invoice progress.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive hold request] --> B[Load sales order]
+    B --> C{Order executable?}
+    C -->|No| D[Return INVALID_ORDER_STATUS]
+    C -->|Yes| E{Reason provided?}
+    E -->|No| F[Return HOLD_REASON_REQUIRED]
+    E -->|Yes| G[Store hold reason and set status to CREDIT_HOLD]
+    G --> H[Return held order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Only executable orders may be placed on credit hold.
+- **HOLD_REASON_REQUIRED**: A hold reason is required.
+
+## Test Cases
+
+- places a confirmed order on credit hold
+- preserves prior shipment and invoice progress when placing hold
+- throws when order is not in an executable status
+- throws when hold reason is empty

package/src/modules/sales/docs/commands/PostShipment.md

@@ -0,0 +1,41 @@
+# PostShipment
+
+## Overview
+
+PostShipment turns a draft shipment into immutable fulfillment evidence. It updates sales-order shipped progress and emits the outbound inventory handoff for stock lines.
+
+## Business Rules
+
+- Only DRAFT shipments may be posted.
+- Posted quantities cannot exceed the remaining shippable quantity on each referenced order line unless a future override flow is introduced.
+- Stock lines must emit the outbound inventory handoff exactly once at posting time.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive post request] --> B[Load draft shipment]
+    B --> C[Validate posted quantities and order status]
+    C --> D[Update sales-order shipped progress]
+    D --> E[Emit outbound shipment handoff]
+    E --> F[Set shipment status to POSTED]
+    F --> G[Return posted shipment]
+```
+
+## External Dependencies
+
+- [getShipment](../queries/GetShipment.md) - Load shipment details and referenced lines.
+- [inventory::ReserveStock](../../../inventory/docs/commands/ReserveStock.md) - Downstream inventory execution contract reference.
+
+## Error Scenarios
+
+- **SHIPMENT_NOT_FOUND**: Referenced shipment does not exist.
+- **INVALID_SHIPMENT_STATUS**: Only DRAFT shipments may be posted.
+- **OVER_SHIPMENT_NOT_ALLOWED**: Posted quantity exceeds remaining open quantity.
+
+## Test Cases
+
+- posts a shipment and updates order shipped progress
+- emits downstream inventory handoff for stock lines
+- throws when shipment quantity exceeds remaining order quantity
+- throws when posting a non-draft shipment

package/src/modules/sales/docs/commands/RecordChannelOrder.md

@@ -0,0 +1,45 @@
+# RecordChannelOrder
+
+## Overview
+
+RecordChannelOrder creates or refreshes the normalized representation of an external order payload. It is the idempotent write path that stores source identity, normalized commercial fields, raw troubleshooting context, and the initial PENDING_CONVERSION lifecycle state.
+
+## Business Rules
+
+- Channel-order identity must be unique by company, channel, and external order identity.
+- The command must be idempotent across duplicate deliveries of the same external event.
+- A newly created channel order always starts in PENDING_CONVERSION status.
+- Raw payload reference or normalized troubleshooting context must be preserved.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive inbound payload] --> B[Resolve channel and external identity]
+    B --> C{Channel order already exists?}
+    C -->|No| D[Create ChannelOrder in PENDING_CONVERSION]
+    C -->|Yes| E[Update existing ChannelOrder idempotently]
+    D --> F[Persist normalized payload context]
+    E --> F
+    F --> G[Return recorded channel order]
+```
+
+## External Dependencies
+
+- [getChannel](../queries/GetChannel.md) - Validate channel scope for the inbound order.
+- [getListingByExternalIdentifier](../queries/GetListingByExternalIdentifier.md) - Resolve listing mapping from external identifiers when available.
+
+## Error Scenarios
+
+- **CHANNEL_NOT_FOUND**: Referenced channel does not exist.
+- **EXTERNAL_ORDER_ID_REQUIRED**: External order identity is required.
+- **CROSS_COMPANY_REFERENCE**: Inbound order data resolved to a different company scope.
+
+## Test Cases
+
+- creates a new pending channel order from inbound payload
+- updates an existing channel order idempotently on duplicate delivery
+- preserves raw troubleshooting context
+- throws when external order identity is missing
+- throws when the channel does not exist
+- throws on cross-company reference

package/src/modules/sales/docs/commands/RejectSalesOrder.md

@@ -0,0 +1,41 @@
+# RejectSalesOrder
+
+## Overview
+
+RejectSalesOrder returns a submitted sales order to DRAFT with an explicit rejection reason. It preserves review feedback without discarding the commercial work already entered on the order.
+
+## Business Rules
+
+- Only SUBMITTED orders may be rejected.
+- A non-empty rejection reason is required.
+- Rejecting the order must preserve existing lines and snapshots already prepared in draft.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reject request] --> B[Load sales order]
+    B --> C{Status is SUBMITTED?}
+    C -->|No| D[Return INVALID_ORDER_STATUS]
+    C -->|Yes| E{Reason provided?}
+    E -->|No| F[Return REJECTION_REASON_REQUIRED]
+    E -->|Yes| G[Store rejection reason and set status to DRAFT]
+    G --> H[Return rejected order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Only SUBMITTED orders may be rejected.
+- **REJECTION_REASON_REQUIRED**: A rejection reason is required.
+
+## Test Cases
+
+- rejects a submitted order and returns it to DRAFT
+- stores the rejection reason
+- throws when rejecting an order outside SUBMITTED status
+- throws when rejection reason is empty

package/src/modules/sales/docs/commands/ReleaseSalesOrderCreditHold.md

@@ -0,0 +1,36 @@
+# ReleaseSalesOrderCreditHold
+
+## Overview
+
+ReleaseSalesOrderCreditHold removes a commercial hold and returns the order to its executable lifecycle. It restores downstream shipment and invoice eligibility without losing prior fulfillment or billing evidence.
+
+## Business Rules
+
+- Only CREDIT_HOLD orders may be released.
+- The prior executable progress baseline must remain intact after release.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive release request] --> B[Load sales order]
+    B --> C{Status is CREDIT_HOLD?}
+    C -->|No| D[Return INVALID_ORDER_STATUS]
+    C -->|Yes| E[Restore executable lifecycle status]
+    E --> F[Return released order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_NOT_FOUND**: Referenced sales order does not exist.
+- **INVALID_ORDER_STATUS**: Only CREDIT_HOLD orders may be released.
+
+## Test Cases
+
+- releases a held order back to executable status
+- preserves shipment and invoice progress when releasing hold
+- throws when order is not on credit hold

package/src/modules/sales/docs/commands/RetireListing.md

@@ -0,0 +1,36 @@
+# RetireListing
+
+## Overview
+
+RetireListing permanently removes a listing from active sellability while preserving its history for channel-order traceability.
+
+## Business Rules
+
+- DRAFT, ACTIVE, and PAUSED listings may be retired.
+- Retiring a listing must preserve historical channel-order references and external identifiers for support lookup.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive retire request] --> B[Load listing]
+    B --> C{Status allows retirement?}
+    C -->|No| D[Return INVALID_LISTING_STATUS]
+    C -->|Yes| E[Set status to RETIRED]
+    E --> F[Return retired listing]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **LISTING_NOT_FOUND**: Referenced listing does not exist.
+- **INVALID_LISTING_STATUS**: Listing status does not allow retirement.
+
+## Test Cases
+
+- retires a draft or active listing
+- preserves historical references after retirement
+- throws when listing status does not allow retirement