# 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, payment-term lines, 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 — approval is the last gate before supplier execution begins; once approved (ORDERED), subsequent post-order flows (PostGoodsReceipt etc.) no longer require item ACTIVE status to avoid blocking in-progress fulfillment
- Approving an order does not create stock movement or billing records

## 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 and items still active?}
    F -->|No| G[Return execution reference error]
    F -->|Yes| H["Set orderStatus to ORDERED, receiptStatus to NOT_RECEIVED, billingStatus to NOT_BILLED"]
    H --> I[Return approved order]
```

## External Dependencies

- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Re-validate supplier status and role before ordering
- [item-management::GetItem](../../../item-management/docs/queries/GetItem.md) - Re-validate item status before ordering

## 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
- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the SUPPLIER role
- **ITEM_NOT_ACTIVE**: Referenced item is not in ACTIVE status

## Test Cases

- approves a valid submitted purchase order
- 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 is no longer classified as a supplier
