@tailor-platform/erp-kit 0.4.0 → 0.5.0

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

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

@@ -0,0 +1,88 @@
+# PurchaseOrder
+
+## Description
+
+PurchaseOrder is the commercial procurement document that turns supplier pricing and payment terms into a concrete supplier commitment. It owns the supplier reference, receiving site, ordered lines, agreed unit prices, payment-term snapshot, and the fulfillment progress that later receipts and supplier bills consume.
+
+The model combines document-control states with fulfillment states so procurement can answer both questions at once: "has this order been commercially approved?" and "how much of it is still open to receive or bill?"
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createPurchaseOrder
+    Draft --> Draft: updatePurchaseOrder
+    Draft --> Submitted: submitPurchaseOrder
+    Submitted --> Draft: rejectPurchaseOrder
+    Submitted --> Ordered: approvePurchaseOrder
+    Draft --> Cancelled: cancelPurchaseOrder
+    Submitted --> Cancelled: cancelPurchaseOrder
+    Ordered --> Cancelled: cancelPurchaseOrder
+    Ordered --> PartiallyReceived: postGoodsReceipt
+    Ordered --> Received: postGoodsReceipt
+    PartiallyReceived --> PartiallyReceived: postGoodsReceipt
+    PartiallyReceived --> Received: postGoodsReceipt
+    Ordered --> PartiallyBilled: matchPurchaseBill
+    Ordered --> Billed: matchPurchaseBill
+    PartiallyReceived --> PartiallyBilled: matchPurchaseBill
+    PartiallyReceived --> Billed: matchPurchaseBill
+    Received --> PartiallyBilled: matchPurchaseBill
+    Received --> Billed: matchPurchaseBill
+    PartiallyBilled --> PartiallyBilled: matchPurchaseBill
+    PartiallyBilled --> Billed: matchPurchaseBill
+    PartiallyReceived --> Closed: closePurchaseOrder
+    Received --> Closed: closePurchaseOrder
+    PartiallyBilled --> Closed: closePurchaseOrder
+    Billed --> Closed: closePurchaseOrder
+```
+
+### Command Definitions
+
+- [createPurchaseOrder](../commands/CreatePurchaseOrder.md) - Create a new draft purchase order with one or more lines
+- [updatePurchaseOrder](../commands/UpdatePurchaseOrder.md) - Revise mutable draft commercial fields and line content
+- [submitPurchaseOrder](../commands/SubmitPurchaseOrder.md) - Validate draft completeness and move the order into submitted review
+- [rejectPurchaseOrder](../commands/RejectPurchaseOrder.md) - Return a submitted order to draft with a rejection reason
+- [approvePurchaseOrder](../commands/ApprovePurchaseOrder.md) - Freeze commercial terms and release a submitted order to the supplier
+- [cancelPurchaseOrder](../commands/CancelPurchaseOrder.md) - Cancel an order before downstream fulfillment or billing makes it irreversible
+- [closePurchaseOrder](../commands/ClosePurchaseOrder.md) - Close remaining open quantity after fulfillment or explicit write-off
+- [postGoodsReceipt](../commands/PostGoodsReceipt.md) - Update receipt progress and receiving status from posted goods receipts
+- [matchPurchaseBill](../commands/MatchPurchaseBill.md) - Update billed progress and billing status from matched supplier bills
+
+### Query Definitions
+
+- [getPurchaseOrder](../queries/GetPurchaseOrder.md) - Retrieve a purchase order with its lines, snapshots, and fulfillment totals
+
+### Models
+
+- PurchaseOrder
+- PurchaseOrderLine
+- PurchaseOrderPaymentTermSnapshot
+- PurchaseOrderLinePriceSnapshot
+
+### Invariants
+
+- A purchase order always belongs to exactly one company and one supplier
+- Submitted, ordered, fulfilled, billed, and closed orders must contain at least one line
+- Every line references an active item, has ordered quantity greater than zero, and has a non-negative agreed unit price
+- Lines that require physical receipt must carry a receiving site before the order can leave draft
+- Commercial fields that define the supplier commitment are mutable only while the order is in `DRAFT`
+- The payment term snapshot and ordered unit price snapshot are immutable after the order enters `ORDERED`
+- Cumulative received quantity and cumulative billed quantity cannot be negative and cannot exceed business tolerance rules for the line
+- Cancellation is not allowed once a posted receipt or a matched supplier bill already exists
+- External supplier order reference is unique within one company when provided
+
+### Relationships
+
+- **Belongs To BusinessPartner**: Each order references one supplier [BusinessPartner](../../../business-partner/docs/models/BusinessPartner.md)
+- **Belongs To Site**: Each order belongs to one receiving [Site](../../../organization/docs/models/Site.md) at document level, with line-level overrides allowed as an extension
+- **Has Many PurchaseOrderLines**: Each order contains one or more commercial commitment lines
+- **Snapshots PurchasePaymentTerm**: The order stores one immutable [PurchasePaymentTerm](./PurchasePaymentTerm.md) snapshot for downstream bill calculation
+- **Snapshots PurchasePriceRule**: Each line may preserve the matched [PurchasePriceRule](./PurchasePriceRule.md) reference and final ordered price
+- **Referenced By GoodsReceipt**: [GoodsReceipt](./GoodsReceipt.md) lines consume open ordered quantity
+- **Referenced By PurchaseBill**: [PurchaseBill](./PurchaseBill.md) lines consume open billed quantity

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

@@ -0,0 +1,59 @@
+# PurchasePaymentTerm
+
+## Description
+
+PurchasePaymentTerm defines the supplier-facing settlement schedule that purchase orders and supplier bills snapshot for downstream payable processing. A term contains one or more schedule lines that express net-day, end-of-month, fixed-day, installment, and early-payment-discount logic.
+
+The model stays inside purchase because it is part of the commercial agreement captured during procurement, but it is designed to hand a stable due schedule to downstream AP without requiring AP to re-interpret supplier contract language.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createPurchasePaymentTerm
+    Active --> Inactive: deactivatePurchasePaymentTerm
+    Inactive --> Active: activatePurchasePaymentTerm
+    Active --> Active: updatePurchasePaymentTerm
+    Inactive --> Inactive: updatePurchasePaymentTerm
+```
+
+### Command Definitions
+
+- [createPurchasePaymentTerm](../commands/CreatePurchasePaymentTerm.md) - Create a new active supplier payment term with at least one schedule line
+- [updatePurchasePaymentTerm](../commands/UpdatePurchasePaymentTerm.md) - Update the definition of an existing payment term without changing historical snapshots
+- [activatePurchasePaymentTerm](../commands/ActivatePurchasePaymentTerm.md) - Re-enable a deactivated payment term for new procurement documents
+- [deactivatePurchasePaymentTerm](../commands/DeactivatePurchasePaymentTerm.md) - Prevent a payment term from being assigned to new procurement documents
+
+### Query Definitions
+
+- [getPurchasePaymentTerm](../queries/GetPurchasePaymentTerm.md) - Retrieve a payment term and all of its schedule lines
+- [calculatePurchaseBillDueSchedule](../queries/CalculatePurchaseBillDueSchedule.md) - Convert a payment term plus bill inputs into payable installments and discount windows
+
+### Models
+
+- PurchasePaymentTerm
+- PurchasePaymentTermLine
+
+### Invariants
+
+- Every payment term has at least one schedule line
+- Percentage-based installment schedules must total exactly 100 percent before rounding
+- Schedule lines must not contain negative percentage values or negative fixed amounts
+- Early-payment discount dates must occur on or before the final due date generated by the term
+- If a term offers discounting, it must explicitly record whether discount calculation uses `GROSS_AMOUNT` or `NET_AMOUNT`
+- Installment rounding residual is absorbed by the final generated bill schedule line so total scheduled amount always equals the bill amount in transaction currency
+- Inactive payment terms remain valid for historical purchase order and purchase bill snapshots but cannot be assigned to new drafts
+- Exchange-rate conversion is out of scope for payment-term calculation; schedules are computed entirely in the bill transaction currency
+
+### Relationships
+
+- **Has Many PurchasePaymentTermLines**: Each term contains one or more schedule lines that define due-date and discount behavior
+- **Referenced By SupplierProfile**: A [SupplierProfile](./SupplierProfile.md) may point to one default payment term
+- **Snapshotted By PurchaseOrder**: A [PurchaseOrder](./PurchaseOrder.md) stores the chosen term as an immutable commercial snapshot
+- **Snapshotted By PurchaseBill**: A [PurchaseBill](./PurchaseBill.md) carries the term snapshot forward into downstream payable readiness

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

