@tailor-platform/erp-kit 0.4.1 → 0.5.0

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

@@ -0,0 +1,47 @@
+# ActivatePurchasePriceRule
+
+## Overview
+
+ActivatePurchasePriceRule re-enables a supplier purchase price rule so it can participate in future price resolution again.
+
+## Business Rules
+
+- Target rule must exist
+- Activating an already active rule returns success without changing state
+- Reactivated rules still require valid reference data and a non-conflicting precedence context
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive activate request] --> B{Rule exists?}
+    B -->|No| C[Return PRICE_RULE_NOT_FOUND]
+    B -->|Yes| D{Already active?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F{Rule still valid for activation?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Set status to ACTIVE]
+    H --> I[Return activated rule]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_RULE_NOT_FOUND**: Target price rule does not exist
+- **DUPLICATE_RULE_PRECEDENCE**: Another active rule already owns the same precedence context
+- **INVALID_RULE_CONFIGURATION**: Rule references or dates are no longer valid for activation
+
+## Test Cases
+
+- activates an inactive price rule
+- returns success when the rule is already active
+- returns error when rule does not exist
+- returns error when activation would conflict with another active rule
+- returns error when rule configuration is invalid at activation time
+- returns error when the referenced item no longer exists
+- returns error when the referenced item is inactive
+- returns error when the referenced currency no longer exists
+- returns error when the referenced unit no longer exists

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

@@ -0,0 +1,55 @@
+# ApprovePurchaseOrder
+
+## Overview
+
+ApprovePurchaseOrder moves a submitted purchase order into `ORDERED` status, freezes the commercial agreement, and records the order as ready for supplier execution.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `SUBMITTED` status can be approved
+- Supplier must still be active and classified as a supplier
+- Referenced items must still be active for operational execution
+- Approval freezes the ordered unit prices, matched price-rule references, and payment-term snapshot
+- Approving an order does not create stock movement or billing records
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive approve request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is SUBMITTED?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_SUBMITTED]
+    D -->|Yes| F{Supplier and items still active?}
+    F -->|No| G[Return execution reference error]
+    F -->|Yes| H[Freeze payment term and line price snapshots]
+    H --> I[Set status to ORDERED]
+    I --> J[Return approved order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier status and role before ordering
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Re-validate item status before ordering
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_SUBMITTED**: Purchase order is not in `SUBMITTED` status
+- **SUPPLIER_NOT_ACTIVE**: Supplier is inactive at approval time
+- **PARTNER_NOT_SUPPLIER**: Supplier no longer carries the `SUPPLIER` role
+- **ITEM_NOT_ACTIVE**: One or more referenced items are inactive
+- **MISSING_COMMERCIAL_SNAPSHOT**: Required payment-term or price snapshot data is missing
+
+## Test Cases
+
+- approves a valid submitted purchase order
+- freezes payment-term snapshot at approval time
+- freezes ordered line prices and matched rule references at approval time
+- returns error when purchase order does not exist
+- returns error when purchase order is not submitted
+- returns error when supplier is inactive
+- returns error when an item is inactive
+- returns error when supplier is no longer classified as a supplier
+- returns error when approval cannot reconstruct the commercial snapshot

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

@@ -0,0 +1,39 @@
+# CancelGoodsReceipt
+
+## Overview
+
+CancelGoodsReceipt abandons a draft goods receipt before it affects purchase-order fulfillment or inventory execution.
+
+## Business Rules
+
+- Target goods receipt must exist
+- Only receipts in `DRAFT` status can be cancelled
+- Cancelling a draft receipt does not change purchase-order received quantity
+- Posted receipts cannot be cancelled; they require a future compensating correction workflow
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Goods receipt exists?}
+    B -->|No| C[Return GOODS_RECEIPT_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return GOODS_RECEIPT_NOT_DRAFT]
+    D -->|Yes| F[Set status to CANCELLED]
+    F --> G[Return cancelled receipt]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **GOODS_RECEIPT_NOT_FOUND**: Target goods receipt does not exist
+- **GOODS_RECEIPT_NOT_DRAFT**: Goods receipt is not in `DRAFT` status
+
+## Test Cases
+
+- cancels a draft goods receipt
+- returns error when goods receipt does not exist
+- returns error when goods receipt is already posted

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

