@tailor-platform/erp-kit 0.4.1 → 0.5.0

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

@@ -0,0 +1,39 @@
+# DeactivatePurchasePriceList
+
+## Overview
+
+DeactivatePurchasePriceList retires a supplier price list from future defaulting while preserving all orders that already used one of its rules.
+
+## Business Rules
+
+- Target price list must exist
+- Deactivating an already inactive list returns success without changing state
+- Deactivated lists are ignored by price resolution for new draft orders
+- Historical purchase orders keep their ordered prices and matched rule references
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Price list exists?}
+    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
+    B -->|Yes| D{Already inactive?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F[Set status to INACTIVE]
+    F --> G[Return deactivated list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: Target price list does not exist
+
+## Test Cases
+
+- deactivates an active price list
+- returns success when the list is already inactive
+- preserves historical purchase-order snapshots after deactivation
+- returns error when price list does not exist

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

@@ -0,0 +1,39 @@
+# DeactivatePurchasePriceRule
+
+## Overview
+
+DeactivatePurchasePriceRule retires one supplier purchase pricing condition from future rule resolution while preserving all historical purchase orders that already used it.
+
+## Business Rules
+
+- Target rule must exist
+- Deactivating an already inactive rule returns success without changing state
+- Deactivated rules are ignored by automatic price calculation for new draft orders
+- Historical purchase orders keep their ordered prices and matched rule references
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Rule exists?}
+    B -->|No| C[Return PRICE_RULE_NOT_FOUND]
+    B -->|Yes| D{Already inactive?}
+    D -->|Yes| E[Return success with no-op]
+    D -->|No| F[Set status to INACTIVE]
+    F --> G[Return deactivated rule]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_RULE_NOT_FOUND**: Target price rule does not exist
+
+## Test Cases
+
+- deactivates an active price rule
+- returns success when the rule is already inactive
+- preserves historical purchase-order snapshots after deactivation
+- returns error when rule does not exist

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

@@ -0,0 +1,63 @@
+# MatchPurchaseBill
+
+## Overview
+
+MatchPurchaseBill runs procurement matching on a draft supplier bill. It compares each bill line against the referenced purchase-order line and, when 3-way matching is required, against cumulative posted goods receipts. The bill then becomes `MATCHED` or `BLOCKED`.
+
+## Business Rules
+
+- Target purchase bill must exist
+- Only bills in `DRAFT` status can be matched
+- Matching mode must be explicitly recorded as `TWO_WAY` or `THREE_WAY`
+- 2-way matching compares billed quantity and billed price to the purchase order
+- 3-way matching also requires billed quantity to stay within cumulative posted receipt quantity, subject to configured tolerance
+- Price variance above tolerance results in `BLOCKED` instead of `MATCHED`
+- Matched bills calculate due schedule from the payment-term snapshot and increase purchase-order billed quantity
+- Blocked bills preserve variance reason and comparison basis without emitting downstream AP readiness
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive match request] --> B{Purchase bill exists and is DRAFT?}
+    B -->|No| C[Return not found or invalid status]
+    B -->|Yes| D{Matching mode provided?}
+    D -->|No| E[Return MATCH_MODE_REQUIRED]
+    D -->|Yes| F[Compare each bill line to PO line]
+    F --> G{THREE_WAY?}
+    G -->|Yes| H[Compare billed qty to posted receipts]
+    G -->|No| I[Skip receipt comparison]
+    H --> J{Within quantity and price tolerance?}
+    I --> J
+    J -->|No| K[Record variance evidence and set BLOCKED]
+    J -->|Yes| L[Calculate due schedule and set MATCHED]
+    L --> M[Increase PO billed quantity and prepare bill-ready handoff]
+    K --> N[Return blocked bill]
+    M --> O[Return matched bill]
+```
+
+## External Dependencies
+
+- [getGoodsReceipt](../queries/GetGoodsReceipt.md) - Source cumulative posted receipt evidence for 3-way matching
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
+- **PURCHASE_BILL_NOT_DRAFT**: Purchase bill is not in `DRAFT` status
+- **MATCH_MODE_REQUIRED**: No matching mode was provided
+- **PURCHASE_ORDER_CANCELLED**: Referenced purchase order is cancelled
+- **PAYMENT_SCHEDULE_CALCULATION_FAILED**: Due schedule could not be derived from the payment-term snapshot
+
+## Test Cases
+
+- matches a valid 2-way purchase bill
+- matches a valid 3-way purchase bill when posted receipt quantity is sufficient
+- blocks a bill when 3-way quantity exceeds posted receipt quantity
+- blocks a bill when price variance exceeds tolerance
+- records matching mode on the bill
+- increases purchase-order billed quantity when the bill is matched
+- returns error when purchase bill does not exist
+- returns error when purchase bill is not draft
+- returns error when matching mode is missing
+- returns error when a referenced purchase order is cancelled
+- returns error when payment schedule calculation fails

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

@@ -0,0 +1,61 @@
+# PostGoodsReceipt
+
+## Overview
+
+PostGoodsReceipt validates a draft receipt, updates cumulative received quantities on the referenced purchase-order lines, transitions the purchase order to the correct receiving state, and emits the inbound inventory handoff when required.
+
+## Business Rules
+
+- Target goods receipt must exist
+- Only receipts in `DRAFT` status can be posted
+- Each receipt line must still reference open purchase-order quantity
+- Over-receipt beyond configured tolerance is blocked unless an explicit override path is provided
+- Only posted goods receipts count toward 3-way supplier bill matching
+- Stock-item lines emit the `InboundReceiptHandoff` exactly once; service lines do not require inventory execution
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive post request] --> B{Goods receipt exists and is DRAFT?}
+    B -->|No| C[Return not found or invalid status]
+    B -->|Yes| D{Receipt lines still have open quantity and are within tolerance?}
+    D -->|No| E[Return receipt validation error]
+    D -->|Yes| F[Increase PO line received quantities]
+    F --> G[Set goods receipt to POSTED]
+    G --> H{Stock line present?}
+    H -->|Yes| I[Emit inbound receipt handoff]
+    H -->|No| J[Skip inventory handoff]
+    I --> K[Roll up PO receiving status]
+    J --> K
+    K --> L[Return posted receipt]
+```
+
+## External Dependencies
+
+- [inventory::CreateStockMovement](../../../inventory/docs/commands/CreateStockMovement.md) - Downstream stock execution target for stock-item receipts
+
+## Error Scenarios
+
+- **GOODS_RECEIPT_NOT_FOUND**: Target goods receipt does not exist
+- **GOODS_RECEIPT_NOT_DRAFT**: Goods receipt is not in `DRAFT` status
+- **PURCHASE_ORDER_NOT_RECEIVABLE**: Purchase order is cancelled or closed
+- **NO_OPEN_RECEIPT_QUANTITY**: Purchase-order line has no remaining open quantity to receive
+- **OVER_RECEIPT_TOLERANCE_EXCEEDED**: Received quantity exceeds allowed tolerance
+- **INACTIVE_EXECUTION_REFERENCE**: Supplier or item is no longer valid for execution
+- **INVENTORY_HANDOFF_FAILED**: Downstream inventory handoff could not be recorded
+
+## Test Cases
+
+- posts a valid goods receipt and increases purchase-order received quantity
+- transitions purchase order to partially received when open quantity remains
+- transitions purchase order to received when all quantity is posted
+- emits inventory handoff once for a stock-item receipt
+- skips inventory handoff for a service receipt
+- returns error when goods receipt does not exist
+- returns error when goods receipt is not draft
+- returns error when posting exceeds tolerance
+- returns error when inventory handoff fails
+- returns error when purchase order is no longer receivable
+- returns error when posting a receipt line with no open quantity remaining
+- returns error when execution references are inactive

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

