# CreatePurchaseBill

## Overview

CreatePurchaseBill creates a supplier bill in `DRAFT` status with invoice identity, purchase references, line quantities, tax snapshot inputs, and the payment-term snapshot that will later drive payable scheduling.

## Business Rules

- Company, supplier, invoice number, invoice date, and at least one line are required
- Duplicate supplier invoice numbers are rejected within the same supplier and company
- Each line must reference a valid purchase-order line and record billed quantity greater than zero
- Supplier bill cannot reference a cancelled purchase order
- Assigned payment term snapshot and supplier tax identification must be captured at create time
- New purchase bills are created in `DRAFT` status

## Process Flow

```mermaid
flowchart TD
    A[Receive create request] --> B{Supplier and company valid?}
    B -->|No| C[Return supplier or company error]
    B -->|Yes| D{Duplicate invoice number?}
    D -->|Yes| E[Return DUPLICATE_SUPPLIER_INVOICE_NUMBER]
    D -->|No| F{At least one valid bill line?}
    F -->|No| G[Return line validation error]
    F -->|Yes| H[Snapshot payment term and supplier tax identity]
    H --> I[Insert purchase bill in DRAFT]
    I --> J[Return created bill]
```

## External Dependencies

- [business-partner::GetPartner](../../../business-partner/docs/queries/GetPartner.md) - Validate supplier identity and status
- [business-partner::ListPartnerIdentificationsByPartner](../../../business-partner/docs/queries/ListPartnerIdentificationsByPartner.md) - Source supplier tax identification snapshot

## Error Scenarios

- **SUPPLIER_NOT_FOUND**: Referenced supplier does not exist
- **DUPLICATE_SUPPLIER_INVOICE_NUMBER**: Supplier invoice number already exists in the same company and supplier scope
- **EMPTY_BILL_LINES**: No purchase-bill lines were provided
- **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
- **PAYMENT_TERM_SNAPSHOT_MISSING**: No valid payment-term snapshot is available for the bill
- **SUPPLIER_TAX_IDENTIFICATION_MISSING**: Required supplier tax identification cannot be snapshotted

## Test Cases

- creates a draft purchase bill with valid line references
- snapshots payment-term data at create time
- snapshots supplier tax identification at create time
- returns error when supplier does not exist
- returns error when invoice number is duplicated
- returns error when no bill lines are provided
- returns error when a purchase-order line does not exist
- returns error when billed quantity is zero or negative
- returns error when referenced purchase order is cancelled
- returns error when no payment-term snapshot is available
- returns error when supplier tax identification cannot be snapshotted
