# CreatePurchaseItem

## Permission Scope

purchaseItem

## Overview

CreatePurchaseItem adopts an item for purchasing: it creates the purchase module's record for one item-management item and fixes the purchasing defaults that purchase order lines resolve from. Until this record exists, the item cannot be ordered.

## Business Rules

- The referenced item must exist in item-management
- An item may hold at most one purchasing record; adopting an already adopted item is rejected
- Item status is not checked — procurement may prepare the purchasing record while the item is still DRAFT, and the ACTIVE requirement is enforced where orders are entered
- `requiresPhysicalReceipt` is required
- Host-defined custom fields are persisted alongside the builtin columns; a builtin column always wins over a custom field of the same name

## Process Flow

```mermaid
flowchart TD
    A[Receive adoption request for an item] --> B{Item exists?}
    B -->|No| C[Return ITEM_NOT_FOUND]
    B -->|Yes| D{Item already adopted?}
    D -->|Yes| E[Return DUPLICATE_PURCHASE_ITEM]
    D -->|No| F[Insert purchasing record with its defaults]
    F --> G[Item can now be ordered]
```

## External Dependencies

- [item-management::GetItem](../../../item-management/docs/query/GetItem.md) - Validate that the adopted item exists

## Error Scenarios

- **ITEM_NOT_FOUND**: Referenced item does not exist
- **DUPLICATE_PURCHASE_ITEM**: Referenced item already holds a purchasing record

## Test Cases

- adopts an item for purchasing with the given receipt expectation
- returns error when the item does not exist
- returns error when the item already has a purchasing record
- persists host-defined custom fields alongside the builtin columns