@tailor-platform/erp-kit 0.4.1 → 0.5.1

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

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

@@ -0,0 +1,53 @@
+# CalculatePurchasePrice
+
+## Overview
+
+CalculatePurchasePrice resolves the best matching supplier purchase price rule for a draft purchase-order line and returns the suggested unit price together with the matched rule reference.
+
+## Business Rules
+
+- Inputs include `companyId`, `supplierId`, `itemId`, ordered quantity, purchase unit, transaction currency, and order date
+- Only active price lists and active price rules participate in matching
+- Rule precedence is deterministic across supplier, price-list priority, item scope, purchase unit, minimum quantity break, effective date, and explicit rule priority
+- When purchase unit differs from the rule comparison unit, quantity comparison uses shared unit conversion
+- Currency conversion is out of scope; rules match only when the requested currency equals the rule currency
+- Returns null suggestion when no active rule matches and manual pricing is expected
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive supplier, item, qty, unit, currency, date] --> B{Item and units valid?}
+    B -->|No| C[Return reference error]
+    B -->|Yes| D[Load active lists and active rules for supplier/company]
+    D --> E[Normalize quantity for rule comparison]
+    E --> F[Filter rules by item, UoM, currency, date, and min qty]
+    F --> G{Rule found?}
+    G -->|No| H[Return null suggestion]
+    G -->|Yes| I[Pick highest precedence rule]
+    I --> J[Return suggested unit price and matched rule reference]
+```
+
+## External Dependencies
+
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate item existence and active status
+- [primitives::ConvertQuantity](../../../primitives/docs/queries/ConvertQuantity.md) - Compare quantity breaks across compatible units of measure
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is inactive
+- **UNIT_NOT_FOUND**: Referenced purchase unit does not exist
+- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
+- **INCOMPATIBLE_UNITS**: Quantity-break comparison requires units that do not share a conversion path
+- **NO_MATCHING_PRICE_RULE**: No active rule matches; caller receives null suggestion
+
+## Test Cases
+
+- returns the best matching rule for a valid supplier item context
+- picks the higher quantity-break rule when ordered quantity qualifies
+- ignores inactive price lists and inactive rules
+- returns null when no active rule matches
+- returns error when item does not exist
+- returns error when item is inactive
+- returns error when units are incompatible for quantity-break comparison

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

@@ -0,0 +1,36 @@
+# GetGoodsReceipt
+
+## Overview
+
+GetGoodsReceipt retrieves a goods receipt with its receipt lines, receipt date, posting status, and inbound handoff metadata.
+
+## Business Rules
+
+- Lookup key is goods-receipt id
+- Returns receipts in any status so draft, cancelled, and posted receipts remain reviewable
+- Response includes referenced purchase-order and purchase-order-line links needed for audit and 3-way matching
+- Returns null when the goods receipt does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive goodsReceiptId] --> B[Select GoodsReceipt and receipt lines by id]
+    B --> C{Receipt found?}
+    C -->|Yes| D[Return goods receipt with lines and handoff metadata]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **GOODS_RECEIPT_NOT_FOUND**: No goods receipt exists for the given id; caller receives null
+
+## Test Cases
+
+- returns goods receipt when found
+- returns receipt lines and handoff metadata with the receipt
+- returns null when goods receipt does not exist

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

@@ -0,0 +1,41 @@
+# GetPurchaseBill
+
+## Overview
+
+GetPurchaseBill retrieves a supplier bill together with its matching outcome, payable schedule snapshot, tax snapshot, and line-level purchase references.
+
+## Business Rules
+
+- Accepts lookup by `{ id }` or by `{ companyId, supplierId, invoiceNumber }`
+- Returns bills in any status so blocked, matched, and cancelled evidence remains available for audit
+- Response includes matching mode, variance reason, and due-schedule lines when available
+- Returns null when no purchase bill matches the lookup
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup input] --> B{Lookup by id or supplier invoice identity?}
+    B -->|id| C[Select PurchaseBill by id]
+    B -->|invoice identity| D[Select PurchaseBill by company + supplier + invoice number]
+    C --> E{Bill found?}
+    D --> E
+    E -->|Yes| F[Load bill lines, tax snapshot, and due schedule]
+    E -->|No| G[Return null]
+    F --> H[Return purchase bill]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: No purchase bill matches the given lookup; caller receives null
+
+## Test Cases
+
+- returns purchase bill when found by id
+- returns purchase bill when found by supplier invoice identity
+- returns matching outcome and due schedule with the bill
+- returns null when purchase bill is not found

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

@@ -0,0 +1,42 @@
+# GetPurchaseOrder
+
+## Overview
+
+GetPurchaseOrder retrieves a single purchase order with its lines, frozen commercial snapshots, and fulfillment progress.
+
+## Business Rules
+
+- Accepts lookup by `{ id }` or by `{ companyId, externalSupplierOrderReference }`
+- Returns purchase orders in any status so cancelled and closed documents remain auditable
+- Response includes line-level remaining quantity to receive and remaining quantity to bill
+- Response includes payment-term snapshot and matched price-rule references when present
+- Returns null when no purchase order matches the lookup
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive lookup input] --> B{Lookup by id or external reference?}
+    B -->|id| C[Select PurchaseOrder by id]
+    B -->|external reference| D[Select PurchaseOrder by company + external reference]
+    C --> E{Order found?}
+    D --> E
+    E -->|Yes| F[Load lines, snapshots, and fulfillment totals]
+    E -->|No| G[Return null]
+    F --> H[Return purchase order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: No purchase order matches the given lookup; caller receives null
+
+## Test Cases
+
+- returns purchase order when found by id
+- returns purchase order when found by company and external supplier order reference
+- returns lines and fulfillment totals with the order
+- returns null when purchase order is not found

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

@@ -0,0 +1,36 @@
+# GetPurchasePaymentTerm
+
+## Overview
+
+GetPurchasePaymentTerm retrieves one purchase payment term and all of its schedule lines by identifier.
+
+## Business Rules
+
+- Lookup key is payment-term id
+- Returns payment terms in any status so historical references remain readable
+- Response includes all schedule lines needed to compute installments and discount windows
+- Returns null when the payment term does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive paymentTermId] --> B[Select PurchasePaymentTerm and schedule lines by id]
+    B --> C{Term found?}
+    C -->|Yes| D[Return payment term with lines]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: No purchase payment term exists for the given id; caller receives null
+
+## Test Cases
+
+- returns purchase payment term when found
+- returns schedule lines with the term
+- returns null when purchase payment term does not exist

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

@@ -0,0 +1,36 @@
+# GetPurchasePriceList
+
+## Overview
+
+GetPurchasePriceList retrieves a supplier purchase price list together with all of its purchase price rules.
+
+## Business Rules
+
+- Lookup key is price-list id
+- Returns price lists in any status so historical supplier contracts remain inspectable
+- Response includes embedded purchase price rules and their current statuses
+- Returns null when the price list does not exist
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive priceListId] --> B[Select PurchasePriceList and rules by id]
+    B --> C{List found?}
+    C -->|Yes| D[Return price list with rules]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: No purchase price list exists for the given id; caller receives null
+
+## Test Cases
+
+- returns purchase price list when found
+- returns embedded purchase price rules with the list
+- returns null when purchase price list does not exist

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

@@ -0,0 +1,36 @@
+# GetSupplierProfile
+
+## Overview
+
+GetSupplierProfile retrieves the purchase-owned supplier procurement profile for one company and supplier, including the default purchase payment term if one is configured.
+
+## Business Rules
+
+- Input lookup is `companyId + supplierId`
+- Returns the supplier profile for any persisted state because the model is standard, not lifecycle-driven
+- Returns the embedded default payment term reference when configured
+- Returns null when no purchase profile exists for the supplier in the company
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive companyId + supplierId] --> B[Select SupplierProfile by company and supplier]
+    B --> C{Profile found?}
+    C -->|Yes| D[Return supplier profile]
+    C -->|No| E[Return null]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **SUPPLIER_PROFILE_NOT_FOUND**: No supplier profile exists for the given company and supplier; caller receives null
+
+## Test Cases
+
+- returns supplier profile when found
+- returns default payment term reference when configured
+- returns null when supplier profile does not exist