# UpdatePurchaseBill

## Permission Scope

purchaseBill

## Overview

UpdatePurchaseBill revises draft supplier bill content before procurement matching is finalized. Lines can have their `purchaseOrderLineId` assigned, changed, or removed while in draft.

## 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 (PO reference is optional; when present, the PO must exist and not be cancelled; each line must carry a unitId; item ACTIVE status is not checked — same post-order rationale 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**: Referenced 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
- returns error when a PO-unlinked line has non-positive quantity
- accepts PO-unlinked lines with valid quantity and uses defaults
- uses PO line unitPrice as default billedUnitPrice when not provided