@@ -0,0 +1,49 @@
+# CancelPurchaseBill
+
+## Overview
+
+CancelPurchaseBill voids a draft, blocked, or matched supplier bill while the bill is still owned by purchase and has not yet been accepted by downstream AP or accounting.
+
+## Business Rules
+
+- Target purchase bill must exist
+- Only bills in `DRAFT`, `BLOCKED`, or `MATCHED` can be cancelled
+- Cancellation is forbidden after downstream AP or accounting accepts the bill-ready handoff
+- Cancellation preserves invoice identity, line references, and variance evidence for future dispute or credit-note workflows
+- Cancelling a matched bill reverses the purchase-order billed quantity that was previously accumulated from that bill
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Purchase bill exists?}
+    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
+    B -->|Yes| D{Status cancellable?}
+    D -->|No| E[Return PURCHASE_BILL_NOT_CANCELLABLE]
+    D -->|Yes| F{Downstream handoff already accepted?}
+    F -->|Yes| G[Return DOWNSTREAM_HANDOFF_ACCEPTED]
+    F -->|No| H[Preserve evidence and set CANCELLED]
+    H --> I[Adjust PO billed quantity if previously matched]
+    I --> J[Return cancelled bill]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
+- **PURCHASE_BILL_NOT_CANCELLABLE**: Purchase bill status does not allow cancellation
+- **DOWNSTREAM_HANDOFF_ACCEPTED**: Downstream AP or accounting already accepted the bill-ready handoff
+
+## Test Cases
+
+- cancels a draft purchase bill
+- cancels a blocked purchase bill
+- cancels a matched purchase bill before downstream acceptance
+- preserves variance evidence when a blocked bill is cancelled
+- reverses purchase-order billed quantity when a matched bill is cancelled
+- returns error when purchase bill does not exist
+- returns error when purchase bill status does not allow cancellation
+- returns error when downstream handoff has already been accepted

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

@@ -0,0 +1,47 @@
+# CancelPurchaseOrder
+
+## Overview
+
+CancelPurchaseOrder stops a purchase order before fulfillment becomes irreversible and moves it into `CANCELLED` status.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `DRAFT`, `SUBMITTED`, or `ORDERED` can be cancelled
+- Cancellation is forbidden once a posted goods receipt exists
+- Cancellation is forbidden once a matched supplier bill exists
+- Cancelling preserves the original order for audit and traceability
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive cancel request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status cancellable?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_CANCELLABLE]
+    D -->|Yes| F{Posted receipt or matched bill exists?}
+    F -->|Yes| G[Return PURCHASE_ORDER_ALREADY_FULFILLED]
+    F -->|No| H[Set status to CANCELLED]
+    H --> I[Return cancelled order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_CANCELLABLE**: Purchase order status does not allow cancellation
+- **PURCHASE_ORDER_ALREADY_FULFILLED**: Posted receipts or matched bills already exist against the order
+
+## Test Cases
+
+- cancels a draft purchase order
+- cancels a submitted purchase order
+- cancels an ordered purchase order with no receipts or matched bills
+- returns error when purchase order does not exist
+- returns error when purchase order status does not allow cancellation
+- returns error when a posted receipt already exists
+- returns error when a matched bill already exists

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

@@ -0,0 +1,49 @@
+# ClosePurchaseOrder
+
+## Overview
+
+ClosePurchaseOrder finalizes a partially fulfilled or fully fulfilled purchase order and prevents further receipt or billing activity on the remaining open quantity.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `PARTIALLY_RECEIVED`, `RECEIVED`, `PARTIALLY_BILLED`, or `BILLED` can be closed
+- Remaining open quantity must already be fully received, fully billed, or explicitly written off with a close reason
+- Closing preserves the original ordered, received, and billed quantities for audit
+- Closed orders reject new goods receipts and new purchase bills
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive close request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status closable?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_CLOSABLE]
+    D -->|Yes| F{Open quantity fully resolved or write-off reason provided?}
+    F -->|No| G[Return OPEN_QUANTITY_REMAINS]
+    F -->|Yes| H[Set status to CLOSED]
+    H --> I[Return closed order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_CLOSABLE**: Purchase order status does not allow closure
+- **OPEN_QUANTITY_REMAINS**: Remaining quantity is not fulfilled or explicitly written off
+- **CLOSE_REASON_REQUIRED**: Residual open quantity exists but no write-off reason was provided
+
+## Test Cases
+
+- closes a fully billed purchase order
+- closes a partially received order when remaining quantity is explicitly written off
+- allows closure without write-off when each line is fully received
+- returns error when purchase order does not exist
+- returns error when purchase order status does not allow closure
+- returns error when unresolved open quantity remains
+- returns error when residual quantity exists without a close reason
+- returns OPEN_QUANTITY_REMAINS before requiring a close reason when write-off is not requested

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

@@ -0,0 +1,54 @@
+# CreateGoodsReceipt
+
+## Overview
+
+CreateGoodsReceipt creates a draft goods receipt against one purchase order with one or more targeted purchase-order lines.
+
+## Business Rules
+
+- Purchase order must exist and belong to the same company as the receipt
+- Purchase order must not be cancelled or closed
+- At least one receipt line is required
+- Each receipt line must reference a valid purchase-order line with open quantity
+- Each receipt line must record a received quantity greater than zero
+- Goods receipts are created in `DRAFT` status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Purchase order exists and is receivable?}
+    B -->|No| C[Return purchase order error]
+    B -->|Yes| D{At least one line?}
+    D -->|No| E[Return EMPTY_RECEIPT_LINES]
+    D -->|Yes| F{Each line references open PO quantity and qty > 0?}
+    F -->|No| G[Return line validation error]
+    F -->|Yes| H[Insert goods receipt in DRAFT]
+    H --> I[Return created receipt]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
+- **PURCHASE_ORDER_NOT_RECEIVABLE**: Purchase order is cancelled, closed, or otherwise unavailable for receipt
+- **EMPTY_RECEIPT_LINES**: No goods-receipt lines were provided
+- **PURCHASE_ORDER_LINE_NOT_FOUND**: Referenced purchase-order line does not exist
+- **NO_OPEN_RECEIPT_QUANTITY**: Purchase-order line has no remaining open quantity to receive
+- **INVALID_RECEIVED_QUANTITY**: Received quantity is zero or negative
+- **COMPANY_SCOPE_MISMATCH**: Goods receipt company does not match the purchase order company
+
+## Test Cases
+
+- creates a draft goods receipt against an ordered purchase order
+- creates a draft goods receipt against a partially received purchase order
+- returns error when purchase order does not exist
+- returns error when purchase order is cancelled or closed
+- returns error when no receipt lines are provided
+- returns error when a purchase-order line does not exist
+- returns error when a receipt line has no open quantity
+- returns error when received quantity is zero or negative
+- returns error when goods receipt company does not match the purchase order company

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

