# README

## Overview

The Sales module manages the outbound commercial lifecycle from customer-facing pricing and payment terms through order capture, shipment coordination, customer invoicing or credit correction, and multi-channel sales synchronization. It owns the transactional records that express what was sold to which customer, at what price, under which payment expectations, through which channel, from which fulfillment context, whether the commitment is confirmed or on commercial hold, and how much of that commitment has been shipped, invoiced, or commercially credited.

Sales sits between master-data modules and downstream execution or finance modules. It references customers from business-partner, sellable items from item-management, commercial product context from product-management, organizational scope from organization, and currencies or UoMs from primitives. It coordinates with inventory for reservation and outbound stock execution, while keeping customer-facing order, shipment, and billing rules inside the sales domain. Role-based access control and immutable operational traceability are treated as first-class requirements through user-management and audit integrations.

## Key Features

- **[Sales Order Lifecycle](docs/features/sales-order-lifecycle.md)**: Create and manage `SalesOrder` documents with line items, customer references, pricing and payment snapshots, lifecycle control including credit hold, and fulfillment or billing progress tracking from draft through closure
- **[Customer Sales Pricing](docs/features/customer-sales-pricing.md)**: Maintain customer- or channel-facing `SalesPriceList` and `SalesPriceRule` records with date validity, quantity breaks, currency support, and deterministic defaulting onto sales order lines
- **[Sales Payment Terms](docs/features/sales-payment-terms.md)**: Define customer-facing payment schedules, installment structures, and discount terms that flow from ordering into invoice due-date calculation
- **[Shipment Fulfillment](docs/features/shipment-fulfillment.md)**: Record `Shipment` documents against sales order lines, support partial shipments and backorders, and provide the outbound fulfillment basis for inventory execution and customer status updates
- **[Customer Invoicing](docs/features/customer-invoicing.md)**: Capture `SalesInvoice` and `SalesCreditNote` documents from orders and shipment evidence, validate billing or correction quantities against policy, and hand issued receivable documents to downstream accounts-receivable processing
- **[Channel Listing Management](docs/features/channel-listing-management.md)**: Manage `Channel` and `Listing` records that control which items are sellable on each external sales channel, with channel-specific identifiers, publication status, and assortment controls
- **[Channel Order Sync](docs/features/channel-order-sync.md)**: Ingest `ChannelOrder` records from external channels, track explicit channel-order lifecycle states and import or export attempts through `SyncJob`, and normalize channel-originated demand into internal sales workflow

## Module Scope

### In Scope

- Sales order creation, revision, submission, confirmation, commercial hold or release, cancellation, closure, and fulfillment or billing progress tracking
- Sales order lines with item, quantity, unit of measure, customer price, currency, requested ship date, and shipment or invoice progress
- Customer- and channel-facing pricing via `SalesPriceList` and `SalesPriceRule`, including effective dates, quantity breaks, and rule selection precedence
- Customer-facing payment term definitions via `SalesPaymentTerm`, including net-day, end-of-month, installment, and discount-based schedules
- Shipment recording via `Shipment`, including partial shipment, backorder visibility, shipment address snapshots, and outbound handoff contracts to inventory
- Customer invoice capture and commercial credit correction via `SalesInvoice` and `SalesCreditNote`, including invoice numbering, tax and pricing snapshots, shipment-aware billing policy checks, pre-AR cancellation controls, and post-issue commercial correction without requiring a physical return
- Multi-channel sellability management through `Channel` and `Listing`, including listing status, channel identifiers, and company-scoped assortment control
- Channel-originated order ingestion through `ChannelOrder` with explicit lifecycle states such as pending conversion, converted, exception, and channel cancellation, plus retryable synchronization jobs through `SyncJob`
- Company-scoped sales documents with customer references restricted to ACTIVE partners carrying the CUSTOMER role

### Out of Scope