@@ -0,0 +1,53 @@
+# PurchasePriceList
+
+## Description
+
+PurchasePriceList groups the supplier-specific purchasing conditions that buyers can reuse across many orders. It defines the commercial container for one supplier in one company, while the actual unit prices, validity windows, and quantity breaks live on child purchase price rules.
+
+Separating the list from the rules lets procurement retire an entire negotiated contract or reactivate it later without rewriting historical purchase-order snapshots.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createPurchasePriceList
+    Active --> Inactive: deactivatePurchasePriceList
+    Inactive --> Active: activatePurchasePriceList
+    Active --> Active: updatePurchasePriceList
+    Inactive --> Inactive: updatePurchasePriceList
+```
+
+### Command Definitions
+
+- [createPurchasePriceList](../commands/CreatePurchasePriceList.md) - Create a new active supplier price list container
+- [updatePurchasePriceList](../commands/UpdatePurchasePriceList.md) - Update descriptive or prioritization fields of an existing price list
+- [activatePurchasePriceList](../commands/ActivatePurchasePriceList.md) - Re-enable a retired supplier contract for new price resolution
+- [deactivatePurchasePriceList](../commands/DeactivatePurchasePriceList.md) - Prevent a price list from participating in future rule resolution
+
+### Query Definitions
+
+- [getPurchasePriceList](../queries/GetPurchasePriceList.md) - Retrieve a price list with its embedded rules
+- [calculatePurchasePrice](../queries/CalculatePurchasePrice.md) - Resolve the best matching active purchase price rule for a draft order line
+
+### Models
+
+- PurchasePriceList
+
+### Invariants
+
+- Every price list belongs to exactly one company and one supplier
+- Only active price lists can participate in automatic purchase price resolution
+- Deactivating a price list does not change purchase orders that already snapshotted one of its rules
+- Price-list priority must be deterministic within one supplier and company so rule resolution can break ties consistently
+
+### Relationships
+
+- **Belongs To BusinessPartner**: Each list targets one supplier [BusinessPartner](../../../business-partner/docs/models/BusinessPartner.md)
+- **Has Many PurchasePriceRules**: A price list contains one or more [PurchasePriceRule](./PurchasePriceRule.md) records
+- **Referenced By PurchaseOrder**: Draft [PurchaseOrder](./PurchaseOrder.md) lines may default from rules owned by the list before snapshotting the final agreed price

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

@@ -0,0 +1,58 @@
+# PurchasePriceRule
+
+## Description
+
+PurchasePriceRule defines the exact purchasing condition used to price a draft purchase-order line. A rule can target an item, purchasing unit of measure, transaction currency, validity window, minimum quantity break, and explicit priority, allowing procurement to model annual contracts, temporary promotions, and tiered supplier pricing.
+
+The rule lives as an independently managed record because procurement needs to retire, reactivate, or update individual supplier conditions without changing the enclosing contract container.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Active: createPurchasePriceRule
+    Active --> Inactive: deactivatePurchasePriceRule
+    Inactive --> Active: activatePurchasePriceRule
+    Active --> Active: updatePurchasePriceRule
+    Inactive --> Inactive: updatePurchasePriceRule
+```
+
+### Command Definitions
+
+- [createPurchasePriceRule](../commands/CreatePurchasePriceRule.md) - Add a new active supplier purchase price rule to a list
+- [updatePurchasePriceRule](../commands/UpdatePurchasePriceRule.md) - Update the condition fields of a price rule without changing historical order snapshots
+- [activatePurchasePriceRule](../commands/ActivatePurchasePriceRule.md) - Re-enable a retired rule for future price resolution
+- [deactivatePurchasePriceRule](../commands/DeactivatePurchasePriceRule.md) - Stop a rule from being selected for new draft orders
+
+### Query Definitions
+
+- [getPurchasePriceList](../queries/GetPurchasePriceList.md) - Retrieve rules through their parent price list
+- [calculatePurchasePrice](../queries/CalculatePurchasePrice.md) - Apply rule precedence and quantity logic to a draft order line
+
+### Models
+
+- PurchasePriceRule
+
+### Invariants
+
+- Unit price must be strictly positive
+- Minimum quantity must be zero or greater
+- Effective end date, when provided, must be on or after the effective start date
+- Operational use requires the referenced item, currency, and purchase unit to exist and remain active
+- Rules with indistinguishable precedence for the same supplier, item, date, UoM, currency, and quantity context are invalid because price resolution must always choose a single winner
+- Multi-currency price conversion is out of scope inside purchase pricing; rules are matched only when the requested transaction currency equals the rule currency
+- Purchase orders snapshot the applied rule reference and unit price so later edits or deactivation never rewrite historical commercial terms
+
+### Relationships
+
+- **Belongs To PurchasePriceList**: Each rule is owned by one [PurchasePriceList](./PurchasePriceList.md)
+- **References Item**: The rule prices one [Item](../../../item-management/docs/models/Item.md) or another explicitly documented purchasing scope
+- **References Currency**: The rule price is denominated in one [Currency](../../../primitives/docs/models/Currency.md)
+- **References Unit**: The rule is keyed to one purchasing [Unit](../../../primitives/docs/models/Unit.md); quantity comparison may require [convertQuantity](../../../primitives/docs/queries/ConvertQuantity.md)
+- **Snapshotted By PurchaseOrderLine**: The final agreed price and matched rule reference are frozen onto [PurchaseOrder](./PurchaseOrder.md) lines

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

