@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/sales/docs/queries/GetSalesInvoice.md

@@ -0,0 +1,34 @@
+# GetSalesInvoice
+
+## Overview
+
+GetSalesInvoice retrieves one sales invoice with line, due-schedule, and status detail for billing or downstream AR handoff support.
+
+## Business Rules
+
+- Lookup by id performs an exact invoice match.
+- The query returns DRAFT, ISSUED, SENT, and CANCELLED invoices.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive invoice id] --> B[Query SalesInvoice and SalesInvoiceLine]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return invoice with lines and schedule]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching sales invoice exists.
+
+## Test Cases
+
+- returns invoice when found by id
+- returns issued invoice with due schedule
+- returns null when invoice is not found

package/src/modules/sales/docs/queries/GetSalesOrder.md

@@ -0,0 +1,36 @@
+# GetSalesOrder
+
+## Overview
+
+GetSalesOrder retrieves one sales order by identifier, returning header, line, customer, channel, payment-term, and progress details needed by sales, fulfillment, and billing workflows.
+
+## Business Rules
+
+- Lookup by id performs an exact sales-order match.
+- Returned payload includes line-level shipped, invoiced, and remaining quantities.
+- The query may return any lifecycle status, including CANCELLED or CLOSED.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive sales-order id] --> B[Query SalesOrder and SalesOrderLine]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Assemble order with progress details]
+    E --> F[Return sales order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching sales order exists.
+
+## Test Cases
+
+- returns sales order when found by id
+- returns line-level shipped and invoiced progress
+- returns null when sales order is not found

package/src/modules/sales/docs/queries/GetSalesPaymentTerm.md

@@ -0,0 +1,34 @@
+# GetSalesPaymentTerm
+
+## Overview
+
+GetSalesPaymentTerm retrieves one payment-term definition with its schedule-line content and discount metadata.
+
+## Business Rules
+
+- Lookup by id performs an exact payment-term match.
+- The query returns DRAFT, ACTIVE, and INACTIVE terms.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive payment-term id] --> B[Query SalesPaymentTerm]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return payment term]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching sales payment term exists.
+
+## Test Cases
+
+- returns payment term when found
+- returns inactive payment term when requested directly
+- returns null when payment term is not found

package/src/modules/sales/docs/queries/GetSalesPriceList.md

@@ -0,0 +1,34 @@
+# GetSalesPriceList
+
+## Overview
+
+GetSalesPriceList retrieves one sales price list by identifier, including company scope and lifecycle status.
+
+## Business Rules
+
+- Lookup by id performs an exact price-list match.
+- The query returns DRAFT, ACTIVE, and INACTIVE price lists.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive price-list id] --> B[Query SalesPriceList]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return price list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching sales price list exists.
+
+## Test Cases
+
+- returns price list when found by id
+- returns inactive price list when requested by id
+- returns null when price list is not found

package/src/modules/sales/docs/queries/GetShipment.md

@@ -0,0 +1,34 @@
+# GetShipment
+
+## Overview
+
+GetShipment retrieves one shipment with posted quantities, draft details, and customer-facing shipment context.
+
+## Business Rules
+
+- Lookup by id performs an exact shipment match.
+- The query returns both DRAFT and POSTED shipments.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive shipment id] --> B[Query Shipment and ShipmentLine]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return shipment with lines]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching shipment exists.
+
+## Test Cases
+
+- returns shipment when found by id
+- returns posted shipment with lines
+- returns null when shipment is not found

package/src/modules/sales/docs/queries/GetSyncJob.md

@@ -0,0 +1,34 @@
+# GetSyncJob
+
+## Overview
+
+GetSyncJob retrieves one sync-job execution record with direction, timing, counts, and terminal outcome detail.
+
+## Business Rules
+
+- Lookup by id performs an exact sync-job match.
+- The query returns running and terminal sync-job states.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive sync-job id] --> B[Query SyncJob]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return sync job]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching sync job exists.
+
+## Test Cases
+
+- returns sync job when found by id
+- returns failed sync job with counts and error summary
+- returns null when sync job is not found

package/src/modules/sales/docs/queries/ListChannelOrdersByStatus.md

