@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/sales/docs/models/SalesOrder.md

@@ -0,0 +1,79 @@
+# SalesOrder
+
+## Description
+
+SalesOrder is the primary commercial commitment between one company and one customer. It captures customer, channel, billing, shipping, payment-term, and pricing context before downstream fulfillment or invoicing occurs, and it preserves the commercial baseline that shipment, invoice, and credit-note records must reference later. The aggregate includes one or more SalesOrderLine children that track ordered, shipped, invoiced, and remaining quantities per sellable item.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createSalesOrder
+    Draft --> Submitted: submitSalesOrder
+    Submitted --> Draft: rejectSalesOrder
+    Submitted --> Confirmed: confirmSalesOrder
+    Confirmed --> CreditHold: placeSalesOrderOnCreditHold
+    CreditHold --> Confirmed: releaseSalesOrderCreditHold
+    Confirmed --> PartiallyShipped: postShipment
+    PartiallyShipped --> Shipped: postShipment
+    Confirmed --> PartiallyInvoiced: issueSalesInvoice
+    PartiallyShipped --> PartiallyInvoiced: issueSalesInvoice
+    Shipped --> PartiallyInvoiced: issueSalesInvoice
+    PartiallyInvoiced --> Invoiced: issueSalesInvoice
+    Confirmed --> Cancelled: cancelSalesOrder
+    CreditHold --> Cancelled: cancelSalesOrder
+    Draft --> Cancelled: cancelSalesOrder
+    Submitted --> Cancelled: cancelSalesOrder
+    Shipped --> Closed: closeSalesOrder
+    Invoiced --> Closed: closeSalesOrder
+    PartiallyShipped --> Closed: closeSalesOrder
+    PartiallyInvoiced --> Closed: closeSalesOrder
+```
+
+### Command Definitions
+
+- [createSalesOrder](../commands/CreateSalesOrder.md) - Create a new draft sales order with initial line-level commercial context.
+- [updateSalesOrder](../commands/UpdateSalesOrder.md) - Revise mutable draft fields and line details before submission or explicit revision flow.
+- [submitSalesOrder](../commands/SubmitSalesOrder.md) - Move a draft order into review-ready submitted status.
+- [rejectSalesOrder](../commands/RejectSalesOrder.md) - Return a submitted order to draft with a preserved rejection reason.
+- [confirmSalesOrder](../commands/ConfirmSalesOrder.md) - Freeze commercial terms and make the order executable.
+- [placeSalesOrderOnCreditHold](../commands/PlaceSalesOrderOnCreditHold.md) - Suspend further shipment or invoice release with an explicit commercial hold reason.
+- [releaseSalesOrderCreditHold](../commands/ReleaseSalesOrderCreditHold.md) - Restore an order from credit hold to the executable confirmed lifecycle.
+- [cancelSalesOrder](../commands/CancelSalesOrder.md) - Cancel an order that has not progressed into an irreversible downstream state.
+- [closeSalesOrder](../commands/CloseSalesOrder.md) - Close the remaining open balance when execution is complete or written off by policy.
+
+### Query Definitions
+
+- [getSalesOrder](../queries/GetSalesOrder.md) - Retrieve one sales order with customer, status, line, and progress details.
+- [listSalesOrders](../queries/ListSalesOrders.md) - List sales orders for operational work queues and sales monitoring.
+
+### Models
+
+- SalesOrder
+- SalesOrderLine
+
+### Invariants
+
+- Every sales order belongs to exactly one company and one customer, and all child lines stay within that same company scope.
+- A sales order always contains at least one sales order line before it can leave DRAFT.
+- Only ACTIVE business partners carrying the CUSTOMER role can be used as the customer on a new or confirmed sales order.
+- Each line preserves the applied unit price, currency, matched price-rule reference, and payment-term snapshot so later master-data edits do not rewrite the confirmed commercial baseline.
+- When the order is in CREDIT_HOLD, no new shipment posting or invoice issuance may proceed until the hold is released.
+- The cumulative shipped quantity and cumulative invoiced quantity for each line can never exceed the ordered quantity unless a documented override flow is introduced later.
+- An order can move to CLOSED only when every remaining obligation is fulfilled, cancelled, or explicitly written off by policy.
+
+### Relationships
+
+- **Owns SalesOrderLine**: SalesOrder is the aggregate root for one or more SalesOrderLine children.
+- **References BusinessPartner (cross-module)**: `customerId`, billing address snapshot, shipping address snapshot, and customer tax identifiers come from business-partner.
+- **References SalesPaymentTerm**: `paymentTermId` and a normalized payment-term snapshot drive downstream invoice due schedules.
+- **References Channel**: `channelId` is optional and links internally entered or channel-originated demand to its commercial channel context.
+- **Referenced By Shipment**: Shipment records consume open sales-order quantities for fulfillment evidence.
+- **Referenced By SalesInvoice and SalesCreditNote**: Billing documents must point back to the originating commercial commitment.
+- **Referenced By ChannelOrder**: Converted channel orders store the internal sales-order linkage after normalization succeeds.

package/src/modules/sales/docs/models/SalesOrderLine.md

@@ -0,0 +1,42 @@
+# SalesOrderLine
+
+## Description
+
+SalesOrderLine represents one sellable obligation within a sales order. It stores the item, ordered quantity, selling unit, commercial price snapshot, requested fulfillment date, billing policy hints, and cumulative shipped or invoiced progress needed to calculate what remains to ship or invoice.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createSalesOrder](../commands/CreateSalesOrder.md) - Create initial order lines when the sales order is first drafted.
+- [updateSalesOrder](../commands/UpdateSalesOrder.md) - Add, remove, or revise draft order lines before the commercial baseline is confirmed.
+- [confirmSalesOrder](../commands/ConfirmSalesOrder.md) - Freeze line-level pricing, payment, and fulfillment snapshots at confirmation time.
+- [closeSalesOrder](../commands/CloseSalesOrder.md) - Mark remaining line balance as complete, cancelled, or written off when the order closes.
+
+### Query Definitions
+
+- [getSalesOrder](../queries/GetSalesOrder.md) - Return line-level item, quantity, and progress details inside one sales order.
+- [listSalesOrders](../queries/ListSalesOrders.md) - Expose line summaries for sales and fulfillment work queues.
+
+### Models
+
+- SalesOrderLine
+
+### Invariants
+
+- Every sales order line belongs to exactly one sales order and inherits its company scope.
+- Each line must reference one ACTIVE sellable item, a positive ordered quantity, and a non-negative unit price.
+- Remaining quantity to ship and remaining quantity to invoice are derived from the immutable ordered quantity and the cumulative posted shipment or issued invoice evidence.
+- Once the parent order is confirmed, line-level commercial fields are immutable unless an explicit revision workflow is introduced.
+
+### Relationships
+
+- **Belongs To SalesOrder**: `salesOrderId` ties the line to its parent order aggregate.
+- **References Item (cross-module)**: `itemId` must point to an ACTIVE item from item-management.
+- **References SalesPriceRule**: `matchedPriceRuleId` is optional and records which rule defaulted the commercial price.
+- **Referenced By ShipmentLine**: Shipment lines consume open shippable quantity from one order line.
+- **Referenced By SalesInvoiceLine**: Invoice lines validate billed quantity and price against one order line.

package/src/modules/sales/docs/models/SalesPaymentTerm.md

@@ -0,0 +1,53 @@
+# SalesPaymentTerm
+
+## Description
+
+SalesPaymentTerm defines reusable receivable timing rules for sales orders and invoices. It stores one or more schedule lines plus optional early-payment discount metadata so invoice due schedules can be calculated deterministically from the invoice date without embedding finance logic into the customer master.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createSalesPaymentTerm
+    Draft --> Active: activateSalesPaymentTerm
+    Active --> Inactive: deactivateSalesPaymentTerm
+```
+
+### Command Definitions
+
+- [createSalesPaymentTerm](../commands/CreateSalesPaymentTerm.md) - Create a draft payment term with one or more schedule lines.
+- [updateSalesPaymentTerm](../commands/UpdateSalesPaymentTerm.md) - Revise schedule lines or discount metadata while the term remains editable.
+- [activateSalesPaymentTerm](../commands/ActivateSalesPaymentTerm.md) - Make the term assignable to new orders and invoices.
+- [deactivateSalesPaymentTerm](../commands/DeactivateSalesPaymentTerm.md) - Prevent future assignment while preserving historical snapshots.
+
+### Query Definitions
+
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Retrieve one payment term and its schedule definition.
+- [listSalesPaymentTerms](../queries/ListSalesPaymentTerms.md) - List payment terms available for commercial assignment.
+- [calculateInvoiceDueSchedule](../queries/CalculateInvoiceDueSchedule.md) - Calculate the receivable schedule from an invoice date and term definition.
+
+### Models
+
+- SalesPaymentTerm
+- SalesPaymentTermScheduleLine
+
+### Invariants
+
+- Every payment term belongs to exactly one company.
+- A payment term must contain at least one schedule line.
+- Percentage-based schedule lines must sum to 100 percent across the term definition.
+- When early-payment discount metadata exists, its cutoff date logic must not fall after the final due date.
+- Only ACTIVE payment terms may be assigned to new draft sales orders or invoices.
+
+### Relationships
+
+- **Owns Payment-Term Schedule Lines**: A payment term contains one or more schedule definitions used to calculate due schedules.
+- **References Company (cross-module)**: `companyId` isolates receivable policy by legal entity.
+- **Referenced By SalesOrder**: Orders snapshot the assigned payment term for downstream billing.
+- **Referenced By SalesInvoice**: Issued invoices carry the normalized due schedule derived from the term.

