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

karrio/server/providers/models/sheet.py

@@ -10,6 +10,16 @@ _ = translation.gettext_lazy
 
 @core.register_model
 class RateSheet(core.OwnedEntity):
+    """
+    Rate sheet with shared zones, surcharges, and service-zone rate mappings.
+
+    Structure:
+    - zones: Shared geographic zone definitions
+    - surcharges: Shared surcharge definitions (fuel, handling, etc.)
+    - service_rates: Service-zone rate mappings with weights and transit times
+    - services: Service level definitions that reference zones/surcharges by ID
+    """
+
     class Meta:
         db_table = "rate-sheet"
         verbose_name = "Rate Sheet"
@@ -29,22 +39,40 @@ class RateSheet(core.OwnedEntity):
     services = models.ManyToManyField(
         "ServiceLevel", blank=True, related_name="service_sheet"
     )
-    
-    # New optimized structure
+
+    # ─────────────────────────────────────────────────────────────────
+    # SHARED ZONE DEFINITIONS
+    # Structure: [{'id': 'zone_1', 'label': 'Zone 1', 'country_codes': [...], 'cities': [...], 'postal_codes': [...], 'transit_days': int}]
+    # ─────────────────────────────────────────────────────────────────
     zones = models.JSONField(
         blank=True,
         null=True,
         default=core.field_default([]),
-        help_text="Shared zone definitions: [{'id': 'zone_1', 'label': 'Zone 1', 'cities': [...], 'country_codes': [...]}]"
+        help_text="Shared zone definitions: [{'id': 'zone_1', 'label': 'Zone 1', 'cities': [...], 'country_codes': [...]}]",
+    )
+
+    # ─────────────────────────────────────────────────────────────────
+    # SHARED SURCHARGE DEFINITIONS
+    # Structure: [{'id': 'surch_1', 'name': 'Fuel', 'amount': 8.5, 'surcharge_type': 'percentage', 'cost': 5.2, 'active': true}]
+    # ─────────────────────────────────────────────────────────────────
+    surcharges = models.JSONField(
+        blank=True,
+        null=True,
+        default=core.field_default([]),
+        help_text="Shared surcharge definitions: [{'id': 'surch_1', 'name': 'Fuel', 'amount': 8.5, 'surcharge_type': 'percentage'}]",
     )
+
+    # ─────────────────────────────────────────────────────────────────
+    # SERVICE-ZONE RATE MAPPING
+    # Structure: [{'service_id': 'svc_1', 'zone_id': 'zone_1', 'rate': 10.50, 'cost': 8.00, 'min_weight': 0, 'max_weight': 5}]
+    # ─────────────────────────────────────────────────────────────────
     service_rates = models.JSONField(
         blank=True,
         null=True,
         default=core.field_default([]),
-        help_text="Service-zone rate mapping: [{'service_id': 'svc_1', 'zone_id': 'zone_1', 'rate': 10.50}]"
+        help_text="Service-zone rate mapping: [{'service_id': 'svc_1', 'zone_id': 'zone_1', 'rate': 10.50}]",
     )