@@ -0,0 +1,34 @@
+# ListChannelOrdersByStatus
+
+## Overview
+
+ListChannelOrdersByStatus lists channel orders for operational support queues such as pending conversion, exception replay, or cancellation review.
+
+## Business Rules
+
+- Company scope and at least one status value are required.
+- The query may additionally filter by channel or date range.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive filters] --> B[Validate company and status filters]
+    B --> C[Query matching channel orders]
+    C --> D[Return channel-order summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **STATUS_FILTER_REQUIRED**: At least one status filter is required.
+
+## Test Cases
+
+- lists pending conversion channel orders
+- lists exceptional channel orders for replay
+- filters results by channel when provided
+- throws when no status filter is provided

package/src/modules/sales/docs/queries/ListChannels.md

@@ -0,0 +1,33 @@
+# ListChannels
+
+## Overview
+
+ListChannels lists channels for commerce administration, support, and sync-operations planning.
+
+## Business Rules
+
+- Company scope is required.
+- Status filter is optional; omitted status returns all lifecycle states.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive list filters] --> B[Validate company scope]
+    B --> C[Query matching channels]
+    C --> D[Return channel summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope is required.
+
+## Test Cases
+
+- lists channels by company
+- filters channels by status when provided
+- throws when company scope is missing

package/src/modules/sales/docs/queries/ListListingsByChannel.md

@@ -0,0 +1,33 @@
+# ListListingsByChannel
+
+## Overview
+
+ListListingsByChannel lists all listings defined under one channel so merchandising and support teams can review assortment state.
+
+## Business Rules
+
+- Channel identifier is required.
+- Returned listings may include active, paused, draft, and retired records unless a status filter narrows the result.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive channel id] --> B[Query listings by channel]
+    B --> C[Apply optional status filter]
+    C --> D[Return listing summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CHANNEL_ID_REQUIRED**: Channel id is required.
+
+## Test Cases
+
+- lists listings under a channel
+- filters listings by status when provided
+- throws when channel id is missing

package/src/modules/sales/docs/queries/ListSalesCreditNotesByInvoice.md

@@ -0,0 +1,33 @@
+# ListSalesCreditNotesByInvoice
+
+## Overview
+
+ListSalesCreditNotesByInvoice lists all credit notes issued against one invoice for dispute handling and downstream AR reconciliation.
+
+## Business Rules
+
+- Sales-invoice identifier is required.
+- Returned credit notes may include draft and issued states unless a status filter narrows the result.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive invoice id] --> B[Query credit notes by invoice]
+    B --> C[Apply optional status filter]
+    C --> D[Return credit-note history]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_INVOICE_ID_REQUIRED**: Sales-invoice id is required.
+
+## Test Cases
+
+- lists credit notes under an invoice
+- filters credit notes by status when provided
+- throws when invoice id is missing

package/src/modules/sales/docs/queries/ListSalesInvoicesBySalesOrder.md

@@ -0,0 +1,33 @@
+# ListSalesInvoicesBySalesOrder
+
+## Overview
+
+ListSalesInvoicesBySalesOrder lists invoices issued against one sales order so billing teams can review partial or final billing history.
+
+## Business Rules
+
+- Sales-order identifier is required.
+- Returned invoices may be draft, issued, sent, or cancelled unless a status filter narrows the result.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive sales-order id] --> B[Query invoices by sales order]
+    B --> C[Apply optional status filter]
+    C --> D[Return invoice history]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_ID_REQUIRED**: Sales-order id is required.
+
+## Test Cases
+
+- lists invoices under a sales order
+- filters invoices by status when provided
+- throws when sales-order id is missing

package/src/modules/sales/docs/queries/ListSalesOrders.md

