feat(catalogues): enhance UOM validation with dedicated validator service

- Replace generic unit field with uom_group_id in Inventory schema for UUID-based validation
- Add uom_group_code format validation using regex pattern (UOM-XXX-NNNNNN)
- Create new UOMValidator service class for centralized UOM group validation
- Implement _validate_uom_group method in CatalogueService for create and update operations
- Add UOM group validation checks during catalogue creation and updates
- Improve error handling and logging for UOM validation failures
- Ensure UOM consistency across catalogue, inventory, and purchase modules

app/catalogues/schemas/schema.py

@@ -428,7 +428,7 @@ class InventoryLevel(BaseModel):
 
 
 class Inventory(BaseModel):
-    unit: str = Field("PCS", description="Unit of measurement (validated against UOM master)")
+    uom_group_id: Optional[str] = Field(None, description="UOM group UUID")
     uom_group_code: Optional[str] = Field(None, description="UOM group code (e.g., UOM-VOL-000001, UOM-WGT-000001)")
     levels: Optional[Dict[str, InventoryLevel]] = Field(
         None, 
@@ -454,14 +454,17 @@ class Inventory(BaseModel):
         description="Legacy: Warehouse location code"
     )
 
-    @field_validator("unit")
-    def validate_unit(cls, v):
-        """Normalize unit code - actual validation against UOM master happens at service level"""
+    @field_validator("uom_group_id")
+    def validate_uom_group_id(cls, v):
+        """Validate UOM group ID format (UUID)"""
         if v:
-            v = v.strip().upper()
+            v = v.strip()
             if not v:
-                return "PCS"  # Default fallback
-        return v or "PCS"
+                return None
+            # Basic UUID format validation (will be validated against UOM master at service level)
+            if len(v) < 10:
+                raise ValueError("UOM group ID must be a valid UUID")
+        return v
 
     @field_validator("uom_group_code")
     def validate_uom_group_code(cls, v):
@@ -470,6 +473,9 @@ class Inventory(BaseModel):
             v = v.strip().upper()
             if not v:
                 return None
+            # Basic format validation (UOM-XXX-NNNNNN)
+            if not re.match(r"^UOM-[A-Z]{3}-\d{6}$", v):
+                logger.warning(f"UOM group code '{v}' doesn't match expected format UOM-XXX-NNNNNN")
         return v
 
     @field_validator("levels")

app/catalogues/services/service.py

@@ -99,6 +99,23 @@ class CatalogueService:
         
         return len(valid_categories) == 0  # Allow if no categories defined in taxonomy
 
