# UpdatePurchaseBill

## Overview

UpdatePurchaseBill revises draft supplier bill content before procurement matching is finalized.

## Business Rules

- Target purchase bill must exist
- Only bills in `DRAFT` status can be updated
- Updated invoice number must still be unique within supplier and company
- Updated lines must satisfy the same validation rules as create
- Once a bill has been matched, blocked, or cancelled, its comparison evidence is immutable

## Process Flow

```mermaid
flowchart TD
    A[Receive update request] --> B{Purchase bill exists?}
    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
    B -->|Yes| D{Status is DRAFT?}
    D -->|No| E[Return PURCHASE_BILL_NOT_DRAFT]
    D -->|Yes| F{Invoice number unique and lines valid?}
    F -->|No| G[Return validation error]
    F -->|Yes| H[Update draft bill]
    H --> I[Return updated bill]
```

## External Dependencies

- [business-partner::ListPartnerIdentificationsByPartner](../../../business-partner/docs/queries/ListPartnerIdentificationsByPartner.md) - Refresh supplier tax identification snapshot when draft bill data changes

## Error Scenarios

- **PURCHASE_BILL_NOT_FOUND**: Target purchase bill does not exist
- **PURCHASE_BILL_NOT_DRAFT**: Purchase bill is not in `DRAFT` status
- **DUPLICATE_SUPPLIER_INVOICE_NUMBER**: Supplier invoice number already exists in the same company and supplier scope
- **PURCHASE_ORDER_LINE_NOT_FOUND**: Referenced purchase-order line does not exist
- **INVALID_BILLED_QUANTITY**: Billed quantity is zero or negative
- **PURCHASE_ORDER_CANCELLED**: Referenced purchase order is cancelled

## Test Cases

- updates invoice metadata on a draft purchase bill
- updates bill lines on a draft purchase bill
- returns error when purchase bill does not exist
- returns error when purchase bill is not draft
- returns error when updated invoice number is duplicated
- returns error when updated line data is invalid
- returns error when updated billed quantity is zero or negative
- returns error when updated bill references a cancelled purchase order
