# SubmitPurchaseOrder

## Permission Scope

purchaseOrder

## Overview

SubmitPurchaseOrder validates that a draft purchase order is commercially complete and moves `orderStatus` to `SUBMITTED` for review or approval.

## Business Rules

- Target purchase order must exist
- Only orders with `orderStatus` = `DRAFT` can be submitted
- Submitted orders must contain at least one line
- Supplier must still carry the `SUPPLIER` role at submission time
- External supplier order reference must be unique within the company when provided

## Process Flow

```mermaid
flowchart TD
    A[Receive submit request] --> B{Purchase order exists and is DRAFT?}
    B -->|No| C[Return not found or invalid status]
    B -->|Yes| D{At least one valid line?}
    D -->|No| E[Return line validation error]
    D -->|Yes| F{Supplier and external reference valid?}
    F -->|No| G[Return supplier or duplicate reference error]
    F -->|Yes| H["Set orderStatus to SUBMITTED"]
    H --> I[Return submitted order]
```

## External Dependencies

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

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
- **PURCHASE_ORDER_NOT_DRAFT**: Purchase order is not in `DRAFT` status
- **EMPTY_PURCHASE_ORDER_LINES**: Purchase order has no lines
- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the SUPPLIER role
- **DUPLICATE_EXTERNAL_SUPPLIER_ORDER_REFERENCE**: Another order already uses the same external supplier order reference in the company

## Test Cases

- submits a valid draft purchase order
- returns error when purchase order does not exist
- returns error when purchase order is not in draft
- returns error when purchase order has no lines
- returns error when supplier is no longer classified as a supplier
- returns error when external supplier order reference is duplicated
- submits when line has requiresPhysicalReceipt false and no receiving site
