# StartInventoryCount

## Permission Scope

inventoryControl

## Overview

startInventoryCount initiates the count process, transitioning the count from PLANNED to IN_PROGRESS status. It snapshots the current system on-hand quantities for each item-location pair within the count scope and creates individual count lines. Optionally, stock movements can be frozen for the counted scope during the count.

## Business Rules

- Count must exist
- Count must be in PLANNED status
- Snapshots current on-hand quantity for each item-location pair
- Optionally freezes stock movements for the counted scope
- Creates an InventoryCountLine for each item-location pair in scope

## Process Flow

```mermaid
flowchart TD
    A[Receive start request] --> B{Count exists?}
    B -->|No| C[Return error: COUNT_NOT_FOUND]
    B -->|Yes| D{Status is PLANNED?}
    D -->|No| E[Return error: COUNT_NOT_PLANNED]
    D -->|Yes| F[Snapshot system quantities]
    F --> G{Freeze requested?}
    G -->|Yes| H[Block stock movements for scope]
    H --> I[Create count lines for each item-location]
    G -->|No| I
    I --> J[Update status to IN_PROGRESS]
    J --> K[Return started count]
```

## External Dependencies

- None (internal models: [StockLevel](../models/StockLevel.md), [InventoryCountLine](../models/InventoryCountLine.md))

## Error Scenarios

- **COUNT_NOT_FOUND**: Referenced count does not exist
- **COUNT_NOT_PLANNED**: Count is not in PLANNED status

## Test Cases

- returns error when not found
- returns error when not planned
- starts count and snapshots quantities
- creates count lines for all items at location
- optionally freezes stock movements
