# README ## Overview The Sales module manages the outbound commercial lifecycle from order capture through fulfillment coordination. It owns the transactional records that express what was sold to which customer, at what price, under which externally supplied payment expectations, whether the commitment is confirmed or on commercial hold, and how much of that commitment has been fulfilled or billed by downstream modules. Sales sits between master-data modules and downstream execution or finance modules. It references customers from business-partner, sellable items from item-management, organizational scope from organization, and currencies or UoMs from primitives. It keeps customer-facing order rules and progress projection inside the sales domain without owning shipment evidence, inventory stock execution, or accounts-receivable document lifecycles. Role-based access control and immutable operational traceability are treated as first-class requirements through user-management integration. ## Key Features - **[Sales Item Adoption](docs/model/SalesItem.md)**: Adopt an item-management item for selling and own the selling defaults its order lines resolve; only adopted items can be sold - **[Sales Order Lifecycle](docs/feature/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 ## Module Scope ### In Scope - Selling records for items (`SalesItem`), holding the selling defaults an order line resolves and, by their existence, which items may be sold at all - Sales order creation, revision, submission, confirmation, commercial hold or release, cancellation, closure, and fulfillment or billing progress tracking - Header-level transaction currency, restricted to the owning company's base currency - Sales order lines with item, quantity, unit of measure, customer price, requested ship date, and downstream fulfillment or billing progress - External payment-term identifiers and snapshots on sales orders when a downstream receivables or finance module supplies payment expectations - Line-level fulfillment progress projections that downstream fulfillment modules can update after they own the shipment evidence - Sales-order billing progress fields that downstream accounts-receivable processing can use to report how much of the commercial commitment has been billed - 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) - Customer invoice and credit-note document lifecycles, tax determination engines, statutory e-invoicing transport, journal entry posting, revenue recognition, and receivable settlement (accounts-receivable or financial-accounting modules) - Payment-term master data, due-schedule calculation, installment structures, and early-payment discount policies (accounts-receivable or finance master-data modules) - Shipment evidence documents, shipment-line details, warehouse execution details such as pick waves, packing steps, cartonization, bin-level allocation, and carrier label generation (inventory, fulfillment, or future warehouse-operations modules) - 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) - Price list and price rule master data, quantity breaks, and automatic price defaulting onto order lines; the application supplies the final unit price and may preserve its own evidence in the line price snapshot - Sales channel and listing master data, channel-specific item identifiers, and assortment control (future commerce module) - Channel order ingestion, marketplace order normalization, and external-order lifecycle tracking (future commerce 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 and fulfillment commitment flow**: customer order, agreed price, payment expectation, and fulfillment progress projection. Downstream fulfillment owns shipment evidence, accounts receivable owns customer invoice and credit-note lifecycles, and sales preserves the order baseline plus progress projections needed to understand what remains open. The outbound-shipment and inventory modules are intentionally kept as the owners of **shipment evidence, physical stock state, and warehouse execution**. Sales records what the company promised to ship, what was commercially confirmed, and the resulting fulfilled quantity projection against the customer commitment. Outbound-shipment owns shipment documents and inventory owns reservation ledgers, on-hand changes, lot or serial state, storage locations, and stock-movement facts. This keeps sales focused on customer commitments rather than warehouse internals. Selling defaults for an item are owned here rather than added to the shared item ledger. Whether selling an item is expected to produce an outbound shipment is a sales judgment, and item-management keeps only what every business function agrees on — identity, primary unit, registration status. The alternative, one wide item table, would force every function's columns onto everyone. Financial settlement is also kept out of scope. Customer invoices, credit notes, journal posting, tax accounting, receivable aging, collection, and payment application belong to accounts-receivable or financial-accounting modules. The contract is deliberate: sales owns the commercial order and progress projection; accounts receivable owns receivable documents and settlement. Price determination is kept outside sales. An order line carries the agreed unit price and an optional serialized price snapshot, so an application that runs its own pricing rules can preserve the evidence behind that price without sales owning price-list master data. Payment-term master data is outside sales as well; sales can preserve an externally supplied payment-term identifier and snapshot on the order, but the schedule semantics and due-date calculation belong to receivables or finance master data. Multi-channel selling is also kept outside sales. Channel master data, listings, and marketplace order ingestion serve external storefront integration rather than the internal order commitment, and an integration that captures channel demand can normalize it into `createSalesOrder` like any other source of demand. Sales therefore stays one order pipeline regardless of where the demand originated. ## Module Dependencies - [business-partner](../business-partner/README.md) — Customer reference, contact, address, 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 onto orders - [item-management](../item-management/README.md) — Item or SKU references on sales order lines - [organization](../organization/README.md) — Company scoping for sales documents - [primitives](../primitives/README.md) — Currency and unit-of-measure references for prices and quantities - [user-management](../user-management/README.md) — Sales permissions for submit, confirm, reject, amend, cancel, and close actions - [coa-management](../coa-management/README.md) — Future integration target for receivable, revenue, tax, discount, and variance account references once accounting posting is introduced