@@ -0,0 +1,59 @@
+# CreatePurchaseBill
+
+## Overview
+
+CreatePurchaseBill creates a supplier bill in `DRAFT` status with invoice identity, purchase references, line quantities, tax snapshot inputs, and the payment-term snapshot that will later drive payable scheduling.
+
+## Business Rules
+
+- Company, supplier, invoice number, invoice date, and at least one line are required
+- Duplicate supplier invoice numbers are rejected within the same supplier and company
+- Each line must reference a valid purchase-order line and record billed quantity greater than zero
+- Supplier bill cannot reference a cancelled purchase order
+- Assigned payment term snapshot and supplier tax identification must be captured at create time
+- New purchase bills are created in `DRAFT` status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Supplier and company valid?}
+    B -->|No| C[Return supplier or company error]
+    B -->|Yes| D{Duplicate invoice number?}
+    D -->|Yes| E[Return DUPLICATE_SUPPLIER_INVOICE_NUMBER]
+    D -->|No| F{At least one valid bill line?}
+    F -->|No| G[Return line validation error]
+    F -->|Yes| H[Snapshot payment term and supplier tax identity]
+    H --> I[Insert purchase bill in DRAFT]
+    I --> J[Return created bill]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate supplier identity and status
+- [business-partner::ListPartnerIdentificationsByPartner](../../../business-partner/docs/queries/ListPartnerIdentificationsByPartner.md) - Source supplier tax identification snapshot
+
+## Error Scenarios
+
+- **SUPPLIER_NOT_FOUND**: Referenced supplier does not exist
+- **DUPLICATE_SUPPLIER_INVOICE_NUMBER**: Supplier invoice number already exists in the same company and supplier scope
+- **EMPTY_BILL_LINES**: No purchase-bill lines were provided
+- **PURCHASE_ORDER_LINE_NOT_FOUND**: Referenced purchase-order line does not exist
+- **INVALID_BILLED_QUANTITY**: Billed quantity is zero or negative
+- **PURCHASE_ORDER_CANCELLED**: Referenced purchase order is cancelled
+- **PAYMENT_TERM_SNAPSHOT_MISSING**: No valid payment-term snapshot is available for the bill
+- **SUPPLIER_TAX_IDENTIFICATION_MISSING**: Required supplier tax identification cannot be snapshotted
+
+## Test Cases
+
+- creates a draft purchase bill with valid line references
+- snapshots payment-term data at create time
+- snapshots supplier tax identification at create time
+- returns error when supplier does not exist
+- returns error when invoice number is duplicated
+- returns error when no bill lines are provided
+- returns error when a purchase-order line does not exist
+- returns error when billed quantity is zero or negative
+- returns error when referenced purchase order is cancelled
+- returns error when no payment-term snapshot is available
+- returns error when supplier tax identification cannot be snapshotted

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