- CRM lead management, opportunity pipelines, quotations, and sales forecasting (future CRM or application-layer workflows)
- Promotion engines, coupon logic, loyalty programs, rebates, commissions, and incentive compensation (future pricing or sales-ops capability)
- Payment gateway authorization, card capture, wallet settlement, chargebacks, and cash application (future payment or accounts-receivable module)
- Tax determination engines, statutory e-invoicing transport, journal entry posting, revenue recognition, and receivable settlement (future accounting or AR modules)
- Warehouse execution details such as pick waves, packing steps, cartonization, bin-level allocation, and carrier label generation (inventory or future warehouse-operations module)
- Customer returns, refunds, RMAs, and reverse-logistics workflows that require physical goods movement (future returns or customer-service capability)
- Subscription billing, usage-based pricing, recurring invoices, and contract renewals (future subscription module)
- Marketplace advertising, merchandising analytics, and channel marketing optimization (future commerce operations capability)
- Public storefront UX, checkout orchestration, and channel-specific web application behavior (application layer)

### Scope Decision Rationale

Sales is scoped to the **customer-facing order-to-cash document flow up to invoice issuance**: commercial price, payment expectation, customer order, outbound shipment, customer invoice, and channel-originated order capture. Those records change together and rely on the same customer and fulfillment commitments, so they belong in one module rather than being split prematurely across pricing, commerce, and billing domains.

Inventory is intentionally kept as the owner of **physical stock state and warehouse execution**. Sales records what the company promised to ship, what was commercially confirmed, and what quantity was shipped against the customer commitment. Inventory owns reservation ledgers, on-hand changes, lot or serial state, storage locations, and stock-movement execution. This keeps sales focused on customer commitments rather than warehouse internals.

Financial settlement is also kept out of scope. Sales may determine that an invoice or credit note is commercially valid and ready for downstream processing, but journal posting, tax accounting, receivable aging, collection, and payment application belong to future accounting or accounts-receivable modules. The contract is deliberate: sales issues the commercial receivable document; downstream finance recognizes and settles it.

Commercial correction stays inside sales even when physical returns do not. A pure price correction, quantity dispute, or post-issue allowance may require a `SalesCreditNote` even though no warehouse return occurs. That document belongs with the rest of the sales-side order and invoice evidence. Physical reverse logistics, refund settlement, and inventory putaway remain out of scope for a future returns capability.

Customer pricing and payment terms are included here because they directly drive order entry and invoice behavior. Although a future cross-domain pricing capability could centralize broader commercial rules, the initial customer-facing price lists, channel-specific price selection, and receivable due-date terms are tightly coupled to sales order capture and must exist for the module to be operational.

Channel listing management and channel order sync are included because multi-channel selling changes the same commercial records that the sales team owns. A listing affects whether and how an item may be sold on a specific channel, while a synced marketplace order must normalize into the same `SalesOrder` lifecycle as manually entered demand. Keeping those contracts in the sales module avoids splitting one order pipeline across disconnected modules.

## Module Dependencies

- [business-partner](../business-partner/README.md) — Customer reference, contact, address, buyer-to-customer resolution for channel-originated orders, role classification, and tax-identification data; only ACTIVE partners with the CUSTOMER role can be used in sales transactions, and sales snapshots the chosen shipping or billing address plus tax identifiers onto orders and invoices
- [item-management](../item-management/README.md) — Item or SKU references on sales order, shipment, invoice, and listing records
- [product-management](../product-management/README.md) — Commercial product context and optional catalog metadata used when preparing channel listings
- [organization](../organization/README.md) — Company scoping and fulfillment or billing site context for sales documents
- [primitives](../primitives/README.md) — Currency and unit-of-measure references for pricing, quantities, and payment term calculations
- [inventory](../inventory/README.md) — Downstream reservation, outbound stock execution, and lot or serial evidence for shippable lines
- [user-management](../user-management/README.md) — Sales, fulfillment, billing, and integration permissions for submit, confirm, ship, invoice, publish, sync, cancel, and close actions
- [audit](../audit/README.md) — Immutable audit trail for order, shipment, invoice, listing, and sync-job state transitions
- [coa-management](../coa-management/README.md) — Future integration target for receivable, revenue, tax, discount, and variance account references once accounting posting is introduced
