@tailor-platform/erp-kit 0.4.0 → 0.5.0

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

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