@tailor-platform/erp-kit 0.4.1 → 0.5.0

package/src/modules/sales/docs/commands/usr/bin/ri.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/commands/usr/bin/rs.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/commands/usr/bin/trustcachectl.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/commands/usr/sbin/htpasswd.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/commands/usr/sbin/lpadmin.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/commands/usr/sbin/setkey.md

@@ -0,0 +1,52 @@
+# filename == heading
+
+<!-- This section should contain the following subsections in order: -->
+<!-- 1. ## Overview (required) -->
+<!-- 2. ## Business Rules (required) -->
+<!-- 3. ## Process Flow (required) -->
+<!-- 4. ## External Dependencies (required) -->
+<!-- 5. ## Error Scenarios (required) -->
+<!-- 6. ## Test Cases (required) -->
+
+## Overview
+
+## Business Rules
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Process Flow
+
+<!-- Code block requirements: -->
+<!-- Minimum 1 mermaid code blocks required -->
+
+```mermaid
+// TODO: Add your code here
+```
+
+## External Dependencies
+
+<!-- e.g. `- [inventory::adjustStock](../../inventory/commands/adjustStock.md) - Adjust stock quantity` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Error Scenarios
+
+<!-- Use UPPER_SNAKE_CASE error codes to identify each scenario.
+e.g. `- **ITEM_NOT_FOUND**: Specified item ID does not exist` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 items per list -->
+
+## Test Cases
+
+<!-- List test case descriptions that correspond to it() blocks in the test file.
+e.g. `- returns error when code is empty` -->
+
+<!-- List requirements: -->
+<!-- Minimum 1 unordered lists required -->
+<!-- Minimum 1 items per list -->
+
+- TODO: Add list item
+

package/src/modules/sales/docs/features/channel-listing-management.md