@@ -0,0 +1,44 @@
+# RejectPurchaseOrder
+
+## Overview
+
+RejectPurchaseOrder returns a submitted purchase order to `DRAFT` status and records the rejection reason so the buyer can revise the document.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `SUBMITTED` status can be rejected
+- Rejection reason is required and preserved for audit
+- Rejection does not alter commercial line content; it only changes control status back to draft
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reject 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{Reason provided?}
+    F -->|No| G[Return REJECTION_REASON_REQUIRED]
+    F -->|Yes| H[Store rejection reason and set status to DRAFT]
+    H --> I[Return rejected order]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_SUBMITTED**: Purchase order is not in `SUBMITTED` status
+- **REJECTION_REASON_REQUIRED**: No rejection reason was provided
+
+## Test Cases
+
+- rejects a submitted purchase order back to draft
+- records the rejection reason for audit
+- returns error when purchase order does not exist
+- returns error when purchase order is not submitted
+- returns error when rejection reason is missing

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

@@ -0,0 +1,48 @@
+# ReleasePurchaseBill
+
+## Overview
+
+ReleasePurchaseBill moves a blocked supplier bill to `MATCHED` after an authorized user confirms that the recorded variance is acceptable or has been resolved outside the original comparison.
+
+## Business Rules
+
+- Target purchase bill must exist
+- Only bills in `BLOCKED` status can be released
+- Release reason or override note is required for audit
+- Released bills preserve the original blocked variance evidence in addition to the release decision
+- Releasing a bill recalculates the due schedule if needed and prepares the downstream bill-ready handoff
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive release request] --> B{Purchase bill exists?}
+    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
+    B -->|Yes| D{Status is BLOCKED?}
+    D -->|No| E[Return PURCHASE_BILL_NOT_BLOCKED]
+    D -->|Yes| F{Override reason provided?}
+    F -->|No| G[Return RELEASE_REASON_REQUIRED]
+    F -->|Yes| H[Preserve variance evidence and set MATCHED]
+    H --> I[Prepare due schedule and bill-ready handoff]
+    I --> J[Return released bill]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
+- **PURCHASE_BILL_NOT_BLOCKED**: Purchase bill is not in `BLOCKED` status
+- **RELEASE_REASON_REQUIRED**: No override or resolution reason was provided
+- **PAYMENT_SCHEDULE_CALCULATION_FAILED**: Due schedule could not be derived from the payment-term snapshot
+
+## Test Cases
+
+- releases a blocked purchase bill with an override reason
+- preserves original variance evidence when releasing
+- returns error when purchase bill does not exist
+- returns error when purchase bill is not blocked
+- returns error when override reason is missing
+- returns error when payment schedule calculation fails

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

