# CreatePurchasePriceRule

## Permission Scope

purchasePricing

## 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/query/GetItem.md) - Validate item existence and active status
- [primitives::GetCurrency](../../../primitives/docs/query/GetCurrency.md) - Validate transaction currency
- [primitives::GetUnit](../../../primitives/docs/query/GetUnit.md) - Validate purchase unit of measure

## Error Scenarios

- **PRICE_LIST_NOT_FOUND**: Referenced purchase price list 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

- 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
