@tailor-platform/erp-kit 0.0.1 → 0.1.0

package/src/modules/primitives/docs/commands/ConvertAmount.md

@@ -0,0 +1,50 @@
+# ConvertAmount
+
+## Overview
+
+ConvertAmount transforms a monetary amount from one currency to another using the applicable exchange rate for a given date. The function looks up the most recent exchange rate on or before the specified date and applies it to calculate the converted amount. The result is rounded according to the target currency's decimal precision.
+
+This function supports multi-currency operations including transaction recording, financial reporting, and consolidation.
+
+## Business Rules
+
+- Source and target currencies must both be active
+- Exchange rate lookup uses the most recent rate with effectiveDate <= conversionDate
+- Calculation: `result = amount x exchangeRate`
+- Result is rounded to the target currency's `decimalPlaces`
+- Same currency conversion (e.g., USD to USD) returns the original amount with rate of 1.0
+- If no direct rate exists, inverse rate may be calculated: `1 / reverseRate`
+- Amount must be non-negative (zero is allowed)
+- Forward rates are supported: if conversion date is in the future and a forward rate exists, it will be used
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive conversion request] --> B{Same currency?}
+    B -->|Yes| C[Return original amount]
+    B -->|No| D{Both currencies active?}
+    D -->|No| E[Return error: inactive currency]
+    D -->|Yes| F[Find rate for date]
+    F --> G{Direct rate found?}
+    G -->|Yes| H[Use direct rate]
+    G -->|No| I{Inverse rate found?}
+    I -->|Yes| J[Calculate inverse: 1/rate]
+    I -->|No| K[Return error: no rate available]
+    J --> H
+    H --> L[Calculate: amount x rate]
+    L --> M[Round to target decimal places]
+    M --> N[Return converted amount]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Inactive currency**: Either source or target currency is inactive - return error identifying the inactive currency
+- **No exchange rate**: No rate found for the currency pair on or before the specified date - return error with date and currency pair
+- **Invalid amount**: Negative amount provided - return validation error
+- **Currency not found**: Specified currency code/ID does not exist - return not found error
+- **Date in future**: Conversion date is in the future and no forward rate exists - return error or use most recent rate based on configuration

package/src/modules/primitives/docs/commands/ConvertQuantity.md

@@ -0,0 +1,43 @@
+# 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 - return error with message indicating the mismatch
+- **Inactive unit**: Either source or target unit is inactive - return error identifying the inactive unit
+- **Invalid quantity**: Negative quantity provided - return validation error (or allow based on configuration)
+- **Unit not found**: Specified unit ID does not exist - return not found error
+- **Overflow**: Calculation produces a number exceeding system limits - return overflow error

package/src/modules/primitives/docs/commands/CreateCategory.md

@@ -0,0 +1,44 @@
+# CreateCategory
+
+## Overview
+
+CreateCategory establishes a new unit of measure category that groups related units where conversions are meaningful. Each category must have a designated reference unit that serves as the base for all conversion calculations within that category. The reference unit is created simultaneously with the category and has a conversion factor of 1.0.
+
+This command supports initial system setup with standard categories (Unit, Weight, Volume, Length, Time) and business-specific category creation.
+
+## Business Rules
+
+- Category name must be unique across all categories (active and inactive)
+- Category name is required and must be non-empty
+- Reference unit must be specified at category creation time
+- Reference unit is created with conversion factor of 1.0
+- New categories are created in Active status by default
+- Category cannot exist without at least one unit (the reference unit)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create category request] --> B{Category name provided?}
+    B -->|No| C[Return error: missing name]
+    B -->|Yes| D{Category name unique?}
+    D -->|No| E[Return error: duplicate name]
+    D -->|Yes| F{Reference unit specified?}
+    F -->|No| G[Return error: missing reference unit]
+    F -->|Yes| H[Create category record]
+    H --> I[Create reference unit with factor 1.0]
+    I --> J[Link reference unit to category]
+    J --> K[Set category status: Active]
+    K --> L[Return created category with reference unit]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Missing category name**: Name not provided - return validation error
+- **Duplicate category name**: Category with same name already exists - return conflict error
+- **Missing reference unit**: No reference unit details provided - return validation error indicating reference unit is required
+- **Invalid reference unit**: Reference unit details are incomplete or invalid - return validation error with specific issues

