# CancelPurchaseBill

## Permission Scope

purchaseBill

## Overview

CancelPurchaseBill voids a draft or blocked supplier bill.

## Business Rules

- Target purchase bill must exist
- Only bills in `DRAFT` or `BLOCKED` can be cancelled
- Cancellation preserves invoice identity, line references, and variance evidence for future dispute or credit-note workflows

## Process Flow

```mermaid
flowchart TD
    A[Receive cancel request] --> B{Purchase bill exists?}
    B -->|No| C[Return PURCHASE_BILL_NOT_FOUND]
    B -->|Yes| D{Status cancellable?}
    D -->|No| E[Return PURCHASE_BILL_NOT_CANCELLABLE]
    D -->|Yes| H[Preserve evidence and set CANCELLED]
    H --> I[Return cancelled bill]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_BILL_NOT_FOUND**: Referenced purchase bill does not exist
- **PURCHASE_BILL_NOT_CANCELLABLE**: Purchase bill status does not allow cancellation

## Test Cases

- cancels a draft purchase bill
- cancels a blocked purchase bill
- preserves variance evidence when a blocked bill is cancelled
- returns error when purchase bill does not exist
- returns error when purchase bill status does not allow cancellation
