# PurchaseBill

## Description

PurchaseBill captures a supplier invoice inside the purchase domain until procurement matching is complete. It compares supplier-invoiced quantities, prices, and tax information against purchase-order commitments and, when required, posted goods receipts. The bill is then marked matched, blocked for variance, or cancelled before downstream AP acceptance.

The purchase bill also owns the procurement-side payable readiness contract. Once a bill is matched, purchase can hand downstream modules a stable `BillReadyHandoff` payload containing the invoice identity, matched amounts, due schedule, and tax snapshot.

## Domain Model Definitions

### Model type

Stateful

#### State Transitions

```mermaid
stateDiagram-v2
    [*] --> Draft: createPurchaseBill
    Draft --> Draft: updatePurchaseBill
    Draft --> Blocked: matchPurchaseBill
    Draft --> Matched: matchPurchaseBill
    Blocked --> Matched: releasePurchaseBill
    Draft --> Cancelled: cancelPurchaseBill
    Blocked --> Cancelled: cancelPurchaseBill
    Matched --> Cancelled: cancelPurchaseBill
```

### Command Definitions

- [createPurchaseBill](../commands/CreatePurchaseBill.md) - Create a draft supplier bill with invoice identity and line references
- [updatePurchaseBill](../commands/UpdatePurchaseBill.md) - Revise a draft bill before procurement matching is finalized
- [matchPurchaseBill](../commands/MatchPurchaseBill.md) - Run 2-way or 3-way matching and set the bill to matched or blocked
- [releasePurchaseBill](../commands/ReleasePurchaseBill.md) - Move a blocked bill to matched after authorized variance resolution
- [cancelPurchaseBill](../commands/CancelPurchaseBill.md) - Cancel a draft, blocked, or matched bill before downstream AP accepts the handoff

### Query Definitions

- [getPurchaseBill](../queries/GetPurchaseBill.md) - Retrieve a supplier bill with matching results, snapshots, and line references
- [calculatePurchaseBillDueSchedule](../queries/CalculatePurchaseBillDueSchedule.md) - Compute the downstream payable schedule from the bill's payment-term snapshot

### Models

- PurchaseBill
- PurchaseBillLine
- PurchaseBillTaxSnapshot
- BillReadyHandoff

### Invariants

- Every purchase bill belongs to exactly one company and one supplier
- Supplier invoice number is unique within one company and supplier combination
- Every bill line references at least one purchase-order line and records billed quantity greater than zero
- `MATCHED` bills preserve the comparison baseline: invoice date, invoice number, ordered price reference, payment-term snapshot, supplier tax identifier, tax code, taxable amount, and tax amount
- A 3-way match cannot mark a bill as matched when billed quantity exceeds cumulative posted receipt quantity beyond tolerance
- `BLOCKED` bills must preserve the variance reason and comparison basis for review
- `CANCELLED` is allowed only while no downstream AP or accounting module has accepted the `BillReadyHandoff`
- 4-way matching is explicitly out of scope for this module plan; quality evidence can be added as a future extension without redesigning the bill lifecycle
- Credit-note and debit-memo workflows are future extensions that must preserve the original bill evidence rather than rewriting it

### Relationships

- **Belongs To BusinessPartner**: Each bill references one supplier [BusinessPartner](../../../business-partner/docs/models/BusinessPartner.md)
- **References PurchaseOrder**: Bill lines match against one or more [PurchaseOrder](./PurchaseOrder.md) lines
- **References GoodsReceipt**: 3-way matching may compare against posted [GoodsReceipt](./GoodsReceipt.md) lines
- **Snapshots PurchasePaymentTerm**: The bill carries a [PurchasePaymentTerm](./PurchasePaymentTerm.md) snapshot and calculated due schedule
- **Snapshots PartnerIdentification**: The bill stores supplier tax identity from [PartnerIdentification](../../../business-partner/docs/models/PartnerIdentification.md)
- **May Emit BillReadyHandoff**: Matched bills hand off invoice reference, matched amounts, due schedule, tax snapshot, and matching mode to downstream AP or accounting
