# ApprovePurchaseOrder

## Permission Scope

purchaseOrder

## Overview

ApprovePurchaseOrder moves a submitted purchase order's `orderStatus` to `ORDERED`, initializes `receiptStatus` to `NOT_RECEIVED` and `billingStatus` to `NOT_BILLED`, and records the order as ready for supplier execution. Snapshots (supplier name, item name/SKU) are already captured at creation or update time; approval does not overwrite them.

## Business Rules

- Target purchase order must exist
- Only orders with `orderStatus` = `SUBMITTED` can be approved
- Supplier must still be active and classified as a supplier
- Referenced items must still be active and hold a purchasing record — approval is the last gate before supplier execution begins
- Approving an order does not create stock movement or billing records
- Approving an order publishes one inventory supply plan for each physical-receipt purchase-order line using sourceType `PURCHASE_ORDER`, the PO id as `sourceId`, and the PO line id as `sourceLineId`
- Standard purchase order lines are the core delivery/supply unit; planned split deliveries are represented by splitting purchase order lines
- Service or non-physical receipt lines do not create inventory supply plans

## Process Flow

```mermaid
flowchart TD
    A[Receive approve request] --> B{Purchase order exists?}
    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
    B -->|Yes| D{Status is SUBMITTED?}
    D -->|No| E[Return PURCHASE_ORDER_NOT_SUBMITTED]
    D -->|Yes| F{Supplier active, items active and purchasable?}
    F -->|No| G[Return execution reference error]
    F -->|Yes| H["Set orderStatus to ORDERED, receiptStatus to NOT_RECEIVED, billingStatus to NOT_BILLED"]
    H --> I[Create inventory supply plans for physical receipt lines]
    I --> J[Return approved order]
```

## External Dependencies

- [business-partner::GetSupplierAccount](../../../business-partner/docs/query/GetSupplierAccount.md) - Re-validate supplier company and transaction availability before ordering
- [item-management::GetItem](../../../item-management/docs/query/GetItem.md) - Re-validate item status before ordering
- [inventory::CreateInventorySupplyPlan](../../../inventory/docs/command/CreateInventorySupplyPlan.md) - Publishes future inbound supply once the supplier commitment becomes ordered

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
- **PURCHASE_ORDER_NOT_SUBMITTED**: Purchase order is not in `SUBMITTED` status
- **SUPPLIER_NOT_ACTIVE**: Referenced supplier is not in ACTIVE status
- **SUPPLIER_ACCOUNT_COMPANY_MISMATCH**: Supplier account belongs to another company
- **ITEM_NOT_ACTIVE**: Referenced item is not in ACTIVE status
- **ITEM_NOT_PURCHASABLE**: Referenced item holds no purchasing record and cannot be purchased

## Test Cases

- approves a valid submitted purchase order
- creates inventory supply plans for physical receipt lines on approval
- returns error when purchase order does not exist
- returns error when purchase order is not submitted
- returns error when supplier is inactive
- returns error when an item is inactive
- returns error when supplier account belongs to another company
- returns error when an item has no purchasing record