package/src/modules/sales/docs/models/SalesPriceList.md

@@ -0,0 +1,50 @@
+# SalesPriceList
+
+## Description
+
+SalesPriceList groups reusable customer-facing price rules for one company. It provides the administrative boundary for activating, retiring, and auditing a commercial pricing set without forcing price logic into the item master itself.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createSalesPriceList
+    Draft --> Active: activateSalesPriceList
+    Active --> Inactive: deactivateSalesPriceList
+```
+
+### Command Definitions
+
+- [createSalesPriceList](../commands/CreateSalesPriceList.md) - Create a draft price list for one company and commercial context.
+- [updateSalesPriceList](../commands/UpdateSalesPriceList.md) - Revise list metadata while it remains editable.
+- [activateSalesPriceList](../commands/ActivateSalesPriceList.md) - Make the list available for price-rule resolution on new orders.
+- [deactivateSalesPriceList](../commands/DeactivateSalesPriceList.md) - Prevent future orders from using the list while preserving history.
+
+### Query Definitions
+
+- [getSalesPriceList](../queries/GetSalesPriceList.md) - Retrieve one price list with its company scope and activation state.
+- [listSalesPriceLists](../queries/ListSalesPriceLists.md) - List price lists for pricing administration and audit.
+- [listSalesPriceRulesByPriceList](../queries/ListSalesPriceRulesByPriceList.md) - List the rules maintained under a selected price list.
+
+### Models
+
+- SalesPriceList
+- SalesPriceRule
+
+### Invariants
+
+- Every price list belongs to exactly one company.
+- Only ACTIVE price lists may participate in new price resolution.
+- Deactivating a price list never mutates the snapshotted prices already stored on confirmed sales orders or issued invoices.
+
+### Relationships
+
+- **Owns SalesPriceRule**: A price list groups one or more SalesPriceRule records.
+- **References Company (cross-module)**: `companyId` scopes the list to a single legal entity.
+- **Referenced By SalesOrderLine**: Order lines may store the matched rule that came from a given list at defaulting time.

package/src/modules/sales/docs/models/SalesPriceRule.md

@@ -0,0 +1,51 @@
+# SalesPriceRule
+
+## Description
+
+SalesPriceRule is the actual commercial pricing condition resolved during sales-order entry. It captures the item scope, optional customer or channel scope, minimum quantity, effective dates, unit of measure, currency, explicit priority, and selling price that determine whether the rule is applicable to a draft order line.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createSalesPriceRule
+    Draft --> Active: activateSalesPriceRule
+    Active --> Inactive: deactivateSalesPriceRule
+```
+
+### Command Definitions
+
+- [createSalesPriceRule](../commands/CreateSalesPriceRule.md) - Create a draft pricing rule inside a company-scoped price list.
+- [updateSalesPriceRule](../commands/UpdateSalesPriceRule.md) - Adjust scope, price, dates, or quantity break before or after activation under controlled rules.
+- [activateSalesPriceRule](../commands/ActivateSalesPriceRule.md) - Make the rule eligible for deterministic price selection.
+- [deactivateSalesPriceRule](../commands/DeactivateSalesPriceRule.md) - Remove the rule from future matching without rewriting history.
+
+### Query Definitions
+
+- [getApplicableSalesPrice](../queries/GetApplicableSalesPrice.md) - Resolve the best matching rule and effective unit price for a draft sales-order context.
+- [listSalesPriceRulesByPriceList](../queries/ListSalesPriceRulesByPriceList.md) - List rules maintained under a selected price list.
+
+### Models
+
+- SalesPriceRule
+
+### Invariants
+
+- Every rule belongs to exactly one sales price list and one company context.
+- A rule must specify a non-negative minimum quantity, a positive unit price, a valid currency, and a valid sellable item scope.
+- If both effective start and end dates are present, the end date cannot precede the start date.
+- Two ACTIVE rules with indistinguishable precedence for the same commercial context are not allowed without an explicit tie-breaker priority.
+
+### Relationships
+
+- **Belongs To SalesPriceList**: `salesPriceListId` assigns the rule to a reusable pricing set.
+- **References Item (cross-module)**: `itemId` points to the sellable item being priced.
+- **References BusinessPartner (cross-module)**: `customerId` is optional for customer-specific commercial agreements.
+- **References Channel**: `channelId` is optional for marketplace or storefront-specific pricing.
+- **References primitives**: `currencyId` and `uomId` must align with primitives conversion support.