+    async def _validate_uom_group(self, uom_group_id: str = None, uom_group_code: str = None) -> bool:
+        """
+        Validate UOM group against UOM master data.
+        """
+        if not uom_group_id and not uom_group_code:
+            return True  # No UOM specified is valid
+        
+        try:
+            from app.catalogues.uom_validator import UOMValidator
+            validator = UOMValidator(self.db)
+            await validator.validate_uom_group(uom_group_id, uom_group_code)
+            return True
+            
+        except Exception as e:
+            # Re-raise the exception from the validator
+            raise e
+
     async def get_brand_suggestions(self, partial: str, merchant_id: str = None) -> List[str]:
         """
         Get brand suggestions for partial input from taxonomy data.
@@ -300,6 +317,11 @@ class CatalogueService:
                         detail=str(e)
                     )
 
+            # Validate UOM group if provided
+            if data.inventory and (data.inventory.uom_group_id or data.inventory.uom_group_code):
+                await self._validate_uom_group(data.inventory.uom_group_id, data.inventory.uom_group_code)
+                    )
+
             # Validate inventory levels against merchant's allowed levels
             if data.inventory and data.inventory.levels and merchant_id:
                 from app.catalogues.utils import validate_inventory_levels_for_merchant
@@ -399,6 +421,15 @@ class CatalogueService:
                             detail=str(e)
                         )
 
+            # Validate UOM group if being updated
+            if "inventory" in update_data and update_data["inventory"]:
+                inventory_data = update_data["inventory"]
+                if isinstance(inventory_data, dict):
+                    uom_group_id = inventory_data.get("uom_group_id")
+                    uom_group_code = inventory_data.get("uom_group_code")
+                    if uom_group_id or uom_group_code:
+                        await self._validate_uom_group(uom_group_id, uom_group_code)
+
             # Validate inventory levels if being updated
             if "inventory" in update_data and update_data["inventory"] and merchant_id:
                 inventory_data = update_data["inventory"]

app/catalogues/uom_validator.py

@@ -0,0 +1,340 @@
+"""
+UOM Validation Utility for Catalogue Integration
+Validates UOM consistency across catalogue, inventory, and purchase operations.
+"""
+
+import logging
+from typing import Optional, Dict, Any, List
+from fastapi import HTTPException, status
+from motor.core import AgnosticDatabase as AsyncIOMotorDatabase
+
+from app.uom.constants import SCM_UOM_GROUP_COLLECTION
+from app.catalogues.constants import SCM_CATALOGUE_COLLECTION
+
+logger = logging.getLogger(__name__)
+
+
+class UOMValidator:
+    """
+    Centralized UOM validation service for catalogue operations.
+    Ensures UOM consistency across catalogue, inventory, and purchase modules.
+    """
+    
+    def __init__(self, db: AsyncIOMotorDatabase):
+        self.db = db
+        self.uom_collection = db[SCM_UOM_GROUP_COLLECTION]
+        self.catalogue_collection = db[SCM_CATALOGUE_COLLECTION]
+    
+    async def validate_uom_group(self, uom_group_id: str = None, uom_group_code: str = None) -> Dict[str, Any]:
+        """
+        Validate UOM group exists and is active.
+        
+        Args:
+            uom_group_id: UOM group UUID
+            uom_group_code: UOM group code (e.g., UOM-VOL-000001)
+            
+        Returns:
+            UOM group document if valid
+            
+        Raises:
+            HTTPException: If UOM group is invalid or not found
+        """
+        if not uom_group_id and not uom_group_code:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Either uom_group_id or uom_group_code must be provided"
+            )
+        
+        try:
+            # Build query based on available identifiers
+            query = {"status": "active"}
+            if uom_group_id:
+                query["uom_group_id"] = uom_group_id
+            elif uom_group_code:
+                query["uom_group_code"] = uom_group_code
+            
+            # Check if UOM group exists and is active
+            uom_group = await self.uom_collection.find_one(query)
+            
+            if not uom_group:
+                error_msg = "UOM group not found or inactive"
+                if uom_group_id:
+                    error_msg += f" (ID: {uom_group_id})"
+                if uom_group_code:
+                    error_msg += f" (Code: {uom_group_code})"
+                
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=error_msg
+                )
+            
+            logger.debug(f"UOM group validated: {uom_group.get('name')} ({uom_group.get('uom_group_code')})")
+            return uom_group
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error validating UOM group: {e}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Error validating UOM group"
+            )
+    
+    async def validate_unit_in_group(self, unit_code: str, uom_group_id: str = None, uom_group_code: str = None) -> bool:
+        """
+        Validate that a unit code exists in the specified UOM group.
+        
+        Args:
+            unit_code: Unit code to validate (e.g., 'ml', 'g', 'pcs')
+            uom_group_id: UOM group UUID
+            uom_group_code: UOM group code
+            
+        Returns:
+            True if unit is valid in the group
+            
+        Raises:
+            HTTPException: If validation fails
+        """
+        if not unit_code:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Unit code is required"
+            )
+        
+        # First validate the UOM group
+        uom_group = await self.validate_uom_group(uom_group_id, uom_group_code)
+        
+        # Check if unit exists in the group
+        units = uom_group.get("units", [])
+        unit_codes = [unit.get("code", "").lower() for unit in units if unit.get("status") == "active"]
+        
+        if unit_code.lower() not in unit_codes:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail=f"Unit '{unit_code}' is not valid for UOM group '{uom_group.get('name')}'. Valid units: {', '.join(unit_codes)}"
+            )
+        
+        logger.debug(f"Unit '{unit_code}' validated in UOM group '{uom_group.get('name')}'")
+        return True
+    
+    async def validate_catalogue_uom_consistency(self, catalogue_id: str, unit_code: str) -> bool:
+        """
+        Validate that a unit code is consistent with the catalogue's UOM group.
+        
+        Args:
+            catalogue_id: Catalogue UUID
+            unit_code: Unit code to validate
+            
+        Returns:
+            True if unit is consistent with catalogue's UOM group
+            
+        Raises:
+            HTTPException: If validation fails
+        """
+        if not catalogue_id or not unit_code:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Both catalogue_id and unit_code are required"
+            )
+        
+        try:
+            # Get catalogue document
+            catalogue = await self.catalogue_collection.find_one({"catalogue_id": catalogue_id})
+            
+            if not catalogue:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"Catalogue not found: {catalogue_id}"
+                )
+            
+            # Extract UOM group information from catalogue
+            uom_group_id = None
+            uom_group_code = None
+            
+            # Check inventory section first
+            if "inventory" in catalogue and catalogue["inventory"]:
+                inventory = catalogue["inventory"]
+                uom_group_id = inventory.get("uom_group_id")
+                uom_group_code = inventory.get("uom_group_code")
+            
+            # Fallback to root level
+            if not uom_group_id and not uom_group_code:
+                uom_group_id = catalogue.get("uom_group_id")
+                uom_group_code = catalogue.get("uom_group_code")
+            
+            # If no UOM group is specified, allow any unit (backward compatibility)
+            if not uom_group_id and not uom_group_code:
+                logger.warning(f"Catalogue {catalogue_id} has no UOM group specified, allowing unit '{unit_code}'")
+                return True
+            
+            # Validate unit against the catalogue's UOM group
+            return await self.validate_unit_in_group(unit_code, uom_group_id, uom_group_code)
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error validating catalogue UOM consistency: {e}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Error validating catalogue UOM consistency"
+            )
+    
+    async def get_valid_units_for_catalogue(self, catalogue_id: str) -> List[Dict[str, Any]]:
+        """
+        Get list of valid units for a catalogue based on its UOM group.
+        
+        Args:
+            catalogue_id: Catalogue UUID
+            
+        Returns:
+            List of valid unit dictionaries with code, name, and conversion info
+            
+        Raises:
+            HTTPException: If catalogue not found
+        """
+        try:
+            # Get catalogue document
+            catalogue = await self.catalogue_collection.find_one({"catalogue_id": catalogue_id})
+            
+            if not catalogue:
+                raise HTTPException(
+                    status_code=status.HTTP_404_NOT_FOUND,
+                    detail=f"Catalogue not found: {catalogue_id}"
+                )
+            
+            # Extract UOM group information
+            uom_group_id = None
+            uom_group_code = None
+            
+            if "inventory" in catalogue and catalogue["inventory"]:
+                inventory = catalogue["inventory"]
+                uom_group_id = inventory.get("uom_group_id")
+                uom_group_code = inventory.get("uom_group_code")
+            
+            if not uom_group_id and not uom_group_code:
+                uom_group_id = catalogue.get("uom_group_id")
+                uom_group_code = catalogue.get("uom_group_code")
+            
+            # If no UOM group specified, return empty list
+            if not uom_group_id and not uom_group_code:
+                return []
+            
+            # Get UOM group and return active units
+            uom_group = await self.validate_uom_group(uom_group_id, uom_group_code)
+            units = uom_group.get("units", [])
+            
+            # Filter active units and return relevant information
+            valid_units = []
+            for unit in units:
+                if unit.get("status") == "active":
+                    valid_units.append({
+                        "code": unit.get("code"),
+                        "name": unit.get("name"),
+                        "conversion_to_base": unit.get("conversion_to_base"),
+                        "is_base": unit.get("is_base", False)
+                    })
+            
+            return valid_units
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error getting valid units for catalogue: {e}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Error getting valid units for catalogue"
+            )
+    
+    async def convert_quantity(self, from_unit: str, to_unit: str, quantity: float, uom_group_id: str = None, uom_group_code: str = None) -> float:
+        """
+        Convert quantity from one unit to another within the same UOM group.
+        
+        Args:
+            from_unit: Source unit code
+            to_unit: Target unit code
+            quantity: Quantity to convert
+            uom_group_id: UOM group UUID
+            uom_group_code: UOM group code
+            
+        Returns:
+            Converted quantity
+            
+        Raises:
+            HTTPException: If conversion fails
+        """
+        if from_unit.lower() == to_unit.lower():
+            return quantity
+        
+        try:
+            # Get UOM group
+            uom_group = await self.validate_uom_group(uom_group_id, uom_group_code)
+            units = uom_group.get("units", [])
+            
+            # Find conversion factors
+            from_conversion = None
+            to_conversion = None
+            
+            for unit in units:
+                if unit.get("code", "").lower() == from_unit.lower() and unit.get("status") == "active":
+                    from_conversion = unit.get("conversion_to_base")
+                elif unit.get("code", "").lower() == to_unit.lower() and unit.get("status") == "active":
+                    to_conversion = unit.get("conversion_to_base")
+            
+            if from_conversion is None:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Source unit '{from_unit}' not found in UOM group"
+                )
+            
+            if to_conversion is None:
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST,
+                    detail=f"Target unit '{to_unit}' not found in UOM group"
+                )
+            
+            # Convert: quantity * from_conversion / to_conversion
+            converted_quantity = (quantity * from_conversion) / to_conversion
+            
+            logger.debug(f"Converted {quantity} {from_unit} to {converted_quantity} {to_unit}")
+            return converted_quantity
+            
+        except HTTPException:
+            raise
+        except Exception as e:
+            logger.error(f"Error converting quantity: {e}")
+            raise HTTPException(
+                status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                detail="Error converting quantity"
+            )
+
+
+# Convenience functions for easy import
+async def validate_catalogue_uom(db: AsyncIOMotorDatabase, catalogue_id: str, unit_code: str) -> bool:
+    """
+    Convenience function to validate UOM consistency for a catalogue.
+    
+    Args:
+        db: MongoDB database instance
+        catalogue_id: Catalogue UUID
+        unit_code: Unit code to validate
+        
+    Returns:
+        True if valid
+    """
+    validator = UOMValidator(db)
+    return await validator.validate_catalogue_uom_consistency(catalogue_id, unit_code)
+
+
+async def get_catalogue_valid_units(db: AsyncIOMotorDatabase, catalogue_id: str) -> List[Dict[str, Any]]:
+    """
+    Convenience function to get valid units for a catalogue.
+    
+    Args:
+        db: MongoDB database instance
+        catalogue_id: Catalogue UUID
+        
+    Returns:
+        List of valid units
+    """
+    validator = UOMValidator(db)
+    return await validator.get_valid_units_for_catalogue(catalogue_id)

app/sync/catalogues/handler.py

@@ -371,8 +371,20 @@ class CatalogueSyncHandler(SyncHandler):
         if "inventory" in entity and entity["inventory"]:
             inventory = entity["inventory"]
             flattened["track_inventory"] = inventory.get("track_inventory", False)
+            
+            # Extract UOM information from inventory
+            flattened["uom_group_id"] = inventory.get("uom_group_id")
+            flattened["uom_group_code"] = inventory.get("uom_group_code")
         else:
             flattened["track_inventory"] = False
+            flattened["uom_group_id"] = None
+            flattened["uom_group_code"] = None
+        
+        # Also check for UOM fields at root level (fallback)
+        if flattened.get("uom_group_id") is None:
+            flattened["uom_group_id"] = entity.get("uom_group_id")
+        if flattened.get("uom_group_code") is None:
+            flattened["uom_group_code"] = entity.get("uom_group_code")
         
         # Extract from procurement (batch_managed)
         if "procurement" in entity and entity["procurement"]:
@@ -512,13 +524,15 @@ class CatalogueSyncHandler(SyncHandler):
                         UNION SELECT 'category'
                         UNION SELECT 'pricing'
                         UNION SELECT 'updated_at'
+                        UNION SELECT 'uom_group_id'
+                        UNION SELECT 'uom_group_code'
                     ) expected_cols
                     WHERE column_name NOT IN (
                         SELECT column_name 
                         FROM information_schema.columns 
                         WHERE table_schema = 'trans' 
                           AND table_name = 'catalogue_ref'
-                          AND column_name IN ('catalogue_code', 'brand', 'category', 'pricing', 'updated_at')
+                          AND column_name IN ('catalogue_code', 'brand', 'category', 'pricing', 'updated_at', 'uom_group_id', 'uom_group_code')
                     )
                 """)
                 

app/sync/catalogues/models.py

@@ -18,6 +18,7 @@ CATALOGUE_FIELD_MAPPING = {
     "base_price": "base_price",            # NUMERIC(12,2)
     "track_inventory": "track_inventory",   # BOOLEAN
     "batch_managed": "batch_managed",       # BOOLEAN
+    "uom_group_id": "uom_group_id",        # UUID
     "uom_group_code": "uom_group_code",    # TEXT
     "status": "status",                     # TEXT NOT NULL
     "created_at": "created_at",            # TIMESTAMP NOT NULL