# UpdatePurchasePriceRule

## Permission Scope

purchasePricing

## Overview

UpdatePurchasePriceRule changes the live pricing condition on an existing supplier price rule without modifying any purchase orders that already snapshotted that rule's price.

## Business Rules

- Target rule must exist
- Updated references and value fields must satisfy the same validation rules as create
- Updating an inactive rule is allowed so it can be corrected before reactivation
- Updated precedence must remain unique within the supplier pricing context
- Historical purchase orders preserve the original ordered price even when the source rule changes

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Rule exists?}
    B -->|No| C[Return PRICE_RULE_NOT_FOUND]
    B -->|Yes| D{References and values valid?}
    D -->|No| E[Return validation error]
    D -->|Yes| F{Unique precedence?}
    F -->|No| G[Return DUPLICATE_RULE_PRECEDENCE]
    F -->|Yes| H[Update rule]
    H --> I[Return updated 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_RULE_NOT_FOUND**: Target price rule does not exist
- **ITEM_NOT_FOUND**: Referenced item does not exist
- **ITEM_NOT_ACTIVE**: Referenced item is not in ACTIVE status
- **CURRENCY_NOT_FOUND**: Referenced currency does not exist
- **UNIT_NOT_FOUND**: Referenced purchase unit does not exist
- **INVALID_UNIT_PRICE**: Unit price is negative or otherwise invalid
- **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

- updates price and quantity break on an active rule
- updates an inactive rule without reactivating it
- preserves historical purchase-order snapshots after update
- returns error when rule does not exist
- returns error when updated references are invalid
- returns error when the updated item does not exist
- returns error when the updated item is inactive
- returns error when the updated unit does not exist
- returns error when the updated unit price is not positive
- returns error when the updated minimum quantity is negative
- returns error when the updated effective range is inverted
- returns error when updated precedence duplicates another rule