@@ -0,0 +1,66 @@
+# CreatePurchaseOrder
+
+## Overview
+
+CreatePurchaseOrder creates a new purchase order in `DRAFT` status with supplier, company, receiving context, payment-term snapshot seed, and one or more commercial lines.
+
+## Business Rules
+
+- Company, supplier, and at least one line are required
+- Supplier must exist, be active, and carry the `SUPPLIER` role
+- Each line must reference an active item, have quantity greater than zero, and have a non-negative unit price
+- Lines that require physical receipt must identify a valid receiving site
+- If a default purchase payment term is inherited from the supplier profile, it must be active at creation time
+- Order is always created in `DRAFT` status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Supplier valid and active?}
+    B -->|No| C[Return supplier error]
+    B -->|Yes| D{At least one line?}
+    D -->|No| E[Return EMPTY_PURCHASE_ORDER_LINES]
+    D -->|Yes| F{Validate each line item, quantity, price, site}
+    F -->|No| G[Return line validation error]
+    F -->|Yes| H{Resolve default payment term if needed}
+    H -->|Invalid| I[Return payment term error]
+    H -->|Valid| J[Insert order and lines in DRAFT]
+    J --> K[Return created order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate supplier identity, status, and supplier role
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Validate each referenced item and item status
+- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Validate receiving site references
+
+## Error Scenarios
+
+- **SUPPLIER_NOT_FOUND**: Referenced supplier does not exist
+- **SUPPLIER_NOT_ACTIVE**: Referenced supplier is inactive
+- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the `SUPPLIER` role
+- **EMPTY_PURCHASE_ORDER_LINES**: No purchase-order lines were provided
+- **ITEM_NOT_FOUND**: Referenced item does not exist
+- **ITEM_NOT_ACTIVE**: Referenced item is inactive
+- **INVALID_QUANTITY**: Ordered quantity is zero or negative
+- **INVALID_UNIT_PRICE**: Unit price is negative
+- **RECEIVING_SITE_NOT_FOUND**: Referenced receiving site does not exist
+- **RECEIVING_SITE_REQUIRED**: A physical-receipt line has no receiving site
+- **PAYMENT_TERM_INACTIVE**: Inherited default payment term is inactive
+
+## Test Cases
+
+- creates a draft purchase order with valid supplier and lines
+- inherits default payment term from supplier profile when present
+- returns error when supplier does not exist
+- returns error when supplier is inactive
+- returns error when partner is not a supplier
+- returns error when no lines are provided
+- returns error when an item does not exist
+- returns error when an item is inactive
+- returns error when quantity is zero or negative
+- returns error when unit price is negative
+- returns error when receiving site is missing for a physical line
+- returns error when receiving site does not exist
+- returns error when inherited payment term is inactive

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

@@ -0,0 +1,52 @@
+# CreatePurchasePaymentTerm
+
+## Overview
+
+CreatePurchasePaymentTerm creates a new company-scoped supplier payment term in `ACTIVE` status with one or more schedule lines and optional early-payment discount metadata.
+
+## Business Rules
+
+- `companyId`, name, and at least one schedule line are required
+- Percentage-based installment lines must total 100 percent
+- Schedule lines must not contain negative percentages or negative fixed amounts
+- Discount cutoff must occur on or before the generated final due date
+- Discount base must be explicitly `GROSS_AMOUNT` or `NET_AMOUNT` when discounting is enabled
+- New payment terms are created in `ACTIVE` status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Company exists?}
+    B -->|No| C[Return company error]
+    B -->|Yes| D{At least one schedule line?}
+    D -->|No| E[Return EMPTY_SCHEDULE]
+    D -->|Yes| F{Lines valid and percentages balanced?}
+    F -->|No| G[Return schedule validation error]
+    F -->|Yes| H{Discount metadata valid?}
+    H -->|No| I[Return discount validation error]
+    H -->|Yes| J[Insert payment term and lines in ACTIVE]
+    J --> K[Return created term]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope for the new payment term
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist
+- **EMPTY_SCHEDULE**: No payment term schedule lines were provided
+- **INVALID_INSTALLMENT_TOTAL**: Percentage-based installment lines do not total 100 percent
+- **INVALID_SCHEDULE_LINE**: A schedule line contains a negative percentage or negative fixed amount
+- **INVALID_DISCOUNT_CONFIGURATION**: Discount metadata is incomplete or inconsistent with the final due date
+
+## Test Cases
+
+- creates an active payment term with one schedule line
+- creates an installment payment term when percentages total 100 percent
+- returns error when company does not exist
+- returns error when no schedule lines are provided
+- returns error when installment percentages do not total 100 percent
+- returns error when a schedule line contains a negative amount or percentage
+- returns error when discount cutoff is after the final due date

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