package/src/modules/primitives/docs/commands/CreateCurrency.md

@@ -0,0 +1,47 @@
+# CreateCurrency
+
+## Overview
+
+CreateCurrency establishes a new monetary unit in the system with its ISO 4217 code, display symbol, name, and decimal precision. The first currency created automatically becomes the organization's base currency. Subsequent currencies are added as available currencies for multi-currency operations.
+
+This command supports initial system setup and market expansion scenarios where new trading currencies are needed.
+
+## Business Rules
+
+- ISO 4217 code must be exactly 3 uppercase letters
+- ISO 4217 code must be unique across all currencies (active and inactive)
+- Currency symbol is required and typically 1-3 characters
+- Decimal places must be a non-negative integer (0-4 typical range)
+- First currency created automatically becomes the base currency with `isBaseCurrency: true`
+- Subsequent currencies are created with `isBaseCurrency: false`
+- New currencies are created in Active status by default
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate ISO code format}
+    B -->|Invalid| C[Return error: invalid ISO code]
+    B -->|Valid| D{ISO code unique?}
+    D -->|No| E[Return error: duplicate code]
+    D -->|Yes| F{Validate decimal places}
+    F -->|Invalid| G[Return error: invalid decimal places]
+    F -->|Valid| H{Is first currency?}
+    H -->|Yes| I[Set as base currency]
+    H -->|No| J[Set isBaseCurrency: false]
+    I --> K[Create currency record]
+    J --> K
+    K --> L[Set status: Active]
+    L --> M[Return created currency]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Invalid ISO code format**: Code is not exactly 3 uppercase letters - return validation error with format requirements
+- **Duplicate ISO code**: Currency with same code already exists - return conflict error with existing currency reference
+- **Invalid decimal places**: Value is negative or exceeds maximum (typically 4) - return validation error with valid range
+- **Missing required fields**: Symbol or name not provided - return validation error listing missing fields

package/src/modules/primitives/docs/commands/CreateExchangeRate.md

@@ -0,0 +1,48 @@
+# CreateExchangeRate
+
+## Overview
+
+CreateExchangeRate establishes a new conversion ratio between a currency pair with a specific effective date. The rate specifies how many units of the target currency equal one unit of the source currency. Rates are date-based to support historical accuracy - transactions use the rate effective on their transaction date.
+
+This command supports daily rate updates, period-end rate recording, and forward rate entry for future-dated transactions.
+
+## Business Rules
+
+- Source and target currencies must both exist and be active
+- Source and target currencies must be different (no self-conversion rates)
+- Rate value must be a positive decimal number (greater than zero)
+- Effective date is required and determines when the rate becomes applicable
+- Future effective dates are allowed (forward rates)
+- Multiple rates for the same currency pair with different effective dates are allowed
+- When a rate for the same currency pair and effective date already exists, the new rate supersedes (append-only semantics)
+- Rate lookup uses the most recent rate with effectiveDate <= transaction date
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create rate request] --> B{Source currency exists and active?}
+    B -->|No| C[Return error: invalid source currency]
+    B -->|Yes| D{Target currency exists and active?}
+    D -->|No| E[Return error: invalid target currency]
+    D -->|Yes| F{Source != Target?}
+    F -->|No| G[Return error: same currency pair]
+    F -->|Yes| H{Rate value > 0?}
+    H -->|No| I[Return error: invalid rate value]
+    H -->|Yes| J{Effective date provided?}
+    J -->|No| K[Return error: missing effective date]
+    J -->|Yes| L[Create exchange rate record]
+    L --> M[Return created rate]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Invalid source currency**: Source currency does not exist or is inactive - return error identifying the currency
+- **Invalid target currency**: Target currency does not exist or is inactive - return error identifying the currency
+- **Same currency pair**: Source and target currencies are the same - return error indicating self-conversion is not allowed
+- **Invalid rate value**: Rate is zero, negative, or not a valid number - return validation error with acceptable range
+- **Missing effective date**: No effective date provided - return validation error indicating date is required

