# CreatePurchaseRequisition

## Permission Scope

purchaseRequisition

## Overview

CreatePurchaseRequisition creates a new purchase requisition in `DRAFT` status with requester, company, and one or more request lines containing item references, unit of measure, descriptions, quantities, and estimated costs.

## Business Rules

- Company, requester, and at least one line are required
- Each line must have a description, an item reference, a unit of measure, quantity greater than zero, and a non-negative estimated unit price
- The referenced item must exist
- A line may omit the suggested supplier; supplier assignment is optional
- When a suggested supplier is provided, the supplier must exist, be active, and carry the `SUPPLIER` role
- Requisition is always created with `status` = `DRAFT`

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Company and requester valid?}
    B -->|No| C[Return validation error]
    B -->|Yes| D{At least one line?}
    D -->|No| E[Return EMPTY_PURCHASE_REQUISITION_LINES]
    D -->|Yes| F{Validate each line description, quantity, price}
    F -->|No| G[Return line validation error]
    F -->|Yes| H{Validate optional item and supplier references}
    H -->|No| I[Return reference error]
    H -->|Yes| J[Insert requisition and lines in DRAFT]
    J --> K[Return created requisition]
```

## External Dependencies

- [item-management::GetItem](../../../item-management/docs/query/GetItem.md) - Validate item references on lines
- [business-partner::GetPartner](../../../business-partner/docs/query/GetPartner.md) - Validate optional suggested supplier references

## Error Scenarios

- **EMPTY_PURCHASE_REQUISITION_LINES**: Purchase requisition has no lines
- **DESCRIPTION_REQUIRED**: A line is missing a description
- **INVALID_QUANTITY**: Quantity is zero or negative
- **INVALID_ESTIMATED_UNIT_PRICE**: Estimated unit price is negative
- **ITEM_NOT_FOUND**: Referenced item does not exist
- **SUPPLIER_NOT_FOUND**: Referenced supplier partner does not exist
- **SUPPLIER_NOT_ACTIVE**: Referenced supplier is not in ACTIVE status
- **PARTNER_NOT_SUPPLIER**: Referenced partner does not carry the SUPPLIER role

## Test Cases

- creates a draft purchase requisition with valid requester and lines
- creates a requisition with lines referencing an item
- creates a requisition with optional suggested supplier on lines
- returns error when no lines are provided
- returns error when a line is missing a description
- returns error when quantity is zero or negative
- returns error when estimated unit price is negative
- returns error when a referenced item does not exist
- returns error when a suggested supplier does not exist
- returns error when a suggested supplier is inactive
- returns error when a suggested supplier is not classified as a supplier
- returns DescriptionRequiredError with empty string when description is undefined-like
