# README

## Overview

The Purchase module manages the procurement lifecycle from supplier-facing commercial terms through purchase ordering and 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 currencies/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 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 Requisition Lifecycle](docs/feature/purchase-requisition-lifecycle.md)**: Create and manage PurchaseRequisition documents with line items, estimated costs, requester and department context, and an approval lifecycle from draft through submission, approval, conversion to purchase order, or cancellation
- **[Purchase Requisition to PO Conversion](docs/feature/purchase-requisition-to-po-conversion.md)**: Convert approved purchase requisition lines into draft purchase orders with supplier resolution, pricing defaulting, and full line-level traceability
- **[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
- **[Supplier Purchase Pricing](docs/feature/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

## Module Scope

### In Scope

- Purchase requisition creation, submission, approval, rejection back to draft, recall, cancellation, conversion to purchase order, and closure
- Purchase requisition lines with item or free-text description, requested quantity, estimated unit price, optional suggested supplier, and need-by date
- Conversion of approved purchase requisition lines into draft purchase orders with supplier resolution, pricing defaulting, and line-level traceability
- 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
- Receipt progress tracking from inventory-owned `GOODS_RECEIPT` execution 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)
- 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 **commercial procurement document flow**: negotiated supplier price, 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, lot or serial handling, 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.

Supplier-specific pricing is included here because it directly drives purchase order 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 useful from day one.

The purchase module also owns the minimum cross-module contracts needed for execution. Inventory-owned goods receipt executions 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) — Currency and unit-of-measure references for pricing and 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
- [audit](../audit/README.md) — Immutable audit trail for order and receipt state transitions