@@ -0,0 +1,50 @@
+# SetSupplierDefaultPurchasePaymentTerm
+
+## Overview
+
+SetSupplierDefaultPurchasePaymentTerm creates or updates the purchase-owned supplier profile for a company and assigns the default payment term used when new draft purchase orders are created for that supplier.
+
+## Business Rules
+
+- Supplier must exist and carry the `SUPPLIER` role
+- Supplier profile is unique per `companyId + supplierId`
+- Assigned payment term must exist, belong to the same company, and be active for new draft defaulting
+- Passing the same default term as the current profile is idempotent
+- Clearing the default term is allowed and preserves the supplier profile record for future procurement settings
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive supplier + company + paymentTermId] --> B{Supplier exists and is a SUPPLIER?}
+    B -->|No| C[Return supplier error]
+    B -->|Yes| D{Payment term provided?}
+    D -->|Yes| E{Payment term exists, same company, active?}
+    D -->|No| G[Upsert supplier profile with cleared default]
+    E -->|No| F[Return payment term error]
+    E -->|Yes| G[Upsert supplier profile with default term]
+    G --> H[Return supplier profile]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate the supplier reference and partner role
+
+## Error Scenarios
+
+- **SUPPLIER_NOT_FOUND**: Supplier partner does not exist
+- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the `SUPPLIER` role
+- **PAYMENT_TERM_NOT_FOUND**: Referenced purchase payment term does not exist
+- **PAYMENT_TERM_INACTIVE**: Referenced purchase payment term is inactive and cannot be used as a default
+- **COMPANY_SCOPE_MISMATCH**: Supplier profile company does not match the payment term company
+
+## Test Cases
+
+- creates a supplier profile when none exists
+- updates the default payment term on an existing supplier profile
+- clears the default payment term when explicit null is provided
+- returns error when supplier does not exist
+- returns error when partner is not a supplier
+- returns error when payment term does not exist
+- returns error when payment term is inactive
+- returns error when payment term belongs to a different company

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

