# UpdatePurchaseRequisition

## Permission Scope

purchaseRequisition

## Overview

UpdatePurchaseRequisition revises mutable fields on a draft purchase requisition, including adding, removing, or editing lines, updating descriptions, quantities, estimated prices, item references, unit of measure, and optional supplier references.

## Business Rules

- Target purchase requisition must exist
- Only requisitions with `status` = `DRAFT` can be updated
- `updateLines` and `removeLineIds` must target a line that exists on the requisition
- `updateLines` patches the existing line in place, so its id and `createdAt` are preserved
- The requisition must retain at least one line after the update
- Updated lines must satisfy the same validation rules as create
- Updating a requisition never changes downstream documents that may have been created from a prior conversion

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Purchase requisition exists?}
    B -->|No| C[Return PURCHASE_REQUISITION_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return PURCHASE_REQUISITION_NOT_DRAFT]
    D -->|Yes| F{At least one line remains?}
    F -->|No| G[Return EMPTY_PURCHASE_REQUISITION_LINES]
    F -->|Yes| H{Updated lines and references valid?}
    H -->|No| I[Return validation error]
    H -->|Yes| J[Update draft requisition and lines]
    J --> K[Return updated requisition]
```

## External Dependencies

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

## Error Scenarios

- **PURCHASE_REQUISITION_NOT_FOUND**: Referenced purchase requisition does not exist
- **PURCHASE_REQUISITION_NOT_DRAFT**: Purchase requisition is not in `DRAFT` status
- **LINE_NOT_FOUND**: Referenced line does not exist on the target order
- **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

- updates requisition metadata on a draft purchase requisition
- updates a line in place so its id and createdAt survive the edit
- adds a requisition line via addLines
- removes a requisition line via removeLineIds
- returns error when purchase requisition does not exist
- returns error when purchase requisition is not in draft
- returns error when an update targets a missing line
- returns error when a removal would leave the requisition without lines
- 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
- preserves existing fields when no patch or line changes are provided