package/src/modules/sales/docs/models/Shipment.md

@@ -0,0 +1,49 @@
+# Shipment
+
+## Description
+
+Shipment is the sales-side fulfillment document that proves which order quantities were shipped, when they shipped, and from which site. It is the commercial handoff to inventory execution and the billing evidence for shipment-gated invoicing policies.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createShipment
+    Draft --> Posted: postShipment
+```
+
+### Command Definitions
+
+- [createShipment](../commands/CreateShipment.md) - Create a draft shipment against open sales-order lines.
+- [updateShipment](../commands/UpdateShipment.md) - Correct draft shipment details such as quantities, addresses, or tracking data before posting.
+- [postShipment](../commands/PostShipment.md) - Post the shipment, update order progress, and emit the outbound inventory handoff.
+
+### Query Definitions
+
+- [getShipment](../queries/GetShipment.md) - Retrieve one shipment with posted quantities, addresses, and tracking context.
+- [listShipmentsBySalesOrder](../queries/ListShipmentsBySalesOrder.md) - List shipments associated with a selected sales order.
+
+### Models
+
+- Shipment
+- ShipmentLine
+
+### Invariants
+
+- Every shipment belongs to exactly one company and references exactly one sales order.
+- Only DRAFT shipments may be edited directly.
+- Only POSTED shipment quantities contribute to sales-order shipped progress or shipment-gated invoice eligibility.
+- For stock items, posting emits exactly one outbound shipment handoff for each posted shipment line.
+
+### Relationships
+
+- **Owns ShipmentLine**: Each shipment contains one or more shipment lines tied to order lines.
+- **References SalesOrder**: `salesOrderId` identifies the originating commercial commitment.
+- **References Site (cross-module)**: `shipFromSiteId` comes from organization and records fulfillment origin.
+- **References inventory handoff contract**: Posting produces the `OutboundShipmentHandoff` payload for downstream stock execution.

package/src/modules/sales/docs/models/ShipmentLine.md

@@ -0,0 +1,38 @@
+# ShipmentLine
+
+## Description
+
+ShipmentLine records the quantity from one sales-order line that is included in a shipment. It preserves the shipped quantity, unit of measure, and customer-facing shipment context needed to calculate remaining open balance on the order.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createShipment](../commands/CreateShipment.md) - Create initial shipment lines from open sales-order lines.
+- [updateShipment](../commands/UpdateShipment.md) - Revise draft shipment quantities or tracking context before posting.
+- [postShipment](../commands/PostShipment.md) - Lock shipment quantities as posted fulfillment evidence.
+
+### Query Definitions
+
+- [getShipment](../queries/GetShipment.md) - Return line-level shipment evidence for one posted or draft shipment.
+- [listShipmentsBySalesOrder](../queries/ListShipmentsBySalesOrder.md) - Return shipment-line history under one sales order.
+
+### Models
+
+- ShipmentLine
+
+### Invariants
+
+- Every shipment line belongs to exactly one shipment and one sales-order line.
+- Shipped quantity must be greater than zero and may not exceed the remaining shippable quantity unless an explicit override policy is introduced later.
+- Service or non-stock lines may be recorded for customer traceability but do not require downstream inventory execution.
+
+### Relationships
+
+- **Belongs To Shipment**: `shipmentId` ties the line to its parent shipment.
+- **References SalesOrderLine**: `salesOrderLineId` identifies the commercial quantity being fulfilled.
+- **Referenced By SalesInvoiceLine**: Shipment-gated invoices may cite posted shipment lines as billing evidence.

package/src/modules/sales/docs/models/SyncJob.md

@@ -0,0 +1,53 @@
+# SyncJob
+
+## Description
+
+SyncJob records one import, export, retry, or replay execution against a channel integration. It is the operational log that captures timing, direction, counts, and error outcome separately from ChannelOrder business state so integration reliability can be managed without blurring demand semantics.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Running: startSyncJob
+    Running --> Succeeded: startSyncJob
+    Running --> PartiallySucceeded: startSyncJob
+    Running --> Failed: startSyncJob
+    Running --> Cancelled: cancelSyncJob
+    Failed --> Running: retrySyncJob
+    PartiallySucceeded --> Running: retrySyncJob
+    Cancelled --> Running: retrySyncJob
+```
+
+### Command Definitions
+
+- [startSyncJob](../commands/StartSyncJob.md) - Create and start a sync execution for one channel and direction.
+- [retrySyncJob](../commands/RetrySyncJob.md) - Replay a failed or partial sync job with controlled idempotency.
+- [cancelSyncJob](../commands/CancelSyncJob.md) - Stop a running or queued sync job when policy allows.
+
+### Query Definitions
+
+- [getSyncJob](../queries/GetSyncJob.md) - Retrieve one sync job with timing, counts, and error summary.
+- [listSyncJobs](../queries/ListSyncJobs.md) - List sync jobs for monitoring, support, and replay management.
+
+### Models
+
+- SyncJob
+
+### Invariants
+
+- Every sync job belongs to exactly one company and one channel.
+- A sync job records one direction at a time, such as import or outbound status push.
+- Processed, succeeded, failed, and retried counts reflect one execution attempt and do not silently merge unrelated runs.
+- Terminal sync-job outcome is tracked independently from ChannelOrder business state.
+
+### Relationships
+
+- **References Channel**: `channelId` scopes the integration execution context.
+- **References Company (cross-module)**: `companyId` ensures tenant-safe sync isolation.
+- **Referenced By ChannelOrder**: channel orders may store the originating or latest sync job for support traceability.

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