@@ -0,0 +1,51 @@
+# SubmitPurchaseOrder
+
+## Overview
+
+SubmitPurchaseOrder validates that a draft purchase order is commercially complete and moves it into `SUBMITTED` status for review or approval.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `DRAFT` status can be submitted
+- Submitted orders must contain at least one line
+- Every physical line must have a receiving site
+- Supplier must still carry the `SUPPLIER` role at submission time
+- External supplier order reference must be unique within the company when provided
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive submit request] --> B{Purchase order exists and is DRAFT?}
+    B -->|No| C[Return not found or invalid status]
+    B -->|Yes| D{At least one valid line?}
+    D -->|No| E[Return line validation error]
+    D -->|Yes| F{Supplier and external reference valid?}
+    F -->|No| G[Return supplier or duplicate reference error]
+    F -->|Yes| H[Set status to SUBMITTED]
+    H --> I[Return submitted order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier role and status
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_DRAFT**: Purchase order is not in `DRAFT` status
+- **EMPTY_PURCHASE_ORDER_LINES**: Purchase order has no lines
+- **RECEIVING_SITE_REQUIRED**: A physical-receipt line has no receiving site
+- **PARTNER_NOT_SUPPLIER**: Supplier no longer carries the `SUPPLIER` role
+- **DUPLICATE_EXTERNAL_SUPPLIER_ORDER_REFERENCE**: Another order already uses the same external supplier order reference in the company
+
+## Test Cases
+
+- submits a valid draft purchase order
+- returns error when purchase order does not exist
+- returns error when purchase order is not in draft
+- returns error when purchase order has no lines
+- returns error when a physical line has no receiving site
+- returns error when supplier is no longer classified as a supplier
+- returns error when external supplier order reference is duplicated

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

@@ -0,0 +1,48 @@
+# UpdateGoodsReceipt
+
+## Overview
+
+UpdateGoodsReceipt changes draft receipt quantities, receipt dates, or targeted lines before the receipt is posted.
+
+## Business Rules
+
+- Target goods receipt must exist
+- Only receipts in `DRAFT` status can be updated
+- Updated lines must satisfy the same validation rules as create
+- Posted receipts are immutable and must be corrected by a future compensating workflow instead of update
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update 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{Updated lines valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update draft receipt]
+    H --> I[Return updated 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
+- **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
+
+## Test Cases
+
+- updates quantities on a draft goods receipt
+- updates receipt date on a draft goods receipt
+- returns error when goods receipt does not exist
+- returns error when goods receipt is not draft
+- returns error when updated line data is invalid
+- returns error when an updated receipt quantity is not positive
+- returns error when an updated receipt line has no open quantity remaining

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

@@ -0,0 +1,51 @@
+# UpdatePurchaseBill
+
+## Overview
+
+UpdatePurchaseBill revises draft supplier bill content before procurement matching is finalized.
+
+## Business Rules
+
+- Target purchase bill must exist
+- Only bills in `DRAFT` status can be updated
+- Updated invoice number must still be unique within supplier and company
+- Updated lines must satisfy the same validation rules as create
+- Once a bill has been matched, blocked, or cancelled, its comparison evidence is immutable
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Purchase bill exists?}
+    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return PURCHASE_BILL_NOT_DRAFT]
+    D -->|Yes| F{Invoice number unique and lines valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update draft bill]
+    H --> I[Return updated bill]
+```
+
+## External Dependencies
+
+- [business-partner::ListPartnerIdentificationsByPartner](../../../business-partner/docs/queries/ListPartnerIdentificationsByPartner.md) - Refresh supplier tax identification snapshot when draft bill data changes
+
+## Error Scenarios
+
+- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
+- **PURCHASE_BILL_NOT_DRAFT**: Purchase bill is not in `DRAFT` status
+- **DUPLICATE_SUPPLIER_INVOICE_NUMBER**: Supplier invoice number already exists in the same company and supplier scope
+- **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
+
+## Test Cases
+
+- updates invoice metadata on a draft purchase bill
+- updates bill lines on a draft purchase bill
+- returns error when purchase bill does not exist
+- returns error when purchase bill is not draft
+- returns error when updated invoice number is duplicated
+- returns error when updated line data is invalid
+- returns error when updated billed quantity is zero or negative
+- returns error when updated bill references a cancelled purchase order

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

@@ -0,0 +1,59 @@
+# UpdatePurchaseOrder
+
+## Overview
+
+UpdatePurchaseOrder revises mutable commercial data on a draft purchase order, including lines, supplier-facing price overrides, payment term selection, and receiving context.
+
+## Business Rules
+
+- Target purchase order must exist
+- Only orders in `DRAFT` status can be updated
+- Updated lines must satisfy the same validation rules as create
+- Draft buyers may override a defaulted supplier price while retaining the matched-rule reference for audit
+- Updating a purchase order never changes already ordered, received, or billed documents
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Purchase order exists?}
+    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return PURCHASE_ORDER_NOT_DRAFT]
+    D -->|Yes| F{Updated lines and references valid?}
+    F -->|No| G[Return validation error]
+    F -->|Yes| H[Update draft order and lines]
+    H --> I[Return updated order]
+```
+
+## External Dependencies
+
+- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier identity and role when supplier-facing data changes
+- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Re-validate item references on changed lines
+- [organization::GetSite](../../../organization/docs/queries/GetSite.md) - Re-validate receiving site references
+
+## Error Scenarios
+
+- **PURCHASE_ORDER_NOT_FOUND**: Target purchase order does not exist
+- **PURCHASE_ORDER_NOT_DRAFT**: Purchase order is not in `DRAFT` status
+- **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**: Selected payment term is inactive for new draft use
+
+## Test Cases
+
+- updates supplier-facing data on a draft purchase order
+- updates line pricing while preserving matched price-rule reference
+- returns error when purchase order does not exist
+- returns error when purchase order is not in draft
+- returns error when updated line data is invalid
+- returns error when an updated line item is inactive
+- returns error when an updated line quantity is not positive
+- returns error when an updated line unit price is negative
+- returns error when an updated receiving site does not exist
+- returns error when a physical-receipt line has no receiving site
+- returns error when selected payment term is inactive

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