package/src/modules/primitives/docs/commands/CreateUnit.md

@@ -0,0 +1,48 @@
+# CreateUnit
+
+## Overview
+
+CreateUnit adds a new unit of measure to an existing category with its symbol, display name, and conversion factor relative to the category's reference unit. The conversion factor defines how many reference units equal one of this unit.
+
+This command supports adding industry-specific units (like "Pallet" or "Roll"), regional units (metric and imperial), and precision units for specialized tracking.
+
+## Business Rules
+
+- Target category must exist and be active
+- Unit symbol must be unique within the category
+- Unit symbol is required and typically 1-5 characters
+- Conversion factor must be a positive decimal number (greater than zero)
+- Rounding precision must be a non-negative integer
+- New units are created as non-reference units (only one reference unit per category)
+- The conversion formula is: `quantity_in_reference = quantity_in_this_unit × conversion_factor`
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create unit request] --> B{Category exists and active?}
+    B -->|No| C[Return error: invalid category]
+    B -->|Yes| D{Symbol provided?}
+    D -->|No| E[Return error: missing symbol]
+    D -->|Yes| F{Symbol unique in category?}
+    F -->|No| G[Return error: duplicate symbol]
+    F -->|Yes| H{Conversion factor > 0?}
+    H -->|No| I[Return error: invalid conversion factor]
+    H -->|Yes| J{Rounding precision valid?}
+    J -->|No| K[Return error: invalid rounding precision]
+    J -->|Yes| L[Create unit record]
+    L --> M[Link unit to category]
+    M --> N[Return created unit]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Invalid category**: Category does not exist or is inactive - return error identifying the category
+- **Missing symbol**: Unit symbol not provided - return validation error
+- **Duplicate symbol**: Unit with same symbol already exists in category - return conflict error
+- **Invalid conversion factor**: Factor is zero, negative, or not a valid number - return validation error
+- **Invalid rounding precision**: Precision is negative - return validation error with acceptable range

package/src/modules/primitives/docs/commands/DeactivateCategory.md

@@ -0,0 +1,38 @@
+# DeactivateCategory
+
+## Overview
+
+DeactivateCategory disables a UoM category from being used in new product assignments while preserving all historical data and existing product associations. This command supports scenarios such as discontinuing a measurement standard or consolidating categories.
+
+## Business Rules
+
+- Target category must exist in the system
+- Target category must be in Active status
+- Category with active units cannot be deactivated - all units must be deactivated first
+- Deactivating an already inactive category returns success with no state change
+- Historical transactions and products using this category's units are not affected
+- Deactivation prevents new products from being assigned units in this category
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Category exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Has active units?}
+    D -->|Yes| E[Return error: has active units]
+    D -->|No| F{Current status?}
+    F -->|Inactive| G[Return success: already inactive]
+    F -->|Active| H[Update status to Inactive]
+    H --> I[Return deactivated category]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Category not found**: Specified category ID does not exist - return not found error
+- **Has active units**: Category still contains active units - return error listing active units that must be deactivated first
+- **Invalid category ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/commands/DeactivateCurrency.md

@@ -0,0 +1,38 @@
+# DeactivateCurrency
+
+## Overview
+
+DeactivateCurrency disables a currency from being used in new transactions while preserving all historical data. This command supports scenarios such as market exit or currency obsolescence (e.g., legacy national currencies replaced by EUR). Deactivated currencies remain in the system for reporting and audit purposes.
+
+## Business Rules
+
+- Target currency must exist in the system
+- Target currency must be in Active status
+- Base currency cannot be deactivated - must first change base currency to another active currency
+- Deactivating an already inactive currency returns success with no state change
+- Historical transactions using this currency are not affected
+- Deactivation prevents the currency from being used in new transactions, exchange rates, or price lists
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Currency exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Is base currency?}
+    D -->|Yes| E[Return error: cannot deactivate base currency]
+    D -->|No| F{Current status?}
+    F -->|Inactive| G[Return success: already inactive]
+    F -->|Active| H[Update status to Inactive]
+    H --> I[Return deactivated currency]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Currency not found**: Specified currency ID does not exist - return not found error
+- **Base currency protection**: Attempting to deactivate the base currency - return error indicating base currency must be changed first
+- **Invalid currency ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/commands/DeactivateUnit.md

