@tailor-platform/erp-kit 0.4.1 → 0.5.1

package/src/modules/purchase/docs/commands/UpdatePurchasePriceRule.md

@@ -0,0 +1,60 @@
+# UpdatePurchasePriceRule
+
+## Overview
+
+UpdatePurchasePriceRule changes the live pricing condition on an existing supplier price rule without modifying any purchase orders that already snapshotted that rule's price.
+
+## Business Rules
+
+- Target rule must exist
+- Updated references and value fields must satisfy the same validation rules as create
+- Updating an inactive rule is allowed so it can be corrected before reactivation
+- Updated precedence must remain unique within the supplier pricing context
+- Historical purchase orders preserve the original ordered price even when the source rule changes
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Rule exists?}
+    B -->|No| C[Return PRICE_RULE_NOT_FOUND]
+    B -->|Yes| D{References and values valid?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F{Unique precedence?}
+    F -->|No| G[Return DUPLICATE_RULE_PRECEDENCE]
+    F -->|Yes| H[Update rule]
+    H --> I[Return updated rule]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate item existence and active status
+- [primitives::GetCurrency](../../../primitives/docs/queries/GetCurrency.md) - Validate transaction currency
+- [primitives::GetUnit](../../../primitives/docs/queries/GetUnit.md) - Validate purchase unit of measure
+
+## Error Scenarios
+
+- **PRICE_RULE_NOT_FOUND**: Target price rule does not exist
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is inactive
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
+- **UNIT_NOT_FOUND**: Referenced purchase unit does not exist
+- **INVALID_UNIT_PRICE**: Unit price is zero or negative
+- **INVALID_MINIMUM_QUANTITY**: Minimum quantity is negative
+- **INVALID_EFFECTIVE_RANGE**: Effective end date is earlier than effective start date
+- **DUPLICATE_RULE_PRECEDENCE**: Another rule already owns the same precedence context
+
+## Test Cases
+
+- updates price and quantity break on an active rule
+- updates an inactive rule without reactivating it
+- preserves historical purchase-order snapshots after update
+- returns error when rule does not exist
+- returns error when updated references are invalid
+- returns error when the updated item does not exist
+- returns error when the updated item is inactive
+- returns error when the updated unit does not exist
+- returns error when the updated unit price is not positive
+- returns error when the updated minimum quantity is negative
+- returns error when the updated effective range is inverted
+- returns error when updated precedence duplicates another rule

package/src/modules/purchase/docs/features/goods-receipt-matching.md

@@ -0,0 +1,71 @@
+# Goods Receipt Matching
+
+## Overview
+
+Goods Receipt Matching records what quantity from a purchase order has actually been received from the supplier. A `GoodsReceipt` references one purchase order and one or more purchase order lines, captures received quantities and receipt dates, and updates each line's received progress. The receipt document is the procurement-side confirmation that supplier fulfillment occurred.
+
+This feature deliberately separates **commercial receipt confirmation** from **warehouse stock execution**. Purchase owns the receipt document and the matching rules against the purchase order; inventory remains the owner of the resulting stock movement, putaway, lot or serial recording, and on-hand updates. That split makes receipts usable both for stock items and for service or non-stock procurement scenarios. The named handoff contract from purchase to inventory is `InboundReceiptHandoff`, whose minimum payload is purchase order reference, purchase order line reference, goods receipt reference, received quantity, unit of measure, and receipt date.
+
+## Business Purpose
+
+- Confirm supplier fulfillment against the original purchase commitment
+- Support partial deliveries and backorders without losing order-level visibility
+- Enforce over-receipt and under-receipt tolerance rules on purchase order lines
+- Provide the receipt basis required for 3-way supplier bill matching
+- Trigger downstream inbound stock or service-acceptance processes without moving warehouse logic into purchase
+- Preserve an auditable history of what was received, when, and against which supplier commitment
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Purchase Order in ORDERED status] --> B[Create Goods Receipt]
+    B --> C[Select open order lines]
+    C --> D[Enter received quantities and dates]
+    D --> E{Within tolerance?}
+    E -->|No| F[Block or require override]
+    E -->|Yes| G[Post Goods Receipt]
+    G --> H[Update PO line received quantities]
+    G --> I[Emit inbound receipt handoff to inventory]
+    H --> J{All quantities received?}
+    J -->|No| K[PO remains PARTIALLY RECEIVED]
+    J -->|Yes| L[PO becomes RECEIVED]
+    G --> M[Receipt eligible for supplier bill matching]
+```
+
+## Scenario Patterns
+
+- **Full delivery**: The supplier delivers every ordered line in one shipment and a single posted goods receipt completes the receiving side of the order
+- **Partial shipment with backorder**: Only half the quantity arrives. The receipt posts successfully, open quantity remains on the PO, and another receipt can be recorded later
+- **Overdelivery within tolerance**: A supplier sends 102 units against an order for 100 where a 2 percent over-receipt tolerance is allowed, so the receipt is accepted
+- **Overdelivery beyond tolerance**: A supplier sends materially more than ordered, and the receipt is blocked or requires an explicit procurement exception
+- **Split line receiving**: One line on the order is fully received while another remains open, and the receipt captures both outcomes in the same document
+- **Service acceptance**: A non-stock service line is marked received or accepted without creating warehouse-level stock, but the receipt still unlocks downstream bill matching
+- **Receipt date tracking**: The supplier shipment arrives late, and the posted receipt captures the actual date for lead-time and supplier-performance analysis
+- **Receipt correction before posting**: A receiver notices a quantity entry mistake while the receipt is still draft and corrects it before it updates PO fulfillment
+- **Future receipt reversal**: A posted receipt is later found to be incorrect. A future reversal workflow will preserve the original posted receipt, emit a compensating correction, and keep the audit trail intact rather than mutating history
+
+## Test Cases
+
+- Creating a goods receipt against an `ORDERED` purchase order with open quantity should succeed
+- A goods receipt line must reference a valid purchase order line and a received quantity greater than zero
+- A cancelled or closed purchase order must not accept new goods receipts
+- Posting a goods receipt must increase the referenced purchase order line's cumulative received quantity
+- Partial receipts must leave the remaining open quantity available for future receipts
+- Receiving more than the ordered quantity plus configured tolerance should fail or require an explicit override
+- Receiving against an inactive item or inactive supplier should be prevented if the order is no longer valid for execution
+- A goods receipt posted for a stock item should emit or call the downstream inventory handoff contract exactly once
+- The `InboundReceiptHandoff` payload must include purchase order reference, purchase order line reference, goods receipt reference, received quantity, UoM, and receipt date at minimum
+- A goods receipt posted for a non-stock or service line must not require warehouse stock execution
+- Only posted goods receipts should count toward 3-way supplier bill matching
+- Receipt posting must be isolated by company and must not update purchase orders belonging to another company
+- If a receipt is reversed or corrected through a future workflow, the purchase order received quantity must remain auditable rather than silently overwritten
+- Purchase order status should move to a partial or full receipt state based on aggregate posted receipt quantities
+- Only authorized receiving or procurement users should be able to post goods receipts
+- A goods receipt should preserve the supplier, order, and line references needed for audit and traceability
+
+## Reference Links
+
+- [Odoo vendor bills and three-way matching](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/manage_deals/manage.html#vendor-bills)
+- [Oracle Fusion Cloud Procurement documentation](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
+- [SAP receipt confirmation documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD/65de2977205c403bbc107264b8eccf4b/552eb9c732c14df6a2926efce6d890ad.html)

package/src/modules/purchase/docs/features/purchase-order-lifecycle.md

@@ -0,0 +1,87 @@
+# Purchase Order Lifecycle
+
+## Overview
+
+Purchase Order Lifecycle governs how a supplier commitment is created, reviewed, placed, fulfilled, and closed. A `PurchaseOrder` records the commercial agreement with a supplier for one or more items, including ordered quantity, expected delivery, unit price, currency, payment-term reference, and receiving site. The order is the primary document that downstream receipts and supplier bills match against.
+
+The lifecycle tracks both document control and fulfillment progress. A purchase order begins in draft, may be submitted for approval, can be explicitly rejected back to draft with a reason, becomes ordered when released to the supplier, then moves through partial or full receipt and partial or full billing states as execution proceeds. This gives procurement teams a single source of truth for what is still open with each supplier.
+
+## Business Purpose
+
+- Create a formal, auditable supplier commitment before goods or services are received
+- Freeze negotiated commercial terms at the time an order is placed, even if future price lists change
+- Capture the company and receiving-site context needed for receipt routing and supplier traceability
+- Track open quantity, received quantity, billed quantity, and remaining commitment per line
+- Provide the reference document required for receipt matching and supplier bill matching
+- Support partial fulfillment without losing visibility into remaining supplier obligations
+- Prevent inactive suppliers, inactive items, or incomplete orders from entering downstream execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Purchase Order] --> B[DRAFT]
+    B --> C[Add supplier, lines, prices, terms]
+    C --> D{Submit?}
+    D -->|No| C
+    D -->|Yes| E[SUBMITTED]
+    E --> F{Approve?}
+    F -->|Reject| R[REJECTED]
+    R --> B
+    F -->|Approve and send| G[ORDERED]
+    G --> H{Receipt posted?}
+    H -->|Partial| I[PARTIALLY RECEIVED]
+    H -->|Full| J[RECEIVED]
+    I --> K{Supplier bill matched?}
+    J --> K
+    K -->|Partial| L[PARTIALLY BILLED]
+    K -->|Full| M[BILLED]
+    I --> N{Close remaining?}
+    J --> N
+    L --> N
+    M --> N
+    N -->|Close| O[CLOSED]
+    B --> P[CANCELLED]
+    E --> P
+    G --> P
+```
+
+## Scenario Patterns
+
+- **Standard stock purchase**: A buyer creates an order for replenishment items, applies supplier pricing and payment terms, submits it, and sends it to the supplier once approved
+- **Rejected for revision**: An approver rejects a submitted order because the receiving site or supplier quote is wrong, and the order returns to draft with the rejection reason preserved for audit
+- **Split delivery**: A supplier confirms the order but ships in two batches. The purchase order remains open after the first receipt and closes only when all ordered quantity is received or explicitly closed out
+- **Price override before release**: A buyer starts from an automatically suggested supplier price rule but overrides one line before approval due to a one-time negotiated exception
+- **Service or non-stock procurement**: A purchase order is created for a supplier-provided service or consumable item that may still require bill matching even if no warehouse stock is updated
+- **Order cancellation before fulfillment**: An order is cancelled after submission because demand disappears and no receipt or bill has yet been matched
+- **Close remaining balance**: A supplier underdelivers the final 2 units and the buyer chooses to close the remaining open quantity instead of keeping the order indefinitely open
+- **Multi-line mixed fulfillment**: Some lines on the same order are fully received while others remain open, and line-level progress rolls up to the document status
+- **Supplier change control**: A buyer duplicates and revises a draft order rather than changing the supplier on an already ordered document, preserving traceability
+
+## Test Cases
+
+- Creating a purchase order with a valid ACTIVE supplier, company, and at least one line should succeed
+- A purchase order line must require an ACTIVE item, quantity greater than zero, and a non-negative unit price
+- Purchase orders can only be created in `DRAFT` status
+- A `DRAFT` order can be revised freely, but `ORDERED` commercial fields must not change without an explicit revision workflow
+- Submitting a purchase order without any lines should fail
+- Submitting a purchase order without a receiving site when the line requires physical receipt should fail
+- Submitting a purchase order for a partner that does not carry the SUPPLIER role should fail
+- Approving or ordering a purchase order whose supplier is INACTIVE should fail
+- Rejecting a submitted purchase order should record the rejection reason and return the document to `DRAFT`
+- Cancelling a purchase order after a posted receipt or matched supplier bill exists should be prevented
+- Posting a partial receipt should update line received quantities and move the order to a partial receipt status
+- Matching a supplier bill should update line billed quantities independently of receipt quantities
+- Closing a purchase order should be allowed only when all remaining open quantities are fulfilled, cancelled, or explicitly written off
+- Purchase order totals and open balances must be isolated per company
+- The applied unit price on a purchase order line must remain unchanged even if the underlying supplier price rule is later edited
+- A purchase order must preserve its assigned payment term snapshot for downstream bill due-date calculation
+- Each purchase order line should expose remaining quantity to receive and remaining quantity to bill
+- Duplicate external supplier order references should be rejected or flagged according to company policy
+- Only authorized procurement users should be able to submit, approve, cancel, or close purchase orders
+
+## Reference Links
+
+- [Odoo Purchase documentation](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase.html)
+- [Oracle Fusion Cloud Procurement guide](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
+- [SAP procurement overview](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/purchase/docs/features/purchase-payment-terms.md

@@ -0,0 +1,67 @@
+# Purchase Payment Terms
+
+## Overview
+
+Purchase Payment Terms defines how supplier invoices become due once commercial purchasing is complete. A `PurchasePaymentTerm` models rules such as net days, end-of-month due dates, installment splits, and early-payment discounts. These terms can default onto purchase orders from the supplier's purchasing profile and flow forward into `PurchaseBill` so that the bill carries the expected supplier settlement schedule when handed off to accounts payable.
+
+The feature is intentionally limited to supplier-facing payable terms within procurement. It does not execute payment runs or post accounting entries. Instead, it standardizes the contractual timing information that purchasing and accounts payable both need.
+
+## Business Purpose
+
+- Standardize supplier settlement expectations across purchase orders and supplier bills
+- Reduce manual bill-entry work by defaulting due-date schedules from negotiated payment terms
+- Support installment or staged payment structures for large or milestone-based purchases
+- Enable early-payment discount handling by making discount windows explicit and reusable
+- Provide a consistent handoff contract from procurement to downstream accounts-payable processing
+- Separate payment timing rules from supplier master data so terms can evolve independently per transaction or agreement
+- Preserve how discountable amount is interpreted by explicitly recording whether discount logic applies to gross or net invoice amount
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Define Purchase Payment Term] --> B[Configure schedule lines and discount rules]
+    B --> C[Activate term]
+    C --> D[Default term from supplier purchasing profile or assign manually to PO]
+    D --> E[Supplier Bill created from order or entered manually]
+    E --> F[Copy payment term snapshot to bill]
+    F --> G[Calculate due dates and installment amounts]
+    G --> H[Bill becomes ready for downstream AP processing]
+```
+
+## Scenario Patterns
+
+- **Net 30 standard term**: A supplier agreement states payment is due 30 days after the invoice date, and every bill using that term receives a single due date 30 days later
+- **2/10 net 30**: A supplier grants a discount if the bill is paid within 10 days, otherwise full payment is due in 30 days. The term captures both the discount window and final due date
+- **Supplier default term propagation**: A supplier is configured with a default purchase payment term, and each new draft PO starts with that term before the buyer decides whether to override it
+- **Installment schedule**: A capital purchase requires 30 percent upfront and 70 percent after delivery. The payment term expresses two due schedule lines rather than a single maturity date
+- **End-of-month settlement**: Bills dated throughout the month become due at month end plus a fixed number of days, matching supplier accounting policy
+- **Term override for one PO**: A buyer uses the supplier's usual net 45 term on most orders but overrides a specific order to net 15 because of a negotiated expedited arrangement
+- **Term retirement**: An old payment term is deactivated when the supplier contract is renegotiated, but historical orders and bills retain the prior snapshot
+- **Manual supplier bill entry**: A bill is entered directly against a PO and inherits its purchase payment term even if no automatic bill generation exists
+- **Discount visibility for AP**: The matched supplier bill exposes the discount cutoff date so downstream AP automation can decide whether to pay early
+
+## Test Cases
+
+- Creating a purchase payment term with at least one schedule line should succeed
+- The sum of installment percentages on a percentage-based payment term must equal 100 percent
+- A payment term schedule line must not allow a negative percentage or negative fixed amount
+- A discount date must occur on or before the final due date
+- A payment term that offers early-payment discount must record whether the discount base is `GROSS_AMOUNT` or `NET_AMOUNT`
+- Inactive payment terms must not be assignable to new purchase orders or new supplier bills
+- When a supplier purchasing profile provides a default payment term, a new draft purchase order should inherit it automatically unless the buyer overrides it
+- A purchase order should snapshot its assigned payment term so later edits do not alter existing downstream bills
+- A supplier bill due-date schedule must be computable from the bill date and the assigned payment term
+- End-of-month terms must produce a due date based on calendar month logic rather than a simple fixed-day offset
+- Installment terms should generate multiple due schedule lines on the supplier bill
+- Early-payment discount metadata must remain available after bill matching so downstream AP can consume it
+- A payment term can be overridden on a draft purchase order but changing it after matched billing should be prevented or explicitly controlled
+- Purchase payment terms must be isolated by company when procurement policies differ by legal entity
+- Deactivating a payment term that is already referenced historically must preserve existing order and bill snapshots
+- Only authorized procurement or finance users should be able to create, update, activate, or deactivate payment terms
+
+## Reference Links
+
+- [Odoo payment terms documentation](https://www.odoo.com/documentation/19.0/applications/finance/accounting/customer_invoices/payment_terms.html)
+- [Oracle Fusion Cloud Financials and procurement documentation](https://docs.oracle.com/en/cloud/saas/index.html)
+- [SAP S/4HANA Cloud documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/purchase/docs/features/supplier-bill-matching.md

@@ -0,0 +1,79 @@
+# Supplier Bill Matching
+
+## Overview
+
+Supplier Bill Matching captures supplier invoices as `PurchaseBill` documents and validates them against the commercial and fulfillment evidence already recorded in purchase. Each bill line references one or more purchase order lines and, when 3-way matching is required, the posted goods receipts that prove quantity has actually been received. The result is a procurement-side decision: is this supplier invoice commercially acceptable, blocked for variance, cancelled before downstream acceptance, or ready for downstream accounts payable?
+
+This feature does not post journal entries or execute payment. Its responsibility is to compare what the supplier invoiced with what was ordered and received, detect mismatches, preserve tax and invoice identity required for legal validity, and preserve a clean handoff contract for future AP and accounting modules. The minimum bill lifecycle is `DRAFT` → `BLOCKED` or `MATCHED`, with `CANCELLED` available only before downstream AP handoff acceptance.
+
+## Business Purpose
+
+- Prevent overbilling by ensuring supplier invoices align with ordered and received quantities
+- Detect price variances between purchase order commitments and supplier invoice lines
+- Support both 2-way matching (order to invoice) and 3-way matching (order, receipt, invoice)
+- Provide a clear blocked-versus-ready status before bills reach downstream accounts-payable workflows
+- Allow matched or blocked bills to be cancelled while they are still owned by purchase and have not yet been accepted by downstream AP
+- Carry supplier invoice identity, payment-term snapshot, and due-date schedule into payable processing
+- Capture supplier tax identifiers, tax codes, and tax amounts needed by downstream AP validation
+- Preserve an auditable link between invoice lines, purchase orders, and receipts
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Purchase Bill] --> B[Enter supplier invoice reference and lines]
+    B --> C[Match bill lines to PO lines]
+    C --> D{Matching mode?}
+    D -->|2-way| E[Compare invoice to ordered qty and price]
+    D -->|3-way| F[Compare invoice to ordered qty, price, and posted receipts]
+    E --> G{Within tolerance?}
+    F --> G
+    G -->|No| H[BLOCKED FOR VARIANCE]
+    G -->|Yes| I[MATCHED]
+    I --> J[Calculate due schedule from payment term]
+    J --> K[Ready for downstream AP or accounting handoff]
+    H --> L{Cancel before AP handoff?}
+    I --> L
+    L -->|Yes| M[CANCELLED]
+    L -->|No| J
+```
+
+## Scenario Patterns
+
+- **Perfect 3-way match**: The supplier invoice arrives after the goods receipt, and billed quantities and prices match the purchase order exactly, so the bill is marked ready
+- **Price variance within tolerance**: The supplier invoice price differs slightly from the ordered price due to exchange rounding or minor surcharge, and the configured tolerance allows the bill through
+- **Quantity variance blocked**: The supplier invoices 100 units, but only 80 have been received under a 3-way match policy, so the bill is blocked pending additional receipt or correction
+- **2-way matching for non-stock procurement**: A service purchase is matched only against the purchase order because warehouse receipt proof is not required by policy
+- **Duplicate invoice prevention**: The same supplier invoice number is entered twice for one company and supplier, and the second attempt is rejected
+- **Partial billing**: The supplier bills only the first shipment of a larger order; the matched quantity is recorded and the order remains open for later bills
+- **Pre-AP cancellation**: A matched bill is discovered to contain the wrong supplier invoice reference before AP accepts it, so procurement cancels the bill and preserves the original comparison evidence
+- **Credit or correction workflow precursor**: A supplier invoice is overbilled and blocked or cancelled, creating the basis for a future thin `PurchaseCreditNote` or bill-revision workflow without redesigning the `PurchaseBill` state machine
+- **Payment-term inheritance**: The bill inherits the order's negotiated payment term so downstream AP sees the correct due dates and discount window
+- **Tax snapshot capture**: The bill snapshots supplier tax identification, tax code, taxable amount, and tax amount so legal invoice validation survives later supplier-master edits
+
+## Test Cases
+
+- Creating a purchase bill with a valid supplier, company, and at least one bill line should succeed
+- A purchase bill line must reference a valid purchase order line and a billed quantity greater than zero
+- Duplicate supplier invoice numbers for the same supplier and company should be rejected
+- A 2-way matched bill must compare billed quantity and price to the referenced purchase order line
+- A 3-way matched bill must not approve a billed quantity greater than the cumulative posted receipt quantity, subject to configured tolerance
+- A bill with a price variance above configured tolerance should be marked blocked rather than matched
+- A bill matched to a cancelled purchase order should fail
+- A matched bill must snapshot the supplier invoice date, external invoice number, ordered price reference, assigned payment term, supplier tax identifier, tax code, taxable amount, and tax amount
+- Partial billing must increase the purchase order line billed quantity without forcing the order closed
+- A supplier bill must not be considered ready for downstream AP until all required matching checks pass
+- A matched or blocked bill may transition to `CANCELLED` only while no downstream AP or accounting module has accepted the payable handoff
+- Cancelling a bill must preserve the original variance evidence and line references for future credit-note or dispute workflows
+- Bills must be isolated by company and must not reference purchase orders from another company
+- If a bill is blocked for variance, the variance reason and comparison basis should remain visible for review
+- Matching logic must preserve whether the bill used 2-way or 3-way matching
+- Only authorized procurement or AP users should be able to match, block, or release supplier bills
+- A matched bill should expose the due-date schedule calculated from the assigned purchase payment term
+- Editing supplier price rules after bill creation must not change the comparison baseline for an existing matched or blocked bill
+
+## Reference Links
+
+- [Odoo vendor bills and three-way matching](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/manage_deals/manage.html#vendor-bills)
+- [Oracle invoice matching overview](https://docs.oracle.com/en/cloud/saas/financials/24c/fappp/invoice-matching.html)
+- [SAP supplier invoice and invoice verification documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/purchase/docs/features/supplier-purchase-pricing.md

@@ -0,0 +1,72 @@
+# Supplier Purchase Pricing
+
+## Overview
+
+Supplier Purchase Pricing manages the supplier-specific commercial rules that default onto purchase order lines. A `PurchasePriceList` groups one supplier's purchasable pricing conditions, while `PurchasePriceRule` defines the actual pricing logic for a given item or purchasing context, such as effective date, minimum quantity, currency, and unit of measure. These rules allow procurement teams to keep negotiated purchase prices in a structured, reusable form instead of entering them manually on every order.
+
+The feature is intentionally procurement-specific rather than generic enterprise pricing. It focuses on "what do we expect to pay this supplier for this item under these conditions?" and provides deterministic price selection when buyers create or revise purchase orders. When the supplier's purchasing unit of measure differs from the item's stocking unit, this feature relies on conversion definitions owned by `primitives` rather than re-implementing unit-conversion logic in purchase. Blanket orders and release-against-contract pricing remain explicit non-goals for the MVP.
+
+## Business Purpose
+
+- Reduce manual entry by defaulting supplier-negotiated prices into purchase order lines
+- Capture quantity breaks, date validity, and currency-specific supplier agreements
+- Preserve commercial history by snapshotting the applied rule onto the purchase order at ordering time
+- Support consistent purchasing across buyers, companies, and repeated replenishment cycles
+- Make price variance detection possible when supplier bills arrive above or below the agreed purchase condition
+- Separate procurement pricing from product definition and from downstream AP settlement logic
+- Keep purchasing-UoM pricing compatible with stock-UoM receiving by delegating conversions to the shared unit-conversion capability
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Purchase Price List] --> B[Add Purchase Price Rules]
+    B --> C[Set supplier, item scope, dates, quantity breaks]
+    C --> D[Activate list]
+    D --> E[Buyer creates PO line]
+    E --> F[Resolve applicable rules]
+    F --> G{Rule found?}
+    G -->|Yes| H[Apply best matching rule]
+    G -->|No| I[Manual price entry]
+    H --> J[Snapshot applied price and rule reference on PO line]
+    I --> J
+    J --> K[Order placed]
+    K --> L[Supplier bill matching compares invoice price to ordered price]
+```
+
+## Scenario Patterns
+
+- **Annual supplier contract**: A supplier price list is created for the fiscal year with negotiated base prices for each frequently purchased item
+- **Quantity break pricing**: A supplier offers 10 currency per unit above 100 pieces and 9 currency per unit above 500 pieces; the applicable tier is selected automatically based on ordered quantity
+- **Time-bounded promotion**: A temporary supplier discount is valid for one month. Orders placed within the effective range receive the temporary price, after which the normal rule applies again
+- **Multi-currency purchasing**: The same supplier provides one item in USD and another in EUR; purchase price rules keep those commercial conditions separate and explicit
+- **Supplier-specific UoM**: A supplier sells an item by carton while the item's internal base unit is piece; the purchase price rule is keyed to the purchasing UoM used on the PO
+- **UoM conversion delegation**: A buyer orders in cartons while inventory receives in pieces. The purchase rule prices the carton, and purchase calls the shared unit-conversion definitions from `primitives` to derive receipt and variance comparisons consistently
+- **One-time exception**: The system defaults the contracted price, but the buyer manually overrides it for a special order while retaining the original matched-rule reference for auditability
+- **Rule retirement**: An old price list is deactivated when a new contract begins, preventing future orders from using obsolete supplier pricing
+- **Price variance review**: The supplier invoice arrives above the ordered unit price, and the matched purchase price rule helps determine whether the variance is expected or should be blocked
+
+## Test Cases
+
+- Creating a purchase price list for an ACTIVE supplier with the SUPPLIER role should succeed
+- A purchase price rule must require a positive unit price and a valid item or defined pricing scope
+- A quantity-break rule must not allow a negative minimum quantity
+- A rule with an effective end date earlier than its start date should fail validation
+- Inactive price lists or inactive rules must not be selected for new purchase orders
+- When multiple rules match the same PO line, rule resolution must follow deterministic precedence based on supplier, item scope, UoM, minimum quantity, date, and explicit priority
+- When no rule matches a PO line, the system should allow manual pricing while marking the line as unmatched to a price rule
+- Editing a price rule after a purchase order is placed must not retroactively change the ordered unit price on that existing order
+- A purchase price list must be isolated by company when company-specific procurement data is required
+- Duplicate rules with indistinguishable precedence for the same supplier, item, date, and quantity context should be rejected or warned
+- A purchase price rule currency must reference a valid currency from the primitives module
+- If a purchase price rule UoM differs from the item's stocking UoM, a valid conversion path from `primitives` must exist before the rule can be used operationally
+- Only ACTIVE items should be assignable to newly created purchase price rules
+- A buyer should be able to override a defaulted price on a draft order while retaining audit information about the default rule
+- Supplier bill matching should be able to compare invoice price against the purchase order's snapshotted price even if the underlying rule is later deactivated
+- Only authorized procurement users should be able to create, update, activate, or deactivate purchase price lists
+
+## Reference Links
+
+- [Odoo vendor price and blanket-order purchasing concepts](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/purchase/manage_deals.html)
+- [Oracle Fusion Cloud Procurement documentation](https://docs.oracle.com/en/cloud/saas/procurement/index.html)
+- [SAP S/4HANA Cloud procurement documentation](https://help.sap.com/docs/SAP_S4HANA_CLOUD)

package/src/modules/purchase/docs/models/GoodsReceipt.md

@@ -0,0 +1,58 @@
+# GoodsReceipt
+
+## Description
+
+GoodsReceipt is the purchase-side confirmation that ordered goods or services were received from the supplier. It records one receipt event against one purchase order with one or more receipt lines, updates purchase-order receiving progress, and optionally emits a downstream inventory handoff for stock items.
+
+The model intentionally separates procurement confirmation from warehouse execution. Purchase owns the fact that the supplier fulfilled part of the commitment; inventory owns the resulting stock movement and physical storage consequences.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createGoodsReceipt
+    Draft --> Draft: updateGoodsReceipt
+    Draft --> Posted: postGoodsReceipt
+    Draft --> Cancelled: cancelGoodsReceipt
+```
+
+### Command Definitions
+
+- [createGoodsReceipt](../commands/CreateGoodsReceipt.md) - Create a draft receipt against open purchase-order lines
+- [updateGoodsReceipt](../commands/UpdateGoodsReceipt.md) - Correct draft receipt quantities, dates, or line composition before posting
+- [postGoodsReceipt](../commands/PostGoodsReceipt.md) - Validate tolerance, post the receipt, update order progress, and emit the inbound handoff
+- [cancelGoodsReceipt](../commands/CancelGoodsReceipt.md) - Cancel a draft receipt before it affects purchase-order fulfillment
+
+### Query Definitions
+
+- [getGoodsReceipt](../queries/GetGoodsReceipt.md) - Retrieve a goods receipt with all receipt lines and handoff metadata
+
+### Models
+
+- GoodsReceipt
+- GoodsReceiptLine
+- InboundReceiptHandoff
+
+### Invariants
+
+- Every goods receipt belongs to exactly one company, one supplier, and one purchase order
+- Every receipt line references one open purchase-order line and records a received quantity greater than zero
+- Only `POSTED` receipts contribute to purchase-order received quantities and 3-way bill matching
+- A receipt cannot post against a cancelled or closed purchase order
+- Over-receipt beyond configured tolerance is invalid unless an explicit override path is recorded by policy
+- Service or non-stock receipt lines do not require downstream warehouse execution even when the procurement receipt is posted
+- Posted receipts are immutable; future corrections must use a compensating workflow instead of mutating receipt history in place
+- The minimum `InboundReceiptHandoff` payload contains purchase-order reference, purchase-order-line reference, goods-receipt reference, received quantity, unit of measure, receipt date, destination site, and destination storage location when stock execution requires it
+
+### Relationships
+
+- **Belongs To PurchaseOrder**: Each receipt posts against one [PurchaseOrder](./PurchaseOrder.md)
+- **Has Many GoodsReceiptLines**: Each receipt contains one or more line-level receipt confirmations
+- **References Item**: Receipt lines trace back to one [Item](../../../item-management/docs/models/Item.md) through the purchase-order line
+- **May Emit InboundReceiptHandoff**: Posted stock receipts hand off to inventory execution using [CreateStockMovement](../../../inventory/docs/commands/CreateStockMovement.md) or an equivalent downstream adapter

package/src/modules/purchase/docs/models/PurchaseBill.md

@@ -0,0 +1,68 @@
+# PurchaseBill
+
+## Description
+
+PurchaseBill captures a supplier invoice inside the purchase domain until procurement matching is complete. It compares supplier-invoiced quantities, prices, and tax information against purchase-order commitments and, when required, posted goods receipts. The bill is then marked matched, blocked for variance, or cancelled before downstream AP acceptance.
+
+The purchase bill also owns the procurement-side payable readiness contract. Once a bill is matched, purchase can hand downstream modules a stable `BillReadyHandoff` payload containing the invoice identity, matched amounts, due schedule, and tax snapshot.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createPurchaseBill
+    Draft --> Draft: updatePurchaseBill
+    Draft --> Blocked: matchPurchaseBill
+    Draft --> Matched: matchPurchaseBill
+    Blocked --> Matched: releasePurchaseBill
+    Draft --> Cancelled: cancelPurchaseBill
+    Blocked --> Cancelled: cancelPurchaseBill
+    Matched --> Cancelled: cancelPurchaseBill
+```
+
+### Command Definitions
+
+- [createPurchaseBill](../commands/CreatePurchaseBill.md) - Create a draft supplier bill with invoice identity and line references
+- [updatePurchaseBill](../commands/UpdatePurchaseBill.md) - Revise a draft bill before procurement matching is finalized
+- [matchPurchaseBill](../commands/MatchPurchaseBill.md) - Run 2-way or 3-way matching and set the bill to matched or blocked
+- [releasePurchaseBill](../commands/ReleasePurchaseBill.md) - Move a blocked bill to matched after authorized variance resolution
+- [cancelPurchaseBill](../commands/CancelPurchaseBill.md) - Cancel a draft, blocked, or matched bill before downstream AP accepts the handoff
+
+### Query Definitions
+
+- [getPurchaseBill](../queries/GetPurchaseBill.md) - Retrieve a supplier bill with matching results, snapshots, and line references
+- [calculatePurchaseBillDueSchedule](../queries/CalculatePurchaseBillDueSchedule.md) - Compute the downstream payable schedule from the bill's payment-term snapshot
+
+### Models
+
+- PurchaseBill
+- PurchaseBillLine
+- PurchaseBillTaxSnapshot
+- BillReadyHandoff
+
+### Invariants
+
+- Every purchase bill belongs to exactly one company and one supplier
+- Supplier invoice number is unique within one company and supplier combination
+- Every bill line references at least one purchase-order line and records billed quantity greater than zero
+- `MATCHED` bills preserve the comparison baseline: invoice date, invoice number, ordered price reference, payment-term snapshot, supplier tax identifier, tax code, taxable amount, and tax amount
+- A 3-way match cannot mark a bill as matched when billed quantity exceeds cumulative posted receipt quantity beyond tolerance
+- `BLOCKED` bills must preserve the variance reason and comparison basis for review
+- `CANCELLED` is allowed only while no downstream AP or accounting module has accepted the `BillReadyHandoff`
+- 4-way matching is explicitly out of scope for this module plan; quality evidence can be added as a future extension without redesigning the bill lifecycle
+- Credit-note and debit-memo workflows are future extensions that must preserve the original bill evidence rather than rewriting it
+
+### Relationships
+
+- **Belongs To BusinessPartner**: Each bill references one supplier [BusinessPartner](../../../business-partner/docs/models/BusinessPartner.md)
+- **References PurchaseOrder**: Bill lines match against one or more [PurchaseOrder](./PurchaseOrder.md) lines
+- **References GoodsReceipt**: 3-way matching may compare against posted [GoodsReceipt](./GoodsReceipt.md) lines
+- **Snapshots PurchasePaymentTerm**: The bill carries a [PurchasePaymentTerm](./PurchasePaymentTerm.md) snapshot and calculated due schedule
+- **Snapshots PartnerIdentification**: The bill stores supplier tax identity from [PartnerIdentification](../../../business-partner/docs/models/PartnerIdentification.md)
+- **May Emit BillReadyHandoff**: Matched bills hand off invoice reference, matched amounts, due schedule, tax snapshot, and matching mode to downstream AP or accounting