@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/sales/docs/features/sales-order-lifecycle.md

@@ -0,0 +1,96 @@
+# Sales Order Lifecycle
+
+## Overview
+
+Sales Order Lifecycle governs how a customer commitment is created, reviewed, confirmed, suspended on commercial hold, fulfilled, invoiced, and closed. A `SalesOrder` records the commercial agreement with a customer for one or more items, including ordered quantity, requested ship timing, unit price, currency, shipping and billing context, payment-term reference, and optional originating channel. The order is the primary document that downstream shipments and invoices reference.
+
+The lifecycle tracks both document control and execution progress. A sales order begins in draft, may be submitted for review, can be rejected back to draft with a reason, becomes confirmed when the commercial commitment is accepted, may be moved into `CREDIT_HOLD` when shipment or billing must pause without cancelling the order, and then moves through partial or full shipment and partial or full invoicing states as execution proceeds. This gives sales and operations teams one authoritative record of what is still owed to the customer and what is temporarily blocked for credit or compliance review.
+
+## Business Purpose
+
+- Create a formal, auditable customer commitment before fulfillment or invoicing occurs
+- Freeze commercial terms at order confirmation time even if future price lists or payment terms change
+- Capture customer, channel, billing, and shipping context needed for downstream fulfillment and invoicing
+- Allow a confirmed order to be paused in `CREDIT_HOLD` when credit exposure, compliance review, or dispute handling blocks further execution without voiding the commercial commitment
+- Track ordered quantity, shipped quantity, invoiced quantity, and remaining obligation per line
+- Provide the reference document required for shipment fulfillment and customer invoice generation
+- Support partial fulfillment and partial billing without losing visibility into remaining commitments
+- Prevent inactive customers, inactive items, or incomplete orders from entering downstream execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Sales Order] --> B[DRAFT]
+    B --> C[Add customer, lines, prices, terms]
+    C --> D{Submit?}
+    D -->|No| C
+    D -->|Yes| E[SUBMITTED]
+    E --> F{Approve or confirm?}
+    F -->|Reject| R[REJECTED]
+    R --> B
+    F -->|Confirm| G[CONFIRMED]
+    G --> H{Place credit hold?}
+    H -->|Yes| X[CREDIT_HOLD]
+    X --> Y{Release hold?}
+    Y -->|Yes| G
+    H -->|No| I{Shipment posted?}
+    I -->|Partial| J[PARTIALLY SHIPPED]
+    I -->|Full| K[SHIPPED]
+    J --> L{Invoice issued?}
+    K --> L
+    L -->|Partial| M[PARTIALLY INVOICED]
+    L -->|Full| N[INVOICED]
+    J --> O{Close remaining?}
+    K --> O
+    M --> O
+    N --> O
+    O -->|Close| Q[CLOSED]
+    B --> P[CANCELLED]
+    E --> P
+    G --> P
+    X --> P
+```
+
+## Scenario Patterns
+
+- **Direct sales entry**: A sales representative creates an order manually for an existing customer, confirms the commercial terms, and releases it to downstream fulfillment
+- **Channel-originated order**: A marketplace order is normalized into an internal sales order, preserving channel reference and channel-specific commercial context
+- **Rejected for correction**: An approver rejects a submitted order because the shipping address or payment term is wrong, and the order returns to draft with the rejection reason preserved
+- **Partial fulfillment with backorder**: Only some lines ship on time. The order remains open with remaining shippable quantity visible for later shipment
+- **Partial billing**: One shipment is invoiced immediately while the remaining order quantity stays open for later billing
+- **Credit review pause**: A confirmed order exceeds customer credit exposure, so the order moves to `CREDIT_HOLD` until finance releases it without forcing a new order
+- **Manual price override before confirmation**: A user starts from a defaulted price rule but overrides one line before confirmation due to a negotiated exception
+- **Service or non-stock order**: A service line is confirmed and invoiced without warehouse shipment, but the order still tracks billing and closure correctly
+- **Order cancellation before execution**: Demand disappears after submission and the order is cancelled before any shipment or invoice is issued
+- **Close remaining balance**: A customer declines the final backordered units and the user closes the remaining open quantity instead of keeping the order indefinitely active
+
+## Test Cases
+
+- Creating a sales order with a valid ACTIVE customer, company, and at least one line should succeed
+- A sales order line must require an ACTIVE item, quantity greater than zero, and a non-negative unit price
+- Sales orders can only be created in `DRAFT` status
+- A `DRAFT` order can be revised freely, but confirmed commercial fields must not change without an explicit revision workflow
+- Submitting a sales order without any lines should fail
+- Submitting a sales order without a shipping address when the line requires physical fulfillment should fail
+- Submitting a sales order for a partner that does not carry the CUSTOMER role should fail
+- Confirming a sales order whose customer is INACTIVE should fail
+- Rejecting a submitted sales order should record the rejection reason and return the document to `DRAFT`
+- Moving a confirmed sales order to `CREDIT_HOLD` should require an explicit hold reason and should block new shipment or invoice release actions until the hold is released
+- Releasing `CREDIT_HOLD` should return the order to the last executable confirmed state without losing shipped or invoiced progress already recorded
+- Cancelling a sales order after a posted shipment or issued invoice exists should be prevented unless a controlled downstream reversal flow exists
+- Posting a partial shipment should update line shipped quantities and move the order to a partial shipment status
+- Issuing an invoice should update line invoiced quantities independently of shipment quantities according to billing policy
+- Closing a sales order should be allowed only when all remaining open quantities are fulfilled, cancelled, or explicitly written off
+- Sales order totals and open balances must be isolated per company
+- The applied unit price on a sales order line must remain unchanged even if the underlying sales price rule is later edited
+- A sales order must preserve its assigned payment term snapshot for downstream invoice due-date calculation
+- Each sales order line should expose remaining quantity to ship and remaining quantity to invoice
+- Duplicate external customer order references should be rejected or flagged according to company policy
+- Only authorized sales users should be able to submit, confirm, place on hold, release, cancel, or close sales orders
+
+## Reference Links
+
+- [Odoo Sales orders documentation](https://www.odoo.com/documentation/19.0/applications/sales/sales/sales_quotations.html)
+- [Oracle Order Management documentation](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/index.html)
+- [SAP Sales Order processing overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/sales/docs/features/sales-payment-terms.md

@@ -0,0 +1,67 @@
+# Sales Payment Terms
+
+## Overview
+
+Sales Payment Terms defines how customer invoices become due once commercial billing is issued. A `SalesPaymentTerm` models rules such as net days, end-of-month due dates, installment splits, and early-payment discounts. These terms can default onto sales orders from the customer selling profile and flow forward into `SalesInvoice` so that the invoice carries the expected receivable schedule when handed off to downstream accounts receivable.
+
+The feature is intentionally limited to customer-facing receivable terms within sales. It does not execute payment capture, collection, or settlement. Instead, it standardizes the contractual timing information that sales operations and downstream finance both need.
+
+## Business Purpose
+
+- Standardize customer payment expectations across sales orders and invoices
+- Reduce manual invoice-entry work by defaulting due-date schedules from negotiated payment terms
+- Support installment or staged payment structures for milestone-based or large-value deals
+- Enable early-payment discount handling by making discount windows explicit and reusable
+- Provide a consistent handoff contract from sales to downstream accounts-receivable processing
+- Separate payment timing rules from customer master data so terms can evolve independently per transaction or commercial agreement
+- Preserve how discountable amount is interpreted by explicitly recording whether discount logic applies to gross or net invoice amount
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Define Sales Payment Term] --> B[Configure schedule lines and discount rules]
+    B --> C[Activate term]
+    C --> D[Default term from customer selling profile or assign manually to order]
+    D --> E[Sales Invoice created from order]
+    E --> F[Copy payment term snapshot to invoice]
+    F --> G[Calculate due dates and installment amounts]
+    G --> H[Invoice becomes ready for downstream AR processing]
+```
+
+## Scenario Patterns
+
+- **Net 30 standard term**: A customer agreement states payment is due 30 days after the invoice date, and every invoice using that term receives a single due date 30 days later
+- **2/10 net 30**: A customer receives a discount if the invoice is paid within 10 days; otherwise full payment is due in 30 days. The term captures both the discount window and the final due date
+- **Milestone billing**: A project order requires 50 percent due at invoice issue and 50 percent due 30 days later, and the payment term expresses two receivable schedule lines
+- **End-of-month settlement**: Invoices dated throughout the month become due at month end plus a fixed number of days, matching the customer's settlement policy
+- **Default term propagation**: A customer has a default sales payment term, and each new draft sales order starts with that term before the user decides whether to override it
+- **One-off override**: A customer usually receives net 45 terms, but a specific order is changed to net 15 because of expedited delivery and exceptional commercial approval
+- **Term retirement**: An old payment term is deactivated when the customer contract is renegotiated, but historical orders and invoices retain the prior snapshot
+- **Advance-payment agreement**: A deal requires an invoice with immediate due status before shipment, while the actual payment capture remains outside the sales module
+- **Discount visibility for AR**: The issued invoice exposes the discount cutoff date so downstream receivable automation can decide whether discount handling is allowed
+
+## Test Cases
+
+- Creating a sales payment term with at least one schedule line should succeed
+- The sum of installment percentages on a percentage-based payment term must equal 100 percent
+- A payment term schedule line must not allow a negative percentage or negative fixed amount
+- A discount date must occur on or before the final due date
+- A payment term that offers early-payment discount must record whether the discount base is `GROSS_AMOUNT` or `NET_AMOUNT`
+- Inactive payment terms must not be assignable to new sales orders or new invoices
+- When a customer selling profile provides a default payment term, a new draft sales order should inherit it automatically unless the user overrides it
+- A sales order should snapshot its assigned payment term so later edits do not alter existing downstream invoices
+- A sales invoice due-date schedule must be computable from the invoice date and the assigned payment term
+- End-of-month terms must produce a due date based on calendar month logic rather than a simple fixed-day offset
+- Installment terms should generate multiple due schedule lines on the customer invoice
+- Early-payment discount metadata must remain available after invoice issuance so downstream AR can consume it
+- A payment term can be overridden on a draft sales order but changing it after invoice issuance should be prevented or explicitly controlled
+- Sales payment terms must be isolated by company when receivable policies differ by legal entity
+- Deactivating a payment term that is already referenced historically must preserve existing order and invoice snapshots
+- Only authorized sales or finance users should be able to create, update, activate, or deactivate payment terms
+
+## Reference Links
+
+- [Odoo customer payment terms documentation](https://www.odoo.com/documentation/19.0/applications/finance/accounting/customer_invoices/payment_terms.html)
+- [Oracle receivables payment terms documentation](https://docs.oracle.com/en/cloud/saas/financials/index.html)
+- [SAP payment terms documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/sales/docs/features/shipment-fulfillment.md

@@ -0,0 +1,71 @@
+# Shipment Fulfillment
+
+## Overview
+
+Shipment Fulfillment records what quantity from a sales order has actually been committed to outbound delivery. A `Shipment` references one sales order and one or more sales order lines, captures ship dates, shipment quantities, delivery addresses, and external tracking context, and updates each line's shipped progress. The shipment document is the sales-side confirmation that the customer commitment moved into physical fulfillment.
+
+This feature deliberately separates **commercial shipment control** from **warehouse stock execution**. Sales owns the shipment document, backorder logic, customer-facing shipment status, and matching rules against the order; inventory remains the owner of reservation ledgers, stock issue execution, lot or serial state, and on-hand updates. The named handoff contract from sales to inventory is `OutboundShipmentHandoff`, whose minimum payload is sales order reference, sales order line reference, shipment reference, shipped quantity, unit of measure, source fulfillment site, and ship date.
+
+## Business Purpose
+
+- Confirm outbound fulfillment against the original customer commitment
+- Support partial shipments and backorders without losing order-level visibility
+- Provide the shipment basis required for shipment-gated billing policies
+- Trigger downstream stock issue and warehouse execution processes without moving warehouse logic into sales
+- Preserve customer-facing shipment traceability with shipment references and dates
+- Maintain an auditable record of what was shipped, when, from where, and against which sales commitment
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Sales Order in CONFIRMED status] --> B[Create Shipment]
+    B --> C[Select open order lines]
+    C --> D[Enter shipment quantities, ship-from site, and dates]
+    D --> E{Within open quantity?}
+    E -->|No| F[Block or require controlled override]
+    E -->|Yes| G[Post Shipment]
+    G --> H[Update order line shipped quantities]
+    G --> I[Emit outbound shipment handoff to inventory]
+    H --> J{All quantities shipped?}
+    J -->|No| K[Order remains PARTIALLY SHIPPED]
+    J -->|Yes| L[Order becomes SHIPPED]
+    G --> M[Shipment eligible for invoice generation when policy requires shipment evidence]
+```
+
+## Scenario Patterns
+
+- **Full shipment**: Every ordered line is shipped in one outbound document and a single posted shipment completes the fulfillment side of the order
+- **Partial shipment with backorder**: Only part of the demand ships now. The shipment posts successfully, open quantity remains on the order, and another shipment can be recorded later
+- **Multi-line mixed fulfillment**: One line on the order ships fully while another remains open, and the shipment captures both outcomes in the same document
+- **Channel SLA shipment**: A channel-originated order must be shipped within a short service window, and the shipment document preserves the promised ship date and actual ship date for compliance analysis
+- **Service line exclusion**: A service line on the same sales order is invoiced without a physical shipment, while stock items still require shipment evidence
+- **Tracking update before posting**: A fulfillment user notices the wrong carrier or tracking reference while the shipment is still draft and corrects it before posting
+- **Ship-from-site distinction**: An order is fulfilled from a different site than originally planned, and the shipment records the actual ship-from context for auditability
+- **Future shipment reversal**: A posted shipment is later found to be incorrect. A future reversal workflow will preserve the original posted shipment, emit a compensating correction, and keep the audit trail intact rather than mutating history
+- **Cross-channel status update**: After shipment posts, a later sync job can push shipped status back to the originating channel without the sales module embedding channel API logic in the shipment itself
+
+## Test Cases
+
+- Creating a shipment against a `CONFIRMED` sales order with open shippable quantity should succeed
+- A shipment line must reference a valid sales order line and a shipped quantity greater than zero
+- A cancelled or closed sales order must not accept new shipments
+- Posting a shipment must increase the referenced sales order line's cumulative shipped quantity
+- Partial shipments must leave the remaining open quantity available for future shipment
+- Shipping more than the remaining ordered quantity should fail or require an explicit override policy
+- A shipment posted for a stock item should emit or call the downstream inventory handoff contract exactly once
+- The `OutboundShipmentHandoff` payload must include sales order reference, sales order line reference, shipment reference, shipped quantity, UoM, source site, and ship date at minimum
+- A shipment posted for a non-stock or service line must not require inventory stock execution
+- Only posted shipments should count toward shipment-gated billing policies
+- Shipment posting must be isolated by company and must not update sales orders belonging to another company
+- If a shipment is reversed or corrected through a future workflow, the sales order shipped quantity must remain auditable rather than silently overwritten
+- Sales order status should move to a partial or full shipment state based on aggregate posted shipment quantities
+- Shipment posting should snapshot the customer shipping address used for fulfillment
+- Only authorized fulfillment or sales users should be able to post shipments
+- A shipment should preserve the customer, order, and line references needed for audit and customer support traceability
+
+## Reference Links
+
+- [Odoo delivery orders documentation](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/shipping_receiving/picking_methods.html)
+- [Oracle Shipping Execution documentation](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/index.html)
+- [SAP outbound delivery overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

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

@@ -0,0 +1,48 @@
+# Channel
+
+## Description
+
+Channel defines an external sell-side context such as a marketplace, storefront, or distributor feed. It scopes listing governance, channel-order synchronization, and channel-specific pricing or identifier behavior without embedding external API mechanics into every sales record.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createChannel
+    Draft --> Active: activateChannel
+    Active --> Inactive: deactivateChannel
+```
+
+### Command Definitions
+
+- [createChannel](../commands/CreateChannel.md) - Create a draft channel for one company and integration type.
+- [updateChannel](../commands/UpdateChannel.md) - Revise mutable channel metadata before or after activation under policy.
+- [activateChannel](../commands/ActivateChannel.md) - Make the channel available for listings and sync jobs.
+- [deactivateChannel](../commands/DeactivateChannel.md) - Stop future listing activation or new sync intake for the channel.
+
+### Query Definitions
+
+- [getChannel](../queries/GetChannel.md) - Retrieve one sales channel with company scope and status.
+- [listChannels](../queries/ListChannels.md) - List channels for commerce administration and support.
+
+### Models
+
+- Channel
+
+### Invariants
+
+- Every channel belongs to exactly one company.
+- Only ACTIVE channels may accept newly activated listings or newly started sync jobs unless a recovery policy explicitly allows otherwise.
+- Deactivating a channel preserves historical listing and channel-order references.
+
+### Relationships
+
+- **References Company (cross-module)**: `companyId` isolates channel operations by legal entity.
+- **Referenced By Listing**: Listings are defined within a specific channel context.
+- **Referenced By ChannelOrder and SyncJob**: Channel-originated order ingestion and sync execution are both scoped to one channel.

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

@@ -0,0 +1,56 @@
+# ChannelOrder
+
+## Description
+
+ChannelOrder stores the normalized representation of externally sourced demand before or alongside internal sales-order conversion. It preserves the originating channel identity, normalized commercial payload, raw troubleshooting context, and the operational lifecycle that distinguishes pending conversion, successful conversion, exception handling, and channel-side cancellation.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> PendingConversion: recordChannelOrder
+    PendingConversion --> Converted: convertChannelOrder
+    PendingConversion --> Exception: markChannelOrderException
+    Exception --> PendingConversion: recordChannelOrder
+    PendingConversion --> CancelledByChannel: cancelChannelOrder
+    Exception --> CancelledByChannel: cancelChannelOrder
+```
+
+### Command Definitions
+
+- [recordChannelOrder](../commands/RecordChannelOrder.md) - Create or refresh the normalized channel-order record from inbound payload data.
+- [convertChannelOrder](../commands/ConvertChannelOrder.md) - Materialize or link the internal sales order after mapping succeeds.
+- [markChannelOrderException](../commands/MarkChannelOrderException.md) - Move the order into an actionable exception state with retry context.
+- [cancelChannelOrder](../commands/CancelChannelOrder.md) - Record cancellation received from the originating channel before internal execution progresses too far.
+
+### Query Definitions
+
+- [getChannelOrder](../queries/GetChannelOrder.md) - Retrieve one normalized channel order with status, mapping, and linked sales-order details.
+- [listChannelOrdersByStatus](../queries/ListChannelOrdersByStatus.md) - List channel orders by operational lifecycle for support and replay queues.
+
+### Models
+
+- ChannelOrder
+- ChannelOrderLine
+
+### Invariants
+
+- Every channel order belongs to exactly one company and one originating channel.
+- The tuple of company, channel, and external order identity is unique so duplicate deliveries remain idempotent.
+- A channel order must enter PENDING_CONVERSION before an internal sales order is created or updated.
+- Moving to CONVERTED requires a stored link to the internal sales order.
+- Moving to EXCEPTION preserves actionable error context and retry metadata.
+
+### Relationships
+
+- **References Channel**: `channelId` identifies the origin of the external demand.
+- **References Listing**: normalized order lines use listing mappings to resolve internal items.
+- **References BusinessPartner (cross-module)**: customer resolution may map buyer identity to a business partner.
+- **References SalesOrder**: `salesOrderId` is recorded once conversion succeeds.
+- **Belongs To SyncJob**: ingestion and replay attempts are associated with a sync execution record.

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

@@ -0,0 +1,39 @@
+# ChannelOrderLine
+
+## Description
+
+ChannelOrderLine stores the normalized line-level payload under a `ChannelOrder`. It preserves the external line identity, resolved listing or item mappings, quantity, price context, and normalized troubleshooting payload needed before conversion to internal sales-order lines.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [recordChannelOrder](../commands/RecordChannelOrder.md) - Create or refresh normalized line payload under the parent channel order.
+- [convertChannelOrder](../commands/ConvertChannelOrder.md) - Consume mapped channel-order lines when materializing the internal sales order.
+
+### Query Definitions
+
+- [getChannelOrder](../queries/GetChannelOrder.md) - Return one normalized channel order with its linked conversion context.
+- [listChannelOrdersByStatus](../queries/ListChannelOrdersByStatus.md) - Return operational queues where line-level mapping context may need review.
+
+### Models
+
+- ChannelOrderLine
+
+### Invariants
+
+- Every channel-order line belongs to exactly one `ChannelOrder`.
+- Quantity must remain greater than zero for a normalized commercial line.
+- Listing, item, currency, and unit mappings are optional during ingestion but must be resolvable before successful conversion.
+- Normalized line payload must preserve sufficient source detail for support and replay workflows.
+
+### Relationships
+
+- **Belongs To ChannelOrder**: `channelOrderId` ties the line to its parent inbound order.
+- **References Listing**: `listingId` stores the resolved marketplace or storefront listing when available.
+- **References Item (cross-module)**: `itemId` stores the resolved internal sellable item when mapping succeeds.
+- **References primitives**: `currencyId` and `uomId` preserve the normalized commercial measurement context.

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

@@ -0,0 +1,56 @@
+# Listing
+
+## Description
+
+Listing is the channel-specific sellability record for one internal item on one channel. It preserves external identifiers, publication state, optional operational metadata, and the mapping bridge required to normalize inbound channel orders back to the internal item model.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createListing
+    Draft --> Active: activateListing
+    Active --> Paused: pauseListing
+    Paused --> Active: activateListing
+    Draft --> Retired: retireListing
+    Active --> Retired: retireListing
+    Paused --> Retired: retireListing
+```
+
+### Command Definitions
+
+- [createListing](../commands/CreateListing.md) - Create a draft listing for one active item on one channel.
+- [updateListing](../commands/UpdateListing.md) - Revise identifiers, assortment metadata, or publication prerequisites.
+- [activateListing](../commands/ActivateListing.md) - Make the listing externally sellable when all required prerequisites are present.
+- [pauseListing](../commands/PauseListing.md) - Temporarily stop new sellability without losing identifiers or history.
+- [retireListing](../commands/RetireListing.md) - Permanently remove the listing from active sellability while preserving references.
+
+### Query Definitions
+
+- [getListing](../queries/GetListing.md) - Retrieve one listing with item, channel, and identifier context.
+- [listListingsByChannel](../queries/ListListingsByChannel.md) - List channel assortment records under one channel.
+- [getListingByExternalIdentifier](../queries/GetListingByExternalIdentifier.md) - Resolve the internal listing from a channel-provided external identifier.
+
+### Models
+
+- Listing
+
+### Invariants
+
+- Every listing belongs to exactly one company, one channel, and one sellable item.
+- A listing cannot be ACTIVE unless the referenced item and channel are both ACTIVE and all required external identifiers are present.
+- Historical channel orders remain able to reference a retired listing for audit and support traceability.
+- External identifiers must be unique within the channel context according to operational policy.
+
+### Relationships
+
+- **References Channel**: `channelId` defines the external commercial context.
+- **References Item (cross-module)**: `itemId` links the listing to the internal sellable SKU.
+- **Optionally References SalesPriceRule**: Activation may require a price-linkage or pricing-eligibility check.
+- **Referenced By ChannelOrder**: Inbound channel orders use the listing mapping to normalize external identifiers.

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

@@ -0,0 +1,47 @@
+# SalesCreditNote
+
+## Description
+
+SalesCreditNote is the commercial correction document issued after an invoice already exists. It reduces billed quantity or amount for allowances, disputes, or price corrections while preserving the original invoice as immutable evidence.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createSalesCreditNote
+    Draft --> Issued: issueSalesCreditNote
+```
+
+### Command Definitions
+
+- [createSalesCreditNote](../commands/CreateSalesCreditNote.md) - Create a draft credit note referencing an issued invoice and one or more affected invoice lines.
+- [updateSalesCreditNote](../commands/UpdateSalesCreditNote.md) - Correct draft credit-note amounts, reasons, or references before issue.
+- [issueSalesCreditNote](../commands/IssueSalesCreditNote.md) - Validate the commercial correction and issue the immutable credit note.
+
+### Query Definitions
+
+- [getSalesCreditNote](../queries/GetSalesCreditNote.md) - Retrieve one credit note with correction metadata and affected lines.
+- [listSalesCreditNotesByInvoice](../queries/ListSalesCreditNotesByInvoice.md) - List all credit corrections issued against one invoice.
+
+### Models
+
+- SalesCreditNote
+- SalesCreditNoteLine
+
+### Invariants
+
+- Every credit note belongs to exactly one company and references one issued sales invoice.
+- A credit note must preserve correction reason, tax basis, customer identity, and linked invoice identity at issue time.
+- The cumulative credited quantity or amount against any invoice line cannot exceed the original issued quantity or amount without a documented override policy.
+
+### Relationships
+
+- **Owns SalesCreditNoteLine**: Line-level corrections specify the quantities or amounts being reduced.
+- **References SalesInvoice**: `salesInvoiceId` identifies the invoice being corrected.
+- **References SalesOrder**: Credit notes preserve the originating commercial context through the linked invoice lines.

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

@@ -0,0 +1,37 @@
+# SalesCreditNoteLine
+
+## Description
+
+SalesCreditNoteLine stores the specific invoice-line quantity or amount being corrected on a credit note. It preserves correction reason, tax basis, and original billing reference so downstream posting remains deterministic.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createSalesCreditNote](../commands/CreateSalesCreditNote.md) - Create initial credit-note lines against issued invoice lines.
+- [updateSalesCreditNote](../commands/UpdateSalesCreditNote.md) - Revise draft correction quantities or amounts before issue.
+- [issueSalesCreditNote](../commands/IssueSalesCreditNote.md) - Freeze the final correction baseline at issue time.
+
+### Query Definitions
+
+- [getSalesCreditNote](../queries/GetSalesCreditNote.md) - Return line-level correction details for one credit note.
+- [listSalesCreditNotesByInvoice](../queries/ListSalesCreditNotesByInvoice.md) - Expose the correction history attached to one invoice.
+
+### Models
+
+- SalesCreditNoteLine
+
+### Invariants
+
+- Every credit-note line belongs to exactly one credit note and references one issued invoice line.
+- Credited quantity or amount must be greater than zero.
+- The line preserves the original invoice-line identity and correction reason so later downstream posting does not depend on mutable upstream data.
+
+### Relationships
+
+- **Belongs To SalesCreditNote**: `salesCreditNoteId` ties the line to its parent correction document.
+- **References SalesInvoiceLine**: `salesInvoiceLineId` identifies the billed evidence being corrected.

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

@@ -0,0 +1,55 @@
+# SalesInvoice
+
+## Description
+
+SalesInvoice is the customer-facing receivable document issued from the sales domain. It snapshots invoice identity, billing policy outcome, price and tax context, payment-term output, and customer references so downstream accounts receivable can consume a stable commercial document.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createSalesInvoice
+    Draft --> Issued: issueSalesInvoice
+    Issued --> Sent: sendSalesInvoice
+    Draft --> Cancelled: cancelSalesInvoice
+    Issued --> Cancelled: cancelSalesInvoice
+```
+
+### Command Definitions
+
+- [createSalesInvoice](../commands/CreateSalesInvoice.md) - Create a draft invoice with references to the customer, order, and invoice lines.
+- [updateSalesInvoice](../commands/UpdateSalesInvoice.md) - Correct mutable invoice fields while the document remains draft.
+- [issueSalesInvoice](../commands/IssueSalesInvoice.md) - Validate billing policy, snapshot receivable metadata, and issue the invoice.
+- [sendSalesInvoice](../commands/SendSalesInvoice.md) - Record customer-facing delivery metadata after issuance.
+- [cancelSalesInvoice](../commands/CancelSalesInvoice.md) - Cancel a draft or issued invoice before downstream AR handoff acceptance.
+
+### Query Definitions
+
+- [getSalesInvoice](../queries/GetSalesInvoice.md) - Retrieve one invoice with lines, due schedule, and status metadata.
+- [listSalesInvoicesBySalesOrder](../queries/ListSalesInvoicesBySalesOrder.md) - List all invoices issued against one sales order.
+
+### Models
+
+- SalesInvoice
+- SalesInvoiceLine
+
+### Invariants
+
+- Every invoice belongs to exactly one company and one customer.
+- An issued invoice preserves external invoice number, invoice date, payment-term snapshot, customer tax identity, taxable amount, and tax amount.
+- Invoice quantities and prices must validate against the originating sales order and, when required, posted shipment evidence.
+- A cancelled invoice preserves historical references and may not delete or silently rewrite issued billing evidence.
+
+### Relationships
+
+- **Owns SalesInvoiceLine**: Invoice lines hold the detailed billed quantities and prices.
+- **References SalesOrder**: `salesOrderId` links the invoice to the commercial commitment being billed.
+- **References Shipment**: Shipment-gated billing may cite posted shipment evidence.
+- **References SalesPaymentTerm**: The invoice snapshots the assigned term and derived due schedule.
+- **Referenced By SalesCreditNote**: Credit notes correct previously issued invoice evidence without mutating the original invoice.

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

@@ -0,0 +1,39 @@
+# SalesInvoiceLine
+
+## Description
+
+SalesInvoiceLine stores the specific billed quantity, price, tax basis, and order reference included on one invoice line. It is the unit against which cumulative invoicing and later credit-note corrections are validated.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createSalesInvoice](../commands/CreateSalesInvoice.md) - Create draft invoice lines from selected sales-order lines.
+- [updateSalesInvoice](../commands/UpdateSalesInvoice.md) - Correct draft invoice quantities or references before issue.
+- [issueSalesInvoice](../commands/IssueSalesInvoice.md) - Freeze billed quantity, price, and tax basis at issue time.
+
+### Query Definitions
+
+- [getSalesInvoice](../queries/GetSalesInvoice.md) - Return line-level billed quantities and references for one invoice.
+- [listSalesInvoicesBySalesOrder](../queries/ListSalesInvoicesBySalesOrder.md) - Summarize billed line history for a selected order.
+
+### Models
+
+- SalesInvoiceLine
+
+### Invariants
+
+- Every invoice line belongs to exactly one sales invoice and references exactly one sales-order line.
+- Invoice quantity must be greater than zero and cannot exceed the allowed order-based or shipment-based billing quantity without an explicit override policy.
+- Issued invoice lines preserve the order price snapshot rather than re-resolving live price rules.
+
+### Relationships
+
+- **Belongs To SalesInvoice**: `salesInvoiceId` ties the line to its parent invoice.
+- **References SalesOrderLine**: `salesOrderLineId` validates billed quantity and price against the originating order line.
+- **Optionally References ShipmentLine**: Shipment-gated billing may store shipment evidence at line level.
+- **Referenced By SalesCreditNoteLine**: Credit notes point back to issued invoice lines they correct.