@@ -0,0 +1,38 @@
+# DeactivateUnit
+
+## Overview
+
+DeactivateUnit disables a unit of measure from being used in new product assignments and quantity conversions while preserving all historical data. This command supports scenarios such as discontinuing a measurement unit or consolidating units within a category.
+
+## Business Rules
+
+- Target unit must exist in the system
+- Target unit must be in Active status
+- Reference unit cannot be deactivated - must first change reference unit to another active unit in the category
+- Deactivating an already inactive unit returns success with no state change
+- Historical transactions and products using this unit are not affected
+- Deactivation prevents the unit from being used in new product assignments or conversions
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Unit exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Is reference unit?}
+    D -->|Yes| E[Return error: cannot deactivate reference unit]
+    D -->|No| F{Current status?}
+    F -->|Inactive| G[Return success: already inactive]
+    F -->|Active| H[Update status to Inactive]
+    H --> I[Return deactivated unit]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Unit not found**: Specified unit ID does not exist - return not found error
+- **Reference unit protection**: Attempting to deactivate the category's reference unit - return error indicating reference unit must be changed first
+- **Invalid unit ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/commands/SetBaseCurrency.md

@@ -0,0 +1,39 @@
+# SetBaseCurrency
+
+## Overview
+
+SetBaseCurrency changes the organization's base currency to a different active currency. The base currency serves as the default for financial reporting, consolidation, and serves as the reference point for exchange rate conversions. This command supports scenarios such as corporate restructuring or relocating headquarters to a different country.
+
+## Business Rules
+
+- Target currency must exist in the system
+- Target currency must be in Active status
+- Only one currency can be base currency at a time
+- Setting the current base currency as base returns success with no change
+- Previous base currency remains active but loses base currency designation
+- Exchange rates may need to be recalculated or new rates added after changing base currency
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive set base request] --> B{Currency exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Currency active?}
+    D -->|No| E[Return error: cannot set inactive currency as base]
+    D -->|Yes| F{Already base currency?}
+    F -->|Yes| G[Return success: no change needed]
+    F -->|No| H[Remove base flag from current base]
+    H --> I[Set base flag on target currency]
+    I --> J[Return updated currency]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Currency not found**: Specified currency ID does not exist - return not found error
+- **Inactive currency**: Target currency is not in Active status - return error indicating currency must be activated first
+- **Invalid currency ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/commands/SetReferenceUnit.md