@@ -0,0 +1,37 @@
+# CalculateInvoiceDueSchedule
+
+## Overview
+
+CalculateInvoiceDueSchedule computes the receivable due schedule for an invoice date and sales payment term. It expands installment lines, end-of-month rules, and early-payment discount windows into deterministic due-schedule output.
+
+## Business Rules
+
+- Invoice date and payment-term reference are required inputs.
+- Percentage-based schedules must resolve to a full payable baseline.
+- End-of-month rules must use calendar-month logic rather than a fixed offset shortcut.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive invoice date and payment term] --> B[Load payment-term definition]
+    B --> C[Expand schedule-line rules]
+    C --> D[Calculate due dates and discount windows]
+    D --> E[Return computed due schedule]
+```
+
+## External Dependencies
+
+- [getSalesPaymentTerm](../queries/GetSalesPaymentTerm.md) - Load the assigned payment-term definition.
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Referenced payment term does not exist.
+- **INVALID_PAYMENT_TERM_DEFINITION**: Payment term definition cannot produce a deterministic due schedule.
+
+## Test Cases
+
+- calculates net-day due schedule
+- calculates installment due schedule
+- calculates end-of-month due schedule
+- throws when payment term definition is invalid

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

@@ -0,0 +1,38 @@
+# GetApplicableSalesPrice
+
+## Overview
+
+GetApplicableSalesPrice resolves the best matching commercial price for a draft sales-order line context. It evaluates active rules across price list, customer, channel, item, quantity, date, currency, unit of measure, and explicit priority to return a deterministic result or an unmatched outcome.
+
+## Business Rules
+
+- Only ACTIVE price lists and ACTIVE price rules participate in matching.
+- Rule precedence is deterministic across company, customer, channel, item, quantity break, date, and priority.
+- When no rule matches, the query returns an unmatched result rather than throwing so manual pricing remains possible.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive draft pricing context] --> B[Load active price lists and rules]
+    B --> C[Filter by company, item, customer, channel, date, quantity, currency, and UoM]
+    C --> D{Match found?}
+    D -->|No| E[Return unmatched result]
+    D -->|Yes| F[Apply deterministic precedence]
+    F --> G[Return selected rule and effective unit price]
+```
+
+## External Dependencies
+
+- [primitives::ConvertQuantity](../../../primitives/docs/queries/ConvertQuantity.md) - Support quantity-break comparison across compatible UoMs when needed.
+
+## Error Scenarios
+
+- **INVALID_PRICING_CONTEXT**: Required pricing inputs are missing or inconsistent.
+
+## Test Cases
+
+- returns the highest-precedence matching price rule
+- returns unmatched result when no active rule applies
+- resolves quantity-break pricing with compatible UoM conversion
+- throws when required pricing context is missing

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

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

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

