# README

## Overview

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

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 UoMs from primitives. It also coordinates with inventory for inbound stock receipt execution and hands supplier invoicing off to the account-payable module, while keeping the ordering rules inside the purchase domain. Role-based access control and auditable state transitions are treated as first-class requirements via user-management integration.

## Key Features

- **[Purchase Item Adoption](docs/model/PurchaseItem.md)**: Adopt an item-management item for purchasing and own the purchasing defaults its order lines resolve; only adopted items can be ordered
- **[Purchase Order Lifecycle](docs/feature/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 inventory receipt evidence and billing completion

## Module Scope

### In Scope

- Purchasing records for items (`PurchaseItem`), holding the purchasing defaults an order line resolves and, by their existence, which items may be ordered at all
- 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
- Receipt progress tracking from inbound-shipment-owned receipt evidence, including partial receipts and received-quantity accumulation against purchase order lines
- Purchase order billing status rollup driven by the account-payable module as supplier invoices are registered against ordered lines
- Integration with inventory for inbound stock execution and receipt evidence, plus a matching-data contract that lets account-payable perform supplier-invoice matching against ordered lines
- 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 and their approval-to-PO conversion flow (application layer, or a future requisition module)
- Supplier-specific purchase price lists and price rules, including quantity breaks and price defaulting onto order lines (application layer, or a future pricing module)
- Approval matrix orchestration, multi-level approval chains, RFQ or tendering, and sourcing auctions (future supplier-portal 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)
- Supplier invoice capture, payment term definitions, due-date scheduling, 2-way/3-way invoice matching, and invoice variance handling (account-payable module)
- Tax determination, journal entry posting, accounts payable payment execution, and bank settlement (financial-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 **purchase order document flow**: order commitment and receipt progress. 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, receipt execution, and valuation execution**. Purchase records supplier commitments and derives receipt progress from inventory evidence; inventory owns stock movement, on-hand balance, and cost layer updates. This separation keeps procurement focused on supplier-side commitments rather than warehouse internals.

Supplier invoicing and financial settlement are kept out of scope. Payment terms, supplier bill capture, invoice matching, and due-date scheduling are owned by the account-payable module, and journal posting, tax treatment, and cash disbursement belong to downstream financial-accounting or AP modules. This preserves a clean contract: purchase records what was ordered and received; account-payable captures and matches the supplier invoice; finance recognizes and settles it.

Purchasing defaults for an item are owned here rather than added to the shared item ledger. Whether ordering an item is expected to produce a goods receipt is a procurement 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.

The purchase module also owns the minimum cross-module contracts needed for execution. Inbound-shipment-owned receipt documents provide the receipt evidence used for purchase status. Purchase exposes ordered-line matching data and a billing-status rollup so account-payable can match supplier invoices and feed billed quantities back onto purchase order lines.

## 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) — Unit-of-measure references for order line quantities
- [inventory](../inventory/README.md) — Downstream execution of inbound stock movements and warehouse-level receipt consequences
- [user-management](../user-management/README.md) — Procurement and receiving permissions for submit, approve, receive, and cancel actions