-    
-    # Keep old structure for backward compatibility during migration
+
     metadata = models.JSONField(
         blank=True,
         null=True,
@@ -74,214 +102,330 @@ class RateSheet(core.OwnedEntity):
         return providers.Carrier.objects.filter(
             carrier_code=self.carrier_name, rate_sheet__id=self.id
         )
-    
-    def get_service_zones_legacy(self, service_id: str):
-        """
-        Backward compatible method - returns zones in old format for SDK compatibility
-        Combines shared zones with service-specific rates
-        """
-        zones = self.zones or []
-        service_rates = self.service_rates or []
-        
-        # Get rates for this service
-        service_rate_map = {
-            sr['zone_id']: sr for sr in service_rates 
-            if sr.get('service_id') == service_id
-        }
-        
-        # Combine zone definitions with service rates
-        legacy_zones = []
-        for zone in zones:
-            zone_id = zone.get('id')
-            rate_data = service_rate_map.get(zone_id, {})
-            
-            legacy_zone = {
-                **zone,  # Zone definition (label, cities, country_codes, etc.)
-                'rate': rate_data.get('rate', 0),
-                'min_weight': rate_data.get('min_weight'),
-                'max_weight': rate_data.get('max_weight'),
-                'transit_days': rate_data.get('transit_days'),
-                'transit_time': rate_data.get('transit_time'),
-            }
-            legacy_zones.append(legacy_zone)
-        
-        return legacy_zones
-    
-    def update_service_zone_rate(self, service_id: str, zone_id: str, field: str, value):
-        """
-        Update a rate field for a specific service-zone combination
-        """
-        allowed_fields = {
-            'rate': float,
-            'min_weight': float,
-            'max_weight': float,
-            'transit_days': int,
-            'transit_time': float,
-        }
-        
-        if field not in allowed_fields:
-            raise ValueError(f"Field '{field}' is not allowed for rate updates")
-        
-        # Validate 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}'")
-        
+
+    # ─────────────────────────────────────────────────────────────────
+    # ZONE MANAGEMENT
+    # ─────────────────────────────────────────────────────────────────
+
+    def add_zone(self, zone_data: dict) -> str:
+        """Add a new shared zone definition."""
+        zones = list(self.zones or [])
+
+        # Generate zone ID if not provided
+        if not zone_data.get("id"):
+            zone_data["id"] = f"zone_{len(zones) + 1}"
+
+        zones.append(zone_data)
+        self.zones = zones
+        self.save(update_fields=["zones"])
+        return zone_data["id"]
+
+    def update_zone(self, zone_id: str, zone_data: dict) -> dict:
+        """Update a shared zone definition."""
+        zones = list(self.zones or [])
+
+        for i, zone in enumerate(zones):
+            if zone.get("id") == zone_id:
+                zones[i] = {"id": zone_id, **{k: v for k, v in zone_data.items() if k != "id"}}
+                self.zones = zones
+                self.save(update_fields=["zones"])
+                return zones[i]
+
+        raise ValueError(f"Zone {zone_id} not found")
+
+    def remove_zone(self, zone_id: str):
+        """Remove a zone and all its associated rates."""
+        zones = [z for z in (self.zones or []) if z.get("id") != zone_id]
+        self.zones = zones
+
+        # Remove all rates for this zone
+        service_rates = [sr for sr in (self.service_rates or []) if sr.get("zone_id") != zone_id]
+        self.service_rates = service_rates
+
+        # Remove zone_id from services
+        for service in self.services.all():
+            if zone_id in (service.zone_ids or []):
+                service.zone_ids = [zid for zid in service.zone_ids if zid != zone_id]
+                service.save(update_fields=["zone_ids"])
+
+        self.save(update_fields=["zones", "service_rates"])
+
+    def get_zone(self, zone_id: str) -> dict:
+        """Get a zone by ID."""
+        for zone in self.zones or []:
+            if zone.get("id") == zone_id:
+                return zone
+        return None
+
+    # ─────────────────────────────────────────────────────────────────
+    # SURCHARGE MANAGEMENT
+    # ─────────────────────────────────────────────────────────────────
+
+    def add_surcharge(self, surcharge_data: dict) -> str:
+        """Add a new shared surcharge definition."""
+        surcharges = list(self.surcharges or [])
+
+        if not surcharge_data.get("id"):
+            surcharge_data["id"] = f"surch_{len(surcharges) + 1}"
+
+        surcharge_data.setdefault("active", True)
+        surcharge_data.setdefault("surcharge_type", "fixed")
+
+        surcharges.append(surcharge_data)
+        self.surcharges = surcharges
+        self.save(update_fields=["surcharges"])
+        return surcharge_data["id"]
+
+    def update_surcharge(self, surcharge_id: str, surcharge_data: dict) -> dict:
+        """Update a shared surcharge definition."""
+        surcharges = list(self.surcharges or [])
+
+        for i, surcharge in enumerate(surcharges):
+            if surcharge.get("id") == surcharge_id:
+                surcharges[i] = {"id": surcharge_id, **{k: v for k, v in surcharge_data.items() if k != "id"}}
+                self.surcharges = surcharges
+                self.save(update_fields=["surcharges"])
+                return surcharges[i]
+
+        raise ValueError(f"Surcharge {surcharge_id} not found")
+
+    def remove_surcharge(self, surcharge_id: str):
+        """Remove a surcharge definition and its references from services."""
+        surcharges = [s for s in (self.surcharges or []) if s.get("id") != surcharge_id]
+        self.surcharges = surcharges
+
+        # Remove surcharge_id from services
+        for service in self.services.all():
+            if surcharge_id in (service.surcharge_ids or []):
+                service.surcharge_ids = [sid for sid in service.surcharge_ids if sid != surcharge_id]
+                service.save(update_fields=["surcharge_ids"])
+
+        self.save(update_fields=["surcharges"])
+
+    def batch_update_surcharges(self, updates: list):
+        """Batch update multiple surcharges."""
+        surcharges = list(self.surcharges or [])
+        surcharge_map = {s.get("id"): i for i, s in enumerate(surcharges)}
+
+        for update in updates:
+            surcharge_id = update.get("id")
+            if not surcharge_id:
+                continue
+
+            if surcharge_id in surcharge_map:
+                idx = surcharge_map[surcharge_id]
+                surcharges[idx] = {**surcharges[idx], **update}
+            else:
+                update.setdefault("active", True)
+                update.setdefault("surcharge_type", "fixed")
+                surcharges.append(update)
+                surcharge_map[surcharge_id] = len(surcharges) - 1
+
+        self.surcharges = surcharges
+        self.save(update_fields=["surcharges"])
+
+    def get_surcharge(self, surcharge_id: str) -> dict:
+        """Get a surcharge by ID."""
+        for surcharge in self.surcharges or []:
+            if surcharge.get("id") == surcharge_id:
+                return surcharge
+        return None
+
+    # ─────────────────────────────────────────────────────────────────
+    # SERVICE RATE MANAGEMENT
+    # ─────────────────────────────────────────────────────────────────
+
+    def get_service_rate(self, service_id: str, zone_id: str) -> dict:
+        """Get a service rate by service_id and zone_id."""
+        for rate in self.service_rates or []:
+            if rate.get("service_id") == service_id and rate.get("zone_id") == zone_id:
+                return rate
+        return None
+
+    def update_service_rate(self, service_id: str, zone_id: str, rate_data: dict) -> dict:
+        """Update or create a service-zone rate mapping."""
         service_rates = list(self.service_rates or [])
-        
-        # Find existing rate record
-        for rate_record in service_rates:
-            if (rate_record.get('service_id') == service_id and 
-                rate_record.get('zone_id') == zone_id):
-                rate_record[field] = value
-                break
-        else:
-            # Create new rate record
-            service_rates.append({
-                'service_id': service_id,
-                'zone_id': zone_id,
-                field: value
-            })
-        
+
+        for i, rate in enumerate(service_rates):
+            if rate.get("service_id") == service_id and rate.get("zone_id") == zone_id:
+                service_rates[i] = {"service_id": service_id, "zone_id": zone_id, **rate_data}
+                self.service_rates = service_rates
+                self.save(update_fields=["service_rates"])
+                return service_rates[i]
+
+        # Create new rate record
+        new_rate = {"service_id": service_id, "zone_id": zone_id, **rate_data}
+        service_rates.append(new_rate)
         self.service_rates = service_rates
-        self.save(update_fields=['service_rates'])
-    
-    def batch_update_service_rates(self, updates):
+        self.save(update_fields=["service_rates"])
+        return new_rate
+
+    def batch_update_service_rates(self, updates: list):
         """
-        Batch update service rates
-        updates format: [{'service_id': str, 'zone_id': str, 'field': str, 'value': any}]
+        Batch update service rates.
+        updates format: [{'service_id': str, 'zone_id': str, 'rate': float, 'cost': float, ...}, ...]
         """
-        allowed_fields = {
-            'rate': float,
-            'min_weight': float,
-            'max_weight': float, 
-            'transit_days': int,
-            'transit_time': float,
-        }
-        
         service_rates = list(self.service_rates or [])
-        service_rate_map = {}
-        
-        # Create lookup map for existing rates
+        rate_map = {}
+
         for i, rate in enumerate(service_rates):
             key = f"{rate.get('service_id')}:{rate.get('zone_id')}"
-            service_rate_map[key] = i
-        
+            rate_map[key] = i
+
         for update in updates:
-            service_id = update.get('service_id')
-            zone_id = update.get('zone_id')
-            field = update.get('field')
-            value = update.get('value')
-            
-            if field not in allowed_fields:
-                continue
-            
-            # Validate value
-            try:
-                if value is not None and value != '':
-                    value = allowed_fields[field](value)
-            except (ValueError, TypeError):
+            service_id = update.get("service_id")
+            zone_id = update.get("zone_id")
+            if not service_id or not zone_id:
                 continue
-            
+
             key = f"{service_id}:{zone_id}"
-            
-            if key in service_rate_map:
-                # Update existing rate
-                service_rates[service_rate_map[key]][field] = value
+
+            if key in rate_map:
+                service_rates[rate_map[key]] = {**service_rates[rate_map[key]], **update}
             else:
-                # Create new rate record
-                new_rate = {
-                    'service_id': service_id,
-                    'zone_id': zone_id,
-                    field: value
-                }
-                service_rates.append(new_rate)
-                service_rate_map[key] = len(service_rates) - 1
-        
+                service_rates.append(update)
+                rate_map[key] = len(service_rates) - 1
+
         self.service_rates = service_rates
-        self.save(update_fields=['service_rates'])
-    
-    def add_zone(self, zone_data):
+        self.save(update_fields=["service_rates"])
+
+    def remove_service_rate(self, service_id: str, zone_id: str):
+        """Remove a service-zone rate mapping."""
+        service_rates = [
+            sr
+            for sr in (self.service_rates or [])
+            if not (sr.get("service_id") == service_id and sr.get("zone_id") == zone_id)
+        ]
+        self.service_rates = service_rates
+        self.save(update_fields=["service_rates"])
+
+    # ─────────────────────────────────────────────────────────────────
+    # RATE CALCULATION
+    # ─────────────────────────────────────────────────────────────────
+
+    def apply_surcharges_to_rate(self, base_rate: float, surcharge_ids: list) -> tuple:
         """
-        Add a new shared zone definition
+        Apply surcharges to a base rate.
+
+        Args:
+            base_rate: The base rate before surcharges
+            surcharge_ids: List of surcharge IDs to apply
+
+        Returns:
+            tuple: (final_rate, breakdown)
         """
-        zones = list(self.zones or [])
-        
-        # Generate zone ID if not provided
-        if not zone_data.get('id'):
-            zone_data['id'] = f"zone_{len(zones) + 1}"
-        
-        zones.append(zone_data)
-        self.zones = zones
-        self.save(update_fields=['zones'])
-        return zone_data['id']
-    
-    def remove_zone(self, zone_id: str):
+        total_surcharge = 0.0
+        breakdown = []
+
+        for surcharge_id in surcharge_ids:
+            surcharge = self.get_surcharge(surcharge_id)
+            if not surcharge or not surcharge.get("active", True):
+                continue
+
+            name = surcharge.get("name", "Surcharge")
+            amount = float(surcharge.get("amount", 0))
+            surcharge_type = surcharge.get("surcharge_type", "fixed")
+
+            applied_amount = (base_rate * amount / 100) if surcharge_type == "percentage" else amount
+            total_surcharge += applied_amount
+            breakdown.append(
+                {
+                    "id": surcharge_id,
+                    "name": name,
+                    "amount": applied_amount,
+                    "surcharge_type": surcharge_type,
+                    "original_value": amount,
+                    "cost": surcharge.get("cost"),
+                }
+            )
+
+        return base_rate + total_surcharge, breakdown
+
+    def calculate_rate(self, service_id: str, zone_id: str) -> tuple:
         """
-        Remove a zone and all its associated rates
+        Calculate the total rate for a service-zone combination including surcharges.
+
+        Returns:
+            tuple: (total_rate, breakdown)
         """
-        # Remove zone definition
-        zones = [z for z in (self.zones or []) if z.get('id') != zone_id]
-        self.zones = zones
-        
-        # Remove all rates for this zone
-        service_rates = [sr for sr in (self.service_rates or []) if sr.get('zone_id') != zone_id]
-        self.service_rates = service_rates
-        
-        self.save(update_fields=['zones', 'service_rates'])
-    
-    def migrate_from_legacy_format(self):
+        rate_data = self.get_service_rate(service_id, zone_id)
+        base_rate = float(rate_data.get("rate", 0)) if rate_data else 0
+
+        # Get service surcharge_ids
+        service = self.services.filter(id=service_id).first()
+        surcharge_ids = service.surcharge_ids if service else []
+
+        total_rate, surcharge_breakdown = self.apply_surcharges_to_rate(base_rate, 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,
+        }
+
+    def get_service_zones_for_rating(self, service_id: str) -> list:
         """
-        Migrate from old format where zones are stored per service to new shared format
+        Get zones with rates for a service, formatted for SDK rate calculation.
+
+        Returns:
+            list: Zone dicts with rate data merged from service_rates
         """
-        if self.zones or self.service_rates:
-            # Already in new format
-            return
-        
-        all_zones = {}
-        service_rates = []
-        zone_counter = 1
-        
-        # Extract unique zones across all services
-        for service in self.services.all():
-            service_zones = service.zones or []
-            
-            for zone_index, zone_data in enumerate(service_zones):
-                # Create zone signature for deduplication
-                zone_signature = {
-                    'label': zone_data.get('label', f'Zone {zone_index + 1}'),
-                    'cities': sorted(zone_data.get('cities', [])),
-                    'postal_codes': sorted(zone_data.get('postal_codes', [])),
-                    'country_codes': sorted(zone_data.get('country_codes', [])),
-                }
-                
-                # Use signature as key for deduplication
-                sig_key = str(zone_signature)
-                
-                if sig_key not in all_zones:
-                    zone_id = f"zone_{zone_counter}"
-                    all_zones[sig_key] = {
-                        'id': zone_id,
-                        **zone_signature
-                    }
-                    zone_counter += 1
-                
-                zone_id = all_zones[sig_key]['id']
-                
-                # Store service rate
-                service_rates.append({
-                    'service_id': service.id,
-                    'zone_id': zone_id,
-                    'rate': zone_data.get('rate', 0),
-                    'min_weight': zone_data.get('min_weight'),
-                    'max_weight': zone_data.get('max_weight'),
-                    'transit_days': zone_data.get('transit_days'),
-                    'transit_time': zone_data.get('transit_time'),
+        zones = self.zones or []
+        service_rates = self.service_rates or []
+
+        # Build rate lookup
+        rate_map = {
+            sr.get("zone_id"): sr
+            for sr in service_rates
+            if sr.get("service_id") == service_id
+        }
+
+        # Merge zone definitions with rates
+        result = []
+        for zone in zones:
+            zone_id = zone.get("id")
+            rate_data = rate_map.get(zone_id, {})
+
+            result.append({
+                "id": zone_id,
+                "label": zone.get("label"),
+                "rate": rate_data.get("rate", 0),
+                "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.get("transit_days"),
+                "transit_time": rate_data.get("transit_time") or zone.get("transit_time"),
+                "radius": zone.get("radius"),
+                "latitude": zone.get("latitude"),
+                "longitude": zone.get("longitude"),
+                "cities": zone.get("cities", []),
+                "postal_codes": zone.get("postal_codes", []),
+                "country_codes": zone.get("country_codes", []),
+            })
+
+        return result
+
+    def get_surcharges_for_rating(self, surcharge_ids: list) -> list:
+        """
+        Get surcharges formatted for SDK rate calculation.
+
+        Args:
+            surcharge_ids: List of surcharge IDs to include
+
+        Returns:
+            list: Surcharge dicts for active surcharges
+        """
+        result = []
+        for surcharge_id in surcharge_ids or []:
+            surcharge = self.get_surcharge(surcharge_id)
+            if surcharge and surcharge.get("active", True):
+                result.append({
+                    "id": surcharge.get("id"),
+                    "name": surcharge.get("name"),
+                    "amount": surcharge.get("amount", 0),
+                    "surcharge_type": surcharge.get("surcharge_type", "fixed"),
+                    "cost": surcharge.get("cost"),
+                    "active": surcharge.get("active", True),
                 })
-        
-        # Save optimized structure
-        self.zones = list(all_zones.values())
-        self.service_rates = service_rates
-        self.save(update_fields=['zones', 'service_rates'])
+        return result