# ApprovePurchaseOrder

## Overview

ApprovePurchaseOrder moves a submitted purchase order into `ORDERED` status, freezes the commercial agreement, and records the order as ready for supplier execution.

## Business Rules

- Target purchase order must exist
- Only orders in `SUBMITTED` status can be approved
- Supplier must still be active and classified as a supplier
- Referenced items must still be active for operational execution
- Approval freezes the ordered unit prices, matched price-rule references, and payment-term snapshot
- 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[Freeze payment term and line price snapshots]
    H --> I[Set status to ORDERED]
    I --> J[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**: Target purchase order does not exist
- **PURCHASE_ORDER_NOT_SUBMITTED**: Purchase order is not in `SUBMITTED` status
- **SUPPLIER_NOT_ACTIVE**: Supplier is inactive at approval time
- **PARTNER_NOT_SUPPLIER**: Supplier no longer carries the `SUPPLIER` role
- **ITEM_NOT_ACTIVE**: One or more referenced items are inactive
- **MISSING_COMMERCIAL_SNAPSHOT**: Required payment-term or price snapshot data is missing

## Test Cases

- approves a valid submitted purchase order
- freezes payment-term snapshot at approval time
- freezes ordered line prices and matched rule references at approval time
- 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
- returns error when approval cannot reconstruct the commercial snapshot
