# ConvertQuantity

## Overview

ConvertQuantity transforms a quantity from one unit of measure to another within the same category. The conversion uses the category's reference unit as an intermediary, calculating: `result = quantity x sourceConversionFactor / targetConversionFactor`. The result is rounded according to the target unit's precision setting.

This function supports core ERP operations where quantities must be expressed in different units for purchasing, inventory, and sales.

## Business Rules

- Source and target units must belong to the same UoMCategory
- Quantity must be a non-negative number (zero is allowed)
- Conversion factor calculation: `result = quantity x (sourceUnit.conversionFactor / targetUnit.conversionFactor)`
- Result is rounded to the target unit's `roundingPrecision` decimal places
- Converting between the same unit returns the original quantity
- Both units must be active

## Process Flow

```mermaid
flowchart TD
    A[Receive conversion request] --> B{Same category?}
    B -->|No| C[Return error: incompatible units]
    B -->|Yes| D{Both units active?}
    D -->|No| E[Return error: inactive unit]
    D -->|Yes| F[Get source unit factor]
    F --> G[Get target unit factor]
    G --> H[Calculate: qty x sourceFactor / targetFactor]
    H --> I[Apply target unit rounding precision]
    I --> J[Return converted quantity]
```

## External Dependencies

- None

## Error Scenarios

- **INCOMPATIBLE_UNITS**: Source and target units belong to different categories
- **INACTIVE_UNIT**: Either source or target unit is inactive
- **UNIT_NOT_FOUND**: Specified unit ID does not exist

## Test Cases

- returns error when source unit doesn't exist
- returns error when target unit doesn't exist
- returns error when source unit is inactive
- returns error when target unit is inactive
- returns error when units belong to different categories
- returns same quantity when source and target are the same unit
- converts kg to grams correctly
- converts grams to kg correctly
- converts pounds to kg correctly
- handles zero quantity correctly