# GetPurchaseChangeOrder

## Overview

GetPurchaseChangeOrder retrieves a single purchase change order with its change order lines, proposed actions, and the revision context it targets.

## Business Rules

- Accepts lookup by `{ id }` or by `{ purchaseOrderId }` (returns the current open change order for the PO)
- Returns change orders in any `changeOrderStatus` so rejected, cancelled, and applied documents remain available for audit
- Response includes `changeOrderStatus`, `fromRevisionNumber`, and `reason`
- Response includes all change order lines with their `action` (ADD, MODIFY, or REMOVE), target quantities, unit prices, and `originalPurchaseOrderLineId` references
- When looked up by `purchaseOrderId`, returns the open change order (DRAFT, SUBMITTED, or APPROVED) if one exists, otherwise returns null
- Returns null when no change order matches the lookup

## Process Flow

```mermaid
flowchart TD
    A[Receive lookup input] --> B{Lookup by id or purchaseOrderId?}
    B -->|id| C[Select PurchaseChangeOrder by id]
    B -->|purchaseOrderId| D[Select open PurchaseChangeOrder by purchaseOrderId]
    C --> E{Change order found?}
    D --> E
    E -->|Yes| F[Load change order lines with action details]
    E -->|No| G[Return null]
    F --> H[Return purchase change order]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_CHANGE_ORDER_NOT_FOUND**: No change order matches the given lookup; caller receives null

## Test Cases

- returns change order when found by id
- returns open change order when found by purchaseOrderId
- returns change order lines with their actions and quantities
- returns change orders in any status including APPLIED and REJECTED
- returns null when change order is not found
- returns null when no open change order exists for the given purchaseOrderId
