karrio-server-core 2025.5rc31__py3-none-any.whl → 2026.1.1__py3-none-any.whl

karrio/server/providers/models/service.py

@@ -8,6 +8,13 @@ import karrio.server.core.datatypes as datatypes
 
 @core.register_model
 class ServiceLevel(core.OwnedEntity):
+    """
+    Service level definition for rate sheet-based shipping.
+
+    Services reference shared zones and surcharges defined at the RateSheet level
+    via zone_ids and surcharge_ids. Rate values are stored in RateSheet.service_rates.
+    """
+
     class Meta:
         db_table = "service-level"
         verbose_name = "Service Level"
@@ -51,7 +58,41 @@ class ServiceLevel(core.OwnedEntity):
     domicile = models.BooleanField(null=True)
     international = models.BooleanField(null=True)
 
-    zones = models.JSONField(blank=True, null=True, default=core.field_default([]))
+    # ─────────────────────────────────────────────────────────────────
+    # VOLUMETRIC WEIGHT
+    # ─────────────────────────────────────────────────────────────────
+    max_volume = models.FloatField(
+        blank=True,
+        null=True,
+        help_text="Maximum volume in liters for volumetric weight calculation",
+    )
+
+    # ─────────────────────────────────────────────────────────────────
+    # COST TRACKING (internal - not shown to customer)
+    # ─────────────────────────────────────────────────────────────────
+    cost = models.FloatField(
+        blank=True,
+        null=True,
+        help_text="Base COGS (Cost of Goods Sold) - internal cost tracking",
+    )
+
+    # ─────────────────────────────────────────────────────────────────
+    # ZONE & SURCHARGE REFERENCES
+    # These reference shared definitions at the RateSheet level
+    # ─────────────────────────────────────────────────────────────────
+    zone_ids = models.JSONField(
+        blank=True,
+        null=True,
+        default=core.field_default([]),
+        help_text="List of zone IDs this service applies to: ['zone_1', 'zone_2']",
+    )
+    surcharge_ids = models.JSONField(
+        blank=True,
+        null=True,
+        default=core.field_default([]),
+        help_text="List of surcharge IDs to apply: ['surch_fuel', 'surch_residential']",
+    )
+
     metadata = models.JSONField(blank=True, null=True, default=core.field_default({}))
 
     def __str__(self):
@@ -60,133 +101,149 @@ class ServiceLevel(core.OwnedEntity):
     @property
     def object_type(self):
         return "service_level"
-    
-    @property 
-    def computed_zones(self):
+
+    @property
+    def rate_sheet(self):
+        """Get the rate sheet this service belongs to."""
+        return self.service_sheet.first()
+
+    @property
+    def zones(self):
+        """
+        Get zones as ServiceZone objects for SDK compatibility.
+
+        Transforms zone_ids + rate_sheet data into the ServiceZone format
+        expected by the RatingMixinProxy. Each service_rate entry becomes
+        a separate ServiceZone (supporting multiple weight brackets per zone).
         """
-        Computed property that returns zones in legacy format for backward compatibility.
-        If the service belongs to a rate sheet with optimized structure, reconstruct from there.
-        Otherwise, fall back to the service's own zones field.
+        _rate_sheet = self.rate_sheet
+        if not _rate_sheet:
+            return []
+
+        zones_by_id = {z.get("id"): z for z in (_rate_sheet.zones or [])}
+
+        # Get all service_rates for this service (may have multiple per zone_id for weight brackets)
+        service_rates = [
+            sr for sr in (_rate_sheet.service_rates or [])
+            if sr.get("service_id") == self.id
+            and sr.get("zone_id") in (self.zone_ids or [])
+        ]
+
+        result = []
+        for rate_data in service_rates:
+            zone_id = rate_data.get("zone_id")
+            zone_def = zones_by_id.get(zone_id)
+
+            if not zone_def:
+                continue
+
+            # Build ServiceZone-compatible dict (one per service_rate entry)
+            result.append({
+                "id": zone_id,
+                "label": zone_def.get("label"),
+                "rate": rate_data.get("rate"),
+                "cost": rate_data.get("cost"),
+                "min_weight": rate_data.get("min_weight"),
+                "max_weight": rate_data.get("max_weight"),
+                "transit_days": rate_data.get("transit_days") or zone_def.get("transit_days"),
+                "transit_time": rate_data.get("transit_time") or zone_def.get("transit_time"),
+                "country_codes": zone_def.get("country_codes") or [],
+                "postal_codes": zone_def.get("postal_codes") or [],
+                "cities": zone_def.get("cities") or [],
+                "radius": zone_def.get("radius"),
+                "latitude": zone_def.get("latitude"),
+                "longitude": zone_def.get("longitude"),
+            })
+
+        return result
+
+    @property
+    def surcharges(self):
         """
-        # Check if this service belongs to a rate sheet with optimized structure
-        rate_sheet = getattr(self, '_rate_sheet_cache', None)
+        Get surcharges as Surcharge objects for SDK compatibility.
+
+        Transforms surcharge_ids + rate_sheet data into the Surcharge format
+        expected by the RatingMixinProxy.
+        """
+        _rate_sheet = self.rate_sheet
+        if not _rate_sheet:
+            return []
+
+        surcharges_by_id = {s.get("id"): s for s in (_rate_sheet.surcharges or [])}
+
+        result = []
+        for surcharge_id in (self.surcharge_ids or []):
+            surcharge_def = surcharges_by_id.get(surcharge_id)
+            if not surcharge_def or not surcharge_def.get("active", True):
+                continue
+
+            result.append({
+                "id": surcharge_id,
+                "name": surcharge_def.get("name"),
+                "amount": surcharge_def.get("amount"),
+                "surcharge_type": surcharge_def.get("surcharge_type", "fixed"),
+                "cost": surcharge_def.get("cost"),
+                "active": surcharge_def.get("active", True),
+            })
+
+        return result
+
+    def get_rate_for_zone(self, zone_id: str) -> dict:
+        """
+        Get the rate for a specific zone from the parent rate sheet.
+
+        Returns:
+            dict: Rate data including rate, cost, min_weight, max_weight, transit_days
+        """
+        rate_sheet = self.rate_sheet
         if not rate_sheet:
-            # Try to find rate sheet this service belongs to
-            try:
-                rate_sheet = self.service_sheet.first()
-                self._rate_sheet_cache = rate_sheet
-            except:
-                rate_sheet = None
-        
-        if rate_sheet and rate_sheet.zones and rate_sheet.service_rates:
-            # Use optimized structure
-            return rate_sheet.get_service_zones_legacy(self.id)
-        else:
-            # Fall back to legacy zones field
-            return self.zones or []
-    
-    def update_zone_cell(self, zone_id: str, field: str, value):
-        """Update a single field in a zone by ID or index with validation"""
-        # Define allowed fields with their validators
-        allowed_fields = {
-            'rate': float,
-            'min_weight': float,
-            'max_weight': float,
-            'transit_days': int,
-            'transit_time': float,
-            'label': str,
-            'radius': float,
-            'latitude': float,
-            'longitude': float,
-        }
-        
-        if field not in allowed_fields:
-            raise ValueError(f"Field '{field}' is not allowed for zone updates")
-        
-        # Validate and convert the value
-        try:
-            if value is not None and value != '':
-                value = allowed_fields[field](value)
-        except (ValueError, TypeError):
-            raise ValueError(f"Invalid value '{value}' for field '{field}' (expected {allowed_fields[field].__name__})")
-        
-        zones = self.zones or []
-        
-        # First try to find by zone ID
-        for zone in zones:
-            if zone.get('id') == zone_id:
-                zone[field] = value
-                self.save(update_fields=['zones'])
-                return zone
-        
-        # Fallback: try to find by index for zones without IDs
-        try:
-            zone_index = int(zone_id)
-            if 0 <= zone_index < len(zones):
-                zones[zone_index][field] = value
-                self.save(update_fields=['zones'])
-                return zones[zone_index]
-        except (ValueError, IndexError):
-            pass
-        
-        raise ValueError(f"Zone {zone_id} not found")
-    
-    def batch_update_cells(self, updates: list):
+            return None
+        return rate_sheet.get_service_rate(self.id, zone_id)
+
+    def get_applicable_surcharges(self) -> list:
         """
-        Batch update multiple zone cells with validation
-        updates format: [{'zone_id': str, 'field': str, 'value': any}, ...]
+        Get the applicable surcharges from the parent rate sheet.
+
+        Returns:
+            list: List of surcharge definitions
         """
-        # Define allowed fields with their validators
-        allowed_fields = {
-            'rate': float,
-            'min_weight': float,
-            'max_weight': float,
-            'transit_days': int,
-            'transit_time': float,
-            'label': str,
-            'radius': float,
-            'latitude': float,
-            'longitude': float,
+        rate_sheet = self.rate_sheet
+        if not rate_sheet:
+            return []
+
+        surcharges = []
+        for surcharge_id in (self.surcharge_ids or []):
+            surcharge = rate_sheet.get_surcharge(surcharge_id)
+            if surcharge and surcharge.get('active', True):
+                surcharges.append(surcharge)
+        return surcharges
+
+    def calculate_rate(self, zone_id: str) -> tuple:
+        """
+        Calculate the total rate for a zone including surcharges.
+
+        Args:
+            zone_id: The zone ID to calculate rate for
+
+        Returns:
+            tuple: (total_rate, breakdown) where breakdown includes base rate and surcharges
+        """
+        rate_sheet = self.rate_sheet
+        if not rate_sheet:
+            return 0, []
+
+        # Get base rate for zone
+        rate_data = rate_sheet.get_service_rate(self.id, zone_id)
+        base_rate = float(rate_data.get('rate', 0)) if rate_data else 0
+
+        # Apply surcharges
+        total_rate, surcharge_breakdown = rate_sheet.apply_surcharges_to_rate(
+            base_rate, self.surcharge_ids or []
+        )
+
+        return total_rate, {
+            'base_rate': base_rate,
+            'base_cost': rate_data.get('cost') if rate_data else None,
+            'surcharges': surcharge_breakdown,
+            'total': total_rate,
         }
-        
-        zones = list(self.zones or [])
-        
-        for update in updates:
-            zone_id = update.get('zone_id')
-            field = update.get('field')
-            value = update.get('value')
-            
-            if field not in allowed_fields:
-                raise ValueError(f"Field '{field}' is not allowed for zone updates")
-            
-            # Validate and convert the value
-            try:
-                if value is not None and value != '':
-                    value = allowed_fields[field](value)
-            except (ValueError, TypeError):
-                raise ValueError(f"Invalid value '{value}' for field '{field}' (expected {allowed_fields[field].__name__})")
-            
-            # Find zone by ID first, then by index
-            zone_found = False
-            for zone in zones:
-                if zone.get('id') == zone_id:
-                    zone[field] = value
-                    zone_found = True
-                    break
-            
-            # Fallback to index if zone_id is numeric and zone not found by ID
-            if not zone_found:
-                try:
-                    zone_index = int(zone_id)
-                    if 0 <= zone_index < len(zones):
-                        zones[zone_index][field] = value
-                        zone_found = True
-                except (ValueError, IndexError):
-                    pass
-            
-            if not zone_found:
-                raise ValueError(f"Zone {zone_id} not found")
-
-        self.zones = zones
-        self.save(update_fields=['zones'])
-        return self.zones