@@ -0,0 +1,51 @@
+# UpdatePurchasePaymentTerm
+
+## Overview
+
+UpdatePurchasePaymentTerm changes the live definition of a purchase payment term without rewriting any historical snapshots already copied onto purchase orders or purchase bills.
+
+## Business Rules
+
+- Target payment term must exist
+- Updated schedule lines must continue to satisfy all create-time validation rules
+- Existing purchase orders and purchase bills keep their original snapshots after the term is updated
+- Updating an inactive term is allowed so it can be corrected before future reactivation
+- Company ownership of the term cannot be changed
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Payment term exists?}
+    B -->|No| C[Return PAYMENT_TERM_NOT_FOUND]
+    B -->|Yes| D{Schedule and discount data valid?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F[Update payment term and schedule lines]
+    F --> G[Return updated term]
+```
+
+## External Dependencies
+
+- [organization::GetCompany](../../../organization/docs/queries/GetCompany.md) - Preserve and validate existing company scope
+
+## Error Scenarios
+
+- **PAYMENT_TERM_NOT_FOUND**: Target payment term 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 amount or percentage
+- **INVALID_DISCOUNT_CONFIGURATION**: Discount metadata is incomplete or inconsistent with the final due date
+- **IMMUTABLE_COMPANY_SCOPE**: Update attempted to move the term into another company
+
+## Test Cases
+
+- updates name and schedule lines on an active payment term
+- updates an inactive payment term without reactivating it
+- preserves historical purchase-order snapshots after update
+- preserves historical purchase-bill snapshots after update
+- returns error when payment term does not exist
+- returns error when the updated schedule is empty
+- returns error when updated schedule is invalid
+- returns error when an updated schedule line is invalid
+- returns error when an updated discount configuration is invalid
+- returns error when company scope is changed

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

@@ -0,0 +1,43 @@
+# UpdatePurchasePriceList
+
+## Overview
+
+UpdatePurchasePriceList updates descriptive metadata, validity notes, or deterministic priority on an existing supplier price list without changing historical order snapshots.
+
+## Business Rules
+
+- Target price list must exist
+- Company and supplier ownership are immutable
+- Updating a price list never rewrites purchase orders that already snapshotted one of its rules
+- Priority changes must preserve deterministic ordering for rule selection
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Price list exists?}
+    B -->|No| C[Return PRICE_LIST_NOT_FOUND]
+    B -->|Yes| D{Ownership unchanged and priority valid?}
+    D -->|No| E[Return validation error]
+    D -->|Yes| F[Update price list]
+    F --> G[Return updated list]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **PRICE_LIST_NOT_FOUND**: Target price list does not exist
+- **IMMUTABLE_OWNER_CHANGE**: Update attempted to change the supplier or company owner
+- **INVALID_LIST_PRIORITY**: Updated priority conflicts with deterministic rule ordering
+
+## Test Cases
+
+- updates metadata on an active price list
+- updates metadata on an inactive price list
+- preserves historical purchase-order snapshots after update
+- returns error when price list does not exist
+- returns error when supplier or company ownership is changed
+- returns error when updated priority is invalid