# ClosePurchaseOrder

## Permission Scope

purchaseOrder

## Overview

ClosePurchaseOrder sets `orderStatus` to `CLOSED` on a purchase order that has progressed beyond the initial ordering phase, and prevents further receipt or billing activity on the remaining open quantity. The `receiptStatus` and `billingStatus` values are preserved as-is for audit.

## Business Rules

- Target purchase order must exist
- Only orders with `orderStatus` = `ORDERED` can be closed (i.e., the order must have been approved and not already cancelled or closed)
- Remaining open quantity must already be fully received, fully billed, or explicitly written off with a close reason
- Closing preserves the original ordered, received, and billed quantities for audit
- Closed orders reject new inventory receipt execution against the closed commitment and new purchase bills
- Close validation uses each active line's received quantity from the purchase-order-line receipt projection and billed quantity from the purchase-order-line billing projection
- Closing closes any open inventory supply plans linked to the purchase-order lines so remaining expected supply no longer contributes to planning or ATP

## Process Flow

```mermaid
flowchart TD
    A[Receive close request] --> B{Purchase order exists?}
    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
    B -->|Yes| D{Status closable?}
    D -->|No| E[Return PURCHASE_ORDER_NOT_CLOSABLE]
    D -->|Yes| H{Open quantity fully resolved or write-off reason provided?}
    H -->|No| I[Return OPEN_QUANTITY_REMAINS]
    H -->|Yes| J["Set orderStatus to CLOSED (preserve receiptStatus and billingStatus)"]
    J --> K[Close linked inventory supply plans]
    K --> L[Return closed order]
```

## External Dependencies

- [inventory::CloseInventorySupplyPlan](../../../inventory/docs/command/CloseInventorySupplyPlan.md) - Closes fulfilled or written-off supplier commitments using `SOURCE_DOCUMENT` input for the PO source document

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
- **PURCHASE_ORDER_NOT_CLOSABLE**: Purchase order status does not allow closure
- **OPEN_QUANTITY_REMAINS**: Remaining quantity is not fulfilled or explicitly written off
- **CLOSE_REASON_REQUIRED**: Residual open quantity exists but no write-off reason was provided

## Test Cases

- closes a fully billed purchase order
- closes a partially received order when remaining quantity is explicitly written off
- returns error when purchase order does not exist
- returns error when purchase order status does not allow closure
- returns error when unresolved open quantity remains
- returns error when residual quantity exists without a close reason
- allows closure without write-off when each line is fully received
- returns OPEN_QUANTITY_REMAINS before requiring a close reason when write-off is not requested
- closes an order with no lines
- closes an order when the received quantity projection covers the ordered quantity
- detects open quantity when only billed but not received