@@ -0,0 +1,68 @@
+# Channel Listing Management
+
+## Overview
+
+Channel Listing Management controls where and how the company offers items on external sales channels. A `Channel` defines a sell-side integration context such as a marketplace, storefront, or distributor feed, while a `Listing` defines the item's channel-specific sellability, publication state, external identifiers, and optional commercial metadata required for that channel. Together they express whether a given item may be sold on a given channel under a governed assortment policy.
+
+This feature is intentionally distinct from core product definition and from order synchronization. Product-management owns the channel-agnostic product identity; item-management owns the SKU-level sellable unit; sales owns the channel-specific commercial representation that decides whether an item is exposed externally and under which identifiers or operational constraints. Actual API synchronization is tracked by `SyncJob` in the separate channel-order sync workflow.
+
+## Business Purpose
+
+- Control which items are sellable on each external channel without changing the core product definition
+- Preserve channel-specific identifiers, statuses, and assortment rules required for marketplace or storefront operations
+- Prevent inactive items or inactive channels from remaining externally sellable
+- Support different commercial presentation or operational settings per channel while keeping the internal item canonical
+- Provide the lookup bridge needed for channel-originated orders to map back to internal sales items
+- Maintain an auditable listing history for publish, pause, re-list, and retire decisions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Channel] --> B[Configure company, type, and status]
+    B --> C[Create Listing for item]
+    C --> D[Assign channel identifiers and publication settings]
+    D --> E{Ready to publish?}
+    E -->|No| F[Keep listing in draft or paused state]
+    E -->|Yes| G[Activate listing]
+    G --> H[Listing becomes eligible for external sync]
+    H --> I[Channel order sync can map inbound orders by listing]
+    G --> J{Deactivate item or channel?}
+    J -->|Yes| K[Listing becomes unsellable]
+```
+
+## Scenario Patterns
+
+- **Marketplace assortment setup**: A merchandising user creates a channel for a marketplace and lists selected items with marketplace-specific identifiers
+- **Direct storefront catalog**: A B2C storefront channel lists a subset of the internal assortment while the B2B direct-sales channel lists a different subset
+- **Channel-specific pause**: An item remains sellable directly but its marketplace listing is paused because margin or service-level conditions changed
+- **Inactive item protection**: An item is set inactive internally, and all active listings tied to that item become non-sellable for new channel exposure
+- **External identifier mapping**: A listing stores the external SKU or listing ID required for inbound order normalization and outbound status sync
+- **Fulfillment-policy distinction**: One channel requires only shippable items from a specific company or site, and listings record the operational rule without moving warehouse logic into the listing itself
+- **Re-list after correction**: A listing is paused because required content or price configuration is missing, then reactivated once the issue is fixed
+- **Catalog split by company**: Two companies sell the same item family on different channels, and listing ownership stays isolated per company
+- **Future content extension**: Channel-specific titles, descriptions, or images may later extend the listing without forcing those fields into the core product model
+
+## Test Cases
+
+- Creating a channel with valid company and channel type should succeed
+- Creating a listing must require a valid ACTIVE item and an ACTIVE channel
+- A listing must not be activated unless required internal and external identifiers are present
+- Duplicate external listing identifiers on the same channel should be rejected
+- Inactive channels must not accept newly activated listings
+- Inactive items must not remain actively sellable through newly activated listings
+- A listing should be isolated by company and must not point to a channel owned by another company
+- Deactivating a channel should prevent its listings from being used for new channel order intake
+- A listing may be paused and resumed without losing its historical identifiers and audit trail
+- A listing should preserve the internal item reference needed for channel-order mapping
+- If listing publication depends on channel-specific price configuration, missing required price linkage should block activation
+- Only authorized sales or commerce users should be able to create, activate, pause, or retire channels and listings
+- Listing changes must remain auditable, including publish, pause, identifier change, and retirement actions
+- A listing used by historical channel orders must remain referenceable even after it is no longer actively sellable
+- Channel and listing names should be unique according to company policy where operational ambiguity would otherwise occur
+
+## Reference Links
+
+- [Shopify product and publication concepts](https://shopify.dev/docs/apps/build/online-store/product-publishing)
+- [Amazon marketplace listing concepts](https://developer-docs.amazon.com/sp-api/)
+- [Odoo website and marketplace connector concepts](https://www.odoo.com/documentation/19.0)

package/src/modules/sales/docs/features/channel-order-sync.md

@@ -0,0 +1,78 @@
+# Channel Order Sync
+
+## Overview
+
+Channel Order Sync ingests externally sourced demand into the internal sales workflow and tracks synchronization attempts with explicit operational records. A `ChannelOrder` stores the normalized representation of an order received from a marketplace, storefront, or distributor integration, while `SyncJob` records each import or export attempt, including status, timing, counts, and error context. `ChannelOrder` itself carries an operational lifecycle so users can distinguish demand that is waiting for conversion, already converted, blocked by an exception, or cancelled at the originating channel. This allows the business to treat channel-originated orders as first-class sales demand without losing traceability to the source payload and integration outcome.
+
+The feature is intentionally scoped to reliable ingestion, normalization, deduplication, and operational retry handling. It does not embed storefront UX, checkout orchestration, or arbitrary channel API behavior in the order model. The main contract is that a successful sync should be able to create or update a `ChannelOrder`, map it to internal customers and listings, and then materialize or update a `SalesOrder` without bypassing the normal sales rules. The minimum `ChannelOrder` lifecycle is `PENDING_CONVERSION` → `CONVERTED`, with `EXCEPTION` for failed normalization or mapping and `CANCELLED_BY_CHANNEL` when the originating platform cancels the order before internal execution is complete.
+
+## Business Purpose
+
+- Automate order capture from external sales channels without manual re-entry
+- Preserve source-channel traceability with normalized channel-order records and raw payload references
+- Make synchronization reliable through explicit job records, retry semantics, and error visibility
+- Prevent duplicate order creation when the same channel event arrives more than once
+- Give operations teams explicit `ChannelOrder` states for pending conversion, converted demand, exception handling, and channel-originated cancellation queries
+- Separate integration failure handling from internal sales-order lifecycle management
+- Provide a governed path for pushing selected downstream status updates back to the originating channel
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Start SyncJob] --> B[Fetch or receive channel payloads]
+    B --> C[Deduplicate by channel and external order identity]
+    C --> D[Create or update ChannelOrder as PENDING_CONVERSION]
+    D --> E[Resolve listing, customer, currency, and item mappings]
+    E --> F{Mappings valid?}
+    F -->|No| G[Move ChannelOrder to EXCEPTION and retain retry context]
+    F -->|Yes| H[Create or update SalesOrder]
+    H --> I[Move ChannelOrder to CONVERTED]
+    I --> J[Record sync result on SyncJob]
+    J --> K{Need outbound status sync later?}
+    K -->|Yes| L[Queue later SyncJob for shipment or invoice status push]
+    K -->|No| M[Complete SyncJob]
+    G --> N[Retry after correction or transient recovery]
+    D --> O{Cancellation received from channel?}
+    O -->|Yes| P[Move ChannelOrder to CANCELLED_BY_CHANNEL]
+```
+
+## Scenario Patterns
+
+- **Marketplace order import**: A marketplace sends a new order payload, which is normalized into `ChannelOrder` and converted into an internal sales order
+- **Duplicate webhook delivery**: The same order event arrives twice, and the second attempt is treated idempotently without creating a duplicate sales order
+- **Missing listing mapping**: A channel order references an unknown external listing identifier, so the job records an exception and waits for mapping correction
+- **Transient channel failure**: A sync job fails because the external API times out; the job remains retryable with the original context preserved
+- **Customer resolution fallback**: A channel order includes buyer identity that maps to an existing customer when possible and otherwise triggers a controlled customer-resolution step
+- **Pending conversion queue**: A large batch import lands successfully, but several valid channel orders remain in `PENDING_CONVERSION` until the internal conversion worker is scheduled
+- **Status push after shipment**: A later sync job publishes shipped status or tracking information back to the originating channel once the internal shipment posts
+- **Cancellation update from channel**: A channel-originated cancellation request is received before fulfillment starts, the `ChannelOrder` moves to `CANCELLED_BY_CHANNEL`, and the internal sales order is updated through controlled sales cancellation rules when one already exists
+- **Partial import batch**: A nightly sync imports ten orders successfully while two fail validation, and the job preserves both success and failure counts
+- **Manual replay after fix**: Operations correct the missing listing or customer mapping and replay the failed sync without reprocessing the whole batch blindly
+
+## Test Cases
+
+- Starting a sync job should create a `SyncJob` record with channel, direction, start time, and status
+- A channel order must be unique by company, channel, and external order identity
+- A newly ingested channel order must enter `PENDING_CONVERSION` before any internal sales-order materialization occurs
+- Receiving the same channel order event more than once should be idempotent and must not create duplicate internal sales orders
+- A sync job must preserve raw payload reference or normalized source data sufficient for troubleshooting
+- If a required listing mapping is missing, the sync should fail that record, move the `ChannelOrder` to `EXCEPTION`, and avoid creating a partial internal sales order
+- If required customer, currency, or item resolution fails, the sync should keep actionable error context for retry and preserve the `EXCEPTION` state until replay succeeds
+- A successful sync must create or update a `ChannelOrder` before creating or updating the internal `SalesOrder`
+- Successful conversion must move the `ChannelOrder` to `CONVERTED` and store the linked internal `SalesOrder` reference
+- Sync retries after transient failure should reuse the original channel order identity rather than create a new one
+- Sync results must be isolated by company and must not create sales records in another company
+- A sync job should record processed, succeeded, failed, and retried counts when applicable
+- A channel cancellation event received before fulfillment starts must move the `ChannelOrder` to `CANCELLED_BY_CHANNEL`, and replaying stale conversion jobs afterward must be prevented by policy
+- Outbound shipment or invoice status push should be limited to channel orders that preserve a valid originating channel reference
+- A cancelled or inactive channel must not accept new sync jobs unless explicitly allowed for recovery or replay
+- Only authorized integration or commerce users should be able to start, retry, cancel, or replay sync jobs
+- Historical channel orders and sync jobs must remain queryable for audit and support even after the linked listing is retired
+- A sync job should finish in a terminal status that distinguishes success, partial success, failure, and cancellation, independently of the `ChannelOrder` operational state
+
+## Reference Links
+
+- [Shopify order sync concepts](https://shopify.dev/docs/apps/build/orders-fulfillment/order-management-apps)
+- [Amazon SP-API orders concepts](https://developer-docs.amazon.com/sp-api/)
+- [Oracle omnichannel order capture documentation](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/index.html)

package/src/modules/sales/docs/features/customer-invoicing.md

@@ -0,0 +1,89 @@
+# Customer Invoicing
+
+## Overview
+
+Customer Invoicing captures customer receivable documents as `SalesInvoice` and `SalesCreditNote` records and validates them against the commercial and fulfillment evidence already recorded in sales. Each invoice line references one or more sales order lines and, when shipment-gated billing is required, the posted shipments that prove quantity has actually been fulfilled. Each credit-note line references the issued invoice line being corrected, the affected sales order context, and the correction reason or amount so the commercial dispute can be resolved without mutating the historical invoice.
+
+This feature does not post journal entries, apply cash, or execute collection. Its responsibility is to issue customer invoices that reflect what was sold and, where policy requires, what was shipped; preserve pricing, tax, and invoice identity required for legal and commercial validity; and maintain a clean handoff contract for future accounts-receivable and accounting modules. The minimum document lifecycles are `DRAFT` → `ISSUED` → `SENT` for `SalesInvoice`, with `CANCELLED` available only before downstream AR handoff acceptance, and `DRAFT` → `ISSUED` for `SalesCreditNote`, which references an already issued invoice when cancellation is no longer the correct commercial action.
+
+## Business Purpose
+
+- Create customer-facing invoices from sales orders without bypassing the underlying commercial commitment
+- Prevent over-invoicing by ensuring invoice quantities align with order quantities and billing policy
+- Support both order-based billing and shipment-gated billing depending on item or company policy
+- Carry invoice identity, payment-term snapshot, and due-date schedule into downstream receivable processing
+- Snapshot pricing and tax-relevant commercial data so later master-data edits do not alter issued invoices
+- Allow draft or issued invoices to be cancelled while they are still owned by sales and have not yet been accepted by downstream AR
+- Support post-issue commercial correction through `SalesCreditNote` when an invoice must be reduced for price disputes, quantity disputes, or allowances without deleting the original invoice evidence
+- Preserve an auditable link between invoice lines, sales orders, and shipments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Sales Invoice] --> B[Enter invoice date, customer reference, and lines]
+    B --> C[Match invoice lines to sales order lines]
+    C --> D{Billing policy?}
+    D -->|Order-based| E[Compare invoice to ordered qty and price]
+    D -->|Shipment-gated| F[Compare invoice to ordered qty, price, and posted shipments]
+    E --> G{Valid?}
+    F --> G
+    G -->|No| H[Keep DRAFT for correction]
+    G -->|Yes| I[ISSUE INVOICE]
+    I --> J[Calculate due schedule from payment term]
+    J --> K[Send invoice to customer]
+    K --> L[SENT]
+    L --> M{Cancel before AR handoff?}
+    M -->|Yes| N[CANCELLED]
+    M -->|No| O[Ready for downstream AR or accounting handoff]
+    L --> P{Commercial correction needed after issue?}
+    P -->|Yes| Q[Create SalesCreditNote against issued invoice lines]
+    Q --> R[Validate credited qty or amount against original invoice evidence]
+    R --> S[ISSUE CREDIT NOTE]
+    S --> O
+```
+
+## Scenario Patterns
+
+- **Post-shipment invoice**: The customer invoice is issued after the shipment posts, and invoiced quantities match the fulfilled quantities exactly
+- **Order-based service invoice**: A service order is invoiced directly from the confirmed sales order because no physical shipment evidence is required
+- **Partial invoice**: Only the first shipment of a larger order is invoiced now; the billed quantity is recorded and the order remains open for later invoices
+- **Advance invoice by policy**: A project or make-to-order deal issues an invoice before shipment because the assigned billing policy allows order-based invoicing
+- **Manual correction before issue**: A billing user notices the wrong customer reference while the invoice is still draft and fixes it before the invoice is issued
+- **Pre-AR cancellation**: An issued invoice is discovered to contain the wrong external reference before AR accepts it, so sales cancels the invoice and preserves the original evidence
+- **Post-issue price correction**: An invoice was issued with an overstated unit price, so billing issues a `SalesCreditNote` for the difference instead of cancelling the historical invoice
+- **Quantity dispute allowance**: The customer accepts eight units from a ten-unit invoice and disputes the remainder, so sales issues a partial credit note tied to the original invoice lines
+- **Payment-term inheritance**: The invoice inherits the order's negotiated payment term so downstream AR sees the correct due dates and discount windows
+- **Tax snapshot capture**: The invoice snapshots customer tax identification, tax code, taxable amount, and tax amount so legal invoice validation survives later customer-master edits
+- **Channel-originated billing**: A marketplace order becomes an internal sales order and later a customer invoice, while retaining channel reference for reconciliation and dispute handling
+
+## Test Cases
+
+- Creating a sales invoice with a valid customer, company, and at least one invoice line should succeed
+- A sales invoice line must reference a valid sales order line and an invoice quantity greater than zero
+- Duplicate external invoice numbers for the same company should be rejected
+- An order-based invoice must compare invoice quantity and price to the referenced sales order line
+- A shipment-gated invoice must not allow an invoiced quantity greater than the cumulative posted shipment quantity unless policy explicitly allows pre-shipment billing
+- A sales invoice line price must come from the sales order snapshot rather than from a newly resolved price rule
+- An invoice created from a cancelled sales order should fail
+- An issued invoice must snapshot the invoice date, external invoice number, ordered price reference, assigned payment term, customer tax identifier, tax code, taxable amount, and tax amount
+- Partial invoicing must increase the sales order line invoiced quantity without forcing the order closed
+- A sales invoice must not be considered ready for downstream AR until all required billing-policy checks pass
+- An issued invoice may transition to `SENT` only after customer-facing delivery metadata required by company policy is captured
+- A draft or issued invoice may transition to `CANCELLED` only while no downstream AR or accounting module has accepted the receivable handoff
+- Cancelling an invoice must preserve the original line references and issue evidence for future credit-note or dispute workflows
+- Creating a `SalesCreditNote` must require reference to an issued `SalesInvoice` and at least one affected invoice line or correction amount
+- The cumulative credited quantity or amount for an invoice line must not exceed the original issued quantity or amount unless a documented override policy exists
+- A `SalesCreditNote` must snapshot correction reason, customer, currency, tax basis, and linked invoice identity so downstream AR can post the reversal deterministically
+- Issuing a credit note must not mutate or delete the original invoice; it must preserve a linked audit trail between the invoice, credited lines, and downstream handoff contract
+- Invoices must be isolated by company and must not reference sales orders from another company
+- Shipment-gated validation must preserve whether the invoice was issued from order-based or shipment-based billing policy
+- Only authorized sales or billing users should be able to create, issue, send, cancel, or release customer invoices and credit notes
+- An issued invoice should expose the due-date schedule calculated from the assigned sales payment term
+- Editing sales price rules or customer master data after invoice issuance must not change the comparison baseline for an existing invoice
+
+## Reference Links
+
+- [Odoo customer invoices documentation](https://www.odoo.com/documentation/19.0/applications/finance/accounting/customer_invoices.html)
+- [Oracle Receivables documentation](https://docs.oracle.com/en/cloud/saas/financials/index.html)
+- [SAP billing document overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/sales/docs/features/customer-sales-pricing.md

@@ -0,0 +1,72 @@
+# Customer Sales Pricing
+
+## Overview
+
+Customer Sales Pricing manages the customer- and channel-facing commercial rules that default onto sales order lines. A `SalesPriceList` groups reusable pricing conditions for one company, while `SalesPriceRule` defines the actual pricing logic for a given item and selling context, such as customer scope, channel scope, effective date, minimum quantity, currency, and unit of measure. These rules allow the sales organization to keep agreed sell prices in structured form instead of entering them manually on every order.
+
+The feature is intentionally sales-specific rather than a full enterprise pricing engine. It focuses on "what price should this customer or channel receive for this item under these conditions?" and provides deterministic price selection when users or integrations create or revise sales orders. Promotions, coupon redemption, commissions, and settlement-time discount accounting remain explicit non-goals for the initial scope.
+
+## Business Purpose
+
+- Reduce manual entry by defaulting agreed customer or channel prices onto sales order lines
+- Capture quantity breaks, date validity, and currency-specific selling rules
+- Support differentiated pricing by customer, channel, or commercial program without duplicating item master data
+- Preserve commercial history by snapshotting the applied rule onto the sales order at confirmation time
+- Enable invoice validation and downstream analytics by keeping the ordered price independent from later rule edits
+- Separate pricing logic from product definition and from downstream receivable settlement logic
+- Keep sales-UoM pricing compatible with inventory execution by delegating unit conversion to shared primitives
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Sales Price List] --> B[Add Sales Price Rules]
+    B --> C[Set customer or channel scope, dates, quantity breaks]
+    C --> D[Activate list]
+    D --> E[User or integration creates sales order line]
+    E --> F[Resolve applicable rules]
+    F --> G{Rule found?}
+    G -->|Yes| H[Apply best matching rule]
+    G -->|No| I[Manual price entry]
+    H --> J[Snapshot applied price and rule reference on order line]
+    I --> J
+    J --> K[Order confirmed]
+    K --> L[Invoice uses order price snapshot]
+```
+
+## Scenario Patterns
+
+- **Standard price list**: A company maintains a default sell price list for all direct customers and applies it automatically to new orders
+- **Customer contract pricing**: A strategic customer has a negotiated annual unit price for a specific item, and that rule overrides the default list
+- **Channel-specific pricing**: The same item is sold on a marketplace and on a direct B2B channel at different prices, and the correct rule is selected from the originating channel
+- **Quantity break pricing**: A customer receives a lower unit price when ordering more than a configured quantity threshold
+- **Time-bounded commercial window**: A temporary seasonal price applies only within a specific effective date range, after which the regular price resumes
+- **Multi-currency selling**: The same company sells one item in JPY on a domestic channel and USD on an export channel, and rules keep those conditions separate
+- **Manual exception before confirmation**: The system defaults a contracted price, but the sales user overrides it on a draft order while retaining the matched-rule reference for auditability
+- **Rule retirement**: An obsolete price list is deactivated when a new commercial agreement begins, preventing future orders from using stale pricing
+- **Marketplace item mapping**: A listing points to an item that has a channel-specific price rule, allowing channel order sync to create sales orders without custom pricing logic in the integration layer
+
+## Test Cases
+
+- Creating a sales price list for an ACTIVE company should succeed
+- A sales price rule must require a positive unit price and a valid item or defined pricing scope
+- A quantity-break rule must not allow a negative minimum quantity
+- A rule with an effective end date earlier than its start date should fail validation
+- Inactive price lists or inactive rules must not be selected for new sales orders
+- When multiple rules match the same order line, rule resolution must follow deterministic precedence based on company, customer scope, channel scope, item scope, UoM, minimum quantity, date, and explicit priority
+- When no rule matches an order line, the system should allow manual pricing while marking the line as unmatched to a price rule
+- Editing a price rule after a sales order is confirmed must not retroactively change the ordered unit price on that existing order
+- A sales price list must be isolated by company when company-specific commercial policies differ
+- Duplicate rules with indistinguishable precedence for the same item, customer or channel, date, and quantity context should be rejected or warned
+- A sales price rule currency must reference a valid currency from the primitives module
+- If a sales price rule UoM differs from the item's operational UoM, a valid conversion path from `primitives` must exist before the rule can be used operationally
+- Only ACTIVE items should be assignable to newly created sales price rules
+- A user should be able to override a defaulted price on a draft order while retaining audit information about the default rule
+- Customer invoices should consume the sales order's snapshotted price even if the underlying rule is later deactivated
+- Only authorized sales users should be able to create, update, activate, or deactivate sales price lists
+
+## Reference Links
+
+- [Odoo pricelists documentation](https://www.odoo.com/documentation/19.0/applications/sales/sales/products_prices/prices/pricing.html)
+- [Oracle Pricing documentation](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/index.html)
+- [SAP Sales pricing overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)