@@ -0,0 +1,48 @@
+# CreatePurchasePriceList
+
+## Overview
+
+CreatePurchasePriceList creates a new active supplier-specific price list container for one company. The list provides the parent contract context for later purchase price rules.
+
+## Business Rules
+
+- `companyId`, `supplierId`, and a list name or code are required
+- Supplier must exist, be active, and carry the `SUPPLIER` role
+- List priority must be valid within the supplier and company scope
+- New price lists are created in `ACTIVE` status
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Company exists?}
+    B -->|No| C[Return company error]
+    B -->|Yes| D{Supplier exists, active, SUPPLIER?}
+    D -->|No| E[Return supplier error]
+    D -->|Yes| F{Priority valid?}
+    F -->|No| G[Return priority error]
+    F -->|Yes| H[Insert price list in ACTIVE]
+    H --> I[Return created list]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate supplier identity and role classification
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Validate company scope
+
+## Error Scenarios
+
+- **COMPANY_NOT_FOUND**: Referenced company does not exist
+- **SUPPLIER_NOT_FOUND**: Referenced supplier does not exist
+- **SUPPLIER_NOT_ACTIVE**: Referenced supplier is inactive
+- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the `SUPPLIER` role
+- **INVALID_LIST_PRIORITY**: List priority conflicts with deterministic supplier ordering rules
+
+## Test Cases
+
+- creates an active price list for an active supplier
+- returns error when company does not exist
+- returns error when supplier does not exist
+- returns error when supplier is inactive
+- returns error when partner is not a supplier
+- returns error when list priority is invalid

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

@@ -0,0 +1,62 @@
+# CreatePurchasePriceRule
+
+## Overview
+
+CreatePurchasePriceRule adds a new active supplier pricing condition to an existing price list for one item, currency, purchase unit, quantity break, and validity window.
+
+## Business Rules
+
+- Target price list must exist
+- Referenced item must exist and be active
+- Referenced currency and purchase unit must exist
+- Unit price must be greater than zero
+- Minimum quantity must be zero or greater
+- Effective end date cannot be earlier than effective start date
+- A new rule must not duplicate another rule with indistinguishable precedence in the same supplier context
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Price list exists?}
+    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
+    B -->|Yes| D{Item, currency, and unit valid?}
+    D -->|No| E[Return reference error]
+    D -->|Yes| F{Price and dates valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H{Unique precedence?}
+    H -->|No| I[Return DUPLICATE_RULE_PRECEDENCE]
+    H -->|Yes| J[Insert rule in ACTIVE]
+    J --> K[Return created 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_LIST_NOT_FOUND**: Target price list 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
+
+- creates an active purchase price rule with valid references
+- returns error when price list does not exist
+- returns error when item does not exist
+- returns error when item is inactive
+- returns error when currency does not exist
+- returns error when unit does not exist
+- returns error when unit price is not positive
+- returns error when minimum quantity is negative
+- returns error when effective range is invalid
+- returns error when another rule already has the same precedence

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

@@ -0,0 +1,42 @@
+# DeactivatePurchasePaymentTerm
+
+## Overview
+
+DeactivatePurchasePaymentTerm retires a payment term from future draft procurement documents while preserving all historical snapshots already copied onto orders and bills.
+
+## Business Rules
+
+- Target payment term must exist
+- Deactivating an already inactive payment term returns success without changing state
+- A payment term cannot be deactivated while it is still configured as the default on an active supplier profile
+- Historical purchase-order and purchase-bill snapshots remain valid after deactivation
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Payment term exists?}
+    B -->|No| C[Return PAYMENT_TERM_NOT_FOUND]
+    B -->|Yes| D{Already inactive?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F{Used as active supplier default?}
+    F -->|Yes| G[Return PAYMENT_TERM_IN_USE]
+    F -->|No| H[Set status to INACTIVE]
+    H --> I[Return deactivated term]
+```
+
+## External Dependencies
+
+- [getSupplierProfile](../queries/GetSupplierProfile.md) - Check whether the term is still defaulted on any active supplier profile in scope
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Target payment term does not exist
+- **PAYMENT_TERM_IN_USE**: Payment term is still configured as an active supplier default
+
+## Test Cases
+
+- deactivates an active payment term
+- returns success when the payment term is already inactive
+- returns error when payment term does not exist
+- returns error when payment term is still configured as a supplier default