@@ -0,0 +1,37 @@
+# SupplierProfile
+
+## Description
+
+SupplierProfile is the purchase-owned extension of a supplier partner inside one company. It captures procurement defaults that are not part of general business-partner master data, starting with the default purchase payment term used when a new draft purchase order is created for that supplier.
+
+This model resolves ownership ambiguity between purchase and business-partner: business-partner owns the partner identity and role classification, while purchase owns supplier-facing procurement defaults keyed by `companyId + supplierPartnerId`.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [setSupplierDefaultPurchasePaymentTerm](../commands/SetSupplierDefaultPurchasePaymentTerm.md) - Create or update the supplier procurement profile and assign its default payment term
+
+### Query Definitions
+
+- [getSupplierProfile](../queries/GetSupplierProfile.md) - Retrieve the company-scoped supplier procurement profile with its default payment term
+
+### Models
+
+- SupplierProfile
+
+### Invariants
+
+- A supplier has at most one purchase profile per company
+- A supplier profile can exist only for a partner that has the `SUPPLIER` role
+- A default purchase payment term, when present, must belong to the same company as the supplier profile
+- A deactivated purchase payment term cannot remain the default for new draft purchase orders until it is replaced or cleared
+
+### Relationships
+
+- **Belongs To BusinessPartner**: Each supplier profile extends one [BusinessPartner](../../../business-partner/docs/models/BusinessPartner.md) record used as the supplier reference
+- **References PurchasePaymentTerm**: The profile may point to one default [PurchasePaymentTerm](./PurchasePaymentTerm.md) for draft order defaulting