@@ -0,0 +1,36 @@
+# ListSalesOrders
+
+## Overview
+
+ListSalesOrders lists sales orders for operational monitoring and work queues. It supports filtering by company, customer, status, channel, and date ranges while returning summary progress fields.
+
+## Business Rules
+
+- At least company scope is required for multi-tenant safety.
+- Status filters are optional; omitted status filter returns all statuses.
+- Returned rows include summary open-balance metrics for fulfillment and billing work.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive filter criteria] --> B[Validate company scope]
+    B --> C[Query matching SalesOrders]
+    C --> D[Compute summary progress fields]
+    D --> E[Return matching orders]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope is required.
+
+## Test Cases
+
+- lists sales orders by company scope
+- filters sales orders by status and customer when provided
+- returns summary open-balance metrics
+- throws when company scope is missing

package/src/modules/sales/docs/queries/ListSalesPaymentTerms.md

@@ -0,0 +1,33 @@
+# ListSalesPaymentTerms
+
+## Overview
+
+ListSalesPaymentTerms lists payment terms available for sales assignment and administrative review.
+
+## Business Rules
+
+- Company scope is required.
+- Status filter is optional; omitted status returns all lifecycle states.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive list filters] --> B[Validate company scope]
+    B --> C[Query matching payment terms]
+    C --> D[Return payment-term summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope is required.
+
+## Test Cases
+
+- lists payment terms by company
+- filters payment terms by status when provided
+- throws when company scope is missing

package/src/modules/sales/docs/queries/ListSalesPriceLists.md

@@ -0,0 +1,33 @@
+# ListSalesPriceLists
+
+## Overview
+
+ListSalesPriceLists lists sales price lists for pricing administration. It supports company and lifecycle filtering and returns summary metadata needed for pricing maintenance.
+
+## Business Rules
+
+- Company scope is required.
+- Status filter is optional; omitted status returns all lifecycle states.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive list filters] --> B[Validate company scope]
+    B --> C[Query matching sales price lists]
+    C --> D[Return price-list summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope is required.
+
+## Test Cases
+
+- lists sales price lists by company
+- filters price lists by lifecycle status
+- throws when company scope is missing

package/src/modules/sales/docs/queries/ListSalesPriceRulesByPriceList.md

@@ -0,0 +1,33 @@
+# ListSalesPriceRulesByPriceList
+
+## Overview
+
+ListSalesPriceRulesByPriceList lists pricing rules maintained under a selected sales price list so pricing administrators can review scope, precedence, and lifecycle.
+
+## Business Rules
+
+- Referenced sales price list must exist.
+- The query returns rules across draft, active, and inactive states unless a status filter narrows the result.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive sales price list id] --> B[Query SalesPriceRule by price list]
+    B --> C[Apply optional status filter]
+    C --> D[Return matching rules]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: Referenced sales price list does not exist.
+
+## Test Cases
+
+- lists rules under a sales price list
+- filters rules by lifecycle status when provided
+- throws when price list is not found

package/src/modules/sales/docs/queries/ListShipmentsBySalesOrder.md

@@ -0,0 +1,33 @@
+# ListShipmentsBySalesOrder
+
+## Overview
+
+ListShipmentsBySalesOrder lists all shipments created for one sales order so fulfillment and billing teams can review shipment history and posted evidence.
+
+## Business Rules
+
+- Sales-order identifier is required.
+- Returned result may include draft and posted shipments for the order.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive sales-order id] --> B[Query shipments by sales order]
+    B --> C[Sort shipments by creation or ship date]
+    C --> D[Return shipment history]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SALES_ORDER_ID_REQUIRED**: Sales-order id is required.
+
+## Test Cases
+
+- lists shipments under a sales order
+- returns both draft and posted shipments when present
+- throws when sales-order id is missing

package/src/modules/sales/docs/queries/ListSyncJobs.md

@@ -0,0 +1,34 @@
+# ListSyncJobs
+
+## Overview
+
+ListSyncJobs lists sync-job executions for monitoring, replay management, and integration support.
+
+## Business Rules
+
+- Company scope is required.
+- Optional filters include channel, direction, and terminal status.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive list filters] --> B[Validate company scope]
+    B --> C[Query matching sync jobs]
+    C --> D[Return sync-job summaries]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **COMPANY_SCOPE_REQUIRED**: Company scope is required.
+
+## Test Cases
+
+- lists sync jobs by company
+- filters sync jobs by channel and direction when provided
+- filters sync jobs by terminal status when provided
+- throws when company scope is missing