# GetPurchaseOrder

## Overview

GetPurchaseOrder retrieves a single purchase order with its lines, frozen commercial snapshots, and purchase-owned billing progress.

## Business Rules

- Accepts lookup by `{ id }`
- Returns purchase orders in any `orderStatus` so cancelled and closed documents remain auditable
- Response includes `orderStatus`, `receiptStatus`, and `billingStatus` as separate fields
- Revision history is reachable through the `revisions` (PurchaseOrderRevision) backward relation and per-revision `fieldChanges` (PurchaseOrderFieldChange) — this query exposes the order header and lines; the current revision count, when displayed, is derived from `MAX(revisionNumber)` of attached envelopes (0 when none exist)
- Response includes line-level billed quantity and remaining ordered quantity to bill from the purchase-owned billed-quantity projection
- Response does not include receipt-derived line quantities (`receivedQuantity`, `remainingQuantityToReceive`, or `remainingReceivedQuantityToBill`); callers that need receipt totals should combine this query with inventory receipt evidence queries
- Only active lines (lineStatus = ACTIVE) represent current targets; CANCELLED lines are excluded from fulfillment totals
- Response includes matched price-rule references when present
- Returns null when no purchase order matches the lookup

## Process Flow

```mermaid
flowchart TD
    A[Receive lookup input] --> C[Select PurchaseOrder by id]
    C --> E{Order found?}
    E -->|Yes| F[Load lines, snapshots, and purchase-owned billing totals]
    E -->|No| G[Return null]
    F --> H[Compute billed quantities per line]
    H --> I[Return purchase order]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist

## Test Cases

- returns purchase order when found by id
- returns lines with the order
- returns null when purchase order is not found
- returns billed quantities per line without receipt-derived fields
- does not expose remaining received quantity from the purchase query