# CalculatePurchasePrice

## Overview

CalculatePurchasePrice resolves the best matching supplier purchase price rule for a draft purchase-order line and returns the suggested unit price together with the matched rule reference.

## Business Rules

- Inputs include `companyId`, `supplierId`, `itemId`, ordered quantity, purchase unit, transaction currency, and order date
- Only active price lists and active price rules participate in matching
- Rule precedence is deterministic across supplier, price-list priority, item scope, purchase unit, minimum quantity break, effective date, and explicit rule priority
- Rules match only when the requested currency and purchase unit equal the rule currency and unit
- Returns null suggestion when no active rule matches and manual pricing is expected

## Process Flow

```mermaid
flowchart TD
    A[Receive supplier, item, qty, unit, currency, date] --> B[Load active lists and active rules for supplier/company]
    B --> C[Filter rules by item, UoM, currency, date, and min qty]
    C --> D{Rule found?}
    D -->|No| E[Return null suggestion]
    D -->|Yes| F[Pick highest precedence rule]
    F --> G[Return suggested unit price and matched rule reference]
```

## External Dependencies

- None

## Error Scenarios

- **NO_MATCHING_PRICE_RULE**: No active rule matches the inputs; response still succeeds with null `priceSuggestion` and null `matchedRule`

## Test Cases

- returns the best matching rule for a valid supplier item context
- picks the higher quantity-break rule when ordered quantity qualifies
- ignores inactive price lists and inactive rules
- returns null when no active rule matches