@@ -0,0 +1,43 @@
+# SetReferenceUnit
+
+## Overview
+
+SetReferenceUnit changes the reference unit for a UoM category to a different unit within the same category. When the reference unit changes, all conversion factors in the category are automatically recalculated relative to the new reference. The new reference unit's conversion factor becomes 1.0.
+
+This command supports scenarios where business requirements change and a different unit becomes the standard for measurement.
+
+## Business Rules
+
+- Target unit must exist and belong to the specified category
+- Target unit must be in the same category as the current reference unit
+- Setting the current reference unit as reference returns success with no change
+- When reference unit changes, the new reference unit's conversion factor becomes 1.0
+- All other units' conversion factors are recalculated: `new_factor = old_factor / new_reference_old_factor`
+- Historical conversion calculations are not affected (they used the factors at time of calculation)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive set reference request] --> B{Unit exists?}
+    B -->|No| C[Return error: unit not found]
+    B -->|Yes| D{Unit in specified category?}
+    D -->|No| E[Return error: unit not in category]
+    D -->|Yes| F{Already reference unit?}
+    F -->|Yes| G[Return success: no change needed]
+    F -->|No| H[Get new unit's current factor]
+    H --> I[Recalculate all unit factors]
+    I --> J[Set new unit factor to 1.0]
+    J --> K[Update category reference unit pointer]
+    K --> L[Return updated category]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **Unit not found**: Specified unit ID does not exist - return not found error
+- **Unit not in category**: Unit belongs to a different category than specified - return error with category mismatch details
+- **Invalid unit ID**: Malformed or empty ID provided - return validation error

package/src/modules/primitives/docs/features/currency-definitions.md

@@ -0,0 +1,55 @@
+# Currency Definitions
+
+## Overview
+
+Currency Definitions establish the monetary units available for use across the ERP system. Each currency record contains the ISO 4217 code, display symbol, name, and decimal precision. One currency is designated as the base currency for the organization, serving as the default for reporting and consolidation.
+
+This feature provides the foundation for all multi-currency operations in sales, purchasing, and accounting.
+
+## Business Purpose
+
+Organizations operating internationally need to:
+
+- Record transactions in the customer's or vendor's preferred currency
+- Convert amounts to a consistent base currency for financial reporting
+- Display currency symbols and format amounts correctly by locale
+- Handle currencies with different decimal precisions (e.g., JPY has 0 decimals, USD has 2)
+
+Currency definitions ensure consistent monetary handling across all business operations.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Define Currency] --> B{Is First Currency?}
+    B -->|Yes| C[Set as Base Currency]
+    B -->|No| D[Add to Available Currencies]
+    C --> E[Currency Active]
+    D --> E
+    E --> F[Available for Transactions]
+    F --> G[Products Can Set Prices]
+    F --> H[Orders Can Use Currency]
+    F --> I[Exchange Rates Can Reference]
+```
+
+## Scenario Patterns
+
+- **Initial Setup**: Administrator defines base currency (e.g., USD) and common trading currencies (EUR, GBP, JPY) during system initialization
+- **Market Expansion**: Business enters new market and adds local currency (e.g., BRL for Brazil expansion)
+- **Currency Deactivation**: Obsolete currency (e.g., legacy national currency replaced by EUR) is deactivated to prevent new transactions while preserving historical data
+- **Precision Configuration**: Cryptocurrency or precious metal tracking requires higher decimal precision than standard currencies
+
+## Test Cases
+
+- Creating a currency with valid ISO 4217 code should succeed
+- Currency codes must be unique (no duplicate USD)
+- First currency created should automatically become base currency
+- Changing base currency should be allowed only with proper authorization
+- Deactivating the base currency should be prevented
+- Currency with active transactions should not be deletable (only deactivatable)
+- Decimal places must be non-negative integer (0-4 typical range)
+
+## Reference Links
+
+- [ISO 4217 Currency Codes](https://www.iso.org/iso-4217-currency-codes.html)
+- [Unicode CLDR Currency Data](https://cldr.unicode.org/index/downloads)

package/src/modules/primitives/docs/features/exchange-rates.md

@@ -0,0 +1,61 @@
+# Exchange Rates
+
+## Overview
+
+Exchange Rates maintain the conversion ratios between currency pairs with effective dates. Each rate record specifies the source currency, target currency, rate value, and the date from which it applies. The system uses these rates to convert monetary amounts for transactions, reporting, and consolidation.
+
+Rates are date-based to support historical accuracy - a transaction from last month uses last month's rate, not today's rate.
+
+## Business Purpose
+
+Multi-currency operations require accurate exchange rate management:
+
+- **Transaction Recording**: Convert foreign currency invoices to base currency at booking time
+- **Financial Reporting**: Consolidate subsidiaries using period-end rates
+- **Historical Accuracy**: Audit trail requires rates as of transaction date
+- **Variance Analysis**: Compare budgeted rates vs actual rates for currency exposure
+
+Exchange rates ensure monetary consistency while maintaining complete audit traceability.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Exchange Rate] --> B[Set Currency Pair]
+    B --> C[Set Rate Value]
+    C --> D[Set Effective Date]
+    D --> E{Validate Rate}
+    E -->|Invalid| F[Return Error]
+    E -->|Valid| G[Save Rate]
+    G --> H[Rate Available for Date Range]
+
+    I[Convert Amount] --> J[Find Rate for Date]
+    J --> K{Rate Found?}
+    K -->|No| L[Return Error or Use Fallback]
+    K -->|Yes| M[Apply Rate × Amount]
+    M --> N[Return Converted Amount]
+```
+
+## Scenario Patterns
+
+- **Daily Rate Updates**: Finance team updates rates daily from central bank or market data feed
+- **Period-End Rates**: Month-end closing uses official rates for consolidation
+- **Historical Lookup**: Generating report for Q1 uses Q1 rates, not current rates
+- **Rate Gap Handling**: Transaction on holiday uses most recent prior rate when exact date unavailable
+- **Inverse Calculation**: Rate for USD→EUR automatically provides EUR→USD by inversion
+
+## Test Cases
+
+- Creating rate with valid currency pair and positive rate should succeed
+- Rate with zero or negative value should fail validation
+- Rate effective date in far future should be allowed (forward rates)
+- Looking up rate for date should return most recent rate on or before that date
+- Looking up rate with no prior rate should return error or configurable fallback
+- Same currency conversion (USD→USD) should return rate of 1.0
+- Inverse rate calculation should be mathematically correct (1/rate)
+- Updating existing rate for same date should replace previous value
+
+## Reference Links
+
+- [European Central Bank Exchange Rates](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html)
+- [Open Exchange Rates API](https://openexchangerates.org/)

package/src/modules/primitives/docs/features/unit-conversion.md

@@ -0,0 +1,66 @@
+# Unit Conversion
+
+## Overview
+
+Unit Conversion enables automatic quantity transformation between any two units within the same category. The conversion uses the reference unit as an intermediary, ensuring consistent results regardless of which units are involved. This feature supports the core ERP operations where quantities must be expressed in different units for purchasing, inventory, and sales.
+
+Conversions include configurable rounding precision to match business requirements for different unit types.
+
+## Business Purpose
+
+Different stakeholders work with different units:
+
+- **Purchasing** buys in bulk units (cases, pallets, drums)
+- **Warehouse** tracks in standardized units (pieces, kilograms, liters)
+- **Sales** sells in customer-friendly units (packs, bottles, individual items)
+- **Manufacturing** measures in precise units (grams, milliliters)
+
+Unit conversion eliminates manual calculation errors and ensures inventory accuracy when the same product moves through these different contexts.
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Conversion Request] --> B{Same Category?}
+    B -->|No| C[Return Error: Incompatible Units]
+    B -->|Yes| D[Get Source Unit Factor]
+    D --> E[Get Target Unit Factor]
+    E --> F[Calculate: Qty × Source Factor ÷ Target Factor]
+    F --> G[Apply Rounding Precision]
+    G --> H[Return Converted Quantity]
+
+    subgraph Validation
+    B
+    end
+
+    subgraph Calculation
+    D
+    E
+    F
+    G
+    end
+```
+
+## Scenario Patterns
+
+- **Purchase to Inventory**: Vendor ships 10 cases (12 units/case), system records 120 pieces in inventory
+- **Sales Order Fulfillment**: Customer orders 5 kg, warehouse picks 5000 grams from bin tracked in grams
+- **Manufacturing Consumption**: Recipe calls for 500ml, inventory deducts 0.5 liters from stock
+- **Cross-Unit Reporting**: Generate report showing total weight in both kilograms and pounds for different markets
+- **Fractional Handling**: Order for 2.5 dozen converts to 30 pieces for picking
+
+## Test Cases
+
+- Converting between units in the same category should return correct result
+- Converting between units in different categories should return an error
+- Converting with the same source and target unit should return the original quantity
+- Converting to/from the reference unit should use factor of 1.0
+- Rounding should respect the target unit's precision setting
+- Zero quantity conversion should return zero
+- Negative quantity conversion should be handled consistently (error or allow based on business rules)
+- Very large quantities should not cause overflow errors
+
+## Reference Links
+
+- [NIST Unit Conversion Guide](https://www.nist.gov/pml/owm/metric-si/unit-conversion)
+- [Odoo UoM Conversion Documentation](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/product_management/configure/uom.html)