# README

## Overview

The Purchase module manages the procurement lifecycle from supplier-facing commercial terms through purchase ordering, receipt confirmation, and supplier bill matching. It owns the transactional records that express what was ordered from which supplier, at what price, under which payment terms, for which receiving site, and how much of that commitment has been received or invoiced.

Purchase sits between master-data modules and operational/financial execution modules. It references suppliers from business-partner, items from item-management, organizational scope from organization, and currencies/UoMs from primitives. It also coordinates with inventory for inbound stock receipt execution and with future accounting or accounts-payable modules for financial posting, while keeping commercial procurement rules inside the purchase domain. Role-based access control and auditable state transitions are treated as first-class requirements via user-management and audit integrations.

## Key Features

- **[Purchase Order Lifecycle](docs/features/purchase-order-lifecycle.md)**: Create and manage PurchaseOrder documents with line items, supplier references, expected delivery dates, lifecycle control, and fulfillment status tracking from draft through receipt and billing completion
- **[Supplier Purchase Pricing](docs/features/supplier-purchase-pricing.md)**: Maintain supplier-specific purchase price lists and rules with date validity, quantity breaks, currency support, and deterministic defaulting onto purchase order lines
- **[Purchase Payment Terms](docs/features/purchase-payment-terms.md)**: Define supplier-facing payment schedules, installment structures, and early-payment discount terms that flow from ordering into supplier bill due-date calculation
- **[Goods Receipt Matching](docs/features/goods-receipt-matching.md)**: Record GoodsReceipt documents against purchase order lines, support partial receipts and quantity tolerances, and provide the matched receipt basis for inventory and bill validation
- **[Supplier Bill Matching](docs/features/supplier-bill-matching.md)**: Capture supplier invoices as PurchaseBill documents, validate them using 2-way or 3-way matching rules, detect quantity/price variances, and hand matched bills to downstream accounts-payable processing

## Module Scope

### In Scope

- Purchase order creation, revision, approval or ordering, rejection back to draft, cancellation, closure, and fulfillment status tracking
- Purchase order lines with item, quantity, unit of measure, supplier price, currency, expected delivery date, and receiving or billing progress
- Supplier-specific purchase pricing via `PurchasePriceList` and `PurchasePriceRule`, including effective dates, quantity breaks, and rule selection precedence
- Supplier-facing payment term definitions via `PurchasePaymentTerm`, including fixed-day, net-day, installment, and discount-based schedules
- Goods receipt recording via `GoodsReceipt`, including partial receipts, backorders, quantity tolerances, and received-quantity accumulation against purchase order lines
- Supplier bill capture and matching via `PurchaseBill`, including duplicate invoice detection, 2-way or 3-way matching, quantity or price variance handling, tax snapshot capture, and pre-AP cancellation controls
- Integration events or handoff contracts to inventory for inbound stock execution and to downstream accounting/AP modules for payable recognition, including `InboundReceiptHandoff` and a bill-ready payable handoff
- Company-scoped procurement documents with supplier references restricted to ACTIVE suppliers carrying the SUPPLIER role

### Out of Scope

- Supplier onboarding, qualification, certification, and performance scoring (business-partner or future supplier-management workflows)
- Purchase requisitions, approval matrix orchestration, RFQ or tendering, and sourcing auctions (future procurement workflow module or application layer)
- Blanket orders, call-off contracts, and framework agreements with committed release quantities (future purchasing enhancement)
- Reorder point planning, MRP-driven replenishment, and demand forecasting (future planning module)
- Warehouse execution details such as putaway, bin-level receiving tasks, storage assignment, and stock valuation calculation (inventory module)
- Landed cost allocation, customs or duty accruals, and freight capitalization (future purchasing/accounting capability)
- Tax determination, journal entry posting, accounts payable payment execution, and bank settlement (future accounting or AP modules)
- Supplier returns and return-to-vendor logistics (future reverse-logistics or extended purchase capability)
- Supplier catalog content syndication and punchout integration (future application-layer integration)

### Scope Decision Rationale

Purchase is scoped to the **commercial procurement document flow**: negotiated supplier price, agreed payment terms, order commitment, receipt confirmation, and supplier invoice matching. Those artifacts change together and depend on the same business rules, so they belong in one module rather than being split prematurely across pricing or AP domains.

Inventory is intentionally kept as the owner of **physical stock state and valuation execution**. Purchase records that goods were expected and received against a supplier commitment; inventory owns the resulting stock movement, on-hand balance, lot or serial handling, and cost layer updates. This separation keeps procurement focused on supplier-side matching rather than warehouse internals.

Financial settlement is also kept out of scope. Purchase can determine whether a supplier bill is commercially valid and ready to pay, but journal posting, tax treatment, and cash disbursement belong to downstream accounting or AP modules. This preserves a clean contract: purchase validates the obligation; accounting recognizes and settles it.

Supplier-specific pricing and payment terms are included here because they directly drive purchase order and bill behavior. Although generic enterprise pricing might later move into a dedicated cross-domain pricing module, the initial supplier-facing rules are tightly coupled to procurement and are needed to make purchase orders and bill matching useful from day one.

The purchase module also owns the minimum cross-module contracts needed for execution. `InboundReceiptHandoff` is the named contract from purchase to inventory when a posted receipt must create physical stock movement. Supplier bills remain inside purchase until matching completes; only then may a downstream AP/accounting handoff accept the bill for posting or settlement. Once that downstream handoff is accepted, cancellation or credit processing is no longer a pure purchase concern.

## Module Dependencies

- [business-partner](../business-partner/README.md) — Supplier reference, contact, address, and role classification; only ACTIVE partners with the SUPPLIER role can be used in purchase transactions
- [item-management](../item-management/README.md) — Item/SKU references on purchase order, receipt, and bill lines
- [organization](../organization/README.md) — Company scoping and receiving or delivery site context for purchase documents
- [primitives](../primitives/README.md) — Currency and unit-of-measure references for pricing, quantities, and payment term calculations
- [inventory](../inventory/README.md) — Downstream execution of inbound stock movements and warehouse-level receipt consequences
- [user-management](../user-management/README.md) — Procurement, receiving, and AP-facing permissions for submit, approve, receive, match, release, and cancel actions
- [audit](../audit/README.md) — Immutable audit trail for order, receipt, and bill state transitions and comparison outcomes
- [coa-management](../coa-management/README.md) — Future integration target for payable, accrual, and variance account references once accounting posting is introduced