@@ -0,0 +1,34 @@
+# GetChannelOrder
+
+## Overview
+
+GetChannelOrder retrieves one normalized channel order with mapping, linked sales-order, and troubleshooting context.
+
+## Business Rules
+
+- Lookup by id performs an exact channel-order match.
+- The query returns any channel-order lifecycle status, including EXCEPTION and CANCELLED_BY_CHANNEL.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive channel-order id] --> B[Query ChannelOrder]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return channel order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching channel order exists.
+
+## Test Cases
+
+- returns channel order when found by id
+- returns channel order with linked sales-order reference when converted
+- returns null when channel order is not found

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

@@ -0,0 +1,34 @@
+# GetListing
+
+## Overview
+
+GetListing retrieves one listing with channel, item, identifier, and sellability detail.
+
+## Business Rules
+
+- Lookup by id performs an exact listing match.
+- The query returns DRAFT, ACTIVE, PAUSED, and RETIRED listings.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive listing id] --> B[Query Listing]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return listing]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching listing exists.
+
+## Test Cases
+
+- returns listing when found by id
+- returns retired listing when requested directly
+- returns null when listing is not found

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

@@ -0,0 +1,35 @@
+# GetListingByExternalIdentifier
+
+## Overview
+
+GetListingByExternalIdentifier resolves the internal listing record from an external channel identifier. It is the lookup bridge used by channel-order ingestion and support tooling.
+
+## Business Rules
+
+- Channel identifier and external listing identifier are required.
+- The query returns retired listings when they must remain referenceable for historical support.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive channel id and external identifier] --> B[Query listing by channel and external identifier]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return listing]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **IDENTIFIER_REQUIRED**: Channel id and external identifier are required.
+
+## Test Cases
+
+- returns listing by external identifier
+- returns retired listing when historical reference is needed
+- returns null when no listing matches the external identifier
+- throws when channel id or external identifier is missing

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

@@ -0,0 +1,34 @@
+# GetSalesCreditNote
+
+## Overview
+
+GetSalesCreditNote retrieves one credit note with correction-line detail and linked invoice context.
+
+## Business Rules
+
+- Lookup by id performs an exact credit-note match.
+- The query returns DRAFT and ISSUED credit notes.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive credit-note id] --> B[Query SalesCreditNote and lines]
+    B --> C{Found?}
+    C -->|No| D[Return null]
+    C -->|Yes| E[Return credit note]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NONE**: Returns null when no matching sales credit note exists.
+
+## Test Cases
+
+- returns credit note when found by id
+- returns issued credit note with correction lines
+- returns null when credit note is not found