# CreateSalesItem

## Permission Scope

salesItem

## Overview

CreateSalesItem adopts an item for selling: it creates the sales module's record for one item-management item and fixes the selling defaults that sales order lines resolve from. Until this record exists, the item cannot be sold.

## Business Rules

- The referenced item must exist in item-management
- An item may hold at most one selling record; adopting an already adopted item is rejected
- Item status is not checked — sales may prepare the selling record while the item is still DRAFT, and the ACTIVE requirement is enforced where orders are entered
- `requiresPhysicalFulfillment` 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_SALES_ITEM]
    D -->|No| F[Insert selling record with its defaults]
    F --> G[Item can now be sold]
```

## External Dependencies

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

## Error Scenarios

- **ITEM_NOT_FOUND**: One or more referenced items do not exist
- **DUPLICATE_SALES_ITEM**: Referenced item already holds a selling record

## Test Cases

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