# RejectPurchaseOrder

## Permission Scope

purchaseOrder

## Overview

RejectPurchaseOrder returns a submitted purchase order's `orderStatus` to `DRAFT` and records the rejection reason so the buyer can revise the document.

## Business Rules

- Target purchase order must exist
- Only orders with `orderStatus` = `SUBMITTED` can be rejected
- Rejection reason is required and preserved for audit
- Rejection does not alter commercial line content; it only changes `orderStatus` back to `DRAFT`

## Process Flow

```mermaid
flowchart TD
    A[Receive reject request] --> B{Purchase order exists?}
    B -->|No| C[Return PURCHASE_ORDER_NOT_FOUND]
    B -->|Yes| D{Status is SUBMITTED?}
    D -->|No| E[Return PURCHASE_ORDER_NOT_SUBMITTED]
    D -->|Yes| F{Reason provided?}
    F -->|No| G[Return REJECTION_REASON_REQUIRED]
    F -->|Yes| H["Store rejection reason and set orderStatus to DRAFT"]
    H --> I[Return rejected order]
```

## External Dependencies

- None

## Error Scenarios

- **PURCHASE_ORDER_NOT_FOUND**: Referenced purchase order does not exist
- **PURCHASE_ORDER_NOT_SUBMITTED**: Purchase order is not in `SUBMITTED` status
- **REJECTION_REASON_REQUIRED**: No rejection reason was provided

## Test Cases

- rejects a submitted purchase order back to draft
- records the rejection reason for audit
- returns error when purchase order does not exist
- returns error when purchase order is not submitted
- returns error when rejection reason is missing