feat: Jadlog quotes by the larger of the real and the cubed weight

The client's box is 56 x 14 x 14 cm and weighs 0.30 kg; the film is 0.075 kg
per metre. Jadlog charges the larger of the real and the cubed weight, and this
box is large for its weight, so quoting the real weight alone would price
below what Jadlog charges. JADLOG_CAIXA_CM and JADLOG_CUBAGEM_KG_M3 (both or
neither) give the cubed weight; the quote sends the larger. Until the
contract's factor is set, the Kanban's Frete card says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app/api/operator.py

@@ -64,8 +64,12 @@ def freight_status():
     """What delivery the Site offers, and the package rule it prices with."""
     if freight.name != 'jadlog':
         return {'provider': freight.name}
+    cubed = freight.cubed_kg()
     return {'provider': 'jadlog', 'base_kg': str(freight.base_kg), 'per_metre_kg': str(freight.per_metre_kg),
-            'production_days': freight.production_days}
+            'production_days': freight.production_days,
+            'box_cm': [str(side) for side in freight.box_cm] if freight.box_cm else None,
+            'cubage_kg_m3': str(freight.cubage_kg_m3) if freight.cubage_kg_m3 else None,
+            'cubed_kg': str(cubed) if cubed is not None else None}
 
 
 def backup_status(c):

app/jadlog.py

@@ -10,9 +10,12 @@ home delivery. Jadlog prices by weight in kg and expects the larger of the
 real and the cubed weight. The package weight comes from the client (a base
 plus a weight per billed metre) and has no default: FREIGHT_ADAPTER=jadlog
 refuses to start without it, so a guessed weight never prices a customer's
-freight.
+freight. The cubed weight is the box's volume times the contract's factor
+(JADLOG_CAIXA_CM, JADLOG_CUBAGEM_KG_M3); set both or neither, and with neither
+only the real weight is sent.
 """
 import os
+import re
 from decimal import ROUND_HALF_UP, Decimal
 
 import httpx
@@ -22,6 +25,15 @@ PACKAGE = 3
 ORIGIN = '14402310'
 SERVICE = 'jadlog'
 WEIGHT_SETTINGS = ('JADLOG_PESO_BASE_KG', 'JADLOG_PESO_POR_METRO_KG')
+GRAMS = Decimal('0.001')
+
+
+def box_cm(text):
+    """The box's three sides in cm from "56x14x14" ("56 × 14 × 14", "56,5x14x14")."""
+    sides = [Decimal(side.strip().replace(',', '.')) for side in re.split(r'[x×*]', text.lower())]
+    if len(sides) != 3 or any(side <= 0 for side in sides):
+        raise RuntimeError('JADLOG_CAIXA_CM takes three sides in cm, such as 56x14x14')
+    return sides
 
 
 class JadlogError(Exception):
@@ -96,9 +108,30 @@ class JadlogFreight:
         self.production_days = int(os.environ.get('FREIGHT_PRODUCTION_DAYS') or 0)
         if self.base_kg < 0 or self.per_metre_kg <= 0 or self.production_days < 0:
             raise RuntimeError('Jadlog package weight and production days must be positive')
+        # A box without its factor (or a factor without a box) would price by a guess.
+        box = (os.environ.get('JADLOG_CAIXA_CM') or '').strip()
+        factor = (os.environ.get('JADLOG_CUBAGEM_KG_M3') or '').strip()
+        if bool(box) != bool(factor):
+            raise RuntimeError('Set JADLOG_CAIXA_CM and JADLOG_CUBAGEM_KG_M3 together, or neither')
+        self.box_cm = box_cm(box) if box else None
+        self.cubage_kg_m3 = Decimal(factor.replace(',', '.')) if factor else None
+        if self.cubage_kg_m3 is not None and self.cubage_kg_m3 <= 0:
+            raise RuntimeError('JADLOG_CUBAGEM_KG_M3 must be positive')
+
+    def real_kg(self, metres):
+        return (self.base_kg + self.per_metre_kg * Decimal(str(metres))).quantize(GRAMS)
+
+    def cubed_kg(self):
+        """The box's volume in m³ times the contract's factor; None without a box."""
+        if not self.box_cm:
+            return None
+        a, b, c = self.box_cm
+        return (a * b * c / Decimal(1_000_000) * self.cubage_kg_m3).quantize(GRAMS)
 
     def weight_kg(self, metres):
-        return (self.base_kg + self.per_metre_kg * Decimal(str(metres))).quantize(Decimal('0.001'))
+        """What Jadlog charges by: the larger of the real and the cubed weight."""
+        real, cubed = self.real_kg(metres), self.cubed_kg()
+        return max(real, cubed) if cubed is not None else real
 
     def quote(self, service, postal_code, metres=None, declared_cents=0):
         if service == 'pickup':
@@ -107,13 +140,13 @@ class JadlogFreight:
             raise ValueError('Select pickup or Jadlog delivery with an eight-digit CEP')
         if metres is None or Decimal(str(metres)) <= 0:
             raise ValueError('The order length is required to quote freight')
-        weight = self.weight_kg(metres)
+        weight, real = self.weight_kg(metres), self.real_kg(metres)
         try:
             result = self.quotes.quote(postal_code, weight, int(declared_cents))
         except (JadlogError, httpx.HTTPError) as error:
             raise ValueError(f'Não foi possível cotar o frete na Jadlog agora: {error}') from None
         days = result['days']
         return {'provider': self.name, 'service': SERVICE, 'postal_code': postal_code,
-                'total_cents': result['total_cents'], 'weight_kg': str(weight),
+                'total_cents': result['total_cents'], 'weight_kg': str(weight), 'real_kg': str(real),
                 'days': None if days is None else int(days) + self.production_days,
                 'description': 'Jadlog .PACKAGE'}