package/src/modules/purchase/docs/queries/CalculatePurchaseBillDueSchedule.md

@@ -0,0 +1,47 @@
+# CalculatePurchaseBillDueSchedule
+
+## Overview
+
+CalculatePurchaseBillDueSchedule converts a purchase payment term plus bill inputs into one or more payable due-schedule lines, including early-payment discount windows when configured.
+
+## Business Rules
+
+- Accepts a payment-term snapshot or a payment-term id plus bill date and bill amount inputs
+- Installment schedules can mix percentage-based and fixed-amount lines as documented by the term
+- End-of-month logic is calculated from calendar month boundaries, not from a simple day offset
+- Any rounding residual is assigned to the final due-schedule line so the total equals the bill amount in transaction currency
+- Discount calculations explicitly honor the term's `GROSS_AMOUNT` or `NET_AMOUNT` discount base
+- Exchange-rate conversion is out of scope; all results stay in the bill transaction currency
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive bill date, amount, and payment term] --> B{Payment term available?}
+    B -->|No| C[Return PAYMENT_TERM_NOT_FOUND]
+    B -->|Yes| D[Expand term schedule lines]
+    D --> E[Calculate due dates using net-day, fixed-day, or end-of-month rules]
+    E --> F[Calculate installment amounts and assign residual to final line]
+    F --> G[Attach discount metadata where configured]
+    G --> H[Return due-schedule lines]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Referenced purchase payment term does not exist
+- **INVALID_PAYMENT_TERM_CONFIGURATION**: Payment term schedule is incomplete or internally inconsistent
+- **INVALID_BILL_AMOUNT**: Bill amount input is negative or incompatible with the schedule type
+
+## Test Cases
+
+- calculates a single due date for net-30 terms
+- calculates discount window and final due date for 2/10 net 30
+- calculates multiple due-schedule lines for installment terms
+- applies end-of-month logic correctly
+- assigns rounding residual to the final schedule line
+- returns error when payment term does not exist
+- returns error when payment term configuration is invalid